@livestore/sync-cf 0.4.0-dev.8 → 0.4.0-dev.9

package/src/cf-worker/shared.ts

@@ -1,6 +1,7 @@
 import type { InvalidPullError, InvalidPushError } from '@livestore/common'
 import type { CfTypes } from '@livestore/common-cf'
-import { Effect, type Option, Schema, UrlParams } from '@livestore/utils/effect'
+import { Effect, Schema, UrlParams } from '@livestore/utils/effect'
+import type { SearchParams } from '../common/mod.ts'
 import { SearchParamsSchema, SyncMessage } from '../common/mod.ts'
 
 export interface Env {
@@ -48,20 +49,32 @@ export type DurableObjectId = string
  */
 export const PERSISTENCE_FORMAT_VERSION = 7
 
-export const DEFAULT_SYNC_DURABLE_OBJECT_NAME = 'SYNC_BACKEND_DO'
-
 export const encodeOutgoingMessage = Schema.encodeSync(Schema.parseJson(SyncMessage.BackendToClientMessage))
 export const encodeIncomingMessage = Schema.encodeSync(Schema.parseJson(SyncMessage.ClientToBackendMessage))
 
-export const getSyncRequestSearchParams = (request: CfTypes.Request): Option.Option<typeof SearchParamsSchema.Type> => {
+/**
+ * Extracts the LiveStore sync search parameters from a request. Returns
+ * `undefined` when the request does not carry valid sync metadata so callers
+ * can fall back to custom routing.
+ */
+export const matchSyncRequest = (request: CfTypes.Request): SearchParams | undefined => {
   const url = new URL(request.url)
   const urlParams = UrlParams.fromInput(url.searchParams)
   const paramsResult = UrlParams.schemaStruct(SearchParamsSchema)(urlParams).pipe(Effect.option, Effect.runSync)
 
-  return paramsResult
+  if (paramsResult._tag === 'None') {
+    return undefined
+  }
+
+  return paramsResult.value
 }
 
-export const PULL_CHUNK_SIZE = 100
+export const MAX_PULL_EVENTS_PER_MESSAGE = 100
+
+// Cloudflare hibernated WebSocket frames begin failing just below 1MB. Keep our
+// payloads comfortably beneath that ceiling so we don't rely on implementation
+// quirks of local dev servers.
+export const MAX_WS_MESSAGE_BYTES = 900_000
 
 // RPC subscription storage (TODO refactor)
 export type RpcSubscription = {

package/src/cf-worker/worker.ts

@@ -1,42 +1,14 @@
 import { UnexpectedError } from '@livestore/common'
+import type { HelperTypes } from '@livestore/common-cf'
 import type { Schema } from '@livestore/utils/effect'
 import { Effect } from '@livestore/utils/effect'
 import type { CfTypes, SearchParams } from '../common/mod.ts'
 import type { CfDeclare } from './mod.ts'
-import { DEFAULT_SYNC_DURABLE_OBJECT_NAME, type Env, getSyncRequestSearchParams } from './shared.ts'
+import { type Env, 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 {}
 
-export namespace HelperTypes {
-  type AnyDON = CfTypes.DurableObjectNamespace<undefined>
-
-  type DOKeys<T> = {
-    [K in keyof T]-?: T[K] extends AnyDON ? K : never
-  }[keyof T]
-
-  type NonBuiltins<T> = Omit<T, keyof Env>
-
-  /**
-   * Helper type to extract DurableObject keys from Env to give consumer type safety.
-   *
-   * @example
-   * ```ts
-   *  type PlatformEnv = {
-   *    DB: D1Database
-   *    ADMIN_TOKEN: string
-   *    SYNC_BACKEND_DO: DurableObjectNamespace<SyncBackendDO>
-   * }
-   *  export default makeWorker<PlatformEnv>({
-   *    durableObject: { name: "SYNC_BACKEND_DO" },
-   *    // ^ (property) name?: "SYNC_BACKEND_DO" | undefined
-   *  });
-   */
-  export type ExtractDurableObjectKeys<TEnv = Env> = DOKeys<NonBuiltins<TEnv>> extends never
-    ? string
-    : DOKeys<NonBuiltins<TEnv>>
-}
-
 // HINT: If we ever extend user's custom worker RPC, type T can help here with expected return type safety. Currently unused.
 export type CFWorker<TEnv extends Env = Env, _T extends CfTypes.Rpc.DurableObjectBranded | undefined = undefined> = {
   fetch: <CFHostMetada = unknown>(
@@ -46,7 +18,15 @@ export type CFWorker<TEnv extends Env = Env, _T extends CfTypes.Rpc.DurableObjec
   ) => Promise<CfTypes.Response>
 }
 
+/**
+ * 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.
+ */
 export type MakeWorkerOptions<TEnv extends Env = Env> = {
+  /**
+   * 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.
@@ -55,21 +35,20 @@ export type MakeWorkerOptions<TEnv extends Env = Env> = {
   validatePayload?: (payload: Schema.JsonValue | undefined, context: { storeId: string }) => void | Promise<void>
   /** @default false */
   enableCORS?: boolean
-  durableObject?: {
-    /**
-     * Needs to match the binding name from the wrangler config
-     *
-     * @default 'SYNC_BACKEND_DO'
-     */
-    name?: HelperTypes.ExtractDurableObjectKeys<TEnv>
-  }
 }
 
+/**
+ * Produces a Cloudflare Worker `fetch` handler that delegates sync traffic to the
+ * Durable Object identified by `syncBackendBinding`.
+ *
+ * For more complex setups prefer implementing a custom `fetch` and call {@link handleSyncRequest}
+ * from the branch that handles LiveStore sync requests.
+ */
 export const makeWorker = <
   TEnv extends Env = Env,
   TDurableObjectRpc extends CfTypes.Rpc.DurableObjectBranded | undefined = undefined,
 >(
-  options: MakeWorkerOptions<TEnv> = {},
+  options: MakeWorkerOptions<TEnv>,
 ): CFWorker<TEnv, TDurableObjectRpc> => {
   return {
     fetch: async (request, env, _ctx) => {
@@ -90,20 +69,18 @@ export const makeWorker = <
         })
       }
 
-      const requestParamsResult = getSyncRequestSearchParams(request)
+      const searchParams = matchSyncRequest(request)
 
       // Check if this is a sync request first, before showing info message
-      if (requestParamsResult._tag === 'Some') {
+      if (searchParams !== undefined) {
         return handleSyncRequest<TEnv, TDurableObjectRpc>({
           request,
-          searchParams: requestParamsResult.value,
+          searchParams,
           env,
           ctx: _ctx,
-          options: {
-            headers: corsHeaders,
-            validatePayload: options.validatePayload,
-            durableObject: options.durableObject,
-          },
+          syncBackendBinding: options.syncBackendBinding,
+          headers: corsHeaders,
+          validatePayload: options.validatePayload,
         })
       }
 
@@ -143,16 +120,18 @@ export const makeWorker = <
  *
  * export default {
  *   fetch: async (request, env, ctx) => {
- *     const requestParamsResult = getSyncRequestSearchParams(request)
+ *     const searchParams = matchSyncRequest(request)
  *
  *     // Is LiveStore sync request
- *     if (requestParamsResult._tag === 'Some') {
+ *     if (searchParams !== undefined) {
  *       return handleSyncRequest({
  *         request,
- *         searchParams: requestParamsResult.value,
+ *         searchParams,
  *         env,
  *         ctx,
- *         options: { headers: {}, validatePayload }
+ *         syncBackendBinding: 'SYNC_BACKEND_DO',
+ *         headers: {},
+ *         validatePayload,
  *       })
  *     }
  *
@@ -169,49 +148,47 @@ export const handleSyncRequest = <
   CFHostMetada = unknown,
 >({
   request,
-  searchParams,
+  searchParams: { storeId, payload, transport },
   env,
-  options = {},
+  syncBackendBinding,
+  headers,
+  validatePayload,
 }: {
   request: CfTypes.Request<CFHostMetada>
   searchParams: SearchParams
   env: TEnv
   /** Only there for type-level reasons */
   ctx: CfTypes.ExecutionContext
-  options?: {
-    headers?: CfTypes.HeadersInit
-    durableObject?: MakeWorkerOptions<TEnv>['durableObject']
-    validatePayload?: (payload: Schema.JsonValue | undefined, context: { storeId: string }) => void | Promise<void>
-  }
+  /** Binding name of the sync backend Durable Object */
+  syncBackendBinding: MakeWorkerOptions<TEnv>['syncBackendBinding']
+  headers?: CfTypes.HeadersInit | undefined
+  validatePayload?: (payload: Schema.JsonValue | undefined, context: { storeId: string }) => void | Promise<void>
 }): Promise<CfTypes.Response> =>
   Effect.gen(function* () {
-    const { storeId, payload, transport } = searchParams
-
-    if (options.validatePayload !== undefined) {
-      const result = yield* Effect.promise(async () => options.validatePayload!(payload, { storeId })).pipe(
+    if (validatePayload !== undefined) {
+      const result = yield* Effect.promise(async () => validatePayload!(payload, { storeId })).pipe(
         UnexpectedError.mapToUnexpectedError,
         Effect.either,
       )
 
       if (result._tag === 'Left') {
         console.error('Invalid payload', result.left)
-        return new Response(result.left.toString(), { status: 400, headers: options.headers })
+        return new Response(result.left.toString(), { status: 400, headers })
       }
     }
 
-    const durableObjectName = options.durableObject?.name ?? DEFAULT_SYNC_DURABLE_OBJECT_NAME
-    if (!(durableObjectName in env)) {
+    if (!(syncBackendBinding in env)) {
       return new Response(
-        `Failed dependency: Required Durable Object binding '${durableObjectName as string}' not available`,
+        `Failed dependency: Required Durable Object binding '${syncBackendBinding as string}' not available`,
         {
           status: 424,
-          headers: options.headers,
+          headers,
         },
       )
     }
 
     const durableObjectNamespace = env[
-      durableObjectName as keyof TEnv
+      syncBackendBinding as keyof TEnv
     ] as CfTypes.DurableObjectNamespace<TDurableObjectRpc>
 
     const id = durableObjectNamespace.idFromName(storeId)
@@ -222,7 +199,7 @@ export const handleSyncRequest = <
     if (transport === 'ws' && (upgradeHeader === null || upgradeHeader !== 'websocket')) {
       return new Response('Durable Object expected Upgrade: websocket', {
         status: 426,
-        headers: options?.headers,
+        headers,
       })
     }