@alchemy.run/archil 0.0.0 → 2.0.0-beta.87

package/src/SandboxOptions.ts

@@ -0,0 +1,230 @@
+import type * as archil from "@distilled.cloud/archil";
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as Redacted from "effect/Redacted";
+import type { Disk } from "./Disk.ts";
+import type { Providers } from "./Providers.ts";
+
+/**
+ * An allowed destination, with optional changes to outbound HTTPS requests
+ * that match it. Headers set here overwrite whatever the sandbox sends, so
+ * a credential injected at the boundary never enters the sandbox.
+ */
+export interface SandboxEgressTarget {
+  /** IPv4 address, CIDR range, exact domain, or `*.`-wildcard domain. */
+  target: string;
+  /** HTTP headers to set on matching HTTPS requests. */
+  headers?: Record<string, string | Redacted.Redacted<string>>;
+  /**
+   * Forward matching requests to this public HTTPS URL instead of their
+   * destination, such as a Worker that adds a credential. Archil appends
+   * the original path and query, applies `headers` first, and names the
+   * destination and the sandbox in `archil-forwarded-host`,
+   * `archil-forwarded-scheme`, `archil-forwarded-port`,
+   * `archil-forwarded-path` and `archil-sandbox-id` headers.
+   */
+  forwardUrl?: string;
+}
+
+/**
+ * Outbound network policy. Deny entries win when an address or domain
+ * matches both lists. Wildcards match subdomains, not the apex domain.
+ */
+export interface SandboxEgress {
+  /** What happens to destinations neither list names. */
+  default: "allow" | "deny";
+  /** Allowed destinations: addresses, CIDRs, domains, or targets with request changes. */
+  allow?: ReadonlyArray<string | SandboxEgressTarget>;
+  /** Denied addresses, CIDRs, or domains. */
+  deny?: ReadonlyArray<string>;
+  /**
+   * Hosts whose in-flight HTTP(S) requests finish before the sandbox
+   * pauses (ports 80 and 443 only). Doesn't grant access.
+   */
+  drainOnPause?: ReadonlyArray<string>;
+}
+
+/**
+ * How a mount shares the disk with other clients.
+ *
+ * - `exclusive` — this client owns writes to the whole disk (local-disk
+ *   speed); other clients can still mount `read-only`.
+ * - `shared` — many clients; the disk is read-only until a path is checked
+ *   out with `archil checkout <path>`. FUSE client only.
+ * - `conditional` — many writers; writes go to the server unless a path is
+ *   checked out (remote-filesystem speed).
+ * - `read-only` — no writes.
+ */
+export type MountMode = "exclusive" | "shared" | "conditional" | "read-only";
+
+/** A disk known at run time, e.g. a `DiskHandle` from `CreateDisk`. */
+export interface DiskRef {
+  readonly diskId: string;
+}
+
+/**
+ * The disk of a mount entry: a declared `Archil.Disk` (or the Effect that
+ * declares it), or a run-time handle with its `diskId`.
+ */
+export type MountableDisk = Disk | Effect.Effect<Disk, never, Providers> | DiskRef;
+
+/** How a disk is mounted, in Archil's own terms. */
+export interface DiskMountOptions {
+  /** Absolute directory to mount at. */
+  readonly path: string;
+  /** @default "exclusive" */
+  readonly mode?: MountMode;
+  /** Mount only this subdirectory of the disk. */
+  readonly subdirectory?: string;
+  /**
+   * Milliseconds to wait for the disk's exclusive root delegation before
+   * the mount fails. Only for `exclusive` mounts in an `Archil.Sandbox`.
+   */
+  readonly queueMs?: number;
+  /** Mount a branch of the disk instead of its root. FUSE client only. */
+  readonly branch?: string;
+  /**
+   * Take ownership of the root from a client that crashed without
+   * unmounting; that client's outstanding writes are lost. FUSE client only.
+   */
+  readonly force?: boolean;
+}
+
+/** A disk mounted into a sandbox (`mounts`), or by `MountDisk`. */
+export interface DiskMount extends DiskMountOptions {
+  readonly disk: MountableDisk;
+}
+
+/** A mount option the target doesn't support was set. */
+export class MountOptionUnsupported extends Data.TaggedError("Archil.MountOptionUnsupported")<{
+  readonly option: string;
+  readonly message: string;
+}> {}
+
+/** A mount entry whose disk isn't known yet. */
+export class MountDiskUnresolved extends Data.TaggedError("Archil.MountDiskUnresolved")<{
+  readonly path: string;
+  readonly message: string;
+}> {}
+
+/** The disk id of a resolved mount entry's disk, if it has one. */
+export const mountDiskId = (disk: unknown): string | undefined =>
+  typeof disk === "object" && disk !== null && "diskId" in disk && typeof disk.diskId === "string"
+    ? disk.diskId
+    : undefined;
+
+/**
+ * The wire shape of a sandbox mount. Archil sandboxes mount natively: no
+ * `shared` mode, branches, or `force`.
+ */
+export const toSandboxMount = Effect.fn(function* (diskId: string, mount: DiskMountOptions) {
+  const unsupported =
+    mount.mode === "shared"
+      ? 'mode: "shared"'
+      : mount.branch !== undefined
+        ? "branch"
+        : mount.force
+          ? "force"
+          : undefined;
+  if (unsupported !== undefined) {
+    return yield* new MountOptionUnsupported({
+      option: unsupported,
+      message: `An Archil sandbox can't mount a disk with ${unsupported} (only the FUSE client can); mount it at ${mount.path} without it.`,
+    });
+  }
+  if (mount.queueMs !== undefined && (mount.mode ?? "exclusive") !== "exclusive") {
+    return yield* new MountOptionUnsupported({
+      option: "queueMs",
+      message: `queueMs only applies to exclusive mounts (${mount.path} is ${mount.mode}).`,
+    });
+  }
+  return {
+    disk_id: diskId,
+    path: mount.path,
+    subdirectory: mount.subdirectory,
+    read_only: mount.mode === "read-only",
+    conditional: mount.mode === "conditional",
+    queue_ms: mount.queueMs,
+  } satisfies archil.SandboxMount;
+});
+
+/** A comparable form of a wire mount, defaults filled in. */
+export const mountIdentity = (mount: archil.SandboxMount) => ({
+  disk_id: mount.disk_id,
+  path: mount.path ?? "/mnt/archil",
+  subdirectory: mount.subdirectory || undefined,
+  read_only: mount.read_only ?? false,
+  conditional: mount.conditional ?? false,
+  queue_ms: mount.queue_ms ?? undefined,
+});
+
+/** A port a sandbox serves publicly. */
+export interface SandboxEndpoint {
+  port: number;
+  /** Public hostname that routes to the port. */
+  hostname: string;
+}
+
+const secretValue = (value: string | Redacted.Redacted<string>) =>
+  typeof value === "string" ? value : Redacted.value(value);
+
+/** The wire shape of an egress policy. */
+export const toEgressPolicy = (egress: SandboxEgress): archil.SandboxEgressPolicy => ({
+  default: egress.default,
+  allow: egress.allow?.map((entry) =>
+    typeof entry === "string"
+      ? entry
+      : {
+          target: entry.target,
+          transform: entry.headers
+            ? {
+                headers: Object.fromEntries(
+                  Object.entries(entry.headers).map(([k, v]) => [k, secretValue(v)]),
+                ),
+              }
+            : undefined,
+          forward_url: entry.forwardUrl,
+        },
+  ),
+  deny: egress.deny ? [...egress.deny] : undefined,
+  drain_on_pause: egress.drainOnPause ? [...egress.drainOnPause] : undefined,
+});
+
+const isArchilEgress = (entry: string | object) =>
+  typeof entry === "string" && /^(mount|data)\.\*\.archil\.com$/.test(entry);
+
+/**
+ * Split off the allow-list entries Archil adds itself to a sandbox that
+ * mounts disks (`mount.*.archil.com`, `data.*.archil.com`). They aren't
+ * part of the desired policy, but an update must keep them.
+ */
+export const splitArchilEgress = (egress: archil.SandboxEgressPolicy | undefined) => ({
+  managed: (egress?.allow ?? []).filter(isArchilEgress),
+  policy: egress && { ...egress, allow: egress.allow?.filter((entry) => !isArchilEgress(entry)) },
+});
+
+/** Environment values, unwrapped for the wire. */
+export const toEnv = (env: Record<string, string | Redacted.Redacted<string>> | undefined) =>
+  env === undefined
+    ? undefined
+    : Object.fromEntries(Object.entries(env).map(([k, v]) => [k, secretValue(v)]));
+
+/** A comparable form of an egress policy (header values are hashed out). */
+export const egressIdentity = (egress: SandboxEgress | undefined) =>
+  egress === undefined
+    ? undefined
+    : {
+        ...egress,
+        allow: egress.allow?.map((entry) =>
+          typeof entry === "string"
+            ? entry
+            : {
+                ...entry,
+                headers: entry.headers
+                  ? Object.fromEntries(
+                      Object.entries(entry.headers).map(([k, v]) => [k, secretValue(v)]),
+                    )
+                  : undefined,
+              },
+        ),
+      };

