bazis 0.96.1

package/core/infra/connectors/openaiTextStream.ts

@@ -0,0 +1,134 @@
+/** Bounded SSE assembly. Tool arguments are executed only after the complete response is validated. */
+export async function readOpenAiTextStream(
+  response: Response, signal: AbortSignal, maxBytes: number, onText: (text: string) => void, allowTools = false,
+): Promise<unknown> {
+  const fail = (reason: string): never => { throw new Error(`OpenAI-compatible stream ${reason}.`); };
+  const advertised = Number(response.headers.get("content-length"));
+  if (advertised > maxBytes) {
+    void response.body?.cancel().catch(() => undefined);
+    fail("exceeds maxResponseBytes");
+  }
+  if (!response.body) return fail("body is empty");
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder("utf-8", { fatal: true });
+  const text: string[] = [];
+  const calls = new Map<number, { id: string; type: "function"; function: { name: string; arguments: string } }>();
+  let buffer = "", fields: string[] = [], frameChars = 0, total = 0;
+  let finish: string | undefined, done = false, usage: unknown;
+  const maxFrameChars = Math.min(maxBytes, 1024 * 1024);
+  const cancel = () => { void reader.cancel().catch(() => undefined); };
+  const dispatch = () => {
+    if (!fields.length) return;
+    const data = fields.join("\n"); fields = []; frameChars = 0;
+    if (data === "[DONE]") {
+      if (!finish) fail("ended without a finish reason");
+      done = true;
+      return;
+    }
+    let packet: Record<string, unknown>;
+    try {
+      const value = JSON.parse(data);
+      if (!value || typeof value !== "object" || Array.isArray(value)) return fail("contains an invalid event");
+      packet = value;
+    } catch { return fail("contains invalid JSON"); }
+    if (packet.error) fail("reported a provider error");
+    if (packet.usage) usage = packet.usage;
+    if (!Array.isArray(packet.choices)) return fail("contains invalid choices");
+    for (const choice of packet.choices) {
+      if (!choice || choice.index !== 0) fail("contains an unexpected choice");
+      const delta = choice.delta;
+      if (!delta || typeof delta !== "object" || Array.isArray(delta)
+        || (!allowTools && delta.tool_calls != null) || delta.function_call != null) fail("contains an unsupported delta");
+      if (delta.tool_calls != null) {
+        if (finish || !Array.isArray(delta.tool_calls) || delta.tool_calls.length > 16) fail("contains invalid tool calls");
+        for (const part of delta.tool_calls) {
+          if (!part || !Number.isInteger(part.index) || part.index < 0 || part.index >= 16
+            || (part.type !== undefined && part.type !== "function")) fail("contains an invalid tool fragment");
+          const call = calls.get(part.index) ?? { id: "", type: "function" as const, function: { name: "", arguments: "" } };
+          if (part.id !== undefined) {
+            if (typeof part.id !== "string" || !part.id || part.id.length > 256 || (call.id && call.id !== part.id)) fail("contains an invalid tool id");
+            call.id = part.id;
+          }
+          if (part.function !== undefined) {
+            if (!part.function || typeof part.function !== "object" || Array.isArray(part.function)) fail("contains an invalid function");
+            for (const key of ["name", "arguments"] as const) {
+              const value = part.function[key];
+              if (value !== undefined) {
+                if (typeof value !== "string") fail("contains an invalid function fragment");
+                call.function[key] += value;
+              }
+            }
+          }
+          if (call.function.name.length > 128 || call.function.arguments.length > maxBytes) fail("tool exceeds its size limit");
+          calls.set(part.index, call);
+        }
+      }
+      if (delta.content != null) {
+        if (typeof delta.content !== "string" || finish) fail("contains invalid text");
+        if (delta.content) {
+          signal.throwIfAborted();
+          text.push(delta.content);
+          onText(delta.content);
+          signal.throwIfAborted();
+        }
+      }
+      if (choice.finish_reason != null) {
+        if (finish || !["stop", "length", "content_filter", ...(allowTools ? ["tool_calls"] : [])].includes(choice.finish_reason)) fail("contains an invalid finish reason");
+        finish = choice.finish_reason;
+      }
+    }
+  };
+  const consume = () => {
+    let start = 0;
+    for (let index = 0; index < buffer.length; index++) {
+      const char = buffer[index];
+      if (char !== "\r" && char !== "\n") continue;
+      // Preserve a CR at a chunk boundary until its possible LF arrives.
+      if (char === "\r" && index + 1 === buffer.length) break;
+      const line = buffer.slice(start, index);
+      if (char === "\r" && buffer[index + 1] === "\n") index++;
+      start = index + 1;
+      if (line === "") dispatch();
+      else if (line.startsWith("data:")) {
+        const value = line.slice(5).replace(/^ /, "");
+        frameChars += value.length + 1;
+        if (frameChars > maxFrameChars) fail("event exceeds its size limit");
+        fields.push(value);
+      }
+      if (done) break;
+    }
+    buffer = buffer.slice(start);
+    if (!done && buffer.length + frameChars > maxFrameChars) fail("event exceeds its size limit");
+  };
+  if (signal.aborted) cancel();
+  else signal.addEventListener("abort", cancel, { once: true });
+  try {
+    while (!done) {
+      signal.throwIfAborted();
+      const item = await reader.read();
+      signal.throwIfAborted();
+      if (item.done) {
+        // CR alone is a valid SSE line ending, including the last byte at EOF.
+        if (buffer.endsWith("\r")) { buffer += "\n"; consume(); }
+        break;
+      }
+      total += item.value.byteLength;
+      if (total > maxBytes) fail("exceeds maxResponseBytes");
+      try { buffer += decoder.decode(item.value, { stream: true }); }
+      catch { fail("contains invalid UTF-8"); }
+      consume();
+    }
+    // EOF alone is not success: both a terminal choice and [DONE] are required.
+    if (!done) fail("was interrupted before completion");
+    const toolCalls = [...calls.entries()].sort(([a], [b]) => a - b).map(([index, call], position) => {
+      if (index !== position || !call.id || !call.function.name || !call.function.arguments) fail("contains an incomplete tool call");
+      return call;
+    });
+    if ((toolCalls.length > 0) !== (finish === "tool_calls") || new Set(toolCalls.map(call => call.id)).size !== toolCalls.length) fail("contains inconsistent tool calls");
+    return { choices: [{ finish_reason: finish, message: { content: text.join(""), ...(toolCalls.length ? { tool_calls: toolCalls } : {}) } }], usage };
+  } finally {
+    signal.removeEventListener("abort", cancel);
+    cancel(); // Also release a peer that sends [DONE] but never closes its body.
+    reader.releaseLock();
+  }
+}

