@syncular/server 0.1.3 → 0.2.0

package/src/realtime/in-memory.ts

@@ -1,33 +0,0 @@
-import type { SyncRealtimeBroadcaster, SyncRealtimeEvent } from './types';
-
-/**
- * In-memory broadcaster for tests and single-process setups.
- *
- * This simulates multi-instance fanout when shared across "instances" in a test.
- */
-export class InMemorySyncRealtimeBroadcaster
-  implements SyncRealtimeBroadcaster
-{
-  private handlers = new Set<(event: SyncRealtimeEvent) => void>();
-
-  subscribe(handler: (event: SyncRealtimeEvent) => void): () => void {
-    this.handlers.add(handler);
-    return () => {
-      this.handlers.delete(handler);
-    };
-  }
-
-  async publish(event: SyncRealtimeEvent): Promise<void> {
-    for (const handler of this.handlers) {
-      try {
-        handler(event);
-      } catch {
-        // ignore individual handler errors; realtime is best-effort
-      }
-    }
-  }
-
-  async close(): Promise<void> {
-    this.handlers.clear();
-  }
-}

package/src/realtime/index.ts

@@ -1,7 +0,0 @@
-export { InMemorySyncRealtimeBroadcaster } from './in-memory';
-export type {
-  SyncRealtimeBroadcaster,
-  SyncRealtimeEvent,
-  SyncRealtimeShardKeyInput,
-} from './types';
-export { createSyncRealtimeShardKey } from './types';

package/src/realtime/types.ts

@@ -1,90 +0,0 @@
-/**
- * @syncular/server - Realtime broadcaster types
- *
- * Realtime is a best-effort "wake up" mechanism. Correctness always comes from pull + cursors.
- */
-
-export interface SyncRealtimeCommitEvent {
-  type: 'commit';
-  commitSeq: number;
-  /** Stable sequencer/fanout shard key. */
-  shardKey?: string;
-  /** Logical partition key (tenant / demo / workspace). */
-  partitionId?: string;
-  /**
-   * Optional scopes affected by the commit.
-   * Broadcasters may omit this to keep payloads small (listeners can look up in DB).
-   */
-  scopeKeys?: string[];
-  /** Optional instance id to suppress echo on the originating instance. */
-  sourceInstanceId?: string;
-}
-
-/**
- * Presence event for tracking which clients are connected to which scopes.
- * Used for collaborative features like "who's online" indicators.
- */
-export interface SyncRealtimePresenceEvent {
-  type: 'presence';
-  /** Stable sequencer/fanout shard key. */
-  shardKey?: string;
-  /** The action that occurred */
-  action: 'join' | 'leave' | 'update';
-  /** The scope key this presence event relates to */
-  scopeKey: string;
-  /** Stable owner identity, when the publisher tracks one. */
-  ownerKey?: string;
-  /** Client/device identifier */
-  clientId: string;
-  /** Actor/user identifier */
-  actorId: string;
-  /** Optional metadata (e.g., entity being viewed/edited) */
-  metadata?: Record<string, unknown>;
-  /** Optional instance id to suppress echo on the originating instance. */
-  sourceInstanceId?: string;
-}
-
-export type SyncRealtimeEvent =
-  | SyncRealtimeCommitEvent
-  | SyncRealtimePresenceEvent;
-
-export interface SyncRealtimeBroadcaster {
-  /** Publish an event to other app instances. */
-  publish(event: SyncRealtimeEvent): Promise<void>;
-  /**
-   * Subscribe to events from other app instances.
-   * Returns an unsubscribe function.
-   */
-  subscribe(handler: (event: SyncRealtimeEvent) => void): () => void;
-  /** Close underlying resources (best-effort). */
-  close(): Promise<void>;
-}
-
-export interface SyncRealtimeShardKeyInput {
-  tenantId?: string | null;
-  workspaceId?: string | null;
-  partitionId?: string | null;
-}
-
-export function createSyncRealtimeShardKey(
-  input: SyncRealtimeShardKeyInput = {}
-): string {
-  const partitionId = normalizeShardPart(input.partitionId, 'default');
-  const tenantId = normalizeShardPart(input.tenantId, partitionId);
-  const workspaceId = normalizeShardPart(input.workspaceId, partitionId);
-  return `sync-realtime-v1:${encodeShardPart(tenantId)}:${encodeShardPart(
-    workspaceId
-  )}:${encodeShardPart(partitionId)}`;
-}
-
-function normalizeShardPart(
-  value: string | null | undefined,
-  fallback: string
-): string {
-  const normalized = value?.trim();
-  return normalized && normalized.length > 0 ? normalized : fallback;
-}
-
-function encodeShardPart(value: string): string {
-  return encodeURIComponent(value);
-}

