@syncular/server 0.1.2 → 0.2.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@syncular/server",
-  "version": "0.1.2",
-  "description": "Server-side Syncular engine with opt-in Hono, database, storage, Cloudflare, relay, and CRDT subpaths",
+  "version": "0.2.0",
+  "description": "Syncular server: handleSyncRequest + storage/auth interfaces for the sync protocol",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
   "homepage": "https://syncular.dev",
@@ -20,350 +20,42 @@
     "database",
     "typescript"
   ],
-  "private": false,
+  "type": "module",
+  "sideEffects": false,
   "publishConfig": {
     "access": "public"
   },
-  "type": "module",
   "exports": {
     ".": {
       "bun": "./src/index.ts",
+      "browser": "./src/index.ts",
       "import": {
         "types": "./dist/index.d.ts",
         "default": "./dist/index.js"
       }
     },
-    "./dialect/types": {
-      "bun": "./src/dialect/types.ts",
-      "import": {
-        "types": "./dist/dialect/types.d.ts",
-        "default": "./dist/dialect/types.js"
-      }
-    },
-    "./schema": {
-      "bun": "./src/schema.ts",
-      "import": {
-        "types": "./dist/schema.d.ts",
-        "default": "./dist/schema.js"
-      }
-    },
-    "./snapshot-chunks": {
-      "bun": "./src/snapshot-chunks/index.ts",
-      "import": {
-        "types": "./dist/snapshot-chunks/index.d.ts",
-        "default": "./dist/snapshot-chunks/index.js"
-      }
-    },
-    "./snapshot-artifacts/sqlite-bun": {
-      "bun": "./src/snapshot-artifacts/sqlite-bun.ts",
-      "import": {
-        "types": "./dist/snapshot-artifacts/sqlite-bun.d.ts",
-        "default": "./dist/snapshot-artifacts/sqlite-bun.js"
-      }
-    },
-    "./hono": {
-      "bun": "./src/hono/index.ts",
-      "import": {
-        "types": "./dist/hono/index.d.ts",
-        "default": "./dist/hono/index.js"
-      }
-    },
-    "./hono/blobs": {
-      "bun": "./src/hono/blobs.ts",
-      "import": {
-        "types": "./dist/hono/blobs.d.ts",
-        "default": "./dist/hono/blobs.js"
-      }
-    },
-    "./hono/create-server": {
-      "bun": "./src/hono/create-server.ts",
-      "import": {
-        "types": "./dist/hono/create-server.d.ts",
-        "default": "./dist/hono/create-server.js"
-      }
-    },
-    "./cloudflare": {
-      "bun": "./src/cloudflare/index.ts",
-      "import": {
-        "types": "./dist/cloudflare/index.d.ts",
-        "default": "./dist/cloudflare/index.js"
-      }
-    },
-    "./cloudflare/worker": {
-      "bun": "./src/cloudflare/worker.ts",
-      "import": {
-        "types": "./dist/cloudflare/worker.d.ts",
-        "default": "./dist/cloudflare/worker.js"
-      }
-    },
-    "./cloudflare/durable-object": {
-      "bun": "./src/cloudflare/durable-object.ts",
-      "import": {
-        "types": "./dist/cloudflare/durable-object.d.ts",
-        "default": "./dist/cloudflare/durable-object.js"
-      }
-    },
-    "./cloudflare/r2": {
-      "bun": "./src/cloudflare/r2.ts",
-      "import": {
-        "types": "./dist/cloudflare/r2.d.ts",
-        "default": "./dist/cloudflare/r2.js"
-      }
-    },
-    "./cloudflare/scope-cache": {
-      "bun": "./src/cloudflare/scope-cache.ts",
-      "import": {
-        "types": "./dist/cloudflare/scope-cache.d.ts",
-        "default": "./dist/cloudflare/scope-cache.js"
-      }
-    },
-    "./cloudflare/sentry": {
-      "bun": "./src/cloudflare/sentry.ts",
-      "import": {
-        "types": "./dist/cloudflare/sentry.d.ts",
-        "default": "./dist/cloudflare/sentry.js"
-      }
-    },
-    "./service-worker": {
-      "bun": "./src/service-worker/index.ts",
-      "browser": "./src/service-worker/index.ts",
-      "import": {
-        "types": "./dist/service-worker/index.d.ts",
-        "default": "./dist/service-worker/index.js"
-      }
-    },
-    "./relay": {
-      "bun": "./src/relay/index.ts",
-      "import": {
-        "types": "./dist/relay/index.d.ts",
-        "default": "./dist/relay/index.js"
-      }
-    },
-    "./better-sqlite3": {
-      "bun": "./src/better-sqlite3.ts",
-      "import": {
-        "types": "./dist/better-sqlite3.d.ts",
-        "default": "./dist/better-sqlite3.js"
-      }
-    },
-    "./bun-sqlite": {
-      "bun": "./src/bun-sqlite.ts",
-      "import": {
-        "types": "./dist/bun-sqlite.d.ts",
-        "default": "./dist/bun-sqlite.js"
-      }
-    },
-    "./d1": {
-      "bun": "./src/d1.ts",
-      "import": {
-        "types": "./dist/d1.d.ts",
-        "default": "./dist/d1.js"
-      }
-    },
-    "./libsql": {
-      "bun": "./src/libsql.ts",
-      "import": {
-        "types": "./dist/libsql.d.ts",
-        "default": "./dist/libsql.js"
-      }
-    },
-    "./neon": {
-      "bun": "./src/neon.ts",
-      "import": {
-        "types": "./dist/neon.d.ts",
-        "default": "./dist/neon.js"
-      }
-    },
     "./pglite": {
-      "bun": "./src/pglite.ts",
-      "browser": "./src/pglite.ts",
-      "import": {
-        "types": "./dist/pglite.d.ts",
-        "default": "./dist/pglite.js"
-      }
-    },
-    "./sqlite3": {
-      "bun": "./src/sqlite3.ts",
-      "import": {
-        "types": "./dist/sqlite3.d.ts",
-        "default": "./dist/sqlite3.js"
-      }
-    },
-    "./sqlite": {
-      "bun": "./src/sqlite/index.ts",
-      "import": {
-        "types": "./dist/sqlite/index.d.ts",
-        "default": "./dist/sqlite/index.js"
-      }
-    },
-    "./postgres": {
-      "bun": "./src/postgres/index.ts",
-      "import": {
-        "types": "./dist/postgres/index.d.ts",
-        "default": "./dist/postgres/index.js"
-      }
-    },
-    "./filesystem": {
-      "bun": "./src/filesystem/index.ts",
-      "import": {
-        "types": "./dist/filesystem/index.d.ts",
-        "default": "./dist/filesystem/index.js"
-      }
-    },
-    "./s3": {
-      "bun": "./src/s3/index.ts",
-      "import": {
-        "types": "./dist/s3/index.d.ts",
-        "default": "./dist/s3/index.js"
-      }
-    },
-    "./crdt-yjs": {
-      "bun": "./src/crdt-yjs/index.ts",
+      "bun": "./src/pg-executor-pglite.ts",
+      "browser": "./src/pg-executor-pglite.ts",
       "import": {
-        "types": "./dist/crdt-yjs/index.d.ts",
-        "default": "./dist/crdt-yjs/index.js"
+        "types": "./dist/pg-executor-pglite.d.ts",
+        "default": "./dist/pg-executor-pglite.js"
       }
     }
   },
