@syncular/server 0.1.2 → 0.2.0

package/src/blobs/migrate.ts

@@ -1,158 +0,0 @@
-/**
- * @syncular/server - Blob storage migrations
- *
- * These migrations are separate from core sync migrations because
- * blob storage is optional and may use external storage (S3/R2).
- */
-
-import type { Kysely } from 'kysely';
-import { sql } from 'kysely';
-import type { SyncBlobDb, SyncBlobUploadsDb } from './types';
-
-/**
- * Ensures the blob uploads tracking schema exists.
- * This table is required for the blob manager regardless of storage backend.
- *
- * For PostgreSQL.
- */
-async function ensureBlobUploadsSchemaPostgres<DB extends SyncBlobUploadsDb>(
-  db: Kysely<DB>
-): Promise<void> {
-  await db.schema
-    .createTable('sync_blob_uploads')
-    .ifNotExists()
-    .addColumn('partition_id', 'text', (col) => col.notNull())
-    .addColumn('hash', 'text', (col) => col.notNull())
-    .addColumn('size', 'bigint', (col) => col.notNull())
-    .addColumn('mime_type', 'text', (col) => col.notNull())
-    .addColumn('status', 'text', (col) => col.notNull())
-    .addColumn('actor_id', 'text', (col) => col.notNull())
-    .addColumn('created_at', 'timestamptz', (col) =>
-      col.notNull().defaultTo(sql`now()`)
-    )
-    .addColumn('expires_at', 'timestamptz', (col) => col.notNull())
-    .addColumn('completed_at', 'timestamptz')
-    .addPrimaryKeyConstraint('pk_sync_blob_uploads', ['partition_id', 'hash'])
-    .execute();
-
-  await db.schema
-    .createIndex('idx_sync_blob_uploads_status')
-    .ifNotExists()
-    .on('sync_blob_uploads')
-    .columns(['partition_id', 'status'])
-    .execute();
-
-  await db.schema
-    .createIndex('idx_sync_blob_uploads_expires_at')
-    .ifNotExists()
-    .on('sync_blob_uploads')
-    .columns(['partition_id', 'expires_at'])
-    .execute();
-}
-
-/**
- * Ensures the blob uploads tracking schema exists.
- * This table is required for the blob manager regardless of storage backend.
- *
- * For SQLite.
- */
-async function ensureBlobUploadsSchemasSqlite<DB extends SyncBlobUploadsDb>(
-  db: Kysely<DB>
-): Promise<void> {
-  await db.schema
-    .createTable('sync_blob_uploads')
-    .ifNotExists()
-    .addColumn('partition_id', 'text', (col) => col.notNull())
-    .addColumn('hash', 'text', (col) => col.notNull())
-    .addColumn('size', 'integer', (col) => col.notNull())
-    .addColumn('mime_type', 'text', (col) => col.notNull())
-    .addColumn('status', 'text', (col) => col.notNull())
-    .addColumn('actor_id', 'text', (col) => col.notNull())
-    .addColumn('created_at', 'text', (col) =>
-      col.notNull().defaultTo(sql`(datetime('now'))`)
-    )
-    .addColumn('expires_at', 'text', (col) => col.notNull())
-    .addColumn('completed_at', 'text')
-    .addPrimaryKeyConstraint('pk_sync_blob_uploads', ['partition_id', 'hash'])
-    .execute();
-
-  await db.schema
-    .createIndex('idx_sync_blob_uploads_status')
-    .ifNotExists()
-    .on('sync_blob_uploads')
-    .columns(['partition_id', 'status'])
-    .execute();
-
-  await db.schema
-    .createIndex('idx_sync_blob_uploads_expires_at')
-    .ifNotExists()
-    .on('sync_blob_uploads')
-    .columns(['partition_id', 'expires_at'])
-    .execute();
-}
-
-/**
- * Ensures the blob storage schema exists (for database adapter).
- * Only needed if using the database blob storage adapter.
- *
- * For PostgreSQL.
- */
-export async function ensureBlobStorageSchemaPostgres<DB extends SyncBlobDb>(
-  db: Kysely<DB>
-): Promise<void> {
-  // First ensure uploads table
-  await ensureBlobUploadsSchemaPostgres(db);
-
-  // Then create blobs table
-  await db.schema
-    .createTable('sync_blobs')
-    .ifNotExists()
-    .addColumn('partition_id', 'text', (col) => col.notNull())
-    .addColumn('hash', 'text', (col) => col.notNull())
-    .addColumn('size', 'bigint', (col) => col.notNull())
-    .addColumn('mime_type', 'text', (col) => col.notNull())
-    .addColumn('body', 'bytea', (col) => col.notNull())
-    .addColumn('created_at', 'timestamptz', (col) =>
-      col.notNull().defaultTo(sql`now()`)
-    )
-    .addPrimaryKeyConstraint('pk_sync_blobs', ['partition_id', 'hash'])
-    .execute();
-}
-
-/**
- * Ensures the blob storage schema exists (for database adapter).
- * Only needed if using the database blob storage adapter.
- *
- * For SQLite.
- */
-export async function ensureBlobStorageSchemaSqlite<DB extends SyncBlobDb>(
-  db: Kysely<DB>
-): Promise<void> {
-  // First ensure uploads table
-  await ensureBlobUploadsSchemasSqlite(db);
-
-  // Then create blobs table
-  await db.schema
-    .createTable('sync_blobs')
-    .ifNotExists()
-    .addColumn('partition_id', 'text', (col) => col.notNull())
-    .addColumn('hash', 'text', (col) => col.notNull())
-    .addColumn('size', 'integer', (col) => col.notNull())
-    .addColumn('mime_type', 'text', (col) => col.notNull())
-    .addColumn('body', 'blob', (col) => col.notNull())
-    .addColumn('created_at', 'text', (col) =>
-      col.notNull().defaultTo(sql`(datetime('now'))`)
-    )
-    .addPrimaryKeyConstraint('pk_sync_blobs', ['partition_id', 'hash'])
-    .execute();
-}
-
-/**
- * Drops the blob schema from the database.
- */
-export async function dropBlobSchema<DB extends SyncBlobDb>(
-  db: Kysely<DB>
-): Promise<void> {
-  await db.schema.dropTable('sync_blobs').ifExists().execute();
-  await db.schema.dropTable('sync_blob_uploads').ifExists().execute();
-}

