@pylonsync/sync 0.22.47 → 0.22.50

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 import { LocalStore } from "./local-store";
-import { MutationQueue } from "./mutation-queue";
+import { MutationQueue, type Outbox } from "./mutation-queue";
+import { UploadManager, type QueuedUploadHandle, type UploadAttachTarget } from "./upload-queue";
+import type { FileVisibility } from "./upload";
 import { type RoomError, type RoomMember, type RoomSubscriber } from "./room-subscriptions";
 import { SessionResolver } from "./session-resolver";
 export { RoomSubscriptions, rowRoom, type RoomError, type RoomErrorCode, type RoomMember, type RoomMessage, type RoomMessageSubscriber, type RoomSubscriber, } from "./room-subscriptions";
@@ -8,8 +10,13 @@ export type { ReplicaPersistence } from "./persistence";
 export { BEARER_REJECTED_HEADER, bearerRejected, buildRequest, clearRejectedToken, pylonFetch, pylonFetchRaw, PylonHttpError, resolveBaseUrl, } from "./transport";
 export type { PylonRequestInit, TransportConfig } from "./transport";
 export { LocalStore } from "./local-store";
-export { MutationQueue, MutationRejectedError, type MutationQueuePersistence, type PendingMutation, } from "./mutation-queue";
+export { MutationQueue, MutationRejectedError, type MutationQueuePersistence, type Outbox, type OutboxItem, type PendingMutation, } from "./mutation-queue";
+/** The store channel the outbox notifies on. `store.subscribe(cb,
+ *  OUTBOX_CHANNEL)` hears outbox changes and no entity changes. */
+export declare const OUTBOX_CHANNEL = "$outbox";
 export { generateId } from "./ids";
+export { uploadBytes, type FileVisibility, type UploadBytesOptions, type UploadedFile, } from "./upload";
+export { DEFAULT_MAX_QUEUED_UPLOAD_BYTES, IndexedDBUploadStore, LOCAL_FILE_PREFIX, localUploadId, MemoryUploadStore, UploadQueueFullError, UploadRejectedError, type QueuedUpload, type QueuedUploadHandle, type UploadAttachTarget, type UploadStore, } from "./upload-queue";
 export type { ChangeEvent, ClientChange, PullResponse, PushOpResult, PushResponse, ReactiveMessage, ReactiveSpec, ResolvedSession, Row, SyncConnectionStatus, SyncCursor, TransportType, } from "./types";
 export { defaultStorage, createWriteThroughStorage, type Storage, } from "./storage";
 import type { ReactiveMessage, ResolvedSession, Row, SyncConnectionStatus, SyncCursor, TransportType } from "./types";
