@livestore/sync-cf 0.4.0-dev.20 → 0.4.0-dev.22

package/src/cf-worker/shared.ts

@@ -7,17 +7,61 @@ import { SearchParamsSchema, SyncMessage } from '../common/mod.ts'
 
 export type Env = {}
 
+/** Headers forwarded from the request to callbacks */
+export type ForwardedHeaders = ReadonlyMap<string, string>
+
+/**
+ * Configuration for forwarding request headers to DO callbacks.
+ * - `string[]`: List of header names to forward (case-insensitive)
+ * - `(request) => Record<string, string>`: Custom extraction function (sync)
+ */
+export type ForwardHeadersOption = readonly string[] | ((request: CfTypes.Request) => Record<string, string>)
+
+/** Context passed to onPush/onPull callbacks */
+export type CallbackContext = {
+  storeId: StoreId
+  payload?: Schema.JsonValue
+  /** Headers forwarded from the request (only present if `forwardHeaders` is configured) */
+  headers?: ForwardedHeaders
+}
+
 export type MakeDurableObjectClassOptions = {
-  onPush?: (
-    message: SyncMessage.PushRequest,
-    context: { storeId: StoreId; payload?: Schema.JsonValue },
-  ) => Effect.SyncOrPromiseOrEffect<void>
+  onPush?: (message: SyncMessage.PushRequest, context: CallbackContext) => Effect.SyncOrPromiseOrEffect<void>
   onPushRes?: (message: SyncMessage.PushAck | InvalidPushError) => Effect.SyncOrPromiseOrEffect<void>
-  onPull?: (
-    message: SyncMessage.PullRequest,
-    context: { storeId: StoreId; payload?: Schema.JsonValue },
-  ) => Effect.SyncOrPromiseOrEffect<void>
+  onPull?: (message: SyncMessage.PullRequest, context: CallbackContext) => Effect.SyncOrPromiseOrEffect<void>
   onPullRes?: (message: SyncMessage.PullResponse | InvalidPullError) => Effect.SyncOrPromiseOrEffect<void>
+
+  /**
+   * Forward request headers to `onPush`/`onPull` callbacks for authentication.
+   *
+   * This enables cookie-based or header-based authentication patterns where
+   * you need access to request headers inside the Durable Object.
+   *
+   * @example Forward specific headers by name (case-insensitive)
+   * ```ts
+   * makeDurableObject({
+   *   forwardHeaders: ['cookie', 'authorization'],
+   *   onPush: async (message, { headers }) => {
+   *     const cookie = headers?.get('cookie')
+   *     const session = await validateSession(cookie)
+   *   },
+   * })
+   * ```
+   *
+   * @example Custom extraction function for derived values
+   * ```ts
+   * makeDurableObject({
+   *   forwardHeaders: (request) => ({
+   *     'x-user-id': request.headers.get('x-user-id') ?? '',
+   *     'x-session': request.headers.get('cookie')?.split('session=')[1]?.split(';')[0] ?? '',
+   *   }),
+   *   onPush: async (message, { headers }) => {
+   *     const userId = headers?.get('x-user-id')
+   *   },
+   * })
+   * ```
+   */
+  forwardHeaders?: ForwardHeadersOption
   /**
    * Storage engine for event persistence.
    * - Default: `{ _tag: 'do-sqlite' }` (Durable Object SQLite)
@@ -137,5 +181,39 @@ export const WebSocketAttachmentSchema = Schema.parseJson(
     // Different for each websocket connection
     payload: Schema.optional(Schema.JsonValue),
     pullRequestIds: Schema.Array(Schema.String),
+    // Headers forwarded from the initial request (via forwardHeaders option)
+    headers: Schema.optional(Schema.Record({ key: Schema.String, value: Schema.String })),
   }),
 )
+
+/** Helper to extract headers from a request based on the forwardHeaders option */
+export const extractForwardedHeaders = (
+  request: CfTypes.Request,
+  forwardHeaders: ForwardHeadersOption | undefined,
+): Record<string, string> | undefined => {
+  if (forwardHeaders === undefined) {
+    return undefined
+  }
+
+  if (typeof forwardHeaders === 'function') {
+    return forwardHeaders(request)
+  }
+
+  // Array of header names - extract them case-insensitively
+  const result: Record<string, string> = {}
+  for (const name of forwardHeaders) {
+    const value = request.headers.get(name)
+    if (value !== null) {
+      result[name.toLowerCase()] = value
+    }
+  }
+  return Object.keys(result).length > 0 ? result : undefined
+}
+
+/** Convert a headers record to a ReadonlyMap */
+export const headersRecordToMap = (headers: Record<string, string> | undefined): ForwardedHeaders | undefined => {
+  if (headers === undefined) {
+    return undefined
+  }
+  return new Map(Object.entries(headers).map(([key, value]) => [key.toLowerCase(), value]))
+}

package/src/cf-worker/worker.ts

@@ -4,7 +4,7 @@ import type { HelperTypes } from '@livestore/common-cf'
 import { Effect, Schema } from '@livestore/utils/effect'
 import type { CfTypes, SearchParams } from '../common/mod.ts'
 import type { CfDeclare } from './mod.ts'
-import { type Env, matchSyncRequest } from './shared.ts'
+import { type Env, type ForwardedHeaders, matchSyncRequest } from './shared.ts'
 
 // NOTE We need to redeclare runtime types here to avoid type conflicts with the lib.dom Response type.
 declare class Response extends CfDeclare.Response {}
@@ -18,6 +18,13 @@ export type CFWorker<TEnv extends Env = Env, _T extends CfTypes.Rpc.DurableObjec
   ) => Promise<CfTypes.Response>
 }
 
