Effect-native otel integration (#425)

Author: harrysolovay

.github/workflows/changesets.yml

@@ -14,7 +14,7 @@ jobs:
     timeout-minutes: 10
     steps:
       - uses: actions/checkout@v6
-      - run: "git -c url.https://github.com/.insteadOf=git@github.com: submodule update --init --depth 1 konfik"
+      - run: "git -c url.https://github.com/.insteadOf=git@github.com: submodule update --init konfik"
       - uses: ./konfik/.github/actions/configure_environment
       - run: pnpm run build
       - uses: changesets/action@v1

.github/workflows/checks.yml

@@ -17,7 +17,7 @@ jobs:
       contents: read
     steps:
       - uses: actions/checkout@v6
-      - run: "git -c url.https://github.com/.insteadOf=git@github.com: submodule update --init --depth 1 konfik"
+      - run: "git -c url.https://github.com/.insteadOf=git@github.com: submodule update --init konfik"
       - uses: ./konfik/.github/actions/configure_environment
       - run: pnpm build
       # - run: pnpm test

.github/workflows/deploy-docs.yml

@@ -17,7 +17,7 @@ jobs:
     environment: docs
     steps:
       - uses: actions/checkout@v6
-      - run: "git -c url.https://github.com/.insteadOf=git@github.com: submodule update --init --depth 1 konfik"
+      - run: "git -c url.https://github.com/.insteadOf=git@github.com: submodule update --init konfik"
       - uses: ./konfik/.github/actions/configure_environment
       - run: pnpm build
       - run: pnpm build

docs/pages/actor-routing/upgrades.mdx

@@ -0,0 +1,53 @@
+# HTTP Upgrades
+
+`Namespace.upgrade(name, attachments)` is the handoff from HTTP to the Durable Object.
+
+An HTTP route decides:
+
+- which actor name to connect to
+- which actor type to use
+- what the initial attachments should be
+
+`upgrade(...)` handles the rest.
+
+## Upgrade from a route
+
+```ts
+import { Effect, Layer } from "effect"
+import { HttpRouter } from "effect/unstable/http"
+
+import { ChatNamespace } from "./chat/ChatNamespace.ts"
+import { LobbyNamespace } from "./lobby/LobbyNamespace.ts"
+
+export const ApiLive = Layer.mergeAll(
+  HttpRouter.add(
+    "GET",
+    "/connect",
+    Effect.gen(function* () {
+      const sessionToken = yield* readSessionToken
+      const user = yield* lookupUser(sessionToken)
+
+      if (user) {
+        const roomId = yield* getActiveRoom(user.id)
+        return yield* ChatNamespace.upgrade(roomId, { userId: user.id })
+      }
+
+      return yield* LobbyNamespace.upgrade(sessionToken, {})
+    }),
+  ),
+)
+```
+
+Every request that upgrades with the same actor name lands in the same Durable Object instance.
+
+## What upgrade does
+
+On the Cloudflare side, `upgrade(...)`:
+
+- resolves the Durable Object by actor name
+- validates that the connecting WebSocket is using the expected Liminal client id
+- serializes attachments onto the WebSocket
+- returns the `101 Switching Protocols` response
+
+The validation step is why client and actor definitions must line up. If the wrong client tries to connect, the session
+fails with an audition error rather than silently misbehaving.

docs/pages/actor-routing/worker-entrypoint.mdx

@@ -0,0 +1,55 @@
+# Worker Entrypoint
+
+The Worker entrypoint usually exports:
+
+- a default `fetch` handler
+- each Durable Object class as a named export
+
+`Worker.make(...)` supplies the Worker-side runtime for ordinary HTTP handling. `WorkerdActorNamespace` separately
+manages the Durable Object runtime for actor messages.
+
+## Build the entrypoint
+
+```ts
+// main.ts
+import { Effect, Layer } from "effect"
+import { Assets, Worker } from "effect-workerd"
+import { HttpRouter, HttpServerResponse } from "effect/unstable/http"
+
+import * as GameState from "./Games.ts"
+import { KvLive } from "./KvLive.ts"
+import { TicTacToeNamespace } from "./TicTacToeNamespace.ts"
+
+export { TicTacToeNamespace }
+
+const ApiLive = Layer.mergeAll(
+  HttpRouter.add("GET", "/", Effect.succeed(HttpServerResponse.text("ok"))),
+  HttpRouter.add(
+    "GET",
+    "/play",
+    Effect.gen(function* () {
+      const { gameId, player } = yield* GameState.init
+      return yield* TicTacToeNamespace.upgrade(gameId, { player })
+    }),
+  ),
+  HttpRouter.cors({
+    allowedHeaders: ["*"],
+    allowedMethods: ["*"],
+    allowedOrigins: ["*"],
+  }),
+  HttpRouter.add("*", "/*", Assets.forward),
+)
+
+export default Worker.make({
+  handler: ApiLive.pipe(HttpRouter.toHttpEffect, Effect.flatten),
+  prelude: Layer.mergeAll(KvLive, TicTacToeNamespace.layer("TICTACTOE"), Assets.layer("ASSETS")),
+})
+```
+
+## Things to notice
+
+- `HttpRouter.add(method, path, effect)` mounts a single route.
+- `HttpRouter.cors(...)` wires up CORS for every route in the router.
+- `HttpRouter.add("*", "/*", Assets.forward)` falls through to the Cloudflare Assets binding for unmatched requests.
+- `Worker.make({ handler, prelude })` produces the Worker `fetch` export.
+- The Durable Object class must be re-exported from the Worker entrypoint.