package/core/infra/connectors/opensearch.ts

@@ -0,0 +1,307 @@
+import { createToken, type InjectionToken } from "../../di";
+import type { AppConfig, ConfigRegistry, Secret } from "../../kernel";
+import { reader, requireValue } from "../connectorConfig";
+import { InfraError, type InfraConnector } from "../InfraConnector";
+import { redactSensitive, redactSensitiveText } from "../../../library/redaction";
+
+/** Default cluster request timeout (ms): fail fast instead of hanging. */
+const DEFAULT_OPENSEARCH_TIMEOUT_MS = 5000;
+const DEFAULT_OPENSEARCH_MAX_RESPONSE_BYTES = 1024 * 1024;
+const MAX_ERROR_PREVIEW_CHARS = 4096;
+
+export interface OpenSearchClientOptions {
+  /** Cluster base URL, e.g. `https://localhost:9200`. */
+  readonly url: string;
+  /** User (basic auth), optional. */
+  readonly username?: string;
+  /** Password (basic auth), optional. A revealed secret; never logged. */
+  readonly password?: string;
+  /** Request timeout in ms (default 5000). Keeps startup from hanging. */
+  readonly timeoutMs?: number;
+  /** Maximum response body size. Defaults to 1 MiB. */
+  readonly maxResponseBytes?: number;
+}
+
+/**
+ * Minimal OpenSearch client on top of `fetch`, with no external dependencies.
+ * Covers what an application usually needs: ping/health, search, index,
+ * through the OpenSearch REST API.
+ */
+export class OpenSearchClient {
+  private readonly lifetime = new AbortController();
+  private readonly base: string;
+  private readonly headers: Readonly<Record<string, string>>;
+  private readonly timeoutMs: number;
+  private readonly maxResponseBytes: number;
+
+  public constructor(options: OpenSearchClientOptions) {
+    this.base = normalizeBaseUrl(options.url);
+    this.timeoutMs = options.timeoutMs ?? DEFAULT_OPENSEARCH_TIMEOUT_MS;
+    this.maxResponseBytes = options.maxResponseBytes ?? DEFAULT_OPENSEARCH_MAX_RESPONSE_BYTES;
+    if (!Number.isSafeInteger(this.timeoutMs) || this.timeoutMs <= 0) {
+      throw new InfraError("OpenSearch timeoutMs must be a positive integer.");
+    }
+    if (!Number.isSafeInteger(this.maxResponseBytes) || this.maxResponseBytes <= 0) {
+      throw new InfraError("OpenSearch maxResponseBytes must be a positive integer.");
+    }
+    // Headers are constant for the client's lifetime, so build them once.
+    const headers: Record<string, string> = { "content-type": "application/json" };
+    if (options.username !== undefined || options.password !== undefined) {
+      const raw = `${options.username ?? ""}:${options.password ?? ""}`;
+      headers.authorization = `Basic ${Buffer.from(raw).toString("base64")}`;
+    }
+    this.headers = headers;
+  }
+
+  /** Low-level cluster request. Throws {@link InfraError} on a non-2xx response. */
+  public async request<T = unknown>(method: string, path: string, body?: unknown, signal?: AbortSignal): Promise<T> {
+    const label = `${safeMethod(method)} ${safePath(path)}`;
+    let response: Response;
+    try {
+      this.lifetime.signal.throwIfAborted();
+      response = await fetch(`${this.base}${path}`, {
+        method,
+        headers: this.headers,
+        body: body === undefined ? undefined : JSON.stringify(body),
+        signal: AbortSignal.any([this.lifetime.signal, AbortSignal.timeout(this.timeoutMs), ...(signal ? [signal] : [])]),
+      });
+    } catch (error) {
+      const detail = redactSensitiveText(error instanceof Error ? error.message : String(error));
+      throw new InfraError(`OpenSearch ${label} request failed: ${detail}`);
+    }
+
+    let text: string;
+    try {
+      text = await readBoundedText(response, this.maxResponseBytes, label);
+    } catch (error) {
+      if (error instanceof InfraError) {
+        throw error;
+      }
+      const detail = redactSensitiveText(error instanceof Error ? error.message : String(error));
+      throw new InfraError(`OpenSearch ${label} response read failed: ${detail}`);
+    }
+    if (!response.ok) {
+      const redacted = redactOpenSearchErrorText(text);
+      const preview = redacted.length > MAX_ERROR_PREVIEW_CHARS
+        ? `${redacted.slice(0, MAX_ERROR_PREVIEW_CHARS)}…`
+        : redacted;
+      throw new InfraError(
+        `OpenSearch ${label} -> ${response.status}: ${preview}`,
+      );
+    }
+    try {
+      return JSON.parse(text) as T;
+    } catch {
+      throw new InfraError(`OpenSearch ${label} returned invalid JSON.`);
+    }
+  }
+
+  /** Cluster information (`GET /`). */
+  public info(): Promise<unknown> {
+    return this.request("GET", "/");
+  }
+
+  /** Abort current requests, including response bodies, and reject subsequent calls. */
+  public dispose(): void {
+    this.lifetime.abort(new InfraError("OpenSearch client is disposed."));
+  }
+
+  /** Cluster health (`GET /_cluster/health`). */
+  public clusterHealth(signal?: AbortSignal): Promise<{ status: "green" | "yellow" | "red" }> {
+    return this.request("GET", "/_cluster/health", undefined, signal);
+  }
+
+  /** Searches an index. */
+  public search<T = unknown>(index: string, body: unknown): Promise<T> {
+    return this.request("POST", `/${indexSegment(index)}/_search`, body);
+  }
+
+  /** Indexes a document (with an explicit id: PUT; without: POST with an auto id). */
+  public index<T = unknown>(index: string, document: unknown, id?: string): Promise<T> {
+    return id === undefined
+      ? this.request("POST", `/${indexSegment(index)}/_doc`, document)
+      : this.request("PUT", `/${indexSegment(index)}/_doc/${documentIdSegment(id)}`, document);
+  }
+
+  /** Healthy only for explicitly accepted cluster states. */
+  public async ping(signal?: AbortSignal): Promise<boolean> {
+    try {
+      const health = await this.clusterHealth(signal);
+      return health?.status === "green" || health?.status === "yellow";
+    } catch {
+      return false;
+    }
+  }
+}
+
+/** OpenSearch client token for injection into application services. */
+export const OPENSEARCH: InjectionToken<OpenSearchClient> = createToken<OpenSearchClient>("OpenSearch");
+
+/**
+ * Config interface required by the OpenSearch connector. The search subsystem
+ * config (`defineConfig<SearchConfig>("search", ...)`) must provide these keys.
+ */
+export interface OpenSearchConfigShape {
+  /** Cluster base URL, e.g. `https://localhost:9200`. */
+  readonly url: string;
+  readonly username: string;
+  /** Basic-auth password: declared as `secret(...)`, read as a `Secret`. */
+  readonly password: Secret;
+}
+
+export interface OpenSearchConnectorOptions {
+  readonly token?: InjectionToken<OpenSearchClient>;
+  /** Request timeout in ms (default 5000). */
+  readonly timeoutMs?: number;
+  /** Maximum response body size. Defaults to 1 MiB. */
+  readonly maxResponseBytes?: number;
+}
+
+function buildOpenSearchOptions<T extends OpenSearchConfigShape>(
+  config: AppConfig<T>,
+  options: OpenSearchConnectorOptions,
+  configs?: ConfigRegistry,
+): OpenSearchClientOptions {
+  const c = reader(config, configs);
+  return {
+    url: requireValue(c.get("url"), "url", "opensearch"),
+    username: c.get("username") as string,
+    password: (c.get("password") as Secret).reveal(),
+    ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
+    ...(options.maxResponseBytes !== undefined ? { maxResponseBytes: options.maxResponseBytes } : {}),
+  };
+}
+
+function normalizeBaseUrl(raw: string): string {
+  let url: URL;
+  try {
+    url = new URL(raw);
+  } catch {
+    throw new InfraError("OpenSearch url must be a valid absolute URL.");
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new InfraError("OpenSearch url must use http or https.");
+  }
+  if (url.username.length > 0 || url.password.length > 0) {
+    throw new InfraError("OpenSearch url must not contain embedded credentials; use username/password config fields.");
+  }
+  if (url.search.length > 0 || url.hash.length > 0) {
+    throw new InfraError("OpenSearch url must not contain a query string or fragment.");
+  }
+  return url.toString().replace(/\/+$/, "");
+}
+
+function indexSegment(index: string): string {
+  if (index.trim().length === 0) {
+    throw new InfraError("OpenSearch index must be a non-empty string.");
+  }
+  return encodeURIComponent(index);
+}
+
+function documentIdSegment(id: string): string {
+  if (id.trim().length === 0) {
+    throw new InfraError("OpenSearch document id must be a non-empty string.");
+  }
+  return encodeURIComponent(id);
+}
+
+function safeMethod(method: string): string {
+  const normalized = method.toUpperCase().replace(/[^A-Z]/g, "");
+  return normalized.length === 0 ? "REQUEST" : normalized;
+}
+
+function safePath(path: string): string {
+  return redactSensitiveText(path.replace(/[\r\n\t]/g, " ").slice(0, 512));
+}
+
+function redactOpenSearchErrorText(text: string): string {
+  try {
+    return JSON.stringify(redactSensitive(JSON.parse(text)));
+  } catch {
+    return redactSensitiveText(text);
+  }
+}
+
+async function readBoundedText(response: Response, maxBytes: number, label: string): Promise<string> {
+  const declared = response.headers.get("content-length");
+  if (declared !== null) {
+    const length = Number(declared);
+    if (Number.isFinite(length) && length > maxBytes) {
+      await response.body?.cancel().catch(() => undefined);
+      throw new InfraError(`OpenSearch ${label} response exceeded ${maxBytes} bytes.`);
+    }
+  }
+  if (response.body === null) {
+    return "";
+  }
+
+  const reader = response.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) {
+        break;
+      }
+      total += value.byteLength;
+      if (total > maxBytes) {
+        await reader.cancel().catch(() => undefined);
+        throw new InfraError(`OpenSearch ${label} response exceeded ${maxBytes} bytes.`);
+      }
+      chunks.push(value);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+
+  const bytes = new Uint8Array(total);
+  let offset = 0;
+  for (let index = 0; index < chunks.length; index += 1) {
+    const chunk = chunks[index]!;
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return new TextDecoder().decode(bytes);
+}
+
+/**
+ * OpenSearch connector for the `@Infra` manifest. Configuration comes from the
+ * given `searchConfig` (`defineConfig("search", ...)`): the connector reads the
+ * declared `url`/`username`/`password` keys. The client is a fetch wrapper, so
+ * "opening the connection" is a cluster ping at start (fail fast if the cluster
+ * is unreachable). Closing aborts active requests and rejects new ones.
+ *
+ * ```ts
+ * export const searchConfig = defineConfig("search", {
+ *   default: { url: "https://localhost:9200", username: "admin", password: secret("dev") },
+ * });
+ * @Infra({ search: openSearchConnect(searchConfig) })
+ * export class AppInfra {}
+ * // injection by token: scoped(ISearchService, SearchService, [OPENSEARCH] as const)
+ * ```
+ */
+export function openSearchConnect<T extends OpenSearchConfigShape>(
+  config: AppConfig<T>,
+  options: OpenSearchConnectorOptions = {},
+): InfraConnector<OpenSearchClient> {
+  return {
+    token: options.token ?? OPENSEARCH,
+    config,
+    create(configs) {
+      return new OpenSearchClient(buildOpenSearchOptions(config, options, configs));
+    },
+    async connect(client, signal) {
+      const alive = await client.ping(signal);
+      if (!alive) {
+        throw new InfraError(`Infra connector "opensearch": cluster is not reachable or unhealthy.`);
+      }
+    },
+    dispose(client) {
+      client.dispose();
+    },
+    healthCheck(client, signal) {
+      return client.ping(signal);
+    },
+  };
+}

