alepha 0.22.0 → 0.24.0

package/src/container/core/index.ts

@@ -1,50 +0,0 @@
-import { $module } from "alepha";
-import { $container } from "./primitives/$container.ts";
-import { ContainerProvider } from "./providers/ContainerProvider.ts";
-import { MockContainerProvider } from "./providers/MockContainerProvider.ts";
-import { NodeContainerProvider } from "./providers/NodeContainerProvider.ts";
-
-// ---------------------------------------------------------------------------------------------------------------------
-
-export * from "./interfaces/ContainerOptions.ts";
-export * from "./primitives/$container.ts";
-export * from "./providers/ContainerProvider.ts";
-export * from "./providers/MockContainerProvider.ts";
-export * from "./providers/NodeContainerProvider.ts";
-
-// ---------------------------------------------------------------------------------------------------------------------
-
-/**
- * Type-safe RPC clients for ephemeral containerized Alepha apps.
- *
- * **Features:**
- * - `$container<T>()` directive returns a typed Proxy onto a remote
- *   Alepha controller's `$action` endpoints — the wire format is the
- *   same `POST /api/<method>` shape served by every Alepha server.
- * - Pluggable transport: Node (plain `fetch` against a configured URL),
- *   Mock (in-process call via `LinkProvider.follow` for tests),
- *   Cloudflare workerd (`getContainer().fetch()` through the Containers
- *   binding — see `alepha/container` workerd entry).
- * - Build-time integration: `BuildCloudflareTask.enhanceContainers`
- *   emits the matching wrangler bindings and Durable Object class
- *   declarations.
- *
- * The Node binding is the "temporary, not perfect" path documented in
- * the spec — apps need to provide an explicit `url` per primitive
- * until a `target=docker` adapter ships.
- *
- * @module alepha.container
- */
-export const AlephaContainer = $module({
-  name: "alepha.container",
-  primitives: [$container],
-  services: [ContainerProvider],
-  variants: [MockContainerProvider, NodeContainerProvider],
-  register: (alepha) => {
-    alepha.with({
-      optional: true,
-      provide: ContainerProvider,
-      use: alepha.isTest() ? MockContainerProvider : NodeContainerProvider,
-    });
-  },
-});

package/src/container/core/index.workerd.ts

@@ -1,53 +0,0 @@
-import { Container } from "@cloudflare/containers";
-import { $module } from "alepha";
-import { $container } from "./primitives/$container.ts";
-import { CloudflareContainerProvider } from "./providers/CloudflareContainerProvider.ts";
-import { ContainerProvider } from "./providers/ContainerProvider.ts";
-
-// Stash the Cloudflare Containers `Container` base class on globalThis
-// so `BuildCloudflareTask`'s post-Vite-emitted entry
-// (`dist/main.cloudflare.js`) can declare
-// `class <T> extends globalThis.__alepha_CloudflareContainer` without
-// introducing a bare `@cloudflare/containers` specifier.
-//
-// The entry is written AFTER Vite — anything Vite hasn't seen
-// survives as an unresolved import all the way to workerd (where the
-// upload is `no_bundle: true`). This side-effect runs whenever an app
-// imports anything from `alepha/container` (Vite picks this file via
-// the `workerd` export condition), so by the time the entry's
-// `import "./index.js"` finishes, the global is set and the
-// `extends` expression resolves.
-(globalThis as any).__alepha_CloudflareContainer = Container;
-
-// ---------------------------------------------------------------------------------------------------------------------
-
-export * from "./interfaces/ContainerOptions.ts";
-export * from "./primitives/$container.ts";
-export * from "./providers/CloudflareContainerProvider.ts";
-export * from "./providers/ContainerProvider.ts";
-
-// ---------------------------------------------------------------------------------------------------------------------
-
-/**
- * Type-safe RPC clients for ephemeral containerized Alepha apps,
- * Cloudflare workerd build.
- *
- * Auto-binds `CloudflareContainerProvider` so `$container()` calls
- * route through `env.<NAME>.getContainer(...).fetch()`. Pair with
- * `BuildCloudflareTask.enhanceContainers` (in `alepha/cli/core`) which
- * emits the wrangler.jsonc bindings and DO class declarations.
- *
- * @module alepha.container
- */
-export const AlephaContainer = $module({
-  name: "alepha.container",
-  primitives: [$container],
-  services: [ContainerProvider, CloudflareContainerProvider],
-  register: (alepha) => {
-    alepha.with({
-      optional: true,
-      provide: ContainerProvider,
-      use: CloudflareContainerProvider,
-    });
-  },
-});

