@yourrealm/sdk 0.0.0-alpha.1378.ce03c8dc

package/src/service-definition.ts

@@ -0,0 +1,284 @@
+import type { AppIcon } from "./app-icon.ts";
+import type { Network } from "./identifiers.ts";
+import type { Resolvable } from "./ref.ts";
+import type { Artifact } from "./schema/remote.ts";
+import type { PeerHostPath } from "./schema/peer.ts";
+import type { SiloHostPath } from "./schema/host.ts";
+import type { PublicDomainValue } from "./schema/public-domain.ts";
+import type { WorkerHostPath } from "./worker-protocol/logs-socket-path.ts";
+
+/**
+ * Build a service's image from source instead of pulling one. The recipe
+ * only - no `repo` / `branch` (those are the build service's binding, set
+ * elsewhere). A service carries either `image` or `build`, never both and
+ * never neither (enforced at the type level on `ServiceDefinition` and again
+ * at runtime in `homeServiceSchema`). A `build:` service has no pinned
+ * digest until its first build, so Home leaves it inert (installed, not
+ * reconciled) until one is set.
+ */
+export interface BuildRecipe {
+  /** Path to the Dockerfile within the build context. Defaults to `Dockerfile`. */
+  dockerfile?: string;
+  /** `--build-arg` values passed to the builder, keyed by arg name. */
+  buildArgs?: Record<string, string>;
+  /** Sub-path within the build context to build from. Defaults to the context root. */
+  context?: string;
+}
+
+/**
+ * The `router` block of a routed (single-app) service. Split out of the
+ * common base so `SystemServiceDefinition` can exclude it wholesale:
+ * system apps have no routes.
+ */
+interface ServiceRouter {
+  /**
+   * Human-readable label shown on the Home home screen tile. Falls back
+   * to the app's top-level `name` when omitted.
+   */
+  name?: string;
+  /**
+   * Icon for the tile: a `dashboard-icons:<key>` or `selfhst:<key>` pack key,
+   * or an https URL to an svg/png/webp/jpeg. Home fetches it once and serves
+   * it same-origin, so the browser never reaches the source.
+   */
+  icon?: AppIcon;
+  /**
+   * Show a clickable tile for this service on the Home home screen.
+   * Defaults to `true`. Set `false` for machine-facing routes that need
+   * the gated subdomain but aren't a human-browsable app (e.g. a webhook
+   * receiver or a registry endpoint) — the route still works, it just
+   * doesn't appear as a home tile.
+   */
+  tile?: boolean;
+  /** Port inside the container the proxy forwards to. */
+  containerPort: number;
+  /**
+   * Serve this service on the operator's own domain(s), in addition to
+   * the authenticated subdomain it always gets.
+   *
+   * Takes the resolved value of a `r.home.publicDomain()` permission whole -
+   * hostnames and the operator's redirect choice travel together, so wiring
+   * the domains can't leave the mode behind. A literal string is deliberately
+   * not accepted: the operator supplies the name, the author only says where
+   * it lands. Unconfigured (`{ hosts: [] }`) emits no public route.
+   */
+  publicDomain?: PublicDomainValue;
+  /**
+   * Route only requests matching this path prefix. The prefix is
+   * stripped before forwarding to the container.
+   */
+  pathPrefix?: string;
+  /** Enable response compression (gzip / zstd). */
+  compress?: boolean;
+  /**
+   * Max request body size in megabytes. `null` disables the cap.
+   */
+  maxRequestSizeMb?: number | null;
+  /**
+   * Per-IP sliding-window request budget: no more than `requests`
+   * in any `window` (a duration like `"10s"` / `"1m"`). A bare number
+   * is shorthand for that many requests per second. Defaults to 1000 per
+   * 10s, a runaway-client ceiling rather than a browsing budget; tighten
+   * it on routes that need it. `null` disables rate limiting.
+   */
+  rateLimit?: number | { requests: number; window: string } | null;
+  /**
+   * Static response headers to add. A `null` value removes a default
+   * header the proxy would otherwise set.
+   */
+  headers?: Record<string, string | null>;
+}
+
+/**
+ * Fields shared by every service, independent of whether it pulls an
+ * `image` or carries a `build` recipe — and independent of whether it may
+ * route. Not exported - `ServiceDefinition` / `SystemServiceDefinition`
+ * are the public surfaces, XORs over this base. `router` is layered on by
+ * `ServiceCommon` (single apps only): system apps have no routes, so
+ * `SystemServiceDefinition` builds on this routeless base directly.
+ */
+interface RoutelessServiceCommon {
+  /**
+   * Bind container ports to ports on the worker host. Each entry maps a
+   * `containerPort` to a `hostPort` (TCP unless `protocol` says
+   * otherwise). Every `hostPort` requires a matching `host.port` grant.
+   */
+  hostPorts?: Array<{ containerPort: number; hostPort: number; protocol?: "tcp" | "udp" }>;
+  /**
+   * Environment variables passed into the container. Values can be
+   * plain strings/numbers or refs (derived secrets, peer outputs, etc.)
+   * that resolve at deploy time.
+   */
+  env?: Record<string, string | Resolvable<string> | number>;
+  /**
+   * Files mounted read-only into the container, keyed by absolute
+   * container path. Values are inline text, a `remote.artifact` ref, or
+   * a resolvable string. Useful for config files the app reads at
+   * startup.
+   */
+  files?: Record<string, string | Artifact | Resolvable<string>>;
+  /** Override the image's default command (entrypoint args). */
+  command?: (string | Resolvable<string>)[];
+  /**
+   * Bind-mount directories from the host into the container. Relative
+   * `./...` paths are scoped to the app's data dir; absolute paths only
+   * come from resolved permissions (a Silo's volume, broker socket dirs).
+   */
+  volumes?: Array<{
+    /**
+     * Source path on the host. Relative `./...` is scoped to the app's
+     * own data dir under `/opt/realm/`; absolute paths come from resolved
+     * permissions and are gated against them.
+     */
+    hostPath: `./${string}` | PeerHostPath | WorkerHostPath | SiloHostPath | Resolvable<string>;
+    /** Mount point inside the container. */
+    containerPath: string;
+    /**
+     * Group that owns the mounted directory. Set by a Silo, never written by
+     * hand - the renderer turns it into `group_add` on every service that
+     * mounts this volume, and the grant gate matches the (hostPath, gid) pair
+     * against the Silos the app was bound to.
+     */
+    gid?: number;
+    /**
+     * Mount read-only. Opt-in: a mount an app declared is a mount it means to
+     * use, and writing to it is the common case. A Silo's volume entry sets
+     * this from the mode the app asked for (`volume: "read"` -> `true`).
+     */
+    readOnly?: boolean;
+    /**
+     * Backup strategy for this volume. `file-copy` snapshots files via
+     * restic; `sqlite` runs an online `.backup` against the named file;
+     * the dump strategies (`pg-dump`, `valkey-save`, `mysql-dump`)
+     * snapshot via the appropriate dump tool. `false` opts out.
+     */
+    backup?:
+      | { kind: "file-copy" }
+      | { kind: "sqlite"; file: string }
+      | { kind: "pg-dump"; url: string | Resolvable<string>; version: number }
+      | { kind: "valkey-save"; url: string | Resolvable<string> }
+      | { kind: "mysql-dump"; url: string | Resolvable<string>; version: number }
+      | false;
+  }>;
+  /** Pass through the host's GPU. Requires `host.gpu` grant. */
+  gpu?: boolean;
+  /**
+   * Install host-level iptables / ip6tables rules from this container.
+   * Expands to `cap_add: NET_ADMIN` + `network_mode: host` at render
+   * time. Requires `host.iptables` grant.
+   */
+  iptables?: boolean;
+  /**
+   * Extra Docker networks to join (e.g. another app's network when this
+   * app has a `peers.routedApps` or `peers.backupVolumes` grant).
+   */
+  joinNetworks?: Network[];
+  /**
+   * Container healthcheck. The reconciler waits for `healthy` before
+   * declaring the deploy successful, so failing healthchecks block
+   * rollout instead of silently leaving a broken container running.
+   */
+  healthcheck?: {
+    /**
+     * Healthcheck command in Docker exec form, e.g.
+     * `["CMD", "curl", "-f", "http://localhost"]`.
+     */
+    test: string[];
+    /** Seconds between checks. */
+    interval?: number;
+    /** Seconds before a check is considered failed. */
+    timeout?: number;
+    /** Failed checks before the container is marked unhealthy. */
+    retries?: number;
+    /**
+     * Grace period in seconds. Failed checks during this window don't
+     * count toward `retries`.
+     */
+    startPeriod?: number;
+  };
+  /** Hard memory limit (e.g. `"512m"`, `"1g"`). */
+  memory?: string;
+  /** Hard CPU limit, fractional cores allowed. */
+  cpu?: number;
+  /** Number of identical containers to run for this service. */
+  replicas?: number;
+  /**
+   * Additional Docker labels on the container. The `realm.*` namespace
+   * is reserved.
+   */
+  labels?: string[];
+  /**
+   * Shared memory size in megabytes (`/dev/shm`). Bumped for apps that
+   * use a lot of shared memory (e.g. browsers).
+   */
+  shmSizeMb?: number;
+}
+
+/**
+ * A single-app service: the routeless base plus the `router` block.
+ */
+interface ServiceCommon extends RoutelessServiceCommon {
+  /**
+   * Expose this service on the proxy. The container is reached over
+   * TLS at the configured public domain - the proxy app handles
+   * routing, TLS, and headers.
+   */
+  router?: ServiceRouter;
+}
+
+/**
+ * A service either pulls a prebuilt `image` or carries a `build` recipe -
+ * exactly one, never both, never neither. The `?: never` arms make
+ * supplying the wrong one (or omitting both) a compile-time error in the
+ * realm.ts author's editor and under `realm-sdk test`; `homeServiceSchema`
+ * enforces the same rule at runtime for sandbox-produced state.
+ */
+export type ServiceDefinition =
+  | (ServiceCommon & {
+      /**
+       * Docker image reference. A tag (`postgres:16`) is fine; Home
+       * re-pins it to a SHA digest at install time so every worker pulls
+       * the exact same bytes.
+       */
+      image: string;
+      build?: never;
+    })
+  | (ServiceCommon & {
+      /**
+       * Build this service's image from source. Mutually exclusive with `image`.
+       * `true` is sugar for `{}` (root `Dockerfile`, no build args); pass a
+       * `BuildRecipe` to point at a non-default Dockerfile / context / args.
+       */
+      build: true | BuildRecipe;
+      image?: never;
+    });
+
+/**
+ * A system-app service: the same image/build XOR, but over the routeless
+ * base with `router` tombstoned. System apps have no routes — no
+ * authenticated subdomains, no public domains; genuine network exposure
+ * goes through `host.port`. The XOR is
+ * restated rather than `Omit<>`-ed off `ServiceDefinition` because
+ * `Omit` over a union doesn't distribute.
+ */
+export type SystemServiceDefinition =
+  | (RoutelessServiceCommon & {
+      /**
+       * Docker image reference. A tag (`postgres:16`) is fine; Home
+       * re-pins it to a SHA digest at install time so every worker pulls
+       * the exact same bytes.
+       */
+      image: string;
+      build?: never;
+      router?: never;
+    })
+  | (RoutelessServiceCommon & {
+      /**
+       * Build this service's image from source. Mutually exclusive with `image`.
+       * `true` is sugar for `{}` (root `Dockerfile`, no build args); pass a
+       * `BuildRecipe` to point at a non-default Dockerfile / context / args.
+       */
+      build: true | BuildRecipe;
+      image?: never;
+      router?: never;
+    });

