@yourrealm/sdk 0.0.0-alpha.1378.ce03c8dc

package/src/resolve.ts

@@ -0,0 +1,471 @@
+import { z } from "zod";
+import { appIconSchema } from "./app-icon.ts";
+import { nameSchema } from "./identifiers.ts";
+import type { BuildRecipe, ServiceDefinition } from "./service-definition.ts";
+import { buildRecipeSchema } from "./schema/build-apps.ts";
+import { publicDomainValueSchema } from "./schema/public-domain.ts";
+import { Service } from "./service.ts";
+
+// Mirrors `ServiceDefinition` field-for-field. `Ref<string>` survives the
+// sandbox boundary as a structured `{__realmRef: ...}` marker the Home
+// walker resolves with a grant-scoped allow-map, so every ref-capable field
+// accepts either a plain string or a marker; the walker replaces markers
+// with strings before compose validation runs.
+//
+// Two structural invariants the schema enforces, so the walker doesn't have
+// to defend against them at every step:
+//   1. `concat` is flat — its parts are strings or non-concat markers.
+//   2. `deferred.input` contains no `deferred` descendants, which makes
+//      single-batch `runDeferred` correct by construction.
+const derivedBodySchema = z.object({
+  kind: z.literal("derived"),
+  appId: z.string(),
+  name: z.string(),
+});
+const sharedBodySchema = z.object({
+  kind: z.literal("shared"),
+  providerAppId: z.string(),
+  serviceKey: z.string(),
+  name: z.string(),
+});
+const secretBodySchema = z.object({ kind: z.literal("secret"), path: z.string() });
+
+function hasDeferredDescendant(value: unknown): boolean {
+  if (value == null || typeof value !== "object") return false;
+  if (Array.isArray(value)) return value.some(hasDeferredDescendant);
+  if ("__realmRef" in value) {
+    const m = (value as { __realmRef: unknown }).__realmRef;
+    if (m && typeof m === "object") {
+      if ((m as { kind?: string }).kind === "deferred") return true;
+      return hasDeferredDescendant(m);
+    }
+    return false;
+  }
+  for (const v of Object.values(value as Record<string, unknown>)) {
+    if (hasDeferredDescendant(v)) return true;
+  }
+  return false;
+}
+
+const deferredBodySchema = z.object({
+  kind: z.literal("deferred"),
+  id: z.number().int().nonnegative(),
+  input: z.unknown().refine((v) => !hasDeferredDescendant(v), {
+    message: "deferred input must not contain another deferred marker",
+  }),
+});
+// Concat parts are sync leaves only. `interpolate` rejects
+// `Deferred<string>` at the type level and again with a runtime guard, so a
+// deferred sub-part can't enter a concat through normal authoring; this
+// schema is the last gate on the way out of the sandbox.
+const concatLeafSchema = z.discriminatedUnion("kind", [
+  derivedBodySchema,
+  sharedBodySchema,
+  secretBodySchema,
+]);
+const concatBodySchema = z.object({
+  kind: z.literal("concat"),
+  parts: z.array(z.union([z.string(), concatLeafSchema])),
+});
+const markerBodySchema = z.discriminatedUnion("kind", [
+  derivedBodySchema,
+  sharedBodySchema,
+  secretBodySchema,
+  deferredBodySchema,
+  concatBodySchema,
+]);
+const refMarkerSchema = z.object({ __realmRef: markerBodySchema });
+const stringOrRef = z.union([z.string(), refMarkerSchema]);
+// hostPath stays a strict string. `interpolate` collapses to a literal when
+// all parts resolve to strings (the Postgres/Valkey pattern), so a ref that
+// survives here is rejected at schema parse - it would leak a marker object
+// where a gate-checked path is expected.
+const hostPathSchema = z
+  .string()
+  .refine((p) => (p.startsWith("./") || p.startsWith("/")) && !p.includes(".."), {
+    message: "hostPath must start with ./ or / and must not contain ..",
+  });
+
+// Realm internals + SSH. Short on purpose - users want 80, 443, 53, etc.
+const RESERVED_PORTS = new Set([
+  22, // SSH on the worker host
+  3100, // Home
+  3101, // Home's dev uplink listener
+  6021, // The worker's verify relay
+]);
+
+const hostPortNumberSchema = z
+  .number()
+  .int()
+  .min(1, "hostPort must be >= 1")
+  .max(65535, "hostPort must be <= 65535")
+  .refine((p) => !RESERVED_PORTS.has(p), {
+    message: `hostPort must not be a Realm-reserved port (${[...RESERVED_PORTS].join(", ")})`,
+  });
+
+// Docker reference charset only (lowercase per OCI name grammar). Catches
+// newline (YAML break), `$` (compose env interp), backtick / `;|&<>` (shell
+// metachars), whitespace.
+const imageReferenceSchema = z
+  .string()
+  .min(1, "image must not be empty")
+  .regex(
+    /^[a-z0-9_./\-:@]+$/,
+    "image must contain only Docker reference characters (a-z 0-9 _ . - / : @)",
+  );
+
+// Whole-second duration. Stays a number through resolve + the wire;
+// the renderer formats `${n}s` when emitting compose, since the
+// compose-spec duration parser rejects bare integers.
+const duration = (defaultSeconds: number) => z.number().int().nonnegative().default(defaultSeconds);
+
+const healthcheckSchema = z.object({
+  test: z.array(z.string()),
+  interval: duration(3),
+  timeout: duration(5),
+  retries: z.number().int().nonnegative().default(10),
+  startPeriod: duration(10),
+});
+
+const containerPortSchema = z.number().int().min(1).max(65535);
+
+const routerSchema = z.object({
+  name: z.string().min(1).optional(),
+  icon: appIconSchema.optional(),
+  // Home-screen tile opt-out. Absent = shown; `false` keeps the gated route
+  // but drops the tile (machine-facing endpoints like webhooks/registries).
+  // Optional rather than `.default(true)` so only opted-out routers carry
+  // the field in resolved state.
+  tile: z.boolean().optional(),
+  containerPort: containerPortSchema,
+  // The whole resolved `r.home.publicDomain()` value, hosts and redirect mode
+  // together. No `stringOrRef` arm: that would let a bare author-supplied
+  // string in through the back door, which is what the permission closes.
+  // Absent when the app declares no such permission or none was granted.
+  publicDomain: publicDomainValueSchema.optional(),
+  pathPrefix: z
+    .string()
+    .regex(/^\/[a-zA-Z0-9/_-]*$/, "pathPrefix must start with / and contain only [a-zA-Z0-9/_-]")
+    .optional(),
+  compress: z.boolean().default(true),
+  maxRequestSizeMb: z.number().nullable().default(4),
+  rateLimit: z
+    .union([
+      z.number(),
+      z.object({
+        requests: z.number(),
+        window: z.string().regex(/^\d+(ms|s|m|h)$/, "window must be a duration like 10s, 1m, 1h"),
+      }),
+    ])
+    .nullable()
+    // A runaway-client guard, not a browsing budget: one page load is ~80
+    // requests at the median and ~185 at p90 (HTTP Archive 2025), and grids
+    // like Immich or Plex fetch a few hundred thumbnails in a second. 100/s
+    // sustained from one address still catches a broken fetch loop; anything
+    // tighter (a public login form) is a per-route decision for the author.
+    .default({ requests: 1000, window: "10s" }),
+  headers: z.record(z.string(), z.string().nullable()).optional(),
+});
+
+const hostPortSchema = z.object({
+  containerPort: containerPortSchema,
+  hostPort: hostPortNumberSchema,
+  protocol: z.enum(["tcp", "udp"]).optional(),
+});
+
+const backupStrategySchema = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("file-copy") }),
+  z.object({ kind: z.literal("sqlite"), file: z.string() }),
+  z.object({
+    kind: z.literal("pg-dump"),
+    url: stringOrRef,
+    version: z.number().int().positive(),
+  }),
+  z.object({ kind: z.literal("valkey-save"), url: stringOrRef }),
+  z.object({
+    kind: z.literal("mysql-dump"),
+    url: stringOrRef,
+    version: z.number().int().positive(),
+  }),
+]);
+
+const absoluteContainerPath = z.string().startsWith("/", {
+  message: "containerPath must be absolute (start with '/')",
+});
+
+const homeServiceSchema = z
+  .object({
+    // Exactly one of `image` / `build` is present (enforced in the
+    // superRefine below). `image` is the prebuilt-pull path; `build` is the
+    // build-from-source path, which has no pinned digest until its first
+    // build, so Home leaves the app inert until one is set.
+    image: imageReferenceSchema.optional(),
+    // `build: true` is author sugar for the default recipe — normalize it to
+    // `{}` here so `HomeService.build` is always a `BuildRecipe` object.
+    // The image/build XOR (superRefine below) reads the transformed value, so
+    // `true`/`{}` both count as "build present".
+    build: z
+      .literal(true)
+      .or(buildRecipeSchema)
+      .transform((v): BuildRecipe => (v === true ? {} : v))
+      .optional(),
+    router: routerSchema.optional(),
+    hostPorts: z.array(hostPortSchema).optional(),
+    env: z.record(z.string(), z.union([stringOrRef, z.number()])).optional(),
+    files: z.record(absoluteContainerPath, stringOrRef).optional(),
+    command: z.array(stringOrRef).optional(),
+    volumes: z
+      .array(
+        z.object({
+          hostPath: hostPathSchema,
+          containerPath: absoluteContainerPath,
+          // Silo-owned group. Present only on a Silo's volume entry; the
+          // renderer derives `group_add` from it and the grant gate matches
+          // (hostPath, gid) against the Silos the app joined.
+          gid: z.number().int().positive().optional(),
+          readOnly: z.boolean().optional(),
+          backup: z.union([backupStrategySchema, z.literal(false)]).optional(),
+        }),
+      )
+      .optional(),
+    gpu: z.boolean().optional(),
+    iptables: z.boolean().optional(),
+    joinNetworks: z.array(z.string()).optional(),
+    healthcheck: healthcheckSchema.optional(),
+    memory: z.string().optional(),
+    cpu: z.number().positive().max(128).optional(),
+    replicas: z.number().int().min(1).max(100).default(1),
+    labels: z.array(z.string()).optional(),
+    shmSizeMb: z.number().int().positive().optional(),
+  })
+  .strict()
+  .superRefine((svc, ctx) => {
+    // Exactly one of `image` / `build`. The type-level XOR on
+    // ServiceDefinition catches this at author time; this is the runtime
+    // backstop for sandbox-produced state, where the types are erased.
+    if (svc.image == null && svc.build == null) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["image"],
+        message: "a service must set either `image` or `build`",
+      });
+    } else if (svc.image != null && svc.build != null) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["build"],
+        message: "a service cannot set both `image` and `build`",
+      });
+    }
+
+    // Two volumes on one containerPath hit the same "duplicate mount point"
+    // failure as the files/volumes collision below. Reachable by mounting one
+    // resolved value twice, or alongside a hand-written path matching it.
+    const seen = new Set<string>();
+    for (const [i, vol] of (svc.volumes ?? []).entries()) {
+      if (seen.has(vol.containerPath)) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["volumes", i, "containerPath"],
+          message: `containerPath ${vol.containerPath} is mounted by two volumes`,
+        });
+      }
+      seen.add(vol.containerPath);
+    }
+
+    // `files:` and `volumes:` both emit bind mounts in the rendered
+    // compose. A collision on containerPath produces a "duplicate mount
+    // point" error at `docker compose up`, far from the source. Reject
+    // here so the author sees the conflict at validation time.
+    if (!svc.files || !svc.volumes) return;
+    const volumePaths = new Set(svc.volumes.map((v) => v.containerPath));
+    for (const fileKey of Object.keys(svc.files)) {
+      if (volumePaths.has(fileKey)) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["files", fileKey],
+          message: `containerPath ${fileKey} is used by both files: and volumes:`,
+        });
+      }
+    }
+  });
+
+export type HomeService = z.infer<typeof homeServiceSchema>;
+
+// ui surface manifest. Output/input schemas are emitted as JSON Schema
+// (z.toJSONSchema) so they survive the sandbox boundary; headers can carry
+// refs (e.g. r.stableSecret) the walker resolves under the app's grant
+// scope. `service`/`port` are the grant boundary (which container), so they
+// are flat and static here; the per-call verb/path/query/body comes from the
+// loader's `request(state, config)` fn in the iframe.
+
+// The request descriptor a loader's `request(state, config)` returns. Not a
+// manifest field — Home builds these live at prefill time (stitchLoaderRequests)
+// and the iframe runtime builds one per render; both feed it to the proxy.
+const requestManifestSchema = z.object({
+  method: z.enum(["GET", "POST", "PUT", "PATCH", "DELETE"]),
+  path: z.string(),
+  query: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).optional(),
+  body: z.unknown().optional(),
+});
+
+const loaderManifestSchema = z.object({
+  service: z.string(),
+  port: z.number().int().positive().max(65535),
+  headers: z.record(z.string(), stringOrRef).optional(),
+  outputSchema: z.unknown(),
+  merge: z.literal(true).optional(),
+});
+
+// Actions are mutations — `outputSchema` is optional (authors often don't
+// care about the response). The caller passes an explicit input at
+// `mutate(input)` time, so actions keep an `inputSchema` where loaders read
+// the widget's state. No `merge` knob: a system app resolves with the raw
+// `{ results, failures }` envelope, a single app with the upstream body.
+// Actions are never prefilled; the request is built at call time.
+const actionManifestSchema = z.object({
+  service: z.string(),
+  port: z.number().int().positive().max(65535),
+  headers: z.record(z.string(), stringOrRef).optional(),
+  inputSchema: z.unknown(),
+  outputSchema: z.unknown().optional(),
+});
+
+const baseSurfaceManifestSchema = z.object({
+  title: z.string().min(1),
+  // Icon name from `@yourrealm/sdk/ui/components/icons.tsx` named exports.
+  // Runtime is just `string` (the TS-side `IconName` union catches
+  // typos at authoring time); the Home sidebar falls back to a default
+  // glyph if a value isn't a known export, so a typo doesn't 500.
+  icon: z.string().min(1),
+  // The surface's live UI state + settings schemas (JSON Schema form).
+  // `configSchema` (built from the config leaves' zod schemas) lets Home
+  // validate a submitted config; `stateSchema`'s `{}`-parse seeds the
+  // runtime's initial state.
+  stateSchema: z.unknown().optional(),
+  configSchema: z.unknown().optional(),
+  // The config form's render descriptor: one `ConfigFieldLeaf` per
+  // `r.input.*` leaf (type/label/placeholder/default/enum values/bounds),
+  // so the tile's config screen reuses the same field renderer the app
+  // install/edit form uses. Absent when the surface takes no config.
+  configFields: z.unknown().optional(),
+  // The surface's resolved config: each leaf's `.prefill()` default,
+  // shipped to the iframe as the base layer for every loader's
+  // request(state, config) (Home merges the placement's persisted config
+  // over it).
+  defaultConfig: z.unknown().optional(),
+  loaders: z.record(z.string(), loaderManifestSchema).optional(),
+  actions: z.record(z.string(), actionManifestSchema).optional(),
+});
+
+// Widget-only tile size in 8rem grid cells. Defaults materialize here
+// so every persisted widget entry is self-describing — DB rows carry
+// the actual `cols`/`rows`, no consumer-side `?? 2` fallbacks needed.
+// Mobile collapse formula lives in `home-grid.tsx`.
+const widgetManifestSchema = baseSurfaceManifestSchema.extend({
+  cols: z.number().int().min(1).default(2),
+  rows: z.number().int().min(1).default(2),
+});
+
+const uiManifestSchema = z.object({
+  pages: z.record(z.string(), baseSurfaceManifestSchema).optional(),
+  widgets: z.record(z.string(), widgetManifestSchema).optional(),
+});
+
+// Wire-side TS types inferred from the schemas above; consumers outside the
+// SDK reach them via the `/compile` barrel re-export. Author-facing types
+// (`Page`, `Widget`, `Loader`, `UiConfig`) live in `ui-surface.ts` because
+// they carry render fns and live Zod schemas that can't survive a JSON
+// round-trip.
+export type LoaderManifest = z.infer<typeof loaderManifestSchema>;
+export type ActionManifest = z.infer<typeof actionManifestSchema>;
+export type RequestManifest = z.infer<typeof requestManifestSchema>;
+export type SurfaceManifest = z.infer<typeof baseSurfaceManifestSchema>;
+export type WidgetManifest = z.infer<typeof widgetManifestSchema>;
+export type UiManifest = z.infer<typeof uiManifestSchema>;
+export type ManifestHeader = z.infer<typeof stringOrRef>;
+
+// Header brokering manifest, sampled from `getTrustedHeaders` at eval time.
+// `keys` is the static union of header names across roles (Caddy injects
+// these and anti-spoof strips them). `byRole` maps each header name to its
+// source: a `user` field, a literal string, or a `template` of literal +
+// field segments (when the author interpolates, e.g. `i`Bearer
+// ${user.username}``). The verify hop substitutes the live value.
+const headerFieldSchema = z.object({ field: z.enum(["username", "email"]) });
+const headerSegmentSchema = z.union([z.string(), headerFieldSchema]);
+const authHeaderSourceSchema = z.union([
+  headerFieldSchema,
+  z.object({ literal: z.string() }),
+  z.object({ template: z.array(headerSegmentSchema) }),
+]);
+const trustedHeadersManifestSchema = z.object({
+  keys: z.array(z.string()),
+  byRole: z.record(z.enum(["admin", "member"]), z.record(z.string(), authHeaderSourceSchema)),
+});
+
+export type TrustedHeaderSource = z.infer<typeof authHeaderSourceSchema>;
+export type TrustedHeadersManifest = z.infer<typeof trustedHeadersManifestSchema>;
+
+// The resolved form of an app's `DesiredApp` (what `getDesiredState`
+// returns): services + egress + the ui / auth / routing manifests, after
+// `resolveDesiredApp()` flattens Service instances to definitions and the
+// Home walker bakes refs to literals. Home's internal per-app model — it
+// lives as `AppEval.app` and is what `build-wire` projects the worker wire
+// (`WorkerApp`) out of, dropping the Home-only fields (`ui`,
+// `trustedHeaders`, `hasAnonymousGate`, `kind`).
+export const homeAppSchema = z.object({
+  services: z.record(nameSchema, homeServiceSchema),
+  egress: z.literal(true).optional(),
+  ui: uiManifestSchema.optional(),
+  trustedHeaders: trustedHeadersManifestSchema.optional(),
+  // True when the app declares verifyAnonymousRequest. Home-side only (never
+  // crosses to the worker wire); recompute reads it to register the app's
+  // routed hosts in the anonymous-gate cache.
+  hasAnonymousGate: z.boolean().optional(),
+  // Single = run on one selected worker (default). System = fan out to
+  // every compatible worker. Drives the install panel's picker and the
+  // Home's UI fan-out behavior. See platform/docs realm-ts/workers.mdx.
+  kind: z.enum(["single", "system"]).default("single"),
+});
+
+export type HomeApp = z.infer<typeof homeAppSchema>;
+
+/**
+ * Scans the services map for Service instances and assigns service keys.
+ * After this, refs resolve (e.g. db.url becomes the real string).
+ *
+ * Returns the resolved desired state — Service instances are replaced
+ * with their input definitions for the Worker.
+ *
+ * `opts.appId`, when provided, namespaces each Service's key as
+ * `${appId}_${serviceKey}` so `host` refs resolve to the DNS name a
+ * sibling container will see in the merged worker compose project.
+ */
+export function resolveDesiredApp(
+  state: {
+    services?: Record<string, Service | ServiceDefinition>;
+    egress?: true;
+    ui?: UiManifest;
+    trustedHeaders?: TrustedHeadersManifest;
+    hasAnonymousGate?: boolean;
+    kind?: "single" | "system";
+  },
+  opts: { appId?: string } = {},
+): HomeApp {
+  const resolvedServices: Record<string, unknown> = {};
+
+  for (const [key, service] of Object.entries(state.services ?? {})) {
+    if (service instanceof Service) {
+      const qualifiedKey = opts.appId ? `${opts.appId}_${key}` : key;
+      service._setServiceKey(qualifiedKey);
+      resolvedServices[key] = service.getServiceDefinition();
+    } else {
+      resolvedServices[key] = service;
+    }
+  }
+
+  // Re-serialize to resolve all refs (`JSON.stringify` materializes ref
+  // proxies via their `toJSON`), then validate. Round-trip is a deep
+  // clone of data we just constructed; no untrusted input.
+  const serialized = JSON.parse(JSON.stringify({ ...state, services: resolvedServices }));
+  return homeAppSchema.parse(serialized);
+}