package/src/container/core/interfaces/ContainerOptions.ts

@@ -1,69 +0,0 @@
-import type { DurationLike } from "alepha/datetime";
-
-/**
- * Options for the `$container` primitive.
- *
- * Describes a remote Alepha app running in an ephemeral container. The
- * primitive returns a typed Proxy that calls the container's `$action`
- * endpoints through whatever transport the active provider chooses
- * (Cloudflare Containers binding on `target=cloudflare`, plain HTTP on
- * Node when `url` is set).
- */
-export interface ContainerPrimitiveOptions {
-  /**
-   * Logical container name. Defaults to the property key.
-   *
-   * Cloudflare provider uppercases this to look up the binding
-   * (`env.<NAME>`), so prefer lowercase here.
-   */
-  name?: string;
-
-  /**
-   * Docker image the container runs. Required.
-   *
-   * The build task uses this verbatim in `wrangler.jsonc`'s
-   * `containers[].image` entry.
-   */
-  image: string;
-
-  /**
-   * Explicit URL the Node provider should call. When set, `$container`
-   * routes through `LinkProvider` exactly like `$remote({ url })`.
-   *
-   * On `target=cloudflare`, this is ignored — the Containers binding is
-   * used instead.
-   */
-  url?: string | (() => string);
-
-  /**
-   * Port the container app listens on. Defaults to 3000 (Alepha
-   * convention — NOT Cloudflare's 8080). Used in build-time codegen.
-   */
-  port?: number;
-
-  /**
-   * Idle window before the platform stops the container instance.
-   *
-   * @default "15m"
-   */
-  sleepAfter?: DurationLike;
-
-  /**
-   * Environment variables injected into the container at runtime.
-   */
-  envVars?: Record<string, string>;
-
-  /**
-   * Cloudflare-specific instance class. Ignored on other targets.
-   *
-   * @default "dev"
-   */
-  instanceType?: "dev" | "basic" | "standard";
-
-  /**
-   * Maximum concurrent container instances.
-   *
-   * @default 5
-   */
-  maxInstances?: number;
-}

package/src/container/core/primitives/$container.ts