package/src/service-url.ts

@@ -0,0 +1,64 @@
+// Service URL resolution — the single place that turns an
+// `(appId, serviceId, slug, baseDomain)` tuple into the external host a
+// service is reachable at. Pure string logic, no host globals, so it stays
+// QuickJS-load-safe when pulled in through the `@yourrealm/sdk/compile` barrel.
+
+/**
+ * The structured authenticated subdomain host for a routed service:
+ * `{appId}-{serviceId}.{slug}.{baseDomain}`. `{appId}-{serviceId}` is a
+ * single DNS label (appId already carries its install nanoid), one level
+ * under the per-worker wildcard `*.{slug}.{baseDomain}` the acme-dns policy
+ * issues a cert for. Host only — callers prefix the scheme.
+ */
+export function structuredHost(
+  appId: string,
+  serviceId: string,
+  slug: string,
+  baseDomain: string,
+): string {
+  return `${appId}-${serviceId}.${slug}.${baseDomain}`;
+}
+
+/**
+ * Resolve a service to its full external `https://` URL, or `null` when it
+ * has no reachable URL. The rules, in order:
+ *
+ *   1. No `router` → no external URL at all → `null`.
+ *   2. A `publicDomain` set on the router → `https://{publicDomain}`.
+ *   3. Otherwise the structured authenticated subdomain Home provisions —
+ *      needs both the placement `slug` and the Home's `baseDomain`; `null`
+ *      if either is missing (install not yet on a worker / Home has no base
+ *      domain).
+ */
+export function serviceUrl(args: {
+  appId: string;
+  serviceId: string;
+  slug: string | null;
+  baseDomain: string | null;
+  /** Resolved `router.publicDomain` (first entry if it was an array), if any. */
+  publicDomain?: string;
+  hasRouter: boolean;
+}): string | null {
+  if (!args.hasRouter) return null;
+  if (args.publicDomain) return `https://${args.publicDomain}`;
+  if (!args.slug || !args.baseDomain) return null;
+  return `https://${structuredHost(args.appId, args.serviceId, args.slug, args.baseDomain)}`;
+}
+
+/**
+ * The canonical host out of a router's `publicDomain` - the resolved
+ * `r.home.publicDomain()` record, whose `hosts[0]` is canonical by
+ * convention. `undefined` for an absent record or an empty `hosts` (the
+ * operator enabled the permission but supplied no domain), so `serviceUrl`
+ * falls back to the structured subdomain.
+ *
+ * Takes `unknown` because the callers reach it from four differently-typed
+ * router shapes (resolved state, the wire, a Home DB row, dev state); the
+ * shape check is here once rather than in each of them.
+ */
+export function firstPublicDomain(publicDomain: unknown): string | undefined {
+  if (publicDomain == null || typeof publicDomain !== "object") return undefined;
+  const hosts = (publicDomain as { hosts?: unknown }).hosts;
+  if (Array.isArray(hosts) && typeof hosts[0] === "string") return hosts[0];
+  return undefined;
+}

