@voltro/protocol 0.51.0 → 0.53.0

package/dist/rest.d.ts

@@ -74,6 +74,12 @@ declare interface AnyApprovalPolicy {
 /** A guard is either a scope check or a relationship check. */
 declare type AnyGuardSpec<Input = unknown> = GuardSpec<Input> | PolicyGuardSpec<Input>;
 
+export declare const bytes: (stream: ReadableStream<Uint8Array> | (() => ReadableStream<Uint8Array>), options?: {
+    readonly contentType?: string;
+    readonly contentLength?: number;
+    readonly contentDisposition?: string;
+}) => RestByteResponse;
+
 /**
  * Project every descriptor carrying a `publicApi` annotation into a REST
  * route, in stable (path) order. The boot layer feeds these straight into
@@ -224,6 +230,8 @@ declare interface IdempotencyStore {
 declare interface InsertTarget<Input = unknown, Row = unknown, Item = Record<string, unknown>> extends NestedTargetFields<Input> {
     readonly table: string;
     readonly op: 'insert';
+    /** Declared junction relations — see {@link TargetRelations}. */
+    readonly relations?: TargetRelations | undefined;
     readonly order?: 'prepend' | 'append' | undefined;
     /**
      * Build the optimistic row from the mutation input. The framework
@@ -248,6 +256,8 @@ declare interface InsertTarget<Input = unknown, Row = unknown, Item = Record<str
     readonly shapeItem?: ((input: Input, optimisticId: string) => Item) | undefined;
 }
 
+export declare const isRestByteResponse: (v: unknown) => v is RestByteResponse;
+
 export declare const isRestStreamResponse: (v: unknown) => v is RestStreamResponse;
 
 /** Extract `:name` path params by aligning the route PATTERN with the request
@@ -349,12 +359,19 @@ declare interface OpenAccessSpec {
 
 /** A public raw-HTTP route a plugin serves on the framework listener. */
 declare interface PluginHttpRoute {
-    /** HTTP method, or `'*'` for any (the handler decides). */
-    readonly method: '*' | 'GET' | 'POST' | 'PUT' | 'DELETE';
+    /** HTTP method, or `'*'` for any (the handler decides). PATCH/HEAD/OPTIONS
+     *  are first-class — the REST desugar used to mount `'*'` partly BECAUSE
+     *  this union lacked PATCH; that reason is gone (the `'*'` mount remains
+     *  for its other job: one dispatcher per shared path + a precise 405). */
+    readonly method: '*' | 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
     /** Absolute path prefix, e.g. `/_voltro/storage`. Matches the path AND
      *  any sub-path (`/_voltro/storage/abc123`). */
     readonly path: string;
     readonly handle: (req: PluginHttpRouteRequest) => Promise<PluginHttpRouteResult>;
+    /** Per-route body cap override (bytes) — wins over the listener's shared
+     *  `maxBodyBytes`. NOTE: routes SHARING a path share one body read, so the
+     *  widest override on the path's group applies to the whole group. */
+    readonly maxBodyBytes?: number;
     /**
      * Opt this route's path OUT of the listener's cross-site origin check.
      *
@@ -393,6 +410,21 @@ declare interface PluginHttpRoute {
     readonly originGuard?: 'exempt';
 }
 
+/**
+ * A binary streaming body — the download/export shape. The serve layer pipes
+ * the Web ReadableStream to the socket without buffering, so a response
+ * larger than the heap is fine; the LAZY thunk form defers opening the
+ * source (a provider connection, a file handle) until the response actually
+ * streams.
+ */
+declare interface PluginHttpRouteByteStream {
+    readonly stream: ReadableStream<Uint8Array> | (() => ReadableStream<Uint8Array>);
+    /** Declared up front when known — lets the client render progress. */
+    readonly contentLength?: number;
+    /** e.g. `attachment; filename="export.zip"`. */
+    readonly contentDisposition?: string;
+}
+
 declare interface PluginHttpRouteRequest {
     readonly method: string;
     /** Path WITHOUT query string. */
@@ -504,6 +536,12 @@ declare interface PluginHttpRouteResult {
     /** Stream the response (SSE) instead of sending `body`. See
      *  {@link PluginHttpRouteStream}. */
     readonly stream?: PluginHttpRouteStream;
+    /** Stream a BINARY response (a download, an export) instead of sending
+     *  `body` — see {@link PluginHttpRouteByteStream}. Never buffered by the
+     *  serve layer; never compressed (flush timing + Content-Length are the
+     *  contract). Takes precedence over `body`; do not set both `stream` and
+     *  `byteStream`. */
+    readonly byteStream?: PluginHttpRouteByteStream;
 }
 
 /**
@@ -739,6 +777,19 @@ export declare const requireAnyScope: (scopes: ReadonlyArray<string>) => RestGua
  */
 export declare const requireScope: (scope: string) => RestGuard;
 
+/** A BINARY streaming response (download/export). The serve layer pipes the
+ *  ReadableStream without buffering — a body larger than the heap is fine.
+ *  The LAZY thunk form defers opening the source until the response streams. */
+export declare interface RestByteResponse {
+    readonly __voltroRestBytes: true;
+    readonly byteStream: {
+        readonly stream: ReadableStream<Uint8Array> | (() => ReadableStream<Uint8Array>);
+        readonly contentLength?: number;
+        readonly contentDisposition?: string;
+    };
+    readonly contentType?: string;
+}
+
 export declare type RestGuard = (ctx: RestRouteContext) => RestGuardRejection | undefined | Promise<RestGuardRejection | undefined>;
 
 /**
@@ -751,7 +802,7 @@ export declare interface RestGuardRejection {
     readonly message: string;
 }
 
-export declare type RestMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+export declare type RestMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
 
 /**
  * Per-call context handed to a REST route handler. Resolved by the serve
@@ -791,6 +842,26 @@ export declare interface RestRouteDescriptor<I, O> {
     /** ISO date. Sets a `Sunset:` header; past the date the route returns
      *  `410 Gone` with a replacement pointer. */
     readonly sunset?: string;
+    /**
+     * Opt-in API version. `version: 'v2'` + `path: '/customers'` mounts the route
+     * at `/v2/customers` — the same `/vN/` convention the `publicApi:` projection
+     * has always used (`derivePublicPath`) and the built-in `/v1/api-keys`
+     * surface follows.
+     *
+     * OPT-IN on purpose: a route without `version` keeps its literal `path`
+     * untouched. An automatic prefix would silently move every deployed route —
+     * a second breaking change hiding inside a naming feature.
+     *
+     * Two versions of one resource are TWO descriptors: the old version is
+     * ordinary code — visible, testable, deletable — carrying `deprecated` (the
+     * replacement pointer) and `sunset` (the date it starts answering `410`,
+     * whose body then also names this `version`). There is no transformation
+     * DSL, and the rpc SOCKET is deliberately outside this: the generated client
+     * is versioned with the server it was generated from (a stale browser tab
+     * runs the previous client until reload — that skew window exists and is
+     * documented, it is not solved by URL versioning).
+     */
+    readonly version?: `v${number}`;
     readonly guards?: ReadonlyArray<RestGuard>;
     /**
      * This route STREAMS (Server-Sent Events) rather than resolving one value — its
@@ -801,6 +872,13 @@ export declare interface RestRouteDescriptor<I, O> {
      * no spec, because clients are generated from it.
      */
     readonly streaming?: boolean;
+    /** Per-route body cap override (bytes) — see PluginHttpRoute.maxBodyBytes. */
+    readonly maxBodyBytes?: number;
+    /** GET only: derive a weak ETag from the encoded response and answer a
+     *  matching `If-None-Match` with 304. The tag is content-derived (an md5
+     *  of the JSON), so it is correct across content-encodings — the
+     *  transport's compression varies the bytes, not the representation. */
+    readonly etag?: boolean;
 }
 
 export declare interface RestRouteExample {
@@ -922,11 +1000,29 @@ declare type Subject = typeof Subject.Type;
 
 declare type Target<Input = unknown, Row = unknown> = TargetSpec<Input, Row> | ReadonlyArray<TargetSpec<Input, Row>>;
 
+/**
+ * Declared many-to-many RELATIONS of a write target: `{ inputField:
+ * junctionTable }`. After the executor succeeds — inside the SAME
+ * transaction — the framework reconciles the junction's links for the
+ * written row against `input[inputField]` (an array of target ids) via the
+ * diff-based `store.relationLinks`, so a form's multi-reference field saves
+ * in one mutation with no hand-written junction code. The anchor column is
+ * derived from the junction's `reference()` targets (a self-junction is
+ * refused, never guessed).
+ *
+ * An ABSENT input field leaves the links untouched (absent ≠ empty — an
+ * empty array is the explicit "clear them all"). The row id is the
+ * executor's `output.id`, falling back to `input.id`.
+ */
+declare type TargetRelations = Readonly<Record<string, string>>;
+
 declare type TargetSpec<Input = unknown, Row = unknown> = InsertTarget<Input, Row> | UpdateTarget<Input, Row> | DeleteTarget<Input>;
 
 declare interface UpdateTarget<Input = unknown, Row = unknown, Item = Record<string, unknown>> extends NestedTargetFields<Input> {
     readonly table: string;
     readonly op: 'update';
+    /** Declared junction relations — see {@link TargetRelations}. */
+    readonly relations?: TargetRelations | undefined;
     /** Identify the row(s) to patch. Default: `input.id`. Return an ARRAY to patch
      *  MANY rows/items in one mutation (a bulk edit — where the per-item
      *  parallel-write race lived). */

package/dist/rest.js

@@ -33,26 +33,45 @@ var c = (e, t) => t.method ?? (e === "query" ? "GET" : "POST"), l = (e, t) => t.
 		status: 403,
 		message: `Missing required scope: one of ${e.join(", ")}`
 	};
-}, m = (e) => e, h = (e, t = {}) => ({
+}, m = (e) => {
+	if (e.version === void 0) return e;
+	if (!/^v\d+$/.test(e.version)) throw Error(`defineRestRoute(${e.method} ${e.path}): version "${e.version}" must be 'v' followed by digits — 'v1', 'v2', …`);
+	if ((/* @__PURE__ */ RegExp("^/v\\d+(/|$)")).test(e.path)) throw Error(`defineRestRoute(${e.method} ${e.path}): the path already starts with a version segment AND declares version: '${e.version}'. Pick one spelling — either bake the version into the path, or declare version: and keep the path bare ('/customers'). Both would mount '/${e.version}${e.path}', which is never what the author meant.`);
+	return {
+		...e,
+		path: `/${e.version}${e.path}`
+	};
+}, h = (e, t = {}) => ({
 	__voltroRestStream: !0,
 	stream: {
 		subscribe: e,
 		...t.keepAliveMs === void 0 ? {} : { keepAliveMs: t.keepAliveMs }
 	}
-}), g = (e, t) => `event: ${e}\n${(typeof t == "string" ? t : JSON.stringify(t)).split("\n").map((e) => `data: ${e}`).join("\n")}\n\n`, _ = (e) => typeof e == "object" && !!e && e.__voltroRestStream === !0, v = (e, t, n) => ({
+}), g = (e, t) => `event: ${e}\n${(typeof t == "string" ? t : JSON.stringify(t)).split("\n").map((e) => `data: ${e}`).join("\n")}\n\n`, _ = (e) => typeof e == "object" && !!e && e.__voltroRestStream === !0, v = (e, t = {}) => ({
+	__voltroRestBytes: !0,
+	byteStream: {
+		stream: e,
+		...t.contentLength === void 0 ? {} : { contentLength: t.contentLength },
+		...t.contentDisposition === void 0 ? {} : { contentDisposition: t.contentDisposition }
+	},
+	...t.contentType === void 0 ? {} : { contentType: t.contentType }
+}), y = (e) => typeof e == "object" && !!e && e.__voltroRestBytes === !0, b = async (e) => {
+	let t = await globalThis.crypto.subtle.digest("SHA-1", new TextEncoder().encode(e));
+	return [...new Uint8Array(t)].map((e) => e.toString(16).padStart(2, "0")).join("");
+}, x = (e, t, n) => ({
 	status: e,
 	contentType: "application/json; charset=utf-8",
 	body: JSON.stringify(t),
 	...n ? { headers: n } : {}
-}), y = (e) => {
+}), S = (e) => {
 	if (e.length === 0) return;
 	let t = new TextDecoder().decode(e);
 	if (t.trim() !== "") return JSON.parse(t);
-}, b = (e) => {
+}, C = (e) => {
 	let t = {};
 	for (let [n, r] of new URLSearchParams(e)) t[n] = r;
 	return t;
-}, x = (e, t) => {
+}, w = (e, t) => {
 	let n = e.split("/").filter((e) => e.length > 0), r = t.split("/").filter((e) => e.length > 0), i = {};
 	for (let e = 0; e < n.length; e++) {
 		let t = n[e];
@@ -66,22 +85,24 @@ var c = (e, t) => t.method ?? (e === "query" ? "GET" : "POST"), l = (e, t) => t.
 		}
 	}
 	return i;
-}, S = (e, t) => ({
-	query: b(e.query),
+}, T = (e, t) => ({
+	query: C(e.query),
 	params: t,
-	body: y(e.rawBody)
-}), C = /* @__PURE__ */ new Set([
+	body: S(e.rawBody)
+}), E = /* @__PURE__ */ new Set([
 	"POST",
 	"PUT",
 	"PATCH",
 	"DELETE"
-]), w = (c, l) => {
+]), D = (c, l) => {
 	let u = c.input ? s.decodeUnknown(c.input) : void 0, d = s.encode(c.output), f = {};
 	return c.deprecated !== void 0 && (f.Deprecation = "true"), c.sunset !== void 0 && (f.Sunset = c.sunset), {
 		method: "*",
 		path: c.path,
+		...c.maxBodyBytes === void 0 ? {} : { maxBodyBytes: c.maxBodyBytes },
 		handle: async (s) => {
-			if (s.method.toUpperCase() !== c.method) return v(405, {
+			let p = s.method.toUpperCase();
+			if (!(p === c.method || p === "HEAD" && c.method === "GET")) return x(405, {
 				error: "Method Not Allowed",
 				allow: c.method
 			}, {
@@ -90,74 +111,98 @@ var c = (e, t) => t.method ?? (e === "query" ? "GET" : "POST"), l = (e, t) => t.
 			});
 			if (c.sunset !== void 0) {
 				let e = Date.parse(c.sunset);
-				if (!Number.isNaN(e) && Date.now() >= e) return v(410, {
+				if (!Number.isNaN(e) && Date.now() >= e) return x(410, {
 					error: "Gone",
+					...c.version === void 0 ? {} : { version: c.version },
 					...c.deprecated === void 0 ? {} : { replacement: c.deprecated }
 				}, f);
 			}
-			let p;
+			let m;
 			if (u) {
-				let e = S(s, x(c.path, s.path)), t = await o.runPromise(u(e).pipe(o.map((e) => ({
+				let e = T(s, w(c.path, s.path)), t = await o.runPromise(u(e).pipe(o.map((e) => ({
 					ok: !0,
 					value: e
 				})), o.catchAll((e) => o.succeed({
 					ok: !1,
 					cause: e
 				}))));
-				if (!t.ok) return v(400, {
+				if (!t.ok) return x(400, {
 					error: "Invalid request",
 					detail: String(t.cause)
 				}, f);
-				p = t.value;
+				m = t.value;
 			}
-			let m = l.resolveSubject ? await l.resolveSubject(s.headers) : e(s.headers["x-tenant"] ?? null), h = {
-				subject: m,
+			let h = l.resolveSubject ? await l.resolveSubject(s.headers) : e(s.headers["x-tenant"] ?? null), g = {
+				subject: h,
 				headers: s.headers,
 				store: l.store
 			};
 			if (c.guards) for (let e of c.guards) {
-				let t = await e(h);
-				if (t) return v(t.status, { error: t.message }, f);
+				let t = await e(g);
+				if (t) return x(t.status, { error: t.message }, f);
 			}
-			let g = l.idempotency, y = g && C.has(c.method) ? s.headers[g.header.toLowerCase()] : void 0, b = g && y ? r(m.tenantId, c.method, c.path) : "";
-			if (g && y) {
-				let e = await i(g.store, b, y, g.ttlMs, Date.now());
-				if (e.kind === "replay") return v(e.response.status, e.response.body, {
+			let v = l.idempotency, S = v && E.has(c.method) ? s.headers[v.header.toLowerCase()] : void 0, C = v && S ? r(h.tenantId, c.method, c.path) : "";
+			if (v && S) {
+				let e = await i(v.store, C, S, v.ttlMs, Date.now());
+				if (e.kind === "replay") return x(e.response.status, e.response.body, {
 					...f,
 					"Idempotency-Replayed": "true"
 				});
-				if (e.kind === "conflict") return v(409, { error: "A request with this Idempotency-Key is already being processed" }, f);
+				if (e.kind === "conflict") return x(409, { error: "A request with this Idempotency-Key is already being processed" }, f);
 			}
 			try {
-				let e = await c.handler(p, h);
-				if (_(e)) return {
+				let e = await c.handler(m, g);
+				if (_(e) || y(e)) return v && S && await n(v.store, C, S), y(e) ? {
+					status: 200,
+					headers: f,
+					byteStream: e.byteStream,
+					...e.contentType === void 0 ? {} : { contentType: e.contentType }
+				} : {
 					status: 200,
 					headers: f,
 					stream: e.stream
 				};
-				let n = await o.runPromise(d(e));
-				return g && y && await t(g.store, b, y, {
+				let r = await o.runPromise(d(e));
+				if (v && S && await t(v.store, C, S, {
 					status: 200,
-					body: n
-				}, Date.now()), v(200, n, f);
+					body: r
+				}, Date.now()), c.etag === !0 && c.method === "GET") {
+					let e = `W/"${await b(JSON.stringify(r))}"`, t = s.headers["if-none-match"];
+					return t !== void 0 && t.split(",").some((t) => t.trim() === e) ? {
+						status: 304,
+						headers: {
+							...f,
+							ETag: e
+						}
+					} : x(200, r, {
+						...f,
+						ETag: e
+					});
+				}
+				return x(200, r, f);
 			} catch (e) {
-				if (g && y && await n(g.store, b, y), typeof e == "object" && e && typeof e.status == "number") {
+				if (v && S && await n(v.store, C, S), typeof e == "object" && e && typeof e.status == "number") {
 					let t = e;
-					return v(t.status, { error: t.message ?? "Error" }, f);
+					return x(t.status, { error: t.message ?? "Error" }, f);
 				}
 				return a({
 					error: e,
 					source: "rest",
 					name: `${c.method} ${c.path}`,
 					fields: { status: 500 }
-				}), v(500, { error: "Internal Server Error" }, f);
+				}), x(500, { error: "Internal Server Error" }, f);
 			}
 		}
 	};
-}, T = (e, t = {}) => e.map((e) => w(e, t)), E = async (e, t) => {
+}, O = (e, t = {}) => {
+	if (t.idempotency !== void 0) {
+		for (let t of e) if (t.streaming === !0 && E.has(t.method)) throw Error(`REST route ${t.method} ${t.path} declares \`streaming: true\` on a method the idempotency binding claims (${[...E].join("/")}). A stream cannot complete an idempotency claim — there is no replayable body to cache — so a retried request would 409 until the claim's TTL. Either serve the stream on GET, or scope the idempotency binding away from this app's streaming routes.`);
+	}
+	return e.map((e) => D(e, t));
+}, k = async (e, t) => {
 	let n = await e[0].handle(t);
 	for (let r = 1; r < e.length && n.status === 405; r++) n = await e[r].handle(t);
 	return n;
 };
 //#endregion
-export { d as collectPublicApiRoutes, m as defineRestRoute, c as derivePublicMethod, l as derivePublicPath, E as dispatchSharedPath, _ as isRestStreamResponse, x as matchPathParams, u as publicApiRoute, p as requireAnyScope, f as requireScope, T as restRoutesToHttpRoutes, h as sse, g as sseFrame };
+export { v as bytes, d as collectPublicApiRoutes, m as defineRestRoute, c as derivePublicMethod, l as derivePublicPath, k as dispatchSharedPath, y as isRestByteResponse, _ as isRestStreamResponse, w as matchPathParams, u as publicApiRoute, p as requireAnyScope, f as requireScope, O as restRoutesToHttpRoutes, h as sse, g as sseFrame };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/protocol",
-  "version": "0.51.0",
+  "version": "0.53.0",
   "description": "The Voltro wire + plugin contract — defineQuery/Mutation/Action/Stream, definePlugin, sessions / JWT / API-keys, and the RPC protocol.",
   "keywords": [
     "voltro",
@@ -54,8 +54,8 @@
   },
   "dependencies": {
     "@effect/sql": "^0.52.0",
-    "@voltro/database": "0.51.0",
-    "@voltro/logger": "0.51.0",
+    "@voltro/database": "0.53.0",
+    "@voltro/logger": "0.53.0",
     "jose": "^6.2.8"
   },
   "peerDependencies": {