+/** Context passed to validatePayload callback */
+export type ValidatePayloadContext = {
+  storeId: string
+  /** Request headers (raw, not filtered by forwardHeaders) */
+  headers: ForwardedHeaders
+}
+
 /**
  * Options accepted by {@link makeWorker}. The Durable Object binding has to be
  * supplied explicitly so we never fall back to deprecated defaults when Cloudflare config changes.
@@ -27,11 +34,6 @@ export type MakeWorkerOptions<TEnv extends Env = Env, TSyncPayload = Schema.Json
    * Binding name of the sync Durable Object declared in wrangler config.
    */
   syncBackendBinding: HelperTypes.ExtractDurableObjectKeys<TEnv>
-  /**
-   * Validates the payload during WebSocket connection establishment.
-   * Note: This runs only at connection time, not for individual push events.
-   * For push event validation, use the `onPush` callback in the durable object.
-   */
   /**
    * Optionally pass a schema to decode the client-provided payload into a typed object
    * before calling {@link validatePayload}. If omitted, the raw JSON value is forwarded.
@@ -39,9 +41,23 @@ export type MakeWorkerOptions<TEnv extends Env = Env, TSyncPayload = Schema.Json
   syncPayloadSchema?: Schema.Schema<TSyncPayload>
   /**
    * Validates the (optionally decoded) payload during WebSocket connection establishment.
-   * If {@link syncPayloadSchema} is provided, `payload` will be of the schema’s inferred type.
+   * If {@link syncPayloadSchema} is provided, `payload` will be of the schema's inferred type.
+   *
+   * The context includes request headers for cookie-based or header-based authentication.
+   *
+   * @example Cookie-based authentication
+   * ```ts
+   * validatePayload: async (payload, { storeId, headers }) => {
+   *   const cookie = headers.get('cookie')
+   *   const session = await validateSessionFromCookie(cookie)
+   *   if (!session) throw new Error('Unauthorized')
+   * }
+   * ```
+   *
+   * Note: This runs only at connection time, not for individual push events.
+   * For push event validation, use the `onPush` callback in the Durable Object.
    */
-  validatePayload?: (payload: TSyncPayload, context: { storeId: string }) => void | Promise<void>
+  validatePayload?: (payload: TSyncPayload, context: ValidatePayloadContext) => void | Promise<void>
   /** @default false */
   enableCORS?: boolean
 }
