@syncular/server 0.0.5-44 → 0.0.6-101

package/src/push.ts

@@ -16,7 +16,11 @@ import type {
 } from 'kysely';
 import { sql } from 'kysely';
 import type { ServerSyncDialect } from './dialect/types';
-import type { TableRegistry } from './handlers/registry';
+import {
+  getServerHandlerOrThrow,
+  type ServerHandlerCollection,
+} from './handlers/collection';
+import type { SyncServerAuth } from './handlers/types';
 import type { SyncCoreDb } from './schema';
 
 // biome-ignore lint/complexity/noBannedTypes: Kysely uses `{}` as the initial "no selected columns yet" marker.
@@ -54,7 +58,7 @@ function toDialectJsonValue(
   value: unknown
 ): unknown {
   if (value === null || value === undefined) return null;
-  if (dialect.name === 'sqlite') return JSON.stringify(value);
+  if (dialect.family === 'sqlite') return JSON.stringify(value);
   return value;
 }
 
@@ -177,17 +181,19 @@ function recordPushMetrics(args: {
   );
 }
 
-export async function pushCommit<DB extends SyncCoreDb>(args: {
+export async function pushCommit<
+  DB extends SyncCoreDb,
+  Auth extends SyncServerAuth,
+>(args: {
   db: Kysely<DB>;
   dialect: ServerSyncDialect;
-  handlers: TableRegistry<DB>;
-  actorId: string;
-  partitionId?: string;
+  handlers: ServerHandlerCollection<DB, Auth>;
+  auth: Auth;
   request: SyncPushRequest;
 }): Promise<PushCommitResult> {
   const { db, dialect, handlers, request } = args;
-  const actorId = args.actorId;
-  const partitionId = args.partitionId ?? 'default';
+  const actorId = args.auth.actorId;
+  const partitionId = args.auth.partitionId ?? 'default';
   const requestedOps = Array.isArray(request.operations)
     ? request.operations
     : [];
@@ -425,12 +431,13 @@ export async function pushCommit<DB extends SyncCoreDb>(args: {
 
               for (let i = 0; i < ops.length; i++) {
                 const op = ops[i]!;
-                const handler = handlers.getOrThrow(op.table);
+                const handler = getServerHandlerOrThrow(handlers, op.table);
                 const applied = await handler.applyOperation(
                   {
                     db: trx,
                     trx,
                     actorId,
+                    auth: args.auth,
                     clientId: request.clientId,
                     commitId,
                     schemaVersion: request.schemaVersion,

package/src/snapshot-chunks/db-metadata.test.ts

@@ -1,7 +1,7 @@
 import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
-import type { BlobStorageAdapter } from '@syncular/core';
+import { type BlobStorageAdapter, createDatabase } from '@syncular/core';
 import { type Kysely, sql } from 'kysely';
-import { createBunSqliteDb } from '../../../dialect-bun-sqlite/src';
+import { createBunSqliteDialect } from '../../../dialect-bun-sqlite/src';
 import { createSqliteServerDialect } from '../../../server-dialect-sqlite/src';
 import { ensureSyncSchema } from '../migrate';
 import type { SyncCoreDb } from '../schema';
@@ -53,7 +53,10 @@ describe('createDbMetadataChunkStorage', () => {
   let db: Kysely<TestDb>;
 
   beforeEach(async () => {
-    db = createBunSqliteDb<TestDb>({ path: ':memory:' });
+    db = createDatabase<TestDb>({
+      dialect: createBunSqliteDialect({ path: ':memory:' }),
+      family: 'sqlite',
+    });
     await ensureSyncSchema(db, createSqliteServerDialect());
   });
 

package/src/subscriptions/cache.ts

@@ -0,0 +1,318 @@
+import type { ScopeValues } from '@syncular/core';
+import { type Kysely, sql } from 'kysely';
+import type { SyncServerAuth } from '../handlers/types';
+import type { SyncCoreDb } from '../schema';
+
+const DEFAULT_SCOPE_CACHE_PARTITION_ID = 'default';
+const DEFAULT_MEMORY_SCOPE_CACHE_TTL_MS = 30_000;
+const DEFAULT_MEMORY_SCOPE_CACHE_MAX_ENTRIES = 5_000;
+const DEFAULT_DATABASE_SCOPE_CACHE_TTL_MS = 60_000;
+const DEFAULT_DATABASE_SCOPE_CACHE_TABLE = 'sync_scope_cache';
+
+export interface ScopeCacheContext<
+  DB extends SyncCoreDb = SyncCoreDb,
+  Auth extends SyncServerAuth = SyncServerAuth,
+> {
+  db: Kysely<DB>;
+  auth: Auth;
+  table: string;
+  cacheKey: string;
+}
+
+export interface ScopeCacheSetContext<
+  DB extends SyncCoreDb = SyncCoreDb,
+  Auth extends SyncServerAuth = SyncServerAuth,
+> extends ScopeCacheContext<DB, Auth> {
+  scopes: ScopeValues;
+}
+
+/**
+ * Shared cache contract for scope resolution results.
+ *
+ * Pull requests always apply request-local memoization first.
+ * This cache is used to share results across pulls.
+ */
+export interface ScopeCacheBackend {
+  name: string;
+  get<DB extends SyncCoreDb, Auth extends SyncServerAuth>(
+    args: ScopeCacheContext<DB, Auth>
+  ): Promise<ScopeValues | null>;
+  set<DB extends SyncCoreDb, Auth extends SyncServerAuth>(
+    args: ScopeCacheSetContext<DB, Auth>
+  ): Promise<void>;
+  delete?<DB extends SyncCoreDb, Auth extends SyncServerAuth>(
+    args: ScopeCacheContext<DB, Auth>
+  ): Promise<void>;
+}
+
+export function createDefaultScopeCacheKey(args: {
+  table: string;
+  auth: SyncServerAuth;
+}): string {
+  const partitionId = args.auth.partitionId ?? DEFAULT_SCOPE_CACHE_PARTITION_ID;
+  return `${partitionId}\u0000${args.auth.actorId}\u0000${args.table}`;
+}
+
+function cloneScopeValues(scopes: ScopeValues): ScopeValues {
+  const cloned: ScopeValues = {};
+  for (const [key, value] of Object.entries(scopes)) {
+    if (typeof value === 'string') {
+      cloned[key] = value;
+      continue;
+    }
+    cloned[key] = [...value];
+  }
+  return cloned;
+}
+
+function parseScopeValues(value: string): ScopeValues | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(value);
+  } catch {
+    return null;
+  }
+
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return null;
+  }
+
+  const out: ScopeValues = {};
+  for (const [scopeKey, scopeValue] of Object.entries(parsed)) {
+    if (typeof scopeValue === 'string') {
+      out[scopeKey] = scopeValue;
+      continue;
+    }
+
+    if (
+      Array.isArray(scopeValue) &&
+      scopeValue.every((item) => typeof item === 'string')
+    ) {
+      out[scopeKey] = [...scopeValue];
+      continue;
+    }
+
+    return null;
+  }
+
+  return out;
+}
+
+interface MemoryScopeCacheEntry {
+  scopes: ScopeValues;
+  expiresAt: number;
+}
+
+export interface MemoryScopeCacheOptions {
+  ttlMs?: number;
+  maxEntries?: number;
+  now?: () => number;
+}
+
+export function createMemoryScopeCache(
+  options?: MemoryScopeCacheOptions
+): ScopeCacheBackend {
+  const ttlMs = options?.ttlMs ?? DEFAULT_MEMORY_SCOPE_CACHE_TTL_MS;
+  const maxEntries =
+    options?.maxEntries ?? DEFAULT_MEMORY_SCOPE_CACHE_MAX_ENTRIES;
+  const now = options?.now ?? Date.now;
+  const buckets = new WeakMap<object, Map<string, MemoryScopeCacheEntry>>();
+
+  function getBucket(db: object): Map<string, MemoryScopeCacheEntry> {
+    const existing = buckets.get(db);
+    if (existing) {
+      return existing;
+    }
+    const created = new Map<string, MemoryScopeCacheEntry>();
+    buckets.set(db, created);
+    return created;
+  }
+
+  function evictOldest(bucket: Map<string, MemoryScopeCacheEntry>): void {
+    while (bucket.size > maxEntries) {
+      const oldestKey = bucket.keys().next().value;
+      if (!oldestKey) {
+        return;
+      }
+      bucket.delete(oldestKey);
+    }
+  }
+
+  return {
+    name: 'memory',
+    async get(args) {
+      const bucket = getBucket(args.db);
+      const entry = bucket.get(args.cacheKey);
+      if (!entry) {
+        return null;
+      }
+
+      const nowMs = now();
+      if (entry.expiresAt <= nowMs) {
+        bucket.delete(args.cacheKey);
+        return null;
+      }
+
+      return cloneScopeValues(entry.scopes);
+    },
+    async set(args) {
+      const bucket = getBucket(args.db);
+      if (ttlMs <= 0) {
+        bucket.delete(args.cacheKey);
+        return;
+      }
+
+      if (bucket.has(args.cacheKey)) {
+        bucket.delete(args.cacheKey);
+      }
+      bucket.set(args.cacheKey, {
+        scopes: cloneScopeValues(args.scopes),
+        expiresAt: now() + ttlMs,
+      });
+      evictOldest(bucket);
+    },
+    async delete(args) {
+      const bucket = getBucket(args.db);
+      bucket.delete(args.cacheKey);
+    },
+  };
+}
+
+export interface DatabaseScopeCacheOptions {
+  /**
+   * Scope cache table name.
+   * Default: `sync_scope_cache`
+   */
+  tableName?: string;
+  /**
+   * TTL for cache entries (milliseconds).
+   * Default: 60000
+   */
+  ttlMs?: number;
+  /**
+   * Automatically creates the cache table.
+   * Default: true
+   */
+  autoCreateTable?: boolean;
+  now?: () => Date;
+}
+
+export function createDatabaseScopeCache(
+  options?: DatabaseScopeCacheOptions
+): ScopeCacheBackend {
+  const tableName = options?.tableName ?? DEFAULT_DATABASE_SCOPE_CACHE_TABLE;
+  const ttlMs = options?.ttlMs ?? DEFAULT_DATABASE_SCOPE_CACHE_TTL_MS;
+  const autoCreateTable = options?.autoCreateTable ?? true;
+  const now = options?.now ?? (() => new Date());
+  const schemaReady = new WeakMap<object, Promise<void>>();
+
+  async function ensureTable<DB extends SyncCoreDb>(db: Kysely<DB>) {
+    if (!autoCreateTable) {
+      return;
+    }
+
+    const existing = schemaReady.get(db);
+    if (existing) {
+      await existing;
+      return;
+    }
+
+    const pending = sql`
+      CREATE TABLE IF NOT EXISTS ${sql.table(tableName)} (
+        cache_key TEXT PRIMARY KEY,
+        scope_values TEXT NOT NULL,
+        expires_at TEXT NOT NULL,
+        created_at TEXT NOT NULL
+      )
+    `
+      .execute(db)
+      .then(() => undefined);
+    schemaReady.set(db, pending);
+
+    try {
+      await pending;
+    } catch (error) {
+      schemaReady.delete(db);
+      throw error;
+    }
+  }
+
+  async function removeCacheRow<DB extends SyncCoreDb>(args: {
+    db: Kysely<DB>;
+    cacheKey: string;
+  }): Promise<void> {
+    await sql`
+      DELETE FROM ${sql.table(tableName)}
+      WHERE cache_key = ${args.cacheKey}
+    `.execute(args.db);
+  }
+
+  return {
+    name: 'database',
+    async get(args) {
+      await ensureTable(args.db);
+
+      const rows = await sql<{
+        scope_values: string;
+        expires_at: string;
+      }>`
+        SELECT scope_values, expires_at
+        FROM ${sql.table(tableName)}
+        WHERE cache_key = ${args.cacheKey}
+        LIMIT 1
+      `.execute(args.db);
+
+      const row = rows.rows[0];
+      if (!row) {
+        return null;
+      }
+
+      const nowIso = now().toISOString();
+      if (row.expires_at <= nowIso) {
+        await removeCacheRow({ db: args.db, cacheKey: args.cacheKey });
+        return null;
+      }
+
+      const parsed = parseScopeValues(row.scope_values);
+      if (!parsed) {
+        await removeCacheRow({ db: args.db, cacheKey: args.cacheKey });
+        return null;
+      }
+
+      return parsed;
+    },
+    async set(args) {
+      await ensureTable(args.db);
+
+      if (ttlMs <= 0) {
+        await removeCacheRow({ db: args.db, cacheKey: args.cacheKey });
+        return;
+      }
+
+      const createdAt = now();
+      const expiresAt = new Date(createdAt.getTime() + ttlMs);
+      await sql`
+        INSERT INTO ${sql.table(tableName)} (
+          cache_key,
+          scope_values,
+          expires_at,
+          created_at
+        )
+        VALUES (
+          ${args.cacheKey},
+          ${JSON.stringify(cloneScopeValues(args.scopes))},
+          ${expiresAt.toISOString()},
+          ${createdAt.toISOString()}
+        )
+        ON CONFLICT (cache_key) DO UPDATE SET
+          scope_values = EXCLUDED.scope_values,
+          expires_at = EXCLUDED.expires_at,
+          created_at = EXCLUDED.created_at
+      `.execute(args.db);
+    },
+    async delete(args) {
+      await ensureTable(args.db);
+      await removeCacheRow({ db: args.db, cacheKey: args.cacheKey });
+    },
+  };
+}

package/src/subscriptions/index.ts

@@ -1 +1,2 @@
+export * from './cache';
 export * from './resolve';

package/src/subscriptions/resolve.test.ts

@@ -0,0 +1,180 @@
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
+import { createDatabase } from '@syncular/core';
+import type { Kysely } from 'kysely';
+import { createBunSqliteDialect } from '../../../dialect-bun-sqlite/src';
+import {
+  createServerHandler,
+  createServerHandlerCollection,
+} from '../handlers';
+import type { SyncCoreDb } from '../schema';
+import { createDatabaseScopeCache, createDefaultScopeCacheKey } from './cache';
+import { resolveEffectiveScopesForSubscriptions } from './resolve';
+
+interface TasksTable {
+  id: string;
+  user_id: string;
+  server_version: number;
+}
+
+interface TestDb extends SyncCoreDb {
+  tasks: TasksTable;
+}
+
+interface ClientDb {
+  tasks: TasksTable;
+}
+
+describe('resolveEffectiveScopesForSubscriptions cache behavior', () => {
+  let db: Kysely<TestDb>;
+
+  beforeEach(() => {
+    db = createDatabase<TestDb>({
+      dialect: createBunSqliteDialect({ path: ':memory:' }),
+      family: 'sqlite',
+    });
+  });
+
+  afterEach(async () => {
+    await db.destroy();
+  });
+
+  it('memoizes resolveScopes calls inside a single request', async () => {
+    let resolveCalls = 0;
+    const handler = createServerHandler<TestDb, ClientDb, 'tasks'>({
+      table: 'tasks',
+      scopes: ['user:{user_id}'],
+      resolveScopes: async (ctx) => {
+        resolveCalls += 1;
+        return { user_id: [ctx.actorId] };
+      },
+    });
+    const handlers = createServerHandlerCollection<TestDb>([handler]);
+
+    const resolved = await resolveEffectiveScopesForSubscriptions({
+      db,
+      auth: { actorId: 'u1' },
+      handlers,
+      subscriptions: [
+        { id: 'sub-1', table: 'tasks', scopes: { user_id: 'u1' }, cursor: -1 },
+        { id: 'sub-2', table: 'tasks', scopes: { user_id: 'u1' }, cursor: -1 },
+      ],
+    });
+
+    expect(resolveCalls).toBe(1);
+    expect(resolved).toHaveLength(2);
+    expect(resolved.every((entry) => entry.status === 'active')).toBe(true);
+  });
+
+  it('uses shared cache hit and skips resolveScopes', async () => {
+    let resolveCalls = 0;
+    let cacheGetCalls = 0;
+    let cacheSetCalls = 0;
+    const handler = createServerHandler<TestDb, ClientDb, 'tasks'>({
+      table: 'tasks',
+      scopes: ['user:{user_id}'],
+      resolveScopes: async (ctx) => {
+        resolveCalls += 1;
+        return { user_id: [ctx.actorId] };
+      },
+    });
+    const handlers = createServerHandlerCollection<TestDb>([handler]);
+
+    const resolved = await resolveEffectiveScopesForSubscriptions({
+      db,
+      auth: { actorId: 'u1' },
+      handlers,
+      scopeCache: {
+        name: 'test-cache',
+        async get() {
+          cacheGetCalls += 1;
+          return { user_id: ['u1'] };
+        },
+        async set() {
+          cacheSetCalls += 1;
+        },
+      },
+      subscriptions: [
+        { id: 'sub-1', table: 'tasks', scopes: { user_id: 'u1' }, cursor: -1 },
+      ],
+    });
+
+    expect(resolveCalls).toBe(0);
+    expect(cacheGetCalls).toBe(1);
+    expect(cacheSetCalls).toBe(0);
+    expect(resolved[0]?.status).toBe('active');
+  });
+
+  it('uses request-local memoization even with shared cache misses', async () => {
+    let resolveCalls = 0;
+    let cacheGetCalls = 0;
+    let cacheSetCalls = 0;
+    const handler = createServerHandler<TestDb, ClientDb, 'tasks'>({
+      table: 'tasks',
+      scopes: ['user:{user_id}'],
+      resolveScopes: async (ctx) => {
+        resolveCalls += 1;
+        return { user_id: [ctx.actorId] };
+      },
+    });
+    const handlers = createServerHandlerCollection<TestDb>([handler]);
+
+    const resolved = await resolveEffectiveScopesForSubscriptions({
+      db,
+      auth: { actorId: 'u1' },
+      handlers,
+      scopeCache: {
+        name: 'test-cache',
+        async get() {
+          cacheGetCalls += 1;
+          return null;
+        },
+        async set() {
+          cacheSetCalls += 1;
+        },
+      },
+      subscriptions: [
+        { id: 'sub-1', table: 'tasks', scopes: { user_id: 'u1' }, cursor: -1 },
+        { id: 'sub-2', table: 'tasks', scopes: { user_id: 'u1' }, cursor: -1 },
+      ],
+    });
+
+    expect(resolveCalls).toBe(1);
+    expect(cacheGetCalls).toBe(1);
+    expect(cacheSetCalls).toBe(1);
+    expect(resolved).toHaveLength(2);
+    expect(resolved.every((entry) => entry.status === 'active')).toBe(true);
+  });
+
+  it('roundtrips values through database scope cache', async () => {
+    const scopeCache = createDatabaseScopeCache();
+    const auth = { actorId: 'u1', partitionId: 'tenant-1' };
+    const cacheKey = createDefaultScopeCacheKey({ auth, table: 'tasks' });
+    const context = { db, auth, table: 'tasks', cacheKey };
+    const scopes = { user_id: ['u1', 'u2'] };
+
+    await scopeCache.set({ ...context, scopes });
+    const cachedScopes = await scopeCache.get(context);
+
+    expect(cachedScopes).toEqual(scopes);
+  });
+
+  it('expires entries in database scope cache', async () => {
+    let nowMs = Date.now();
+    const scopeCache = createDatabaseScopeCache({
+      ttlMs: 25,
+      now: () => new Date(nowMs),
+    });
+    const auth = { actorId: 'u1', partitionId: 'tenant-1' };
+    const cacheKey = createDefaultScopeCacheKey({ auth, table: 'tasks' });
+    const context = { db, auth, table: 'tasks', cacheKey };
+
+    await scopeCache.set({
+      ...context,
+      scopes: { user_id: ['u1'] },
+    });
+
+    nowMs += 26;
+    const cachedScopes = await scopeCache.get(context);
+    expect(cachedScopes).toBeNull();
+  });
+});