@syncular/server 0.0.6-96 → 0.1.0

package/src/hono/routes/snapshots.ts

@@ -0,0 +1,345 @@
+/**
+ * Snapshot download routes:
+ * - GET /snapshot-chunks/:chunkId
+ * - GET /snapshot-artifacts/:artifactId
+ */
+
+import { ErrorResponseSchema } from '@syncular/core';
+import type { SqlFamily, SyncCoreDb } from '@syncular/server';
+import {
+  InvalidSubscriptionScopeError,
+  readScopedSnapshotArtifact,
+  readSnapshotChunk,
+  resolveEffectiveScopesForSubscriptions,
+  scopesToSnapshotChunkScopeKey,
+} from '@syncular/server';
+import { describeRoute, resolver } from 'hono-openapi';
+import { z } from 'zod';
+import { syncError } from '../errors';
+import { syncValidator as zValidator } from '../validation';
+import type { SyncRoutesContext } from './context';
+import {
+  readSnapshotScopeValues,
+  responseBodyOverLimit,
+  type SyncAuthResult,
+  snapshotArtifactParamsSchema,
+  snapshotChunkParamsSchema,
+  snapshotChunkQuerySchema,
+} from './shared';
+
+export function registerSnapshotRoutes<
+  DB extends SyncCoreDb = SyncCoreDb,
+  Auth extends SyncAuthResult = SyncAuthResult,
+  F extends SqlFamily = SqlFamily,
+>(ctx: SyncRoutesContext<DB, Auth, F>): void {
+  const {
+    routes,
+    getAuth,
+    options,
+    handlerRegistry,
+    maxSnapshotChunkResponseBytes,
+    maxSnapshotArtifactResponseBytes,
+  } = ctx;
+
+  // -------------------------------------------------------------------------
+  // GET /snapshot-chunks/:chunkId
+  // -------------------------------------------------------------------------
+
+  routes.get(
+    '/snapshot-chunks/:chunkId',
+    describeRoute({
+      tags: ['sync'],
+      summary: 'Download snapshot chunk',
+      description: 'Download an encoded bootstrap snapshot chunk',
+      responses: {
+        200: {
+          description: 'Snapshot chunk data (gzip-compressed framed JSON rows)',
+          content: {
+            'application/octet-stream': {
+              schema: resolver(z.string()),
+            },
+          },
+        },
+        304: {
+          description: 'Not modified (cached)',
+        },
+        401: {
+          description: 'Unauthenticated',
+          content: {
+            'application/json': { schema: resolver(ErrorResponseSchema) },
+          },
+        },
+        403: {
+          description: 'Forbidden',
+          content: {
+            'application/json': { schema: resolver(ErrorResponseSchema) },
+          },
+        },
+        404: {
+          description: 'Not found',
+          content: {
+            'application/json': { schema: resolver(ErrorResponseSchema) },
+          },
+        },
+      },
+    }),
+    zValidator('param', snapshotChunkParamsSchema),
+    zValidator('query', snapshotChunkQuerySchema),
+    async (c) => {
+      const auth = await getAuth(c);
+      if (!auth) return syncError(c, 401, 'sync.auth_required');
+      const partitionId = auth.partitionId ?? 'default';
+      const query = c.req.valid('query');
+      const requestedChunkScopes = readSnapshotScopeValues(c, query.scopes);
+
+      const { chunkId } = c.req.valid('param');
+
+      const chunk = await readSnapshotChunk(options.db, chunkId, {
+        chunkStorage: options.chunkStorage,
+      });
+      if (!chunk) return syncError(c, 404, 'sync.not_found');
+      if (chunk.partitionId !== partitionId) {
+        return syncError(c, 403, 'sync.forbidden');
+      }
+
+      const nowIso = new Date().toISOString();
+      if (chunk.expiresAt <= nowIso) {
+        return syncError(c, 404, 'sync.not_found');
+      }
+
+      if (!requestedChunkScopes) {
+        return syncError(
+          c,
+          400,
+          'sync.invalid_request',
+          'Snapshot chunk scope values are required'
+        );
+      }
+
+      try {
+        const resolved = await resolveEffectiveScopesForSubscriptions({
+          db: options.db,
+          auth,
+          subscriptions: [
+            {
+              id: 'snapshot-chunk-authz',
+              table: chunk.scope,
+              scopes: requestedChunkScopes,
+              cursor: 0,
+              crdtStateVectors: [],
+            },
+          ],
+          handlers: handlerRegistry,
+          scopeCache: options.scopeCache,
+        });
+        const scopeAuth = resolved[0];
+        if (!scopeAuth || scopeAuth.status !== 'active') {
+          return syncError(c, 403, 'sync.forbidden');
+        }
+
+        const scopeHash = await scopesToSnapshotChunkScopeKey(scopeAuth.scopes);
+        const scopedChunkKeyMatches =
+          chunk.scopeKey.startsWith('snapshot-v2:') &&
+          chunk.scopeKey.endsWith(`:scope:${scopeHash}`);
+        if (!scopedChunkKeyMatches) {
+          return syncError(c, 403, 'sync.forbidden');
+        }
+      } catch (error) {
+        if (error instanceof InvalidSubscriptionScopeError) {
+          return syncError(c, 403, 'sync.forbidden');
+        }
+        throw error;
+      }
+
+      const etag = `"sha256:${chunk.sha256}"`;
+      const ifNoneMatch = c.req.header('if-none-match');
+      if (ifNoneMatch && ifNoneMatch === etag) {
+        return new Response(null, {
+          status: 304,
+          headers: {
+            ETag: etag,
+            'Cache-Control': 'private, max-age=0',
+            Vary: 'Authorization, X-Syncular-Snapshot-Scopes',
+          },
+        });
+      }
+
+      const limitResponse = responseBodyOverLimit(c, {
+        limit: 'maxSnapshotChunkResponseBytes',
+        observed: chunk.byteLength,
+        max: maxSnapshotChunkResponseBytes,
+      });
+      if (limitResponse) return limitResponse;
+
+      return new Response(chunk.body as BodyInit, {
+        status: 200,
+        headers: {
+          'Content-Type': 'application/octet-stream',
+          'Content-Length': String(chunk.byteLength),
+          ETag: etag,
+          'Cache-Control': 'private, max-age=0',
+          Vary: 'Authorization, X-Syncular-Snapshot-Scopes',
+          'X-Sync-Chunk-Id': chunk.chunkId,
+          'X-Sync-Chunk-Sha256': chunk.sha256,
+          'X-Sync-Chunk-Encoding': chunk.encoding,
+          'X-Sync-Chunk-Compression': chunk.compression,
+        },
+      });
+    }
+  );
+
+  // -------------------------------------------------------------------------
+  // GET /snapshot-artifacts/:artifactId
+  // -------------------------------------------------------------------------
+
+  routes.get(
+    '/snapshot-artifacts/:artifactId',
+    describeRoute({
+      tags: ['sync'],
+      summary: 'Download scoped snapshot artifact',
+      description: 'Download a verified, scoped bootstrap snapshot artifact',
+      responses: {
+        200: {
+          description: 'Scoped snapshot artifact bytes',
+          content: {
+            'application/octet-stream': {
+              schema: resolver(z.string()),
+            },
+          },
+        },
+        304: {
+          description: 'Not modified (cached)',
+        },
+        401: {
+          description: 'Unauthenticated',
+          content: {
+            'application/json': { schema: resolver(ErrorResponseSchema) },
+          },
+        },
+        403: {
+          description: 'Forbidden',
+          content: {
+            'application/json': { schema: resolver(ErrorResponseSchema) },
+          },
+        },
+        404: {
+          description: 'Not found',
+          content: {
+            'application/json': { schema: resolver(ErrorResponseSchema) },
+          },
+        },
+      },
+    }),
+    zValidator('param', snapshotArtifactParamsSchema),
+    zValidator('query', snapshotChunkQuerySchema),
+    async (c) => {
+      const auth = await getAuth(c);
+      if (!auth) return syncError(c, 401, 'sync.auth_required');
+      const artifactStorage = options.snapshotArtifactStorage;
+      if (!artifactStorage) return syncError(c, 404, 'sync.not_found');
+
+      const partitionId = auth.partitionId ?? 'default';
+      const query = c.req.valid('query');
+      const requestedArtifactScopes = readSnapshotScopeValues(c, query.scopes);
+      const { artifactId } = c.req.valid('param');
+
+      const artifact = await readScopedSnapshotArtifact(options.db, artifactId);
+      if (!artifact) return syncError(c, 404, 'sync.not_found');
+      if (artifact.partitionId !== partitionId) {
+        return syncError(c, 403, 'sync.forbidden');
+      }
+
+      const nowIso = new Date().toISOString();
+      if (artifact.expiresAt <= nowIso) {
+        return syncError(c, 404, 'sync.not_found');
+      }
+
+      if (!requestedArtifactScopes) {
+        return syncError(
+          c,
+          400,
+          'sync.invalid_request',
+          'Snapshot artifact scope values are required'
+        );
+      }
+
+      try {
+        const resolved = await resolveEffectiveScopesForSubscriptions({
+          db: options.db,
+          auth,
+          subscriptions: [
+            {
+              id: artifact.subscriptionId,
+              table: artifact.table,
+              scopes: requestedArtifactScopes,
+              cursor: 0,
+              crdtStateVectors: [],
+            },
+          ],
+          handlers: handlerRegistry,
+          scopeCache: options.scopeCache,
+        });
+        const scopeAuth = resolved[0];
+        if (!scopeAuth || scopeAuth.status !== 'active') {
+          return syncError(c, 403, 'sync.forbidden');
+        }
+
+        const scopeHash = await scopesToSnapshotChunkScopeKey(scopeAuth.scopes);
+        const scopedArtifactKeyMatches =
+          artifact.scopeKey.startsWith('snapshot-artifact-v1:') &&
+          artifact.scopeKey.endsWith(`:scope:${scopeHash}`);
+        if (!scopedArtifactKeyMatches) {
+          return syncError(c, 403, 'sync.forbidden');
+        }
+      } catch (error) {
+        if (error instanceof InvalidSubscriptionScopeError) {
+          return syncError(c, 403, 'sync.forbidden');
+        }
+        throw error;
+      }
+
+      const etag = `"sha256:${artifact.sha256}"`;
+      const ifNoneMatch = c.req.header('if-none-match');
+      if (ifNoneMatch && ifNoneMatch === etag) {
+        return new Response(null, {
+          status: 304,
+          headers: {
+            ETag: etag,
+            'Cache-Control': 'private, max-age=0',
+            Vary: 'Authorization, X-Syncular-Snapshot-Scopes',
+          },
+        });
+      }
+
+      const limitResponse = responseBodyOverLimit(c, {
+        limit: 'maxSnapshotArtifactResponseBytes',
+        observed: artifact.byteLength,
+        max: maxSnapshotArtifactResponseBytes,
+      });
+      if (limitResponse) return limitResponse;
+
+      let body: Uint8Array | ReadableStream<Uint8Array> | null = null;
+      if (artifactStorage.readArtifactStream) {
+        body = await artifactStorage.readArtifactStream(artifact);
+      }
+      body ??= await artifactStorage.readArtifact(artifact);
+      if (!body) return syncError(c, 404, 'sync.not_found');
+
+      return new Response(body as BodyInit, {
+        status: 200,
+        headers: {
+          'Content-Type': 'application/octet-stream',
+          'Content-Length': String(artifact.byteLength),
+          ETag: etag,
+          'Cache-Control': 'private, max-age=0',
+          Vary: 'Authorization, X-Syncular-Snapshot-Scopes',
+          'X-Sync-Artifact-Id': artifact.artifactId,
+          'X-Sync-Artifact-Sha256': artifact.sha256,
+          'X-Sync-Artifact-Kind': artifact.artifactKind,
+          'X-Sync-Artifact-Compression': artifact.compression,
+          'X-Sync-Artifact-Manifest-Digest': artifact.manifestDigest,
+        },
+      });
+    }
+  );
+}

