snapback4 0.0.16 → 0.1.0

package/README.md

@@ -112,8 +112,9 @@ mutation edit(messageId: messages, body: text <=4000):
 - **Types:** `principal`, `id`, `<table>` (a reference to that table's
   id), `int`, `time` (milliseconds), `bool`, `decimal <scale>`,
   `money <CUR> [scale]`, `text <=N`, `text M..N [format handle|url]`,
-  `enum('a', 'b')`, `json <=N`, `bytes <=N`, `[type] <=N` (a list);
-  `?` after a type makes the column optional (null when absent).
+  `enum('a', 'b')`, `json <=N`, `bytes <=N`, `[type] <=N` (a list),
+  `image <=N [once]` and `video <=N` (an upload the row holds — §4,
+  assets); `?` after a type makes the column optional (null when absent).
 - **Indexes:** `by name: cols` orders rows; `unique name: cols` also
   constrains them. A scan needs an index whose leading columns are the
   scan's prefix; a page's order is the index's remaining columns.
@@ -132,6 +133,12 @@ mutation edit(messageId: messages, body: text <=4000):
 - **Sync** (§3) and **retain**: `retain until-revoked` (the default: a
   device drops a group's rows when it leaves the group) or
   `retain delivered-history` (it keeps what it was given).
+- **Expire:** `expire at .expiresAt` (a `time ?` column with an index
+  leading with it, `by byExpiresAt: expiresAt`). A row past that time is
+  absent to every reader on every host from that moment, before any rule;
+  the server sweeps it within seconds and the deletion streams to each
+  device holding it. A null time never expires. Disappearing messages
+  are `expiresAt: now + ttl if ttl` on insert; nothing else to write.
 
 ### Maintains
 
@@ -172,6 +179,32 @@ groups by the audience columns.
 - **Refusals** a program raises with `require .. else CODE` reach the
   client as `{ code: "CODE", family: "rule", .. }`.
 
+### Jobs and schedules
+
+```
+job digest(periodStart: time, periodEnd: time):
+  chunk p in profiles first 100 by byId:
+    ... a mutation's body with p bound; reads and writes as the system ...
+schedule daily every 1d at 08:00: digest        -- or: every 2m
+```
+
+A job is the server's own work: a sequence of sweeps, each `chunk x in
+table[prefix] first N by index:` walking one index a page per commit as
+the system principal (every rule passes; validation, constraints,
+aggregates and partitions apply) under the job ceilings. The cursor
+commits with the rows, so a chunk is wholly done or not started and a
+restart resumes at the next one; the index's columns are `id` or
+`immutable`, so nothing moves under the cursor, and rows inserted past
+the key captured when the sweep began are not visited. `break` ends the
+sweep, `return` the job; a refused chunk parks the job with its refusal
+(`snapback4 doctor` lists runs). No client calls a job. A schedule fires
+it once per period boundary of the server's clock (`every 2m`, `every
+1h`, `every 1d at 08:00`), exactly once per boundary across restarts,
+passing `periodStart` and `periodEnd` when the job declares them (and
+nothing else); a schedule first seen fires from its next boundary.
+`snapback4 run <job> '{..}'` runs one here and now. Jobs are not on
+`api.ts`.
+
 ### The meter
 
 Nothing is priced at compile time. As a program runs, the meter counts
@@ -284,6 +317,31 @@ const viewer = useViewer();           // the principal, or null
 `useQuery` observes: it re-renders when a sync or a local prediction
 touches the query's tables. `usePage` follows `next` across pages.
 
+### Assets
+
+```ts
+const uploaded = await client.upload(file);            // Blob | ArrayBuffer | Uint8Array
+if (uploaded.ok) await client.mutate(api.sendPhoto, { conversationId, photo: { id: uploaded.asset.id } });
+const photo = useAsset(message.photo?.id);             // { status: "loading" } | { status: "ready", url, type } | { status: "denied", why }
+```
+
+An `image <=N` or `video <=N` column holds an upload: the client sends
+the bytes first (`upload` → `{ id, type, bytes, width, height,
+duration }`; the server sniffs JPEG, PNG, WebP and MP4 and refuses the
+rest with `E_ASSET_TYPE`, and anything over the largest column's bound
+with `E_ASSET_TOO_LARGE`), then places `{ id }` in the mutation; the row
+carries the facts the server established. One asset, one home: your own
+upload, placed once (`E_ASSET_UNKNOWN`, `E_ASSET_PLACED`). Serving is
+the home row's read rule: `client.asset(id)` fetches the bytes under the
+viewer's credentials and returns a blob URL (`useAsset` in React;
+`client.assetSource(id)` gives a URI and headers for native image and
+video views); a row that is deleted, whose column is cleared, that
+expired, or that the viewer may not read answers `E_ASSET_UNKNOWN`. A
+column declared `image <=N once` serves one view per principal: the
+second is `E_ASSET_VIEWED`, and the bytes are never cached anywhere
+(the sender is never counted). Uploads are online only; there is
+nothing to queue.
+
 ### Sign-in (`snapback4/auth`)
 
 `guest(url)`, `signup(url, email, password)`, `login(url, email,
@@ -332,8 +390,8 @@ flips the link.
   diagnostic with its site and rewrite; `--cost` adds each site's
   structural class.
 - **`snapback4 why <E_CODE | op | table>`**, **`data <table>`**,
-  **`doctor`**, **`guide [keyword]`** (cards: rules, sync, writes, reads,
-  shapes, bounds, types, personas, refusals).
+  **`doctor`**, **`guide [keyword]`** (cards: rules, sync, expire, assets,
+  jobs, writes, reads, shapes, bounds, types, personas, refusals).
 
 ### The wire
 
@@ -343,7 +401,9 @@ seq, next }` or `{ denied }`; `POST /m/<op>` with `{ "id", "args",
 "newIds" }` answers `{ state: "sent", seq, result }` or `{ state:
 "failed", why }` (a client-minted `id` makes the write apply at most
 once); `GET /sync?from=W` streams the partition; `GET /changes?since=S`
-long-polls for commits; `GET /schema` is the compiled backend;
+long-polls for commits; `POST /assets` (the file's bytes as the body)
+answers `{ asset }`, `GET /assets/<id>` serves them (404 hidden or gone,
+410 viewed; `Range` works); `GET /schema` is the compiled backend;
 `POST /auth/guest` (`{}`), `POST /auth/signup` and `/auth/login`
 (`{ "email", "password" }`) answer `{ "session": { principal, kind, token,
 expiresAt } }` or `{ "denied": Refusal }`; `POST /auth/logout` with the
@@ -384,10 +444,10 @@ through `nodeSqliteDriver`.)
 
 ## 8. Not in this release
 
-Word search (`tokens()` and word-prefix indexes are parsed, not served),
-scheduled jobs, effects (server-side side effects to third parties),
-assets (`image`/`video` columns type-check and store metadata; there is
-no upload or serving path), platform binaries other than darwin-arm64
-(build from source with `cargo build --release -p snapback4` and set
-`SNAPBACK4_BIN`). If the package cannot express something, the
+Word search (`tokens()` and word-prefix indexes are parsed, not served:
+search over synced rows on the device, or by a prefix index), effects
+(server-side side effects to third parties: write the fact to a table
+and let a job or a reader act on it), platform binaries other than
+darwin-arm64 (build from source with `cargo build --release -p snapback4`
+and set `SNAPBACK4_BIN`). If the package cannot express something, the
 diagnostic names the term; record the gap and move on.

package/dist/assets.d.ts

@@ -0,0 +1,10 @@
+import type { AssetRead, Uploaded } from "./contract.ts";
+export type Bytes = Blob | ArrayBuffer | Uint8Array;
+export declare function uploadAsset(base: string, headers: Record<string, string>, doFetch: typeof fetch, bytes: Bytes): Promise<Uploaded>;
+/** Where the bytes are and what to send to get them: for hosts whose image
+ * and video views take a URI with headers (React Native). */
+export declare function assetSource(base: string, headers: Record<string, string>, id: string): {
+    uri: string;
+    headers: Record<string, string>;
+};
+export declare function fetchAsset(base: string, headers: Record<string, string>, doFetch: typeof fetch, id: string): Promise<AssetRead>;

package/dist/assets.js

@@ -0,0 +1,42 @@
+// Assets on the client: `upload` posts the bytes and returns the facts the
+// server established; `asset` fetches the bytes under the viewer's own
+// credentials and hands back a blob URL, so a screen never puts a token in
+// an <img src> and a one-view photo is never durably cached anywhere
+// (LLP 1006 carried into Snapback 4).
+const offline = () => ({ code: "E_OFFLINE", family: "link", message: "the server is unreachable", retryable: true });
+export async function uploadAsset(base, headers, doFetch, bytes) {
+    const { "content-type": _json, ...auth } = headers;
+    const body = bytes instanceof Uint8Array ? new Blob([bytes]) : bytes;
+    try {
+        const response = await doFetch(`${base}/assets`, { method: "POST", headers: { ...auth, "content-type": "application/octet-stream" }, body });
+        const json = (await response.json());
+        if (json.asset)
+            return { ok: true, asset: json.asset };
+        return { ok: false, why: json.denied ?? { code: "E_STORE", family: "store", message: "the server answered without an asset", retryable: true } };
+    }
+    catch {
+        return { ok: false, why: offline() };
+    }
+}
+/** Where the bytes are and what to send to get them: for hosts whose image
+ * and video views take a URI with headers (React Native). */
+export function assetSource(base, headers, id) {
+    const { "content-type": _json, ...auth } = headers;
+    return { uri: `${base}/assets/${encodeURIComponent(id)}`, headers: auth };
+}
+export async function fetchAsset(base, headers, doFetch, id) {
+    const source = assetSource(base, headers, id);
+    try {
+        const response = await doFetch(source.uri, { headers: source.headers });
+        if (!response.ok) {
+            const json = (await response.json().catch(() => null));
+            return { denied: json?.denied ?? { code: response.status === 410 ? "E_ASSET_VIEWED" : "E_ASSET_UNKNOWN", family: "asset", message: response.status === 410 ? "this photo was for one view, and it was viewed" : "no asset is served under that id to this viewer" } };
+        }
+        const blob = await response.blob();
+        const url = URL.createObjectURL(blob);
+        return { url, type: response.headers.get("content-type") ?? blob.type, bytes: blob.size, revoke: () => URL.revokeObjectURL(url) };
+    }
+    catch {
+        return { denied: offline() };
+    }
+}

package/dist/client.js

@@ -3,6 +3,7 @@
 // when a commit touches its tables; a write is sent with a client-minted id
 // and applies at most once, and waits as `pending` while the link is down.
 // Every word a screen reads is on the card (contract.ts).
+import { assetSource, fetchAsset, uploadAsset } from "./assets.js";
 const ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
 /** A time-ordered 128-bit id: 48 bits of milliseconds, 80 bits of entropy, 26 base32 digits. */
 export function mintId(now = Date.now()) {
@@ -254,6 +255,16 @@ export function createClient(options) {
             // Durable admission on this device: the write waits for the link.
             return { state: "pending", id };
         },
+        async upload(bytes) {
+            if (!viewer)
+                return { ok: false, why: { code: "E_AUTH", family: "auth", message: "sign in to upload" } };
+            const uploaded = await uploadAsset(base, headers, doFetch, bytes);
+            if (!uploaded.ok && uploaded.why.code === "E_OFFLINE")
+                setLink("offline");
+            return uploaded;
+        },
+        asset: (id) => fetchAsset(base, headers, doFetch, id),
+        assetSource: (id) => assetSource(base, headers, id),
         link: () => link,
         onLink(listener) {
             linkListeners.add(listener);

package/dist/contract.d.ts

@@ -74,11 +74,52 @@ export interface Observed<T> {
     subscribe(notify: () => void): () => void;
     close(): void;
 }
+/** An upload the server recorded: the facts it established, and the id a
+ * row's `image`/`video` column takes (`{ id }` is enough; the server fills
+ * the rest on the row). */
+export interface Asset {
+    readonly id: string;
+    readonly type: string;
+    readonly bytes: number;
+    readonly width?: number | null;
+    readonly height?: number | null;
+    /** Milliseconds, for video. */
+    readonly duration?: number | null;
+}
+export type Uploaded = {
+    readonly ok: true;
+    readonly asset: Asset;
+} | {
+    readonly ok: false;
+    readonly why: Refusal;
+};
+/** The bytes of an asset, fetched under the viewer's credentials: a blob
+ * URL to put in `src`, and `revoke()` when the screen is done with it. A
+ * one-view photo comes back `denied` with `E_ASSET_VIEWED` the second time. */
+export type AssetRead = {
+    readonly url: string;
+    readonly type: string;
+    readonly bytes: number;
+    readonly revoke: () => void;
+} | {
+    readonly denied: Refusal;
+};
 /** The whole client, as a screen sees it. Everything else is `why`. */
 export interface Client {
     query<A, R>(op: Query<A, R>, args: A): Promise<Read<R>>;
     observe<A, R>(op: Query<A, R>, args: A): Observed<R>;
     mutate<A, R>(op: Mutation<A, R>, args: A): Promise<Write>;
+    /** Send the bytes of a photo or video; place `asset.id` in a mutation's
+     * `image`/`video` argument. Online only: an upload waits for no link. */
+    upload(bytes: Blob | ArrayBuffer | Uint8Array): Promise<Uploaded>;
+    /** The bytes of an asset a row the viewer may read holds, as a blob URL. */
+    asset(id: string): Promise<AssetRead>;
+    /** Where the bytes are and the headers that fetch them, for native image
+     * and video views that take a URI with headers. */
+    assetSource(id: string): {
+        uri: string;
+        headers: Record<string, string>;
+    };
     link(): Link;
     onLink(notify: (link: Link) => void): () => void;
     viewer(): Principal | null;

package/dist/local.js

@@ -5,6 +5,7 @@
 // server had at the last sync; a predictable mutation renders its rows as
 // `pending` before the server confirms them.
 import { mintId } from "./client.js";
+import { assetSource, fetchAsset, uploadAsset } from "./assets.js";
 import { Interpreter, Refused } from "./replica/interpreter.js";
 import { Replica } from "./replica/replica.js";
 import { MemoryStore, openIndexedDb } from "./replica/store.js";
@@ -362,6 +363,17 @@ export async function createLocalClient(options) {
             const first = await Promise.race([outcome, new Promise((resolve) => setTimeout(() => resolve({ state: "pending", id }), 4_000))]);
             return first;
         },
+        async upload(bytes) {
+            // An upload is bytes on the server; there is nothing to queue.
+            if (link !== "online")
+                return { ok: false, why: { code: "E_OFFLINE", family: "link", message: "the server is unreachable; uploads wait for no link", retryable: true } };
+            const uploaded = await uploadAsset(base, headers, doFetch, bytes);
+            if (!uploaded.ok && uploaded.why.code === "E_OFFLINE")
+                setLink("offline");
+            return uploaded;
+        },
+        asset: (id) => fetchAsset(base, headers, doFetch, id),
+        assetSource: (id) => assetSource(base, headers, id),
         link: () => link,
         onLink(listener) {
             linkListeners.add(listener);

package/dist/mock.js

@@ -103,6 +103,14 @@ export function createMockClient(options) {
                 setTimeout(() => { settleOne(entry); bump(); }, delay);
             });
         },
+        async upload(bytes) {
+            const size = bytes instanceof Blob ? bytes.size : bytes.byteLength;
+            return { ok: true, asset: { id: mockId(), type: "image/png", bytes: size, width: 1, height: 1 } };
+        },
+        async asset(id) {
+            return { denied: { code: "E_ASSET_UNKNOWN", family: "asset", message: `the mock holds no bytes for ${id}` } };
+        },
+        assetSource: (id) => ({ uri: `mock://assets/${id}`, headers: {} }),
         link: () => link,
         onLink(notify) { linkListeners.add(notify); return () => linkListeners.delete(notify); },
         viewer: () => options.viewer,

package/dist/react.d.ts

@@ -1,5 +1,5 @@
 import { type ReactNode } from "react";
-import type { Client, Cursor, Link, Mutation, Principal, Query, Read, Write } from "./contract.ts";
+import type { Client, Cursor, Link, Mutation, Principal, Query, Read, Refusal, Write } from "./contract.ts";
 export declare function SnapbackProvider({ client, children }: {
     client: Client;
     children: ReactNode;
@@ -23,3 +23,19 @@ export declare function useMutation<A, R>(op: Mutation<A, R>): {
 };
 export declare function useLink(): Link;
 export declare function useViewer(): Principal | null;
+export type AssetState = {
+    readonly status: "loading";
+} | {
+    readonly status: "ready";
+    readonly url: string;
+    readonly type: string;
+} | {
+    readonly status: "denied";
+    readonly why: Refusal;
+};
+/** The bytes of an asset a row the viewer may read holds, fetched under
+ * the viewer's credentials as a blob URL for `src`. Revoked when the id
+ * changes or the screen unmounts. A one-view photo is fetched once per
+ * mount: a screen that shows it again is `denied` with `E_ASSET_VIEWED`,
+ * which is the feature. Pass `null` to show nothing. */
+export declare function useAsset(id: string | null | undefined): AssetState;

package/dist/react.js

@@ -111,3 +111,34 @@ export function useLink() {
 export function useViewer() {
     return useClient().viewer();
 }
+/** The bytes of an asset a row the viewer may read holds, fetched under
+ * the viewer's credentials as a blob URL for `src`. Revoked when the id
+ * changes or the screen unmounts. A one-view photo is fetched once per
+ * mount: a screen that shows it again is `denied` with `E_ASSET_VIEWED`,
+ * which is the feature. Pass `null` to show nothing. */
+export function useAsset(id) {
+    const client = useClient();
+    const [state, setState] = useState({ status: "loading" });
+    useEffect(() => {
+        if (!id)
+            return;
+        let live = true;
+        let read = null;
+        setState({ status: "loading" });
+        void client.asset(id).then((result) => {
+            read = result;
+            if (!live) {
+                if ("url" in result)
+                    result.revoke();
+                return;
+            }
+            setState("url" in result ? { status: "ready", url: result.url, type: result.type } : { status: "denied", why: result.denied });
+        });
+        return () => {
+            live = false;
+            if (read && "url" in read)
+                read.revoke();
+        };
+    }, [client, id]);
+    return id ? state : { status: "loading" };
+}

package/dist/replica/interpreter.d.ts

@@ -82,6 +82,10 @@ export declare class Interpreter {
     private recurse;
     expr(e: unknown): Promise<unknown>;
     private builtin;
+    /** Whether a held row is past its table's `expire` column on this
+     * device's clock: absent to every read, as on the server, until the
+     * server's sweep deletes it and the deletion arrives in the log. */
+    private expired;
     private get;
     private scan;
     private merge;

package/dist/replica/interpreter.js

@@ -489,6 +489,16 @@ export class Interpreter {
         }
     }
     // ----- reads -----
+    /** Whether a held row is past its table's `expire` column on this
+     * device's clock: absent to every read, as on the server, until the
+     * server's sweep deletes it and the deletion arrives in the log. */
+    expired(table, row) {
+        const column = this.schema.tables[table]?.expire;
+        if (!column)
+            return false;
+        const at = row[column];
+        return typeof at === "number" && at <= this.ctx.now;
+    }
     async get(read) {
         const key = [];
         for (const k of read.key)
@@ -506,7 +516,7 @@ export class Interpreter {
         const row = await this.tx.lookup(read.table, read.index, key);
         if (!this.charge("examined"))
             return null;
-        if (!row)
+        if (!row || this.expired(read.table, row))
             return null;
         if (await this.readable(read.table, row))
             return row;
@@ -569,6 +579,10 @@ export class Interpreter {
             for (const { row, key } of fetched) {
                 if (!this.charge("examined"))
                     break outer;
+                cursor = { ...cursor, after: suffixOf(this.schema, table, index, row, prefix.length) };
+                // Gone, whatever the rule says; it cost one examined row.
+                if (this.expired(table, row))
+                    continue;
                 let allowed;
                 if (verdict !== null)
                     allowed = verdict;
@@ -595,7 +609,6 @@ export class Interpreter {
                     this.capped = mark.capped;
                     break outer;
                 }
-                cursor = { ...cursor, after: suffixOf(this.schema, table, index, row, prefix.length) };
             }
             if (fetched.length < batch)
                 break;
@@ -765,7 +778,8 @@ export class Interpreter {
                 if (!this.charge("probes"))
                     return false;
                 this.tables.add(b.table);
-                return (await this.tx.lookup(b.table, b.index, b.key.map(term))) !== undefined;
+                const found = await this.tx.lookup(b.table, b.index, b.key.map(term));
+                return found !== undefined && !this.expired(b.table, found);
             }
             case "Created": {
                 const b = body;
@@ -838,7 +852,7 @@ export class Interpreter {
     async update(table, id, patch) {
         this.tables.add(table);
         const old = await this.tx.get(table, id);
-        if (!old)
+        if (!old || this.expired(table, old))
             throw new Refused({ code: "NOT_FOUND", family: "rule", message: "the row does not exist on this device", rule: "NOT_FOUND" });
         const next = { ...old, ...patch, pending: true };
         await this.permitted(table, "update", old, next);
@@ -854,7 +868,7 @@ export class Interpreter {
     async delete(table, id) {
         this.tables.add(table);
         const old = await this.tx.get(table, id);
-        if (!old)
+        if (!old || this.expired(table, old))
             throw new Refused({ code: "NOT_FOUND", family: "rule", message: "the row does not exist on this device", rule: "NOT_FOUND" });
         await this.permitted(table, "delete", undefined, old);
         this.written++;

package/dist/replica/store.d.ts

@@ -25,6 +25,8 @@ export interface TableJson {
         } | null;
     } | null;
     leave?: "until-revoked" | "delivered-history";
+    /** The time column that ends a row's life; a row past it is absent here too. */
+    expire?: string | null;
 }
 export interface Bounds {
     after?: unknown[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "snapback4",
-  "version": "0.0.16",
+  "version": "0.1.0",
   "type": "module",
   "description": "Snapback 4: the card (contract), the online and local-first clients (IndexedDB, SQLite), React hooks, sign-in, a labelled mock, and the `snapback4` CLI. LLP 3000.",
   "bin": {
@@ -42,7 +42,7 @@
     "README.md"
   ],
   "optionalDependencies": {
-    "snapback4-darwin-arm64": "0.0.16"
+    "snapback4-darwin-arm64": "0.1.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",