@syncular/server 0.0.6-96 → 0.1.1

package/dist/relay/relay.js

@@ -0,0 +1,320 @@
+/**
+ * @syncular/server/relay - Relay Server
+ *
+ * An edge relay server that acts as a local server to nearby clients
+ * while simultaneously acting as a client to the main server.
+ *
+ * Enables offline-first architectures where local network devices
+ * continue syncing when internet is lost.
+ */
+import { sql } from 'kysely';
+import { ForwardEngine } from './client-role/forward-engine.js';
+import { PullEngine } from './client-role/pull-engine.js';
+import { SequenceMapper } from './client-role/sequence-mapper.js';
+import { ensureRelaySchema } from './migrate.js';
+import { ModeManager } from './mode-manager.js';
+import { RelayRealtime } from './realtime.js';
+/**
+ * Relay server that acts as an edge relay between local clients and a main server.
+ *
+ * @example
+ * ```typescript
+ * import { createRelayServer } from '@syncular/server/relay';
+ * import { createSqliteServerDialect } from '@syncular/server/sqlite';
+ *
+ * const relay = createRelayServer({
+ *   db: sqliteDb,
+ *   dialect: createSqliteServerDialect(),
+ *   mainServerTransport: createHttpTransport({ baseUrl: 'https://main.example.com/sync' }),
+ *   mainServerClientId: 'relay-branch-001',
+ *   mainServerActorId: 'relay-service',
+ *   tables: ['tasks', 'projects'],
+ *   scopes: { project_id: 'acme' },
+ *   handlers: shapeRegistry,
+ * });
+ *
+ * // Mount routes for local clients
+ * app.route('/sync', await relay.getRoutes());
+ *
+ * // Start background sync with main
+ * await relay.start();
+ *
+ * // Events
+ * relay.on('modeChange', (mode) => console.log(mode));
+ * relay.on('forwardConflict', (conflict) => handleConflict(conflict));
+ * ```
+ */
+export class RelayServer {
+    db;
+    dialect;
+    mainServerTransport;
+    mainServerClientId;
+    mainServerActorId;
+    tables;
+    scopes;
+    handlers;
+    modeManager;
+    sequenceMapper;
+    forwardEngine;
+    pullEngine;
+    realtime;
+    eventHandlers = new Map();
+    pruneIntervalMs;
+    pruneMaxAgeMs;
+    lastPruneAtMs = 0;
+    pruneInFlight = null;
+    started = false;
+    schemaInitialized = false;
+    routes = null;
+    routesPromise = null;
+    constructor(options) {
+        this.db = options.db;
+        this.dialect = options.dialect;
+        this.mainServerTransport = options.mainServerTransport;
+        this.mainServerClientId = options.mainServerClientId;
+        this.mainServerActorId = options.mainServerActorId;
+        this.tables = options.tables;
+        this.scopes = options.scopes;
+        this.handlers = options.handlers;
+        this.pruneIntervalMs = options.pruneIntervalMs ?? 3600000;
+        this.pruneMaxAgeMs = options.pruneMaxAgeMs ?? 7 * 24 * 60 * 60 * 1000;
+        // Initialize mode manager
+        this.modeManager = new ModeManager({
+            healthCheckIntervalMs: options.healthCheckIntervalMs ?? 30000,
+            onModeChange: (mode) => this.emit('modeChange', mode),
+        });
+        // Initialize sequence mapper
+        this.sequenceMapper = new SequenceMapper({
+            db: this.db,
+        });
+        // Initialize realtime manager for local clients
+        this.realtime = new RelayRealtime({
+            heartbeatIntervalMs: options.heartbeatIntervalMs ?? 30000,
+        });
+        // Initialize forward engine (forwards local commits to main)
+        this.forwardEngine = new ForwardEngine({
+            db: this.db,
+            transport: this.mainServerTransport,
+            clientId: this.mainServerClientId,
+            sequenceMapper: this.sequenceMapper,
+            retryIntervalMs: options.forwardRetryIntervalMs ?? 5000,
+            onConflict: (conflict) => this.emit('forwardConflict', conflict),
+            onError: (error) => this.emit('error', error),
+        });
+        // Initialize pull engine (pulls changes from main)
+        this.pullEngine = new PullEngine({
+            db: this.db,
+            dialect: this.dialect,
+            transport: this.mainServerTransport,
+            clientId: this.mainServerClientId,
+            tables: this.tables,
+            scopes: this.scopes,
+            handlers: this.handlers,
+            sequenceMapper: this.sequenceMapper,
+            realtime: this.realtime,
+            intervalMs: options.pullIntervalMs ?? 10000,
+            onError: (error) => this.emit('error', error),
+            onPullComplete: async () => {
+                await this.maybePruneRelay();
+            },
+        });
+    }
+    /**
+     * Subscribe to relay events.
+     */
+    on(event, handler) {
+        let handlers = this.eventHandlers.get(event);
+        if (!handlers) {
+            handlers = new Set();
+            this.eventHandlers.set(event, handlers);
+        }
+        handlers.add(handler);
+        return () => {
+            handlers?.delete(handler);
+        };
+    }
+    /**
+     * Get the current mode (online/offline/reconnecting).
+     */
+    getMode() {
+        return this.modeManager.getMode();
+    }
+    /**
+     * Get the tables this relay subscribes to.
+     */
+    getTables() {
+        return this.tables;
+    }
+    /**
+     * Get the scope values for subscriptions.
+     */
+    getScopes() {
+        return this.scopes;
+    }
+    /**
+     * Get the realtime manager for WebSocket connections.
+     */
+    getRealtime() {
+        return this.realtime;
+    }
+    /**
+     * Start the relay server background processes.
+     *
+     * This initializes the database schema and starts:
+     * - Forward engine (sends local commits to main)
+     * - Pull engine (receives changes from main)
+     * - Mode manager (tracks online/offline state)
+     */
+    async start() {
+        if (this.started)
+            return;
+        // Initialize schema if needed
+        if (!this.schemaInitialized) {
+            await ensureRelaySchema(this.db, this.dialect);
+            this.schemaInitialized = true;
+        }
+        this.started = true;
+        // Start background processes
+        this.modeManager.start(async () => {
+            // Health check: try an empty pull
+            try {
+                await this.mainServerTransport.sync({
+                    clientId: this.mainServerClientId,
+                    pull: {
+                        schemaVersion: 1,
+                        subscriptions: [],
+                        limitCommits: 1,
+                    },
+                });
+                return true;
+            }
+            catch {
+                return false;
+            }
+        });
+        this.forwardEngine.start();
+        this.pullEngine.start();
+    }
+    /**
+     * Stop the relay server background processes.
+     */
+    async stop() {
+        if (!this.started)
+            return;
+        this.started = false;
+        this.modeManager.stop();
+        this.forwardEngine.stop();
+        this.pullEngine.stop();
+        this.realtime.closeAll();
+    }
+    /**
+     * Manually trigger a forward cycle (useful for testing).
+     */
+    async forwardOnce() {
+        return this.forwardEngine.forwardOnce();
+    }
+    /**
+     * Manually trigger a pull cycle (useful for testing).
+     */
+    async pullOnce() {
+        return this.pullEngine.pullOnce();
+    }
+    /**
+     * Prune old relay data (sequence mappings, forwarded outbox, resolved conflicts).
+     */
+    async pruneRelay(options) {
+        const maxAgeMs = options?.maxAgeMs ?? this.pruneMaxAgeMs;
+        const threshold = Date.now() - maxAgeMs;
+        const deletedMappings = await this.sequenceMapper.pruneOldMappings(maxAgeMs);
+        const outboxResult = await sql `
+      delete from ${sql.table('relay_forward_outbox')}
+      where status in ('forwarded', 'failed')
+      and updated_at < ${threshold}
+    `.execute(this.db);
+        const deletedOutbox = Number(outboxResult.numAffectedRows ?? 0);
+        const conflictsResult = await sql `
+      delete from ${sql.table('relay_forward_conflicts')}
+      where resolved_at is not null
+      and resolved_at < ${threshold}
+    `.execute(this.db);
+        const deletedConflicts = Number(conflictsResult.numAffectedRows ?? 0);
+        return { deletedMappings, deletedOutbox, deletedConflicts };
+    }
+    /**
+     * Rate-limited pruning. Skips if called within `pruneIntervalMs` of last prune.
+     * Returns zero counts if skipped or if pruning is disabled.
+     */
+    async maybePruneRelay() {
+        if (this.pruneIntervalMs <= 0) {
+            return { deletedMappings: 0, deletedOutbox: 0, deletedConflicts: 0 };
+        }
+        const now = Date.now();
+        if (now - this.lastPruneAtMs < this.pruneIntervalMs) {
+            return { deletedMappings: 0, deletedOutbox: 0, deletedConflicts: 0 };
+        }
+        if (this.pruneInFlight)
+            return this.pruneInFlight;
+        this.pruneInFlight = (async () => {
+            try {
+                const result = await this.pruneRelay();
+                this.lastPruneAtMs = Date.now();
+                return result;
+            }
+            finally {
+                this.pruneInFlight = null;
+            }
+        })();
+        return this.pruneInFlight;
+    }
+    /**
+     * Get Hono routes for local clients.
+     *
+     * Mount these routes to serve local sync clients:
+     * - POST /pull
+     * - POST /push
+     * - GET /realtime (WebSocket)
+     */
+    async getRoutes() {
+        if (this.routes)
+            return this.routes;
+        if (this.routesPromise)
+            return this.routesPromise;
+        this.routesPromise = (async () => {
+            const { createRelayRoutes } = await import('./server-role/index.js');
+            const routes = createRelayRoutes({
+                db: this.db,
+                dialect: this.dialect,
+                handlers: this.handlers,
+                realtime: this.realtime,
+                onCommit: async (localCommitSeq, affectedTables) => {
+                    this.realtime.notifyScopeKeys(affectedTables, localCommitSeq);
+                    this.forwardEngine.wakeUp();
+                },
+            });
+            this.routes = routes;
+            this.routesPromise = null;
+            return routes;
+        })();
+        return this.routesPromise;
+    }
+    emit(event, ...args) {
+        const handlers = this.eventHandlers.get(event);
+        if (!handlers)
+            return;
+        for (const handler of handlers) {
+            try {
+                handler(...args);
+            }
+            catch (err) {
+                console.error(`Error in ${event} handler:`, err);
+            }
+        }
+    }
+}
+/**
+ * Create a new relay server instance.
+ */
+export function createRelayServer(options) {
+    return new RelayServer(options);
+}
+//# sourceMappingURL=relay.js.map

