@syncular/server 0.15.26 → 0.15.27

package/README.md

@@ -57,6 +57,37 @@ done by a binding of the core or by in-database fanout — a relay would add a
 hop, a second protocol surface, and a managed dependency for zero capability
 the core lacks.
 
+## Startup schema readiness
+
+Fail startup before accepting traffic when the generated schema cannot compile
+or the storage projection cannot migrate:
+
+```ts
+import {
+  ensureSyncServerReady,
+  SqliteServerStorage,
+  type SyncServerConfig,
+} from '@syncular/server';
+
+const config: SyncServerConfig = {
+  schema,
+  storage: new SqliteServerStorage('./sync.db'),
+  segments,
+  resolveScopes,
+};
+
+await ensureSyncServerReady(config);
+Bun.serve({ fetch: app.fetch });
+```
+
+The helper accepts the generated `ServerSchema`, compiles it, and calls the
+storage backend's low-level `ensureSchema(CompiledSchema)`. A failure is a
+`SyncServerReadinessError` with stable code `sync.schema_not_ready`, a `phase`
+of `schema_compile` or `storage_migration`, and the generated schema version.
+Log the cause for operators and stop startup. Do not catch readiness errors in
+authentication or convert them to a 401; request-time schema checks are only a
+defensive fallback.
+
 ## Write validators and recovery metadata
 
 `validators` is the server-authoritative seam for row business rules that

package/dist/index.d.ts

@@ -26,6 +26,7 @@ export * from './postgres-storage.js';
 export * from './prune.js';
 export * from './pull.js';
 export * from './push.js';
+export * from './readiness.js';
 export * from './realtime.js';
 export * from './relational-rows.js';
 export * from './s3-blob-store.js';

package/dist/index.js

@@ -30,6 +30,7 @@ export * from './postgres-storage.js';
 export * from './prune.js';
 export * from './pull.js';
 export * from './push.js';
+export * from './readiness.js';
 export * from './realtime.js';
 export * from './relational-rows.js';
 export * from './s3-blob-store.js';

package/dist/readiness.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Explicit server startup readiness.
+ *
+ * Protocol handlers ensure storage lazily for embeddability, but a production
+ * host must prove schema compatibility before it binds an HTTP/WebSocket port.
+ * This helper accepts the generated ServerSchema, compiles it once, and exposes
+ * a structured failure that cannot be confused with request authentication.
+ */
+import type { SyncServerConfig } from './context.js';
+export declare const SYNC_SERVER_READINESS_ERROR_CODE: "sync.schema_not_ready";
+export type SyncServerReadinessPhase = 'schema_compile' | 'storage_migration';
+export declare class SyncServerReadinessError extends Error {
+    readonly name = "SyncServerReadinessError";
+    readonly code: "sync.schema_not_ready";
+    readonly phase: SyncServerReadinessPhase;
+    readonly schemaVersion: number;
+    constructor(options: {
+        readonly phase: SyncServerReadinessPhase;
+        readonly schemaVersion: number;
+        readonly cause: unknown;
+    });
+}
+/**
+ * Compile and migrate the configured server storage before listening.
+ *
+ * Pass the same canonical config used by HTTP and realtime. The thrown error
+ * exposes only a stable code, phase, and schema version; operators can inspect
+ * `cause` locally for the table/column or storage diagnostic.
+ */
+export declare function ensureSyncServerReady(config: Pick<SyncServerConfig, 'schema' | 'storage'>): Promise<void>;

package/dist/readiness.js

@@ -0,0 +1,43 @@
+import { compileSchema } from './schema.js';
+export const SYNC_SERVER_READINESS_ERROR_CODE = 'sync.schema_not_ready';
+export class SyncServerReadinessError extends Error {
+    name = 'SyncServerReadinessError';
+    code = SYNC_SERVER_READINESS_ERROR_CODE;
+    phase;
+    schemaVersion;
+    constructor(options) {
+        super(`Syncular server schema ${options.schemaVersion} is not ready (${options.phase})`, { cause: options.cause });
+        this.phase = options.phase;
+        this.schemaVersion = options.schemaVersion;
+    }
+}
+/**
+ * Compile and migrate the configured server storage before listening.
+ *
+ * Pass the same canonical config used by HTTP and realtime. The thrown error
+ * exposes only a stable code, phase, and schema version; operators can inspect
+ * `cause` locally for the table/column or storage diagnostic.
+ */
+export async function ensureSyncServerReady(config) {
+    let compiled;
+    try {
+        compiled = compileSchema(config.schema);
+    }
+    catch (cause) {
+        throw new SyncServerReadinessError({
+            phase: 'schema_compile',
+            schemaVersion: config.schema.version,
+            cause,
+        });
+    }
+    try {
+        await config.storage.ensureSchema(compiled);
+    }
+    catch (cause) {
+        throw new SyncServerReadinessError({
+            phase: 'storage_migration',
+            schemaVersion: config.schema.version,
+            cause,
+        });
+    }
+}

