youeduc-sdk-messaging 0.0.0 → 0.5.0

package/dist/publisher.d.ts

@@ -0,0 +1,50 @@
+/** Publication of schema-validated events. */
+import * as headersMod from './headers.js';
+import { type Logger } from './logger.js';
+import { type MessageSender, type PayloadValidator, type PublishResult, type Telemetry } from './types.js';
+export interface PublishOptions {
+    /** Defines the partition (order per key). Empty/absent → no key (default partitioner). */
+    key?: string | null | undefined;
+    /** Given or a new UUID4. */
+    correlationId?: string | null | undefined;
+    /** Preferred dedup key for consumers (header `idempotency_key`). */
+    idempotencyKey?: string | null | undefined;
+    /** Header `x-tenant-id`. */
+    tenantId?: string | null | undefined;
+}
+export interface PublisherOptions {
+    /** Name (kebab-case) of the publishing service; goes in the `producer` header. */
+    producer: string;
+    /** Default {@link NoopTelemetry}. */
+    telemetry?: Telemetry | undefined;
+    /** Default: the SDK default logger. */
+    logger?: Logger | undefined;
+    /** Clock (epoch ms) for `published_at`. Default `Date.now`. */
+    clock?: headersMod.EpochClock | undefined;
+    /**
+     * Resource prefix (spec §2.7): `hmg` → topic `hmg.{domain}.events.{version}`. The `producer`
+     * header does not change. Default: none.
+     */
+    resourcePrefix?: string | null | undefined;
+}
+/**
+ * Validates the payload against the event schema and publishes it to the domain topic.
+ *
+ * Same flow as Python: names → schema validation → JSON serialization → headers → send inside
+ * the PRODUCER span (the injected `traceparent` reaches the broker) → metric + log.
+ */
+export declare class Publisher {
+    #private;
+    /** Resource prefix applied to the topic (`null` = none). */
+    readonly resourcePrefix: string | null;
+    constructor(sender: MessageSender, validator: PayloadValidator, options: PublisherOptions);
+    /**
+     * Publishes and waits for the broker ack.
+     *
+     * Throws `TypeError` (invalid names), `SchemaNotFoundError` / `SchemaValidationError`
+     * (nothing is sent) or the send error (`PublishError`, `NotStartedError`...).
+     */
+    publish(domain: string, aggregate: string, event: string, version: string, payload: Readonly<Record<string, unknown>>, options?: PublishOptions): Promise<PublishResult>;
+}
+/** Key bytes of a published record (spec §3): UTF-8, and `""`/absent → `null`. */
+export declare function publishKey(key: string | null | undefined): Buffer | null;

package/dist/publisher.js