@@ -1,100 +0,0 @@
-import { $inject, AlephaError, createPrimitive, KIND, Primitive } from "alepha";
-import type { ContainerPrimitiveOptions } from "../interfaces/ContainerOptions.ts";
-import { ContainerProvider } from "../providers/ContainerProvider.ts";
-
-/**
- * `$container` — typed RPC client to a containerized Alepha app.
- *
- * Returns a typed Proxy whose method calls map 1:1 to the target
- * controller's `$action` endpoints. The wire format mirrors what a
- * normal Alepha server exposes (`POST /api/<method>` with a JSON body),
- * so the container is literally a tiny Alepha worker.
- *
- * Transport is owned by the active {@link ContainerProvider}:
- * - `target=cloudflare` → `CloudflareContainerProvider` routes through
- *   the Containers binding (`env.<NAME>.getContainer(...).fetch()`).
- * - Node (with `url` set) → `NodeContainerProvider` uses plain
- *   `fetch()` against the configured URL.
- *
- * Build-time, `BuildCloudflareTask.enhanceContainers` walks
- * `alepha.primitives($container)` to emit the matching `wrangler.jsonc`
- * entries and Durable Object class declarations into
- * `main.cloudflare.js`.
- *
- * @example
- * ```ts
- * import { $container } from "alepha/container";
- * import type { RocketController } from "@alepha/rocket";
- *
- * class DeployService {
- *   rocket = $container<RocketController>({
- *     image: "alepha/rocket:latest",
- *     port: 3000,
- *     sleepAfter: "15m",
- *   });
- *
- *   async deploy() {
- *     return this.rocket.createJob({ body: { op: "up" } });
- *   }
- * }
- * ```
- */
-export const $container = <T extends object = any>(
-  options: ContainerPrimitiveOptions,
-): ContainerProxy<T> => {
-  if (!options.image) {
-    throw new AlephaError("$container requires an 'image' option");
-  }
-  const instance = createPrimitive(ContainerPrimitive, options);
-  return instance.proxy() as ContainerProxy<T>;
-};
-
-/**
- * Typed proxy returned by `$container<T>()`. Each `$action` member of
- * `T` becomes a callable returning the action's response body.
- *
- * The runtime shape is a `Proxy(primitive)` — own-property reads hit the
- * underlying `ContainerPrimitive` (so `alepha.primitives($container)`
- * still finds it via the `instanceof Primitive` check inside
- * `Alepha.new()`), and anything else is treated as an action name and
- * routed through the active `ContainerProvider`.
- */
-export type ContainerProxy<T extends object> = {
-  [K in keyof T]: T[K] extends (...args: infer A) => infer R
-    ? (...args: A) => Promise<Awaited<R>>
-    : (config?: {
-        body?: unknown;
-        query?: unknown;
-        params?: unknown;
-      }) => Promise<any>;
-};
-
-export class ContainerPrimitive extends Primitive<ContainerPrimitiveOptions> {
-  protected readonly provider = $inject(ContainerProvider);
-
-  public get name(): string {
-    return this.options.name ?? this.config.propertyKey;
-  }
-
-  /**
-   * Build the typed Proxy. The target is the primitive itself so
-   * `instanceof Primitive` keeps working (required by Alepha's
-   * primitive registration in `Alepha.new`). Property reads that match
-   * an own/inherited member return that member; anything else is
-   * treated as an action name and routed through the provider.
-   */
-  public proxy<T extends object = any>(): ContainerProxy<T> {
-    const primitive = this;
-    return new Proxy(primitive as any, {
-      get(target: any, prop: string | symbol, receiver: any) {
-        if (typeof prop === "symbol" || prop in target) {
-          return Reflect.get(target, prop, receiver);
-        }
-        return (config: any = {}) =>
-          primitive.provider.invoke(primitive, prop as string, config);
-      },
-    }) as ContainerProxy<T>;
-  }
-}
-
-$container[KIND] = ContainerPrimitive;

package/src/container/core/providers/CloudflareContainerProvider.ts

@@ -1,70 +0,0 @@
-import { getContainer } from "@cloudflare/containers";
-import { $inject, Alepha, AlephaError } from "alepha";
-import type { ContainerPrimitive } from "../primitives/$container.ts";
-import {
-  type ContainerInvokeConfig,
-  ContainerProvider,
-} from "./ContainerProvider.ts";
-
-/**
- * Cloudflare Workers (workerd) container provider.
- *
- * Routes proxy calls through the Cloudflare Containers binding bound
- * on `env.<NAME>`, using a single shared instance per container.
- * `getContainer` from `@cloudflare/containers` is a free function (not
- * a method on the binding) — it takes the DO namespace and an id and
- * returns a stub with a `.fetch()` method targeting the running
- * container instance.
- *
- * The binding is generated by `BuildCloudflareTask.enhanceContainers`
- * from the `$container` primitives discovered in the app. The runtime
- * `env` object is pulled from the Alepha store key `cloudflare.env`
- * — the worker entry point publishes it there on every fetch
- * (`__alepha.set("cloudflare.env", env)`).
- */
-export class CloudflareContainerProvider extends ContainerProvider {
-  protected readonly alepha = $inject(Alepha);
-
-  public override async invoke(
-    container: ContainerPrimitive,
-    action: string,
-    config: ContainerInvokeConfig,
-  ): Promise<unknown> {
-    const env = this.alepha.store.get("cloudflare.env") as
-      | Record<string, unknown>
-      | undefined;
-    if (!env) {
-      throw new AlephaError(
-        `CloudflareContainerProvider could not resolve 'cloudflare.env' from the store — is the app running on workerd?`,
-      );
-    }
-
-    const bindingName = container.name.toUpperCase();
-    const binding = env[bindingName];
-    if (!binding) {
-      throw new AlephaError(
-        `Cloudflare Containers binding '${bindingName}' not found on env — check wrangler.jsonc.`,
-      );
-    }
-
-    const instance = getContainer(binding as never, "shared");
-    const { path, init } = this.buildRequest(action, config);
-    const request = new Request(`http://container${path}`, init);
-    const response = await instance.fetch(request);
-
-    if (!response.ok) {
-      const text = await response.text().catch(() => "");
-      throw new AlephaError(
-        `Container '${container.name}' action '${action}' failed: ${response.status} ${response.statusText}${
-          text ? ` — ${text}` : ""
-        }`,
-      );
-    }
-
-    const contentType = response.headers.get("content-type") ?? "";
-    if (contentType.includes("application/json")) {
-      return await response.json();
-    }
-    return await response.text();
-  }
-}