package/src/SandboxPortToken.ts

@@ -0,0 +1,125 @@
+import * as archil from "@distilled.cloud/archil";
+import { isResolved } from "alchemy/Diff";
+import * as Provider from "alchemy/Provider";
+import { Resource } from "alchemy/Resource";
+import * as Effect from "effect/Effect";
+import * as Redacted from "effect/Redacted";
+import type { Providers } from "./Providers.ts";
+
+export interface SandboxPortTokenProps {
+  /** Sandbox id (e.g. `sandbox.sandboxId`). Changing it replaces the token. */
+  sandbox: string;
+  /** The exposed port the token opens. Changing it replaces the token. */
+  port: number;
+  /**
+   * How long the token lasts, e.g. `"24h"` or `"30m"`. Omit for a token
+   * that lasts until revoked. Changing it replaces the token.
+   */
+  ttl?: string;
+}
+
+export interface SandboxPortTokenAttributes {
+  /** Token id. */
+  tokenId: string;
+  sandboxId: string;
+  port: number;
+  /** Hostname the token opens. */
+  hostname: string;
+  /** The token. Send it with requests to `hostname`. */
+  token: Redacted.Redacted<string>;
+  /** When the token expires, if it does. */
+  expiresAt: string | undefined;
+}
+
+export type SandboxPortToken = Resource<
+  "Archil.SandboxPortToken",
+  SandboxPortTokenProps,
+  SandboxPortTokenAttributes,
+  never,
+  Providers
+>;
+
+/**
+ * A token that opens one exposed port of one sandbox, for a client that
+ * shouldn't hold your API key. Archil only shows the token once, so Alchemy
+ * stores it in state as a `Redacted` value; destroying the resource revokes
+ * it.
+ * @see https://docs.archil.com/compute/sandboxes/introduction
+ *
+ * ### Creating a Port Token
+ * **Example:** A day-long token for a preview
+ * ```typescript
+ * const token = yield* Archil.SandboxPortToken("PreviewToken", {
+ *   sandbox: preview.sandboxId,
+ *   port: 3000,
+ *   ttl: "24h",
+ * });
+ * ```
+ *
+ * @resource
+ * @product Sandbox
+ */
+export const SandboxPortToken = Resource<SandboxPortToken>("Archil.SandboxPortToken");
+
+/** Mint a port token. */
+export const createPortToken = Effect.fn(function* (sid: string, port: number, ttl?: string) {
+  const { data } = yield* archil.createSandboxPortToken({ sid, port, ttl });
+  return {
+    tokenId: data.id,
+    sandboxId: sid,
+    port: data.port,
+    hostname: data.hostname,
+    token: typeof data.token === "string" ? Redacted.make(data.token) : data.token,
+    expiresAt: data.expires_at,
+  } satisfies SandboxPortTokenAttributes;
+});
+
+/** Revoke a port token. Revoking a missing token succeeds. */
+export const revokePortToken = (sid: string, tokenId: string) =>
+  archil.deleteSandboxPortToken({ sid, token_id: tokenId }).pipe(
+    Effect.asVoid,
+    Effect.catchTag("NotFound", () => Effect.void),
+  );
+
+export const SandboxPortTokenProvider = () =>
+  Provider.effect(
+    SandboxPortToken,
+    Effect.gen(function* () {
+      return {
+        stables: ["tokenId", "sandboxId", "port", "hostname", "token", "expiresAt"],
+        diff: Effect.fn(function* ({ olds, news }) {
+          if (!isResolved(news) || olds === undefined) return undefined;
+          if (news.sandbox !== olds.sandbox || news.port !== olds.port || news.ttl !== olds.ttl) {
+            return { action: "replace" } as const;
+          }
+          return undefined;
+        }),
+        read: Effect.fn(function* ({ output }) {
+          if (!output) return undefined;
+          return yield* archil
+            .getSandboxPortToken({ sid: output.sandboxId, token_id: output.tokenId })
+            .pipe(
+              Effect.map(() => output),
+              Effect.catchTag("NotFound", () => Effect.undefined),
+            );
+        }),
+        reconcile: Effect.fn(function* ({ news, output }) {
+          // Observe — a live token we minted is kept; tokens can't be updated.
+          if (output) {
+            const live = yield* archil
+              .getSandboxPortToken({ sid: output.sandboxId, token_id: output.tokenId })
+              .pipe(
+                Effect.as(true),
+                Effect.catchTag("NotFound", () => Effect.succeed(false)),
+              );
+            if (live) return output;
+          }
+          // Ensure
+          return yield* createPortToken(news.sandbox, news.port, news.ttl);
+        }),
+        delete: Effect.fn(function* ({ output }) {
+          yield* revokePortToken(output.sandboxId, output.tokenId);
+        }),
+      };
+    }),
+  );

