@yourrealm/sdk 0.0.0-alpha.1451.8a8a7d44 → 0.0.0-alpha.1471.2b6cf8b8

package/dist/{chunk-NSZJJPMQ.js → chunk-BSCX74FG.js}

@@ -172,13 +172,51 @@ var snapshotGroupSchema = z.object({
   /** Null when offsite isn't set up, or its listing failed (see `repos`). */
   offsite: z.array(snapshotSchema).nullable()
 });
+var BACKUP_PATH_MAX = 4096;
+function isBackupRelPath(p) {
+  return p.length > 0 && p.length <= BACKUP_PATH_MAX && !p.includes("\0") && p.split("/").every((seg) => seg !== "" && seg !== "." && seg !== "..");
+}
+var relPathSchema = z.string().refine(isBackupRelPath, {
+  message: "must be a relative path with no empty, . or .. segments and no NUL"
+});
+var BACKUP_PATHS_MAX = 1e4;
+var relPathsSchema = z.array(relPathSchema).min(1).max(BACKUP_PATHS_MAX).refine((ps) => new Set(ps).size === ps.length, { message: "a path is named twice" });
 var restoreSourceSchema = z.enum(["local", "offsite"]);
-var restoreItemSchema = z.object({
+var snapshotRefSchema = z.object({
   serviceKey: z.string().min(1),
   volume: backupVolumeSchema,
   snapshotId: z.string().regex(SNAPSHOT_ID_RE),
   source: restoreSourceSchema
 });
+var backupLsRequestSchema = snapshotRefSchema.extend({
+  appId: z.string().min(1),
+  path: z.union([z.literal(""), relPathSchema])
+});
+var lsEntrySchema = z.object({
+  name: z.string().min(1),
+  type: z.enum(["dir", "file", "symlink"]),
+  /** Bytes; files only. */
+  size: z.number().int().nonnegative().optional(),
+  /** ISO-8601, UTC. */
+  mtime: z.string()
+});
+var backupLsResultSchema = z.object({ entries: z.array(lsEntrySchema) });
+var BACKUP_READ_ITEMS_MAX = 100;
+var backupReadRequestSchema = z.object({
+  appId: z.string().min(1),
+  items: z.array(snapshotRefSchema.extend({ paths: relPathsSchema.optional() })).min(1).max(BACKUP_READ_ITEMS_MAX).refine(
+    (items) => new Set(items.map((i) => `${i.serviceKey}/${i.volume}`)).size === items.length,
+    { message: "a volume is named twice" }
+  )
+});
+var restoreItemSchema = snapshotRefSchema.extend({
+  /**
+   * Put back only these, relative to the volume's root: each becomes exactly
+   * the snapshot's version, and nothing else in the volume moves. Folder
+   * (file-copy) volumes only. Absent, the whole volume.
+   */
+  paths: relPathsSchema.optional()
+});
 var backupRestoreRequestSchema = z.object({
   restoreId: z.uuid(),
   appId: z.string().min(1),
@@ -615,6 +653,12 @@ export {
   BACKUP_STALE_GENERATION,
   BACKUP_FILE_EXISTS,
   backupSignResultSchema,
+  isBackupRelPath,
+  BACKUP_PATHS_MAX,
+  backupLsRequestSchema,
+  backupLsResultSchema,
+  BACKUP_READ_ITEMS_MAX,
+  backupReadRequestSchema,
   backupRestoreRequestSchema,
   BACKUP_RESTORE_PHASES,
   BACKUP_RESTORE_INTERRUPTED,

package/dist/test.js

@@ -2,7 +2,7 @@ import {
   REALM_APP_DIR_GID,
   isPreparedAppDir,
   scopeBindSource
-} from "./chunk-NSZJJPMQ.js";
+} from "./chunk-BSCX74FG.js";
 import {
   RealmCompileError,
   checkAppGrants,

package/dist/worker-protocol.js

@@ -1,6 +1,8 @@
 import {
   BACKUP_FILE_EXISTS,
   BACKUP_FILE_TYPES,
+  BACKUP_PATHS_MAX,
+  BACKUP_READ_ITEMS_MAX,
   BACKUP_RESTORE_INTERRUPTED,
   BACKUP_RESTORE_PHASES,
   BACKUP_SAFETY_TAG,
@@ -8,6 +10,9 @@ import {
   PLATFORM_INGRESS_PORTS,
   REALM_APP_DIR_GID,
   REALM_SILO_DIR,
+  backupLsRequestSchema,
+  backupLsResultSchema,
+  backupReadRequestSchema,
   backupRestoreRequestSchema,
   backupSignRequestSchema,
   backupSignResultSchema,
@@ -18,6 +23,7 @@ import {
   backupVolumeSchema,
   dependsOnEdgeSchema,
   ingressInputSchema,
+  isBackupRelPath,
   isManagedSiloPath,
   isPreparedAppDir,
   managedSiloPath,
@@ -33,7 +39,7 @@ import {
   wireServiceSchema,
   workerAppSchema,
   workerStateSchema
-} from "./chunk-NSZJJPMQ.js";
+} from "./chunk-BSCX74FG.js";
 import {
   MANAGEMENT_NET,
   REALM_HOME_PROXY_CONTAINER_PATH,
@@ -62,6 +68,8 @@ import "./chunk-MLKGABMK.js";
 export {
   BACKUP_FILE_EXISTS,
   BACKUP_FILE_TYPES,
+  BACKUP_PATHS_MAX,
+  BACKUP_READ_ITEMS_MAX,
   BACKUP_RESTORE_INTERRUPTED,
   BACKUP_RESTORE_PHASES,
   BACKUP_SAFETY_TAG,
@@ -81,6 +89,9 @@ export {
   REALM_STATS_SOCKET,
   SILO_NET_PREFIX,
   UNTRUSTED_NET,
+  backupLsRequestSchema,
+  backupLsResultSchema,
+  backupReadRequestSchema,
   backupRestoreRequestSchema,
   backupSignRequestSchema,
   backupSignResultSchema,
@@ -94,6 +105,7 @@ export {
   homeProxyMount,
   homeProxySocketPath,
   ingressInputSchema,
+  isBackupRelPath,
   isManagedSiloPath,
   isPreparedAppDir,
   isSiloNetwork,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yourrealm/sdk",
-  "version": "0.0.0-alpha.1451.8a8a7d44",
+  "version": "0.0.0-alpha.1471.2b6cf8b8",
   "description": "The Realm SDK: createApp, the r.* permission factories, the ui surface, the realm-sdk CLI and test harness.",
   "license": "AGPL-3.0-only WITH Classpath-exception-2.0",
   "repository": {
@@ -106,9 +106,9 @@
     "@std/path": "npm:@jsr/std__path@^1",
     "@std/tar": "npm:@jsr/std__tar@^0.1",
     "@std/testing": "npm:@jsr/std__testing@^1",
-    "@local/docker": "0.1.0",
     "@local/logger": "0.1.0",
-    "@yourrealm/noise": "0.1.0"
+    "@yourrealm/noise": "0.1.0",
+    "@local/docker": "0.1.0"
   },
   "scripts": {
     "typecheck": "deno check",

package/src/runtime/spawn-client/kaniko.ts

@@ -22,13 +22,14 @@
 
 import type { BuildRecipe } from "../../service-definition.ts";
 
-// Default builder image: canonical kaniko. It runs as root and never calls
-// unshare(CLONE_NEWUSER), so it builds clean under the broker's envelope:
+// Default builder image: our build of Chainguard's kaniko fork
+// (publish-kaniko.yml), since upstream is archived. It runs as root and never
+// calls unshare(CLONE_NEWUSER), so it builds clean under the broker's envelope:
 // HARDENING plus the file-extraction caps (FOWNER, DAC_OVERRIDE, SETFCAP,
 // FSETID) spec.ts adds so base rootfs with non-root-owned files
 // (node:22-alpine's /home/node) unpack faithfully — the property is
 // kaniko's, not a specific distro's.
-export const DEFAULT_KANIKO_IMAGE = "gcr.io/kaniko-project/executor:latest";
+export const DEFAULT_KANIKO_IMAGE = "benjick/realm-kaniko:v1.25.19";
 
 // Where the broker bind-mounts the staged context, read-only, in the box.
 // Must match `CONTEXT_MOUNT` in spawn-server/spec.ts — kaniko.test.ts pins

package/src/sandbox.ts

@@ -1241,14 +1241,21 @@ export async function runGate(
 // ---- widget prefill (loader request stitching) -----------------------------
 
 // Run every loader's request(seedState, config) inside the VM and collect the
-// descriptors. `seedState` is the surface's `stateSchema.parse({})` — the exact
-// seed the iframe runtime mounts with — so a descriptor produced here matches
+// descriptors. `seedState` follows `seedFrom` in ui-runtime/mount.ts — the page
+// query parsed through `stateSchema`, else its `{}`-parse, else `{}` — the exact
+// seed the iframe runtime mounts with, so a descriptor produced here matches
 // the query key the runtime later builds from `request(state, config)`, and the
 // prefilled data seeds cleanly with no first-paint refetch. A loader whose
 // request is null (or throws) on the seed is lazy for this config → omitted.
-function stitchSnippet(collection: "pages" | "widgets", key: string, config: unknown): string {
+function stitchSnippet(
+  collection: "pages" | "widgets",
+  key: string,
+  config: unknown,
+  search: Record<string, string> | undefined,
+): string {
   return [
     `var __config = ${JSON.stringify(config ?? null)};`,
+    `var __search = ${JSON.stringify(search ?? {})};`,
     `if (__config == null) __config = {};`, // mirror the runtime's `opts.config ?? {}`
     `(function () {`,
     `  var ui = __app.ui;`,
@@ -1256,7 +1263,8 @@ function stitchSnippet(collection: "pages" | "widgets", key: string, config: unk
     `  if (!surface) return JSON.stringify({});`,
     `  var seedState = {};`,
     `  if (surface.stateSchema && typeof surface.stateSchema.safeParse === "function") {`,
-    `    var __p = surface.stateSchema.safeParse({});`,
+    `    var __q = surface.stateSchema.safeParse(__search);`,
+    `    var __p = __q.success ? __q : surface.stateSchema.safeParse({});`,
     `    seedState = __p.success ? __p.data : {};`,
     `  }`,
     `  var out = {};`,
@@ -1289,10 +1297,12 @@ export async function stitchLoaderRequests(opts: {
   kind: "page" | "widget";
   key: string;
   config: unknown;
+  // A page's URL query (see `seedFrom` in ui-runtime/mount.ts). Absent → `{}`.
+  search?: Record<string, string>;
 }): Promise<Record<string, RequestManifest | null>> {
   const vm = getVm({ key: `prefill:${opts.appId}:${opts.bundleId}`, bundle: opts.bundle });
   const collection = opts.kind === "widget" ? "widgets" : "pages";
-  const result = await vm.call(stitchSnippet(collection, opts.key, opts.config));
+  const result = await vm.call(stitchSnippet(collection, opts.key, opts.config, opts.search));
   return (result ?? {}) as Record<string, RequestManifest | null>;
 }
 

package/src/ui/components/icons.tsx

@@ -39,6 +39,14 @@ export { PiEnvelopeDuotone as EnvelopeIcon } from "react-icons/pi";
 export { PiEyeDuotone as EyeIcon } from "react-icons/pi";
 export { PiEyeSlashDuotone as EyeSlashIcon } from "react-icons/pi";
 export { PiFadersDuotone as FadersIcon } from "react-icons/pi";
+export { PiFileDuotone as FileIcon } from "react-icons/pi";
+export { PiFileAudioDuotone as FileAudioIcon } from "react-icons/pi";
+export { PiFileCodeDuotone as FileCodeIcon } from "react-icons/pi";
+export { PiFileImageDuotone as FileImageIcon } from "react-icons/pi";
+export { PiFilePdfDuotone as FilePdfIcon } from "react-icons/pi";
+export { PiFileTextDuotone as FileTextIcon } from "react-icons/pi";
+export { PiFileVideoDuotone as FileVideoIcon } from "react-icons/pi";
+export { PiFileZipDuotone as FileZipIcon } from "react-icons/pi";
 export { PiFolderOpenDuotone as FolderOpenIcon } from "react-icons/pi";
 export { PiFolderSimpleDuotone as FolderSimpleIcon } from "react-icons/pi";
 export { PiGaugeDuotone as GaugeIcon } from "react-icons/pi";

package/src/ui-runtime/mount.ts

@@ -67,11 +67,15 @@ interface RenderApi {
   queryClient: QueryClient;
 }
 
+interface StateSchemaLike {
+  safeParse(v: unknown): { success: boolean; data?: unknown };
+}
+
 interface SurfaceLike {
   title: string;
-  // The live state schema rides the bundle; its `{}`-parse seeds the
-  // widget's initial state.
-  stateSchema?: { safeParse(v: unknown): { success: boolean; data?: unknown } };
+  // The live state schema rides the bundle and seeds the initial state —
+  // see `seedFrom`.
+  stateSchema?: StateSchemaLike;
   loaders?: Record<string, SurfaceLoader>;
   actions?: Record<string, SurfaceAction>;
   render: (api: RenderApi) => ComponentChildren;
@@ -95,6 +99,9 @@ interface MountOpts {
   // as the loader's queryFn output *before* merge, so the runtime applies
   // merge to it too — see `applyMerge`.
   initialData?: Record<string, unknown>;
+  // A page's URL query, flat (last occurrence wins), inlined by Home. Seeds
+  // the initial state — see `seedFrom`. Widgets never get one.
+  search?: Record<string, string>;
 }
 
 interface PendingHandler {
@@ -201,6 +208,21 @@ function applyMerge(loader: SurfaceLoader, raw: unknown): unknown {
   return raw;
 }
 
+// The surface's initial state: the page query parsed through `stateSchema`,
+// else the `{}`-parse, else `{}`. A query that fails to parse is dropped
+// whole, never key by key. Mirrored by `stitchSnippet` in sandbox.ts, so
+// Home's prefill runs `request()` on this exact seed — keep the two in step.
+export function seedFrom(
+  schema: StateSchemaLike | undefined,
+  search: Record<string, string> | undefined,
+): unknown {
+  if (!schema) return {};
+  const fromQuery = schema.safeParse(search ?? {});
+  if (fromQuery.success) return fromQuery.data;
+  const empty = schema.safeParse({});
+  return empty.success ? empty.data : {};
+}
+
 // Assemble the render fn's props from the handles built this render. Pure, so
 // the prop wiring is testable without a DOM.
 export function renderApi(args: {
@@ -240,14 +262,13 @@ export function mount(opts: MountOpts): void {
     },
   });
 
-  // The widget's config (resolved by Home) and initial state (the live
-  // stateSchema's `{}`-parse). `seedState` is a stable reference so
+  // The widget's config (resolved by Home) and initial state (`seedFrom`).
+  // `seedState` is a stable reference so
   // `initialData` applies only while the widget is still at its seed: that
   // gates the prefill to the query key Home actually ran to produce it
   // (`request(seedState, config)`), so a re-keyed loader can't inherit it.
   const config = opts.config ?? {};
-  const seedParse = opts.surface.stateSchema?.safeParse({});
-  const seedState: unknown = seedParse?.success ? seedParse.data : {};
+  const seedState = seedFrom(opts.surface.stateSchema, opts.search);
 
   // Capture the loader/action name sets ONCE, before the component
   // renders. The render loop calls one useQuery per loader and one

package/src/worker/start-worker.ts

@@ -1,6 +1,9 @@
 import { log } from "@local/logger";
 import type { WorkerCapability } from "../permissions.ts";
 import type {
+  BackupLsRequest,
+  BackupLsResult,
+  BackupReadRequest,
   BackupRestoreRequest,
   BackupSignRequest,
   BackupSignResult,
@@ -10,7 +13,13 @@ import type {
 } from "../worker-protocol/index.ts";
 import {
   type AppApplyResult,
+  BACKUP_READ_FILE_TYPE,
+  BACKUP_READ_SIZE_HEADER,
+  BACKUP_READ_TAR_TYPE,
+  BACKUP_READ_TYPE_HEADER,
+  type BackupRead,
   jsonHandler,
+  paramsHandler,
   parseEnrollmentToken,
   type RpcHandler,
   type UpdateProject,
@@ -76,6 +85,18 @@ export interface StartWorkerOptions {
    * it is in progress).
    */
   backupRelease: (appId: string) => Promise<void>;
+  /**
+   * Home → worker `backup.ls`: one folder of a snapshot. Throw a `MethodError`
+   * to refuse (404 not there, 503 locked or no bucket).
+   */
+  backupLs: (req: BackupLsRequest) => Promise<BackupLsResult>;
+  /**
+   * Home → worker `backup.read`: the bytes of paths in a snapshot, as one file
+   * or a tar. Resolves once the read is known to be answerable, with the body
+   * unread; cancelling the body must stop the read. Throw a `MethodError` to
+   * refuse (404 not there, 503 locked or no bucket).
+   */
+  backupRead: (req: BackupReadRequest) => Promise<BackupRead>;
   /**
    * What this box's ingress container is running, or null where it has none.
    * Injected rather than read here, for the reason the whole `worker` layer is
@@ -214,6 +235,18 @@ export async function startWorker(opts: StartWorkerOptions): Promise<WorkerHandl
       await opts.backupRelease(appId);
       return { ok: true };
     }),
+    "backup.ls": jsonHandler("backup.ls", (req) => opts.backupLs(req)),
+    "backup.read": paramsHandler("backup.read", async (req) => {
+      const read = await opts.backupRead(req);
+      const headers: Record<string, string> =
+        read.kind === "file"
+          ? {
+              [BACKUP_READ_TYPE_HEADER]: BACKUP_READ_FILE_TYPE,
+              [BACKUP_READ_SIZE_HEADER]: String(read.size ?? 0),
+            }
+          : { [BACKUP_READ_TYPE_HEADER]: BACKUP_READ_TAR_TYPE };
+      return { status: 200, headers, body: read.body };
+    }),
     uiProxy: uiProxyHandler((appId, service) =>
       lastState === null ? undefined : declaredPortsIn(lastState, appId, service),
     ),

package/src/worker-protocol/backup.ts

@@ -297,23 +297,121 @@ const snapshotGroupSchema = z.object({
   offsite: z.array(snapshotSchema).nullable(),
 });
 
-// --- backup.restore --------------------------------------------------------
+// --- paths inside a snapshot -----------------------------------------------
+
+/** Longest path inside a volume the wire carries, in UTF-16 units. */
+const BACKUP_PATH_MAX = 4096;
+
+/**
+ * A path inside a volume, relative to its root: `a/b.txt`, never `/a`, `a/`,
+ * `a//b`, `.`, `..` or a NUL. The Worker checks it again where it joins it.
+ */
+export function isBackupRelPath(p: string): boolean {
+  return (
+    p.length > 0 &&
+    p.length <= BACKUP_PATH_MAX &&
+    !p.includes("\0") &&
+    p.split("/").every((seg) => seg !== "" && seg !== "." && seg !== "..")
+  );
+}
+
+const relPathSchema = z.string().refine(isBackupRelPath, {
+  message: "must be a relative path with no empty, . or .. segments and no NUL",
+});
+
+/** Most paths one read or put-back names. */
+export const BACKUP_PATHS_MAX = 10_000;
+
+const relPathsSchema = z
+  .array(relPathSchema)
+  .min(1)
+  .max(BACKUP_PATHS_MAX)
+  .refine((ps) => new Set(ps).size === ps.length, { message: "a path is named twice" });
 
 const restoreSourceSchema = z.enum(["local", "offsite"]);
 
-const restoreItemSchema = z.object({
+/** The one snapshot of one volume a listing, a read or a restore item names. */
+const snapshotRefSchema = z.object({
   serviceKey: z.string().min(1),
   volume: backupVolumeSchema,
   snapshotId: z.string().regex(SNAPSHOT_ID_RE),
   source: restoreSourceSchema,
 });
 
+// --- backup.ls ---------------------------------------------------------------
+
+/**
+ * `backup.ls`, Home → Worker: one folder of one snapshot of one volume.
+ * `path` is relative to the volume's root, `""` for the root itself. A
+ * single-file volume (sqlite, pg-dump, mysql-dump, valkey-save) lists its one
+ * file at the root and has no folders.
+ */
+export const backupLsRequestSchema = snapshotRefSchema.extend({
+  appId: z.string().min(1),
+  path: z.union([z.literal(""), relPathSchema]),
+});
+export type BackupLsRequest = z.infer<typeof backupLsRequestSchema>;
+
+const lsEntrySchema = z.object({
+  name: z.string().min(1),
+  type: z.enum(["dir", "file", "symlink"]),
+  /** Bytes; files only. */
+  size: z.number().int().nonnegative().optional(),
+  /** ISO-8601, UTC. */
+  mtime: z.string(),
+});
+export type BackupLsEntry = z.infer<typeof lsEntrySchema>;
+
+/** The folder's entries, sorted by name. */
+export const backupLsResultSchema = z.object({ entries: z.array(lsEntrySchema) });
+export type BackupLsResult = z.infer<typeof backupLsResultSchema>;
+
+// --- backup.read -------------------------------------------------------------
+
+/** Most volumes one read names. */
+export const BACKUP_READ_ITEMS_MAX = 100;
+
+/**
+ * `backup.read`, Home → Worker: the bytes of one selection per volume of one
+ * app. An item's `paths` are relative to its volume's root, files and folders
+ * from anywhere in it; absent, the whole volume. Exactly one item naming
+ * exactly one file answers that file as itself; anything else, one tar. With
+ * one item its names are relative to the volume's root; with several, each
+ * item's sit under a top folder named after its volume, or
+ * `<serviceKey>-<volume>` where two services share a volume name.
+ */
+export const backupReadRequestSchema = z.object({
+  appId: z.string().min(1),
+  items: z
+    .array(snapshotRefSchema.extend({ paths: relPathsSchema.optional() }))
+    .min(1)
+    .max(BACKUP_READ_ITEMS_MAX)
+    .refine(
+      (items) => new Set(items.map((i) => `${i.serviceKey}/${i.volume}`)).size === items.length,
+      { message: "a volume is named twice" },
+    ),
+});
+export type BackupReadRequest = z.infer<typeof backupReadRequestSchema>;
+export type BackupReadItem = BackupReadRequest["items"][number];
+
+// --- backup.restore --------------------------------------------------------
+
+const restoreItemSchema = snapshotRefSchema.extend({
+  /**
+   * Put back only these, relative to the volume's root: each becomes exactly
+   * the snapshot's version, and nothing else in the volume moves. Folder
+   * (file-copy) volumes only. Absent, the whole volume.
+   */
+  paths: relPathsSchema.optional(),
+});
+
 /**
  * `backup.restore`, Home → Worker: put these snapshots back over one app's
  * volumes. The Worker answers once it has accepted the restore - 404 an
- * unknown app or volume, 409 a restore of that app already queued or running,
- * 503 an offsite item with no bucket set - and does the work afterwards,
- * reporting through `backup.status`.
+ * unknown app or volume, or an item's path the snapshot doesn't hold, 400
+ * `paths` on a volume that isn't a folder, 409 a restore of that app already
+ * queued or running, 503 an offsite item with no bucket set - and does the
+ * work afterwards, reporting through `backup.status`.
  */
 export const backupRestoreRequestSchema = z.object({
   restoreId: z.uuid(),

package/src/worker-protocol/index.ts

@@ -15,14 +15,20 @@ export { ingressInputSchema, PLATFORM_INGRESS_PORTS } from "./ingress.ts";
 export {
   BACKUP_FILE_EXISTS,
   BACKUP_FILE_TYPES,
+  BACKUP_PATHS_MAX,
+  BACKUP_READ_ITEMS_MAX,
   BACKUP_RESTORE_INTERRUPTED,
   BACKUP_RESTORE_PHASES,
   BACKUP_SAFETY_TAG,
   BACKUP_STALE_GENERATION,
+  backupLsRequestSchema,
+  backupLsResultSchema,
+  backupReadRequestSchema,
   backupRestoreRequestSchema,
   backupSnapshotTags,
   backupTargetKey,
   backupVolumeSchema,
+  isBackupRelPath,
   parseBackupSnapshotTags,
   backupSignRequestSchema,
   backupSignResultSchema,
@@ -31,6 +37,11 @@ export {
 } from "./backup.ts";
 export type {
   BackupFileType,
+  BackupLsEntry,
+  BackupLsRequest,
+  BackupLsResult,
+  BackupReadItem,
+  BackupReadRequest,
   BackupRepoStatus,
   BackupRestore,
   BackupRestoreItem,

package/src/worker-protocol/uplink/index.ts

@@ -17,12 +17,18 @@ export { PROTOCOL_VERSION } from "./protocol.ts";
 export {
   APPLY_MESSAGE_MAX_CHARS,
   appApplyResultSchema,
+  BACKUP_READ_FILE_TYPE,
+  BACKUP_READ_SIZE_HEADER,
+  BACKUP_READ_TAR_TYPE,
+  BACKUP_READ_TYPE_HEADER,
+  callBackupRead,
   callJson,
   callUiProxy,
   ETAG_HEADER,
   jsonHandler,
   MethodError,
   methods,
+  paramsHandler,
   pullState,
   UPDATE_ERROR_MAX_CHARS,
   UPDATE_PROJECTS,
@@ -30,6 +36,7 @@ export {
 } from "./methods.ts";
 export type {
   AppApplyResult,
+  BackupRead,
   JsonMethod,
   MethodName,
   Params,

package/src/worker-protocol/uplink/methods.ts

@@ -13,6 +13,9 @@ import {
   homeProxyResponseSchema,
 } from "../../runtime/docker/home-proxy-server/protocol.ts";
 import {
+  backupLsRequestSchema,
+  backupLsResultSchema,
+  backupReadRequestSchema,
   backupRestoreRequestSchema,
   backupSignRequestSchema,
   backupSignResultSchema,
@@ -23,11 +26,20 @@ import type { SiloOrphan } from "../silo-paths.ts";
 import { UPDATE_ERROR_MAX_CHARS } from "../update-files.ts";
 import { UplinkError, UplinkProtocolError } from "./errors.ts";
 import { decodeUtf8, encodeUtf8 } from "./frame.ts";
-import { jsonResponse, type Rpc, type RpcHandler } from "./rpc.ts";
+import { jsonResponse, type Rpc, type RpcHandler, type RpcResponse } from "./rpc.ts";
 
 /** The response header `state.pull` answers a 200 with. */
 export const ETAG_HEADER = "etag";
 
+/**
+ * `backup.read`'s 200: `content-type` says what the body is - one file as
+ * itself, or a tar - and a file's carries its size in `content-length`.
+ */
+export const BACKUP_READ_TYPE_HEADER = "content-type";
+export const BACKUP_READ_SIZE_HEADER = "content-length";
+export const BACKUP_READ_FILE_TYPE = "application/octet-stream";
+export const BACKUP_READ_TAR_TYPE = "application/x-tar";
+
 // --- shared pieces ------------------------------------------------------
 
 const capabilitiesSchema = z.array(
@@ -317,16 +329,43 @@ export const methods = {
   },
 
   /**
-   * Home → worker. Restore snapshots over one app's volumes. Answered once the
-   * worker has accepted it - 404 unknown app or volume, 409 a restore of that
-   * app already in progress, 503 an offsite item with no bucket - and run
-   * afterwards; progress rides `backup.status`.
+   * Home → worker. Restore snapshots over one app's volumes, or only some
+   * paths of a folder volume. Answered once the worker has accepted it - 404
+   * unknown app or volume or a path the snapshot doesn't hold, 400 `paths` on
+   * a volume that isn't a folder, 409 a restore of that app already in
+   * progress, 503 an offsite item with no bucket - and run afterwards;
+   * progress rides `backup.status`.
    */
   "backup.restore": {
     params: backupRestoreRequestSchema,
     result: okSchema,
   },
 
+  /**
+   * Home → worker. One folder of a snapshot: 404 an unknown app, volume,
+   * snapshot or folder, 503 the repository locked by a prune past the wait or
+   * an offsite source with no bucket. Read under restic's shared lock, beside
+   * any backup run rather than after it.
+   */
+  "backup.ls": {
+    params: backupLsRequestSchema,
+    result: backupLsResultSchema,
+  },
+
+  /**
+   * Home → worker. The bytes of a selection from one or more volumes' snapshots,
+   * streamed: one item naming one file as itself (`BACKUP_READ_FILE_TYPE`, its
+   * size in `content-length`), anything else one tar (`BACKUP_READ_TAR_TYPE`).
+   * One item's names are relative to its volume's root; several items' sit
+   * under a top folder each (`backupReadRequestSchema`). Every item is checked
+   * before the first byte: 404 an unknown app, volume, snapshot or path, 400 a
+   * malformed request, 503 as `backup.ls`. Cancelling the body stops the read
+   * on the worker.
+   */
+  "backup.read": {
+    params: backupReadRequestSchema,
+  },
+
   /**
    * Home → worker. Release an app a restore left held (`BackupStatusReport.held`)
    * and start it on its data as it is: 404 when it isn't held so, 409 while a
@@ -450,6 +489,47 @@ export async function callUiProxy(rpc: Rpc, payload: Params<"uiProxy">): Promise
   return { status: res.status, headers: res.headers, body: await readAll(res.body) };
 }
 
+export interface BackupRead {
+  /** `file`: the one file's bytes; `tar`: an archive of the selection. */
+  kind: "file" | "tar";
+  /** A file's size in bytes. */
+  size?: number;
+  /** Unread. The caller drains or cancels it; cancelling stops the worker's read. */
+  body: ReadableStream<Uint8Array>;
+}
+
+/**
+ * `backup.read`, whose 200 body is the bytes. A non-2xx throws `MethodError`
+ * with the worker's text, as `callJson` does.
+ */
+export async function callBackupRead(
+  rpc: Rpc,
+  params: Params<"backup.read">,
+  opts?: { signal?: AbortSignal },
+): Promise<BackupRead> {
+  const res = await rpc.call(
+    "backup.read",
+    {},
+    encodeJson(methods["backup.read"].params, params),
+    opts,
+  );
+  if (res.status < 200 || res.status >= 300) {
+    throw new MethodError(
+      "backup.read",
+      res.status,
+      errorText(decodeUtf8(await readAll(res.body))),
+    );
+  }
+  const type = res.headers[BACKUP_READ_TYPE_HEADER];
+  if (type === BACKUP_READ_TAR_TYPE) return { kind: "tar", body: res.body };
+  const size = Number(res.headers[BACKUP_READ_SIZE_HEADER]);
+  if (type !== BACKUP_READ_FILE_TYPE || !Number.isSafeInteger(size) || size < 0) {
+    await res.body.cancel().catch(() => {});
+    throw new UplinkProtocolError("backup.read answered without a body type and size");
+  }
+  return { kind: "file", size, body: res.body };
+}
+
 // --- answering ----------------------------------------------------------
 
 /**
@@ -483,6 +563,37 @@ export function jsonHandler<M extends JsonMethod>(
   };
 }
 
+/**
+ * Wraps a handler for a method whose params are JSON and whose answer is
+ * whatever the handler builds - a streamed body. The params are checked as
+ * `jsonHandler` checks them (400); a `MethodError` thrown before the answer
+ * is answered as `{"error": body}` with its status.
+ */
+export function paramsHandler<M extends MethodName>(
+  method: M,
+  fn: (params: Params<M>) => Promise<RpcResponse>,
+): RpcHandler {
+  const spec = methods[method] as { params: z.ZodType };
+  return async (req) => {
+    let raw: unknown;
+    try {
+      raw = JSON.parse(decodeUtf8(await readAll(req.body)));
+    } catch {
+      return jsonResponse(400, { error: `${method}: body is not JSON` });
+    }
+    const parsed = spec.params.safeParse(raw);
+    if (!parsed.success) {
+      return jsonResponse(400, { error: `${method}: ${issueText(parsed.error)}` });
+    }
+    try {
+      return await fn(parsed.data as Params<M>);
+    } catch (e) {
+      if (e instanceof MethodError) return jsonResponse(e.status, { error: e.body });
+      throw e;
+    }
+  };
+}
+
 // --- helpers ------------------------------------------------------------
 
 function encodeJson(schema: z.ZodType, params: unknown): Uint8Array {

package/src/worker-protocol/uplink/protocol.ts

@@ -8,4 +8,4 @@
  * door both sides can always open is what lets a mismatched pair be told to
  * update instead of being stranded.
  */
-export const PROTOCOL_VERSION = 3;
+export const PROTOCOL_VERSION = 4;