@zerotal/core 1.0.0

package/src/pipeline/Pipeline.ts

@@ -0,0 +1,150 @@
+/**
+ * A generic middleware pipeline: sends a payload through an ordered list of
+ * pipes and hands the final payload to a destination. Pipes are resolved from
+ * the container when one is supplied, otherwise instantiated directly.
+ */
+import type { Container } from "../container/Container.ts";
+import { injectRegistry } from "../container/inject.ts";
+import type { Pipe, NextFn } from "./types.ts";
+
+type PipeClass<T> = new (...args: unknown[]) => Pipe<T>;
+
+/**
+ * Generic middleware pipeline: sends a payload through an ordered list of pipe
+ * classes and hands the final payload to a destination.
+ *
+ * Pipes are resolved from the container when `.via()` is called; otherwise each
+ * is instantiated directly with `new PipeClass()`.
+ *
+ * @typeParam T - The payload type carried through the pipes (typically {@link HttpContext}).
+ *
+ * @example
+ * const result = await Pipeline.send(ctx)
+ *   .through([AuthMiddleware, ThrottleMiddleware])
+ *   .via(container)           // optional — resolves pipes from container
+ *   .then((ctx) => ctx.response);
+ *
+ * @example
+ * // Run the chain and read the mutated payload back:
+ * const finished = await Pipeline.send(ctx).through(pipes).via(container).thenReturn();
+ * return finished.response;
+ */
+export class Pipeline<T> {
+  private _payload!: T;
+  private _pipes: PipeClass<T>[] = [];
+  private _container: Container | undefined = undefined;
+
+  private constructor() {}
+
+  // ── Fluent builder ────────────────────────────────────────────────────
+
+  /** Begin a pipeline carrying `payload` through the pipes added by `through()`. */
+  static send<T>(payload: T): Pipeline<T> {
+    const pipeline = new Pipeline<T>();
+    pipeline._payload = payload;
+    return pipeline;
+  }
+
+  /** Set the ordered list of pipe classes the payload travels through. */
+  through(pipes: PipeClass<T>[]): this {
+    this._pipes = pipes;
+    return this;
+  }
+
+  /** Inject a container so pipes are resolved from it (supports `@inject`). */
+  via(container: Container): this {
+    this._container = container;
+    return this;
+  }
+
+  // ── Execution ─────────────────────────────────────────────────────────
+
+  /**
+   * Execute the pipeline and pass the final payload to `destination`.
+   * Returns whatever `destination` returns.
+   */
+  async then<R>(destination: (payload: T) => Promise<R> | R): Promise<R> {
+    await this._run();
+    return destination(this._payload);
+  }
+
+  /**
+   * Execute the pipeline and return the final payload unchanged.
+   *
+   * The pipeline mutates the payload in-place: every pipe shares the one
+   * `payload` (the request `HttpContext`), and the canonical `Response` is
+   * written to `payload.response`. Read it back from there.
+   */
+  async thenReturn(): Promise<T> {
+    await this._run();
+    return this._payload;
+  }
+
+  // ── Internal recursive runner ─────────────────────────────────────────
+
+  /**
+   * Run the pipes as a recursive onion. Each pipe either calls `next()` to
+   * descend, short-circuits, or wraps the downstream response. A pipe that
+   * returns a `Response` has it mirrored onto `payload.response`; a `void`
+   * return leaves that canonical slot untouched. `next()` resolves to whatever
+   * `Response` (or `undefined`) the deeper pipes left there.
+   */
+  private async _run(): Promise<Response | undefined> {
+    const pipes = this._pipes;
+    // The canonical response store. All real pipelines carry the request
+    // HttpContext; duck-typed so Pipeline stays payload-agnostic.
+    const http = this._payload as { response?: Response } | undefined;
+
+    const execute = async (index: number): Promise<Response | undefined> => {
+      if (index === pipes.length) {
+        // End of chain — surface whatever response was set on the way down.
+        return http?.response;
+      }
+
+      const PipeClass = pipes[index]!;
+
+      // Resolve from the container when it can actually satisfy this class (supports @inject
+      // singleton middleware); otherwise instantiate directly. The previous
+      // implementation used `try { makeSync() } catch { new PipeClass() }`, but middleware is
+      // never registered in the container, so `makeSync` threw BindingNotFoundError for *every*
+      // pipe on *every* request. `Error` captures a stack trace, which made exception
+      // construction — not the middleware itself — a measurable share of per-request CPU
+      // (~3.2 us per pipe). `_isContainerResolvable` is a couple of Map lookups.
+      let pipeInstance: Pipe<T>;
+      if (this._container && _isContainerResolvable(this._container, PipeClass)) {
+        pipeInstance = this._container.makeSync(PipeClass as never) as Pipe<T>;
+      } else {
+        pipeInstance = new PipeClass();
+      }
+
+      const next: NextFn = () => execute(index + 1);
+
+      const result = await pipeInstance.handle(this._payload, next);
+      // Returning a Response is sugar for "set ctx.response"; a void return
+      // leaves the canonical slot as the pipe (or a deeper one) left it.
+      if (result instanceof Response && http) http.response = result;
+      return http?.response;
+    };
+
+    return execute(0);
+  }
+}
+
+/**
+ * True when `container.makeSync(PipeClass)` would succeed — i.e. the class is registered, is
+ * deferred behind a provider, or is auto-wirable via `@inject()`.
+ *
+ * This mirrors the resolution branches in {@link Container.makeSync} so the pipeline can pick
+ * the right path without provoking (and swallowing) a `BindingNotFoundError` per pipe per
+ * request. Kept deliberately conservative: anything it is unsure about falls through to
+ * `new PipeClass()`, which is what the old catch-all did anyway.
+ */
+function _isContainerResolvable<T>(
+  container: Container,
+  PipeClass: new (...args: unknown[]) => Pipe<T>,
+): boolean {
+  if (container.bound(PipeClass)) return true;
+  // Auto-wiring: @inject() records the class in injectRegistry, making it
+  // resolvable without an explicit binding.
+  return injectRegistry.has(PipeClass);
+}