package/src/relay/bun-types.d.ts

@@ -1,50 +0,0 @@
-// Type declarations for bun modules when running tsgo
-declare module 'bun:sqlite' {
-  export default class Database {
-    constructor(path: string);
-    close(): void;
-    exec(sql: string): void;
-    query<T = unknown>(sql: string): Statement<T>;
-    prepare<T = unknown>(sql: string): Statement<T>;
-    transaction<T>(fn: () => T): () => T;
-  }
-
-  export class Statement<T = unknown> {
-    run(
-      ...params: unknown[]
-    ): { changes: number; lastInsertRowid: number | bigint | null };
-    get(...params: unknown[]): T | null;
-    all(...params: unknown[]): T[];
-    values(...params: unknown[]): unknown[][];
-    finalize(): void;
-  }
-}
-
-declare module 'bun:test' {
-  export function describe(name: string, fn: () => void): void;
-  export function it(name: string, fn: () => void | Promise<void>): void;
-  export function test(name: string, fn: () => void | Promise<void>): void;
-  export function beforeEach(fn: () => void | Promise<void>): void;
-  export function afterEach(fn: () => void | Promise<void>): void;
-  export function beforeAll(fn: () => void | Promise<void>): void;
-  export function afterAll(fn: () => void | Promise<void>): void;
-  export function expect<T>(value: T): Matchers<T>;
-
-  interface Matchers<T> {
-    toBe(expected: unknown): void;
-    toEqual(expected: unknown): void;
-    toBeTruthy(): void;
-    toBeFalsy(): void;
-    toBeNull(): void;
-    toBeUndefined(): void;
-    toBeDefined(): void;
-    toBeGreaterThan(expected: number): void;
-    toBeGreaterThanOrEqual(expected: number): void;
-    toBeLessThan(expected: number): void;
-    toBeLessThanOrEqual(expected: number): void;
-    toContain(expected: unknown): void;
-    toHaveLength(expected: number): void;
-    toThrow(expected?: string | RegExp | Error): void;
-    not: Matchers<T>;
-  }
-}

package/src/relay/client-role/forward-engine.ts

