@tulipes/cli 0.1.1 → 0.2.0-rc.1

package/templates/app/modules/config/controllers/config.controllers.ts

@@ -0,0 +1,89 @@
+import type { Request, RequestHandler, Response } from "express";
+import type { Ctx } from "@tulipes/core/boot";
+import { SettingsConflictError, SettingsValidationError } from "@tulipes/core/config";
+import { HttpError, ValidationError } from "@tulipes/core/http";
+
+import { auditChange } from "../helpers/audit.ts";
+import { describeModule } from "../helpers/describe.ts";
+
+/**
+ * The console: what every module is configured with, and the one write —
+ * a settings patch, validated by the module's schema, refused on a stale
+ * version, audited before it lands, applied in this process at once and
+ * in every other replica through the store's watch. Nothing here edits
+ * the environment: a variable is what boot needs before the store answers
+ * or a secret, and neither is edited at runtime.
+ */
+export class ConfigController {
+  readonly #ctx: Ctx;
+
+  constructor(ctx: Ctx) {
+    this.#ctx = ctx;
+  }
+
+  /** Every module, in load order. */
+  app(): RequestHandler {
+    return (_req: Request, res: Response) => {
+      res.respond({
+        data: {
+          app: this.#ctx.config.app ?? {},
+          store: this.#ctx.settings.status(),
+          modules: this.#ctx.modules.map((module) => describeModule(this.#ctx, module.name)),
+        },
+      });
+    };
+  }
+
+  module(): RequestHandler {
+    return (req: Request, res: Response) => {
+      const described = describeModule(this.#ctx, String(req.params.module));
+      if (!described) throw new HttpError(404, "noSuchModule", { field: "module" });
+      res.respond({ data: described });
+    };
+  }
+
+  change(): RequestHandler {
+    return async (req: Request, res: Response) => {
+      const namespace = String(req.params.module);
+      const { values, version } = req.body as { values: Record<string, unknown>; version?: number };
+      if (!this.#ctx.settings.namespaces().includes(namespace)) {
+        throw new HttpError(404, "noSuchModule", { field: "module" });
+      }
+
+      const current = this.#ctx.settings.describe(namespace).stored.version;
+      if (version !== undefined && version !== current) {
+        throw new HttpError(409, "staleVersion", {
+          code: "STALE_VERSION",
+          vars: { version: String(version), current: String(current) },
+          details: { current },
+          defaultMessage: `version ${version} is stale; the store holds version ${current}`,
+        });
+      }
+
+      // Acknowledged before anything changes: identifiers only, never values.
+      await auditChange(this.#ctx, req, { module: namespace, keys: Object.keys(values), version: current });
+
+      const user = req.auth.user!;
+      try {
+        const written = await this.#ctx.settings.set(namespace, values, { id: String(user._id), label: user.email });
+        res.respond({
+          data: { module: namespace, values: written.values, version: written.version, requires_restart: written.requiresRestart },
+          ...(written.requiresRestart.length > 0 && { meta: { action: "restart_required" } }),
+        });
+      } catch (error) {
+        if (error instanceof SettingsValidationError) {
+          throw new ValidationError(error.issues.map((issue) => ({ field: issue.path.map(String).join(".") || "values", message: issue.message })));
+        }
+        if (error instanceof SettingsConflictError) {
+          throw new HttpError(409, "staleVersion", {
+            code: "STALE_VERSION",
+            vars: { version: String(error.expectedVersion), current: String(error.current?.version ?? 0) },
+            details: { current: error.current?.version ?? 0 },
+            defaultMessage: error.message,
+          });
+        }
+        throw error;
+      }
+    };
+  }
+}

package/templates/app/modules/config/helpers/audit.ts

@@ -0,0 +1,41 @@
+import type { Request } from "express";
+import type { Ctx } from "@tulipes/core/boot";
+import { HttpError } from "@tulipes/core/http";
+
+/**
+ * Persist before applying a change, independent of LOG_LEVEL and with a
+ * majority acknowledgment: a write nobody can account for is worse than a
+ * write that did not happen. Only identifiers enter the record — the
+ * namespace, the field names, the version the caller read — never values.
+ * Failure is deliberately terminal: the caller awaits this before acting.
+ */
+export async function auditChange(
+  ctx: Ctx,
+  req: Request,
+  change: { module: string; keys: string[]; version: number },
+): Promise<void> {
+  const user = req.auth.user;
+  if (!user) throw new HttpError(401, "unauthenticated");
+
+  try {
+    const Audit = ctx.models!.get("ConfigAudit");
+    await new Audit({
+      action: "settings.change_requested",
+      module: change.module,
+      keys: change.keys,
+      version: change.version,
+      actor: String(user._id),
+      actor_role: user.role,
+      ip: req.ip,
+      app_env: ctx.Environment.appEnv,
+      mode: ctx.mode,
+      recorded_at: new Date(),
+    }).save({ w: "majority", j: true, wtimeout: 5000 });
+  } catch {
+    // Sink/validation errors may contain record content or connection details.
+    throw new HttpError(503, "auditUnavailable", {
+      code: "AUDIT_UNAVAILABLE",
+      defaultMessage: "The audit record could not be acknowledged; the change was not applied",
+    });
+  }
+}

package/templates/app/modules/config/helpers/describe.ts

@@ -0,0 +1,72 @@
+import type { Ctx } from "@tulipes/core/boot";
+
+/**
+ * Everything the framework knows about one module, for the console: the
+ * manifest, the variables it declares (names, types, sources — a secret's
+ * value never, any value only as what the process resolved), its settings
+ * with their schema, live values and stored version, and its endpoints
+ * with the roles that reach them. Nothing is invented: it all comes from
+ * the booted context, so the console cannot describe an app different
+ * from the one running.
+ */
+export function describeModule(ctx: Ctx, name: string): Record<string, unknown> | undefined {
+  const manifest = ctx.modules.find((entry) => entry.name === name);
+  if (!manifest) return undefined;
+
+  const variables = ctx.Environment.store.describe()
+    .filter((variable) => variable.owner === name)
+    .map((variable) => ({
+      name: variable.spec.name,
+      type: variable.spec.type,
+      description: variable.spec.description,
+      group: variable.spec.group ?? null,
+      required: variable.spec.required ?? false,
+      enum: variable.spec.enum ?? null,
+      default: variable.spec.type === "secret" ? null : (variable.spec.default ?? null),
+      source: variable.source,
+      is_secret: variable.isSecret,
+      is_set: variable.isSet,
+      // What this process resolved; a secret is never here.
+      value: variable.isSecret ? null : (variable.value ?? null),
+    }));
+
+  const settings = ctx.settings.namespaces().includes(name) ? ctx.settings.describe(name) : undefined;
+  const grants = ctx.acl?.describe() ?? [];
+  const routes = ctx.routes.all()
+    .filter((record) => record.module === name)
+    .map((record) => ({
+      id: record.info.id,
+      method: record.method.toUpperCase(),
+      path: record.path,
+      name: record.info.name ?? null,
+      roles: ctx.routes.checker ? "dynamic" : rolesFor(grants, record.info.id),
+    }));
+
+  return {
+    name: manifest.name,
+    tier: manifest.tier,
+    priority: manifest.priority,
+    depends_on: manifest.dependsOn,
+    variables,
+    settings: settings
+      ? {
+          schema: settings.schema,
+          values: settings.values,
+          version: settings.stored.version,
+          updated_at: settings.stored.updated_at,
+          updated_by: settings.stored.updated_by,
+          restart_fields: settings.restart,
+          pending_restart: settings.pendingRestart,
+        }
+      : null,
+    routes,
+  };
+}
+
+function rolesFor(grants: { role: string; resource: string }[], id: string): string[] {
+  const namespace = `${id.split(":")[0]}:*`;
+  const roles = grants
+    .filter(({ resource }) => resource === id || resource === "*" || resource === namespace)
+    .map(({ role }) => role);
+  return [...new Set(roles)].sort();
+}

package/templates/app/modules/config/i18n/en.json

@@ -0,0 +1,6 @@
+{
+  "noSuchModule": "No such module",
+  "invalidModuleName": "Module names are lowercase kebab-case",
+  "staleVersion": "Version {{version}} is stale; the store holds version {{current}}",
+  "auditUnavailable": "The audit record could not be acknowledged; the change was not applied"
+}

package/templates/app/modules/config/i18n/fr.json

@@ -0,0 +1,6 @@
+{
+  "noSuchModule": "Module introuvable",
+  "invalidModuleName": "Les noms de modules sont en kebab-case minuscule",
+  "staleVersion": "La version {{version}} est périmée ; le dépôt est à la version {{current}}",
+  "auditUnavailable": "L’enregistrement d’audit n’a pas pu être confirmé ; la modification n’a pas été appliquée"
+}

package/templates/app/modules/config/models/config-audit.model.ts

@@ -0,0 +1,26 @@
+import { Schema } from "mongoose";
+import type { ModelDef } from "@tulipes/mongoose";
+
+/**
+ * A requested settings change, acknowledged before it is applied. Only the
+ * namespace, the field names and the version travel — never a value, so
+ * the record can be read by anyone who may read the audit without seeing
+ * what was written.
+ */
+const configAuditSchema = new Schema({
+  action: { type: String, required: true, enum: ["settings.change_requested"] },
+  module: { type: String, required: true },
+  keys: { type: [String], required: true },
+  version: { type: Number, required: true },
+  actor: { type: String, required: true },
+  actor_role: { type: String, required: true },
+  ip: String,
+  app_env: { type: String, required: true },
+  mode: { type: String, required: true },
+  recorded_at: { type: Date, required: true },
+}, { collection: "config_audit_events", strict: "throw" });
+
+// No automatic retention: operators own archival/retention for this audit store.
+configAuditSchema.index({ actor: 1, recorded_at: -1 });
+configAuditSchema.index({ module: 1, recorded_at: -1 });
+export default { name: "ConfigAudit", schema: configAuditSchema } satisfies ModelDef;

package/templates/app/modules/config/module.acl.ts

@@ -0,0 +1,12 @@
+import type { AclBuilder } from "@tulipes/core/acl";
+
+/**
+ * The console. Reading what the app is configured with is an
+ * administrator's job; changing it is the deployment's, so writes stay
+ * with `sysadmin`. The boundary is real because the auth module never
+ * grants `admin` the `*` wildcard.
+ */
+export default function configAcl(acl: AclBuilder): void {
+  acl.allow("admin", "config:read", "config:describe");
+  acl.allow("sysadmin", "config:*");
+}

package/templates/app/modules/config/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@app/config",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "tulipes": {
+    "tier": "app",
+    "priority": 910,
+    "dependsOn": [
+      "auth",
+      "core"
+    ]
+  },
+  "dependencies": {
+    "@app/auth": "workspace:*",
+    "@app/core": "workspace:*",
+    "@tulipes/core": "workspace:*",
+    "@tulipes/mongoose": "workspace:*",
+    "express": "^5",
+    "mongoose": "^8",
+    "zod": "^3.25"
+  }
+}