package/src/WriteDisk.ts

@@ -0,0 +1,42 @@
+import * as Binding from "alchemy/Binding";
+import type * as Effect from "effect/Effect";
+import type { WriteDiskClient } from "./Clients.ts";
+import type { Disk } from "./Disk.ts";
+import type { DiskObjectsOptions } from "./ReadDisk.ts";
+
+export type { WriteDiskClient } from "./Clients.ts";
+
+/**
+ * Write a disk's files as objects over Archil's S3-compatible API: put,
+ * append, copy, delete, and multipart uploads of any size. The host gets
+ * its own read-write S3 user on this disk, so it can't reach any other
+ * disk and never holds an API key. A write that conflicts with a mounted
+ * client's write delegation fails with `ObjectConflict`; `ExecDisk`'s
+ * `delegations` and `revokeDelegation` reclaim paths a crashed client
+ * still holds.
+ *
+ * ### Writing Files
+ * **Example:** Append events to a log on a disk
+ * ```typescript
+ * const files = yield* Archil.WriteDisk(Dataset);
+ * yield* files.append("events.ndjson", JSON.stringify(event) + "\n");
+ * ```
+ *
+ * ### Uploading Large Files
+ * **Example:** Stream a file of any size onto the disk
+ * ```typescript
+ * const files = yield* Archil.WriteDisk(Dataset);
+ * const request = yield* HttpServerRequest;
+ * yield* files.upload("uploads/video.mp4", request.stream, { contentType: "video/mp4" });
+ * ```
+ *
+ * @binding
+ * @product Disk
+ */
+export interface WriteDisk extends Binding.Service<
+  WriteDisk,
+  "Archil.WriteDisk",
+  (disk: Disk, options?: DiskObjectsOptions) => Effect.Effect<WriteDiskClient>
+> {}
+
+export const WriteDisk = Binding.Service<WriteDisk>("Archil.WriteDisk");