package/src/service.ts

@@ -0,0 +1,39 @@
+import type { Ref } from "./ref.ts";
+import { ref, stringRef } from "./ref.ts";
+import type { ServiceDefinition } from "./service-definition.ts";
+
+/** The placeholder appId that `derived()` emits for own-app derived secrets. */
+export const SELF_APP_ID = "__self__";
+
+/**
+ * Base class for service presets (Postgres, Valkey, Garage, etc.).
+ */
+export abstract class Service {
+  private _serviceKey: string | undefined;
+
+  /** Called by the framework after scanning the services map */
+  _setServiceKey(key: string) {
+    this._serviceKey = key;
+  }
+
+  /**
+   * A per-service derived secret. Within the same app, same-named secrets
+   * collide intentionally (Postgres.password and Valkey.password in the
+   * same app share a hash) - that's the ergonomic contract.
+   */
+  protected derived(name: string): Ref<string> {
+    return ref({ kind: "derived", appId: SELF_APP_ID, name });
+  }
+
+  /**
+   * DNS name of this service within the per-app compose project. Resolves
+   * to a plain string at serialization time - `_setServiceKey` is
+   * guaranteed to have run before `getServiceDefinition`, which is the
+   * only time a `host` ref is serialized.
+   */
+  get host(): Ref<string> {
+    return stringRef(() => this._serviceKey ?? "__unresolved__");
+  }
+
+  abstract getServiceDefinition(): ServiceDefinition;
+}