package/templates/app/modules/config/routes/config.routes.ts

@@ -0,0 +1,37 @@
+import { Router } from "express";
+import type { BackendCtx } from "@tulipes/core/boot";
+
+import { ConfigController } from "../controllers/config.controllers.ts";
+import { changeBody, moduleParam } from "../schemas/config.schemas.ts";
+
+export default function configRoutes(ctx: BackendCtx): void {
+  const { rai, routes, config } = ctx;
+  const router = Router();
+  const console = new ConfigController(ctx);
+
+  router.get("/", rai({
+      id: "config:read",
+      name: "Describe the app",
+      description: "Every module in load order: manifest, declared variables (names, types, sources; secrets never), settings with schema, live values and stored version, endpoints with the roles that reach them",
+      folder: "config",
+    }), console.app());
+
+  router.get("/:module", rai({
+      id: "config:describe",
+      name: "Describe one module",
+      description: "The same description for one module",
+      folder: "config",
+      params: moduleParam,
+    }), console.module());
+
+  router.patch("/:module", rai({
+      id: "config:write",
+      name: "Change a module's settings",
+      description: "A patch over the stored values, validated by the module's schema; a stale version is refused; applied at once in every replica, except fields tagged restart, which apply on the next boot",
+      folder: "config",
+      params: moduleParam,
+      body: changeBody,
+    }), console.change());
+
+  routes.mount(router, `${config.api!.prefix}/config`);
+}