@@ -0,0 +1,199 @@
+/** Publication of schema-validated events. */
+import { performance } from 'node:perf_hooks';
+import { SchemaNotFoundError, SchemaValidationError } from './errors.js';
+import * as headersMod from './headers.js';
+import { defaultLogger } from './logger.js';
+import * as naming from './naming.js';
+import { NoopTelemetry } from './telemetry.js';
+import { createMessageInfo, } from './types.js';
+import { errorFields, isPlainObject } from './util.js';
+/**
+ * Validates the payload against the event schema and publishes it to the domain topic.
+ *
+ * Same flow as Python: names → schema validation → JSON serialization → headers → send inside
+ * the PRODUCER span (the injected `traceparent` reaches the broker) → metric + log.
+ */
+export class Publisher {
+    #sender;
+    #validator;
+    #producer;
+    /** Resource prefix applied to the topic (`null` = none). */
+    resourcePrefix;
+    #telemetry;
+    #logger;
+    #clock;
+    constructor(sender, validator, options) {
+        naming.serviceName(options.producer);
+        this.resourcePrefix = naming.resourcePrefix(options.resourcePrefix);
+        this.#sender = sender;
+        this.#validator = validator;
+        this.#producer = options.producer;
+        this.#telemetry = options.telemetry ?? new NoopTelemetry();
+        this.#logger = options.logger;
+        this.#clock = options.clock;
+    }
+    get #log() {
+        return this.#logger ?? defaultLogger();
+    }
+    /**
+     * Publishes and waits for the broker ack.
+     *
+     * Throws `TypeError` (invalid names), `SchemaNotFoundError` / `SchemaValidationError`
+     * (nothing is sent) or the send error (`PublishError`, `NotStartedError`...).
+     */
+    async publish(domain, aggregate, event, version, payload, options = {}) {
+        const topic = naming.topic(domain, version, { resourcePrefix: this.resourcePrefix });
+        const eventType = naming.eventType(aggregate, event);
+        let info = createMessageInfo({
+            topic,
+            eventType,
+            messageId: '',
+            schemaVersion: version,
+            key: options.key,
+            correlationId: options.correlationId,
+            tenantId: options.tenantId,
+        });
+        let body;
+        try {
+            this.#validator.validate({ domain, eventType, version, payload });
+            body = serialize(payload);
+        }
+        catch (error) {
+            if (error instanceof SchemaValidationError || error instanceof SchemaNotFoundError) {
+                // A missing schema also counts as a schema error (parity with the consumer).
+                this.#telemetry.recordSchemaError(info);
+                this.#logSchemaFailure(info, error);
+            }
+            throw error;
+        }
+        const messageHeaders = headersMod.buildPublishHeaders({
+            eventType,
+            schemaVersion: version,
+            producer: this.#producer,
+            correlationId: options.correlationId,
+            idempotencyKey: options.idempotencyKey,
+            tenantId: options.tenantId,
+            clock: this.#clock,
+        });
+        info = createMessageInfo({
+            ...info,
+            messageId: messageHeaders[headersMod.MESSAGE_ID] ?? '',
+            correlationId: messageHeaders[headersMod.CORRELATION_ID] ?? null,
+        });
+        const key = publishKey(options.key);
+        const started = performance.now();
+        let record;
+        try {
+            record = await this.#telemetry.publishSpan(info, messageHeaders, () => 
+            // Encoded inside the span: includes the injected traceparent.
+            this.#sender.send(topic, body, { key, headers: headersMod.encode(messageHeaders) }));
+        }
+        catch (error) {
+            const durationMs = performance.now() - started;
+            this.#telemetry.recordPublish(info, { status: 'error', durationMs });
+            this.#log.error('message_publish_failed', {
+                messaging: messagingFields(info, durationMs),
+                error: errorFields(error),
+            });
+            throw error;
+        }
+        const durationMs = performance.now() - started;
+        this.#telemetry.recordPublish(info, { status: 'success', durationMs });
+        const fields = messagingFields(info, durationMs);
+        fields.partition = record.partition;
+        fields.offset = record.offset;
+        this.#log.info('message_published', { messaging: fields });
+        return Object.freeze({
+            messageId: info.messageId,
+            topic: record.topic,
+            partition: record.partition,
+            offset: record.offset,
+        });
+    }
+    #logSchemaFailure(info, error) {
+        const messaging = {
+            event_type: info.eventType,
+            schema_version: info.schemaVersion,
+            topic: info.topic,
+        };
+        if (info.correlationId !== null)
+            messaging.correlation_id = info.correlationId;
+        if (info.tenantId)
+            messaging.tenant_id = info.tenantId;
+        const errorInfo = errorFields(error);
+        if (error instanceof SchemaValidationError)
+            errorInfo.field = error.field;
+        this.#log.error('message_schema_validation_failed', { messaging, error: errorInfo });
+    }
+}
+/** Key bytes of a published record (spec §3): UTF-8, and `""`/absent → `null`. */
+export function publishKey(key) {
+    return key ? Buffer.from(key, 'utf8') : null;
+}
+const NOT_SERIALIZABLE = 'payload is not JSON serializable';
+/**
+ * Strict JSON check (Python `json.dumps(..., allow_nan=False)`): only plain objects, arrays,
+ * strings, finite numbers, booleans and `null`. `undefined` object properties are omitted
+ * (treated as absent, like the schema validation does); anything else (NaN/Infinity, bigint,
+ * Date, Map/Set, class instances, functions, symbols, cycles) is rejected.
+ */
+function assertJson(value, ancestors) {
+    switch (typeof value) {
+        case 'string':
+        case 'boolean':
+            return;
+        case 'number':
+            if (!Number.isFinite(value))
+                throw new SchemaValidationError('', NOT_SERIALIZABLE);
+            return;
+        case 'object': {
+            if (value === null)
+                return;
+            if (ancestors.has(value))
+                throw new SchemaValidationError('', NOT_SERIALIZABLE);
+            ancestors.add(value);
+            if (Array.isArray(value)) {
+                for (let i = 0; i < value.length; i += 1) {
+                    if (!(i in value) || value[i] === undefined)
+                        throw new SchemaValidationError('', NOT_SERIALIZABLE);
+                    assertJson(value[i], ancestors);
+                }
+            }
+            else if (isPlainObject(value)) {
+                if (Object.getOwnPropertySymbols(value).length > 0)
+                    throw new SchemaValidationError('', NOT_SERIALIZABLE);
+                for (const item of Object.values(value)) {
+                    if (item !== undefined)
+                        assertJson(item, ancestors);
+                }
+            }
+            else {
+                throw new SchemaValidationError('', NOT_SERIALIZABLE);
+            }
+            ancestors.delete(value);
+            return;
+        }
+        default:
+            throw new SchemaValidationError('', NOT_SERIALIZABLE);
+    }
+}
+/** Compact UTF-8 JSON; never includes payload values in the error. */
+function serialize(payload) {
+    assertJson(payload, new Set());
+    return Buffer.from(JSON.stringify(payload), 'utf8');
+}
+function messagingFields(info, durationMs) {
+    const fields = {
+        message_id: info.messageId,
+        event_type: info.eventType,
+        schema_version: info.schemaVersion,
+        topic: info.topic,
+        has_key: Boolean(info.key),
+        correlation_id: info.correlationId,
+        publish_duration_ms: Math.round(durationMs * 1000) / 1000,
+    };
+    if (info.tenantId)
+        fields.tenant_id = info.tenantId;
+    return fields;
+}
+//# sourceMappingURL=publisher.js.map

