@syncular/server-hono 0.26.4 → 0.26.6

package/dist/admin.d.ts

@@ -10,7 +10,7 @@
  * commit metadata, scope activity, and reactions) and authorization is
  * entirely the host's and mandatory.
  */
-import { type SyncularAdmin } from '@syncular/server';
+import { type SyncularAdmin, type SyncularErrorHandler } from '@syncular/server';
 import { Hono } from 'hono';
 export interface AdminAuthContext {
     /** The partition the request targets (from the query string / route). */
@@ -30,6 +30,11 @@ export interface SyncularAdminRoutesOptions {
      * When unset, `partition` is required on every data endpoint.
      */
     readonly defaultPartition?: string;
+    /**
+     * Host error reporting: receives every exception that is not a
+     * `SyncError`, which answers 500 `sync.internal_error` (§10.2).
+     */
+    readonly onError?: SyncularErrorHandler;
 }
 /**
  * Build the mountable admin sub-app. Mount it under any prefix, e.g.

package/dist/admin.js

@@ -10,15 +10,9 @@
  * commit metadata, scope activity, and reactions) and authorization is
  * entirely the host's and mandatory.
  */
-import { errorBody, matchesRingQuery, SyncError, } from '@syncular/server';
+import { adapterSyncError, errorBody, matchesRingQuery, SyncError, } from '@syncular/server';
 import { Hono } from 'hono';
 import { ADMIN_CONSOLE_HTML } from './admin-page.js';
-function jsonError(error) {
-    const sync = error instanceof SyncError
-        ? error
-        : new SyncError('sync.invalid_request', String(error));
-    return Response.json(errorBody(sync), { status: sync.httpStatus });
-}
 function intParam(value, fallback) {
     if (value === undefined)
         return fallback;
@@ -35,6 +29,12 @@ export function createSyncularAdminRoutes(admin, options) {
         throw new Error('createSyncularAdminRoutes: an `authorize` guard is required — admin never mounts default-open');
     }
     const app = new Hono();
+    const jsonError = (error) => {
+        const sync = adapterSyncError(error, options.onError, 'admin');
+        return Response.json(errorBody(sync), { status: sync.httpStatus });
+    };
+    // Throws outside a route's own try, such as from `authorize`.
+    app.onError((error) => jsonError(error));
     /** Resolve the request's partition (query, else default) — required. */
     function partitionOf(c) {
         const partition = c.req.query('partition') ?? options.defaultPartition;

package/dist/index.js

@@ -4,17 +4,24 @@
  * Mounts the §1.1 routes including sync, registered operations, segments, and
  * blobs. Realtime upgrades are runtime-specific and stay with the host.
  */
-import { encodeSegmentBody, errorBody, handleBlobDownload, handleBlobUpload, handleBlobUploadGrant, handleSegmentDownload, handleRemoteOperation, handleSyncRequest, SSP2_CONTENT_TYPE, SyncError, } from '@syncular/server';
+import { adapterSyncError, encodeSegmentBody, encodeSegmentStream, errorBody, handleBlobDownload, handleBlobUpload, handleBlobUploadGrant, openSegmentDownload, handleRemoteOperation, handleSyncRequest, SEGMENT_STREAM_THRESHOLD_BYTES, SSP2_CONTENT_TYPE, SyncError, } from '@syncular/server';
 import { Hono } from 'hono';
 export * from './admin.js';
-function errorResponse(error) {
-    const sync = error instanceof SyncError
-        ? error
-        : new SyncError('sync.invalid_request', String(error));
-    return Response.json(errorBody(sync), { status: sync.httpStatus });
-}
 export function createSyncularHono(options) {
     const app = new Hono();
+    // A `SyncError` answers with its catalog status. Any other exception goes
+    // to `config.onError` and answers 500 `sync.internal_error` (§10.2).
+    const errorResponse = (error, route = 'sync') => {
+        const sync = adapterSyncError(error, options.config.onError, route);
+        return Response.json(errorBody(sync), { status: sync.httpStatus });
+    };
+    // Throws outside a route's own try, such as from `authenticate`.
+    app.onError((error, c) => {
+        const segment = c.req.path.split('/')[1];
+        return errorResponse(error, segment === 'operations' || segment === 'segments' || segment === 'blobs'
+            ? segment
+            : 'sync');
+    });
     app.post('/sync', async (c) => {
         const contentType = c.req.header('content-type')?.split(';')[0]?.trim();
         if (contentType !== SSP2_CONTENT_TYPE) {
@@ -49,29 +56,51 @@ export function createSyncularHono(options) {
         const auth = await options.authenticate(c.req.raw);
         if (auth === null)
             return errorResponse(new SyncError('sync.auth_required'));
-        const bytes = new Uint8Array(await c.req.arrayBuffer());
-        const out = await handleRemoteOperation(bytes, { ...options.config, ...auth }, options.operations);
-        return c.body(out.slice().buffer, 200, {
-            'Content-Type': 'application/vnd.syncular.operations.v1+json',
-        });
+        try {
+            const bytes = new Uint8Array(await c.req.arrayBuffer());
+            const out = await handleRemoteOperation(bytes, { ...options.config, ...auth }, options.operations);
+            return c.body(out.slice().buffer, 200, {
+                'Content-Type': 'application/vnd.syncular.operations.v1+json',
+            });
+        }
+        catch (error) {
+            return errorResponse(error, 'operations');
+        }
     });
     app.get('/segments/:segmentId', async (c) => {
         const auth = await options.authenticate(c.req.raw);
         if (auth === null)
             return errorResponse(new SyncError('sync.auth_required'));
         try {
-            const result = await handleSegmentDownload({ ...options.config, ...auth }, {
+            const result = await openSegmentDownload({ ...options.config, ...auth }, {
                 segmentId: c.req.param('segmentId'),
                 scopesHeader: c.req.header('x-syncular-scopes') ?? '{}',
             });
             if (c.req.header('if-none-match') === result.headers.ETag) {
+                await result.body.cancel();
                 return c.body(null, 304, result.headers);
             }
+            const acceptEncoding = c.req.header('accept-encoding');
+            if (result.byteLength > SEGMENT_STREAM_THRESHOLD_BYTES) {
+                // A large segment (a sqlite image) is relayed without buffering;
+                // only a streaming codec applies (§5.8).
+                const encoded = encodeSegmentStream(result.body, acceptEncoding);
+                return new Response(encoded.body, {
+                    status: 200,
+                    headers: {
+                        ...result.headers,
+                        ...(encoded.contentEncoding !== undefined
+                            ? { 'Content-Encoding': encoded.contentEncoding }
+                            : { 'Content-Length': String(result.byteLength) }),
+                    },
+                });
+            }
             // §5.8 shipped default: compress the body per Accept-Encoding
             // (zstd preferred, gzip fallback, identity otherwise). Content
             // addresses are over the uncompressed bytes (§5.1) — fetch
             // decodes transparently on the client.
-            const encoded = encodeSegmentBody(result.bytes, c.req.header('accept-encoding'));
+            const bytes = new Uint8Array(await new Response(result.body).arrayBuffer());
+            const encoded = encodeSegmentBody(bytes, acceptEncoding);
             return c.body(encoded.bytes.slice().buffer, 200, {
                 ...result.headers,
                 ...(encoded.contentEncoding !== undefined
@@ -80,7 +109,7 @@ export function createSyncularHono(options) {
             });
         }
         catch (error) {
-            return errorResponse(error);
+            return errorResponse(error, 'segments');
         }
     });
     // §5.9.3: blob upload with server-side content-address verification.
@@ -102,7 +131,7 @@ export function createSyncularHono(options) {
             return c.body(null, 200);
         }
         catch (error) {
-            return errorResponse(error);
+            return errorResponse(error, 'blobs');
         }
     });
     // §5.9.3: presigned-upload grant — mint a direct-to-storage PUT URL.
@@ -122,7 +151,7 @@ export function createSyncularHono(options) {
             return c.json(grant, 200);
         }
         catch (error) {
-            return errorResponse(error);
+            return errorResponse(error, 'blobs');
         }
     });
     // §5.9.5: blob download, re-authorized against referencing rows. When the
@@ -146,7 +175,7 @@ export function createSyncularHono(options) {
             });
         }
         catch (error) {
-            return errorResponse(error);
+            return errorResponse(error, 'blobs');
         }
     });
     return app;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/server-hono",
-  "version": "0.26.4",
+  "version": "0.26.6",
   "description": "Hono adapter for the Syncular sync server",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -45,10 +45,10 @@
     "!dist/**/*.test.d.ts"
   ],
   "dependencies": {
-    "@syncular/server": "0.26.4",
+    "@syncular/server": "0.26.6",
     "hono": "^4.12.34"
   },
   "devDependencies": {
-    "@syncular/core": "0.26.4"
+    "@syncular/core": "0.26.6"
   }
 }