package/templates/app/modules/config/schemas/config.schemas.ts

@@ -0,0 +1,13 @@
+import { z } from "zod/v4";
+
+/** Validated by rai(), and described in the generated spec and the agent manifest. */
+export const moduleParam = z.object({
+  module: z.string().regex(/^[a-z][a-z0-9-]*$/, "invalidModuleName"),
+});
+
+export const changeBody = z.object({
+  /** A patch over the stored values; the module's own schema validates the result. */
+  values: z.record(z.string(), z.unknown()),
+  /** The version read before editing; a different stored version refuses the write. */
+  version: z.number().int().positive().optional(),
+});

package/templates/app/modules/config/tests/config.test.ts

@@ -0,0 +1,126 @@
+import { randomBytes } from "node:crypto";
+import { fileURLToPath } from "node:url";
+import { z } from "zod/v4";
+import { afterAll, beforeAll, expect, test, vi } from "vitest";
+import { boot } from "@tulipes/core/boot";
+import { useTestApp } from "@tulipes/testing";
+
+import { testEnv, testSettings } from "../../../tests/support.ts";
+
+const rootDir = fileURLToPath(new URL("../../../", import.meta.url));
+const app = useTestApp({ rootDir, env: testEnv(), settings: testSettings() }, { beforeAll, afterAll });
+
+
+const tokens = z.object({
+  data: z.object({ access_token: z.string(), refresh_token: z.string() }),
+});
+
+async function post(path: string, body: unknown, token?: string) {
+  return fetch(app.base + path, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      ...(token ? { authorization: "Bearer " + token } : {}),
+    },
+    body: JSON.stringify(body),
+  });
+}
+
+async function account() {
+  const credentials = {
+    email: randomBytes(12).toString("hex") + "@example.test",
+    password: randomBytes(24).toString("hex"),
+  };
+
+  const response = await post("/api/v1/auth/register", credentials);
+
+  expect(response.status).toBe(201);
+
+  const body = await response.json();
+
+  const { user } = z
+    .object({ data: z.object({ user: z.object({ id: z.string() }) }) })
+    .parse(body).data;
+
+  return { ...tokens.parse(body).data, ...credentials, userId: user.id };
+}
+
+async function get(path: string, token: string) {
+  return fetch(app.base + path, { headers: { authorization: "Bearer " + token } });
+}
+
+async function sysadmin() {
+  const user = await account();
+
+  await app.handle.ctx
+    .models!.get("User")
+    .updateOne({ _id: user.userId }, { role: "sysadmin" });
+
+  return user;
+}
+
+async function patch(path: string, body: unknown, token: string) {
+  return fetch(app.base + path, {
+    method: "PATCH",
+    headers: {
+      "content-type": "application/json",
+      authorization: "Bearer " + token,
+    },
+    body: JSON.stringify(body),
+  });
+}
+
+test("the console describes every module without a secret's value and only administrators read it", async () => {
+  const ordinary = await account();
+  const admin = await account();
+  await app.handle.ctx.models!.get("User").updateOne({ _id: admin.userId }, { role: "admin" });
+
+  expect((await get("/api/v1/config", ordinary.access_token)).status).toBe(403);
+
+  const response = await get("/api/v1/config", admin.access_token);
+  expect(response.status).toBe(200);
+  const { data } = (await response.json()) as { data: { store: { ready: boolean }; modules: Record<string, unknown>[] } };
+  expect(data.store.ready).toBe(true);
+  expect(data.modules.map((module) => module.name)).toEqual(app.handle.ctx.modules.map((module) => module.name));
+
+  const auth = data.modules.find((module) => module.name === "auth") as { variables: Record<string, unknown>[]; settings: { values: Record<string, unknown>; version: number }; routes: Record<string, unknown>[] };
+  const secret = auth.variables.find((variable) => variable.name === "JWT_ACCESS_SECRET")!;
+  expect(secret).toMatchObject({ is_secret: true, is_set: true, value: null, default: null });
+  expect(JSON.stringify(data)).not.toContain(process.env.JWT_ACCESS_SECRET);
+  expect(auth.settings.values).toMatchObject({ accessTtl: "15m" });
+  expect(auth.routes).toContainEqual(expect.objectContaining({ id: "auth:login", method: "POST", roles: expect.arrayContaining(["guest"]) }));
+
+  // The administrator may read; writing is the deployment's job.
+  expect((await patch("/api/v1/config/hello", { values: { greeting: "Nope" } }, admin.access_token)).status).toBe(403);
+});
+
+test("a settings write is validated by the module's schema, refused on a stale version, audited without values and applied at once", async () => {
+  const user = await sysadmin();
+  const described = (await (await get("/api/v1/config/hello", user.access_token)).json()) as { data: { settings: { version: number } } };
+  const before = described.data.settings.version;
+
+  const invalid = await patch("/api/v1/config/hello", { values: { greeting: "" } }, user.access_token);
+  expect(invalid.status).toBe(422);
+  expect(await invalid.json()).toMatchObject({ errors: [{ field: "greeting" }] });
+
+  const stale = await patch("/api/v1/config/hello", { values: { greeting: "Howdy" }, version: before + 7 }, user.access_token);
+  expect(stale.status).toBe(409);
+  expect(await stale.json()).toMatchObject({ errors: [{ code: "STALE_VERSION" }] });
+
+  const written = await patch("/api/v1/config/hello", { values: { greeting: "Howdy" }, version: before }, user.access_token);
+  expect(written.status).toBe(200);
+  expect(await written.json()).toMatchObject({ data: { module: "hello", values: { greeting: "Howdy" }, version: before + 1, requires_restart: [] } });
+
+  // Live in this process, through the same object every handler reads.
+  expect(app.handle.ctx.config.hello).toEqual({ greeting: "Howdy" });
+  const greeted = (await (await fetch(app.base + "/api/v1/hello")).json()) as { data: { message: string } };
+  expect(greeted.data.message).toMatch(/^Howdy/);
+
+  const audit = await app.handle.ctx.models!.get("ConfigAudit").find({ actor: user.userId }).sort({ recorded_at: -1 }).lean();
+  expect(audit[0]).toMatchObject({ action: "settings.change_requested", module: "hello", keys: ["greeting"], version: before, actor_role: "sysadmin" });
+  expect(JSON.stringify(audit)).not.toContain("Howdy");
+
+  expect((await patch("/api/v1/config/nope", { values: {} }, user.access_token)).status).toBe(404);
+
+  await app.handle.ctx.settings.set("hello", { greeting: "Hello" }, { id: "tests" });
+});