@@ -117,37 +133,33 @@ export const makeWorker = <
   }
 }
 
+/** Convert CF Request headers to a ForwardedHeaders map */
+const requestHeadersToMap = (request: CfTypes.Request): ForwardedHeaders => {
+  const result = new Map<string, string>()
+  request.headers.forEach((value, key) => {
+    result.set(key.toLowerCase(), value)
+  })
+  return result
+}
+
 /**
  * Handles LiveStore sync requests (e.g. with search params `?storeId=...&transport=...`).
  *
- * @example
+ * @example Token-based authentication
  * ```ts
  * const validatePayload = (payload: Schema.JsonValue | undefined, context: { storeId: string }) => {
- *   console.log(`Validating connection for store: ${context.storeId}`)
  *   if (payload?.authToken !== 'insecure-token-change-me') {
  *     throw new Error('Invalid auth token')
  *   }
  * }
+ * ```
  *
- * export default {
- *   fetch: async (request, env, ctx) => {
- *     const searchParams = matchSyncRequest(request)
- *
- *     // Is LiveStore sync request
- *     if (searchParams !== undefined) {
- *       return handleSyncRequest({
- *         request,
- *         searchParams,
- *         env,
- *         ctx,
- *         syncBackendBinding: 'SYNC_BACKEND_DO',
- *         headers: {},
- *         validatePayload,
- *       })
- *     }
- *
- *     return new Response('Invalid path', { status: 400 })
- *   }
+ * @example Cookie-based authentication
+ * ```ts
+ * const validatePayload = async (payload: Schema.JsonValue | undefined, { storeId, headers }) => {
+ *   const cookie = headers.get('cookie')
+ *   const session = await validateSessionFromCookie(cookie)
+ *   if (!session) throw new Error('Unauthorized')
  * }
  * ```
  *
@@ -180,6 +192,9 @@ export const handleSyncRequest = <
 }): Promise<CfTypes.Response> =>
   Effect.gen(function* () {
     if (validatePayload !== undefined) {
+      // Convert request headers to a Map for the validation context
+      const requestHeaders = requestHeadersToMap(request)
+
       // Always decode with the supplied schema when present, even if payload is undefined.
       // This ensures required payloads are enforced by the schema.
       if (syncPayloadSchema !== undefined) {
@@ -191,7 +206,7 @@ export const handleSyncRequest = <
         }
 
         const result = yield* Effect.promise(async () =>
-          validatePayload(decodedEither.right as TSyncPayload, { storeId }),
+          validatePayload(decodedEither.right as TSyncPayload, { storeId, headers: requestHeaders }),
         ).pipe(UnknownError.mapToUnknownError, Effect.either)
 
         if (result._tag === 'Left') {
@@ -199,10 +214,9 @@ export const handleSyncRequest = <
           return new Response(result.left.toString(), { status: 400, headers })
         }
       } else {
-        const result = yield* Effect.promise(async () => validatePayload(payload as TSyncPayload, { storeId })).pipe(
-          UnknownError.mapToUnknownError,
-          Effect.either,
-        )
+        const result = yield* Effect.promise(async () =>
+          validatePayload(payload as TSyncPayload, { storeId, headers: requestHeaders }),
+        ).pipe(UnknownError.mapToUnknownError, Effect.either)
 
         if (result._tag === 'Left') {
           console.error('Invalid payload (validation failed)', result.left)

package/src/common/do-rpc-schema.ts

@@ -4,7 +4,7 @@ import * as SyncMessage from './sync-message-types.ts'
 
 const commonPayloadFields = {
   /**
-   * While the storeId is already implied by the durable object, we still need the explicit storeId
+   * While the storeId is already implied by the Durable Object, we still need the explicit storeId
    * since a DO doesn't know its own id.name value. 🫠
    * https://community.cloudflare.com/t/how-can-i-get-the-name-of-a-durable-object-from-itself/505961/8
    */