@absolutejs/sync 1.15.0 → 1.16.0

package/dist/engine/socket.d.ts

@@ -1,6 +1,23 @@
 import { Elysia } from 'elysia';
+import type { SyncConnectionStats } from './connection';
 import type { PresenceHub } from './presence';
 import type { SyncEngine } from './syncEngine';
+import type { FrameSerializer } from '../serializer';
+/**
+ * Diagnostic surfaced via {@link SyncSocketOptions.onSlow} when a connection
+ * trips the WS backpressure threshold. The host can log, kick, or charge the
+ * tenant extra via the meter.
+ */
+export type SlowConnectionEvent = {
+    /** Stable per-connection id from Elysia's `ws.id`. */
+    wsId: string;
+    /** Bytes the WS currently has queued waiting to send. */
+    bufferedAmount: number;
+    /** Per-connection counters at the moment of detection. */
+    stats: SyncConnectionStats;
+    /** Why the event fired. */
+    reason: 'buffer-threshold' | 'send-backpressure';
+};
 export type SyncSocketOptions = {
     /** The sync engine whose collections this socket serves. */
     engine: SyncEngine;
@@ -15,19 +32,56 @@ export type SyncSocketOptions = {
      * collection's `authorize`/`hydrate`/`match`. Defaults to an empty object.
      */
     resolveContext?: (data: Record<string, unknown>) => unknown | Promise<unknown>;
+    /**
+     * Bytes threshold for the per-connection WS send buffer. When
+     * `ws.getBufferedAmount()` exceeds this, `onSlow` fires once per
+     * crossing. Default `Infinity` (disabled).
+     *
+     * Added in 1.14.0.
+     */
+    maxBufferedBytes?: number;
+    /**
+     * Fired when the per-connection WS buffer crosses `maxBufferedBytes`, OR
+     * when `ws.send()` returns `-1` (Bun's backpressure signal). The signal
+     * re-arms once the WS reports `drain`. Pair with `closeOnSlow: true` to
+     * kick slow clients automatically, or use this hook to charge the
+     * tenant extra via `@absolutejs/metering`.
+     *
+     * Added in 1.14.0.
+     */
+    onSlow?: (event: SlowConnectionEvent) => void | Promise<void>;
+    /**
+     * Close the WS the first time a connection crosses `maxBufferedBytes`
+     * (or the `-1` send threshold). Default `false`. Client will reconnect
+     * and re-hydrate.
+     *
+     * Added in 1.14.0.
+     */
+    closeOnSlow?: boolean;
+    /**
+     * Wire-format serializer (1.16.0). Default `jsonSerializer` —
+     * preserves the pre-1.16 behavior. Both ends of the connection MUST
+     * use the same serializer; opt into a binary one (msgpack, cbor, or
+     * a custom layout) on BOTH this plugin AND the client to cut the
+     * bandwidth + parse CPU.
+     */
+    serializer?: FrameSerializer;
 };
 /**
- * Elysia WebSocket plugin for the Tier 3 sync engine. One socket multiplexes any
- * number of collection subscriptions: the client sends `subscribe`/`unsubscribe`
- * frames and receives `snapshot`/`diff`/`error` frames (see
- * {@link createSyncConnection}). Mount it once and drive `engine.applyChange`
- * from your mutations.
+ * Elysia WebSocket plugin for the sync engine. One socket multiplexes any
+ * number of collection subscriptions: the client sends `subscribe` /
+ * `unsubscribe` frames and receives `snapshot` / `diff` / `error` frames
+ * (see {@link createSyncConnection}). Mount once and drive
+ * `engine.applyChange` from your mutations.
  *
  * Uses Elysia's first-class `.ws()` rather than a hand-rolled stream — the
- * bidirectional channel carries both subscriptions and (later) mutations, and
+ * bidirectional channel carries both subscriptions and mutations, and
  * `ws.send` serializes frames for us.
+ *
+ * 1.14.0 adds WS-layer slow-client detection — see `maxBufferedBytes` /
+ * `onSlow` / `closeOnSlow`.
  */
-export declare const syncSocket: ({ engine, path, resolveContext, presence }: SyncSocketOptions) => Elysia<"", {
+export declare const syncSocket: ({ engine, path, resolveContext, presence, maxBufferedBytes, onSlow, closeOnSlow, serializer }: SyncSocketOptions) => Elysia<"", {
     decorator: {};
     store: {};
     derive: {};

package/dist/engine/syncEngine.d.ts

@@ -27,6 +27,16 @@ export type CrdtFields<Row> = {
 export declare class UnauthorizedError extends Error {
     constructor(subject: string);
 }
+/**
+ * Thrown by `engine.subscribe` / `engine.hydrate` (1.15.0+) when the caller's
+ * `AbortSignal` fires before the operation reaches a `Subscription` /
+ * resolved value. The `name` is `'AbortError'` to match the DOM-standard
+ * spelling so existing `catch (error) { if (error.name === 'AbortError') ... }`
+ * patterns work unchanged.
+ */
+export declare class AbortError extends Error {
+    constructor(reason?: string);
+}
 /**
  * Thrown when a mutation's write fails its table's schema (see
  * {@link defineSchema}). The message names the offending field.
@@ -50,6 +60,19 @@ export type SubscribeArgs<T, P, Ctx> = {
      * snapshot.
      */
     since?: number;
+    /**
+     * Cancellation handle (1.15.0). Two effects:
+     *  1. If the signal is already aborted when `subscribe` is called, the
+     *     engine throws {@link AbortError} immediately — no authorize, no
+     *     hydrate, no subscription.
+     *  2. If the signal fires AFTER the subscription is live, the engine
+     *     auto-calls `unsubscribe()`. The consumer never has to thread two
+     *     handles for the same lifetime.
+     *
+     * Backwards-compatible — omit `signal` and the engine behaves exactly
+     * as in pre-1.15.0.
+     */
+    signal?: AbortSignal;
 };
 export type Subscription<T> = {
     /** The result set at subscribe time — a snapshot (empty when resuming). */
@@ -97,8 +120,14 @@ export type SyncEngine = {
      * One-shot read: authorize and return a collection's current rows without
      * subscribing. Powers an Eden-typed HTTP hydrate route (and SSR). Rejects
      * with {@link UnauthorizedError} on deny.
+     *
+     * Pass `options.signal` (1.15.0+) to cancel the operation mid-flight —
+     * the engine throws {@link AbortError} after the next await point if
+     * the signal has fired.
      */
-    hydrate: (collection: string, params: unknown, ctx: unknown) => Promise<unknown[]>;
+    hydrate: (collection: string, params: unknown, ctx: unknown, options?: {
+        signal?: AbortSignal;
+    }) => Promise<unknown[]>;
     /**
      * Feed a committed change to `table` into the engine, fanning the resulting
      * diff to every live subscription of every collection that reads that table.

package/dist/index.d.ts

@@ -5,7 +5,9 @@ export type { ReactiveEvent, ReactiveHub, ReactiveListener } from './reactiveHub
 export { sync } from './plugin';
 export type { SyncPluginOptions, SyncRequestContext } from './plugin';
 export { syncSocket } from './engine/socket';
-export type { SyncSocketOptions } from './engine/socket';
+export type { SlowConnectionEvent, SyncSocketOptions } from './engine/socket';
+export { jsonSerializer } from './serializer';
+export type { FrameSerializer } from './serializer';
 export { syncCdc } from './engine/cdc';
 export type { SyncCdcOptions } from './engine/cdc';
 export { syncDevtools } from './devtools';

package/dist/index.js

@@ -187,15 +187,43 @@ var sync = ({
 // src/engine/socket.ts
 import { Elysia as Elysia2 } from "elysia";
 
+// src/serializer.ts
+var jsonSerializer = {
+  decode: (raw) => {
+    if (typeof raw === "string") {
+      try {
+        return JSON.parse(raw);
+      } catch {
+        return null;
+      }
+    }
+    if (raw instanceof Uint8Array) {
+      try {
+        return JSON.parse(new TextDecoder().decode(raw));
+      } catch {
+        return null;
+      }
+    }
+    if (raw instanceof ArrayBuffer) {
+      try {
+        return JSON.parse(new TextDecoder().decode(new Uint8Array(raw)));
+      } catch {
+        return null;
+      }
+    }
+    return raw;
+  },
+  encodeClient: (frame) => JSON.stringify(frame),
+  encodeServer: (frame) => JSON.stringify(frame)
+};
+
 // src/engine/connection.ts
-var parseFrame = (raw) => {
+var parseFrame = (raw, serializer) => {
   let value = raw;
-  if (typeof value === "string") {
-    try {
-      value = JSON.parse(value);
-    } catch {
+  if (typeof value === "string" || value instanceof Uint8Array || value instanceof ArrayBuffer) {
+    value = serializer.decode(raw);
+    if (value === null)
       return;
-    }
   }
   if (typeof value !== "object" || value === null) {
     return;
@@ -240,11 +268,23 @@ var parseFrame = (raw) => {
 var createSyncConnection = ({
   engine,
   ctx,
-  send,
-  presence
+  send: rawSend,
+  presence,
+  serializer = jsonSerializer
 }) => {
   const subscriptions = new Map;
   const presenceRooms = new Map;
+  let framesSent = 0;
+  let slowSendsRecent = 0;
+  const send = (frame) => {
+    const ret = rawSend(frame);
+    if (ret === -1) {
+      slowSendsRecent += 1;
+    } else {
+      framesSent += 1;
+      slowSendsRecent = 0;
+    }
+  };
   let pending = [];
   let pendingVersion;
   let flushScheduled = false;
@@ -289,7 +329,7 @@ var createSyncConnection = ({
     scheduleFlush();
   };
   const handle = async (raw) => {
-    const frame = parseFrame(raw);
+    const frame = parseFrame(raw, serializer);
     if (frame === undefined) {
       send({ type: "error", message: "Malformed sync frame" });
       return;
@@ -406,7 +446,13 @@ var createSyncConnection = ({
     }
     presenceRooms.clear();
   };
-  return { handle, close };
+  const stats = () => ({
+    framesSent,
+    presenceRoomCount: presenceRooms.size,
+    slowSendsRecent,
+    subscriptionCount: subscriptions.size
+  });
+  return { close, handle, stats };
 };
 
 // src/engine/socket.ts
@@ -414,27 +460,76 @@ var syncSocket = ({
   engine,
   path = "/sync/ws",
   resolveContext,
-  presence
+  presence,
+  maxBufferedBytes,
+  onSlow,
+  closeOnSlow = false,
+  serializer = jsonSerializer
 }) => {
   const connections = new Map;
+  const threshold = maxBufferedBytes ?? Infinity;
+  const fireSlow = (event) => {
+    if (!onSlow)
+      return;
+    try {
+      const ret = onSlow(event);
+      if (ret && typeof ret.then === "function") {
+        ret.catch((error) => {
+          console.error("[sync/socket] onSlow rejected:", error);
+        });
+      }
+    } catch (error) {
+      console.error("[sync/socket] onSlow threw:", error);
+    }
+  };
   return new Elysia2({ name: "@absolutejs/sync/socket" }).ws(path, {
     async open(ws) {
       const ctx = resolveContext ? await resolveContext(ws.data) : {};
-      connections.set(ws.id, createSyncConnection({
-        engine,
-        ctx,
-        presence,
-        send: (frame) => {
-          ws.send(frame);
-        }
-      }));
+      const bunWs = ws;
+      const tracked = {
+        connection: createSyncConnection({
+          engine,
+          ctx,
+          presence,
+          serializer,
+          send: (frame) => {
+            const payload = serializer.encodeServer(frame);
+            const ret = bunWs.send(typeof payload === "string" ? payload : payload);
+            const buffered = bunWs.getBufferedAmount?.() ?? 0;
+            const overBuffer = buffered > threshold;
+            const backpressure = ret === -1;
+            if ((overBuffer || backpressure) && !tracked.slowSignaled) {
+              tracked.slowSignaled = true;
+              fireSlow({
+                bufferedAmount: buffered,
+                reason: backpressure ? "send-backpressure" : "buffer-threshold",
+                stats: tracked.connection.stats(),
+                wsId: bunWs.id
+              });
+              if (closeOnSlow)
+                bunWs.close?.();
+            }
+            return ret;
+          }
+        }),
+        slowSignaled: false
+      };
+      connections.set(bunWs.id, tracked);
     },
     async message(ws, message) {
-      await connections.get(ws.id)?.handle(message);
+      await connections.get(ws.id)?.connection.handle(message);
+    },
+    drain(ws) {
+      const tracked = connections.get(ws.id);
+      if (tracked)
+        tracked.slowSignaled = false;
     },
     close(ws) {
-      connections.get(ws.id)?.close();
-      connections.delete(ws.id);
+      const tracked = connections.get(ws.id);
+      if (tracked) {
+        tracked.connection.close();
+        connections.delete(ws.id);
+      }
     }
   });
 };
@@ -994,6 +1089,32 @@ class UnauthorizedError extends Error {
   }
 }
 
+class AbortError extends Error {
+  constructor(reason) {
+    super(reason ?? "Aborted");
+    this.name = "AbortError";
+  }
+}
+var checkAborted = (signal) => {
+  if (signal?.aborted) {
+    throw new AbortError(signal.reason instanceof Error ? signal.reason.message : typeof signal.reason === "string" ? signal.reason : "Aborted");
+  }
+};
+var linkAbortToUnsubscribe = (signal, unsubscribe) => {
+  if (signal === undefined)
+    return;
+  if (signal.aborted) {
+    unsubscribe();
+    return;
+  }
+  const handler = () => {
+    try {
+      unsubscribe();
+    } catch {}
+  };
+  signal.addEventListener("abort", handler, { once: true });
+};
+
 class SchemaError extends Error {
   constructor(table, fieldName) {
     super(`Schema violation on "${table}": invalid field "${fieldName}"`);
@@ -1856,29 +1977,35 @@ var createSyncEngine = (options = {}) => {
     registerSearch: (collection) => {
       registry.set(collection.name, collection);
     },
-    subscribe: async ({ collection, params, ctx, onDiff, since }) => {
+    subscribe: async ({ collection, params, ctx, onDiff, since, signal }) => {
+      checkAborted(signal);
       const registered = registry.get(collection);
       if (registered === undefined) {
         throw new Error(`Unknown collection "${collection}"`);
       }
       const typedOnDiff = onDiff;
       const subscribeSet = subsFor(collection);
+      const wrapReturn = (sub) => {
+        checkAborted(signal);
+        linkAbortToUnsubscribe(signal, sub.unsubscribe);
+        return sub;
+      };
       const registeredKind = registered.kind;
       if (registeredKind === "join") {
         const joined = await subscribeJoin(collection, registered, params, ctx, typedOnDiff, subscribeSet);
-        return joined;
+        return wrapReturn(joined);
       }
       if (registeredKind === "graph") {
         const graphed = await subscribeGraph(collection, registered, params, ctx, typedOnDiff, subscribeSet);
-        return graphed;
+        return wrapReturn(graphed);
       }
       if (registeredKind === "reactive") {
         const reactived = await subscribeReactive(collection, registered, params, ctx, typedOnDiff, subscribeSet);
-        return reactived;
+        return wrapReturn(reactived);
       }
       if (registeredKind === "search") {
         const searched = await subscribeSearch(collection, registered, params, ctx, typedOnDiff, subscribeSet);
-        return searched;
+        return wrapReturn(searched);
       }
       const definition = registered;
       if (definition.authorize !== undefined) {
@@ -1920,31 +2047,35 @@ var createSyncEngine = (options = {}) => {
         subscribeSet.delete(subscription);
       };
       if (resuming) {
-        return {
+        return wrapReturn({
           initial: [],
           catchup: buildCatchup(since, tables, key, boundMatch),
           version: atVersion,
           unsubscribe
-        };
+        });
       }
-      return {
+      return wrapReturn({
         initial: view.rows(),
         version: atVersion,
         unsubscribe
-      };
+      });
     },
-    hydrate: async (collection, params, ctx) => {
+    hydrate: async (collection, params, ctx, options2) => {
+      const signal = options2?.signal;
+      checkAborted(signal);
       const definition = registry.get(collection);
       if (definition === undefined) {
         throw new Error(`Unknown collection "${collection}"`);
       }
       if (definition.authorize !== undefined) {
         const allowed = await definition.authorize(params, ctx);
+        checkAborted(signal);
         if (!allowed) {
           throw new UnauthorizedError(`hydrate collection "${collection}"`);
         }
       }
       const raw = [...await definition.hydrate(params, ctx)];
+      checkAborted(signal);
       const tables = definition.tables ?? [collection];
       const scopedTable = tables.length === 1 ? tables[0] : undefined;
       const rows = scopedTable !== undefined ? raw.map((row) => migrateRow(scopedTable, row)) : raw;
@@ -2754,10 +2885,11 @@ export {
   syncDevtools,
   syncCdc,
   sync,
+  jsonSerializer,
   createWriteBehindCache,
   createReactiveHub,
   createPresenceHub
 };
 
-//# debugId=202C826A4AA9A02264756E2164756E21
+//# debugId=B96A4C67BAC0D9FB64756E2164756E21
 //# sourceMappingURL=index.js.map