package/dist/relay/relay.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay.js","sourceRoot":"","sources":["../../src/relay/relay.ts"],"names":[],"mappings":"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"}

package/dist/relay/schema.d.ts

@@ -0,0 +1,158 @@
+/**
+ * @syncular/server/relay - Database schema types
+ *
+ * Relay-specific tables for edge relay servers.
+ */
+import type { SyncCoreDb } from '@syncular/server';
+import type { Generated } from 'kysely';
+/**
+ * Forward outbox status for commits awaiting forwarding to main server.
+ */
+export type RelayForwardOutboxStatus = 'pending' | 'forwarding' | 'forwarded' | 'failed';
+/**
+ * Sequence map status for tracking local to main commit mapping.
+ */
+export type RelaySequenceMapStatus = 'pending' | 'forwarded' | 'confirmed';
+/**
+ * Forward outbox - Queue for commits to forward to main server.
+ *
+ * When local clients push to the relay, commits are stored here
+ * for subsequent forwarding to the main server.
+ */
+interface RelayForwardOutboxTable {
+    /** Unique identifier for this outbox entry */
+    id: string;
+    /** Local commit sequence assigned by the relay */
+    local_commit_seq: number;
+    /** Original client_id from the local client */
+    client_id: string;
+    /** Original client_commit_id from the local client */
+    client_commit_id: string;
+    /** Operations JSON for forwarding */
+    operations_json: string;
+    /** Client schema version when commit was created */
+    schema_version: number;
+    /** Current status of this entry */
+    status: RelayForwardOutboxStatus;
+    /** Main server's commit_seq after forwarding (null until confirmed) */
+    main_commit_seq: number | null;
+    /** Error message if status is 'failed' */
+    error: string | null;
+    /** Last response JSON from main server */
+    last_response_json: string | null;
+    /** Creation timestamp */
+    created_at: Generated<number>;
+    /** Last update timestamp */
+    updated_at: Generated<number>;
+    /** Number of forward attempts */
+    attempt_count: Generated<number>;
+}
+/**
+ * Sequence map - Maps local to main commit sequences.
+ *
+ * Tracks the relationship between relay's local commit_seq
+ * and the main server's global commit_seq.
+ */
+interface RelaySequenceMapTable {
+    /** Relay's local commit sequence */
+    local_commit_seq: number;
+    /** Main server's commit sequence (null if not yet forwarded) */
+    main_commit_seq: number | null;
+    /** Mapping status */
+    status: RelaySequenceMapStatus;
+    /** When this mapping was created */
+    created_at: Generated<number>;
+    /** When this mapping was last updated */
+    updated_at: Generated<number>;
+}
+/**
+ * Forward conflicts - Conflicts encountered when forwarding to main.
+ *
+ * When a local commit is rejected by the main server due to conflicts,
+ * the details are stored here for application-level handling.
+ */
+interface RelayForwardConflictTable {
+    /** Unique identifier */
+    id: string;
+    /** Local commit sequence that caused the conflict */
+    local_commit_seq: number;
+    /** Original client_id from the local client */
+    client_id: string;
+    /** Original client_commit_id from the local client */
+    client_commit_id: string;
+    /** Full rejection response from main server */
+    response_json: string;
+    /** When the conflict was recorded */
+    created_at: number;
+    /** When the conflict was resolved (null if unresolved) */
+    resolved_at: number | null;
+}
+/**
+ * Relay config - Key-value store for relay state.
+ *
+ * Stores configuration and runtime state like:
+ * - scope_keys: subscribed scopes
+ * - main_cursor: last pulled commit_seq from main server
+ * - mode: online/offline/reconnecting
+ */
+interface RelayConfigTable {
+    /** Configuration key */
+    key: string;
+    /** JSON-encoded value */
+    value_json: string;
+}
+/**
+ * Database interface for relay-specific tables.
+ * Merge this with SyncCoreDb for the full database interface.
+ */
+export interface RelayDb {
+    relay_forward_outbox: RelayForwardOutboxTable;
+    relay_sequence_map: RelaySequenceMapTable;
+    relay_forward_conflicts: RelayForwardConflictTable;
+    relay_config: RelayConfigTable;
+}
+/**
+ * Full database interface required by the relay runtime.
+ *
+ * Includes:
+ * - Sync core tables (commit log, cursors, etc.)
+ * - Relay-specific tables (outbox, sequence map, config, conflicts)
+ */
+export type RelayDatabase = SyncCoreDb & RelayDb;
+/**
+ * Forward outbox entry (with parsed operations).
+ */
+export interface ForwardOutboxEntry {
+    id: string;
+    local_commit_seq: number;
+    client_id: string;
+    client_commit_id: string;
+    operations: Array<{
+        table: string;
+        row_id: string;
+        op: 'upsert' | 'delete';
+        payload: Record<string, unknown> | null;
+        base_version?: number | null;
+    }>;
+    schema_version: number;
+    status: RelayForwardOutboxStatus;
+    main_commit_seq: number | null;
+    error: string | null;
+    created_at: number;
+    updated_at: number;
+    attempt_count: number;
+}
+/**
+ * Forward conflict entry (with parsed response).
+ */
+export interface ForwardConflictEntry {
+    id: string;
+    local_commit_seq: number;
+    client_id: string;
+    client_commit_id: string;
+    response: unknown;
+    created_at: number;
+    resolved_at: number | null;
+}
+export {};
+//# sourceMappingURL=schema.d.ts.map