@@ -1,355 +0,0 @@
-/**
- * @syncular/server/relay - Forward Engine
- *
- * Forwards commits from the relay's local outbox to the main server.
- * Preserves original client_id + client_commit_id for idempotency.
- */
-
-import type {
-  SyncOperation,
-  SyncPushResponse,
-  SyncTransport,
-} from '@syncular/core';
-import { randomId } from '@syncular/core';
-import type { Kysely } from 'kysely';
-import { sql } from 'kysely';
-import type {
-  ForwardConflictEntry,
-  ForwardOutboxEntry,
-  RelayDatabase,
-  RelayForwardOutboxStatus,
-} from '../schema';
-import type { SequenceMapper } from './sequence-mapper';
-
-/**
- * Forward engine options.
- */
-export interface ForwardEngineOptions<
-  DB extends RelayDatabase = RelayDatabase,
-> {
-  db: Kysely<DB>;
-  transport: SyncTransport;
-  clientId: string;
-  sequenceMapper: SequenceMapper<DB>;
-  retryIntervalMs?: number;
-  onConflict?: (conflict: ForwardConflictEntry) => void;
-  onError?: (error: Error) => void;
-}
-
-/**
- * Forward engine for sending local commits to the main server.
- */
-export class ForwardEngine<DB extends RelayDatabase = RelayDatabase> {
-  private readonly db: Kysely<DB>;
-  private readonly transport: SyncTransport;
-  private readonly clientId: string;
-  private readonly sequenceMapper: SequenceMapper<DB>;
-  private readonly retryIntervalMs: number;
-  private readonly onConflict?: (conflict: ForwardConflictEntry) => void;
-  private readonly onError?: (error: Error) => void;
-
-  private running = false;
-  private timer: ReturnType<typeof setTimeout> | null = null;
-  // biome-ignore lint/correctness/noUnusedPrivateClassMembers: assigned in scheduleWakeUp and read in tick
-  private wakeUpRequested = false;
-
-  constructor(options: ForwardEngineOptions<DB>) {
-    this.db = options.db;
-    this.transport = options.transport;
-    this.clientId = options.clientId;
-    this.sequenceMapper = options.sequenceMapper;
-    this.retryIntervalMs = options.retryIntervalMs ?? 5000;
-    this.onConflict = options.onConflict;
-    this.onError = options.onError;
-  }
-
-  /**
-   * Start the forward engine loop.
-   */
-  start(): void {
-    if (this.running) return;
-    this.running = true;
-    this.scheduleNext(0);
-  }
-
-  /**
-   * Stop the forward engine.
-   */
-  stop(): void {
-    this.running = false;
-    if (this.timer) {
-      clearTimeout(this.timer);
-      this.timer = null;
-    }
-  }
-
-  /**
-   * Wake up the engine to process immediately.
-   */
-  wakeUp(): void {
-    if (!this.running) return;
-    this.wakeUpRequested = true;
-    if (this.timer) {
-      clearTimeout(this.timer);
-      this.timer = null;
-    }
-    this.scheduleNext(0);
-  }
-
-  /**
-   * Forward a single commit (for manual/testing use).
-   */
-  async forwardOnce(): Promise<boolean> {
-    return this.processOne();
-  }
-
-  private scheduleNext(delayMs: number): void {
-    if (!this.running) return;
-    if (this.timer) return;
-
-    this.timer = setTimeout(async () => {
-      this.timer = null;
-      this.wakeUpRequested = false;
-
-      try {
-        const forwarded = await this.processOne();
-        // If we forwarded something, immediately try again
-        const nextDelay = forwarded ? 0 : this.retryIntervalMs;
-        this.scheduleNext(nextDelay);
-      } catch (err) {
-        this.onError?.(err instanceof Error ? err : new Error(String(err)));
-        this.scheduleNext(this.retryIntervalMs);
-      }
-    }, delayMs);
-  }
-
-  private async processOne(): Promise<boolean> {
-    const next = await this.getNextSendable();
-    if (!next) return false;
-
-    await this.markSending(next.id);
-
-    let response: SyncPushResponse;
-    try {
-      const combined = await this.transport.sync({
-        clientId: next.client_id,
-        push: {
-          commits: [
-            {
-              clientCommitId: next.client_commit_id,
-              operations: next.operations,
-              schemaVersion: next.schema_version,
-            },
-          ],
-        },
-      });
-      const batchResponse = combined.push?.commits.find(
-        (commit) => commit.clientCommitId === next.client_commit_id
-      );
-      if (!batchResponse) {
-        throw new Error('Server returned no push response');
-      }
-      response = {
-        ok: true,
-        status: batchResponse.status,
-        commitSeq: batchResponse.commitSeq,
-        results: batchResponse.results,
-      };
-    } catch (err) {
-      // Network error - mark as pending for retry
-      await this.markPending(next.id, String(err));
-      throw err;
-    }
-
-    const responseJson = JSON.stringify(response);
-
-    if (response.status === 'applied' || response.status === 'cached') {
-      const mainCommitSeq = response.commitSeq ?? null;
-
-      // Update outbox entry
-      await this.markForwarded(next.id, mainCommitSeq, responseJson);
-
-      // Update sequence mapper
-      if (mainCommitSeq != null) {
-        await this.sequenceMapper.markForwarded(
-          next.local_commit_seq,
-          mainCommitSeq
-        );
-      }
-
-      return true;
-    }
-
-    // Rejected - store conflict and mark as failed
-    const conflict = await this.recordConflict(next, responseJson);
-    await this.markFailed(next.id, 'REJECTED', responseJson);
-
-    this.onConflict?.(conflict);
-
-    return true;
-  }
-
-  private async getNextSendable(): Promise<ForwardOutboxEntry | null> {
-    const staleThreshold = Date.now() - 30000;
-
-    const rowResult = await sql<{
-      id: string;
-      local_commit_seq: number;
-      client_id: string;
-      client_commit_id: string;
-      operations_json: string;
-      schema_version: number;
-      status: RelayForwardOutboxStatus;
-      main_commit_seq: number | null;
-      error: string | null;
-      last_response_json: string | null;
-      created_at: number;
-      updated_at: number;
-      attempt_count: number;
-    }>`
-      select
-        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
-      from ${sql.table('relay_forward_outbox')}
-      where
-        status = 'pending'
-        or (status = 'forwarding' and updated_at < ${staleThreshold})
-      order by created_at asc
-      limit 1
-    `.execute(this.db);
-    const row = rowResult.rows[0];
-
-    if (!row) return null;
-
-    const operations =
-      typeof row.operations_json === 'string'
-        ? (JSON.parse(row.operations_json) as SyncOperation[])
-        : (row.operations_json as SyncOperation[]);
-
-    return {
-      id: row.id,
-      local_commit_seq: row.local_commit_seq,
-      client_id: row.client_id,
-      client_commit_id: row.client_commit_id,
-      operations,
-      schema_version: row.schema_version,
-      status: row.status,
-      main_commit_seq: row.main_commit_seq,
-      error: row.error,
-      created_at: row.created_at,
-      updated_at: row.updated_at,
-      attempt_count: row.attempt_count,
-    };
-  }
-
-  private async markSending(id: string): Promise<void> {
-    const now = Date.now();
-
-    await sql`
-      update ${sql.table('relay_forward_outbox')}
-      set
-        status = 'forwarding',
-        updated_at = ${now},
-        attempt_count = attempt_count + 1,
-        error = ${null}
-      where id = ${id}
-    `.execute(this.db);
-  }
-
-  private async markPending(id: string, error: string): Promise<void> {
-    const now = Date.now();
-
-    await sql`
-      update ${sql.table('relay_forward_outbox')}
-      set status = 'pending', updated_at = ${now}, error = ${error}
-      where id = ${id}
-    `.execute(this.db);
-  }
-
-  private async markForwarded(
-    id: string,
-    mainCommitSeq: number | null,
-    responseJson: string
-  ): Promise<void> {
-    const now = Date.now();
-
-    await sql`
-      update ${sql.table('relay_forward_outbox')}
-      set
-        status = 'forwarded',
-        main_commit_seq = ${mainCommitSeq},
-        updated_at = ${now},
-        error = ${null},
-        last_response_json = ${responseJson}
-      where id = ${id}
-    `.execute(this.db);
-  }
-
-  private async markFailed(
-    id: string,
-    error: string,
-    responseJson: string
-  ): Promise<void> {
-    const now = Date.now();
-
-    await sql`
-      update ${sql.table('relay_forward_outbox')}
-      set
-        status = 'failed',
-        updated_at = ${now},
-        error = ${error},
-        last_response_json = ${responseJson}
-      where id = ${id}
-    `.execute(this.db);
-  }
-
-  private async recordConflict(
-    entry: ForwardOutboxEntry,
-    responseJson: string
-  ): Promise<ForwardConflictEntry> {
-    const now = Date.now();
-    const id = randomId();
-
-    await sql`
-      insert into ${sql.table('relay_forward_conflicts')} (
-        id,
-        local_commit_seq,
-        client_id,
-        client_commit_id,
-        response_json,
-        created_at,
-        resolved_at
-      )
-      values (
-        ${id},
-        ${entry.local_commit_seq},
-        ${entry.client_id},
-        ${entry.client_commit_id},
-        ${responseJson},
-        ${now},
-        ${null}
-      )
-    `.execute(this.db);
-
-    return {
-      id,
-      local_commit_seq: entry.local_commit_seq,
-      client_id: entry.client_id,
-      client_commit_id: entry.client_commit_id,
-      response: JSON.parse(responseJson),
-      created_at: now,
-      resolved_at: null,
-    };
-  }
-}

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

@@ -1,9 +0,0 @@
-/**
- * @syncular/server/relay - Client Role
- *
- * Components for the relay's role as a client to the main server.
- */
-
-export * from './forward-engine';
-export * from './pull-engine';
-export * from './sequence-mapper';