package/src/hono/routes.ts

@@ -0,0 +1,68 @@
+/**
+ * @syncular/server/hono - Sync routes for Hono
+ *
+ * Provides:
+ * - POST /      (combined push + pull in one round-trip)
+ * - GET  /snapshot-chunks/:chunkId (download encoded snapshot chunks)
+ * - GET  /snapshot-artifacts/:artifactId (download scoped snapshot artifacts)
+ * - GET  /realtime (optional WebSocket "wake up" notifications)
+ */
+
+import type { SqlFamily, SyncCoreDb } from '@syncular/server';
+import type { Hono } from 'hono';
+import { registerAuditRoutes } from './routes/audit';
+import { registerAuthLeaseRoutes } from './routes/auth-leases';
+import { registerCombinedSyncRoutes } from './routes/combined';
+import { createSyncRoutesContext } from './routes/context';
+import { registerHealthRoutes } from './routes/health';
+import { registerRealtimeRoutes } from './routes/realtime';
+import {
+  type CreateSyncRoutesOptions,
+  realtimeUnsubscribeMap,
+  type SyncAuthResult,
+  wsConnectionManagerMap,
+} from './routes/shared';
+import { registerSnapshotRoutes } from './routes/snapshots';
+import type { WebSocketConnectionManager } from './ws';
+
+export type {
+  CreateSyncRoutesOptions,
+  NormalizedSyncCorsConfig,
+  SyncAuthResult,
+  SyncCorsOptions,
+  SyncCorsOrigin,
+  SyncCorsOriginResolver,
+  SyncRoutesConfigWithRateLimit,
+} from './routes/shared';
+export { normalizeSyncCorsConfig } from './routes/shared';
+
+export function createSyncRoutes<
+  DB extends SyncCoreDb = SyncCoreDb,
+  Auth extends SyncAuthResult = SyncAuthResult,
+  F extends SqlFamily = SqlFamily,
+>(options: CreateSyncRoutesOptions<DB, Auth, F>): Hono {
+  const ctx = createSyncRoutesContext(options);
+
+  // Route registration order matters in Hono; keep it identical to the
+  // original monolithic factory.
+  registerHealthRoutes(ctx);
+  registerAuthLeaseRoutes(ctx);
+  registerAuditRoutes(ctx);
+  registerCombinedSyncRoutes(ctx);
+  registerSnapshotRoutes(ctx);
+  registerRealtimeRoutes(ctx);
+
+  return ctx.routes;
+}
+
+export function getSyncWebSocketConnectionManager(
+  routes: Hono
+): WebSocketConnectionManager | undefined {
+  return wsConnectionManagerMap.get(routes);
+}
+
+export function getSyncRealtimeUnsubscribe(
+  routes: Hono
+): (() => void) | undefined {
+  return realtimeUnsubscribeMap.get(routes);
+}