package/templates/app/modules/core/bootstrap/cache.bootstrap.ts

@@ -0,0 +1,12 @@
+import type { BootstrapCleanup } from "@tulipes/core/boot";
+
+import { closeCache } from "../helpers/cache/index.ts";
+
+/**
+ * The app cache opens lazily on first use, so there is nothing to open here;
+ * what this bootstrap contributes is the cleanup: the redis driver holds a
+ * connection, and core runs this after traffic drains, in reverse load order.
+ */
+export default function cache(): BootstrapCleanup {
+  return () => closeCache();
+}

package/templates/app/modules/core/helpers/cache/index.ts

@@ -0,0 +1,60 @@
+import { Redis } from "ioredis";
+import type { Environment } from "@tulipes/core/env";
+
+import { MemoryCache } from "./memory-cache.ts";
+import { RedisCache } from "./redis-cache.ts";
+import type { Cache } from "./types.ts";
+
+export type { Cache } from "./types.ts";
+export { BaseCache } from "./types.ts";
+export { MemoryCache } from "./memory-cache.ts";
+export { RedisCache } from "./redis-cache.ts";
+
+let active: { cache: Cache; redis?: Redis } | undefined;
+
+/**
+ * The app's one cache, picked from the environment: redis when REDIS_URL is
+ * declared, in-process memory otherwise (tests, minimal setups). Lazily
+ * created, process-wide singleton.
+ */
+export function appCache(environment: Environment): Cache {
+  if (active) return active.cache;
+
+  if (environment.store.has("REDIS_URL")) {
+    // Fail a command fast instead of queueing it and retrying for seconds: the
+    // cache is consulted on every request, so a redis outage must cost a miss,
+    // not a stalled request. RedisCache turns the rejection into that miss.
+    const redis = new Redis(String(environment.get("REDIS_URL")), {
+      maxRetriesPerRequest: 1,
+      enableOfflineQueue: false,
+    });
+    // ioredis makes an unhandled "error" event an uncaught exception; the cache
+    // reports what it actually affects, when it affects it.
+    redis.on("error", () => {});
+    active = { cache: new RedisCache(redis), redis };
+  } else {
+    active = { cache: new MemoryCache() };
+  }
+  return active.cache;
+}
+
+/**
+ * The cache bootstrap's cleanup: the redis driver holds a connection. QUIT
+ * is the orderly close, but with the offline queue off it is refused on a
+ * client that is not ready — a process stopping while the first connection
+ * is still being made, or during an outage — so that client is dropped.
+ */
+export async function closeCache(): Promise<void> {
+  const redis = active?.redis;
+  active = undefined;
+  if (!redis) return;
+  if (redis.status === "ready") {
+    try {
+      await redis.quit();
+      return;
+    } catch {
+      // fall through: the connection went away between the check and QUIT
+    }
+  }
+  redis.disconnect();
+}