package/core/infra/connectors/postgres.ts

@@ -0,0 +1,105 @@
+import { SQL } from "bun";
+import { createToken, type InjectionToken } from "../../di";
+import type { AppConfig, ConfigRegistry, Secret } from "../../kernel";
+import { reader, requireValue } from "../connectorConfig";
+import { errorMessage, InfraError, type InfraConnector } from "../InfraConnector";
+
+/** PostgreSQL client (native Bun `SQL`, no external dependencies). */
+export const POSTGRES: InjectionToken<SQL> = createToken<SQL>("Postgres");
+
+/**
+ * Config interface required by the PostgreSQL connector. The database subsystem
+ * config (`defineConfig<DbConfig>("db", ...)`) must provide these keys.
+ */
+export interface PostgresConfigShape {
+  readonly host: string;
+  readonly port: number;
+  readonly database: string;
+  readonly username: string;
+  readonly password: Secret;
+  readonly tls?: PostgresSslMode;
+  readonly max?: number;
+  readonly connectionTimeout?: number;
+  readonly idleTimeout?: number;
+  readonly maxLifetime?: number;
+}
+
+export type PostgresSslMode = "disable" | "allow" | "prefer" | "require" | "verify-ca" | "verify-full";
+export interface PostgresConnectorOptions {
+  readonly token?: InjectionToken<SQL>;
+  /** Maximum pool drain before closing connections. Default 1000ms; 0 closes immediately. */
+  readonly shutdownTimeoutMs?: number;
+}
+
+/** Shared raw SQL/ORM options. Driver timeout fields are in seconds. */
+export function postgresConnectionOptions(config: AppConfig<PostgresConfigShape>, configs?: ConfigRegistry): Bun.SQL.Options {
+  const c = reader(config, configs);
+  const integer = (key: string, min: number, max: number): number | undefined => {
+    const value = c.has(key) ? c.get(key) : undefined;
+    if (value === undefined) return undefined;
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < min || value > max) throw new InfraError(`postgres ${key} must be an integer ${min}..${max}`);
+    return value;
+  };
+  const tls = c.has("tls") ? c.get("tls") : undefined;
+  if (tls !== undefined && !["disable", "allow", "prefer", "require", "verify-ca", "verify-full"].includes(String(tls))) throw new InfraError("postgres tls is invalid");
+  return {
+    hostname: requireValue(c.get("host"), "host", "postgres"),
+    port: integer("port", 1, 65535),
+    database: requireValue(c.get("database"), "database", "postgres"),
+    username: requireValue(c.get("username"), "username", "postgres"),
+    password: (c.get("password") as Secret).reveal(),
+    ...(tls === undefined ? {} : { tls: tls as PostgresSslMode }),
+    max: integer("max", 1, 2147483647),
+    connectionTimeout: integer("connectionTimeout", 1, 2147483647),
+    idleTimeout: integer("idleTimeout", 0, 2147483647),
+    maxLifetime: integer("maxLifetime", 0, 2147483647),
+  };
+}
+
+/**
+ * PostgreSQL connector for the `@Infra` manifest. The whole configuration comes
+ * from the given `dbConfig` object (`defineConfig("db", ...)`): the connector
+ * reads the declared keys (`host`/`port`/`database`/`username`/`password`)
+ * itself, with no string keys in the manifest. Opens the connection at start
+ * (`SELECT 1`) and closes it at shutdown.
+ *
+ * ```ts
+ * export const dbConfig = defineConfig("db", {
+ *   default: { host: "localhost", port: 5432, database: "app", username: "postgres", password: secret("dev") },
+ * });
+ * @Infra({ db: postgres(dbConfig) })
+ * export class AppInfra {}
+ * // injection by token: scoped(IReportsService, ReportsService, [POSTGRES] as const)
+ * ```
+ */
+export function postgres<T extends PostgresConfigShape>(config: AppConfig<T>, options: PostgresConnectorOptions = {}): InfraConnector<SQL> {
+  const shutdownTimeoutMs = options.shutdownTimeoutMs === undefined ? 1000 : options.shutdownTimeoutMs;
+  if (!Number.isSafeInteger(shutdownTimeoutMs) || shutdownTimeoutMs < 0 || shutdownTimeoutMs > 2147483647) {
+    throw new InfraError("postgres shutdownTimeoutMs must be an integer 0..2147483647");
+  }
+  return {
+    token: options.token ?? POSTGRES,
+    config,
+    create(configs) {
+      return new SQL(postgresConnectionOptions(config, configs));
+    },
+    async connect(client) {
+      try {
+        await client.unsafe("SELECT 1");
+      } catch (error) {
+        throw new InfraError(`Infra connector "postgres": failed to connect — ${errorMessage(error)}`);
+      }
+    },
+    async dispose(client) {
+      await client.close({ timeout: shutdownTimeoutMs / 1000 });
+    },
+    async healthCheck(client) {
+      try {
+        await client.unsafe("SELECT 1");
+        return true;
+      } catch {
+        return false;
+      }
+    },
+  };
+}

