okengine 0.8.0 → 0.9.1

package/src/docker/recipes/pgdog.ts

@@ -0,0 +1,84 @@
+/**
+ * PgDog image recipe — Postgres wire-protocol connection pooler.
+ *
+ * Sits in front of the `postgres` recipe. Transaction pooling is set
+ * explicitly (`pooler_mode = "transaction"` — also PgDog's upstream default).
+ * Config shape matches upstream docs: `pgdog.toml` + `users.toml`
+ * (https://docs.pgdog.dev/configuration/).
+ */
+
+import type { ImageRecipe } from "../types.ts";
+
+/** Backend Postgres service name in the compose network. */
+export const PGDOG_BACKEND_SERVICE = "store-sql";
+
+/**
+ * Build `pgdog.toml` — general listen settings + one primary database.
+ *
+ * @param opts - Database name clients use + Postgres host on the compose network
+ */
+export function buildPgDogToml(opts: {
+  readonly database: string;
+  readonly postgresHost?: string;
+}): string {
+  const host = opts.postgresHost ?? PGDOG_BACKEND_SERVICE;
+  const db = opts.database;
+  return [
+    "[general]",
+    'host = "0.0.0.0"',
+    "port = 6432",
+    'pooler_mode = "transaction"',
+    "",
+    "[[databases]]",
+    `name = ${tomlString(db)}`,
+    `host = ${tomlString(host)}`,
+    "port = 5432",
+    `database_name = ${tomlString(db)}`,
+    "",
+  ].join("\n");
+}
+
+/**
+ * Build `users.toml` — one user/database pair (same creds as Postgres).
+ *
+ * @param opts - Client/server credentials
+ */
+export function buildPgDogUsersToml(opts: {
+  readonly user: string;
+  readonly password: string;
+  readonly database: string;
+}): string {
+  return [
+    "[[users]]",
+    `name = ${tomlString(opts.user)}`,
+    `password = ${tomlString(opts.password)}`,
+    `database = ${tomlString(opts.database)}`,
+    "",
+  ].join("\n");
+}
+
+/** PgDog pooler. Postgres wire protocol on 6432. */
+export const pgdog: ImageRecipe = {
+  id: "pgdog",
+  port: 6432,
+  match: (i) => /pgdog/i.test(i),
+  apply: () => ({
+    volumes: ["./pgdog.toml:/pgdog/pgdog.toml:ro", "./users.toml:/pgdog/users.toml:ro"],
+    dependsOn: {
+      [PGDOG_BACKEND_SERVICE]: { condition: "service_healthy" },
+    },
+    healthcheck: {
+      test: ["CMD-SHELL", "pg_isready -h 127.0.0.1 -p 6432 || exit 1"],
+      interval: "5s",
+      timeout: "3s",
+      retries: 12,
+      start_period: "5s",
+    },
+  }),
+  url: (_s, c) =>
+    `postgres://${c.user}:${encodeURIComponent(c.password)}@${c.host}:${c.port}/${c.database}`,
+};
+
+function tomlString(value: string): string {
+  return `"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;
+}

package/src/docker/recipes/redis.ts

@@ -1,15 +1,18 @@
 /**
- * Redis-protocol image recipe (Redis · Valkey · Dragonfly · KeyDB).
+ * Redis image recipe — default `store.kv` pin (`redis:*`).
+ *
+ * Valkey and Dragonfly are separate recipes — same `redis` driver /
+ * `redis://` URL, different binaries. Pin via `images["store.kv"]`.
  */
 
 import { credEnv } from "../helpers.ts";
 import type { ImageRecipe } from "../types.ts";
 
-/** Redis-protocol servers. */
+/** Redis Open Source — Redis protocol on 6379. */
 export const redis: ImageRecipe = {
   id: "redis",
   port: 6379,
-  match: (i) => /redis|valkey|dragonfly|keydb/i.test(i),
+  match: (i) => /(?:^|\/)redis(?:[:@/]|$)/i.test(i) || /keydb/i.test(i),
   apply: (s) => ({
     command: [
       "sh",

package/src/docker/recipes/traefik.ts

@@ -0,0 +1,83 @@
+/**
+ * Traefik image recipe — Docker-label auto-discovery reverse proxy.
+ *
+ * Opt-in via `images.proxy`. Scaled `app` replicas
+ * (`docker compose up --scale app=N`) are discovered via the Docker
+ * provider — no Caddyfile-style reconfiguration.
+ *
+ * Security: the recipe never mounts the raw Docker socket into Traefik.
+ * A `tecnativa/docker-socket-proxy` companion exposes a filtered API
+ * (containers/events/ping/version only) on the internal compose network.
+ * Traefik’s own docs recommend this pattern for Docker API access.
+ */
+
+import { APP_PORT } from "../../runtime/types.ts";
+import type { ImageRecipe } from "../types.ts";
+
+/** Filtered Docker API proxy — only this service mounts `docker.sock`. */
+export const SOCKET_PROXY_IMAGE = "tecnativa/docker-socket-proxy:v0.5.0";
+
+/** Compose service name for the socket proxy companion. */
+export const SOCKET_PROXY_SERVICE = "socket-proxy";
+
+/** Traefik routing labels applied to the `app` service. */
+export function traefikAppLabels(appPort: number = APP_PORT): Record<string, string> {
+  return {
+    "traefik.enable": "true",
+    "traefik.http.routers.app.rule": "Host(`${OKE_PROXY_HOST:-localhost}`)",
+    "traefik.http.routers.app.entrypoints": "websecure",
+    "traefik.http.routers.app.tls.certresolver": "letsencrypt",
+    "traefik.http.services.app.loadbalancer.server.port": String(appPort),
+  };
+}
+
+/** Traefik reverse proxy. HTTP 80 + HTTPS 443; Docker provider via socket-proxy. */
+export const traefik: ImageRecipe = {
+  id: "traefik",
+  port: 80,
+  match: (i) => /traefik/i.test(i),
+  apply: () => ({
+    extraPorts: [{ host: 443, container: 443 }],
+    command: [
+      "--ping=true",
+      "--providers.docker=true",
+      `--providers.docker.endpoint=tcp://${SOCKET_PROXY_SERVICE}:2375`,
+      "--providers.docker.exposedbydefault=false",
+      "--entrypoints.web.address=:80",
+      "--entrypoints.websecure.address=:443",
+      "--entrypoints.web.http.redirections.entrypoint.to=websecure",
+      "--certificatesresolvers.letsencrypt.acme.httpchallenge=true",
+      "--certificatesresolvers.letsencrypt.acme.httpchallenge.entrypoint=web",
+      "--certificatesresolvers.letsencrypt.acme.email=${OKE_PROXY_ACME_EMAIL:-admin@example.com}",
+      "--certificatesresolvers.letsencrypt.acme.storage=/letsencrypt/acme.json",
+    ],
+    volumes: ["proxy-letsencrypt:/letsencrypt"],
+    dependsOn: {
+      [SOCKET_PROXY_SERVICE]: { condition: "service_started" },
+    },
+    healthcheck: {
+      test: ["CMD", "traefik", "healthcheck", "--ping"],
+      interval: "10s",
+      timeout: "3s",
+      retries: 5,
+    },
+    services: {
+      [SOCKET_PROXY_SERVICE]: {
+        image: SOCKET_PROXY_IMAGE,
+        environment: {
+          CONTAINERS: "1",
+          EVENTS: "1",
+          PING: "1",
+          VERSION: "1",
+          NETWORKS: "1",
+        },
+        volumes: ["/var/run/docker.sock:/var/run/docker.sock:ro"],
+        networks: ["oke"],
+      },
+      app: {
+        labels: traefikAppLabels(),
+      },
+    },
+  }),
+  url: (_s, c) => `https://${c.host}`,
+};

package/src/docker/recipes/valkey.ts

@@ -0,0 +1,30 @@
+/**
+ * Valkey image recipe — Redis-wire-compatible (BSD-3-Clause, Linux Foundation).
+ *
+ * Opt-in via `images["store.kv"]` (driver id stays `redis`). Official image:
+ * `valkey/valkey`.
+ */
+
+import { credEnv } from "../helpers.ts";
+import type { ImageRecipe } from "../types.ts";
+
+/** Valkey — Redis protocol on 6379. */
+export const valkey: ImageRecipe = {
+  id: "valkey",
+  port: 6379,
+  match: (i) => /valkey/i.test(i),
+  apply: (s) => ({
+    command: [
+      "sh",
+      "-c",
+      'exec valkey-server --requirepass "$$OKE_STORE_KV_PASSWORD" --maxmemory "$${OKE_STORE_KV_MAXMEMORY:-0}" --maxmemory-policy "$${OKE_STORE_KV_MAXMEMORY_POLICY:-noeviction}"',
+    ],
+    healthcheck: {
+      test: ["CMD", "valkey-cli", "-a", credEnv(s, "PASSWORD"), "ping"],
+      interval: "5s",
+      timeout: "3s",
+      retries: 10,
+    },
+  }),
+  url: (_s, c) => `redis://:${encodeURIComponent(c.password)}@${c.host}:${c.port}`,
+};

package/src/docker/stack-id.ts

@@ -58,6 +58,8 @@ export function hostPortForInstance(
   if (role === "channel.email") return 20_000 + n;
   if (role === "vault") return 22_000 + n;
   if (role === "ai") return 23_000 + n;
+  if (role === "pgdog") return 24_000 + n;
+  if (role === "proxy") return 25_000 + n;
   return defaultHostPort(role, containerPort) + n;
 }
 
@@ -79,6 +81,7 @@ export function extraHostPortForInstance(
   const n = instancePortOffset(instanceId);
   if (role === "store.files") return 19_000 + n;
   if (role === "channel.email") return 21_000 + n;
+  if (role === "proxy") return 26_000 + n;
   return hostPort + n;
 }
 
@@ -123,6 +126,8 @@ export const STACK_CONTROL_KEYS = [
   "MP_SMTP_AUTH_ACCEPT_ANY",
   "MP_SMTP_AUTH_ALLOW_INSECURE",
   "OKE_AI_MODEL",
+  "OKE_PROXY_HOST",
+  "OKE_PROXY_ACME_EMAIL",
 ] as const;
 
 /**

package/src/docker/types.ts

@@ -56,6 +56,9 @@ export interface RecipeExtraPort {
   readonly container: number;
 }
 
+/** Compose `ulimits` value — soft/hard object or a single limit. */
+export type RecipeUlimit = number | { readonly soft?: number; readonly hard?: number };
+
 /** Image-specific compose fragment from {@link ImageRecipe.apply}. */
 export interface RecipeApplyResult {
   readonly environment?: Readonly<Record<string, string>>;
@@ -64,8 +67,23 @@ export interface RecipeApplyResult {
   readonly healthcheck?: ComposeHealthcheck;
   readonly volumes?: readonly string[];
   readonly user?: string;
+  /** Compose `ulimits` (e.g. Dragonfly `memlock: -1`). */
+  readonly ulimits?: Readonly<Record<string, RecipeUlimit>>;
+  /** Labels on this recipe's own compose service. */
+  readonly labels?: Readonly<Record<string, string>>;
   /** Additional published ports (e.g. Mailpit UI, RustFS console). */
   readonly extraPorts?: readonly RecipeExtraPort[];
+  /**
+   * Compose `depends_on` (e.g. pooler waits for Postgres).
+   * Keys are compose service names (`store-sql`), not role keys.
+   */
+  readonly dependsOn?: Readonly<Record<string, { readonly condition: string }>>;
+  /**
+   * Extra `services` entries merged into this role's compose layer —
+   * companions (e.g. Docker socket proxy) or overlays on peers
+   * (e.g. Traefik routing labels on `app`).
+   */
+  readonly services?: Readonly<Record<string, Record<string, unknown>>>;
 }
 
 /**

package/src/drivers/channel-taqnyat-whatsapp.ts

@@ -0,0 +1,94 @@
+/**
+ * `taqnyat-whatsapp` channel driver — WhatsApp via sently's Taqnyat transport.
+ *
+ * Exposes {@link TaqnyatWhatsAppTransport} (including vendor-extra
+ * `sendWithFailover`) on `whatsappTransport` for structural detection.
+ */
+
+import {
+  TaqnyatWhatsAppTransport,
+  type TaqnyatWhatsAppFailover,
+} from "sently/transports/taqnyat-whatsapp";
+import { mapSentlySendError, mapSentlySendResult } from "./channel-sently-map.ts";
+import type {
+  ChannelDriver,
+  ChannelMessage,
+  ChannelOpenOptions,
+  ChannelSendResult,
+  ChannelTransport,
+} from "./channel-types.ts";
+
+/** Structural vendor-extra for provider-side SMS/email failover. */
+export type WhatsAppFailoverTransport = {
+  sendWithFailover(
+    options:
+      | { to: string; text: string }
+      | { to: string; template: { name: string; language: string } },
+    failover: TaqnyatWhatsAppFailover,
+  ): Promise<{ readonly messageId: string; readonly status: string; readonly response: string }>;
+};
+
+/**
+ * Whether a WhatsApp transport exposes `sendWithFailover` (structural).
+ *
+ * @param t - Candidate transport
+ */
+export function hasWhatsAppSendWithFailover(t: unknown): t is WhatsAppFailoverTransport {
+  return (
+    !!t &&
+    typeof t === "object" &&
+    typeof (t as { sendWithFailover?: unknown }).sendWithFailover === "function"
+  );
+}
+
+/**
+ * Open a Taqnyat WhatsApp driver.
+ *
+ * @param options - `bearerToken` / `token` / `apiKey`
+ */
+export function openTaqnyatWhatsAppChannel(options: ChannelOpenOptions = {}): ChannelDriver {
+  const bearerToken = options.bearerToken ?? options.token ?? options.apiKey;
+  if (!bearerToken) {
+    throw new Error("taqnyat-whatsapp: bearerToken (or token/apiKey) is required");
+  }
+
+  const transport = new TaqnyatWhatsAppTransport({ bearerToken });
+
+  const channel: ChannelTransport = {
+    provider: "taqnyat-whatsapp",
+    mediums: ["whatsapp"],
+    async send(message: ChannelMessage): Promise<ChannelSendResult> {
+      try {
+        const templateName =
+          message.template ??
+          (typeof message.data?.template === "string" ? message.data.template : undefined);
+        const language =
+          message.locale ??
+          (typeof message.data?.language === "string" ? message.data.language : "en");
+
+        const result = templateName
+          ? await transport.send({
+              to: message.to,
+              template: { name: templateName, language },
+            })
+          : await transport.send({
+              to: message.to,
+              text: message.text ?? String(message.data?.otp ?? ""),
+            });
+
+        return mapSentlySendResult("taqnyat-whatsapp", result);
+      } catch (err) {
+        return mapSentlySendError("taqnyat-whatsapp", err);
+      }
+    },
+    verify: () => transport.verify(),
+  };
+
+  return { id: "taqnyat-whatsapp", channel, whatsappTransport: transport };
+}
+
+/** Taqnyat WhatsApp driver factory. */
+export const taqnyatWhatsAppChannelDriver = {
+  id: "taqnyat-whatsapp" as const,
+  open: openTaqnyatWhatsAppChannel,
+};

package/src/drivers/channel-types.ts

@@ -148,6 +148,7 @@ export type ChannelDriverId =
   | "sndr"
   | "taqnyat"
   | "taqnyat-mail"
+  | "taqnyat-whatsapp"
   | "msegat"
   | "unifonic"
   | "wa-cloud"

package/src/elements/channel/otp-delivery.test.ts

@@ -0,0 +1,76 @@
+/**
+ * Tier-2 OTP cross-medium FallbackTransport delivery.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { openConsoleChannel } from "../../drivers/channel-console.ts";
+import type { ChannelSendResult } from "../../drivers/channel-types.ts";
+import { deliverOtpAcrossChannels, shouldFallbackOtpMedium } from "./otp-delivery.ts";
+
+describe("otp-delivery", () => {
+  test("shouldFallbackOtpMedium rejects invalid-address errors", () => {
+    expect(shouldFallbackOtpMedium(new Error("invalid recipient address"))).toBe(false);
+    expect(shouldFallbackOtpMedium(Object.assign(new Error("x"), { statusCode: 400 }))).toBe(false);
+    expect(shouldFallbackOtpMedium(new Error("provider timeout"))).toBe(true);
+  });
+
+  test("FailoverTransport advances to next medium on provider error", async () => {
+    let calls = 0;
+    const send = async (template: string): Promise<ChannelSendResult> => {
+      calls += 1;
+      if (template === "auth-otp-sms") {
+        return {
+          ok: false,
+          messageId: "x",
+          driverId: "sms",
+          attempts: [{ driverId: "sms", ok: false, error: "provider timeout", at: Date.now() }],
+        };
+      }
+      return {
+        ok: true,
+        messageId: "e1",
+        driverId: "email",
+        attempts: [{ driverId: "email", ok: true, at: Date.now() }],
+      };
+    };
+
+    const result = await deliverOtpAcrossChannels([openConsoleChannel()], send, {
+      channels: ["sms", "email"],
+      templates: { sms: "auth-otp-sms", email: "auth-otp-email" },
+      phone: "+15551234567",
+      email: "a@example.com",
+      data: { otp: "123456" },
+    });
+
+    expect(result.ok).toBe(true);
+    expect(result.channel).toBe("email");
+    expect(calls).toBe(2);
+    expect(result.attempts.some((a) => !a.ok)).toBe(true);
+    expect(result.attempts.some((a) => a.ok)).toBe(true);
+  });
+
+  test("only: delivers a single channel (explicit resend)", async () => {
+    const templates: string[] = [];
+    const send = async (template: string): Promise<ChannelSendResult> => {
+      templates.push(template);
+      return {
+        ok: true,
+        messageId: "m",
+        driverId: "console",
+        attempts: [{ driverId: "console", ok: true, at: Date.now() }],
+      };
+    };
+
+    const result = await deliverOtpAcrossChannels([openConsoleChannel()], send, {
+      channels: ["sms", "email"],
+      templates: { sms: "auth-otp-sms", email: "auth-otp-email" },
+      phone: "+15551234567",
+      email: "a@example.com",
+      data: { otp: "123456" },
+      only: "email",
+    });
+
+    expect(result.channel).toBe("email");
+    expect(templates).toEqual(["auth-otp-email"]);
+  });
+});