package/src/container/core/providers/ContainerProvider.ts

@@ -1,92 +0,0 @@
-import { AlephaError } from "alepha";
-import { $logger } from "alepha/logger";
-import type { ContainerPrimitive } from "../primitives/$container.ts";
-
-export interface ContainerInvokeConfig {
-  body?: unknown;
-  query?: Record<string, unknown>;
-  params?: Record<string, unknown>;
-  headers?: Record<string, string>;
-}
-
-/**
- * Abstract transport for `$container` proxies.
- *
- * Concrete subclasses translate a `(container, action, config)` call
- * into an HTTP request that reaches the running container. The default
- * binding on Node throws — apps must register either a
- * `NodeContainerProvider` (with `url` on each primitive) or the
- * Cloudflare workerd variant.
- */
-export abstract class ContainerProvider {
-  protected readonly log = $logger();
-
-  /**
-   * Invoke a remote action on the container. Subclasses do the work;
-   * the default implementation rejects to make missing wiring obvious.
-   */
-  public async invoke(
-    container: ContainerPrimitive,
-    action: string,
-    config: ContainerInvokeConfig,
-  ): Promise<unknown> {
-    void config;
-    throw new AlephaError(
-      `No ContainerProvider configured for container '${container.name}' (action '${action}'). ` +
-        `Set up alepha/container via AlephaContainer and either supply 'url' (Node) or build for target=cloudflare.`,
-    );
-  }
-
-  /**
-   * Helper: build the fetch path/body for an action call. Kept as a
-   * protected method so workerd and Node providers share the wire
-   * shape — `POST /api/<action>` with the JSON body, query params on
-   * the URL, and the request headers merged in.
-   */
-  protected buildRequest(
-    action: string,
-    config: ContainerInvokeConfig,
-  ): { path: string; init: RequestInit } {
-    const params = new URLSearchParams();
-    if (config.query) {
-      for (const [k, v] of Object.entries(config.query)) {
-        if (v !== undefined && v !== null) params.set(k, String(v));
-      }
-    }
-
-    // Match the route Alepha generates server-side when no explicit
-    // `path:` is set on `$action`: `/${name}` with one `/:<key>`
-    // segment appended per param. Params that match a `:key`
-    // placeholder are substituted in place; any remaining params are
-    // appended in declaration order so `params: {id:"abc"}` against a
-    // proxy action `getDeploy` yields `/api/getDeploy/abc`.
-    let path = `/api/${action}`;
-    if (config.params) {
-      const tail: string[] = [];
-      for (const [k, v] of Object.entries(config.params)) {
-        const placeholder = `:${k}`;
-        const encoded = encodeURIComponent(String(v));
-        if (path.includes(placeholder)) {
-          path = path.replace(placeholder, encoded);
-        } else {
-          tail.push(encoded);
-        }
-      }
-      if (tail.length) path += `/${tail.join("/")}`;
-    }
-
-    const search = params.toString();
-    if (search) path += `?${search}`;
-
-    const init: RequestInit = {
-      method: "POST",
-      headers: {
-        "content-type": "application/json",
-        ...(config.headers ?? {}),
-      },
-      body: config.body !== undefined ? JSON.stringify(config.body) : undefined,
-    };
-
-    return { path, init };
-  }
-}