package/src/pipeline/currentPage.ts

@@ -0,0 +1,46 @@
+import { HttpContext } from "./HttpContext.ts";
+
+/**
+ * Resolves the page a paginator should return when the caller doesn't name one.
+ *
+ * @param pageName - The paginator's name, so one request can drive several independently.
+ * @returns The 1-based page, or `undefined` to fall back to the query string.
+ */
+export type CurrentPageResolver = (pageName: string) => number | undefined;
+
+/**
+ * Override where `paginate()` reads the current page for the rest of this request.
+ *
+ * The default reads the query string, which is what a plain HTTP request wants. A
+ * server-driven view whose page number lives in component state rather than the URL
+ * registers its own instead — Flow's `Pagination` mixin does exactly this, so
+ * `Post.paginate(10)` inside a component follows the component's page.
+ *
+ * Scoped to the request: the resolver goes on the active {@link HttpContext}, reached through
+ * request-scoped storage, so it lasts exactly as long as the request does and never reaches
+ * another one. Keep it that way — a module-level slot would not be request-scoped.
+ *
+ * @param resolver - Called with the paginator name; return `undefined` to defer to the query string.
+ */
+export function setCurrentPageResolver(resolver: CurrentPageResolver): void {
+  const ctx = HttpContext.tryGet();
+  if (ctx) ctx._pageResolver = resolver;
+}
+
+/**
+ * The page a paginator should return, for the request in flight.
+ *
+ * Order: a resolver registered for this request, then the query string, then `1`. Outside a
+ * request — a queue worker, a CLI command, a test — there is nothing to read, so it is `1`.
+ *
+ * @param pageName - The paginator's name. Defaults to `"page"`.
+ * @returns A 1-based page number, never below 1.
+ */
+export function currentPage(pageName = "page"): number {
+  const ctx = HttpContext.tryGet();
+  if (!ctx) return 1;
+
+  const resolved = ctx._pageResolver?.(pageName);
+  const page = resolved ?? ctx.integer(pageName, 1);
+  return Math.max(1, Math.trunc(page ?? 1));
+}

package/src/pipeline/types.ts