package/core/infra/connectors/redis.ts

@@ -0,0 +1,132 @@
+import { RedisClient } from "bun";
+import {
+  DISTRIBUTED_CACHE_BACKEND,
+  DISTRIBUTED_OUTPUT_CACHE,
+  DISTRIBUTED_SERVICE_CACHE,
+  type DistributedCacheStores,
+} from "../../cache";
+import { createToken, DI, type InjectionToken, type ProviderDefinition } from "../../di";
+import type { AppConfig, Secret } from "../../kernel";
+import { RedisDistributedCacheBackend, type RedisDistributedCacheTuning } from "../cache/RedisDistributedCacheBackend";
+import { reader, requireValue } from "../connectorConfig";
+import { errorMessage, InfraError, type InfraConnector } from "../InfraConnector";
+
+/** Redis/Valkey client (native Bun `RedisClient`, no external dependencies). */
+export const REDIS: InjectionToken<RedisClient> = createToken<RedisClient>("Redis");
+
+/**
+ * Config interface required by the Redis connector. The subsystem config
+ * (`defineConfig<RedisConfig>("redis", ...)`) must provide these keys.
+ */
+export interface RedisConfigShape {
+  /** Full connection string, e.g. `redis://localhost:6379`. */
+  readonly url: string | Secret;
+}
+
+export type RedisConnectorCacheMode =
+  | "distributed"
+  | ({ readonly mode: "distributed" } & RedisDistributedCacheTuning);
+
+export interface RedisConnectorOptions {
+  readonly token?: InjectionToken<RedisClient>;
+  /**
+   * Publishes a distributed cache backend on top of the client: `{ cache: "distributed" }`.
+   * For fine tuning use `{ cache: { mode: "distributed", keyPrefix, ... } }`.
+   * An application may have one backend; a second one is rejected when the container is built.
+   */
+  readonly cache?: RedisConnectorCacheMode;
+}
+
+/**
+ * Distributed cache providers on top of the Redis client: the backend plus two
+ * registries (HTTP responses and method values). The cache module picks them up from DI.
+ */
+function distributedCacheProviders(tuning: RedisDistributedCacheTuning, token: InjectionToken<RedisClient>): ProviderDefinition[] {
+  return [
+    DI.singleton(
+      DI.factoryProvider(
+        DISTRIBUTED_CACHE_BACKEND,
+        [token],
+        (client: RedisClient) => new RedisDistributedCacheBackend(client, tuning),
+      ),
+    ),
+    DI.singleton(
+      DI.factoryProvider(DISTRIBUTED_OUTPUT_CACHE, [DISTRIBUTED_CACHE_BACKEND], (backend: DistributedCacheStores) =>
+        backend.outputCache,
+      ),
+    ),
+    DI.singleton(
+      DI.factoryProvider(DISTRIBUTED_SERVICE_CACHE, [DISTRIBUTED_CACHE_BACKEND], (backend: DistributedCacheStores) =>
+        backend.serviceCache,
+      ),
+    ),
+  ];
+}
+
+/**
+ * Redis connector for the `@Infra` manifest. Configuration comes from the given
+ * `redisConfig` (`defineConfig("redis", ...)`): the connector reads the declared
+ * `url` key. Opens the connection at start and closes it at shutdown. The second
+ * argument takes connector options (distributed cache and so on).
+ *
+ * ```ts
+ * export const redisConfig = defineConfig("redis", { default: { url: "redis://localhost:6379" } });
+ * @Infra({ cache: redisConnect(redisConfig, { cache: "distributed" }) })
+ * export class AppInfra {}
+ * // injection by token: scoped(ISessionsService, SessionsService, [REDIS] as const)
+ * ```
+ */
+export function redisConnect<T extends RedisConfigShape>(
+  config: AppConfig<T>,
+  options: RedisConnectorOptions = {},
+): InfraConnector<RedisClient> {
+  const cache = options.cache;
+  const token = options.token ?? REDIS;
+  const cacheProviders =
+    cache === undefined
+      ? undefined
+      : distributedCacheProviders(cache === "distributed" ? {} : withoutMode(cache), token);
+
+  return {
+    token,
+    config,
+    providers: cacheProviders,
+    exports: cacheProviders ? [DISTRIBUTED_CACHE_BACKEND, DISTRIBUTED_OUTPUT_CACHE, DISTRIBUTED_SERVICE_CACHE] : undefined,
+    create(configs) {
+      return new RedisClient(redisUrl(reader(config, configs).get("url")));
+    },
+    async connect(client) {
+      try {
+        await client.connect();
+      } catch (error) {
+        throw new InfraError(`Infra connector "redis": failed to connect — ${errorMessage(error)}`);
+      }
+    },
+    dispose(client) {
+      client.close();
+    },
+    async healthCheck(client) {
+      try {
+        return (await client.ping()) === "PONG";
+      } catch {
+        return false;
+      }
+    },
+  };
+}
+
+function redisUrl(value: unknown): string {
+  if (typeof value === "string") {
+    return requireValue(value, "url", "redis");
+  }
+  const reveal = (value as { readonly reveal?: unknown } | null)?.reveal;
+  if (typeof reveal === "function") {
+    return requireValue(reveal.call(value), "url", "redis");
+  }
+  throw new InfraError('Infra connector "redis": "url" must be a string or Secret.');
+}
+
+function withoutMode(cache: { readonly mode: "distributed" } & RedisDistributedCacheTuning): RedisDistributedCacheTuning {
+  const { mode: _mode, ...tuning } = cache;
+  return tuning;
+}