-  "scripts": {
-    "test": "bun test src",
-    "tsgo": "tsgo --noEmit",
-    "generate:openapi": "bun scripts/generate-openapi.ts",
-    "build": "tsgo",
-    "release": "syncular-publish",
-    "evaluate:relay-paths": "bun scripts/evaluate-relay-paths.ts",
-    "evaluate:rust-boundary": "bun scripts/evaluate-relay-rust-boundary.ts"
-  },
-  "dependencies": {
-    "@syncular/core": "0.1.1"
-  },
-  "peerDependencies": {
-    "@cloudflare/workers-types": "*",
-    "@electric-sql/pglite": "^0.3.15",
-    "@hono/standard-validator": "^0.2.2",
-    "@neondatabase/serverless": "^1.0.2",
-    "@sentry/cloudflare": "^10.47.0",
-    "@scalar/hono-api-reference": "^0.10.6",
-    "@standard-community/standard-json": "^0.3.5",
-    "@standard-community/standard-openapi": "^0.2.9",
-    "@types/better-sqlite3": "^7.6.13",
-    "better-sqlite3": "^12.8.0",
-    "hono": "^4.0.0",
-    "hono-openapi": "^1.3.0",
-    "kysely": "^0.28.0",
-    "kysely-bun-sqlite": "^0.4.0",
-    "kysely-d1": "^0.4.0",
-    "kysely-generic-sqlite": "^1.2.1",
-    "kysely-neon": "^2.0.2",
-    "kysely-pglite-dialect": "^1.2.0",
-    "libsql": "^0.5.29",
-    "openapi-types": "^12.1.3",
-    "sqlite3": "^6.0.1",
-    "yjs": "^13.6.30",
-    "zod": "^4.0.0"
-  },
-  "devDependencies": {
-    "@cloudflare/workers-types": "*",
-    "@electric-sql/pglite": "^0.3.15",
-    "@hono/standard-validator": "^0.2.2",
-    "@neondatabase/serverless": "^1.0.2",
-    "@sentry/cloudflare": "^10.47.0",
-    "@scalar/hono-api-reference": "^0.10.6",
-    "@standard-community/standard-json": "^0.3.5",
-    "@standard-community/standard-openapi": "^0.2.9",
-    "@syncular/config": "0.0.0",
-    "@syncular/console": "0.1.1",
-    "@types/better-sqlite3": "^7.6.13",
-    "@types/json-schema": "^7.0.15",
-    "better-sqlite3": "^12.8.0",
-    "hono": "^4.12.15",
-    "hono-openapi": "^1.3.0",
-    "kysely": "*",
-    "kysely-bun-sqlite": "^0.4.0",
-    "kysely-d1": "^0.4.0",
-    "kysely-generic-sqlite": "^1.2.1",
-    "kysely-neon": "^2.0.2",
-    "kysely-pglite-dialect": "^1.2.0",
-    "libsql": "^0.5.29",
-    "openapi-types": "^12.1.3",
-    "sqlite3": "^6.0.1",
-    "yjs": "^13.6.30",
-    "zod": "*"
-  },
   "files": [
     "dist",
     "src",
+    "README.md",
     "!src/**/*.test.ts",
     "!src/**/*.test.tsx",
-    "!src/**/__tests__/**",
-    "!dist/**/*.test.*",
-    "!dist/**/__tests__/**",
-    "!test/**",
-    "!tests/**"
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.d.ts"
   ],
