@syncular/server 0.1.3 → 0.2.0

package/src/relay/server-role/index.ts

@@ -1,338 +0,0 @@
-/**
- * @syncular/server/relay - Server Role
- *
- * Hono routes for serving local clients.
- */
-
-import type { SyncPullRequest, SyncPushRequest } from '@syncular/core';
-import {
-  createSyncTimer,
-  createSyncularErrorResponse,
-  isRecord,
-  logSyncEvent,
-  ScopeValuesSchema,
-  SyncBootstrapStateSchema,
-  SyncPullRequestSchema,
-  SyncPushRequestSchema,
-} from '@syncular/core';
-import type {
-  ServerHandlerCollection,
-  ServerSyncDialect,
-  SyncServerAuth,
-} from '@syncular/server';
-import { recordClientCursor } 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';
-import { relayPull } from './pull';
-import { relayPushCommit } from './push';
-
-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;
-}
-
-function clampInt(value: number, min: number, max: number): number {
-  return Math.max(min, Math.min(max, value));
-}
-
-function relayError(
-  c: Context,
-  status: 400 | 401,
-  code:
-    | 'sync.auth_required'
-    | 'sync.invalid_request'
-    | 'sync.too_many_operations',
-  message?: string,
-  details?: Record<string, unknown>
-): Response {
-  return c.json(
-    createSyncularErrorResponse(code, {
-      ...(message ? { message } : {}),
-      ...(details ? { details } : {}),
-    }),
-    status
-  );
-}
-
-function invalidRelayRequest(
-  c: Context,
-  message: string,
-  details?: Record<string, unknown>
-): Response {
-  return relayError(c, 400, 'sync.invalid_request', message, details);
-}
-
-/**
- * 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 function createRelayRoutes<DB extends RelayDatabase = RelayDatabase>(
-  options: CreateRelayRoutesOptions<DB>
-): Hono {
-  const routes = new Hono();
-  const maxOperationsPerPush = options.maxOperationsPerPush ?? 200;
-  const maxSubscriptionsPerPull = options.maxSubscriptionsPerPull ?? 200;
-  const maxPullLimitCommits = options.maxPullLimitCommits ?? 100;
-
-  const authenticate =
-    options.authenticate ?? (async () => ({ actorId: 'anonymous' }));
-
-  // POST /pull
-  routes.post('/pull', async (c) => {
-    const auth = await authenticate(c);
-    if (!auth) return relayError(c, 401, 'sync.auth_required');
-
-    const rawBody: unknown = await c.req.json();
-    const timer = createSyncTimer();
-
-    if (!isRecord(rawBody)) {
-      return invalidRelayRequest(c, 'Invalid JSON body');
-    }
-
-    if (!rawBody.clientId || typeof rawBody.clientId !== 'string') {
-      return invalidRelayRequest(c, 'clientId is required');
-    }
-
-    if (!Array.isArray(rawBody.subscriptions)) {
-      return invalidRelayRequest(c, 'subscriptions array is required');
-    }
-
-    if (rawBody.subscriptions.length > maxSubscriptionsPerPull) {
-      return invalidRelayRequest(
-        c,
-        `Too many subscriptions (max ${maxSubscriptionsPerPull})`
-      );
-    }
-
-    const subscriptions: SyncPullRequest['subscriptions'] = [];
-    for (const subValue of rawBody.subscriptions) {
-      if (!isRecord(subValue)) {
-        return invalidRelayRequest(c, 'Invalid subscription entry');
-      }
-
-      const id = typeof subValue.id === 'string' ? subValue.id : null;
-      const table = typeof subValue.table === 'string' ? subValue.table : null;
-      if (!id || !table) {
-        return invalidRelayRequest(c, 'Subscription id/table required');
-      }
-
-      const scopesParsed = ScopeValuesSchema.safeParse(subValue.scopes);
-      if (!scopesParsed.success) {
-        return invalidRelayRequest(c, 'Invalid subscription scopes');
-      }
-
-      const rawParams = subValue.params;
-      if (rawParams !== undefined && !isRecord(rawParams)) {
-        return invalidRelayRequest(c, 'Invalid subscription params');
-      }
-
-      const cursor =
-        typeof subValue.cursor === 'number' && Number.isInteger(subValue.cursor)
-          ? Math.max(-1, subValue.cursor)
-          : -1;
-
-      const rawBootstrapState = subValue.bootstrapState;
-      const bootstrapState =
-        rawBootstrapState === undefined || rawBootstrapState === null
-          ? null
-          : (() => {
-              const parsed =
-                SyncBootstrapStateSchema.safeParse(rawBootstrapState);
-              if (!parsed.success) return null;
-              return parsed.data;
-            })();
-
-      if (
-        rawBootstrapState !== undefined &&
-        rawBootstrapState !== null &&
-        bootstrapState === null
-      ) {
-        return invalidRelayRequest(c, 'Invalid subscription bootstrapState');
-      }
-
-      subscriptions.push({
-        id,
-        table,
-        scopes: scopesParsed.data,
-        params: rawParams,
-        cursor,
-        bootstrapState,
-        crdtStateVectors: [],
-      });
-    }
-
-    const request: SyncPullRequest = {
-      clientId: rawBody.clientId,
-      schemaVersion:
-        typeof rawBody.schemaVersion === 'number' &&
-        Number.isInteger(rawBody.schemaVersion)
-          ? rawBody.schemaVersion
-          : Number.NaN,
-      limitCommits: clampInt(
-        typeof rawBody.limitCommits === 'number' &&
-          Number.isInteger(rawBody.limitCommits)
-          ? rawBody.limitCommits
-          : 50,
-        1,
-        maxPullLimitCommits
-      ),
-      limitSnapshotRows: clampInt(
-        typeof rawBody.limitSnapshotRows === 'number' &&
-          Number.isInteger(rawBody.limitSnapshotRows)
-          ? rawBody.limitSnapshotRows
-          : 1000,
-        1,
-        5000
-      ),
-      maxSnapshotPages: clampInt(
-        typeof rawBody.maxSnapshotPages === 'number' &&
-          Number.isInteger(rawBody.maxSnapshotPages)
-          ? rawBody.maxSnapshotPages
-          : 4,
-        1,
-        10
-      ),
-      dedupeRows:
-        typeof rawBody.dedupeRows === 'boolean'
-          ? rawBody.dedupeRows
-          : undefined,
-      subscriptions,
-    };
-
-    const validatedRequest = SyncPullRequestSchema.safeParse(request);
-    if (!validatedRequest.success) {
-      return invalidRelayRequest(c, 'Invalid pull request');
-    }
-
-    const pullResult = await relayPull({
-      db: options.db,
-      dialect: options.dialect,
-      handlers: options.handlers,
-      auth,
-      request: validatedRequest.data,
-    });
-
-    await recordClientCursor(options.db, options.dialect, {
-      clientId: validatedRequest.data.clientId,
-      actorId: auth.actorId,
-      cursor: pullResult.clientCursor,
-      effectiveScopes: pullResult.effectiveScopes,
-    });
-
-    // Notify realtime about updated scope values
-    options.realtime.updateClientScopeKeys(
-      request.clientId,
-      Object.keys(pullResult.effectiveScopes)
-    );
-
-    logSyncEvent({
-      event: 'relay.pull',
-      userId: auth.actorId,
-      durationMs: timer(),
-      subscriptionCount: pullResult.response.subscriptions.length,
-      clientCursor: pullResult.clientCursor,
-    });
-
-    return c.json(pullResult.response);
-  });
-
-  // POST /push
-  routes.post('/push', async (c) => {
-    const auth = await authenticate(c);
-    if (!auth) return relayError(c, 401, 'sync.auth_required');
-
-    const rawBody: unknown = await c.req.json();
-    const parsed = SyncPushRequestSchema.safeParse(rawBody);
-    if (!parsed.success) {
-      return invalidRelayRequest(c, 'Invalid push request');
-    }
-
-    const body: SyncPushRequest = parsed.data;
-
-    if (body.operations.length > maxOperationsPerPush) {
-      return relayError(
-        c,
-        400,
-        'sync.too_many_operations',
-        `Maximum ${maxOperationsPerPush} operations per push`
-      );
-    }
-
-    const timer = createSyncTimer();
-
-    const pushed = await relayPushCommit({
-      db: options.db,
-      dialect: options.dialect,
-      handlers: options.handlers,
-      auth,
-      request: body,
-    });
-
-    logSyncEvent({
-      event: 'relay.push',
-      userId: auth.actorId,
-      durationMs: timer(),
-      operationCount: body.operations.length,
-      status: pushed.response.status,
-      commitSeq: pushed.response.commitSeq,
-    });
-
-    // Notify about the commit
-    if (
-      pushed.response.ok === true &&
-      pushed.response.status === 'applied' &&
-      typeof pushed.response.commitSeq === 'number' &&
-      pushed.affectedTables.length > 0
-    ) {
-      await options.onCommit?.(
-        pushed.response.commitSeq,
-        pushed.affectedTables
-      );
-    }
-
-    return c.json(pushed.response);
-  });
-
-  return routes;
-}

package/src/relay/server-role/pull.ts

@@ -1,43 +0,0 @@
-/**
- * @syncular/server/relay - Server Role Pull Handler
- *
- * Handles pulls from local clients, serving changes stored locally
- * on the relay.
- */
-
-import type { SyncPullRequest } from '@syncular/core';
-import type {
-  ServerHandlerCollection,
-  ServerSyncDialect,
-  SyncServerAuth,
-} from '@syncular/server';
-import { type PullResult, pull } from '@syncular/server';
-import type { Kysely } from 'kysely';
-import type { RelayDatabase } from '../schema';
-
-type RelayAuth = SyncServerAuth;
-
-/**
- * Pull commits for a local client from the relay.
- *
- * This wraps the standard server pull with relay-specific logic:
- * - Restricts scopes to those the relay subscribes to
- */
-export async function relayPull<
-  DB extends RelayDatabase = RelayDatabase,
->(args: {
-  db: Kysely<DB>;
-  dialect: ServerSyncDialect;
-  handlers: ServerHandlerCollection<DB, RelayAuth>;
-  auth: RelayAuth;
-  request: SyncPullRequest;
-}): Promise<PullResult> {
-  // Use the standard pull - scope authorization is handled by handlers
-  return pull({
-    db: args.db,
-    dialect: args.dialect,
-    handlers: args.handlers,
-    auth: args.auth,
-    request: args.request,
-  });
-}