package/src/blobs/types.ts

@@ -1,74 +0,0 @@
-/**
- * @syncular/server - Blob storage types
- */
-
-import type { Generated } from 'kysely';
-
-// ============================================================================
-// Blob Upload Tracking
-// ============================================================================
-
-/**
- * Blob uploads tracking table.
- * Tracks initiated uploads and their completion status.
- */
-export interface SyncBlobUploadsTable {
-  /** Partition/tenant namespace */
-  partition_id: string;
-  /** SHA-256 hash with prefix: "sha256:<hex>" */
-  hash: string;
-  /** Expected size in bytes */
-  size: number;
-  /** MIME type */
-  mime_type: string;
-  /** Upload status */
-  status: 'pending' | 'complete';
-  /** Actor who initiated the upload */
-  actor_id: string;
-  /** When the upload was initiated */
-  created_at: Generated<string>;
-  /** When the upload expires (for cleanup of incomplete uploads) */
-  expires_at: string;
-  /** When the upload was completed */
-  completed_at: string | null;
-}
-
-export interface SyncBlobUploadsDb {
-  sync_blob_uploads: SyncBlobUploadsTable;
-}
-
-// ============================================================================
-// Blob Storage (Database Adapter)
-// ============================================================================
-
-/**
- * Blob storage table (for database adapter).
- * Stores blob content directly in the database.
- */
-export interface SyncBlobsTable {
-  /** Partition/tenant namespace */
-  partition_id: string;
-  /** SHA-256 hash with prefix: "sha256:<hex>" */
-  hash: string;
-  /** Size in bytes */
-  size: number;
-  /** MIME type */
-  mime_type: string;
-  /** Blob content */
-  body: Uint8Array;
-  /** When the blob was created */
-  created_at: Generated<string>;
-}
-
-export interface SyncBlobsDb {
-  sync_blobs: SyncBlobsTable;
-}
-
-// ============================================================================
-// Combined DB Interface
-// ============================================================================
-
-/**
- * Full database interface for blob storage.
- */
-export interface SyncBlobDb extends SyncBlobUploadsDb, SyncBlobsDb {}

package/src/bun-sqlite-ambient.d.ts

