@endora-commerce/platform 0.100.0

package/dist/kernel/settings/settings-cache.js

@@ -0,0 +1,253 @@
+import { SharedDropMarks } from '../cache/shared-drop-marks.js';
+/**
+ * Read-through cache for `SettingsService.get` — feature 004 / US3 (T050).
+ *
+ * Two layers, in this order on read:
+ *   1. Per-process LRU (cheap; absorbs intra-request bursts).
+ *   2. Redis (`settings:v1:<code>:<channelId>`, TTL 1h; survives restarts).
+ *
+ * Invalidation goes the other way: write → drop in Redis → drop in LRU. The
+ * write seam calls {@link SettingsCacheInvalidation} itself and awaits it
+ * (issue #45); until then the drop rode an EventBus notification, which made it
+ * a function of *which handler the bus reached first*.
+ *
+ * Dropping the shared layer first is deliberate: it is the layer that outlives
+ * this process and would otherwise be re-pulled into every other process's
+ * LRU. Dropping it is also the step that can fail (network, closed
+ * connection), and a half-done invalidation must degrade to "slower but
+ * correct", never to "fast and wrong". {@link SharedDropMarks} holds the two
+ * guards that enforce it.
+ *
+ * **The local layer expires.** The EventBus is in-process (`events/bus.ts`),
+ * so a second API instance learns about a write only through the shared layer:
+ * invalidation is, across processes, a broadcast that can be missed. Redis
+ * expires its entries after an hour; without {@link SETTINGS_LRU_TTL_MS} the
+ * LRU expired nothing and was bounded only by its capacity, so a process that
+ * missed a notification served the pre-write value indefinitely — the one case
+ * the operator's "clear cache" button cannot fix, because clearing rides the
+ * same in-process path that already failed. The window is on the value's age,
+ * never refreshed by a read: a setting read on every request is exactly the
+ * entry a sliding window would pin forever.
+ *
+ * Stored values are JSON-serialised so structured types (objects, arrays)
+ * survive the Redis hop. The `null` sentinel is never stored — absence of a
+ * key means "cache miss"; falsy values like `false`, `0`, `""` are valid.
+ */
+/** Shared with the operator-facing cache-clear surface, so the two cannot drift. */
+export const SETTINGS_CACHE_KEY_PREFIX = 'settings:v1:';
+export const SETTINGS_CACHE_NAMESPACE = 'settings';
+/**
+ * Maximum age of an entry in the per-process layer.
+ *
+ * 30 s is chosen from both ends. The layer exists to remove the Redis hop from
+ * a path read several times per request, and a request burst — a page load, a
+ * checkout step, a worker's batch — lives well inside 30 s, so the hit rate
+ * that justifies the layer is untouched; a 5 s window (what `custom_fields`
+ * uses for a far colder key space) would put a Redis round trip back on the
+ * hot path many times a second. At the other end, 30 s is a bound an operator
+ * experiences as "reload the page and it is right" rather than as a defect,
+ * and it is two orders of magnitude below the hour Redis keeps its own copy —
+ * which is what makes the self-healing real rather than theoretical.
+ */
+export const SETTINGS_LRU_TTL_MS = 30_000;
+const KEY_PREFIX = SETTINGS_CACHE_KEY_PREFIX;
+/**
+ * The channel segment of a **platform-wide** read's key (feature 072, D-41).
+ * A uuid can never spell it, so it cannot collide with a real channel; using
+ * the nil UUID here would have re-introduced the ambiguity the null read exists
+ * to remove. `invalidate(code)` drops by the `<prefix><code>:` prefix, so this
+ * segment needs no invalidator of its own.
+ */
+const GLOBAL_KEY_SEGMENT = '__global__';
+const TTL_SECONDS = 60 * 60;
+const LRU_MAX = 1024;
+const NOT_REGISTERED = '__settings_not_registered__';
+export class SettingsCache {
+    redis;
+    now;
+    lru = new Map();
+    marks = new SharedDropMarks();
+    constructor(redis, 
+    /** Injectable so a test can advance the TTL window without a real clock. */
+    now = () => Date.now()) {
+        this.redis = redis;
+        this.now = now;
+    }
+    static composeKey(code, channelId) {
+        return `${KEY_PREFIX}${code}:${channelId ?? GLOBAL_KEY_SEGMENT}`;
+    }
+    /**
+     * Returns:
+     *   - { hit: true; value: unknown } when the value (or "not registered" sentinel) is cached
+     *   - { hit: false } when the caller must fall through to Postgres
+     * The "not registered" sentinel is encoded as `{ __settings_not_registered__: true }`.
+     */
+    async get(code, channelId) {
+        const key = SettingsCache.composeKey(code, channelId);
+        if (await this.isBypassed(key))
+            return { hit: false };
+        const entry = this.lru.get(key);
+        if (entry !== undefined) {
+            if (this.now() - entry.storedAt < SETTINGS_LRU_TTL_MS) {
+                // Touch the LRU for eviction order — but not `storedAt`: the bound is
+                // on the value's age, and a hot key must still age out.
+                this.lru.delete(key);
+                this.lru.set(key, entry);
+                if (this.isNotRegisteredSentinel(entry.value)) {
+                    return { hit: true, value: undefined, notRegistered: true };
+                }
+                return { hit: true, value: entry.value };
+            }
+            this.lru.delete(key);
+        }
+        const raw = await this.redis.get(key);
+        if (raw === null)
+            return { hit: false };
+        const decoded = JSON.parse(raw);
+        this.touchLru(key, decoded);
+        if (this.isNotRegisteredSentinel(decoded)) {
+            return { hit: true, value: undefined, notRegistered: true };
+        }
+        return { hit: true, value: decoded };
+    }
+    async set(code, channelId, value) {
+        const key = SettingsCache.composeKey(code, channelId);
+        // A read that started before the write resolved the pre-invalidation value
+        // from Postgres. Caching it now would undo the invalidation in flight.
+        if (await this.isBypassed(key))
+            return;
+        this.touchLru(key, value);
+        await this.redis.set(key, JSON.stringify(value), 'EX', TTL_SECONDS);
+    }
+    /** Cache the "not registered" outcome so repeated typos don't hammer Postgres. */
+    async setNotRegistered(code, channelId) {
+        const key = SettingsCache.composeKey(code, channelId);
+        if (await this.isBypassed(key))
+            return;
+        const sentinel = { [NOT_REGISTERED]: true };
+        this.touchLru(key, sentinel);
+        await this.redis.set(key, JSON.stringify(sentinel), 'EX', TTL_SECONDS);
+    }
+    /**
+     * Drop every cached entry for a given setting code (across every channel).
+     * Returns how many shared keys were deleted.
+     */
+    async invalidate(code) {
+        return this.drop(`${KEY_PREFIX}${code}:`, 200);
+    }
+    /**
+     * Used after group-level changes that may affect many codes, and by the
+     * operator-facing cache clear. Returns how many shared keys were deleted.
+     */
+    async invalidateAll() {
+        return this.drop(KEY_PREFIX, 500);
+    }
+    /** {@inheritDoc SettingsCacheInvalidation.invalidateAfterWrite} */
+    async invalidateAfterWrite(code) {
+        return this.afterWrite(() => this.invalidate(code));
+    }
+    /** {@inheritDoc SettingsCacheInvalidation.invalidateAllAfterWrite} */
+    async invalidateAllAfterWrite() {
+        return this.afterWrite(() => this.invalidateAll());
+    }
+    /**
+     * The one place the write seam's tolerance is written down.
+     *
+     * `drop` has already marked the prefix failed by the time it re-throws, so
+     * every read in this process bypasses both layers for those keys and retries
+     * the drop until Redis answers — the invariant is intact and the answer is
+     * "slower but correct". What is left of the throw is a report, and a report
+     * must not undo the write that produced it.
+     */
+    async afterWrite(drop) {
+        try {
+            return await drop();
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Drop both layers for a key prefix, shared layer first. The prefix is
+     * marked for the whole operation so concurrent reads and writes cannot
+     * observe or restore the pre-invalidation state; the mark is only released
+     * once the shared layer is known to be clean.
+     */
+    async drop(prefix, scanCount) {
+        this.marks.begin(prefix);
+        try {
+            const deleted = await this.dropShared(prefix, scanCount);
+            this.marks.retireFailedUnder(prefix);
+            return deleted;
+        }
+        catch (err) {
+            // Fail closed: Redis may still serve the pre-invalidation value to this
+            // process, so keep reads off the cache until a later drop succeeds.
+            this.marks.markFailed(prefix);
+            throw err;
+        }
+        finally {
+            this.dropLocal(prefix);
+            this.marks.finish(prefix);
+        }
+    }
+    /** SCAN + DEL, to avoid blocking on KEYS in production-sized databases. */
+    async dropShared(prefix, scanCount) {
+        let cursor = '0';
+        let deleted = 0;
+        do {
+            const [next, keys] = await this.redis.scan(cursor, 'MATCH', `${prefix}*`, 'COUNT', scanCount);
+            cursor = next;
+            if (keys.length > 0) {
+                deleted += await this.redis.del(...keys);
+            }
+        } while (cursor !== '0');
+        return deleted;
+    }
+    dropLocal(prefix) {
+        for (const k of this.lru.keys()) {
+            if (k.startsWith(prefix))
+                this.lru.delete(k);
+        }
+    }
+    /**
+     * True when neither layer may be trusted for this key: a drop is in flight,
+     * or an earlier drop failed and Redis was never cleaned. In the failed case
+     * the drop is retried here, so a transient outage costs the affected codes
+     * their caching until Redis answers again — not for the process lifetime.
+     */
+    async isBypassed(key) {
+        if (this.marks.isClean)
+            return false;
+        if (this.marks.isDraining(key))
+            return true;
+        const failed = this.marks.failedPrefixFor(key);
+        if (failed === undefined)
+            return false;
+        try {
+            await this.drop(failed, 200);
+        }
+        catch {
+            // Still unreachable — stay off the cache and read through to Postgres.
+        }
+        return true;
+    }
+    touchLru(key, value) {
+        if (this.lru.has(key))
+            this.lru.delete(key);
+        this.lru.set(key, { value, storedAt: this.now() });
+        while (this.lru.size > LRU_MAX) {
+            const oldest = this.lru.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.lru.delete(oldest);
+        }
+    }
+    isNotRegisteredSentinel(v) {
+        return (typeof v === 'object' &&
+            v !== null &&
+            Object.prototype.hasOwnProperty.call(v, NOT_REGISTERED) &&
+            v[NOT_REGISTERED] === true);
+    }
+}
+//# sourceMappingURL=settings-cache.js.map

package/dist/kernel/settings/settings-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings-cache.js","sourceRoot":"","sources":["../../../src/kernel/settings/settings-cache.ts"],"names":[],"mappings":"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"}

package/dist/kernel/settings/settings.service.d.ts

@@ -0,0 +1,142 @@
+import type { EntityManager } from '@mikro-orm/postgresql';
+import type { z } from 'zod';
+import type { SettingsCache } from './settings-cache.js';
+/**
+ * SettingsService — the universal getter (US3 / T049).
+ *
+ * The single read mechanism every other module uses to retrieve a setting's
+ * value. A read either **names a real sales channel** or says it has **none**;
+ * nothing in between is spellable (feature 072, D-41).
+ *
+ * Resolution order for a channel-scoped read (`salesChannelId` is a uuid):
+ *
+ *   0. Channel-id shape check; a non-uuid → throw {@link SettingsChannelIdInvalid}.
+ *   1. Cache hit (read-through Redis + per-process LRU).
+ *   2. Setting lookup by code; absent → throw {@link SettingNotRegistered}.
+ *   3. Scope check; the channel must be in the setting's `salesChannels`
+ *      collection (or the collection must be empty = "all channels").
+ *      Otherwise → throw {@link SettingOutOfScopeForChannel}.
+ *   4. Per-channel `setting_values` row → return its `value`.
+ *   5. Else → `setting.globalValue`, else `setting.defaultValue`.
+ *
+ * For a **platform-wide** read (`salesChannelId === null`) step 4 is skipped:
+ * the answer is `globalValue ?? defaultValue`, the tier the admin service has
+ * always written ("Platform-wide global override") and `resolveEffectiveValue`
+ * has always resolved, but which had no read API. Three modules independently
+ * invented the nil UUID as its spelling and a fourth inlined it — it worked by
+ * accident, being well-formed enough for Postgres and matching no row. A
+ * setting scoped to a *subset* of channels has no platform-wide answer, so it
+ * throws {@link SettingOutOfScopeForChannel} with a `null` channel.
+ *
+ * No schema change: `setting_values.sales_channel_id` stays `uuid NOT NULL`.
+ * The null lives in the read signature, not in a column.
+ *
+ * The optional caller-supplied schema is validated AFTER the resolved value
+ * is materialised; mismatches surface as {@link SettingValueShapeMismatch}.
+ */
+export declare class SettingNotRegistered extends Error {
+    readonly settingCode: string;
+    readonly name = "SettingNotRegistered";
+    readonly code: "SETTING_NOT_REGISTERED";
+    constructor(settingCode: string);
+}
+export declare class SettingOutOfScopeForChannel extends Error {
+    readonly settingCode: string;
+    /** `null` = the read was platform-wide, and this setting is not. */
+    readonly salesChannelId: string | null;
+    readonly name = "SettingOutOfScopeForChannel";
+    readonly code: "SETTING_OUT_OF_SCOPE_FOR_CHANNEL";
+    constructor(settingCode: string, 
+    /** `null` = the read was platform-wide, and this setting is not. */
+    salesChannelId: string | null);
+}
+/**
+ * The caller passed something that is not a sales-channel id (feature 072,
+ * D-42 layer 3).
+ *
+ * `setting_values.sales_channel_id` is `uuid`, so a channel **code**, an empty
+ * string or any other id-shaped string cannot address a row: PostgreSQL rejects
+ * the comparison outright. Before this guard the failure surfaced as a driver
+ * error naming a column, which every caller's `catch` read as "not configured
+ * yet" — that is the whole of the defect family this error exists to end.
+ *
+ * Thrown **before** the `EntityManager` is touched, and deliberately outside
+ * the set of errors a settings read may absorb (D-43): a malformed channel id
+ * is a code defect, not a missing value. "No channel" is spelled `null`.
+ */
+export declare class SettingsChannelIdInvalid extends Error {
+    readonly settingCode: string;
+    readonly salesChannelId: string;
+    readonly name = "SettingsChannelIdInvalid";
+    readonly code: "SETTINGS_CHANNEL_ID_INVALID";
+    constructor(settingCode: string, salesChannelId: string);
+}
+export declare class SettingValueShapeMismatch extends Error {
+    readonly settingCode: string;
+    readonly issues: unknown;
+    readonly name = "SettingValueShapeMismatch";
+    readonly code: "SETTING_VALUE_SHAPE_MISMATCH";
+    constructor(settingCode: string, issues: unknown);
+}
+export type SettingsReadResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: 'not_registered' | 'out_of_scope' | 'shape_mismatch';
+    details?: unknown;
+};
+export declare class SettingsService {
+    private readonly emFactory;
+    private readonly cache?;
+    /**
+     * Base64 32-byte key for the `secret` value type (feature 043). The
+     * cache stores ciphertext envelopes; decryption happens per read in this
+     * process so plaintext never sits in Redis.
+     */
+    private readonly secretEncryptionKey?;
+    constructor(emFactory: () => EntityManager, cache?: SettingsCache | undefined, 
+    /**
+     * Base64 32-byte key for the `secret` value type (feature 043). The
+     * cache stores ciphertext envelopes; decryption happens per read in this
+     * process so plaintext never sits in Redis.
+     */
+    secretEncryptionKey?: string | undefined);
+    get<T>(code: string, salesChannelId: string | null, schema: z.ZodType<T>): Promise<T>;
+    /**
+     * Batch read. Every code is resolved independently; per-code errors are
+     * returned as `{ ok: false, error: ... }` instead of throwing, so a single
+     * missing code does not poison the whole batch.
+     */
+    getMany(codes: string[], salesChannelId: string | null): Promise<Map<string, SettingsReadResult<unknown>>>;
+    /** Raw-read variant used by `getMany` — no caller schema, returns `unknown`. */
+    private getRaw;
+    /**
+     * The seam guard (D-42 layer 3). Runs before the cache and before the
+     * `EntityManager`, so a caller learns it passed a non-id rather than the
+     * driver reporting a column it has never heard of.
+     */
+    private assertChannelId;
+    private validate;
+    /**
+     * Secret settings (feature 043) resolve to a ciphertext envelope; backend
+     * consumers receive the plaintext. Non-envelope values (every other value
+     * type, plus legacy plaintext secrets) pass through untouched.
+     */
+    private maybeDecrypt;
+    /**
+     * Feature 058 (US2) — delete-integrity lookup for the credentials module.
+     *
+     * Returns every `credential_ref` setting whose resolved value (global
+     * override OR a per-channel `SettingValue`) equals `configurationCode`. The
+     * credentials module calls this through its port interface (Principle I)
+     * before deleting a configuration; a non-empty result blocks the delete
+     * (`CREDENTIAL_IN_USE`, FR-012). The manifest `defaultValue` is intentionally
+     * ignored — a manifest never ships a real configuration code.
+     */
+    listReferencesToConfiguration(configurationCode: string): Promise<{
+        settingCode: string;
+        salesChannelCode?: string;
+    }[]>;
+}
+//# sourceMappingURL=settings.service.d.ts.map

package/dist/kernel/settings/settings.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings.service.d.ts","sourceRoot":"","sources":["../../../src/kernel/settings/settings.service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAI7B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAGzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,qBAAa,oBAAqB,SAAQ,KAAK;aAGjB,WAAW,EAAE,MAAM;IAF/C,SAAkB,IAAI,0BAA0B;IAChD,QAAQ,CAAC,IAAI,EAAG,wBAAwB,CAAU;gBACtB,WAAW,EAAE,MAAM;CAGhD;AAED,qBAAa,2BAA4B,SAAQ,KAAK;aAIlC,WAAW,EAAE,MAAM;IACnC,oEAAoE;aACpD,cAAc,EAAE,MAAM,GAAG,IAAI;IAL/C,SAAkB,IAAI,iCAAiC;IACvD,QAAQ,CAAC,IAAI,EAAG,kCAAkC,CAAU;gBAE1C,WAAW,EAAE,MAAM;IACnC,oEAAoE;IACpD,cAAc,EAAE,MAAM,GAAG,IAAI;CAQhD;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,wBAAyB,SAAQ,KAAK;aAI/B,WAAW,EAAE,MAAM;aACnB,cAAc,EAAE,MAAM;IAJxC,SAAkB,IAAI,8BAA8B;IACpD,QAAQ,CAAC,IAAI,EAAG,6BAA6B,CAAU;gBAErC,WAAW,EAAE,MAAM,EACnB,cAAc,EAAE,MAAM;CAOzC;AAUD,qBAAa,yBAA0B,SAAQ,KAAK;aAIhC,WAAW,EAAE,MAAM;aACnB,MAAM,EAAE,OAAO;IAJjC,SAAkB,IAAI,+BAA+B;IACrD,QAAQ,CAAC,IAAI,EAAG,8BAA8B,CAAU;gBAEtC,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,OAAO;CAIlC;AAED,MAAM,MAAM,kBAAkB,CAAC,CAAC,IAC5B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GACtB;IACE,EAAE,EAAE,KAAK,CAAC;IACV,KAAK,EAAE,gBAAgB,GAAG,cAAc,GAAG,gBAAgB,CAAC;IAC5D,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AAEN,qBAAa,eAAe;IAExB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC;IACvB;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAC;gBAPpB,SAAS,EAAE,MAAM,aAAa,EAC9B,KAAK,CAAC,EAAE,aAAa,YAAA;IACtC;;;;OAIG;IACc,mBAAmB,CAAC,EAAE,MAAM,YAAA;IAGzC,GAAG,CAAC,CAAC,EACT,IAAI,EAAE,MAAM,EACZ,cAAc,EAAE,MAAM,GAAG,IAAI,EAC7B,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC;IA2Cb;;;;OAIG;IACG,OAAO,CACX,KAAK,EAAE,MAAM,EAAE,EACf,cAAc,EAAE,MAAM,GAAG,IAAI,GAC5B,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,kBAAkB,CAAC,OAAO,CAAC,CAAC,CAAC;IA4BpD,gFAAgF;YAClE,MAAM;IAuCpB;;;;OAIG;IACH,OAAO,CAAC,eAAe;IAOvB,OAAO,CAAC,QAAQ;IAMhB;;;;OAIG;IACH,OAAO,CAAC,YAAY;IAKpB;;;;;;;;;OASG;IACG,6BAA6B,CACjC,iBAAiB,EAAE,MAAM,GACxB,OAAO,CAAC;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAqBjE"}