package/src/relay/server-role/push.ts

@@ -1,164 +0,0 @@
-/**
- * @syncular/server/relay - Server Role Push Handler
- *
- * Handles pushes from local clients, storing them locally and
- * queueing them for forwarding to the main server.
- */
-
-import type { SyncPushRequest } from '@syncular/core';
-import { randomId } from '@syncular/core';
-import type {
-  ServerHandlerCollection,
-  ServerSyncDialect,
-  SyncServerAuth,
-} from '@syncular/server';
-import { type PushCommitResult, pushCommit } from '@syncular/server';
-import { type Kysely, sql } from 'kysely';
-import type { RelayDatabase } from '../schema';
-
-type RelayAuth = SyncServerAuth;
-
-/**
- * Push a commit from a local client to the relay.
- *
- * This wraps the standard server pushCommit with relay-specific logic:
- * 1. Validates that operations are within the relay's scope
- * 2. Stores the commit locally
- * 3. Enqueues the commit for forwarding to the main server
- */
-export async function relayPushCommit<
-  DB extends RelayDatabase = RelayDatabase,
->(args: {
-  db: Kysely<DB>;
-  dialect: ServerSyncDialect;
-  handlers: ServerHandlerCollection<DB, RelayAuth>;
-  auth: RelayAuth;
-  request: SyncPushRequest;
-}): Promise<PushCommitResult> {
-  const { request } = args;
-
-  return args.db.transaction().execute(async (trx) => {
-    // Use the standard pushCommit - scope authorization is handled by handlers
-    const result = await pushCommit({
-      db: trx,
-      dialect: args.dialect,
-      handlers: args.handlers,
-      auth: args.auth,
-      request,
-    });
-
-    // If the commit was applied, enqueue it for forwarding to main server
-    if (
-      result.response.ok === true &&
-      result.response.status === 'applied' &&
-      typeof result.response.commitSeq === 'number'
-    ) {
-      try {
-        await enqueueForForwarding(trx, {
-          localCommitSeq: result.response.commitSeq,
-          clientId: request.clientId,
-          clientCommitId: request.clientCommitId,
-          operations: request.operations,
-          schemaVersion: request.schemaVersion,
-        });
-      } catch (error) {
-        await rollbackLocalCommit(trx, result.response.commitSeq);
-        throw error;
-      }
-    }
-
-    return result;
-  });
-}
-
-/**
- * Enqueue a locally-committed change for forwarding to the main server.
- */
-async function enqueueForForwarding<DB extends RelayDatabase>(
-  db: Kysely<DB>,
-  args: {
-    localCommitSeq: number;
-    clientId: string;
-    clientCommitId: string;
-    operations: SyncPushRequest['operations'];
-    schemaVersion: number;
-  }
-): Promise<void> {
-  const now = Date.now();
-
-  await sql`
-    insert into ${sql.table('relay_forward_outbox')} (
-      id,
-      local_commit_seq,
-      client_id,
-      client_commit_id,
-      operations_json,
-      schema_version,
-      status,
-      main_commit_seq,
-      error,
-      last_response_json,
-      created_at,
-      updated_at,
-      attempt_count
-    )
-    values (
-      ${randomId()},
-      ${args.localCommitSeq},
-      ${args.clientId},
-      ${args.clientCommitId},
-      ${JSON.stringify(args.operations)},
-      ${args.schemaVersion},
-      'pending',
-      ${null},
-      ${null},
-      ${null},
-      ${now},
-      ${now},
-      ${0}
-    )
-  `.execute(db);
-
-  // Also create a sequence map entry for this commit
-  await sql`
-    insert into ${sql.table('relay_sequence_map')} (
-      local_commit_seq,
-      main_commit_seq,
-      status,
-      created_at,
-      updated_at
-    )
-    values (${args.localCommitSeq}, ${null}, 'pending', ${now}, ${now})
-    on conflict (local_commit_seq) do nothing
-  `.execute(db);
-}
-
-async function rollbackLocalCommit<DB extends RelayDatabase>(
-  db: Kysely<DB>,
-  commitSeq: number
-): Promise<void> {
-  await sql`
-    delete from ${sql.table('relay_sequence_map')}
-    where ${sql.ref('local_commit_seq')} = ${commitSeq}
-  `.execute(db);
-
-  await sql`
-    delete from ${sql.table('relay_forward_outbox')}
-    where ${sql.ref('local_commit_seq')} = ${commitSeq}
-  `.execute(db);
-
-  await sql`
-    delete from ${sql.table('sync_table_commits')}
-    where ${sql.ref('commit_seq')} = ${commitSeq}
-  `.execute(db);
-
-  await sql`
-    delete from ${sql.table('sync_changes')}
-    where ${sql.ref('commit_seq')} = ${commitSeq}
-  `.execute(db);
-
-  await sql`
-    delete from ${sql.table('sync_commits')}
-    where ${sql.ref('commit_seq')} = ${commitSeq}
-  `.execute(db);
-}