@@ -1,19 +0,0 @@
-// Type declarations for bun:sqlite when running tsgo (which doesn't fully support bun-types)
-declare module 'bun:sqlite' {
-  export 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[]): void;
-    get(...params: unknown[]): T | null;
-    all(...params: unknown[]): T[];
-    values(...params: unknown[]): unknown[][];
-    finalize(): void;
-  }
-}

package/src/bun-sqlite.ts

@@ -1,27 +0,0 @@
-/**
- * @syncular/server/bun-sqlite - Bun SQLite dialect for sync
- *
- * Provides a Kysely dialect for bun:sqlite.
- */
-
-import { Database } from 'bun:sqlite';
-import { BunSqliteDialect } from 'kysely-bun-sqlite';
-
-export interface BunSqliteOptions {
-  /** Path to SQLite database file, or ':memory:' for in-memory */
-  path: string;
-}
-
-/**
- * Create the Bun SQLite dialect directly.
- *
- * @example
- * const dialect = createBunSqliteDialect({ path: ':memory:' });
- * const db = new Kysely<MyDb>({ dialect });
- */
-export function createBunSqliteDialect(
-  options: BunSqliteOptions
-): BunSqliteDialect {
-  const database = new Database(options.path);
-  return new BunSqliteDialect({ database });
-}

package/src/clients.ts

@@ -1,22 +0,0 @@
-/**
- * @syncular/server - Client cursor tracking
- */
-
-import type { ScopeValues } from '@syncular/core';
-import type { DbExecutor, ServerSyncDialect } from './dialect/types';
-import type { SyncCoreDb } from './schema';
-
-export async function recordClientCursor<DB extends SyncCoreDb>(
-  db: DbExecutor<DB>,
-  dialect: ServerSyncDialect,
-  args: {
-    partitionId?: string;
-    clientId: string;
-    actorId: string;
-    cursor: number;
-    effectiveScopes: ScopeValues;
-    realtimeSubscriptions?: unknown;
-  }
-): Promise<void> {
-  await dialect.recordClientCursor(db, args);
-}

package/src/cloudflare/durable-object.ts

