@syncular/server-workers 0.15.48 → 0.17.0

package/README.md

@@ -101,21 +101,23 @@ See `wrangler.toml.example` for the binding config.
 
 ## Schema migration (D1)
 
-`D1ServerStorage` does **not** apply its DDL on construction (a cold request
-must never race a schema apply). Apply it once with wrangler. Generate the
-migration SQL from `sqliteDdlStatements()` (exported from `@syncular/server`)
-into a `migrations/` file, then:
-
-```sh
-wrangler d1 create syncular
-wrangler d1 migrations apply syncular
-```
-
-The schema is plain SQLite DDL (shared with `bun:sqlite` via
-`sqlite-dialect.ts`), so it is portable across the two SQLite-family
-storages. Regenerate and apply a migration when upgrading Syncular adds a core
-table. The durable reaction queue uses `sync_reactions`; a Worker running a
-reaction planner or runner fails closed if that migration is absent.
+Run `storage.migrateSchema(compileSchema(schema))` from an authenticated
+maintenance handler before admitting sync traffic. The method creates core
+and application tables and rewrites stored rows. It returns
+`{ complete, statementsExecuted }`; call it again in a new Worker invocation
+when `complete` is false.
+
+Each call defaults to 50 statements. Set `{ maxStatements: 40 }` to leave
+room for other queries, or choose another integer from 10 through 1000 for
+your D1 plan. Run at most one call per invocation. Progress and row updates
+commit together, so interrupted requests can resume with the same schema.
+The storage rejects row reads and transaction commits during migration.
+
+`ensureSchema` performs one step and throws
+`sync.storage.schema_migration_pending` when another invocation is needed.
+Drain older Syncular deployments before starting an upgrade: they do not
+check the migration state. See [the migration guide](https://syncular.dev/server-workers/#schema-migration)
+for a maintenance handler and the remaining D1 limits.
 
 ## Storage: D1 (`D1ServerStorage`)
 
@@ -139,6 +141,10 @@ from a Worker scheduler, queue consumer, Workflow step, or Durable Object
 alarm according to the application's hosting model.
 
 Schedule `pruneReactions` per partition as a separate maintenance pass.
+For commit-log pruning, expose the `SyncularRealtimeHost.pruneCommitLog` method
+through the owning Durable Object and call its RPC from the scheduler. This
+method uses the existing partition FIFO. Direct D1 pruning requires the same
+external serialization assertion as push application.
 Defaults retain completed rows for 30 days and dead-lettered rows for 90 days,
 with at most 1,000 deletions per pass. Repeat while `mayHaveMore` is true.
 Pending and leased rows are never eligible. D1 executes each bounded cleanup
@@ -263,6 +269,9 @@ const realtimeDOConfig = (env: Env): RealtimeDOConfig => ({
 export class SyncularRealtimeDO extends DurableObject<Env> {
   #host = new SyncularRealtimeHost(this.ctx, this.env.DB, realtimeDOConfig(this.env));
   fetch(request: Request) { return this.#host.fetch(request); }
+  pruneCommitLog(partition: string, nowMs: number) {
+    return this.#host.pruneCommitLog({ partition, nowMs });
+  }
   webSocketMessage(ws: WebSocket, msg: ArrayBuffer | string) {
     return this.#host.webSocketMessage(ws, msg);
   }

package/dist/realtime-do.d.ts

@@ -67,7 +67,7 @@
  * partition serialization may call `/__wake` after its own commit so sockets
  * re-pull. See `durableObjectRealtimeNotifier` for that caller side.
  */
-import { D1ServerStorage, type RealtimeHubConfig } from '@syncular/server';
+import { D1ServerStorage, type PruneOptions, type RealtimeHubConfig } from '@syncular/server';
 export interface DurableObjectStateLike {
     acceptWebSocket(ws: WebSocketLike, tags?: string[]): void;
     getWebSockets(tag?: string): WebSocketLike[];
@@ -153,6 +153,8 @@ export declare class SyncularRealtimeHost {
      * and accepts external-command wakes at `/__syncular_realtime/wake`.
      */
     fetch(request: Request): Promise<Response>;
+    /** Trusted maintenance shares the partition FIFO with HTTP/socket writes. */
+    pruneCommitLog(options: Omit<PruneOptions, 'storage'>): Promise<number>;
     /** Hibernation callback: an inbound frame. */
     webSocketMessage(ws: WebSocketLike, message: ArrayBuffer | string): Promise<void>;
     /** Hibernation callback: the socket closed. */

package/dist/realtime-do.js

@@ -67,7 +67,7 @@
  * partition serialization may call `/__wake` after its own commit so sockets
  * re-pull. See `durableObjectRealtimeNotifier` for that caller side.
  */
-import { createRealtimeHub, D1ServerStorage, errorBody, handleSyncRequest, SSP2_CONTENT_TYPE, SyncError, } from '@syncular/server';
+import { createRealtimeHub, D1ServerStorage, errorBody, handleSyncRequest, pruneCommitLog, SSP2_CONTENT_TYPE, SyncError, } from '@syncular/server';
 function isAttachment(value) {
     return (typeof value === 'object' &&
         value !== null &&
@@ -158,6 +158,13 @@ export class SyncularRealtimeHost {
         }
         return new Response('not found', { status: 404 });
     }
+    /** Trusted maintenance shares the partition FIFO with HTTP/socket writes. */
+    pruneCommitLog(options) {
+        return this.#serializePartition(async () => {
+            await this.#storage.migrate();
+            return pruneCommitLog({ ...options, storage: this.#storage });
+        });
+    }
     #serializePartition(operation) {
         const result = this.#partitionTail.then(operation, operation);
         this.#partitionTail = result.then(() => undefined, () => undefined);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/server-workers",
-  "version": "0.15.48",
+  "version": "0.17.0",
   "description": "Cloudflare Workers adapter for the Syncular sync server",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -45,10 +45,10 @@
     "!dist/**/*.test.d.ts"
   ],
   "dependencies": {
-    "@syncular/server": "0.15.48",
-    "@syncular/server-hono": "0.15.48"
+    "@syncular/server": "0.17.0",
+    "@syncular/server-hono": "0.17.0"
   },
   "devDependencies": {
-    "@syncular/core": "0.15.48"
+    "@syncular/core": "0.17.0"
   }
 }

package/src/realtime-do.ts

@@ -72,6 +72,8 @@ import {
   D1ServerStorage,
   errorBody,
   handleSyncRequest,
+  pruneCommitLog,
+  type PruneOptions,
   type RealtimeHub,
   type RealtimeHubConfig,
   type RealtimeSession,
@@ -249,6 +251,14 @@ export class SyncularRealtimeHost {
     return new Response('not found', { status: 404 });
   }
 
+  /** Trusted maintenance shares the partition FIFO with HTTP/socket writes. */
+  pruneCommitLog(options: Omit<PruneOptions, 'storage'>): Promise<number> {
+    return this.#serializePartition(async () => {
+      await this.#storage.migrate();
+      return pruneCommitLog({ ...options, storage: this.#storage });
+    });
+  }
+
   #serializePartition<T>(operation: () => Promise<T>): Promise<T> {
     const result = this.#partitionTail.then(operation, operation);
     this.#partitionTail = result.then(