-  "peerDependenciesMeta": {
-    "@cloudflare/workers-types": {
-      "optional": true
-    },
-    "@electric-sql/pglite": {
-      "optional": true
-    },
-    "@hono/standard-validator": {
-      "optional": true
-    },
-    "@neondatabase/serverless": {
-      "optional": true
-    },
-    "@sentry/cloudflare": {
-      "optional": true
-    },
-    "@scalar/hono-api-reference": {
-      "optional": true
-    },
-    "@standard-community/standard-json": {
-      "optional": true
-    },
-    "@standard-community/standard-openapi": {
-      "optional": true
-    },
-    "@types/better-sqlite3": {
-      "optional": true
-    },
-    "better-sqlite3": {
-      "optional": true
-    },
-    "hono": {
-      "optional": true
-    },
-    "hono-openapi": {
-      "optional": true
-    },
-    "kysely-bun-sqlite": {
-      "optional": true
-    },
-    "kysely-d1": {
-      "optional": true
-    },
-    "kysely-generic-sqlite": {
-      "optional": true
-    },
-    "kysely-neon": {
-      "optional": true
-    },
-    "kysely-pglite-dialect": {
-      "optional": true
-    },
-    "libsql": {
-      "optional": true
-    },
-    "openapi-types": {
-      "optional": true
-    },
-    "sqlite3": {
-      "optional": true
-    },
-    "yjs": {
-      "optional": true
-    }
+  "dependencies": {
+    "@syncular/core": "0.2.0"
+  },
+  "devDependencies": {
+    "@electric-sql/pglite": "^0.5.4"
   }
 }

