@syncular/server 0.1.2 → 0.2.0

package/src/hono/routes/snapshots.ts

@@ -1,345 +0,0 @@
-/**
- * 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

@@ -1,68 +0,0 @@
-/**
- * @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

@@ -1,81 +0,0 @@
-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

@@ -1,131 +0,0 @@
-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,
-  });
-}