@bymax-one/nest-cache 1.1.0 → 1.2.1

package/dist/admin/index.cjs

@@ -0,0 +1,745 @@
+'use strict';
+
+var common = require('@nestjs/common');
+var nestCache = require('@bymax-one/nest-cache');
+
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (decorator(result)) || result;
+  return result;
+};
+var __decorateParam = (index, decorator) => (target, key) => decorator(target, key, index);
+
+// src/admin/bymax-cache-admin.constants.ts
+var BYMAX_CACHE_ADMIN_OPTIONS = /* @__PURE__ */ Symbol("BYMAX_CACHE_ADMIN_OPTIONS");
+var SCOPE_PATTERN_SHAPE = /^[^*?[\\]+\*?$/;
+var REQUIRED_FIELDS = ["id", "label", "pattern", "origin"];
+function readScopePattern(pattern) {
+  const isPrefixMatch = pattern.endsWith("*");
+  return { prefix: isPrefixMatch ? pattern.slice(0, -1) : pattern, isPrefixMatch };
+}
+function isKeyInScope(pattern, key) {
+  const { prefix, isPrefixMatch } = readScopePattern(pattern);
+  return isPrefixMatch ? key.startsWith(prefix) : key === pattern;
+}
+function readField(scope, field) {
+  switch (field) {
+    case "id":
+      return scope.id;
+    case "label":
+      return scope.label;
+    case "pattern":
+      return scope.pattern;
+    default:
+      return scope.origin;
+  }
+}
+function validateScopes(scopes) {
+  if (scopes.length === 0) {
+    throw new nestCache.CacheException(nestCache.CACHE_ERROR_CODES.INVALID_SCOPE, { reason: "no scopes declared" });
+  }
+  const seen = /* @__PURE__ */ new Set();
+  const validated = [];
+  for (const scope of scopes) {
+    for (const field of REQUIRED_FIELDS) {
+      if (readField(scope, field) === "") {
+        throw new nestCache.CacheException(nestCache.CACHE_ERROR_CODES.INVALID_SCOPE, {
+          reason: "empty scope field",
+          field,
+          scopeId: scope.id
+        });
+      }
+    }
+    if (seen.has(scope.id)) {
+      throw new nestCache.CacheException(nestCache.CACHE_ERROR_CODES.INVALID_SCOPE, {
+        reason: "duplicate scope id",
+        scopeId: scope.id
+      });
+    }
+    if (!SCOPE_PATTERN_SHAPE.test(scope.pattern)) {
+      throw new nestCache.CacheException(nestCache.CACHE_ERROR_CODES.INVALID_SCOPE, {
+        reason: "pattern must be a literal prefix optionally followed by *",
+        scopeId: scope.id,
+        pattern: scope.pattern
+      });
+    }
+    seen.add(scope.id);
+    validated.push(
+      Object.freeze({
+        id: scope.id,
+        label: scope.label,
+        pattern: scope.pattern,
+        isReadable: scope.isReadable,
+        origin: scope.origin
+      })
+    );
+  }
+  return Object.freeze(validated);
+}
+function findScope(scopes, id) {
+  const found = scopes.find((scope) => scope.id === id);
+  if (!found) {
+    throw new nestCache.CacheException(nestCache.CACHE_ERROR_CODES.SCOPE_NOT_FOUND, { scopeId: id });
+  }
+  return found;
+}
+
+// src/admin/constants/admin-defaults.ts
+var DEFAULT_DEGRADED_ABOVE_MS = 250;
+var DEFAULT_PROBE_TIMEOUT_MS = 2e3;
+var DEFAULT_SCAN_LIMIT = 500;
+var DEFAULT_COMMAND_BATCH_LIMIT = 100;
+var DEFAULT_REVEAL_LIMIT = 200;
+var DEFAULT_REVEAL_STRING_LIMIT = 4096;
+
+// src/admin/config/resolved-admin-options.ts
+function requirePositiveInteger(option, value) {
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new nestCache.CacheException(nestCache.CACHE_ERROR_CODES.INVALID_SCOPE, {
+      reason: "threshold must be positive",
+      option,
+      value
+    });
+  }
+}
+function resolveAdminOptions(options) {
+  const resolved = {
+    scopes: validateScopes(options.scopes),
+    degradedAboveMs: options.degradedAboveMs ?? DEFAULT_DEGRADED_ABOVE_MS,
+    probeTimeoutMs: options.probeTimeoutMs ?? DEFAULT_PROBE_TIMEOUT_MS,
+    scanLimit: options.scanLimit ?? DEFAULT_SCAN_LIMIT,
+    commandBatchLimit: options.commandBatchLimit ?? DEFAULT_COMMAND_BATCH_LIMIT,
+    revealLimit: options.revealLimit ?? DEFAULT_REVEAL_LIMIT,
+    revealStringLimit: options.revealStringLimit ?? DEFAULT_REVEAL_STRING_LIMIT,
+    isGlobal: options.isGlobal ?? false
+  };
+  requirePositiveInteger("degradedAboveMs", resolved.degradedAboveMs);
+  requirePositiveInteger("probeTimeoutMs", resolved.probeTimeoutMs);
+  requirePositiveInteger("scanLimit", resolved.scanLimit);
+  requirePositiveInteger("commandBatchLimit", resolved.commandBatchLimit);
+  requirePositiveInteger("revealLimit", resolved.revealLimit);
+  requirePositiveInteger("revealStringLimit", resolved.revealStringLimit);
+  return Object.freeze(resolved);
+}
+
+// src/admin/utils/read-replies.ts
+var KNOWN_TYPES = /* @__PURE__ */ new Set([
+  "string",
+  "hash",
+  "set",
+  "list",
+  "zset",
+  "stream"
+]);
+function isKnownType(reply) {
+  return typeof reply === "string" && KNOWN_TYPES.has(reply);
+}
+var TTL_PERSISTENT = -1;
+function readKeyType(reply) {
+  return isKnownType(reply) ? reply : "other";
+}
+function readKeyTtl(reply) {
+  if (typeof reply !== "number" || !Number.isFinite(reply)) {
+    return { kind: "missing" };
+  }
+  if (reply === TTL_PERSISTENT) {
+    return { kind: "persistent" };
+  }
+  if (reply < 0) {
+    return { kind: "missing" };
+  }
+  return { kind: "expiring", seconds: reply };
+}
+function readSizeBytes(reply) {
+  return typeof reply === "number" && Number.isFinite(reply) ? reply : null;
+}
+
+// src/admin/services/cache-admin.service.ts
+var SCAN_END_CURSOR = "0";
+var DESCRIBE_COMMANDS_PER_KEY = 2;
+var SIZING_COMMANDS_PER_KEY = 1;
+var TYPE_NONE = "none";
+function replyAt(replies, index) {
+  const slot = replies?.at(index);
+  if (!slot || slot[0] !== null) {
+    return null;
+  }
+  return slot[1];
+}
+function readScoredMembers(reply, limit) {
+  if (!Array.isArray(reply)) {
+    return { members: [], isComplete: true };
+  }
+  const members = [];
+  let pairCount = 0;
+  let pendingMember = null;
+  for (const element of reply) {
+    if (Array.isArray(element)) {
+      const [member, score] = element;
+      pairCount += 1;
+      if (members.length < limit) {
+        members.push({ member: String(member), score: String(score) });
+      }
+      continue;
+    }
+    if (pendingMember === null) {
+      pendingMember = String(element);
+      continue;
+    }
+    pairCount += 1;
+    if (members.length < limit) {
+      members.push({ member: pendingMember, score: String(element) });
+    }
+    pendingMember = null;
+  }
+  return { members, isComplete: members.length === pairCount };
+}
+exports.CacheAdminService = class CacheAdminService {
+  /**
+   * @param cache - Supplies the client. `CacheService.getClient()` refuses
+   *   cluster mode, so this surface inherits that rule rather than restating it.
+   * @param options - The resolved administration options.
+   */
+  constructor(cache, options) {
+    this.cache = cache;
+    this.options = options;
+  }
+  /**
+   * Returns the declared scopes.
+   *
+   * **Never touches the connection**, and that is a property rather than an
+   * accident of the current implementation. A surface reads this to decide what
+   * it may offer at all, so it must answer during an outage — an operator whose
+   * cache is down is exactly the person who needs to be told what the inspector
+   * covers. The tempting change is a liveness check to make the list "more
+   * accurate"; it would turn a declaration into a measurement, and a scope that
+   * vanished during an outage reads as a scope that was removed.
+   *
+   * @returns The frozen allowlist, in declaration order.
+   */
+  listScopes() {
+    return this.options.scopes;
+  }
+  /**
+   * Lists one page of the keys in a scope.
+   *
+   * The page may carry slightly MORE than `scanLimit` entries: the limit stops
+   * the scan loop, and the batch that crosses it is kept whole rather than
+   * trimmed, because the cursor has already moved past those keys and trimming
+   * would drop them from every subsequent page too.
+   *
+   * @param scopeId - The scope a caller named.
+   * @param listOptions - Cursor and whether to measure sizes.
+   * @returns The page, with the sample it read and whether it reached the end.
+   * @throws {CacheException} `SCOPE_NOT_FOUND` for an undeclared id, or
+   *   `UNSUPPORTED_IN_CLUSTER` in cluster mode.
+   */
+  async listKeys(scopeId, listOptions = {}) {
+    const scope = findScope(this.options.scopes, scopeId);
+    const client = this.cache.getClient();
+    const limit = this.options.scanLimit;
+    const keys = [];
+    let cursor = listOptions.cursor ?? SCAN_END_CURSOR;
+    do {
+      const [nextCursor, batch] = await client.scan(cursor, "MATCH", scope.pattern, "COUNT", limit);
+      cursor = nextCursor;
+      keys.push(...batch);
+    } while (cursor !== SCAN_END_CURSOR && keys.length < limit);
+    const isComplete = cursor === SCAN_END_CURSOR;
+    const includeSize = listOptions.includeSize === true;
+    const entries = await this.describeAll(client, keys, includeSize);
+    return {
+      scopeId: scope.id,
+      entries,
+      sampledCount: entries.length,
+      sampledBytes: includeSize ? sumMeasured(entries) : null,
+      isComplete,
+      scanLimit: limit,
+      cursor: isComplete ? null : cursor
+    };
+  }
+  /**
+   * Describes one key without reading its value.
+   *
+   * Works on an unreadable scope: only the value is withheld, never the
+   * description. {@link KeyDetail.isReadable} lets a surface disable the reveal
+   * rather than discovering the refusal by attempting it.
+   *
+   * @param scopeId - The scope a caller named.
+   * @param key - The key, which must belong to that scope.
+   * @returns The key's type, remaining life, and whether its value may be read.
+   * @throws {CacheException} `SCOPE_NOT_FOUND` or `KEY_NOT_IN_SCOPE`.
+   */
+  async describeKey(scopeId, key) {
+    const scope = this.resolve(scopeId, key);
+    const client = this.cache.getClient();
+    const [type, ttl] = await Promise.all([client.type(key), client.ttl(key)]);
+    return {
+      scopeId: scope.id,
+      key,
+      type: readKeyType(type),
+      ttl: readKeyTtl(ttl),
+      sizeBytes: null,
+      isReadable: scope.isReadable
+    };
+  }
+  /**
+   * Reads a key's value, or explains why it will not.
+   *
+   * @param scopeId - The scope a caller named.
+   * @param key - The key, which must belong to that scope.
+   * @returns The value, a refusal carrying the scope's `origin`, or `missing`.
+   * @throws {CacheException} `SCOPE_NOT_FOUND` or `KEY_NOT_IN_SCOPE`.
+   */
+  async revealValue(scopeId, key) {
+    const scope = this.resolve(scopeId, key);
+    if (!scope.isReadable) {
+      return { status: "withheld", key, scopeId: scope.id, origin: scope.origin };
+    }
+    const client = this.cache.getClient();
+    const rawType = await client.type(key);
+    if (rawType === TYPE_NONE) {
+      return { status: "missing", key };
+    }
+    const type = readKeyType(rawType);
+    const value = await this.readValue(client, key, type);
+    return value === null ? { status: "missing", key } : { status: "revealed", key, type, value };
+  }
+  /**
+   * Resolves a scope and confirms the key belongs to it.
+   *
+   * The membership check is the reason scope patterns are restricted to a
+   * literal prefix: it makes this decidable exactly, rather than by a matcher
+   * that could be more permissive than the server's.
+   *
+   * @param scopeId - The scope a caller named.
+   * @param key - The key a caller named.
+   * @returns The resolved scope.
+   * @throws {CacheException} `SCOPE_NOT_FOUND` or `KEY_NOT_IN_SCOPE`.
+   */
+  resolve(scopeId, key) {
+    const scope = findScope(this.options.scopes, scopeId);
+    if (!isKeyInScope(scope.pattern, key)) {
+      throw new nestCache.CacheException(nestCache.CACHE_ERROR_CODES.KEY_NOT_IN_SCOPE, { scopeId: scope.id, key });
+    }
+    return scope;
+  }
+  /**
+   * Describes every key on a page, in batches bounded by command count.
+   *
+   * The bound is in commands rather than keys because that is the resource
+   * actually spent: describing a key costs two commands, or three when sized,
+   * and Redis works through a flush single-threaded while every other client
+   * waits. At least one key goes per batch, so a limit below one key's cost
+   * still makes progress instead of dividing to nothing.
+   *
+   * @param client - The reader.
+   * @param keys - The page's keys.
+   * @param includeSize - Whether to add `MEMORY USAGE`.
+   * @returns One entry per key, in page order.
+   */
+  async describeAll(client, keys, includeSize) {
+    const perKey = DESCRIBE_COMMANDS_PER_KEY + (includeSize ? SIZING_COMMANDS_PER_KEY : 0);
+    const chunkSize = Math.max(1, Math.floor(this.options.commandBatchLimit / perKey));
+    const entries = [];
+    for (let start = 0; start < keys.length; start += chunkSize) {
+      const chunk = keys.slice(start, start + chunkSize);
+      const pipeline = client.pipeline();
+      for (const key of chunk) {
+        pipeline.type(key).ttl(key);
+        if (includeSize) {
+          pipeline.memory("USAGE", key);
+        }
+      }
+      const replies = await pipeline.exec();
+      chunk.forEach((key, index) => {
+        const base = index * perKey;
+        entries.push({
+          key,
+          type: readKeyType(replyAt(replies, base)),
+          ttl: readKeyTtl(replyAt(replies, base + 1)),
+          sizeBytes: includeSize ? readSizeBytes(replyAt(replies, base + 2)) : null
+        });
+      });
+    }
+    return entries;
+  }
+  /**
+   * Reads a value according to its Redis type, truncating to the configured caps.
+   *
+   * @param client - The reader.
+   * @param key - The key to read.
+   * @param type - The key's type.
+   * @returns The value, or `null` when the key vanished between reads.
+   */
+  async readValue(client, key, type) {
+    const limit = this.options.revealLimit;
+    switch (type) {
+      case "string": {
+        const value = await client.get(key);
+        if (value === null) {
+          return null;
+        }
+        const capped = value.slice(0, this.options.revealStringLimit);
+        return { kind: "string", value: capped, isComplete: capped.length === value.length };
+      }
+      case "hash": {
+        const all = Object.entries(await client.hgetall(key));
+        const kept = all.slice(0, limit);
+        return {
+          kind: "hash",
+          // `field`, not `name`: Redis's own vocabulary for a hash is field/value
+          // (`HSET key field value`, `HDEL key field`). A generic `name` loses the
+          // domain term in the one place a reader would check it against the
+          // server's documentation.
+          fields: kept.map(([field, value]) => ({ field, value })),
+          isComplete: kept.length === all.length
+        };
+      }
+      case "set":
+      case "list": {
+        const all = type === "set" ? await client.smembers(key) : await client.lrange(key, 0, limit);
+        const kept = all.slice(0, limit);
+        return { kind: "members", members: kept, isComplete: kept.length === all.length };
+      }
+      case "zset": {
+        const reply = await client.call("ZRANGE", key, 0, limit, "WITHSCORES");
+        const { members, isComplete } = readScoredMembers(reply, limit);
+        return { kind: "scored", members, isComplete };
+      }
+      default:
+        return { kind: "unsupported", type };
+    }
+  }
+};
+exports.CacheAdminService = __decorateClass([
+  common.Injectable(),
+  __decorateParam(0, common.Inject(nestCache.CacheService)),
+  __decorateParam(1, common.Inject(BYMAX_CACHE_ADMIN_OPTIONS))
+], exports.CacheAdminService);
+function sumMeasured(entries) {
+  return entries.reduce((total, entry) => total + (entry.sizeBytes ?? 0), 0);
+}
+
+// src/admin/utils/parse-info.ts
+var FIELD_SEPARATOR = ":";
+var SECTION_PREFIX = "#";
+var UNBOUNDED_MAXMEMORY = 0;
+var MS_PER_SECOND = 1e3;
+var BGSAVE_OK = "ok";
+var BGSAVE_ERROR = "err";
+var INFO_TRUE = "1";
+var WIRE_REPLICA_ROLE = "slave";
+var NUMERIC_VALUE = /^[+-]?\d+(\.\d+)?([eE][+-]?\d+)?$/;
+function parseInfoFields(text2) {
+  const fields = /* @__PURE__ */ new Map();
+  for (const rawLine of text2.split("\n")) {
+    const line = rawLine.trim();
+    if (line.startsWith(SECTION_PREFIX)) {
+      continue;
+    }
+    const cut = line.indexOf(FIELD_SEPARATOR);
+    if (cut <= 0) {
+      continue;
+    }
+    fields.set(line.slice(0, cut), line.slice(cut + 1));
+  }
+  return fields;
+}
+function text(fields, name) {
+  return fields.get(name) ?? null;
+}
+function num(fields, name) {
+  const raw = fields.get(name)?.trim();
+  if (raw === void 0 || !NUMERIC_VALUE.test(raw)) {
+    return null;
+  }
+  const value = Number(raw);
+  return Number.isFinite(value) ? value : null;
+}
+function maxMemory(fields) {
+  const value = num(fields, "maxmemory");
+  if (value === null) {
+    return { kind: "unreported" };
+  }
+  return value === UNBOUNDED_MAXMEMORY ? { kind: "unbounded" } : { kind: "limited", bytes: value };
+}
+function lastSaveAt(fields) {
+  const seconds = num(fields, "rdb_last_save_time");
+  return seconds === null ? null : new Date(seconds * MS_PER_SECOND).toISOString();
+}
+function bgsaveStatus(fields) {
+  const raw = text(fields, "rdb_last_bgsave_status");
+  if (raw === BGSAVE_OK) {
+    return BGSAVE_OK;
+  }
+  return raw === BGSAVE_ERROR ? BGSAVE_ERROR : null;
+}
+function aofEnabled(fields) {
+  const raw = text(fields, "aof_enabled");
+  return raw === null ? null : raw === INFO_TRUE;
+}
+function role(fields) {
+  return text(fields, "role") === WIRE_REPLICA_ROLE ? "replica" : "master";
+}
+function readRedisStats(infoText, readAt) {
+  const fields = parseInfoFields(infoText);
+  return {
+    readAt: readAt.toISOString(),
+    server: {
+      redisVersion: text(fields, "redis_version"),
+      mode: text(fields, "redis_mode"),
+      uptimeSeconds: num(fields, "uptime_in_seconds")
+    },
+    clients: {
+      connected: num(fields, "connected_clients"),
+      blocked: num(fields, "blocked_clients")
+    },
+    memory: {
+      usedBytes: num(fields, "used_memory"),
+      peakBytes: num(fields, "used_memory_peak"),
+      max: maxMemory(fields),
+      fragmentationRatio: num(fields, "mem_fragmentation_ratio"),
+      evictionPolicy: text(fields, "maxmemory_policy")
+    },
+    stats: {
+      keyspaceHits: num(fields, "keyspace_hits"),
+      keyspaceMisses: num(fields, "keyspace_misses"),
+      expiredKeys: num(fields, "expired_keys"),
+      evictedKeys: num(fields, "evicted_keys"),
+      instantaneousOpsPerSec: num(fields, "instantaneous_ops_per_sec"),
+      totalCommandsProcessed: num(fields, "total_commands_processed"),
+      totalConnectionsReceived: num(fields, "total_connections_received"),
+      rejectedConnections: num(fields, "rejected_connections")
+    },
+    persistence: {
+      rdbLastSaveAt: lastSaveAt(fields),
+      rdbChangesSinceLastSave: num(fields, "rdb_changes_since_last_save"),
+      rdbLastBgsaveStatus: bgsaveStatus(fields),
+      aofEnabled: aofEnabled(fields)
+    },
+    replication: {
+      role: role(fields),
+      connectedReplicas: num(fields, "connected_slaves")
+    }
+  };
+}
+
+// src/admin/services/cache-status.service.ts
+var PONG = "PONG";
+var SCAN_UNSUPPORTED_MODE = "cluster";
+var TLS_PROTOCOL = "rediss:";
+var PROBE_TIMEOUT = /* @__PURE__ */ Symbol("probe-timeout");
+async function raceDeadline(work, timeoutMs) {
+  let timer;
+  const deadline = new Promise((resolve) => {
+    timer = setTimeout(() => {
+      resolve(PROBE_TIMEOUT);
+    }, timeoutMs);
+  });
+  try {
+    return await Promise.race([work, deadline]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+function readErrorCode(error) {
+  if (typeof error !== "object" || error === null) {
+    return null;
+  }
+  const code = Reflect.get(error, "code");
+  return typeof code === "string" ? code : null;
+}
+function readEndpoint(options) {
+  const withheld = { host: null, port: null, isTls: false };
+  if (options.mode !== "standalone") {
+    return withheld;
+  }
+  const connection = options.connection;
+  if (!connection) {
+    return withheld;
+  }
+  if (connection.url !== void 0) {
+    try {
+      const parsed = new URL(connection.url);
+      return {
+        // No empty-host branch: a `redis:`/`rediss:` URL without a host is a
+        // parse error (measured — `new URL('redis://:6379')` throws), so it is
+        // caught below rather than reaching here as a blank hostname.
+        host: parsed.hostname,
+        // A URL that names no port still connects, on the default — reporting
+        // null here would hide the endpoint rather than describe it.
+        port: parsed.port === "" ? nestCache.DEFAULT_REDIS_PORT : Number.parseInt(parsed.port, 10),
+        isTls: parsed.protocol === TLS_PROTOCOL
+      };
+    } catch {
+      return withheld;
+    }
+  }
+  return {
+    host: connection.host ?? null,
+    port: connection.port ?? null,
+    isTls: connection.tls !== void 0
+  };
+}
+exports.CacheStatusService = class CacheStatusService {
+  /**
+   * @param cache - The cache facade this service probes through.
+   * @param options - The resolved cache module options.
+   * @param adminOptions - The resolved administration options.
+   * @param serializer - The wired serializer, named on the config payload.
+   */
+  constructor(cache, options, adminOptions, serializer) {
+    this.cache = cache;
+    this.options = options;
+    this.adminOptions = adminOptions;
+    this.serializer = serializer;
+  }
+  /**
+   * Pings Redis and reports the result in three states.
+   *
+   * @returns The probe outcome, plus the mode facts that hold whether or not it
+   *   answered.
+   */
+  async health() {
+    return {
+      ...await this.probe(),
+      mode: this.options.mode,
+      isScanSupported: this.options.mode !== SCAN_UNSUPPORTED_MODE,
+      degradedAboveMs: this.adminOptions.degradedAboveMs
+    };
+  }
+  /**
+   * Reads Redis `INFO` into a typed reading.
+   *
+   * @returns The parsed statistics, stamped with the reading host's clock.
+   */
+  async stats() {
+    return readRedisStats(await this.cache.info(), /* @__PURE__ */ new Date());
+  }
+  /**
+   * Reports how this deployment is wired, with every credential withheld.
+   *
+   * @returns The resolved configuration, safe to serve to an operator surface.
+   */
+  config() {
+    return {
+      mode: this.options.mode,
+      namespace: this.options.namespace,
+      keySeparator: this.options.keySeparator,
+      shutdownTimeoutMs: this.options.shutdownTimeoutMs,
+      isFlushAllowedInProduction: this.options.allowFlushInProduction,
+      serializer: this.serializer.constructor.name,
+      // Names only. A Lua body is deployment logic and has no business on an
+      // operator-facing payload.
+      scripts: (this.options.scripts ?? []).map((script) => script.name),
+      connection: readEndpoint(this.options)
+    };
+  }
+  /**
+   * Measures one `PING`.
+   *
+   * `latencyMs` is produced on exactly one path — a reply that arrived. Every
+   * other outcome returns the `down` branch, which has no latency field to fill
+   * in, so a confident status without a measurement cannot be constructed here.
+   *
+   * @returns The probe outcome.
+   */
+  async probe() {
+    const started = performance.now();
+    let reply;
+    try {
+      reply = await raceDeadline(this.cache.ping(), this.adminOptions.probeTimeoutMs);
+    } catch (error) {
+      return { status: "down", reason: "error", code: readErrorCode(error) };
+    }
+    if (reply === PROBE_TIMEOUT) {
+      return { status: "down", reason: "timeout", code: null };
+    }
+    if (reply !== PONG) {
+      return { status: "down", reason: "error", code: null };
+    }
+    const latencyMs = Math.round(performance.now() - started);
+    return latencyMs > this.adminOptions.degradedAboveMs ? { status: "degraded", latencyMs } : { status: "up", latencyMs };
+  }
+};
+exports.CacheStatusService = __decorateClass([
+  common.Injectable(),
+  __decorateParam(0, common.Inject(nestCache.CacheService)),
+  __decorateParam(1, common.Inject(nestCache.BYMAX_CACHE_OPTIONS)),
+  __decorateParam(2, common.Inject(BYMAX_CACHE_ADMIN_OPTIONS)),
+  __decorateParam(3, common.Inject(nestCache.BYMAX_CACHE_SERIALIZER))
+], exports.CacheStatusService);
+
+// src/admin/bymax-cache-admin.module.ts
+var ADMIN_SERVICES = [exports.CacheStatusService, exports.CacheAdminService];
+exports.BymaxCacheAdminModule = class BymaxCacheAdminModule {
+  /**
+   * Registers the administration surface with statically known options.
+   *
+   * Options are validated here, at wiring — a malformed scope or a non-positive
+   * threshold fails the boot rather than the first request.
+   *
+   * @param options - The scopes this deployment exposes, plus any thresholds.
+   * @returns The dynamic module.
+   * @throws {CacheException} `INVALID_SCOPE` when the declaration is malformed.
+   */
+  static forRoot(options) {
+    const resolved = resolveAdminOptions(options);
+    return {
+      module: exports.BymaxCacheAdminModule,
+      global: resolved.isGlobal,
+      providers: [{ provide: BYMAX_CACHE_ADMIN_OPTIONS, useValue: resolved }, ...ADMIN_SERVICES],
+      exports: [BYMAX_CACHE_ADMIN_OPTIONS, ...ADMIN_SERVICES]
+    };
+  }
+  /**
+   * Registers the administration surface with options built asynchronously.
+   *
+   * Validation runs inside the factory, so the same rules apply on both paths
+   * and neither can drift into accepting what the other rejects.
+   *
+   * @param options - Factory wiring plus the synchronous `isGlobal` flag.
+   * @returns The dynamic module.
+   */
+  static forRootAsync(options) {
+    return {
+      module: exports.BymaxCacheAdminModule,
+      global: options.isGlobal ?? false,
+      imports: options.imports ?? [],
+      providers: [
+        {
+          provide: BYMAX_CACHE_ADMIN_OPTIONS,
+          inject: options.inject ?? [],
+          useFactory: async (...args) => resolveAdminOptions(await options.useFactory(...args))
+        },
+        ...ADMIN_SERVICES
+      ],
+      exports: [BYMAX_CACHE_ADMIN_OPTIONS, ...ADMIN_SERVICES]
+    };
+  }
+};
+exports.BymaxCacheAdminModule = __decorateClass([
+  common.Module({})
+], exports.BymaxCacheAdminModule);
+
+exports.BYMAX_CACHE_ADMIN_OPTIONS = BYMAX_CACHE_ADMIN_OPTIONS;
+exports.DEFAULT_COMMAND_BATCH_LIMIT = DEFAULT_COMMAND_BATCH_LIMIT;
+exports.DEFAULT_DEGRADED_ABOVE_MS = DEFAULT_DEGRADED_ABOVE_MS;
+exports.DEFAULT_PROBE_TIMEOUT_MS = DEFAULT_PROBE_TIMEOUT_MS;
+exports.DEFAULT_REVEAL_LIMIT = DEFAULT_REVEAL_LIMIT;
+exports.DEFAULT_REVEAL_STRING_LIMIT = DEFAULT_REVEAL_STRING_LIMIT;
+exports.DEFAULT_SCAN_LIMIT = DEFAULT_SCAN_LIMIT;
+exports.findScope = findScope;
+exports.isKeyInScope = isKeyInScope;
+exports.parseInfoFields = parseInfoFields;
+exports.readKeyTtl = readKeyTtl;
+exports.readKeyType = readKeyType;
+exports.readRedisStats = readRedisStats;
+exports.readScopePattern = readScopePattern;
+exports.readSizeBytes = readSizeBytes;
+exports.resolveAdminOptions = resolveAdminOptions;
+exports.validateScopes = validateScopes;