package/src/admin.ts

@@ -11,12 +11,14 @@
  * entirely the host's and mandatory.
  */
 import {
+  adapterSyncError,
   errorBody,
   matchesRingQuery,
   type RingEventQuery,
   type ReactionStatus,
   SyncError,
   type SyncularAdmin,
+  type SyncularErrorHandler,
   type SyncularServerEvent,
 } from '@syncular/server';
 import { Hono } from 'hono';
@@ -41,14 +43,11 @@ export interface SyncularAdminRoutesOptions {
    * When unset, `partition` is required on every data endpoint.
    */
   readonly defaultPartition?: string;
-}
-
-function jsonError(error: unknown): Response {
-  const sync =
-    error instanceof SyncError
-      ? error
-      : new SyncError('sync.invalid_request', String(error));
-  return Response.json(errorBody(sync), { status: sync.httpStatus });
+  /**
+   * Host error reporting: receives every exception that is not a
+   * `SyncError`, which answers 500 `sync.internal_error` (§10.2).
+   */
+  readonly onError?: SyncularErrorHandler;
 }
 
 function intParam(value: string | undefined, fallback: number): number {
@@ -72,6 +71,12 @@ export function createSyncularAdminRoutes(
     );
   }
   const app = new Hono();
+  const jsonError = (error: unknown): Response => {
+    const sync = adapterSyncError(error, options.onError, 'admin');
+    return Response.json(errorBody(sync), { status: sync.httpStatus });
+  };
+  // Throws outside a route's own try, such as from `authorize`.
+  app.onError((error) => jsonError(error));
 
   /** Resolve the request's partition (query, else default) — required. */
   function partitionOf(c: {

package/src/index.ts

@@ -5,17 +5,21 @@
  * blobs. Realtime upgrades are runtime-specific and stay with the host.
  */
 import {
+  adapterSyncError,
   encodeSegmentBody,
+  encodeSegmentStream,
   errorBody,
   handleBlobDownload,
   handleBlobUpload,
   handleBlobUploadGrant,
-  handleSegmentDownload,
+  openSegmentDownload,
   handleRemoteOperation,
   type RemoteOperationRegistry,
   handleSyncRequest,
+  SEGMENT_STREAM_THRESHOLD_BYTES,
   SSP2_CONTENT_TYPE,
   SyncError,
+  type SyncularErrorRoute,
   type SyncServerConfig,
 } from '@syncular/server';
 import { Hono } from 'hono';
@@ -31,16 +35,27 @@ export interface SyncularHonoOptions {
   ) => Promise<{ actorId: string; partition: string } | null>;
 }
 
-function errorResponse(error: unknown): Response {
-  const sync =
-    error instanceof SyncError
-      ? error
-      : new SyncError('sync.invalid_request', String(error));
-  return Response.json(errorBody(sync), { status: sync.httpStatus });
-}
-
 export function createSyncularHono(options: SyncularHonoOptions): Hono {
   const app = new Hono();
+  // A `SyncError` answers with its catalog status. Any other exception goes
+  // to `config.onError` and answers 500 `sync.internal_error` (§10.2).
+  const errorResponse = (
+    error: unknown,
+    route: SyncularErrorRoute = 'sync',
+  ): Response => {
+    const sync = adapterSyncError(error, options.config.onError, route);
+    return Response.json(errorBody(sync), { status: sync.httpStatus });
+  };
+  // Throws outside a route's own try, such as from `authenticate`.
+  app.onError((error, c) => {
+    const segment = c.req.path.split('/')[1];
+    return errorResponse(
+      error,
+      segment === 'operations' || segment === 'segments' || segment === 'blobs'
+        ? segment
+        : 'sync',
+    );
+  });
 
   app.post('/sync', async (c) => {
     const contentType = c.req.header('content-type')?.split(';')[0]?.trim();
@@ -84,15 +99,19 @@ export function createSyncularHono(options: SyncularHonoOptions): Hono {
     const auth = await options.authenticate(c.req.raw);
     if (auth === null)
       return errorResponse(new SyncError('sync.auth_required'));
-    const bytes = new Uint8Array(await c.req.arrayBuffer());
-    const out = await handleRemoteOperation(
-      bytes,
-      { ...options.config, ...auth },
-      options.operations,
-    );
-    return c.body(out.slice().buffer as ArrayBuffer, 200, {
-      'Content-Type': 'application/vnd.syncular.operations.v1+json',
-    });
+    try {
+      const bytes = new Uint8Array(await c.req.arrayBuffer());
+      const out = await handleRemoteOperation(
+        bytes,
+        { ...options.config, ...auth },
+        options.operations,
+      );
+      return c.body(out.slice().buffer as ArrayBuffer, 200, {
+        'Content-Type': 'application/vnd.syncular.operations.v1+json',
+      });
+    } catch (error) {
+      return errorResponse(error, 'operations');
+    }
   });
 
   app.get('/segments/:segmentId', async (c) => {
@@ -100,7 +119,7 @@ export function createSyncularHono(options: SyncularHonoOptions): Hono {
     if (auth === null)
       return errorResponse(new SyncError('sync.auth_required'));
     try {
-      const result = await handleSegmentDownload(
+      const result = await openSegmentDownload(
         { ...options.config, ...auth },
         {
           segmentId: c.req.param('segmentId'),
@@ -108,16 +127,32 @@ export function createSyncularHono(options: SyncularHonoOptions): Hono {
         },
       );
       if (c.req.header('if-none-match') === result.headers.ETag) {
+        await result.body.cancel();
         return c.body(null, 304, result.headers);
       }
+      const acceptEncoding = c.req.header('accept-encoding');
+      if (result.byteLength > SEGMENT_STREAM_THRESHOLD_BYTES) {
+        // A large segment (a sqlite image) is relayed without buffering;
+        // only a streaming codec applies (§5.8).
+        const encoded = encodeSegmentStream(result.body, acceptEncoding);
+        return new Response(encoded.body, {
+          status: 200,
+          headers: {
+            ...result.headers,
+            ...(encoded.contentEncoding !== undefined
+              ? { 'Content-Encoding': encoded.contentEncoding }
+              : { 'Content-Length': String(result.byteLength) }),
+          },
+        });
+      }
       // §5.8 shipped default: compress the body per Accept-Encoding
       // (zstd preferred, gzip fallback, identity otherwise). Content
       // addresses are over the uncompressed bytes (§5.1) — fetch
       // decodes transparently on the client.
-      const encoded = encodeSegmentBody(
-        result.bytes,
-        c.req.header('accept-encoding'),
+      const bytes = new Uint8Array(
+        await new Response(result.body).arrayBuffer(),
       );
+      const encoded = encodeSegmentBody(bytes, acceptEncoding);
       return c.body(encoded.bytes.slice().buffer as ArrayBuffer, 200, {
         ...result.headers,
         ...(encoded.contentEncoding !== undefined
@@ -125,7 +160,7 @@ export function createSyncularHono(options: SyncularHonoOptions): Hono {
           : {}),
       });
     } catch (error) {
-      return errorResponse(error);
+      return errorResponse(error, 'segments');
     }
   });
 
@@ -150,7 +185,7 @@ export function createSyncularHono(options: SyncularHonoOptions): Hono {
       );
       return c.body(null, 200);
     } catch (error) {
-      return errorResponse(error);
+      return errorResponse(error, 'blobs');
     }
   });
 
@@ -176,7 +211,7 @@ export function createSyncularHono(options: SyncularHonoOptions): Hono {
       );
       return c.json(grant, 200);
     } catch (error) {
-      return errorResponse(error);
+      return errorResponse(error, 'blobs');
     }
   });
 
@@ -206,7 +241,7 @@ export function createSyncularHono(options: SyncularHonoOptions): Hono {
         ...result.headers,
       });
     } catch (error) {
-      return errorResponse(error);
+      return errorResponse(error, 'blobs');
     }
   });