package/dist/publisher.js.map

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

package/dist/retry.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Default schedule: 30 s, 5 min, 1 h, 12 h (~13h35min before the DLQ; same as Python's
+ * `(30, 300, 3600, 43200)`, spec §6).
+ */
+export declare const DEFAULT_RETRY_DELAYS_MS: readonly number[];
+export interface RetryPolicyOptions {
+    /** Delay of each retry, in milliseconds; whole seconds, positive and distinct labels. */
+    delaysMs?: readonly number[];
+}
+/**
+ * Backoff through retry topics: attempt `n` (0-based) waits `delaysMs[n]`.
+ *
+ * When attempts are exhausted (`x-retry-count >= delaysMs.length`) the message goes to the DLQ.
+ * `delaysMs: []` disables retry (every transient failure goes to the DLQ). Immutable.
+ */
+export declare class RetryPolicy {
+    readonly delaysMs: readonly number[];
+    constructor(options?: RetryPolicyOptions);
+    get maxRetries(): number;
+    /** Delay (ms) of the next attempt, or `null` when exhausted. */
+    delayFor(retryCount: number): number | null;
+    /** Retry topics of the group, in schedule order. */
+    retryTopics(mainTopic: string, group: string): string[];
+}

package/dist/retry.js

@@ -0,0 +1,42 @@
+import * as naming from './naming.js';
+/**
+ * Default schedule: 30 s, 5 min, 1 h, 12 h (~13h35min before the DLQ; same as Python's
+ * `(30, 300, 3600, 43200)`, spec §6).
+ */
+export const DEFAULT_RETRY_DELAYS_MS = Object.freeze([
+    30_000, 300_000, 3_600_000, 43_200_000,
+]);
+/**
+ * Backoff through retry topics: attempt `n` (0-based) waits `delaysMs[n]`.
+ *
+ * When attempts are exhausted (`x-retry-count >= delaysMs.length`) the message goes to the DLQ.
+ * `delaysMs: []` disables retry (every transient failure goes to the DLQ). Immutable.
+ */
+export class RetryPolicy {
+    delaysMs;
+    constructor(options = {}) {
+        const delays = Object.freeze([...(options.delaysMs ?? DEFAULT_RETRY_DELAYS_MS)]);
+        const labels = delays.map((delay) => naming.delayLabel(delay));
+        if (new Set(labels).size !== labels.length) {
+            throw new TypeError(`retry delays must be distinct; got [${delays.join(', ')}]`);
+        }
+        this.delaysMs = delays;
+        Object.freeze(this);
+    }
+    get maxRetries() {
+        return this.delaysMs.length;
+    }
+    /** Delay (ms) of the next attempt, or `null` when exhausted. */
+    delayFor(retryCount) {
+        if (retryCount < 0)
+            throw new RangeError(`retry_count must be >= 0; got ${retryCount}`);
+        if (retryCount >= this.delaysMs.length)
+            return null;
+        return this.delaysMs[retryCount] ?? null;
+    }
+    /** Retry topics of the group, in schedule order. */
+    retryTopics(mainTopic, group) {
+        return this.delaysMs.map((delay) => naming.retryTopic(mainTopic, group, delay));
+    }
+}
+//# sourceMappingURL=retry.js.map

package/dist/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../src/retry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,aAAa,CAAC;AAEtC;;;GAGG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAsB,MAAM,CAAC,MAAM,CAAC;IACtE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,UAAU;CACvC,CAAC,CAAC;AAOH;;;;;GAKG;AACH,MAAM,OAAO,WAAW;IACb,QAAQ,CAAoB;IAErC,YAAY,OAAO,GAAuB,EAAE;QAC1C,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,QAAQ,IAAI,uBAAuB,CAAC,CAAC,CAAC,CAAC;QACjF,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC;QAC/D,IAAI,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC,MAAM,EAAE,CAAC;YAC3C,MAAM,IAAI,SAAS,CAAC,uCAAuC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACnF,CAAC;QACD,IAAI,CAAC,QAAQ,GAAG,MAAM,CAAC;QACvB,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACtB,CAAC;IAED,IAAI,UAAU;QACZ,OAAO,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC;IAC9B,CAAC;IAED,gEAAgE;IAChE,QAAQ,CAAC,UAAkB;QACzB,IAAI,UAAU,GAAG,CAAC;YAAE,MAAM,IAAI,UAAU,CAAC,iCAAiC,UAAU,EAAE,CAAC,CAAC;QACxF,IAAI,UAAU,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM;YAAE,OAAO,IAAI,CAAC;QACpD,OAAO,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,IAAI,CAAC;IAC3C,CAAC;IAED,oDAAoD;IACpD,WAAW,CAAC,SAAiB,EAAE,KAAa;QAC1C,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,UAAU,CAAC,SAAS,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC;IAClF,CAAC;CACF"}