@@ -0,0 +1,80 @@
+/**
+ * Shared types for the middleware pipeline: the `next` callback, the controller
+ * handler return type, the `Pipe` contract, and the response-carrying payload.
+ */
+
+/**
+ * Passes control to the rest of the pipeline and resolves with the `Response`
+ * produced downstream (or `undefined` when nothing deeper has set one yet —
+ * the controller may not have run, or a deeper pipe short-circuited with void).
+ *
+ * Always guard the result before touching it:
+ *
+ *   const res = await next();
+ *   if (res) res.headers.get('…');   // res is Response | undefined
+ */
+export type NextFn = () => Promise<Response | void>;
+
+/**
+ * Return type for controller handler methods.
+ *
+ * Equivalent to `Promise<void>` but communicates intent — a handler either
+ * returns nothing (side-effect already set on ctx) or a ResponseBuilder from
+ * a redirect helper (redirect(), redirect().back(), etc.). Because ResponseBuilder
+ * implements PromiseLike<void>, TypeScript unwraps it to void automatically,
+ * so all IFRS helpers work without changing this type.
+ *
+ * @example
+ * async store(ctx: HttpContext): HttpResponse {
+ *   const data = await StorePostRequest.validate();
+ *   const post  = await Post.create(data);
+ *   return redirect(`/posts/${post.id}`, 303).withSuccess('Post created.');
+ * }
+ *
+ * async showLogin(ctx: HttpContext): HttpResponse {
+ *   return inertia('Auth/Login');
+ * }
+ */
+export type HttpResponse = Promise<void>;
+
+/**
+ * A single step in a middleware pipeline.
+ *
+ * ## Contract
+ * A pipe does exactly one of three things:
+ * - **Continue:** `return next()` to run the rest of the chain.
+ * - **Short-circuit:** produce a `Response` and stop. Either `return` it
+ *   directly, or set `ctx.response` and `return` (void). Do NOT call `next()`.
+ * - **Wrap:** `const res = await next()`, inspect/transform `res`, then return
+ *   the (possibly new) `Response` — or just mutate `ctx.response` and return void.
+ *
+ * `ctx.response` is the canonical store: returning a `Response` is sugar the
+ * pipeline mirrors onto it, and a `void` return leaves it untouched (so it can
+ * never erase a response a deeper pipe already set).
+ *
+ * @example
+ * class RequireAuth implements Pipe<HttpContext> {
+ *   async handle(ctx: HttpContext, next: NextFn): Promise<Response | void> {
+ *     if (!ctx.user) {
+ *       return Response.json({ message: 'Unauthenticated.' }, { status: 401 });
+ *     }
+ *     return next();
+ *   }
+ * }
+ */
+export interface Pipe<T> {
+  handle(payload: T, next: NextFn): Promise<Response | void>;
+}
+
+/**
+ * HttpContext carries the Response when a controller sets it.
+ * Pipes that produce a response set ctx.response and return ctx.
+ * The pipeline terminal in Application.ts reads ctx.response.
+ */
+/**
+ * A payload that can carry a `Response`. Pipes set `response` and return the
+ * payload to short-circuit; the pipeline terminal reads it back.
+ */
+export interface HasResponse {
+  response: Response | undefined;
+}

package/src/provider/LockProvider.ts