package/src/services/index.ts

@@ -0,0 +1,5 @@
+export { Postgres } from "../postgres.ts";
+export { MySQL } from "../mysql.ts";
+export { Valkey } from "../valkey.ts";
+export { Redis } from "../redis.ts";
+export { Garage } from "../garage.ts";

package/src/shared.ts

@@ -0,0 +1,65 @@
+// Shared types for the permissions/inputs factory system.
+//
+// No runtime here — only kinds, mixin interfaces, and the Builder type
+// machinery. All concrete factories (host.*, input.*, etc.) build on these.
+
+import type { z } from "zod";
+
+// ----- Kinds ---------------------------------------------------------------
+//
+// The closed `PermissionKind` (and its host/peer/remote subsets) is
+// derived from the actual factory exports — see permissions.ts. It can't
+// live here: the derivation walks schema/*, which depends on factory.ts,
+// which imports this file — a type-level cycle. shared.ts carries only the
+// inline shapes Builder uses.
+
+export type InputKind =
+  | "input.text"
+  | "input.secret"
+  | "input.number"
+  | "input.boolean"
+  | "input.enum";
+
+// ----- Factory shape -------------------------------------------------------
+
+export type Mode = "perm" | "input";
+
+// Schema-aware factory shape. Zod's input/output split lets `.default(...)`
+// schemas (input: T | undefined, output: T) keep the no-arg call form while
+// data lands as the parsed output: the arg is optional when `undefined` is
+// assignable to the schema's input, so `r.host.gpu()` typechecks but
+// `r.host.port(80)` still requires the literal port.
+export type FactoryFor<
+  S extends z.ZodType,
+  K,
+  BaseR extends object,
+  M extends Mode,
+> = M extends "perm"
+  ? (
+      ...args: undefined extends z.input<S> ? [input?: z.input<S>] : [input: z.input<S>]
+    ) => BaseR & { readonly kind: K; readonly data: z.output<S> }
+  : () => BaseR & { readonly kind: K; readonly schema: S };
+
+export type Builder<BaseR extends object, M extends Mode, KindUnion extends string> = <
+  S extends z.ZodType,
+  K extends KindUnion,
+>(
+  kind: K,
+  schema: S,
+) => FactoryFor<S, K, BaseR, M>;
+
+// ----- Slot helpers --------------------------------------------------------
+
+export type AddRequiredSlot<M, K extends string, V> = M & { readonly [P in K]: V };
+export type AddOptionalSlot<M, K extends string, V> = M & { readonly [P in K]?: V };
+
+// ----- Slot-absence gate ---------------------------------------------------
+//
+// Refuses double-stacking the same wrapper. If K is already in M, the
+// rest-arg type is an impossible-to-satisfy [error: ...] tuple. If absent,
+// rest args are []. Inference of BaseR happens via `inner: Builder<BaseR>`,
+// not through this gate, so it stays clean.
+
+export type GateNoSlot<M, K extends string> = K extends keyof M
+  ? [error: `slot '${K & string}' already added — wrapper composed twice`]
+  : [];

