youeduc-sdk-messaging 0.0.0 → 0.5.0

package/dist/integrations/runtime.d.ts

@@ -0,0 +1,232 @@
+/**
+ * Framework-agnostic runtime of the SDK (Python `integrations/runtime.py`, without the sync
+ * bridge: Node is async-native).
+ *
+ * - {@link MessagingSettings} — canonical configuration (`SDK_MESSAGING`, spec §14), the same
+ *   mapping used by the Python SDK (Django `settings.SDK_MESSAGING`, Flask `app.config`).
+ * - {@link buildMessaging} / {@link buildDedupStore} — facade and shared dedup store from it.
+ * - {@link serveConsumers} / {@link runConsumers} — consumer process for CLI entry points
+ *   (signals, draining, exit code).
+ *
+ * Redis is loaded only by {@link buildDedupStore} (dynamic `import('./redis.js')`), so `redis`
+ * stays an optional peer dependency.
+ */
+import { inspect } from 'node:util';
+import { type Environment, KafkaConfig } from '../config.js';
+import { type Logger } from '../logger.js';
+import { Messaging, type MessagingConsumerOptions } from '../messaging.js';
+import type { DuplicateChecker } from '../types.js';
+/** Default `SEND_TIMEOUT_S` (20 s), in ms. */
+export declare const DEFAULT_SEND_TIMEOUT_MS = 20000;
+/** Default `PUBLISH_TIMEOUT_S` (25 s), in ms. */
+export declare const DEFAULT_PUBLISH_TIMEOUT_MS = 25000;
+/** Default `DRAIN_TIMEOUT_S` (30 s), in ms. */
+export declare const DEFAULT_DRAIN_TIMEOUT_MS = 30000;
+/** Default `REDIS.TTL_S` (7 days), in ms. */
+export declare const DEFAULT_REDIS_TTL_MS = 604800000;
+/** Default `REDIS.TIMEOUT_S` (5 s), in ms. */
+export declare const DEFAULT_REDIS_TIMEOUT_MS = 5000;
+/** Canonical configuration document (`SDK_MESSAGING`): UPPERCASE keys, durations in **seconds**. */
+export interface SdkMessagingMapping {
+    SERVICE: string;
+    ENVIRONMENT: string;
+    /** `null`/absent → only the bundled contracts (`contracts.schemaLoader()`). */
+    SCHEMAS_DIR?: string | null;
+    /** `null`/absent → `KafkaConfig.fromEnv({ env })`. */
+    KAFKA?: {
+        bootstrap_servers: string;
+        client_id?: string | null;
+        security_protocol?: string;
+        sasl_mechanism?: string | null;
+        sasl_username?: string | null;
+        sasl_password?: string | null;
+    } | null;
+    SEND_TIMEOUT_S?: number;
+    PUBLISH_TIMEOUT_S?: number;
+    DRAIN_TIMEOUT_S?: number;
+    TENANT_METRIC_LABEL?: boolean;
+    REDIS?: {
+        URL: string;
+        NAMESPACE: string;
+        TTL_S?: number;
+        TIMEOUT_S?: number;
+    } | null;
+    /** `null`/absent → no prefix; else kebab-case (`hmg`, `prd`), spec §2.7. */
+    RESOURCE_PREFIX?: string | null;
+}
+/** `REDIS` block of {@link MessagingSettings} (shared dedup). Durations in ms. */
+export declare class RedisSettings {
+    #private;
+    readonly namespace: string;
+    readonly ttlMs: number;
+    readonly timeoutMs: number;
+    constructor(init: {
+        url: string;
+        namespace: string;
+        ttlMs?: number;
+        timeoutMs?: number;
+    });
+    get url(): string;
+    toJSON(): Record<string, unknown>;
+    [inspect.custom](): string;
+}
+export interface MessagingSettingsInit {
+    service: string;
+    environment: string;
+    /** `null`/absent → only the bundled contracts. */
+    schemasDir?: string | null;
+    kafka: KafkaConfig;
+    sendTimeoutMs?: number;
+    publishTimeoutMs?: number;
+    drainTimeoutMs?: number;
+    tenantMetricLabel?: boolean;
+    redis?: RedisSettings | null;
+    /** `null`/absent → no prefix. */
+    resourcePrefix?: string | null;
+}
+/**
+ * Validated canonical configuration. Build it with {@link MessagingSettings.fromMapping} from the
+ * `SDK_MESSAGING` object:
+ *
+ * ```ts
+ * const settings = MessagingSettings.fromMapping({
+ *   SERVICE: 'enrollment-api',       // required (kebab-case)
+ *   ENVIRONMENT: 'production',       // required
+ *   SCHEMAS_DIR: './schemas',        // optional: null/absent → bundled contracts only
+ *   KAFKA: null,                     // null → KafkaConfig.fromEnv() (KAFKA_BOOTSTRAP_SERVERS...)
+ *   SEND_TIMEOUT_S: 20,              // broker ack wait
+ *   PUBLISH_TIMEOUT_S: 25,           // caller-side publish bound (> SEND_TIMEOUT_S)
+ *   DRAIN_TIMEOUT_S: 30,             // draining on shutdown
+ *   TENANT_METRIC_LABEL: true,
+ *   REDIS: null,                     // or { URL, NAMESPACE, TTL_S, TIMEOUT_S }
+ *   RESOURCE_PREFIX: null,           // e.g. 'hmg'/'prd' → hmg.<topic>, hmg.<group> (spec §2.7)
+ * });
+ * ```
+ *
+ * Units: the mapping is the canonical document shared with the Python SDK, so its durations are
+ * in **seconds** (`*_S`); the settings object exposes them in **milliseconds** (`sendTimeoutMs`,
+ * `publishTimeoutMs`, `drainTimeoutMs`, `redis.ttlMs`, `redis.timeoutMs`), like the rest of the
+ * Node API. `KAFKA` is a mapping with the snake_case `KafkaConfig` field names
+ * (`{ bootstrap_servers: 'kafka:9092', ... }`), never a `KafkaConfig` instance (spec §18).
+ *
+ * `publishTimeoutMs` is validated and exposed for parity; Node has no sync bridge, so the SDK
+ * itself does not use it (applications may use it to bound their own publish waits).
+ */
+export declare class MessagingSettings {
+    readonly service: string;
+    readonly environment: string;
+    /** `null` = no `SCHEMAS_DIR`: {@link buildMessaging} uses only the bundled contracts. */
+    readonly schemasDir: string | null;
+    readonly kafka: KafkaConfig;
+    readonly sendTimeoutMs: number;
+    readonly publishTimeoutMs: number;
+    readonly drainTimeoutMs: number;
+    readonly tenantMetricLabel: boolean;
+    readonly redis: RedisSettings | null;
+    /** Resource prefix applied by {@link buildMessaging} to every topic and group id (`null` = none). */
+    readonly resourcePrefix: string | null;
+    /** No validation here: use {@link MessagingSettings.fromMapping}. */
+    constructor(init: MessagingSettingsInit);
+    /**
+     * Validates and converts `SDK_MESSAGING`. Any problem → `TypeError` (Python `ValueError`; the
+     * `KafkaConfig` and `naming` validations also throw `TypeError`). Unknown keys are rejected,
+     * also inside `KAFKA` and `REDIS` (a typo must not pass silently). `env` replaces
+     * `process.env` when `KAFKA` is `null`/absent. An `undefined` value counts as absent.
+     */
+    static fromMapping(mapping: unknown, options?: {
+        env?: Environment;
+    }): MessagingSettings;
+}
+/**
+ * {@link Messaging} with the schema loader described in spec §14 (bundled contracts, preceded
+ * by `FileSystemSchemaLoader(SCHEMAS_DIR)` when set) and `OtelTelemetry`. Starts nothing. A
+ * `SCHEMAS_DIR` that is not a directory → `TypeError`.
+ */
+export declare function buildMessaging(settings: MessagingSettings, options?: {
+    logger?: Logger;
+}): Messaging;
+/** What {@link serveConsumers} uses from a dedup store (`RedisDedupStore` satisfies it). */
+export interface DedupStore {
+    checker(group: string): DuplicateChecker;
+    /** Never throws: failure → `false`. */
+    ping(): Promise<boolean>;
+    close(): Promise<void>;
+}
+/**
+ * `RedisDedupStore` from the `REDIS` block (`null` without it). The Redis module (and `redis`
+ * itself) is imported only here, so the peer dependency stays optional.
+ */
+export declare function buildDedupStore(settings: MessagingSettings): Promise<DedupStore | null>;
+/** What the runner uses from a consumer (`Consumer` satisfies it). */
+export interface RunnableConsumer {
+    readonly group: string;
+    start(): Promise<void>;
+    stop(options?: {
+        drainTimeoutMs?: number;
+    }): Promise<void>;
+    /** Resolves when the consumer loop ends; rejects with the fatal error that stopped it. */
+    wait(): Promise<void>;
+}
+/** Options of `Messaging.consumer(...)` (spec §17): the facade's own type, re-exported. */
+export type { MessagingConsumerOptions } from '../messaging.js';
+/** A facade able to create consumers (`Messaging` once `consumer()` is available). */
+export interface ConsumerFactory {
+    consumer(options: MessagingConsumerOptions): RunnableConsumer;
+}
+/** What the runner uses from the facade (`Messaging` satisfies it). */
+export interface RunnableMessaging {
+    start(): Promise<void>;
+    stop(options?: {
+        drainTimeoutMs?: number;
+    }): Promise<void>;
+    readonly logger?: Logger;
+}
+/**
+ * `build(messaging, dedupStore) → [consumer, ...]`: create them with `messaging.consumer({...})`
+ * (pass `duplicateChecker: dedupStore.checker(group)` for shared dedup). Do not start them: the
+ * runner does.
+ */
+export type ConsumerBuilder<M extends RunnableMessaging = Messaging> = (messaging: M, dedupStore: DedupStore | null) => Iterable<RunnableConsumer> | Promise<Iterable<RunnableConsumer>>;
+/** Where stop signals come from (default `process`); injectable for tests and embedding. */
+export interface SignalSource {
+    on(signal: 'SIGINT' | 'SIGTERM', listener: () => void): unknown;
+    off(signal: 'SIGINT' | 'SIGTERM', listener: () => void): unknown;
+}
+export interface ServeConsumersOptions<M extends RunnableMessaging = Messaging> {
+    /** Used by the default factories (`buildMessaging`, `buildDedupStore`) and for `drainTimeoutMs`. */
+    settings?: MessagingSettings;
+    /** Default `buildMessaging(settings)`. */
+    messagingFactory?: () => M | Promise<M>;
+    /** Default `buildDedupStore(settings)` (`null` without `REDIS`). Always closed at the end. */
+    dedupStoreFactory?: () => DedupStore | null | Promise<DedupStore | null>;
+    /** Default `true`: SIGINT/SIGTERM request the stop (main thread only). */
+    installSignalHandlers?: boolean;
+    /** Default `settings.drainTimeoutMs`, or 30 000 ms. */
+    drainTimeoutMs?: number;
+    /** Called with the consumers already started; `requestStop()` is equivalent to a signal. */
+    onReady?: (requestStop: () => void) => unknown;
+    /** Runner logs. Default: the facade logger (`messaging.logger`), else the SDK default logger. */
+    logger?: Logger;
+    /** Signal source. Default `process`. */
+    signals?: SignalSource | undefined;
+}
+/**
+ * Runs consumers until SIGINT/SIGTERM (or `requestStop`) or the first fatal error.
+ *
+ * - Facade: `messagingFactory()` or `buildMessaging(settings)`.
+ * - Dedup store: `dedupStoreFactory()` or `buildDedupStore(settings)`; pinged once
+ *   (`dedup_store_unreachable` when down) and always closed at the end.
+ * - Shutdown: stops the consumers and the facade, draining up to `drainTimeoutMs`. Signals stay
+ *   captured while draining: a second signal is only logged.
+ *
+ * Resolves `0` (signal / requested stop) or `1` (a consumer crashed — `consumers_crashed` — or the
+ * shutdown failed). Startup errors (`build`, `start`, empty build) are rethrown after cleanup.
+ */
+export declare function serveConsumers<M extends RunnableMessaging = Messaging>(build: ConsumerBuilder<M>, options?: ServeConsumersOptions<M>): Promise<number>;
+/**
+ * CLI entry point: `await serveConsumers(...)` and sets `process.exitCode` to the result.
+ *
+ * Run it in a process/Deployment **separate** from the web server and keep the termination
+ * grace period above `drainTimeoutMs`. Startup errors are rethrown (unhandled → exit code 1).
+ */
+export declare function runConsumers<M extends RunnableMessaging = Messaging>(build: ConsumerBuilder<M>, options?: ServeConsumersOptions<M>): Promise<number>;