okengine 0.7.0 → 0.9.0

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-sently.test.ts

@@ -7,6 +7,7 @@ import { openFcmChannel } from "./channel-fcm.ts";
 import { openMsegatChannel } from "./channel-msegat.ts";
 import { openSndrChannel } from "./channel-sndr.ts";
 import { openTaqnyatChannel } from "./channel-taqnyat.ts";
+import { openTaqnyatMailChannel } from "./channel-taqnyat-mail.ts";
 import { openUnifonicChannel } from "./channel-unifonic.ts";
 import { openWaCloudChannel } from "./channel-wa-cloud.ts";
 import { openWebPushChannel } from "./channel-webpush.ts";
@@ -26,6 +27,13 @@ describe("sently channel drivers", () => {
     expect(d.channel?.mediums).toContain("sms");
   });
 
+  test("taqnyat-mail requires bearer + campaignName", () => {
+    expect(() => openTaqnyatMailChannel({ bearerToken: "t" })).toThrow("campaignName");
+    const d = openTaqnyatMailChannel({ bearerToken: "t", campaignName: "auth" });
+    expect(d.id).toBe("taqnyat-mail");
+    expect(d.transport?.provider).toBe("taqnyat-mail");
+  });
+
   test("msegat requires userName + apiKey + sender", () => {
     expect(() => openMsegatChannel({ userName: "u", apiKey: "k" })).toThrow("sender");
     const d = openMsegatChannel({ userName: "u", apiKey: "k", sender: "Brand" });

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

@@ -0,0 +1,34 @@
+/**
+ * `taqnyat-mail` channel driver — Email via sently's Taqnyat Mail transport.
+ *
+ * Additive email option (alongside smtp / resend / sndr). Taqnyat's
+ * `mailSend.php` requires a campaign name — set via options or
+ * `TAQNYAT_CAMPAIGN`.
+ */
+
+import { TaqnyatMailTransport } from "sently/transports/taqnyat-mail";
+import type { ChannelDriver, ChannelOpenOptions } from "./channel-types.ts";
+
+/**
+ * Open a Taqnyat Email driver.
+ *
+ * @param options - `bearerToken`/`token`/`apiKey` + `campaignName`
+ */
+export function openTaqnyatMailChannel(options: ChannelOpenOptions = {}): ChannelDriver {
+  const bearerToken = options.bearerToken ?? options.token ?? options.apiKey;
+  if (!bearerToken) {
+    throw new Error("taqnyat-mail channel: bearerToken (or token/apiKey) is required");
+  }
+  const campaignName = options.campaignName;
+  if (!campaignName) {
+    throw new Error("taqnyat-mail channel: campaignName is required");
+  }
+  const transport = new TaqnyatMailTransport({ bearerToken, campaignName });
+  return { id: "taqnyat-mail", transport };
+}
+
+/** Taqnyat Email driver factory. */
+export const taqnyatMailChannelDriver = {
+  id: "taqnyat-mail" as const,
+  open: openTaqnyatMailChannel,
+};

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

@@ -58,6 +58,74 @@ export interface WhatsAppTransport {
   close?(): Promise<void>;
 }
 
+/**
+ * Provider-managed OTP vendor extra on an SMS transport (Taqnyat Verify).
+ * Kept off the base {@link SmsTransport} surface — only transports that expose
+ * these methods support Channel provider OTP.
+ */
+export interface SmsOtpTransport {
+  sendOtp(options: ChannelOtpSendOptions): Promise<ChannelOtpSendResult>;
+  verifyOtp(options: ChannelOtpVerifyOptions): Promise<ChannelOtpVerifyResult>;
+}
+
+/** Options for {@link SmsOtpTransport.sendOtp} (Taqnyat Verify). */
+export interface ChannelOtpSendOptions {
+  /** Recipient phone number (E.164). */
+  readonly to: string;
+  /** Unique id for this verification flow (required again on verify). */
+  readonly requestId: string;
+  /** Message language (`en` or `ar`). */
+  readonly lang?: "en" | "ar";
+  /** Optional note appended to the OTP SMS. */
+  readonly note?: string;
+  /** Sender id override. */
+  readonly from?: string;
+}
+
+/** Result of a successful provider OTP send. */
+export interface ChannelOtpSendResult {
+  /** Echo of the {@link ChannelOtpSendOptions.requestId}. */
+  readonly requestId: string;
+  /** Recipient as passed in. */
+  readonly to: string;
+  /** Provider status code (`5` = code sent). */
+  readonly code: number;
+  /** Raw response body text. */
+  readonly response: string;
+  /** Provider identifier. */
+  readonly provider: string;
+}
+
+/** Options for {@link SmsOtpTransport.verifyOtp}. */
+export interface ChannelOtpVerifyOptions {
+  /** Recipient phone number (same as send). */
+  readonly to: string;
+  /** Same {@link ChannelOtpSendOptions.requestId} used when sending. */
+  readonly requestId: string;
+  /** OTP code the user entered. */
+  readonly code: string;
+  /** Message language (`en` or `ar`). */
+  readonly lang?: "en" | "ar";
+  /** Sender id override. */
+  readonly from?: string;
+  /** Optional note. */
+  readonly note?: string;
+}
+
+/** Result of a successful provider OTP check (failures throw). */
+export interface ChannelOtpVerifyResult {
+  /** Always `true` when the call resolves. */
+  readonly ok: true;
+  /** Provider status code (`10` = completed; `13`/`19` = already verified). */
+  readonly code: number;
+  /** Provider message when present. */
+  readonly message: string;
+  /** Raw response body text. */
+  readonly response: string;
+  /** Provider identifier. */
+  readonly provider: string;
+}
+
 /** Sently-compatible push transport (structural). */
 export interface PushTransport {
   readonly provider?: string;
@@ -79,6 +147,8 @@ export type ChannelDriverId =
   | "resend"
   | "sndr"
   | "taqnyat"
+  | "taqnyat-mail"
+  | "taqnyat-whatsapp"
   | "msegat"
   | "unifonic"
   | "wa-cloud"
@@ -183,6 +253,8 @@ export interface ChannelOpenOptions {
   readonly vapidPublicKey?: string;
   readonly vapidPrivateKey?: string;
   readonly vapidSubject?: string;
+  /** Taqnyat Email campaign name (required by `mailSend.php`). */
+  readonly campaignName?: string;
   /** Injected fetch for HTTP drivers. */
   readonly fetch?: typeof globalThis.fetch;
   /** Dev inbox sink for console driver. */