@@ -0,0 +1,64 @@
+import { ServiceProvider } from "./ServiceProvider.ts";
+import type { AppEnvironment } from "./ServiceProvider.ts";
+import type { ConfigManager } from "../config/ConfigManager.ts";
+import { LockManager } from "../lock/LockManager.ts";
+import { LockConfig } from "../lock/config.ts";
+import type { LockConfigShape } from "../lock/config.ts";
+import { MemoryLockDriver } from "../lock/drivers/MemoryLockDriver.ts";
+import { SqliteLockDriver } from "../lock/drivers/SqliteLockDriver.ts";
+import { RedisLockDriver } from "../lock/drivers/RedisLockDriver.ts";
+import type { LockDriver } from "../lock/drivers/LockDriver.ts";
+
+// The `lock` binding is registered directly on core's ContainerBindings
+// (see src/container/types.ts) since lock ships as part of core.
+
+/**
+ * Service provider that registers the `lock` binding.
+ *
+ * Reads the `lock` config, instantiates the matching {@link LockDriver}
+ * ({@link MemoryLockDriver}, {@link SqliteLockDriver}, or
+ * {@link RedisLockDriver}), and binds a {@link LockManager} singleton. Pre-
+ * resolves it on boot so the synchronous {@link Lock} facade works afterward,
+ * and disposes the manager (closing driver resources) on stop.
+ *
+ * @category Configuration
+ */
+export class LockProvider extends ServiceProvider {
+  static override provides = ["lock"] as const;
+  static override environments: AppEnvironment[] = ["web", "worker", "console", "test"];
+
+  override onRegister(): void {
+    this.app.container.singleton("lock", () => {
+      const configManager = this.app.container.tryMake("config") as ConfigManager | null;
+      const raw = configManager?.get<Partial<LockConfigShape>>("lock") ?? {};
+      const cfg = LockConfig(raw);
+
+      let driver: LockDriver;
+
+      switch (cfg.driver) {
+        case "redis":
+          driver = new RedisLockDriver(cfg.prefix);
+          break;
+        case "sqlite":
+          driver = new SqliteLockDriver(cfg.sqlite.path);
+          break;
+        case "memory":
+        default:
+          driver = new MemoryLockDriver();
+          break;
+      }
+
+      return new LockManager(driver);
+    });
+  }
+
+  override async onBooted(): Promise<void> {
+    // Pre-resolve so the Lock facade (synchronous callers) works after boot.
+    await this.app.container.make("lock");
+  }
+
+  override async onStopping(): Promise<void> {
+    const manager = this.app.container.tryMake("lock") as LockManager | null;
+    manager?.dispose();
+  }
+}

package/src/provider/LogProvider.ts