package/dist/storage.d.ts

@@ -237,6 +237,11 @@ export interface ServerStorage {
      * INDEX). The handler calls this before serving; hosts that drive
      * storage directly (tests, admin tooling) call it once up front. Row
      * operations for tables not covered by an `ensureSchema` call throw.
+     *
+     * This low-level storage seam accepts a `CompiledSchema`. Application hosts
+     * should call `ensureSyncServerReady(config)` with their generated schema
+     * before binding a public port; protocol handlers still call this method
+     * lazily as a defensive backstop.
      */
     ensureSchema(schema: CompiledSchema): Promise<void>;
     begin(partition: string): Promise<StorageTransaction>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/server",
-  "version": "0.15.26",
+  "version": "0.15.27",
   "description": "Syncular server: handleSyncRequest + storage/auth interfaces for the sync protocol",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -53,7 +53,7 @@
     "!dist/**/*.test.d.ts"
   ],
   "dependencies": {
-    "@syncular/core": "0.15.26"
+    "@syncular/core": "0.15.27"
   },
   "devDependencies": {
     "@electric-sql/pglite": "^0.5.4"

package/src/index.ts

@@ -30,6 +30,7 @@ export * from './postgres-storage';
 export * from './prune';
 export * from './pull';
 export * from './push';
+export * from './readiness';
 export * from './realtime';
 export * from './relational-rows';
 export * from './s3-blob-store';

package/src/readiness.ts

@@ -0,0 +1,66 @@
+/**
+ * Explicit server startup readiness.
+ *
+ * Protocol handlers ensure storage lazily for embeddability, but a production
+ * host must prove schema compatibility before it binds an HTTP/WebSocket port.
+ * This helper accepts the generated ServerSchema, compiles it once, and exposes
+ * a structured failure that cannot be confused with request authentication.
+ */
+import type { SyncServerConfig } from './context';
+import { type CompiledSchema, compileSchema } from './schema';
+
+export const SYNC_SERVER_READINESS_ERROR_CODE =
+  'sync.schema_not_ready' as const;
+
+export type SyncServerReadinessPhase = 'schema_compile' | 'storage_migration';
+
+export class SyncServerReadinessError extends Error {
+  override readonly name = 'SyncServerReadinessError';
+  readonly code = SYNC_SERVER_READINESS_ERROR_CODE;
+  readonly phase: SyncServerReadinessPhase;
+  readonly schemaVersion: number;
+
+  constructor(options: {
+    readonly phase: SyncServerReadinessPhase;
+    readonly schemaVersion: number;
+    readonly cause: unknown;
+  }) {
+    super(
+      `Syncular server schema ${options.schemaVersion} is not ready (${options.phase})`,
+      { cause: options.cause },
+    );
+    this.phase = options.phase;
+    this.schemaVersion = options.schemaVersion;
+  }
+}
+
+/**
+ * Compile and migrate the configured server storage before listening.
+ *
+ * Pass the same canonical config used by HTTP and realtime. The thrown error
+ * exposes only a stable code, phase, and schema version; operators can inspect
+ * `cause` locally for the table/column or storage diagnostic.
+ */
+export async function ensureSyncServerReady(
+  config: Pick<SyncServerConfig, 'schema' | 'storage'>,
+): Promise<void> {
+  let compiled: CompiledSchema;
+  try {
+    compiled = compileSchema(config.schema);
+  } catch (cause) {
+    throw new SyncServerReadinessError({
+      phase: 'schema_compile',
+      schemaVersion: config.schema.version,
+      cause,
+    });
+  }
+  try {
+    await config.storage.ensureSchema(compiled);
+  } catch (cause) {
+    throw new SyncServerReadinessError({
+      phase: 'storage_migration',
+      schemaVersion: config.schema.version,
+      cause,
+    });
+  }
+}

package/src/storage.ts

@@ -269,6 +269,11 @@ export interface ServerStorage {
    * INDEX). The handler calls this before serving; hosts that drive
    * storage directly (tests, admin tooling) call it once up front. Row
    * operations for tables not covered by an `ensureSchema` call throw.
+   *
+   * This low-level storage seam accepts a `CompiledSchema`. Application hosts
+   * should call `ensureSyncServerReady(config)` with their generated schema
+   * before binding a public port; protocol handlers still call this method
+   * lazily as a defensive backstop.
    */
   ensureSchema(schema: CompiledSchema): Promise<void>;