package/src/runtime/docker/compose/compose-schema.ts

@@ -0,0 +1,118 @@
+// Validation schema for the docker-compose YAML the renderer produces.
+// Used by Home integration tests to assert the generated output round-trips
+// against the compose grammar Realm actually emits — strict so a stray
+// field surfaces as a test failure rather than a silent passthrough.
+
+import { z } from "zod";
+
+const volumeSchema = z
+  .object({
+    type: z.enum(["bind", "volume"]),
+    source: z.string(),
+    target: z.string(),
+    read_only: z.boolean().optional(),
+  })
+  .strict();
+
+const portSchema = z
+  .object({
+    target: z.number().int(),
+    published: z.number().int(),
+    protocol: z.enum(["tcp", "udp"]).optional(),
+  })
+  .strict();
+
+const healthcheckSchema = z
+  .object({
+    test: z.array(z.string()),
+    interval: z.string().optional(),
+    timeout: z.string().optional(),
+    retries: z.number().int().optional(),
+    start_period: z.string().optional(),
+  })
+  .strict();
+
+const deploySchema = z
+  .object({
+    replicas: z.number().int().optional(),
+    resources: z
+      .object({
+        limits: z
+          .object({
+            memory: z.string().optional(),
+            cpus: z.string().optional(),
+          })
+          .strict()
+          .optional(),
+      })
+      .strict()
+      .optional(),
+  })
+  .strict();
+
+const dependsOnEntrySchema = z
+  .object({
+    condition: z.enum(["service_healthy", "service_started", "service_completed_successfully"]),
+    restart: z.boolean().optional(),
+  })
+  .strict();
+
+const loggingSchema = z
+  .object({
+    driver: z.string(),
+    options: z.record(z.string(), z.string()).optional(),
+  })
+  .strict();
+
+const composeServiceSchema = z
+  .object({
+    image: z.string(),
+    environment: z.record(z.string(), z.string()).optional(),
+    env_file: z.union([z.string(), z.array(z.string())]).optional(),
+    command: z.array(z.string()).optional(),
+    labels: z.record(z.string(), z.string()).optional(),
+    volumes: z.array(volumeSchema).optional(),
+    group_add: z.array(z.number().int().positive()).optional(),
+    ports: z.array(portSchema).optional(),
+    healthcheck: healthcheckSchema.optional(),
+    deploy: deploySchema.optional(),
+    cap_drop: z.array(z.string()).optional(),
+    cap_add: z.array(z.string()).optional(),
+    security_opt: z.array(z.string()).optional(),
+    pids_limit: z.number().int().optional(),
+    ulimits: z.record(z.string(), z.number().int()).optional(),
+    shm_size: z.string().optional(),
+    devices: z.array(z.string()).optional(),
+    network_mode: z.string().optional(),
+    restart: z.string().optional(),
+    stop_grace_period: z.string().optional(),
+    depends_on: z.record(z.string(), dependsOnEntrySchema).optional(),
+    networks: z
+      .record(
+        z.string(),
+        z
+          .object({
+            aliases: z.array(z.string()).optional(),
+          })
+          .strict(),
+      )
+      .optional(),
+    logging: loggingSchema.optional(),
+  })
+  .strict();
+
+const composeNetworkSchema = z
+  .object({
+    name: z.string().optional(),
+    external: z.boolean().optional(),
+    internal: z.boolean().optional(),
+    driver: z.string().optional(),
+  })
+  .strict();
+
+export const composeSchema = z
+  .object({
+    services: z.record(z.string(), composeServiceSchema),
+    networks: z.record(z.string(), composeNetworkSchema).optional(),
+  })
+  .strict();