package/src/globals.d.ts

@@ -0,0 +1,2 @@
+// `globalThis.__ALCHEMY_RUNTIME__`, declared by alchemy's Phase module.
+import type {} from "alchemy/Phase";

package/src/index.ts

@@ -0,0 +1,59 @@
+export * from "./ApiToken.ts";
+export * from "./AuthProvider.ts";
+export * from "./Branch.ts";
+export * from "./BranchDisk.ts";
+export * from "./Checkpoint.ts";
+export {
+  SandboxPortNotExposed,
+  type Command,
+  type DiskDelegationsClient,
+  type DiskHandle,
+  type ExecOptions,
+  type ObjectsTransportError,
+  type ProcessCallError,
+  type PtyConnection,
+  type PtyOptions,
+  type ReadWriteDiskClient,
+  type SandboxFiles,
+  type SandboxHandle,
+  type SandboxOps,
+  type SandboxPort,
+  type SandboxPortError,
+  type SandboxProcess,
+  type SandboxProcessExit,
+  type SandboxProcessOutput,
+  type ShareError,
+  type StartOptions,
+} from "./Clients.ts";
+export * from "./ConnectSandbox.ts";
+export * from "./CreateDisk.ts";
+export * from "./CreateImage.ts";
+export * from "./CreateSandbox.ts";
+export {
+  Account,
+  account,
+  Credentials,
+  CredentialsFromEnv,
+  DEFAULT_REGION,
+  fromApiKey,
+  fromAuthProvider,
+  REGIONS,
+  type ArchilAccount,
+} from "./Credentials.ts";
+export * from "./Disk.ts";
+export * from "./DiskObjectsHttp.ts";
+export * from "./DiskUser.ts";
+export * from "./ExecDisk.ts";
+export * from "./ExecDiskHttp.ts";
+export * from "./ExecDisks.ts";
+export * from "./Image.ts";
+export { ArchilFailed, ArchilNotReady } from "./internal/archil.ts";
+export * from "./MountDisk.ts";
+export * from "./Providers.ts";
+export * from "./ReadDisk.ts";
+export * from "./ReadWriteDisk.ts";
+export * from "./Sandbox.ts";
+export * from "./SandboxOptions.ts";
+export * from "./SandboxPortToken.ts";
+export type { InferEnv } from "./InferEnv.ts";
+export * from "./WriteDisk.ts";