@@ -105,6 +112,9 @@ export interface SyncEngineConfig {
      * its own leader (the pre-multi-tab semantics).
      */
     multiTab?: boolean;
+    /** Cap on the bytes `queueUpload` keeps on the device. Default 200 MB.
+     *  Past it `queueUpload` throws `UploadQueueFullError`. */
+    maxQueuedUploadBytes?: number;
 }
 export declare class SyncEngine {
     private config;
@@ -212,6 +222,8 @@ export declare class SyncEngine {
     private persistDegraded;
     readonly store: LocalStore;
     readonly mutations: MutationQueue;
+    /** Files queued with `queueUpload`, sent when there is a network. */
+    readonly uploads: UploadManager;
     /**
      * Stable per-client identifier. Minted on first construction, not
      * necessarily persisted (depends on what the host provides).
@@ -399,6 +411,65 @@ export declare class SyncEngine {
      * dev HUD's sync row; also handy for a "saving…" indicator.
      */
     pendingCount(): number;
+    private outboxCache;
+    /**
+     * Writes made here that the server has not applied yet (`pending`:
+     * offline, or waiting for a sign-in), and writes the server rejected
+     * (`failed`, with its error). Oldest first. The same object is
+     * returned until the queue changes, so it can back
+     * `useSyncExternalStore`. Changes notify store subscribers on
+     * `OUTBOX_CHANNEL`.
+     */
+    outbox(): Outbox;
+    /**
+     * Send a failed write again, with `data` (when given) merged over the
+     * fields it set. The write is applied locally again at once (the
+     * rejection rolled it back) and queued under a new op id. Settles like
+     * `insert`: resolves with the new op id once the server applies it or
+     * it is queued offline, and rejects with a `MutationRejectedError` when
+     * the server rejects it again (it is then failed again, with the new
+     * error).
+     *
+     * A write is only ever sent as the user who made it. Throws
+     * `MutationRejectedError` with code `OWNER_MISMATCH` when someone else
+     * is signed in, and `OWNER_UNKNOWN` when it is not yet known who is
+     * signed in (or the write predates owner tracking). Dismiss those.
+     */
+    retryWrite(id: string, data?: Row): Promise<string>;
+    /** Drop a failed write after the user has seen it. Its local change
+     *  was already rolled back. Returns false when there is no failed write
+     *  with that id; a pending write cannot be dismissed. */
+    dismissWrite(id: string): boolean;
+    /**
+     * Keep a file on the device and upload it when there is a network, then
+     * set it on the record it belongs to. Returns at once.
+     *
+     * At once, `attach.entity`/`attach.id` gets `attach.field` (and
+     * `attach.urlField`, when given) = `local:<localId>` as a queued write,
+     * so the record shows the file from the device (`uploadLocalUrl`). When
+     * the upload finishes, a second queued write sets the file's id (and
+     * URL). Both are ordinary writes: policies and owner rules apply.
+     *
+     * The file is sent only as the user who queued it. Throws
+     * `UploadQueueFullError` past `maxQueuedUploadBytes`. Pending and failed
+     * uploads show in `outbox()` with kind `"upload"`; retry and dismiss them
+     * with `retryWrite` / `dismissWrite`.
+     */
+    queueUpload(file: Blob, opts: {
+        attach: UploadAttachTarget;
+        filename?: string;
+        contentType?: string;
+        visibility?: FileVisibility;
+    }): Promise<QueuedUploadHandle>;
+    /** An object URL for a queued file (`local:<localId>` without the
+     *  prefix), or null when no queued upload has that id. */
+    uploadLocalUrl(localId: string): string | null;
+    /** Apply the queued writes to the replica again after a reload. An
+     *  optimistic change lives only in memory, so without this a row
+     *  written offline vanished from the screen on reload (it was still
+     *  queued and still reached the server later). Oldest first, so an
+     *  update of a row inserted offline finds the row. */
+    private reapplyPendingWrites;
     /**
      * Mutate connection status + notify subscribers. Idempotent — same-
      * status calls are a no-op so the WS onopen → connected transition

package/dist/multi-tab-orchestrator.d.ts

@@ -51,6 +51,10 @@ export interface MultiTabOrchestratorHooks {
     /** Leader → followers: the leader's push failed transiently and
      *  these op ids stay queued for retry. */
     onMutationsQueued(opIds: string[]): void;
+    /** Another tab retried or dismissed these failed writes. */
+    onMutationsRemoved(opIds: string[]): void;
+    /** Another tab changed the upload queue in storage. */
+    onUploadsChanged(): void;
     /** Leader → follower: a binary frame from the WS. Engine routes
      *  to its local binary handlers. */
     onBinaryReceived(bytes: Uint8Array): void;

package/dist/mutation-queue.d.ts

@@ -29,6 +29,9 @@ export interface PendingMutation {
     error?: string;
     /** Server error code for a failed mutation, when the server sent one. */
     errorCode?: string;
+    /** When the write was made, in ms since the epoch. Missing on writes
+     *  queued by an older client; those sort first. */
+    createdAt?: number;
     /** User id the write was made as (`null` = anonymous). Persisted with
      *  the queue so a write is only ever pushed as the user who made it.
      *  `undefined` = unknown (queued by an older client). */
@@ -44,6 +47,32 @@ export interface PendingMutation {
      *  before the mutation; `undefined` = not captured (inserts). */
     prevRow?: Row | null;
 }
+/** One write as the outbox shows it. */
+export interface OutboxItem {
+    /** Op id. Pass it to `retryWrite` / `dismissWrite`. */
+    id: string;
+    entity: string;
+    rowId: string;
+    /** `"upload"` is a file from `queueUpload`; `entity`/`rowId` is the
+     *  record it attaches to. */
+    kind: "insert" | "update" | "delete" | "upload";
+    /** The fields the write sets. Empty for a delete. For an upload:
+     *  `field`, `urlField`, `filename`, `contentType`, `size`. */
+    data: Row;
+    /** When the write was made, in ms since the epoch (0 when unknown). */
+    createdAt: number;
+    /** The server's message, for a failed write. */
+    error?: string;
+    /** The server's error code (`POLICY_DENIED`, `VALIDATION_FAILED`, ...),
+     *  for a failed write. */
+    errorCode?: string;
+}
+/** Writes not yet on the server, and writes the server rejected. */
+export interface Outbox {
+    pending: OutboxItem[];
+    failed: OutboxItem[];
+}
+export declare function toOutboxItem(m: PendingMutation): OutboxItem;
 /**
  * Optional persistence backend. The default IndexedDB persistence
  * layer supports incremental writes with `saveChanges`. Custom backends
@@ -61,7 +90,18 @@ export declare class MutationQueue {
     /** Callers waiting for a mutation's outcome, by op id. Memory-only:
      *  a promise cannot outlive the page that created it. */
     private waiters;
+    /** Called after every change to what the queue holds or to a write's
+     *  status. The engine turns it into a store notification so the outbox
+     *  re-renders. */
+    private changeListener;
+    /** Bumped on every change; lets readers cache a snapshot. */
+    private _version;
     constructor(persistence?: MutationQueuePersistence);
+    /** Set the one listener called after each queue change. */
+    setChangeListener(listener: (() => void) | null): void;
+    /** Changes so far. Equal versions mean the same contents. */
+    version(): number;
+    private changed;
     /**
      * Attach a persistence backend after construction. The SyncEngine
      * swaps in IndexedDB-backed persistence once the DB has opened.
@@ -79,8 +119,27 @@ export declare class MutationQueue {
      *  entry with the same op_id is already queued — a follower
      *  retrying its forward of the same op shouldn't double-queue on
      *  the leader. */
-    add(change: ClientChange, prevRow?: Row | null, owner?: string | null, ownerPending?: boolean): string;
+    add(change: ClientChange, prevRow?: Row | null, owner?: string | null, ownerPending?: boolean, createdAt?: number): string;
     pending(): PendingMutation[];
+    /** Writes the server rejected, oldest first. They stay until the user
+     *  retries or dismisses them. */
+    failed(): PendingMutation[];
+    /**
+     * Queue a failed write again under a new op id, with `data` (when
+     * given) merged over the original change's fields. The failed entry is
+     * removed in the same persistence write, so a reload never sees both.
+     * The new write keeps the original's owner and `createdAt`. `prevRow`
+     * is the row before the caller re-applied the write locally, for the
+     * rollback if the server rejects it again. Returns the new op id.
+     *
+     * The server forgets a rejected op id (it never applied it), so the new
+     * id cannot be applied alongside the old one.
+     */
+    retry(id: string, data: Row | undefined, prevRow: Row | null | undefined): string;
+    /** Drop a failed write after the user has seen it. Returns false when
+     *  there is no failed write with that id (pending writes cannot be
+     *  dismissed: they may already be on the server). */
+    dismiss(id: string): boolean;
     /** Look up a queued mutation by op id (any status). Used by the
      *  follower's mutations-failed handler to reach the captured
      *  `prevRow` for rollback. */
@@ -145,3 +204,5 @@ export declare class MutationQueue {
     /** Fire-and-forget persistence write. */
     private flush;
 }
+/** Oldest first; writes without `createdAt` (older clients) first of all. */
+export declare function byCreatedAt(list: PendingMutation[]): PendingMutation[];

package/dist/test-harness/server.d.ts

@@ -129,10 +129,16 @@ export declare class TestServer {
     /** When set, `/api/sync/push` waits for this promise before it
      *  answers. Lets a test queue a write while a push is in flight. */
     pushGate: Promise<void> | null;
+    /** The file endpoints (`/api/files/init`, PUT, `/api/files/confirm`). */
+    readonly files: TestFileServer;
     /** Entities whose pushed writes are rejected per op, like a write
      *  policy denial on the real server (HTTP 200 with a per-op error). */
     private deniedWrites;
     denyWrites(entity: string, code?: string, message?: string): void;
+    /** Reject a pushed insert/update of `entity` whose fields match
+     *  `predicate`, like a write policy that checks a field value. */
+    private conditionalDenials;
+    rejectWritesWhere(entity: string, predicate: (data: Row) => boolean, code?: string, message?: string): void;
     private nextPushOutcome;
     primeNextPushOutcome(o: {
         kind: "network";
@@ -223,3 +229,81 @@ export declare class TestServer {
     private bumpSeq;
     private appendLog;
 }
+/**
+ * In-memory stand-in for the runtime's file routes. Records every request
+ * so a test can count uploads, and lets a test refuse a file (`rejectInit`)
+ * or drop the connection during the next PUT (`dropNextPut`).
+ */
+export declare class TestFileServer {
+    private readonly server;
+    private nextId;
+    private slots;
+    readonly stored: Map<string, {
+        filename: string;
+        size: number;
+        owner: string | null;
+    }>;
+    initCount: number;
+    putCount: number;
+    private rejection;
+    private dropPut;
+    constructor(server: TestServer);
+    /** Refuse every init with this status, like a type or size check. */
+    rejectInit(status: number, code: string, message: string): void;
+    clearRejection(): void;
+    /** When set, every PUT waits for it before it answers. */
+    putGate: Promise<void> | null;
+    /** The next PUT fails like a dropped connection (no status). */
+    dropNextPut(): void;
+    init(token: string | undefined, body: {
+        filename?: string;
+        size?: number;
+    }): {
+        status: number;
+        body: {
+            error: {
+                code: string;
+                message: string;
+            };
+            uploadUrl?: undefined;
+            assetId?: undefined;
+        };
+    } | {
+        status: number;
+        body: {
+            uploadUrl: string;
+            assetId: string;
+            error?: undefined;
+        };
+    };
+    put(id: string, bytes: unknown): {
+        status: number;
+        body: {
+            error: {
+                code: string;
+            };
+        };
+    } | {
+        status: number;
+        body: null;
+    };
+    confirm(token: string | undefined, id: string): {
+        status: number;
+        body: {
+            error: {
+                code: string;
+            };
+            id?: undefined;
+            url?: undefined;
+            size?: undefined;
+        };
+    } | {
+        status: number;
+        body: {
+            id: string;
+            url: string;
+            size: number;
+            error?: undefined;
+        };
+    };
+}

package/dist/upload-queue.d.ts

@@ -0,0 +1,190 @@
+import type { OutboxItem } from "./mutation-queue";
+import type { TransportConfig } from "./transport";
+import { type FileVisibility, type UploadedFile } from "./upload";
+/** Where an upload is attached when it finishes: `entity`/`id` gets
+ *  `field` = the file id, and `urlField` (when set) = the file URL. */
+export interface UploadAttachTarget {
+    entity: string;
+    id: string;
+    field: string;
+    urlField?: string;
+}
+/** One queued upload, as stored. */
+export interface QueuedUpload {
+    /** `upl_...`. The record's field holds `local:<localId>` until the
+     *  upload finishes. */
+    localId: string;
+    blob: Blob;
+    filename: string;
+    contentType: string;
+    size: number;
+    visibility: FileVisibility;
+    /** User id the upload was made as (`null` = anonymous). */
+    owner: string | null;
+    /** Made before this run knew who is signed in; stamped by the first
+     *  resolved session. */
+    ownerPending?: boolean;
+    attach: UploadAttachTarget;
+    createdAt: number;
+    status: "pending" | "failed";
+    error?: string;
+    errorCode?: string;
+    /** Set once the server confirmed the file, before the attach update is
+     *  queued. A restart in between attaches without uploading again. */
+    uploaded?: UploadedFile;
+}
+/** Persistence for queued uploads. */
+export interface UploadStore {
+    put(record: QueuedUpload): Promise<void>;
+    delete(localId: string): Promise<void>;
+    list(): Promise<QueuedUpload[]>;
+}
+/** The prefix of a field value that names a queued upload. */
+export declare const LOCAL_FILE_PREFIX = "local:";
+/** `local:<localId>` → `<localId>`; null for any other value. */
+export declare function localUploadId(ref: unknown): string | null;
+/** Default cap on the bytes waiting in the queue: 200 MB. */
+export declare const DEFAULT_MAX_QUEUED_UPLOAD_BYTES: number;
+/** Thrown by `queueUpload` when the file would take the queue past its
+ *  size limit. Past the limit the browser may evict the app's storage,
+ *  which would lose every queued file, so the queue refuses instead. */
+export declare class UploadQueueFullError extends Error {
+    readonly code = "UPLOAD_QUEUE_FULL";
+    readonly limitBytes: number;
+    readonly queuedBytes: number;
+    constructor(limitBytes: number, queuedBytes: number, fileBytes: number);
+}
+export declare class MemoryUploadStore implements UploadStore {
+    private rows;
+    put(record: QueuedUpload): Promise<void>;
+    delete(localId: string): Promise<void>;
+    list(): Promise<QueuedUpload[]>;
+}
+/** Queued uploads in IndexedDB database `pylon_uploads_<appName>`. */
+export declare class IndexedDBUploadStore implements UploadStore {
+    private readonly appName;
+    private db;
+    constructor(appName?: string);
+    private open;
+    private run;
+    put(record: QueuedUpload): Promise<void>;
+    delete(localId: string): Promise<void>;
+    list(): Promise<QueuedUpload[]>;
+    /** Close the connection (tests; a deleteDatabase waits for it). */
+    close(): Promise<void>;
+}
+/** What the queue does with an upload, by its owner and who is signed in. */
+export type UploadOwnerVerdict = "send" | "hold" | "discard";
+/**
+ * The owner rule for uploads, the same as for queued writes: send when the
+ * upload's owner is signed in (or it was a guest's and that guest signed in
+ * to an account), hold while nobody or nobody known is signed in, discard
+ * when another user is signed in.
+ */
+export declare function uploadOwnerVerdict(owner: string | null, current: string | null | undefined): UploadOwnerVerdict;
+/** Whether an upload error is worth trying again later: no network, a
+ *  server error, a timeout, or a rate limit. Anything else (the type or
+ *  size was refused, a policy) is the server's answer. */
+export declare function isTransientUploadError(err: unknown): boolean;
+/** One queued upload as the outbox shows it. */
+export declare function uploadOutboxItem(r: QueuedUpload): OutboxItem;
+export declare function newUploadId(): string;
+/** What `queueUpload` returns. */
+export interface QueuedUploadHandle {
+    localId: string;
+    /** `local:<localId>`: the value the record's field holds until the
+     *  upload finishes. */
+    ref: string;
+    /** An object URL of the file, to show it at once. Null where the
+     *  platform has no `URL.createObjectURL`. */
+    localUrl: string | null;
+    /** Resolves with the uploaded file once it is attached; rejects with an
+     *  `UploadRejectedError` when the server refuses it or another user is
+     *  signed in. A page that reloads loses this promise, not the upload. */
+    done: Promise<UploadedFile>;
+}
+/** Why a queued upload was not sent. `code` is the server's error code
+ *  (`FILE_TOO_LARGE`, `POLICY_DENIED`, ...), or `DISCARDED` when another
+ *  user is signed in. */
+export declare class UploadRejectedError extends Error {
+    readonly code: string;
+    readonly localId: string;
+    constructor(message: string, code: string, localId: string);
+}
+/** What the upload manager needs from the sync engine. */
+export interface UploadManagerHost {
+    transport(): TransportConfig;
+    /** The signed-in user (`null` = anonymous), or `undefined` while it is
+     *  not known (no answer from the server yet this run, or a token change
+     *  in flight). */
+    currentOwner(): string | null | undefined;
+    /** The user a new upload belongs to; `undefined` = not known yet. */
+    ownerForNewUpload(): string | null | undefined;
+    /** Only the leader tab uploads. */
+    isLeader(): boolean;
+    isRunning(): boolean;
+    /** Queue an ordinary write that sets fields on a record. */
+    update(entity: string, id: string, patch: Record<string, unknown>): void;
+    /** The outbox changed. */
+    changed(): void;
+    /** Tell other tabs to reload the queue. */
+    broadcast(): void;
+    /** Run `fn` after `ms` unless the engine stops. */
+    later(ms: number, fn: () => void): void;
+}
+/**
+ * The offline upload queue: storage, the one-at-a-time upload loop, the
+ * owner rule, the size limit, and the outbox entries.
+ */
+export declare class UploadManager {
+    private readonly host;
+    private readonly maxBytes;
+    private store;
+    private records;
+    private objectUrls;
+    private waiters;
+    private running;
+    private failureCount;
+    private retryScheduled;
+    private _version;
+    constructor(host: UploadManagerHost, maxBytes?: number);
+    /** Bumped on every change to the queue. */
+    version(): number;
+    private changed;
+    /** Swap in persistent storage and load what it holds. */
+    attachStore(store: UploadStore): Promise<void>;
+    /** Re-read the queue from storage (another tab changed it). */
+    reload(): Promise<void>;
+    /** Queued uploads, oldest first. */
+    list(): QueuedUpload[];
+    get(localId: string): QueuedUpload | undefined;
+    /** Bytes waiting on the device. */
+    queuedBytes(): number;
+    enqueue(blob: Blob, opts: {
+        attach: UploadAttachTarget;
+        filename?: string;
+        contentType?: string;
+        visibility?: FileVisibility;
+    }): Promise<QueuedUploadHandle>;
+    /** An object URL for a queued file, or null. */
+    localUrl(localId: string): string | null;
+    private revoke;
+    private settle;
+    private remove;
+    /** Stamp uploads made before anyone was known to be signed in. */
+    stampPendingOwner(owner: string | null): Promise<void>;
+    /**
+     * Upload every queued file the signed-in user owns, oldest first, one at
+     * a time. Stops at the first error that says the network is down and
+     * tries again later (and on the next reconnect). A file the server
+     * refuses is marked failed and not tried again until `retry`.
+     */
+    process(): Promise<void>;
+    private scheduleRetry;
+    /** Queue a failed upload again. Throws `UploadRejectedError` with code
+     *  `OWNER_MISMATCH` / `OWNER_UNKNOWN` as `retryWrite` does. */
+    retry(localId: string): Promise<void>;
+    /** Drop a failed upload and its bytes. False when there is no failed
+     *  upload with that id. The record keeps its `local:` value. */
+    dismiss(localId: string): boolean;
+}

package/dist/upload.d.ts

@@ -0,0 +1,37 @@
+import { type TransportConfig } from "./transport";
+export interface UploadedFile {
+    id: string;
+    /** Where to read the file. Store this on your row. */
+    url: string;
+    size: number;
+}
+/**
+ * Who can read an uploaded file through `url`.
+ *   - "private" (default): only the uploader.
+ *   - "public": anyone, signed in or not. Use it for content every visitor
+ *     sees, such as feed photos or listing images.
+ * Writes and deletes stay with the uploader either way. On a CDN-backed
+ * store (Stack0, a public bucket) every file is served by its URL, so the
+ * setting only changes reads that go through `/api/files/<id>`.
+ */
+export type FileVisibility = "private" | "public";
+export interface UploadBytesOptions {
+    filename?: string;
+    contentType?: string;
+    visibility?: FileVisibility;
+}
+/**
+ * Upload a file (File, Blob, or raw bytes) in three steps:
+ *   1. POST /api/files/init with the name, type, size, and visibility;
+ *   2. PUT the bytes to the returned upload URL;
+ *   3. POST /api/files/confirm, which returns `{ id, url, size }`.
+ *
+ * The upload URL is either pylon's own receiver (local disk), which needs
+ * the session like any API call, or a presigned storage URL, whose
+ * signature is the credential. The session is never sent to a presigned
+ * URL on another origin.
+ *
+ * Throws `PylonHttpError` (with `status`) when the server answers with an
+ * error, and the fetch error when there is no network.
+ */
+export declare function uploadBytes(transport: TransportConfig, input: File | Blob | ArrayBuffer | Uint8Array, options?: UploadBytesOptions): Promise<UploadedFile>;

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.22.47",
+  "version": "0.22.50",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./dist/index.d.ts",