package/dist/relay/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/relay/schema.ts"],"names":[],"mappings":"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"}

package/dist/relay/schema.js

@@ -0,0 +1,7 @@
+/**
+ * @syncular/server/relay - Database schema types
+ *
+ * Relay-specific tables for edge relay servers.
+ */
+export {};
+//# sourceMappingURL=schema.js.map

package/dist/relay/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/relay/schema.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/relay/server-role/index.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @syncular/server/relay - Server Role
+ *
+ * Hono routes for serving local clients.
+ */
+import type { ServerHandlerCollection, ServerSyncDialect, SyncServerAuth } from '@syncular/server';
+import type { Context } from 'hono';
+import { Hono } from 'hono';
+import type { Kysely } from 'kysely';
+import type { RelayRealtime } from '../realtime';
+import type { RelayDatabase } from '../schema';
+type RelayAuth = SyncServerAuth;
+/**
+ * Options for creating relay routes.
+ */
+export interface CreateRelayRoutesOptions<DB extends RelayDatabase = RelayDatabase> {
+    db: Kysely<DB>;
+    dialect: ServerSyncDialect;
+    handlers: ServerHandlerCollection<DB, RelayAuth>;
+    realtime: RelayRealtime;
+    /**
+     * Called after a commit is successfully applied locally.
+     * Use this to trigger forwarding and notify local clients.
+     */
+    onCommit?: (localCommitSeq: number, affectedTables: string[]) => Promise<void>;
+    /**
+     * Optional: authenticate requests. Return actor ID or null for unauthorized.
+     * If not provided, all requests are allowed with actor ID 'anonymous'.
+     */
+    authenticate?: (c: Context) => Promise<{
+        actorId: string;
+    } | null>;
+    /**
+     * Max operations per pushed commit (default: 200).
+     */
+    maxOperationsPerPush?: number;
+    /**
+     * Max subscriptions per pull request (default: 200).
+     */
+    maxSubscriptionsPerPull?: number;
+    /**
+     * Max commits per pull request (default: 100).
+     */
+    maxPullLimitCommits?: number;
+}
+/**
+ * Create Hono routes for relay server-role endpoints.
+ *
+ * Provides:
+ * - POST /pull (commit stream + optional bootstrap snapshots)
+ * - POST /push (commit ingestion)
+ * - GET /realtime (WebSocket wake-up notifications)
+ */
+export declare function createRelayRoutes<DB extends RelayDatabase = RelayDatabase>(options: CreateRelayRoutesOptions<DB>): Hono;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/relay/server-role/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/relay/server-role/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAaH,OAAO,KAAK,EACV,uBAAuB,EACvB,iBAAiB,EACjB,cAAc,EACf,MAAM,kBAAkB,CAAC;AAE1B,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AACpC,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC5B,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AACrC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAI/C,KAAK,SAAS,GAAG,cAAc,CAAC;AAEhC;;GAEG;AACH,MAAM,WAAW,wBAAwB,CACvC,EAAE,SAAS,aAAa,GAAG,aAAa;IAExC,EAAE,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;IACf,OAAO,EAAE,iBAAiB,CAAC;IAC3B,QAAQ,EAAE,uBAAuB,CAAC,EAAE,EAAE,SAAS,CAAC,CAAC;IACjD,QAAQ,EAAE,aAAa,CAAC;IACxB;;;OAGG;IACH,QAAQ,CAAC,EAAE,CACT,cAAc,EAAE,MAAM,EACtB,cAAc,EAAE,MAAM,EAAE,KACrB,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB;;;OAGG;IACH,YAAY,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC,CAAC;IACnE;;OAEG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B;;OAEG;IACH,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC;;OAEG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAiCD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,SAAS,aAAa,GAAG,aAAa,EACxE,OAAO,EAAE,wBAAwB,CAAC,EAAE,CAAC,GACpC,IAAI,CAkON"}