package/src/internal/DeployerKey.ts

@@ -0,0 +1,63 @@
+import { Credentials, DEFAULT_REGION } from "@distilled.cloud/archil/Credentials";
+import * as Provider from "alchemy/Provider";
+import { Resource } from "alchemy/Resource";
+import * as Effect from "effect/Effect";
+import * as Redacted from "effect/Redacted";
+import type { Providers } from "../Providers.ts";
+
+export interface DeployerKeyAttributes {
+  /** The API key the stack deploys with. */
+  apiKey: Redacted.Redacted<string>;
+  /** Archil region the key acts in. */
+  region: string;
+}
+
+/**
+ * The deploying account's API key, recorded so bindings can hand it to
+ * their host. Archil only mints API keys from a console session (an API
+ * key gets a 401), and its keys can't be scoped, so a host gets the same
+ * key the stack deploys with. Rotating the deploy key updates every host.
+ */
+export type DeployerKey = Resource<
+  "Archil.DeployerKey",
+  {},
+  DeployerKeyAttributes,
+  never,
+  Providers
+>;
+
+export const DeployerKey = Resource<DeployerKey>("Archil.DeployerKey");
+
+const current = Effect.gen(function* () {
+  const { apiKey, region } = yield* yield* Credentials;
+  return { apiKey, region: region ?? DEFAULT_REGION } satisfies DeployerKeyAttributes;
+});
+
+export const DeployerKeyProvider = () =>
+  Provider.effect(
+    DeployerKey,
+    Effect.gen(function* () {
+      return {
+        // Nothing lives in Archil: the key belongs to the deployer.
+        nuke: { skip: true },
+        diff: Effect.fn(function* ({ output }) {
+          if (output === undefined) return undefined;
+          const next = yield* current;
+          if (
+            Redacted.value(next.apiKey) !== Redacted.value(output.apiKey) ||
+            next.region !== output.region
+          ) {
+            return { action: "update" } as const;
+          }
+          return undefined;
+        }),
+        read: Effect.fn(function* ({ output }) {
+          return output;
+        }),
+        reconcile: Effect.fn(function* () {
+          return yield* current;
+        }),
+        delete: () => Effect.void,
+      };
+    }),
+  );