package/src/hono/validation.ts

@@ -0,0 +1,81 @@
+import {
+  createSyncularErrorResponse,
+  type SyncularErrorCode,
+} from '@syncular/core';
+import type { Context } from 'hono';
+import { validator as openApiValidator } from 'hono-openapi';
+
+type OpenApiValidatorArgs = Parameters<typeof openApiValidator>;
+type ValidationIssue = {
+  message?: unknown;
+  path?: unknown;
+};
+type ValidationResult = {
+  success: boolean;
+  error?: readonly ValidationIssue[];
+  target?: unknown;
+};
+
+function createSyncularValidator(
+  code: SyncularErrorCode
+): typeof openApiValidator {
+  return ((...args: OpenApiValidatorArgs) => {
+    const [target, schema, hook, options] = args;
+    return openApiValidator(
+      target,
+      schema,
+      async (result: ValidationResult, c: Context) => {
+        if (!result.success) {
+          return c.json(
+            createSyncularErrorResponse(code, {
+              message: 'Invalid request.',
+              details: {
+                target: String(result.target ?? target),
+                issues: serializeValidationIssues(result.error ?? []),
+              },
+            }),
+            400
+          );
+        }
+        return hook?.(result as never, c as never);
+      },
+      options
+    );
+  }) as typeof openApiValidator;
+}
+
+export const syncValidator = createSyncularValidator('sync.invalid_request');
+export const blobValidator = createSyncularValidator('blob.invalid_request');
+export const consoleValidator = createSyncularValidator(
+  'console.invalid_request'
+);
+
+function serializeValidationIssues(
+  issues: readonly ValidationIssue[]
+): Array<{ message: string; path?: string[] }> {
+  return issues.map((issue) => {
+    const path = serializeIssuePath(issue.path);
+    return {
+      message:
+        typeof issue.message === 'string'
+          ? issue.message
+          : 'Validation failed.',
+      ...(path.length > 0 ? { path } : {}),
+    };
+  });
+}
+
+function serializeIssuePath(path: unknown): string[] {
+  if (!Array.isArray(path)) return [];
+  return path.map((segment) => {
+    if (
+      segment &&
+      typeof segment === 'object' &&
+      'key' in segment &&
+      typeof segment.key !== 'symbol'
+    ) {
+      return String(segment.key);
+    }
+    return String(segment);
+  });
+}