package/templates/app/modules/core/helpers/cache/memory-cache.ts

@@ -0,0 +1,53 @@
+import { BaseCache } from "./types.ts";
+
+interface Entry {
+  value: unknown;
+  /** Epoch ms when this entry expires, or `null` for no expiry. */
+  expiresAt: number | null;
+}
+
+/**
+ * In-process cache backed by a `Map`. For tests and local runs without
+ * Redis — not shared across processes (each worker has its own store).
+ *
+ * Bounded: past `maxEntries` the least-recently-used key is evicted. LRU
+ * order rides on Map insertion order — hits re-insert their key at the tail.
+ */
+export class MemoryCache extends BaseCache {
+  readonly #store = new Map<string, Entry>();
+  readonly #maxEntries: number;
+
+  constructor(maxEntries = 10_000) {
+    super();
+    this.#maxEntries = maxEntries;
+  }
+
+  async get<T>(key: string): Promise<T | null> {
+    const entry = this.#store.get(key);
+    if (!entry) return null;
+    if (entry.expiresAt !== null && entry.expiresAt <= Date.now()) {
+      this.#store.delete(key);
+      return null;
+    }
+    // Refresh recency: delete + re-set moves the key to the Map's tail.
+    this.#store.delete(key);
+    this.#store.set(key, entry);
+    return entry.value as T;
+  }
+
+  async set<T>(key: string, value: T, ttlSeconds?: number): Promise<void> {
+    const expiresAt =
+      ttlSeconds && ttlSeconds > 0 ? Date.now() + ttlSeconds * 1000 : null;
+    this.#store.delete(key);
+    this.#store.set(key, { value, expiresAt });
+
+    while (this.#store.size > this.#maxEntries) {
+      // Oldest key = head of the Map's insertion order.
+      this.#store.delete(this.#store.keys().next().value!);
+    }
+  }
+
+  async del(key: string): Promise<void> {
+    this.#store.delete(key);
+  }
+}