package/src/container/core/providers/MockContainerProvider.ts

@@ -1,62 +0,0 @@
-import { $inject, Alepha, AlephaError } from "alepha";
-import type { ContainerPrimitive } from "../primitives/$container.ts";
-import {
-  type ContainerInvokeConfig,
-  ContainerProvider,
-} from "./ContainerProvider.ts";
-
-/**
- * In-process test provider.
- *
- * Resolves the action name against `LinkProvider`'s registered links in
- * the SAME Alepha instance — effectively calling the "containerized"
- * controller as if it were local. Use it in tests: register the
- * controller class on the test container alongside the consumer and
- * substitute `ContainerProvider` with `MockContainerProvider`.
- *
- * @example
- * ```ts
- * const alepha = Alepha.create()
- *   .with(AlephaContainer)
- *   .with(RocketController)
- *   .with(MyApp)
- *   .with({ provide: ContainerProvider, use: MockContainerProvider });
- * ```
- */
-export class MockContainerProvider extends ContainerProvider {
-  protected readonly alepha = $inject(Alepha);
-
-  public override async invoke(
-    container: ContainerPrimitive,
-    action: string,
-    config: ContainerInvokeConfig,
-  ): Promise<unknown> {
-    void container;
-    // Lazy-resolve LinkProvider so tests that don't load `alepha/server/links`
-    // still get a clear error message.
-    const linkProviderClass = await this.loadLinkProvider();
-    const linkProvider = this.alepha.inject(linkProviderClass) as {
-      follow: (
-        name: string,
-        config?: Record<string, unknown>,
-      ) => Promise<unknown>;
-    };
-    return await linkProvider.follow(action, {
-      body: config.body,
-      query: config.query,
-      params: config.params,
-      headers: config.headers,
-    });
-  }
-
-  protected async loadLinkProvider(): Promise<any> {
-    try {
-      const mod = await import("alepha/server/links");
-      return mod.LinkProvider;
-    } catch {
-      throw new AlephaError(
-        "MockContainerProvider needs 'alepha/server/links' to be available — add AlephaServerLinks to the test app.",
-      );
-    }
-  }
-}

package/src/container/core/providers/NodeContainerProvider.ts

@@ -1,53 +0,0 @@
-import { AlephaError } from "alepha";
-import type { ContainerPrimitive } from "../primitives/$container.ts";
-import {
-  type ContainerInvokeConfig,
-  ContainerProvider,
-} from "./ContainerProvider.ts";
-
-/**
- * Node (dev / test / non-Cloudflare) container provider.
- *
- * Routes proxy calls through plain `fetch()` against the URL given on
- * the `$container` primitive. If no `url` is supplied, calls throw —
- * v1 deliberately has no Docker spawning. This is the "temporary, not
- * perfect" Node path documented in the spec; the longer-term plan is
- * to plug in a `target=docker` adapter once that lands.
- */
-export class NodeContainerProvider extends ContainerProvider {
-  public override async invoke(
-    container: ContainerPrimitive,
-    action: string,
-    config: ContainerInvokeConfig,
-  ): Promise<unknown> {
-    const url = this.resolveUrl(container);
-    if (!url) {
-      throw new AlephaError(
-        `Container '${container.name}' has no 'url' configured — NodeContainerProvider cannot reach the container.`,
-      );
-    }
-
-    const { path, init } = this.buildRequest(action, config);
-    const response = await fetch(`${url.replace(/\/$/, "")}${path}`, init);
-
-    if (!response.ok) {
-      const text = await response.text().catch(() => "");
-      throw new AlephaError(
-        `Container '${container.name}' action '${action}' failed: ${response.status} ${response.statusText}${
-          text ? ` — ${text}` : ""
-        }`,
-      );
-    }
-
-    const contentType = response.headers.get("content-type") ?? "";
-    if (contentType.includes("application/json")) {
-      return await response.json();
-    }
-    return await response.text();
-  }
-
-  protected resolveUrl(container: ContainerPrimitive): string | undefined {
-    const url = container.options.url;
-    return typeof url === "function" ? url() : url;
-  }
-}