@@ -1,289 +0,0 @@
-/**
- * @syncular/server/cloudflare - Durable Object handler (WebSocket + polling)
- *
- * Provides a base DurableObject class with Hono routing and WebSocket support.
- * The DO's stateful nature allows it to hold persistent WebSocket connections,
- * bridging Cloudflare's hibernation API to Hono's `upgradeWebSocket` interface.
- *
- * @example
- * ```typescript
- * import { SyncDurableObject, createSyncWorkerWithDO } from '@syncular/server/cloudflare/durable-object';
- * import { createD1Dialect } from '@syncular/server/d1';
- * import { createSqliteServerDialect } from '@syncular/server/sqlite';
- * import { ensureSyncSchema } from '@syncular/server';
- * import { createSyncServer } from '@syncular/server/hono';
- *
- * type Env = { DB: D1Database; SYNC_DO: DurableObjectNamespace };
- *
- * export class SyncDO extends SyncDurableObject<Env> {
- *   setup(app, env, upgradeWebSocket) {
- *     const db = createD1Dialect(env.DB);
- *     const dialect = createSqliteServerDialect();
- *     const { syncRoutes, consoleRoutes } = createSyncServer({
- *       db, dialect,
- *       sync: {
- *         handlers: [tasksHandler],
- *         authenticate: async (request) => ({
- *           actorId: request.headers.get('x-user-id')!,
- *         }),
- *       },
- *       upgradeWebSocket,
- *     });
- *     app.route('/sync', syncRoutes);
- *     if (consoleRoutes) app.route('/console', consoleRoutes);
- *   }
- * }
- *
- * // Worker entry — routes all requests to the DO
- * export default createSyncWorkerWithDO<Env>('SYNC_DO');
- * ```
- */
-
-import { Hono } from 'hono';
-import type { UpgradeWebSocket, WSEvents } from 'hono/ws';
-import { defineWebSocketHelper, WSContext } from 'hono/ws';
-
-// ---------------------------------------------------------------------------
-// WebSocket ↔ Hono bridge
-// ---------------------------------------------------------------------------
-
-interface WebSocketTag {
-  events: WSEvents<WebSocket>;
-}
-
-const STALE_SOCKET_CLOSE_CODE = 1012;
-const STALE_SOCKET_CLOSE_REASON =
-  'WebSocket session expired; reconnect required';
-
-/**
- * WeakMap from server-side WebSocket → tag with event handlers.
- * Populated on upgrade, read in webSocketMessage/webSocketClose.
- */
-const socketTags = new WeakMap<WebSocket, WebSocketTag>();
-
-function closeStaleSocket(ws: WebSocket): void {
-  try {
-    ws.close(STALE_SOCKET_CLOSE_CODE, STALE_SOCKET_CLOSE_REASON);
-  } catch {
-    // ignore
-  }
-}
-
-function createWSContext(ws: WebSocket): WSContext<WebSocket> {
-  return new WSContext<WebSocket>({
-    send(data) {
-      ws.send(webSocketSendData(data));
-    },
-    close(code, reason) {
-      ws.close(code, reason);
-    },
-    raw: ws,
-    get readyState() {
-      return ws.readyState as 0 | 1 | 2 | 3;
-    },
-  });
-}
-
-/**
- * Create an `upgradeWebSocket` function backed by the Durable Object
- * hibernation API (`state.acceptWebSocket`).
- *
- * Each accepted socket is tagged with its Hono `WSEvents` handlers so the
- * DO's `webSocketMessage` / `webSocketClose` callbacks can dispatch to them.
- */
-function createDOUpgradeWebSocket(
-  doState: DurableObjectState
-): UpgradeWebSocket<WebSocket> {
-  return defineWebSocketHelper((_c, events) => {
-    const pair = new WebSocketPair();
-    const [client, server] = Object.values(pair) as [WebSocket, WebSocket];
-
-    // Accept via hibernation API so the DO can wake on messages
-    doState.acceptWebSocket(server);
-
-    // Tag the server socket so webSocketMessage/webSocketClose can find handlers
-    socketTags.set(server, { events: events as WSEvents<WebSocket> });
-
-    // Fire onOpen synchronously (socket is already accepted)
-    const wsCtx = createWSContext(server);
-    events.onOpen?.(new Event('open'), wsCtx);
-
-    return new Response(null, {
-      status: 101,
-      webSocket: client,
-    } as ResponseInit & { webSocket: WebSocket });
-  });
-}
-
-function webSocketSendData(
-  data: string | ArrayBuffer | Uint8Array<ArrayBufferLike>
-): string | ArrayBuffer {
-  if (data instanceof Uint8Array) {
-    const buffer = new ArrayBuffer(data.byteLength);
-    new Uint8Array(buffer).set(data);
-    return buffer;
-  }
-  return data;
-}
-
-// ---------------------------------------------------------------------------
-// SyncDurableObject base class
-// ---------------------------------------------------------------------------
-
-/**
- * Base class for a Syncular Durable Object with Hono routing and WebSocket.
- *
- * Subclass and implement `setup()` to configure routes.
- */
-export abstract class SyncDurableObject<
-  E extends object = Record<string, unknown>,
-> {
-  protected ctx: DurableObjectState;
-  protected env: E;
-
-  private app: Hono<{ Bindings: E }> | null = null;
-  private initPromise: Promise<void> | null = null;
-  private doUpgradeWebSocket: UpgradeWebSocket<WebSocket>;
-
-  constructor(ctx: DurableObjectState, env: E) {
-    this.ctx = ctx;
-    this.env = env;
-    this.doUpgradeWebSocket = createDOUpgradeWebSocket(ctx);
-    this.closeUntrackedSockets();
-  }
-
-  /**
-   * Configure the Hono app with sync routes.
-   *
-   * Called once when the DO first receives a request.
-   * Use `upgradeWebSocket` when creating the sync server to enable realtime.
-   */
-  abstract setup(
-    app: Hono<{ Bindings: E }>,
-    env: E,
-    upgradeWebSocket: UpgradeWebSocket<WebSocket>
-  ): void | Promise<void>;
-
-  private async getApp(): Promise<Hono<{ Bindings: E }>> {
-    if (this.app) return this.app;
-    if (!this.initPromise) {
-      const honoApp = new Hono<{ Bindings: E }>();
-      this.initPromise = Promise.resolve(
-        this.setup(honoApp, this.env, this.doUpgradeWebSocket)
-      ).then(() => {
-        this.app = honoApp;
-      });
-    }
-    await this.initPromise;
-    return this.app!;
-  }
-
-  private closeUntrackedSockets(): void {
-    const sockets = this.ctx.getWebSockets();
-    for (const ws of sockets) {
-      if (socketTags.has(ws)) continue;
-      closeStaleSocket(ws);
-    }
-  }
-
-  /** Handle incoming HTTP requests (and WebSocket upgrades). */
-  async fetch(request: Request): Promise<Response> {
-    const app = await this.getApp();
-    return app.fetch(request, this.env);
-  }
-
-  /** Dispatch incoming WebSocket messages to Hono event handlers. */
-  async webSocketMessage(
-    ws: WebSocket,
-    message: string | ArrayBuffer
-  ): Promise<void> {
-    const tag = socketTags.get(ws);
-    if (!tag?.events.onMessage) {
-      closeStaleSocket(ws);
-      return;
-    }
-
-    const wsCtx = createWSContext(ws);
-    const evt = new MessageEvent('message', { data: message });
-    tag.events.onMessage(evt, wsCtx);
-  }
-
-  /** Dispatch WebSocket close events to Hono event handlers. */
-  async webSocketClose(
-    ws: WebSocket,
-    code: number,
-    reason: string,
-    _wasClean: boolean
-  ): Promise<void> {
-    const tag = socketTags.get(ws);
-    if (!tag?.events.onClose) {
-      socketTags.delete(ws);
-      return;
-    }
-
-    const wsCtx = createWSContext(ws);
-    const evt = new CloseEvent('close', { code, reason });
-    tag.events.onClose(evt, wsCtx);
-    socketTags.delete(ws);
-  }
-
-  /** Dispatch WebSocket error events to Hono event handlers. */
-  async webSocketError(ws: WebSocket, _error: unknown): Promise<void> {
-    const tag = socketTags.get(ws);
-    if (!tag?.events.onError) {
-      closeStaleSocket(ws);
-      return;
-    }
-
-    const wsCtx = createWSContext(ws);
-    const evt = new Event('error');
-    tag.events.onError(evt, wsCtx);
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Worker → DO router
-// ---------------------------------------------------------------------------
-
-/**
- * Create a Worker export that routes all requests to a Durable Object.
- *
- * Uses a single DO instance (derived from a stable ID) to hold all
- * connections. For multi-tenant setups, override `getStubId`.
- *
- * @example
- * ```typescript
- * export default createSyncWorkerWithDO<Env>('SYNC_DO');
- * ```
- */
-export function createSyncWorkerWithDO<E extends object>(
-  bindingName: string & keyof E,
-  options?: {
-    /**
-     * Derive a DurableObject ID from the request.
-     * Defaults to a single global instance via `idFromName('sync')`.
-     */
-    getStubId?: (
-      ns: DurableObjectNamespace,
-      request: Request,
-      env: E
-    ) => DurableObjectId;
-  }
-): ExportedHandler<E> {
-  return {
-    async fetch(
-      request: Request,
-      env: E,
-      _ctx: ExecutionContext
-    ): Promise<Response> {
-      const ns = env[
-        bindingName as keyof E
-      ] as unknown as DurableObjectNamespace;
-      const id = options?.getStubId
-        ? options.getStubId(ns, request, env)
-        : ns.idFromName('sync');
-      const stub = ns.get(id);
-      return stub.fetch(request);
-    },
-  };
-}

package/src/cloudflare/index.ts

@@ -1,22 +0,0 @@
-/**
- * @syncular/server/cloudflare - Cloudflare adapters for Syncular
- *
- * Two deployment modes:
- * - Worker (polling only): `@syncular/server/cloudflare/worker`
- * - Durable Object (WebSocket + polling): `@syncular/server/cloudflare/durable-object`
- *
- * Blob storage:
- * - R2 native: `@syncular/server/cloudflare/r2`
- *
- * Scope cache:
- * - Durable Object cache backend: `@syncular/server/cloudflare/scope-cache`
- *
- * Dialect is user-provided:
- * - D1 + SQLite: `@syncular/server/d1` + `@syncular/server/sqlite`
- * - Neon + Postgres: `@syncular/server/neon` + `createNeonServerDialect()` from `@syncular/server/postgres`
- */
-
-export * from './durable-object';
-export * from './r2';
-export * from './scope-cache';
-export * from './worker';