package/templates/app/modules/core/helpers/cache/redis-cache.ts

@@ -0,0 +1,68 @@
+import type { Redis } from "ioredis";
+import { BaseCache } from "./types.ts";
+
+/**
+ * Redis-backed cache. Values are JSON-serialized; keys are namespaced by
+ * `prefix` so cache keys never collide with other Redis users in the same
+ * db (BullMQ especially) and can be cleared without a FLUSHDB.
+ */
+export class RedisCache extends BaseCache {
+  readonly #redis: Redis;
+  readonly #prefix: string;
+
+  constructor(redis: Redis, prefix = "cache:") {
+    super();
+    this.#redis = redis;
+    this.#prefix = prefix;
+  }
+
+  #key(key: string): string {
+    return `${this.#prefix}${key}`;
+  }
+
+  /**
+   * A cache is best effort, and this one sits in global middleware: if a redis
+   * outage threw from here, every endpoint would answer 500 — an outage of the
+   * whole API caused by an optional dependency. Every operation therefore
+   * degrades to "no cache" and says so at most once every 30 seconds.
+   */
+  #reportedAt = 0;
+
+  #degraded(operation: string, error: unknown): void {
+    const now = Date.now();
+    if (now - this.#reportedAt < 30_000) return;
+    this.#reportedAt = now;
+    console.error(`[cache] redis ${operation} failed; serving without cache: ${(error as Error).message}`);
+  }
+
+  async get<T>(key: string): Promise<T | null> {
+    try {
+      const raw = await this.#redis.get(this.#key(key));
+      return raw === null ? null : (JSON.parse(raw) as T);
+    } catch (error) {
+      this.#degraded("get", error);
+      return null;
+    }
+  }
+
+  async set<T>(key: string, value: T, ttlSeconds?: number): Promise<void> {
+    const raw = JSON.stringify(value);
+    try {
+      if (ttlSeconds && ttlSeconds > 0) {
+        await this.#redis.set(this.#key(key), raw, "EX", ttlSeconds);
+      } else {
+        await this.#redis.set(this.#key(key), raw);
+      }
+    } catch (error) {
+      this.#degraded("set", error);
+    }
+  }
+
+  async del(key: string): Promise<void> {
+    try {
+      await this.#redis.del(this.#key(key));
+    } catch (error) {
+      this.#degraded("del", error);
+    }
+  }
+}