@@ -0,0 +1,137 @@
+import { ServiceProvider } from "./ServiceProvider.ts";
+import type { AppEnvironment } from "./ServiceProvider.ts";
+import { FrameworkEvents } from "../events/FrameworkEvents.ts";
+import type {
+  // Application lifecycle
+  AppBooted,
+  // HTTP
+  RequestHandled,
+  RequestFailed,
+} from "../events/FrameworkEvents.ts";
+
+import type { LoggingConfigShape } from "../logger/types.ts";
+import { LoggingConfig } from "../logger/config.ts";
+import { LogManager } from "../logger/LogManager.ts";
+import { LoggerMiddleware } from "../logger/LoggerMiddleware.ts";
+
+/**
+ * What an app without a `config/logging.ts` gets. Deliberately the same as
+ * {@link LoggingConfig}'s own defaults rather than a second, thinner set — an
+ * app that never publishes the config file still gets the file trail, which is
+ * the whole point of the trail being on by default.
+ */
+function _defaultConfig(): LoggingConfigShape {
+  return LoggingConfig();
+}
+
+/** Casts the opaque ctx object to extract HTTP-readable fields. */
+function _ctx(raw: object) {
+  return raw as {
+    response?: { status?: number };
+    request?: { method?: string };
+    url?: { pathname?: string };
+  };
+}
+
+/**
+ * Service provider that wires logging into the application.
+ *
+ * Registers the `log` binding (a {@link LogManager} built from the `logging`
+ * config, enriched with the app name and environment), installs the
+ * {@link LoggerMiddleware} for per-request access logs (unless
+ * `logging.requests` is `false`), and subscribes to the core lifecycle events
+ * (`AppBooted`, and 4xx/5xx `RequestHandled` / `RequestFailed`) to route them
+ * through the logger. Subscriptions are torn down on stop.
+ *
+ * Feature packages log their own activity (slow queries, job/mail/scheduler
+ * failures, the auth audit trail) through their own bridge, which resolves the
+ * `log` binding when logging is installed — so the logger knows nothing about them.
+ *
+ * @category Logging
+ */
+export class LogProvider extends ServiceProvider {
+  static override provides = ["log"] as const;
+  static override environments: AppEnvironment[] = ["web", "console", "worker", "test", "repl"];
+
+  private _unsubs: Array<() => void> = [];
+
+  override onRegister(): void {
+    this.app.container.singleton("log", async (c) => {
+      const cfg = (await c.make("config")) as { get<T>(path: string): T | undefined };
+      const logging = cfg.get<LoggingConfigShape>("logging") ?? _defaultConfig();
+      const appName = cfg.get<string>("app.name");
+      const appEnv = cfg.get<string>("app.env") ?? Bun.env["APP_ENV"];
+
+      return new LogManager(logging, { app: appName, env: appEnv });
+    });
+  }
+
+  override async onBooting(): Promise<void> {
+    const log = (await this.app.container.make("log")) as LogManager;
+    LoggerMiddleware.setManager(log);
+
+    // Per-request access logging is on by default; `logging.requests: false` opts out.
+    const cfg = (await this.app.container.make("config")) as {
+      get<T>(path: string): T | undefined;
+    };
+    const requests = cfg.get<LoggingConfigShape>("logging")?.requests ?? true;
+    if (requests) this.app.useOnce(LoggerMiddleware as never);
+  }
+
+  override async onBooted(): Promise<void> {
+    const manager = (await this.app.container.make("log")) as LogManager;
+    // Framework events carry a scope so a boot log reads as columns rather than
+    // a wall of prose: [APP] for lifecycle, [HTTP] for the request pipeline.
+    const appLog = manager.scope("app");
+    const log = manager.scope("http");
+
+    this._unsubs.push(
+      // ── Application lifecycle ──────────────────────────────────────────────────
+
+      FrameworkEvents.on<AppBooted>("AppBooted", (e) => {
+        appLog.info("Application booted", {
+          durationMs: Math.round(e.durationMs),
+          environment: e.environment,
+          providers: e.providerCount,
+        });
+      }),
+
+      // ── HTTP ─────────────────────────────────────────────────────────────────
+
+      FrameworkEvents.on<RequestHandled>("RequestHandled", (e) => {
+        const c = _ctx(e.ctx);
+        const path = c.url?.pathname ?? "?";
+        if (
+          path.startsWith("/__zerotal/") ||
+          path.startsWith("/__flow/") ||
+          path.startsWith("/__dev/")
+        )
+          return;
+        const status = c.response?.status ?? 0;
+        const ctx = { method: c.request?.method ?? "?", path, status, durationMs: e.durationMs };
+        if (status >= 500) log.error("Request error", ctx);
+        else if (status >= 400) log.warn("Request warning", ctx);
+      }),
+
+      FrameworkEvents.on<RequestFailed>("RequestFailed", (e) => {
+        const c = _ctx(e.ctx);
+        log.error(
+          "Request pipeline error",
+          {
+            method: c.request?.method ?? "?",
+            path: c.url?.pathname ?? "?",
+            status: e.status,
+            durationMs: e.durationMs,
+          },
+          new Error(e.error),
+        );
+      }),
+    );
+  }
+
+  override onStopping(): Promise<void> {
+    for (const unsub of this._unsubs) unsub();
+    this._unsubs = [];
+    return Promise.resolve();
+  }
+}

package/src/provider/ServiceProvider.ts