package/src/admin.ts

@@ -0,0 +1,312 @@
+/**
+ * `SyncularAdmin` — the operator-facing read surface over the server core
+ * (TODO §2.5). A read-only, partition-scoped, JSON-able query layer over
+ * `ServerStorage`, the optional segment/blob store stats, and an in-memory
+ * event ring. This is v2's answer to v1's full React console app: the same
+ * 80% operator value (who's connected, what's flowing, horizon health, the
+ * event tail) as a handful of queries in the server package — no separate
+ * UI package, no framework, no wire-protocol surface (SPEC.md is untouched;
+ * this is host surface, mirrored in the server README).
+ *
+ * Nothing here is on the sync hot path. Every method is a plain read; the
+ * additive optional storage/store methods it depends on are documented as
+ * such and this module fails loud (a thrown `Error`) when a backend lacks
+ * one, so a host wiring an unsupported store learns immediately rather than
+ * getting a silently-empty console.
+ */
+import type { BlobStore, BlobStoreStats } from './blob-store';
+import { clockOf, type SyncServerConfig } from './context';
+import type { SyncularServerEvent } from './events';
+import type { RingBufferEvents, RingEventQuery } from './events-ring';
+import { DEFAULT_RETENTION, type RetentionPolicy } from './prune';
+import { compileSchema, type ServerSchema } from './schema';
+import type { SegmentStore, SegmentStoreStats } from './segment-store';
+import type {
+  ClientRecord,
+  CommitMetadata,
+  ScopeCommitActivity,
+  ServerStorage,
+} from './storage';
+
+/** A connected/known client as the console sees it (§4.5, §8.1). */
+export interface AdminClient {
+  readonly clientId: string;
+  readonly actorId: string;
+  readonly cursor: number;
+  readonly updatedAtMs: number;
+  readonly subscriptions: readonly {
+    readonly id: string;
+    readonly table: string;
+    readonly scopes: Record<string, readonly string[]>;
+  }[];
+  /** True when the cursor record was touched within the active window. */
+  readonly active: boolean;
+}
+
+export interface AdminRowInspection {
+  readonly table: string;
+  readonly rowId: string;
+  readonly exists: boolean;
+  readonly serverVersion?: number;
+  readonly scopes?: Record<string, string>;
+  /** blobIds this row currently references (§5.9.4), when the store tracks them. */
+  readonly referencedBlobIds?: readonly string[];
+}
+
+export interface AdminHorizonStatus {
+  readonly partition: string;
+  readonly maxCommitSeq: number;
+  readonly horizonSeq: number;
+  /** Commits still below the retained log's tail — the pruneable backlog. */
+  readonly retainedCommits: number;
+  /** min(cursor) over active clients, or null when none are active. */
+  readonly activeCursorFloor: number | null;
+  /** The horizon a prune pass would advance to right now (§4.6). */
+  readonly recommendedHorizonSeq: number;
+  readonly recommendation: 'up-to-date' | 'prune-recommended';
+}
+
+export interface AdminListCommitsOptions {
+  readonly afterSeq?: number;
+  readonly limit?: number;
+  readonly table?: string;
+}
+
+export interface AdminScopeActivityOptions {
+  readonly limit?: number;
+}
+
+export interface AdminStats {
+  readonly segments?: SegmentStoreStats;
+  readonly blobs?: BlobStoreStats;
+}
+
+export interface SyncularAdminOptions {
+  readonly storage: ServerStorage;
+  /**
+   * The server schema. When present, row reads (`inspectRow`) ensure the
+   * relational row tables exist first — needed when the admin runs against
+   * a storage instance that has not served a sync request yet.
+   */
+  readonly schema?: ServerSchema;
+  /** The event ring feeding the event tail. Absent ⇒ `events()` is empty. */
+  readonly ring?: RingBufferEvents;
+  readonly segments?: SegmentStore;
+  readonly blobs?: BlobStore;
+  /** Retention policy for horizon recommendation (defaults to §4.6). */
+  readonly retention?: Partial<RetentionPolicy>;
+  /** Epoch-ms clock (defaults to `Date.now`) — active-window math. */
+  readonly clock?: () => number;
+}
+
+const DEFAULT_COMMIT_LIMIT = 50;
+const DEFAULT_SCOPE_LIMIT = 50;
+
+function required<T>(value: T | undefined, what: string): T {
+  if (value === undefined) {
+    throw new Error(
+      `SyncularAdmin: the configured ${what} does not implement this read (TODO §2.5 optional method missing)`,
+    );
+  }
+  return value;
+}
+
+function toAdminClient(record: ClientRecord, active: boolean): AdminClient {
+  return {
+    clientId: record.clientId,
+    actorId: record.actorId,
+    cursor: record.cursor,
+    updatedAtMs: record.updatedAtMs,
+    subscriptions: record.subscriptions.map((sub) => ({
+      id: sub.id,
+      table: sub.table,
+      scopes: sub.scopes,
+    })),
+    active,
+  };
+}
+
+/** The read-only console query surface. Construct one per host process. */
+export class SyncularAdmin {
+  readonly #storage: ServerStorage;
+  readonly #schema?: ServerSchema;
+  readonly #ring?: RingBufferEvents;
+  readonly #segments?: SegmentStore;
+  readonly #blobs?: BlobStore;
+  readonly #retention: RetentionPolicy;
+  readonly #clock: () => number;
+
+  constructor(options: SyncularAdminOptions) {
+    this.#storage = options.storage;
+    if (options.schema !== undefined) this.#schema = options.schema;
+    if (options.ring !== undefined) this.#ring = options.ring;
+    if (options.segments !== undefined) this.#segments = options.segments;
+    if (options.blobs !== undefined) this.#blobs = options.blobs;
+    this.#retention = { ...DEFAULT_RETENTION, ...options.retention };
+    this.#clock = options.clock ?? Date.now;
+  }
+
+  /**
+   * Build an admin over a `SyncServerConfig`, reusing its storage / segment
+   * / blob store / clock. Pass the ring separately (it is an events sink,
+   * composed into the config's `events` by the host — see `composeEvents`).
+   */
+  static fromConfig(
+    config: SyncServerConfig,
+    extra?: { ring?: RingBufferEvents; retention?: Partial<RetentionPolicy> },
+  ): SyncularAdmin {
+    return new SyncularAdmin({
+      storage: config.storage,
+      schema: config.schema,
+      segments: config.segments,
+      ...(config.blobs !== undefined ? { blobs: config.blobs } : {}),
+      ...(extra?.ring !== undefined ? { ring: extra.ring } : {}),
+      ...(extra?.retention !== undefined ? { retention: extra.retention } : {}),
+      clock: clockOf(config),
+    });
+  }
+
+  /** The known clients for a partition (cursor, last-seen, subscriptions). */
+  async listClients(partition: string): Promise<AdminClient[]> {
+    const list = required(
+      this.#storage.listClientRecords?.bind(this.#storage),
+      'storage',
+    );
+    const records = await list(partition);
+    const activeFloorMs = this.#clock() - this.#retention.activeWindowMs;
+    return records.map((record) =>
+      toAdminClient(record, record.updatedAtMs >= activeFloorMs),
+    );
+  }
+
+  /** Commit-log metadata (no payloads), newest first. */
+  async listCommits(
+    partition: string,
+    options: AdminListCommitsOptions = {},
+  ): Promise<CommitMetadata[]> {
+    const read = required(
+      this.#storage.listCommitMetadata?.bind(this.#storage),
+      'storage',
+    );
+    return read(partition, {
+      afterSeq: options.afterSeq ?? 0,
+      limit: options.limit ?? DEFAULT_COMMIT_LIMIT,
+      ...(options.table !== undefined ? { table: options.table } : {}),
+    });
+  }
+
+  /**
+   * Inspect a single row: current server_version, stored scopes, and the
+   * blobIds it references (when the store tracks references). Payload bytes
+   * are deliberately NOT decoded — the console shows metadata, not content.
+   */
+  async inspectRow(
+    partition: string,
+    table: string,
+    rowId: string,
+  ): Promise<AdminRowInspection> {
+    const read = required(
+      this.#storage.getRowScopes?.bind(this.#storage),
+      'storage',
+    );
+    if (this.#schema !== undefined) {
+      await this.#storage.ensureSchema(compileSchema(this.#schema));
+    }
+    const row = await read(partition, table, rowId);
+    if (row === undefined) {
+      return { table, rowId, exists: false };
+    }
+    return {
+      table,
+      rowId,
+      exists: true,
+      serverVersion: row.serverVersion,
+      scopes: row.scopes,
+    };
+  }
+
+  /**
+   * Recent commits touching one scope key (`variable:value`, e.g.
+   * `project:p1`) — routed through the change-scope index, never a scan.
+   */
+  async scopeActivity(
+    partition: string,
+    scopeKey: { variable: string; value: string },
+    options: AdminScopeActivityOptions = {},
+  ): Promise<ScopeCommitActivity[]> {
+    const read = required(
+      this.#storage.scopeActivity?.bind(this.#storage),
+      'storage',
+    );
+    return read(partition, {
+      variable: scopeKey.variable,
+      value: scopeKey.value,
+      limit: options.limit ?? DEFAULT_SCOPE_LIMIT,
+    });
+  }
+
+  /**
+   * Horizon health for a partition: current horizon, retained-commit
+   * backlog, active cursor floor, and the horizon a prune pass would reach
+   * now (§4.6) plus a coarse recommendation.
+   */
+  async horizonStatus(partition: string): Promise<AdminHorizonStatus> {
+    const nowMs = this.#clock();
+    const maxCommitSeq = await this.#storage.getMaxCommitSeq(partition);
+    const horizonSeq = await this.#storage.getHorizonSeq(partition);
+    const cursors = await this.#storage.listClientCursors(partition);
+    const activeCursors = cursors
+      .filter((c) => c.updatedAtMs >= nowMs - this.#retention.activeWindowMs)
+      .map((c) => c.cursor);
+    const activeCursorFloor =
+      activeCursors.length > 0 ? Math.min(...activeCursors) : null;
+    const cursorFloor = activeCursorFloor ?? Number.MAX_SAFE_INTEGER;
+    const forcedSeq = await this.#storage.getCommitSeqBefore(
+      partition,
+      nowMs - this.#retention.ageForceMs,
+    );
+    const retainFloor = maxCommitSeq - this.#retention.minRetainedCommits;
+    const target = Math.min(Math.max(cursorFloor, forcedSeq), retainFloor);
+    const recommendedHorizonSeq = Math.max(horizonSeq, Math.max(0, target));
+    return {
+      partition,
+      maxCommitSeq,
+      horizonSeq,
+      retainedCommits: maxCommitSeq - horizonSeq,
+      activeCursorFloor,
+      recommendedHorizonSeq,
+      recommendation:
+        recommendedHorizonSeq > horizonSeq ? 'prune-recommended' : 'up-to-date',
+    };
+  }
+
+  /** Segment + blob store counters where the stores expose them. */
+  async stats(partition: string): Promise<AdminStats> {
+    const segments = await this.#segments?.stats?.();
+    const blobs = await this.#blobs?.stats?.(partition);
+    return {
+      ...(segments !== undefined ? { segments } : {}),
+      ...(blobs !== undefined ? { blobs } : {}),
+    };
+  }
+
+  /** Segment store counters alone (undefined when unsupported/unset). */
+  async segmentStats(): Promise<SegmentStoreStats | undefined> {
+    return this.#segments?.stats?.();
+  }
+
+  /** Blob store counters for a partition (undefined when unsupported/unset). */
+  async blobStats(partition: string): Promise<BlobStoreStats | undefined> {
+    return this.#blobs?.stats?.(partition);
+  }
+
+  /** True when this admin has an event ring wired (the event tail is live). */
+  get hasEventStream(): boolean {
+    return this.#ring !== undefined;
+  }
+
+  /** The event tail from the ring buffer (newest first). Empty when unwired. */
+  events(query: RingEventQuery = {}): SyncularServerEvent[] {
+    return this.#ring?.query(query) ?? [];
+  }
+}