package/src/hono/websocket-origin.ts

@@ -0,0 +1,131 @@
+import type { Context } from 'hono';
+
+function normalizeOrigin(origin: string): string | null {
+  try {
+    return new URL(origin).origin;
+  } catch {
+    return null;
+  }
+}
+
+function defaultPortForProtocol(protocol: string): string {
+  return protocol === 'https:' ? '443' : '80';
+}
+
+function matchesWildcardOriginPattern(origin: URL, pattern: string): boolean {
+  const match = pattern.match(
+    /^(https?):\/\/(\*\.)?(\[[^\]]+\]|[^/:]+)(?::(\*|\d+))?$/i
+  );
+  if (!match) {
+    return false;
+  }
+
+  const [, scheme, wildcardPrefix, rawHost, rawPort] = match;
+  const protocol = `${scheme!.toLowerCase()}:`;
+  if (origin.protocol !== protocol) {
+    return false;
+  }
+
+  const patternHostname = rawHost!.replace(/^\[(.*)\]$/, '$1').toLowerCase();
+  const originHostname = origin.hostname.toLowerCase();
+
+  if (wildcardPrefix) {
+    const suffix = `.${patternHostname}`;
+    if (
+      originHostname === patternHostname ||
+      !originHostname.endsWith(suffix)
+    ) {
+      return false;
+    }
+  } else if (originHostname !== patternHostname) {
+    return false;
+  }
+
+  if (rawPort === '*') {
+    return true;
+  }
+
+  const originPort = origin.port || defaultPortForProtocol(origin.protocol);
+  const patternPort = rawPort || defaultPortForProtocol(protocol);
+  return originPort === patternPort;
+}
+
+function isAllowedOriginMatch(origin: URL, pattern: string): boolean {
+  const exact = pattern.includes('*') ? null : normalizeOrigin(pattern);
+  if (exact) {
+    return origin.origin === exact;
+  }
+  return matchesWildcardOriginPattern(origin, pattern);
+}
+
+export function resolveAllowedOriginFromPatterns(
+  originHeader: string | null | undefined,
+  allowedOrigins: string | string[] | '*'
+): string | null {
+  if (allowedOrigins === '*') {
+    return '*';
+  }
+
+  const normalizedAllowedOrigins =
+    typeof allowedOrigins === 'string' ? [allowedOrigins] : allowedOrigins;
+
+  if (!originHeader) {
+    return null;
+  }
+
+  let parsedOrigin: URL;
+  try {
+    parsedOrigin = new URL(originHeader);
+  } catch {
+    return null;
+  }
+
+  return normalizedAllowedOrigins.some((pattern) =>
+    isAllowedOriginMatch(parsedOrigin, pattern)
+  )
+    ? originHeader
+    : null;
+}
+
+export function isRequestOriginAllowed(args: {
+  requestUrl: string;
+  originHeader?: string | null;
+  allowedOrigins?: string[] | '*';
+}): boolean {
+  if (args.allowedOrigins === '*') {
+    return true;
+  }
+
+  const origin = args.originHeader;
+  if (!origin) {
+    return true;
+  }
+
+  if (Array.isArray(args.allowedOrigins)) {
+    return (
+      resolveAllowedOriginFromPatterns(origin, args.allowedOrigins) !== null
+    );
+  }
+
+  const normalizedOrigin = normalizeOrigin(origin);
+  if (!normalizedOrigin) {
+    return false;
+  }
+
+  try {
+    return normalizedOrigin === new URL(args.requestUrl).origin;
+  } catch {
+    return false;
+  }
+}
+
+export function isWebSocketOriginAllowed(
+  c: Context,
+  allowedOrigins?: string[] | '*'
+): boolean {
+  return isRequestOriginAllowed({
+    requestUrl: c.req.url,
+    originHeader: c.req.raw.headers.get('origin') ?? c.req.header('origin'),
+    allowedOrigins,
+  });
+}