@@ -0,0 +1,84 @@
+/**
+ * The base class application authors extend to register bindings and hook into
+ * the application lifecycle (boot, start, stop, and per-request phases).
+ */
+import type { Application } from "../application/Application.ts";
+import type { ContainerBindings } from "../container/types.ts";
+import type { HttpContext } from "../pipeline/HttpContext.ts";
+
+/** The runtime modes a provider can declare it participates in. */
+export type AppEnvironment = "web" | "console" | "worker" | "test" | "repl";
+
+/** Base class for service providers: register bindings and observe the app lifecycle. */
+export abstract class ServiceProvider {
+  /** Environments in which this provider is active. Defaults to all of them. */
+  static environments: AppEnvironment[] = ["web", "console", "worker", "test", "repl"];
+
+  /**
+   * Container tokens this provider registers.
+   * Required when using the array form of app.defer([Provider, ...]).
+   *
+   * @example
+   * static override provides = ['cache'] as const;
+   */
+  static provides?: readonly (keyof ContainerBindings)[];
+
+  /**
+   * Other providers this one needs. They are pulled into the application
+   * automatically (transitively, de-duplicated) and guaranteed to boot **before**
+   * this provider — so you only have to register the feature you want, not its
+   * plumbing. Reference the provider classes directly:
+   *
+   * @example
+   * static override dependsOn = [FlowProvider];
+   */
+  static dependsOn?: Array<new (app: Application) => ServiceProvider>;
+
+  /**
+   * Boot-order tiebreak among providers with no `dependsOn` relationship.
+   * Lower boots earlier; defaults to `0`. Handy for framework-core providers
+   * (e.g. `static override priority = -100`).
+   */
+  static priority?: number;
+
+  constructor(protected app: Application) {}
+
+  /** Register container bindings. Runs before any provider boots; do not resolve services here. */
+  onRegister(): void {}
+  /** Resolve and prepare services before the app is considered booted. */
+  async onBooting(): Promise<void> {}
+  /** Run once all providers have booted and every binding is available. */
+  async onBooted(): Promise<void> {}
+  /** Run just before the app starts accepting work (e.g. the HTTP server). */
+  async onStarting(): Promise<void> {}
+  /** Run once the app has started. */
+  async onStarted(): Promise<void> {}
+  /** Run when the app begins a graceful shutdown; release resources here. */
+  async onStopping(): Promise<void> {}
+  /** Run once shutdown is complete. */
+  async onStopped(): Promise<void> {}
+
+  // ── Per-request hooks ─────────────────────────────────────────────────
+  // Called by the framework on every HTTP request. Override to observe or
+  // mutate the lifecycle without registering middleware.
+
+  /** Called before the middleware pipeline runs. */
+  async onRequestReceived(_ctx: HttpContext): Promise<void> {}
+
+  /** Called after the pipeline completes and ctx.response is set. */
+  async onRequestProcessed(_ctx: HttpContext): Promise<void> {}
+
+  /** Called after the response has been sent to the client. */
+  async onResponseSent(_ctx: HttpContext): Promise<void> {}
+
+  /**
+   * Variables to expose in `bun zt repl`.
+   * Override in any provider to make its facades available by name in the REPL session.
+   *
+   * @example
+   * override replContext() { return { DB, Mail }; }
+   */
+  replContext(): Record<string, unknown> {
+    return {};
+  }
+}

package/src/provider/StorageProvider.ts

@@ -0,0 +1,45 @@
+import { ServiceProvider } from "./ServiceProvider.ts";
+import type { AppEnvironment } from "./ServiceProvider.ts";
+import type { ConfigManager } from "../config/ConfigManager.ts";
+import { StorageManager } from "../storage/StorageManager.ts";
+import { StorageConfig } from "../storage/config.ts";
+import { StorageFilesMiddleware, mountsFrom } from "../storage/StorageFilesMiddleware.ts";
+
+declare module "@zerotal/core" {
+  interface ContainerBindings {
+    storage: StorageManager;
+  }
+}
+
+/**
+ * Registers the `storage` binding and, for any disk that declares `serve`, the
+ * middleware that exposes it over HTTP.
+ *
+ * A disk without a `serve` block has no URL at all — the default `local` disk
+ * is unreachable and only `public` is served. Exposure is opt-in per disk
+ * rather than something you have to remember to switch off.
+ */
+export class StorageProvider extends ServiceProvider {
+  static override provides = ["storage"] as const;
+  static override environments: AppEnvironment[] = ["web", "console", "worker", "test"];
+
+  override onRegister(): void {
+    this.app.container.singleton("storage", () => {
+      const config = this.app.container.makeSync("config") as ConfigManager;
+      const storageCfg = config.get<ReturnType<typeof StorageConfig>>("storage", StorageConfig());
+      return new StorageManager(storageCfg);
+    });
+  }
+
+  override async onBooting(): Promise<void> {
+    const storage = await this.app.container.make("storage");
+
+    const config = this.app.container.makeSync("config") as ConfigManager;
+    const storageCfg = config.get<ReturnType<typeof StorageConfig>>("storage", StorageConfig());
+    const mounts = mountsFrom(storageCfg);
+    // No servable disk means no middleware — nothing to match, nothing to get wrong.
+    if (mounts.length === 0) return;
+
+    this.app.useOnce(StorageFilesMiddleware.with({ mounts, storage }));
+  }
+}