@livestore/common-cf 0.4.0-dev.21 → 0.4.0-dev.23

package/src/do-rpc/server.ts

@@ -15,6 +15,7 @@ import {
   type Scope,
   Stream,
 } from '@livestore/utils/effect'
+
 import type * as CfTypes from '../cf-types.ts'
 
 export interface ClientDoWithRpcCallback {
@@ -47,10 +48,10 @@ export const toDurableObjectHandler =
 
       // Handle potential nested array from client serialization
       let requests: RpcMessage.FromClient<Rpcs>[]
-      if (Array.isArray(decoded) && decoded.length === 1 && Array.isArray(decoded[0])) {
+      if (Array.isArray(decoded) === true && decoded.length === 1 && Array.isArray(decoded[0]) === true) {
         // Double-wrapped array [[{...}]] -> [{...}]
         requests = decoded[0]
-      } else if (Array.isArray(decoded)) {
+      } else if (Array.isArray(decoded) === true) {
         // Single array [{...}]
         requests = decoded
       } else {
@@ -69,10 +70,12 @@ export const toDurableObjectHandler =
         }
 
         // Find the RPC handler
+        // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- RpcGroup.requests map returns Rpc.Any; narrowing to AnyWithProps for property access
         const rpc = group.requests.get(request.tag)! as unknown as Rpc.AnyWithProps
+        // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- context.unsafeMap dynamic lookup; type safety ensured by RpcGroup registration
         const entry = context.unsafeMap.get(rpc.key) as Rpc.Handler<Rpcs['_tag']>
 
-        if (!rpc || !entry) {
+        if (rpc == null || entry == null) {
           responses.push({
             _tag: 'Exit',
             requestId: request.id,
@@ -82,10 +85,11 @@ export const toDurableObjectHandler =
         }
 
         // Check if this is a streaming RPC
+        // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- Rpc.Handler doesn't expose successSchema publicly; see https://github.com/Effect-TS/effect/issues/6064
         const isStream = RpcSchema.isStreamSchema((rpc as any).successSchema)
 
         // For streaming RPCs with only one request, return ReadableStream directly
-        if (isStream && requests.length === 1) {
+        if (isStream === true && requests.length === 1) {
           return yield* createStreamingResponse(rpc, entry, request, parser, options.layer)
         }
 
@@ -99,17 +103,19 @@ export const toDurableObjectHandler =
           })
 
           let value: any
-          if (Effect.isEffect(handlerResult)) {
+          if (Effect.isEffect(handlerResult) === true) {
+            // @effect-diagnostics-next-line anyUnknownInErrorContext:off -- `Rpc.Handler.handler` returns `Effect<any, any>` due to dynamic dispatch
             value = yield* handlerResult
           } else {
             value = handlerResult
           }
 
           // Get the exit schema for this RPC
+          // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- Rpc.exitSchema requires AnyWithProps; type narrowing already done above
           const exitSchema = Rpc.exitSchema(rpc as any) as Schema.Schema<any>
 
           let encodedExit: any
-          if (exitSchema) {
+          if (exitSchema !== undefined) {
             // Use schema encoding for proper serialization
             const rawExit = Exit.succeed(value)
             encodedExit = yield* Schema.encodeUnknown(exitSchema)(rawExit)
@@ -126,11 +132,12 @@ export const toDurableObjectHandler =
         }).pipe(
           Effect.catchAllCause((cause) => {
             // Get the exit schema for this RPC
+            // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- Rpc.exitSchema requires AnyWithProps; type narrowing already done above
             const exitSchema = Rpc.exitSchema(rpc as any) as Schema.Schema<any>
 
             return Effect.gen(function* () {
               let encodedExit: any
-              if (exitSchema) {
+              if (exitSchema !== undefined) {
                 // Use schema encoding for proper serialization
                 const rawExit = Exit.failCause(cause)
                 encodedExit = yield* Schema.encodeUnknown(exitSchema)(rawExit)
@@ -151,12 +158,13 @@ export const toDurableObjectHandler =
         responses.push(result)
       }
 
+      // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- msgPack parser.encode returns unknown; cast to expected wire format
       const encoded = parser.encode(responses) as Uint8Array<ArrayBuffer>
       return encoded
     }).pipe(Effect.provide(options.layer), Effect.scoped, Effect.orDie)
 
 /** Out-of-band RPC stream response emission back to the caller DO */
-export const emitStreamResponse = ({
+export const emitStreamResponse = Effect.fn('do-rpc/emitStreamResponse')(function* ({
   callerContext,
   env,
   requestId,
@@ -166,22 +174,22 @@ export const emitStreamResponse = ({
   callerContext: { bindingName: string; durableObjectId: string }
   requestId: string
   values: NonEmptyArray<any>
-}) =>
-  Effect.gen(function* () {
-    const clientDoNamespace = env[callerContext.bindingName] as
-      | CfTypes.DurableObjectNamespace<ClientDoWithRpcCallback>
-      | undefined
+}) {
+  // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- CF worker env bindings are typed as Record<string, any>; narrowing to known DO namespace
+  const clientDoNamespace = env[callerContext.bindingName] as
+    | CfTypes.DurableObjectNamespace<ClientDoWithRpcCallback>
+    | undefined
 
-    if (clientDoNamespace === undefined) {
-      throw new Error(`Client DO namespace not found: ${callerContext.bindingName}`)
-    }
+  if (clientDoNamespace === undefined) {
+    throw new Error(`Client DO namespace not found: ${callerContext.bindingName}`)
+  }
 
-    const clientDo = clientDoNamespace.get(clientDoNamespace.idFromString(callerContext.durableObjectId))
+  const clientDo = clientDoNamespace.get(clientDoNamespace.idFromString(callerContext.durableObjectId))
 
-    const res: RpcMessage.ResponseChunkEncoded = { _tag: 'Chunk', requestId, values }
+  const res: RpcMessage.ResponseChunkEncoded = { _tag: 'Chunk', requestId, values }
 
-    yield* Effect.tryPromise(() => clientDo.syncUpdateRpc(res))
-  }).pipe(Effect.withSpan('do-rpc/emitStreamResponse'))
+  yield* Effect.tryPromise(() => clientDo.syncUpdateRpc(res))
+})
 
 /**
  * Creates a ReadableStream response for streaming RPCs.
@@ -193,7 +201,7 @@ const createStreamingResponse = <Rpcs extends Rpc.Any, LE>(
   request: any,
   parser: ReturnType<typeof RpcSerialization.msgPack.unsafeMake>,
   layer: Layer.Layer<Rpc.ToHandler<Rpcs> | Rpc.Middleware<Rpcs>, LE>,
-): Effect.Effect<CfTypes.ReadableStream, any, Scope.Scope> =>
+): Effect.Effect<CfTypes.ReadableStream, never, Scope.Scope> =>
   Effect.gen(function* () {
     // Execute the handler to get the stream
     const handlerResult = entry.handler(request.payload, {
@@ -203,20 +211,19 @@ const createStreamingResponse = <Rpcs extends Rpc.Any, LE>(
       }),
     })
 
-    let stream: Stream.Stream<any, any, never>
-    if (Effect.isEffect(handlerResult)) {
-      // If handler returns Effect<Stream>, we need to run it to get the stream
-      stream = yield* handlerResult
-    } else {
-      // Direct stream
-      stream = handlerResult
-    }
+    // @effect-diagnostics-next-line anyUnknownInErrorContext:off -- `Rpc.Handler.handler` returns `Effect<any, any>` due to dynamic dispatch; orDie converts the error to a defect handled by the downstream catchAllCause
+    const stream: Stream.Stream<any, any> =
+      Effect.isEffect(handlerResult) === true ? yield* Effect.orDie(handlerResult) : handlerResult
 
     // Get the stream schemas for proper chunk-level encoding
+    // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- Rpc.Handler doesn't expose successSchema publicly; see https://github.com/Effect-TS/effect/issues/6064
     const streamSchemas = RpcSchema.getStreamSchemas((rpc as any).successSchema.ast)
-    const chunkEncoder = Option.isSome(streamSchemas)
-      ? Schema.encodeUnknown(Schema.Array(streamSchemas.value.success as Schema.Schema<any>))
-      : Schema.encodeUnknown(Schema.Array(Schema.Any as Schema.Schema<any>))
+    const chunkEncoder =
+      Option.isSome(streamSchemas) === true
+        ? // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- stream schema success type is inferred as unknown; cast needed for encodeUnknown
+          Schema.encodeUnknown(Schema.Array(streamSchemas.value.success as Schema.Schema<any>))
+        : // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- Schema.Any needs explicit cast for Schema.Array compatibility
+          Schema.encodeUnknown(Schema.Array(Schema.Any as Schema.Schema<any>))
 
     // Convert stream to ReadableStream
     const readableStream = new ReadableStream({
@@ -238,6 +245,7 @@ const createStreamingResponse = <Rpcs extends Rpc.Any, LE>(
                 values: encodedValues,
               }
 
+              // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- msgPack parser.encode returns unknown; cast to expected wire format
               const serialized = parser.encode([chunkMessage]) as Uint8Array<ArrayBuffer>
               controller.enqueue(serialized)
             }),
@@ -245,6 +253,7 @@ const createStreamingResponse = <Rpcs extends Rpc.Any, LE>(
 
           // Send final exit message with proper schema encoding
           const rawExit = Exit.void
+          // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- Rpc.exitSchema requires AnyWithProps; type narrowing already done above
           const exitSchema = Rpc.exitSchema(rpc as any) as Schema.Schema<any>
           const encodedExit = yield* Schema.encodeUnknown(exitSchema)(rawExit)
 
@@ -254,6 +263,7 @@ const createStreamingResponse = <Rpcs extends Rpc.Any, LE>(
             exit: encodedExit,
           }
 
+          // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- msgPack parser.encode returns unknown; cast to expected wire format
           const exitSerialized = parser.encode([exitMessage]) as Uint8Array<ArrayBuffer>
           controller.enqueue(exitSerialized)
           controller.close()
@@ -262,6 +272,7 @@ const createStreamingResponse = <Rpcs extends Rpc.Any, LE>(
             Effect.gen(function* () {
               // Send error exit with proper schema encoding
               const rawExit = Exit.failCause(cause)
+              // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- Rpc.exitSchema requires AnyWithProps; type narrowing already done above
               const exitSchema = Rpc.exitSchema(rpc as any) as Schema.Schema<any>
               const encodedExit = yield* Schema.encodeUnknown(exitSchema)(rawExit)
 
@@ -271,6 +282,7 @@ const createStreamingResponse = <Rpcs extends Rpc.Any, LE>(
                 exit: encodedExit,
               }
 
+              // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- msgPack parser.encode returns unknown; cast to expected wire format
               const exitSerialized = parser.encode([exitMessage]) as Uint8Array<ArrayBuffer>
               controller.enqueue(exitSerialized)
               controller.close()
@@ -281,6 +293,7 @@ const createStreamingResponse = <Rpcs extends Rpc.Any, LE>(
         // Run the stream processing
         runStream.pipe(Effect.provide(layer), Effect.scoped, Effect.tapCauseLogPretty, Effect.runPromise)
       },
+      // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- bridging standard Web API ReadableStream to Cloudflare Worker ReadableStream type
     }) as any as CfTypes.ReadableStream
 
     // yield* Effect.addFinalizer(() => Effect.promise(() => readableStream.cancel()))

package/src/do-rpc/test-fixtures/worker.ts

@@ -1,6 +1,7 @@
 /// <reference types="@cloudflare/workers-types" />
 
 import { DurableObject } from 'cloudflare:workers'
+
 import { layerProtocolDurableObject, toDurableObjectHandler } from '@livestore/common-cf'
 import {
   Effect,
@@ -13,6 +14,7 @@ import {
   Schedule,
   Stream,
 } from '@livestore/utils/effect'
+
 import { TestRpcs } from './rpc-schema.ts'
 
 export interface Env {
@@ -20,7 +22,7 @@ export interface Env {
 }
 
 export class TestRpcDurableObject extends DurableObject {
-  __DURABLE_OBJECT_BRAND = 'TestRpcDurableObject' as never
+  override __DURABLE_OBJECT_BRAND = 'TestRpcDurableObject' as never
 
   async rpc(payload: unknown): Promise<unknown> {
     const TestRpcsLive = TestRpcs.toLayer({
@@ -139,7 +141,7 @@ export default {
         headers: { 'Content-Type': 'text/plain' },
       })
     } catch (error) {
-      return new Response(`Error: ${error}`, { status: 500 })
+      return new Response(`Error: ${String(error)}`, { status: 500 })
     }
   },
 }

package/src/ws-rpc/README.md

@@ -19,4 +19,4 @@ This module provides a Effect RPC implementation for WebSocket connections hoste
 
 ```ts
 // See test-fixtures/worker.ts for an example
-```
+```

package/src/ws-rpc/test-fixtures/worker.ts

@@ -1,7 +1,9 @@
 /// <reference types="@cloudflare/workers-types" />
 
 import { DurableObject } from 'cloudflare:workers'
+
 import { Effect, Layer, Option, RpcServer, Schedule, Stream } from '@livestore/utils/effect'
+
 import type * as CfTypes from '../../cf-types.ts'
 import { setupDurableObjectWebSocketRpc } from '../ws-rpc-server.ts'
 import { TestRpcs } from './rpc-schema.ts'
@@ -11,7 +13,7 @@ export interface Env {
 }
 
 export class TestRpcDurableObject extends DurableObject<Env, unknown> {
-  __DURABLE_OBJECT_BRAND = 'TestRpcDurableObject' as never
+  override __DURABLE_OBJECT_BRAND = 'TestRpcDurableObject' as never
 
   constructor(state: DurableObjectState, env: Env) {
     super(state, env)
@@ -59,7 +61,7 @@ export class TestRpcDurableObject extends DurableObject<Env, unknown> {
     })
   }
 
-  async fetch(request: Request): Promise<Response> {
+  override async fetch(request: Request): Promise<Response> {
     const upgradeHeader = request.headers.get('Upgrade')
     if (upgradeHeader === undefined || upgradeHeader !== 'websocket') {
       return new Response('Durable Object expected Upgrade: websocket', { status: 426 })
@@ -81,7 +83,7 @@ export default {
   async fetch(request: Request, env: Env): Promise<Response> {
     try {
       const upgradeHeader = request.headers.get('Upgrade')
-      if (!upgradeHeader || upgradeHeader !== 'websocket') {
+      if (upgradeHeader == null || upgradeHeader !== 'websocket') {
         return new Response('Durable Object expected Upgrade: websocket', { status: 426 })
       }
 
@@ -89,7 +91,7 @@ export default {
 
       return serverDO.fetch(request)
     } catch (error) {
-      return new Response(`Error: ${error}`, { status: 500 })
+      return new Response(`Error: ${String(error)}`, { status: 500 })
     }
   },
 }

package/src/ws-rpc/ws-rpc-server.ts

@@ -17,6 +17,7 @@
 
 import { notYetImplemented, omitUndefineds } from '@livestore/utils'
 import {
+  Context,
   constVoid,
   Effect,
   Exit,
@@ -30,8 +31,16 @@ import {
   Scope,
   Stream,
 } from '@livestore/utils/effect'
+
 import type * as CfTypes from '../cf-types.ts'
 
+/**
+ * Context service providing access to the current WebSocket.
+ * This is useful for reading WebSocket attachment data (e.g., forwarded headers)
+ * inside RPC handlers.
+ */
+export class WsContext extends Context.Tag('WsContext')<WsContext, { readonly ws: CfTypes.WebSocket }>() {}
+
 /**
  * Configuration options for setting up WebSocket RPC on a Durable Object.
  */
@@ -44,11 +53,25 @@ export interface DurableObjectWebSocketRpcConfig {
    * - 'accept': Use traditional WebSocket handling (not yet implemented)
    */
   webSocketMode: 'hibernate' | 'accept'
-  /** Effect RPC layer that defines the available RPC methods and handlers */
-  rpcLayer: Layer.Layer<never, never, RpcServer.Protocol>
+  /**
+   * Effect RPC layer that requires `RpcServer.Protocol` (and `WsContext` if used)
+   * and provides the RPC server runtime.
+   *
+   * This is typically created by:
+   * ```typescript
+   * RpcServer.layer(MyRpcs).pipe(Layer.provide(handlersLayer))
+   * ```
+   *
+   * `WsContext` is provided by the WebSocket protocol layer, so handlers can access
+   * WebSocket attachment data (e.g., forwarded headers stored after WebSocket upgrade).
+   *
+   * The layer requirements (`RIn`) must be a subset of `RpcServer.Protocol | WsContext`,
+   * which are both provided by the WebSocket protocol layer.
+   */
+  rpcLayer: Layer.Layer<never, never, RpcServer.Protocol | WsContext>
   /** Function to get access to incoming requests */
   onMessage?: (msg: RpcMessage.FromClientEncoded, ws: CfTypes.WebSocket) => void
-  mainLayer?: Layer.Layer<never, never, never>
+  mainLayer?: Layer.Layer<never>
 }
 
 /**
@@ -132,7 +155,7 @@ export const setupDurableObjectWebSocketRpc = ({
 
   const launchServer = (ws: CfTypes.WebSocket) =>
     Effect.gen(function* () {
-      if (serverCtxMap.has(ws)) {
+      if (serverCtxMap.has(ws) === true) {
         return serverCtxMap.get(ws)!
       }
 
@@ -140,7 +163,7 @@ export const setupDurableObjectWebSocketRpc = ({
 
       const scope = yield* Scope.make()
 
-      const incomingQueue = yield* Mailbox.make<Uint8Array<ArrayBufferLike> | string>()
+      const incomingQueue = yield* Mailbox.make<Uint8Array | string>()
 
       yield* Scope.addFinalizer(scope, incomingQueue.shutdown)
 
@@ -160,7 +183,7 @@ export const setupDurableObjectWebSocketRpc = ({
         scope,
         onMessage: (message: string | ArrayBuffer) =>
           incomingQueue
-            .offer(message as Uint8Array<ArrayBufferLike> | string)
+            .offer(message as Uint8Array | string)
             .pipe(
               Effect.asVoid,
               Effect.withSpan('ws-rpc-server/onMessage', { root: true }),
@@ -190,7 +213,7 @@ export const setupDurableObjectWebSocketRpc = ({
   const webSocketClose: CfTypes.DurableObject['webSocketClose'] = async (ws, _code, _reason, _wasClean) => {
     const ctx = serverCtxMap.get(ws)
     // console.log('webSocketClose', ctx, ws)
-    if (ctx) {
+    if (ctx !== undefined) {
       await Scope.close(ctx.scope, Exit.void).pipe(Effect.runPromise)
       serverCtxMap.delete(ws)
     }
@@ -212,7 +235,7 @@ export interface WsRpcServerArgs {
   ws: CfTypes.WebSocket
   onMessage?: (message: RpcMessage.FromClientEncoded, ws: CfTypes.WebSocket) => void
   /** Mailbox queue for receiving incoming messages from the WebSocket */
-  incomingQueue: Mailbox.Mailbox<Uint8Array<ArrayBufferLike> | string>
+  incomingQueue: Mailbox.Mailbox<Uint8Array | string>
 }
 
 /**
@@ -221,13 +244,16 @@ export interface WsRpcServerArgs {
  * This layer handles the low-level WebSocket protocol details for RPC communication,
  * including message serialization, routing, and error handling.
  *
+ * Also provides `WsContext` with the current WebSocket so handlers can access
+ * WebSocket attachment data (e.g., forwarded headers).
+ *
  * @param args Configuration for WebSocket RPC protocol
- * @returns Effect layer that provides RPC server protocol functionality
+ * @returns Effect layer that provides RPC server protocol functionality and WsContext
  *
  * @internal This is typically used internally by `setupDurableObjectWebSocketRpc`
  */
 export const layerRpcServerWebsocket = (args: WsRpcServerArgs) =>
-  Layer.scoped(RpcServer.Protocol, makeSocketProtocol(args))
+  Layer.mergeAll(Layer.scoped(RpcServer.Protocol, makeSocketProtocol(args)), Layer.succeed(WsContext, { ws: args.ws }))
 
 /**
  * Creates the low-level RPC protocol implementation for WebSocket communication.
@@ -245,7 +271,7 @@ const makeSocketProtocol = ({ incomingQueue, ws, onMessage }: WsRpcServerArgs) =
     const serialization = yield* RpcSerialization.RpcSerialization
     const disconnects = yield* Mailbox.make<number>()
 
-    const writeRaw = (msg: Uint8Array<ArrayBufferLike> | string) => Effect.succeed(ws.send(msg))
+    const writeRaw = (msg: Uint8Array | string) => Effect.succeed(ws.send(msg))
 
     let writeRequest!: (clientId: number, message: RpcMessage.FromClientEncoded) => Effect.Effect<void>
 
@@ -278,7 +304,7 @@ const makeSocketProtocol = ({ incomingQueue, ws, onMessage }: WsRpcServerArgs) =
               while: () => i < decoded.length,
               body: () => {
                 const request = decoded[i++]!
-                if (onMessage) {
+                if (onMessage !== undefined) {
                   onMessage(request, ws)
                 }
                 return writeRequest(id, request)

package/src/ws-rpc/ws-rpc.test.ts

@@ -1,3 +1,7 @@
+import { expect } from 'vitest'
+
+import { Vitest } from '@livestore/utils-dev/node-vitest'
+import { WranglerDevServerService } from '@livestore/utils-dev/wrangler'
 import {
   Chunk,
   Effect,
@@ -12,9 +16,7 @@ import {
   Stream,
 } from '@livestore/utils/effect'
 import { PlatformNode } from '@livestore/utils/node'
-import { Vitest } from '@livestore/utils-dev/node-vitest'
-import { WranglerDevServerService } from '@livestore/utils-dev/wrangler'
-import { expect } from 'vitest'
+
 import { TestRpcs } from './test-fixtures/rpc-schema.ts'
 
 const testTimeout = 60_000