package/src/speculative-silo.ts

@@ -0,0 +1,96 @@
+// The `host.silo` value a speculative eval sees when no Silo has been picked.
+//
+// The install preview grants every declared permission sight-unseen so the
+// review step can show what an app would ship before the operator commits.
+// `host.silo` is the one permission that cannot be granted that way: its
+// descriptor carries the author's affordances (`{volume: "readwrite"}`) while
+// its grant carries a Silo id the operator chooses, and there is no default
+// Silo to fall back on. Without a stand-in, every app that joins a Silo drops
+// out of its own preview and silently loses the whole Images panel.
+//
+// Lives in its own module rather than in `schema/host.ts` because `r.host` is
+// built from that file's entire namespace (`index.ts`), so anything exported
+// there becomes author-facing API - and this is the one value an author must
+// never be able to mint.
+//
+// Nothing here reaches a worker: `evalApps` refuses `speculative` without
+// `ephemeral`, and the two callers write no app row.
+
+import { siloNetwork } from "./worker-protocol/networks.ts";
+import type { SiloGrants, SiloHostPath, SiloResolved } from "./schema/host.ts";
+
+/**
+ * The stand-in Silo's identity. Deliberately not plausible: nothing downstream
+ * of a speculative eval reads these, and if something ever starts to, they are
+ * legible things to find in the output rather than values someone could mistake
+ * for the operator's own.
+ *
+ * `containerPath` is the exception and matches `DEFAULT_CONTAINER_PATH` in
+ * Home's `silos.ts`, because an author who reads `volume.containerPath` into an
+ * env var should see the usual string.
+ */
+export const SPECULATIVE_SILO = {
+  id: "speculative",
+  hostPath: "/speculative-silo",
+  containerPath: "/silo",
+  /**
+   * The volume schema requires a positive gid, so this cannot be 0. Home draws
+   * real Silo gids from a counter starting at 1,000,000 (`home_state.next_gid`),
+   * so anything below that floor can never name a group an operator has.
+   */
+  gid: 999_999,
+  /**
+   * Shape-faithful on purpose: 64 hex characters, the same as a derived key.
+   * A recognisable sentinel would look safer and behave worse - an app that
+   * validates its Silo key (`z.string().length(64)`, or a bare truthiness
+   * check) would drop out of its own preview, which is the exact failure this
+   * whole module exists to prevent.
+   */
+  apiKey: "0".repeat(64),
+} as const;
+
+/**
+ * Build the resolved value from the author's declaration alone.
+ *
+ * Everything the preview needs - which images, which services, whether
+ * anything mounts a volume - falls out of the declared shape. Which directory
+ * the bytes actually live in changes none of it.
+ *
+ * The require-map is answered from the ask rather than from the Silo's service
+ * directory, and the reason is structural rather than a judgement call: Home's
+ * preview evaluates the candidate on its own (`evalApps([candidate])`), so the
+ * directory is merged from an empty set and comes back empty for every Silo id.
+ * A require-map in preview is therefore unmet unconditionally - whatever the
+ * operator has installed, whichever Silo they would go on to pick. Answering
+ * from the ask declines to emit a signal that is always false. The real check
+ * still runs at install, where `speculative` is off and the operator has
+ * actually chosen a Silo, and it still produces `siloRequiresUnmetMessage`.
+ */
+export function speculativeSilo(asked: SiloGrants): SiloResolved {
+  const resolved: SiloResolved = {};
+  if (asked.network !== undefined) {
+    (resolved as { network: SiloResolved["network"] }).network = siloNetwork(SPECULATIVE_SILO.id);
+    if (asked.network !== true) {
+      const services: Record<string, { host: string; port: number }> = {};
+      for (const [name, port] of Object.entries(asked.network)) {
+        services[name] = { host: name, port };
+      }
+      (resolved as { services: SiloResolved["services"] }).services = services;
+    }
+  }
+  if (asked.volume !== undefined) {
+    (resolved as { volume: SiloResolved["volume"] }).volume = {
+      hostPath: SPECULATIVE_SILO.hostPath as SiloHostPath,
+      containerPath: SPECULATIVE_SILO.containerPath,
+      gid: SPECULATIVE_SILO.gid,
+      // The author declared the mode and the placeholder honours it: the shape
+      // an app sees must not change with the mode of the eval.
+      readOnly: asked.volume === "read",
+      backup: false,
+    };
+  }
+  if (asked.apiKey !== undefined) {
+    (resolved as { apiKey: SiloResolved["apiKey"] }).apiKey = SPECULATIVE_SILO.apiKey;
+  }
+  return resolved;
+}

package/src/stable-secret.ts

@@ -0,0 +1,14 @@
+import type { Ref } from "./ref.ts";
+import { ref } from "./ref.ts";
+import { SELF_APP_ID } from "./service.ts";
+
+/**
+ * App-scoped stable secret ref. Same name + same app yields the same
+ * value across deploys; different apps yield different values for the
+ * same name. Home resolves these via HMAC over
+ * `JSON(["derived-password", appId, name])` using a seed derived from
+ * `REALM_SECRET` (see `platform/home/src/server/keys.ts`).
+ */
+export function stableSecret(name: string): Ref<string> {
+  return ref({ kind: "derived", appId: SELF_APP_ID, name });
+}