wip

Author: MatthewWid

docs/astro.config.ts

@@ -21,6 +21,7 @@ export default defineConfig({
 						"guides/getting-started",
 						"guides/channels",
 						"guides/batching",
+						"guides/connections",
 					],
 				},
 				{

docs/src/content/docs/guides/connections.mdx

@@ -0,0 +1,121 @@
+---
+layout: ../../../layouts/Base.astro
+title: Custom connection adapters
+description: Learn how to use custom connection adapters to make Better SSE compatible with anything.
+---
+
+*Connection adapters* allow you to make Better SSE [sessions](/better-sse/reference/api/#sessionstate) compatible with any protocol, framework or runtime environment.
+
+Where *sessions* manage the request and response lifecycle, the formatting of data and other SSE-specific behaviour, [*connection adapters*](/better-sse/reference/api/#connection) implement the underlying connection itself, such as extracting request headers and query parameters, sending response headers and data chunks and reporting when the connection closes.
+
+## Built-in connection adapters
+
+Better SSE ships with a number of built-in connection adapters that are used internally but can also be extended to add or augment functionality.
+
+When a session is created, it will automatically determine which connection adapter to use based on the arguments provided.
+
+### Fetch API
+
+When providing an instance of [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request) (and optionally [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response)) from the [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API). The following example with [Hono](https://hono.dev/):
+
+```typescript
+import { createResponse } from "better-sse"
+
+app.get("/sse", async (c) => 
+    createResponse(c.req.raw, (session) => {
+        session.push("Hello world!")
+    })
+)
+```
+
+Causes the session to use the built-in [`FetchConnection`](/better-sse/reference/api/#fetchconnection) adapter, equivalent to the following:
+
+```typescript
+import { createResponse, FetchConnection } from "better-sse"
+
+app.get("/sse", async (c) => {
+    const connection = new FetchConnection(c.req.raw, null)
+
+    return createResponse(connection, (session) => {
+        session.push("Hello world!")
+    })
+})
+```
+
+### Node HTTP/1 API
+
+When providing instances of [`IncomingMessage`](https://nodejs.org/api/http.html#class-httpincomingmessage) and [`ServerResponse`](https://nodejs.org/api/http.html#class-httpserverresponse) from the [Node HTTP/1 API](https://nodejs.org/api/http.html). The following example with [Express](https://expressjs.com/):
+
+```typescript
+import { createSession } from "better-sse"
+
+app.get("/sse", async (req, res) => {
+    const session = await createSession(req, res)
+    session.push("Hello world!")
+})
+```
+
+Causes the session to use the built-in [`NodeHttp1Connection`](/better-sse/reference/api/#nodehttp1connection) adapter, equivalent to the following:
+
+```typescript
+import { createSession, NodeHttp1Connection } from "better-sse"
+
+app.get("/sse", async (req, res) => {
+    const connection = new NodeHttp1Connection(req, res)
+    const session = await createSession(connection)
+    session.push("Hello world!")
+})
+```
+
+### Node HTTP/2 Compatibility API
+
+When providing instances of [`Http2ServerRequest`](https://nodejs.org/api/http2.html#class-http2http2serverrequest) and [`Http2ServerResponse`](https://nodejs.org/api/http2.html#class-http2http2serverresponse) from the [Node HTTP/2 Compatibility API](https://nodejs.org/api/http2.html#compatibility-api). The following example with [`createServer`](https://nodejs.org/api/http2.html#http2createserveroptions-onrequesthandler):
+
+```typescript
+import { createSession } from "better-sse"
+
+createServer(async (req, res) => {
+    const { ":path": path, ":method": method } = req.headers
+
+    if (req.url === "/sse") {
+        const session = await createSession(req, res)
+        session.push("Hello world!")
+    }
+})
+```
+
+Causes the session to use the built-in [`NodeHttp2CompatConnection`](/better-sse/reference/api/#nodehttp2compatconnection) adapter, equivalent to the following:
+
+```typescript
+import { createSession, NodeHttp2CompatConnection } from "better-sse"
+
+createServer(async (req, res) => {
+    const { ":path": path, ":method": method } = req.headers
+
+    if (req.url === "/sse") {
+        const connection = new NodeHttp2CompatConnection(req, res)
+        const session = await createSession(connection)
+        session.push("Hello world!")
+    }
+})
+```
+
+## Create a custom connection adapter
+
+You can create a custom connection adapter from scratch - extending from the [`Connection` class](/better-sse/reference/api/#connection) directly - or use any of the in-built adapters as a base:
+
+* [`FetchConnection`](/better-sse/reference/api/#fetchconnection) ([source code](https://github.com/MatthewWid/better-sse/blob/master/src/adapters/FetchConnection.ts))
+* [`NodeHttp1Connection`](/better-sse/reference/api/#nodehttp1connection) ([source code](https://github.com/MatthewWid/better-sse/blob/master/src/adapters/NodeHttp1Connection.ts))
+* [`NodeHttp2CompatConnection`](/better-sse/reference/api/#nodehttp2compatconnection) ([source code](https://github.com/MatthewWid/better-sse/blob/master/src/adapters/NodeHttp2CompatConnection.ts))
+
+### Koa
+
+Let's create a custom connection adapter that abstracts away the implementation details of SSE streaming with [Koa](https://koajs.com/).
+
+To begin, create a class that extends from the base [`Connection` class](/better-sse/reference/api/#connection):
+
+```typescript title="KoaConnection.ts"
+import { Connection } from "better-sse"
+
+class KoaConnection extends Connection {}
+```