package/dist/schema.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Loading and validation of JSON Schemas (Draft 2020-12).
+ *
+ * No error message produced here contains payload *values* (PII): only the JSON pointer of the
+ * field, the name of the violated rule and, for `required` / `additionalProperties`, the names
+ * of the properties involved. Wording, the selected error and the checked formats follow the
+ * Python SDK (`jsonschema` + `best_match`).
+ */
+import type { JsonObject, PayloadValidationRequest, PayloadValidator, SchemaLoader, SchemaValidator, SchemaValidatorFactory } from './types.js';
+/**
+ * Schemas in memory, indexed by `"domain/eventSlug/version"` (spec §17). Stores and returns
+ * deep copies: caller mutations never leak.
+ */
+export declare class InMemorySchemaLoader implements SchemaLoader {
+    #private;
+    constructor(schemas: Readonly<Record<string, JsonObject>>);
+    load(domain: string, event: string, version: string): JsonObject;
+}
+/**
+ * Asks `loaders` in order: the first one that does not throw `SchemaNotFoundError` wins.
+ *
+ * Typical use: the service's own schemas first, the SDK's bundled contracts after them:
+ * `new ChainSchemaLoader(new FileSystemSchemaLoader('schemas'), contracts.schemaLoader())`.
+ * Any other error of a loader (I/O, `SchemaValidationError` for a malformed file) propagates at
+ * once, without asking the next ones. None found → `SchemaNotFoundError`.
+ */
+export declare class ChainSchemaLoader implements SchemaLoader {
+    #private;
+    constructor(...loaders: SchemaLoader[]);
+    get loaders(): readonly SchemaLoader[];
+    load(domain: string, event: string, version: string): JsonObject;
+}
+/** File-system primitives used by {@link FileSystemSchemaLoader} (injectable for tests). */
+export interface SchemaFileSystem {
+    readFile(filePath: string): Buffer;
+    realpath(filePath: string): string;
+}
+/**
+ * Reads `root/{domain}/{event}/{version}.json`.
+ *
+ * Protected against path traversal: empty components, `.`/`..`, separators or NUL are refused,
+ * and the final path (after resolving symlinks) must stay inside `root`. Otherwise →
+ * `SchemaNotFoundError`. Only a missing file (`ENOENT`, `ENOTDIR`, `EISDIR`) becomes
+ * `SchemaNotFoundError`; other I/O errors propagate unchanged. Non-UTF-8, malformed JSON or a
+ * non-object → `SchemaValidationError`.
+ *
+ * Synchronous I/O: meant to be called once per schema (`SchemaRegistry` caches validators).
+ */
+export declare class FileSystemSchemaLoader implements SchemaLoader {
+    #private;
+    constructor(root: string, options?: {
+        fileSystem?: SchemaFileSystem;
+    });
+    get root(): string;
+    load(domain: string, event: string, version: string): JsonObject;
+}
+/**
+ * Validates payloads with Ajv (Draft 2020-12), including `format`.
+ *
+ * The schema is checked in the constructor (an invalid schema fails early). `$ref` is never
+ * fetched over the network: only local references (`#/$defs/...`, anchors, embedded subschemas
+ * with `$id`) resolve, and every `$ref`/`$dynamicRef` is resolved statically at construction;
+ * one that does not resolve (remote included) becomes `SchemaValidationError`.
+ *
+ * The reported error is the one Python's `jsonschema.best_match` would pick (shallowest
+ * instance path, lexicographically last sibling, anyOf/oneOf descended into their context).
+ */
+export declare class JsonSchemaValidator implements SchemaValidator {
+    #private;
+    constructor(schema: JsonObject);
+    validate(payload: unknown): void;
+}
+/**
+ * Implements {@link PayloadValidator}: resolves the schema of an event and validates.
+ *
+ * Validators are cached per `[domain, slug, version]`. Load failures (`SchemaNotFoundError`)
+ * and invalid schemas are not cached, so a schema published later is found without restarting.
+ */
+export declare class SchemaRegistry implements PayloadValidator {
+    #private;
+    constructor(loader: SchemaLoader, validatorFactory?: SchemaValidatorFactory);
+    validate(request: PayloadValidationRequest): void;
+}