@benzenejs/mesh-reporting 0.0.0-stage → 0.1.0-beta.2

package/dist/Extensions.d.ts

@@ -0,0 +1,20 @@
+/** Port of Benzene.Mesh.Reporting.Extensions. */
+import { IBenzeneServiceContainer } from '@benzenejs/abstractions';
+import { IMiddlewarePipelineBuilder } from '@benzenejs/abstractions-middleware';
+import { MeshReportingOptions } from './MeshReportingOptions';
+import { MeshSelfReportOptions } from './MeshSelfReportOptions';
+/**
+ * Registers `HttpMeshReportPublisher` (as `IMeshReportPublisher`) against the given options - for a reporting
+ * service that isn't colocated with the aggregator's own storage. C# extension method -> free function.
+ */
+export declare function addMeshHttpReporting(services: IBenzeneServiceContainer, options: MeshReportingOptions): IBenzeneServiceContainer;
+/**
+ * Registers `MeshSelfReportOptions` and the singleton `MeshSelfReportState` the self-report middleware needs.
+ * Requires an `IMeshReportPublisher` already registered (via {@link addMeshHttpReporting} or the aggregator).
+ */
+export declare function addMeshSelfReport(services: IBenzeneServiceContainer, options: MeshSelfReportOptions): IBenzeneServiceContainer;
+/**
+ * Adds `MeshSelfReportMiddleware` to the pipeline. Requires {@link addMeshSelfReport} (and an
+ * `IMeshReportPublisher` registration) already called on the same container.
+ */
+export declare function useMeshSelfReport<TContext>(app: IMiddlewarePipelineBuilder<TContext>): IMiddlewarePipelineBuilder<TContext>;

package/dist/Extensions.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addMeshHttpReporting = addMeshHttpReporting;
+exports.addMeshSelfReport = addMeshSelfReport;
+exports.useMeshSelfReport = useMeshSelfReport;
+const mesh_contracts_1 = require("@benzenejs/mesh-contracts");
+const HttpMeshReportPublisher_1 = require("./HttpMeshReportPublisher");
+const MeshReportingOptions_1 = require("./MeshReportingOptions");
+const MeshSelfReportMiddleware_1 = require("./MeshSelfReportMiddleware");
+const MeshSelfReportOptions_1 = require("./MeshSelfReportOptions");
+const MeshSelfReportState_1 = require("./MeshSelfReportState");
+/**
+ * Registers `HttpMeshReportPublisher` (as `IMeshReportPublisher`) against the given options - for a reporting
+ * service that isn't colocated with the aggregator's own storage. C# extension method -> free function.
+ */
+function addMeshHttpReporting(services, options) {
+    services.addSingletonInstance(MeshReportingOptions_1.MeshReportingOptions, options);
+    services.addSingletonFactory(mesh_contracts_1.IMeshReportPublisher, (resolver) => new HttpMeshReportPublisher_1.HttpMeshReportPublisher(resolver.getService(MeshReportingOptions_1.MeshReportingOptions)));
+    return services;
+}
+/**
+ * Registers `MeshSelfReportOptions` and the singleton `MeshSelfReportState` the self-report middleware needs.
+ * Requires an `IMeshReportPublisher` already registered (via {@link addMeshHttpReporting} or the aggregator).
+ */
+function addMeshSelfReport(services, options) {
+    services.addSingletonInstance(MeshSelfReportOptions_1.MeshSelfReportOptions, options);
+    services.addSingletonFactory(MeshSelfReportState_1.MeshSelfReportState, () => new MeshSelfReportState_1.MeshSelfReportState());
+    return services;
+}
+/**
+ * Adds `MeshSelfReportMiddleware` to the pipeline. Requires {@link addMeshSelfReport} (and an
+ * `IMeshReportPublisher` registration) already called on the same container.
+ */
+function useMeshSelfReport(app) {
+    return app.use((resolver) => new MeshSelfReportMiddleware_1.MeshSelfReportMiddleware(resolver.getService(mesh_contracts_1.IMeshReportPublisher), resolver.getService(MeshSelfReportOptions_1.MeshSelfReportOptions), resolver.getService(MeshSelfReportState_1.MeshSelfReportState)));
+}

package/dist/HttpMeshReportPublisher.d.ts

@@ -0,0 +1,19 @@
+/** Port of Benzene.Mesh.Reporting.HttpMeshReportPublisher. */
+import { IMeshReportPublisher, MeshServiceReport } from '@benzenejs/mesh-contracts';
+import { MeshReportingOptions } from './MeshReportingOptions';
+/** A `fetch`-like function - the port of C# `HttpClient.PostAsync` (`HttpClient` -> injectable `fetch`). */
+export type ReportFetch = (url: string, init: RequestInit) => Promise<Response>;
+/**
+ * The HTTP-ingestion `IMeshReportPublisher` - POSTs the report as JSON to `MeshReportingOptions.ingestionUrl`
+ * (an aggregator's ingestion endpoint), for a reporter that isn't colocated with the aggregator's storage.
+ *
+ * `HttpClient` -> an injectable `fetch` (default global `fetch`, the `@benzenejs/health-checks-http` pattern);
+ * `EnsureSuccessStatusCode` -> throw on a non-2xx response. The report's fields are already camelCase, so
+ * `JSON.stringify` matches C#'s camelCase `JsonSerializerOptions`.
+ */
+export declare class HttpMeshReportPublisher implements IMeshReportPublisher {
+    private readonly options;
+    private readonly fetchFn;
+    constructor(options: MeshReportingOptions, fetchFn?: ReportFetch);
+    publishAsync(report: MeshServiceReport): Promise<void>;
+}

package/dist/HttpMeshReportPublisher.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HttpMeshReportPublisher = void 0;
+/**
+ * The HTTP-ingestion `IMeshReportPublisher` - POSTs the report as JSON to `MeshReportingOptions.ingestionUrl`
+ * (an aggregator's ingestion endpoint), for a reporter that isn't colocated with the aggregator's storage.
+ *
+ * `HttpClient` -> an injectable `fetch` (default global `fetch`, the `@benzenejs/health-checks-http` pattern);
+ * `EnsureSuccessStatusCode` -> throw on a non-2xx response. The report's fields are already camelCase, so
+ * `JSON.stringify` matches C#'s camelCase `JsonSerializerOptions`.
+ */
+class HttpMeshReportPublisher {
+    options;
+    fetchFn;
+    constructor(options, fetchFn = fetch) {
+        this.options = options;
+        this.fetchFn = fetchFn;
+    }
+    async publishAsync(report) {
+        const json = JSON.stringify(report);
+        const response = await this.fetchFn(this.options.ingestionUrl, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: json,
+        });
+        if (!response.ok) {
+            throw new Error(`Mesh report POST to ${this.options.ingestionUrl} failed with status ${response.status}.`);
+        }
+    }
+}
+exports.HttpMeshReportPublisher = HttpMeshReportPublisher;

package/dist/MeshReportingOptions.d.ts

@@ -0,0 +1,7 @@
+/** Port of Benzene.Mesh.Reporting.MeshReportingOptions. */
+/** Configures where `HttpMeshReportPublisher` posts self-reports. Resolved from the container by its class. */
+export declare class MeshReportingOptions {
+    readonly ingestionUrl: string;
+    /** @param ingestionUrl The aggregator's ingestion endpoint (e.g. `https://mesh.internal/mesh/report`). */
+    constructor(ingestionUrl: string);
+}

package/dist/MeshReportingOptions.js

@@ -0,0 +1,13 @@
+"use strict";
+/** Port of Benzene.Mesh.Reporting.MeshReportingOptions. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MeshReportingOptions = void 0;
+/** Configures where `HttpMeshReportPublisher` posts self-reports. Resolved from the container by its class. */
+class MeshReportingOptions {
+    ingestionUrl;
+    /** @param ingestionUrl The aggregator's ingestion endpoint (e.g. `https://mesh.internal/mesh/report`). */
+    constructor(ingestionUrl) {
+        this.ingestionUrl = ingestionUrl;
+    }
+}
+exports.MeshReportingOptions = MeshReportingOptions;

package/dist/MeshSelfReportMiddleware.d.ts

@@ -0,0 +1,23 @@
+/** Port of Benzene.Mesh.Reporting.MeshSelfReportMiddleware. */
+import { IMiddleware, NextFunc } from '@benzenejs/abstractions-middleware';
+import { IMeshReportPublisher } from '@benzenejs/mesh-contracts';
+import { MeshSelfReportOptions } from './MeshSelfReportOptions';
+import { MeshSelfReportState } from './MeshSelfReportState';
+/**
+ * After a real request/message completes, opportunistically publishes this service's current spec/health via
+ * the injected `IMeshReportPublisher` - piggybacking on real traffic rather than a dedicated scheduled
+ * reporter. Throttled by `MeshSelfReportOptions.minimumIntervalMs` (tracked in `MeshSelfReportState`).
+ *
+ * Publishing is fire-and-forget and fully best-effort: it never delays the wrapped response, and a publish
+ * failure (or a provider throwing) is swallowed - side-channel telemetry, not part of the primary path.
+ */
+export declare class MeshSelfReportMiddleware<TContext> implements IMiddleware<TContext> {
+    private readonly publisher;
+    private readonly options;
+    private readonly state;
+    constructor(publisher: IMeshReportPublisher, options: MeshSelfReportOptions, state: MeshSelfReportState);
+    get name(): string;
+    handleAsync(context: TContext, next: NextFunc): Promise<void>;
+    private shouldPublish;
+    private publishBestEffortAsync;
+}

package/dist/MeshSelfReportMiddleware.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MeshSelfReportMiddleware = void 0;
+const mesh_contracts_1 = require("@benzenejs/mesh-contracts");
+/**
+ * After a real request/message completes, opportunistically publishes this service's current spec/health via
+ * the injected `IMeshReportPublisher` - piggybacking on real traffic rather than a dedicated scheduled
+ * reporter. Throttled by `MeshSelfReportOptions.minimumIntervalMs` (tracked in `MeshSelfReportState`).
+ *
+ * Publishing is fire-and-forget and fully best-effort: it never delays the wrapped response, and a publish
+ * failure (or a provider throwing) is swallowed - side-channel telemetry, not part of the primary path.
+ */
+class MeshSelfReportMiddleware {
+    publisher;
+    options;
+    state;
+    constructor(publisher, options, state) {
+        this.publisher = publisher;
+        this.options = options;
+        this.state = state;
+    }
+    get name() {
+        return 'MeshSelfReport';
+    }
+    async handleAsync(context, next) {
+        await next();
+        if (this.shouldPublish()) {
+            // Fire-and-forget: not awaited, so the wrapped response is never delayed. Errors are handled inside.
+            void this.publishBestEffortAsync();
+        }
+    }
+    shouldPublish() {
+        const last = this.state.lastPublishedAtUtc;
+        return last === undefined || Date.now() - last >= this.options.minimumIntervalMs;
+    }
+    async publishBestEffortAsync() {
+        // Set before attempting the publish, not after - so a burst of concurrent requests don't all see "no
+        // recent publish" and race. A failed attempt still counts toward the throttle window, deliberately.
+        this.state.lastPublishedAtUtc = Date.now();
+        try {
+            let specJson;
+            let health;
+            let error;
+            try {
+                specJson = await this.options.specProvider();
+            }
+            catch (ex) {
+                error = errorName(ex);
+            }
+            try {
+                health = await this.options.healthProvider();
+            }
+            catch (ex) {
+                error ??= errorName(ex);
+            }
+            const report = new mesh_contracts_1.MeshServiceReport(this.options.serviceName, Date.now(), specJson, health, error);
+            await this.publisher.publishAsync(report);
+        }
+        catch {
+            // Best-effort side-channel telemetry - a publish failure must never affect the primary path.
+        }
+    }
+}
+exports.MeshSelfReportMiddleware = MeshSelfReportMiddleware;
+/** Mirrors C#'s `ex.GetType().Name`. */
+function errorName(ex) {
+    return ex instanceof Error ? ex.name : typeof ex;
+}

package/dist/MeshSelfReportOptions.d.ts

@@ -0,0 +1,26 @@
+/** Port of Benzene.Mesh.Reporting.MeshSelfReportOptions. */
+import { HealthCheckResponse } from '@benzenejs/health-checks-core';
+/** Default minimum interval between opportunistic publishes: 5 minutes, in milliseconds. */
+export declare const DefaultMinimumIntervalMs: number;
+/**
+ * Configures `MeshSelfReportMiddleware` - how to name this service, how to obtain its own current
+ * spec/health on demand, and how often that's allowed to happen. The spec/health providers are delegates
+ * (a self-reporting service already knows how to produce both), keeping this package free of a dependency
+ * on the spec/health generators.
+ *
+ * `Func<Task<string?>>`/`Func<Task<HealthCheckResponse?>>` -> `() => Promise<... | undefined>`; `TimeSpan`
+ * -> millisecond `number`.
+ */
+export declare class MeshSelfReportOptions {
+    readonly serviceName: string;
+    readonly specProvider: () => Promise<string | undefined>;
+    readonly healthProvider: () => Promise<HealthCheckResponse | undefined>;
+    readonly minimumIntervalMs: number;
+    /**
+     * @param serviceName This service's name (matches its registry entry's `name`).
+     * @param specProvider Produces this service's current spec document, verbatim, or `undefined` if unavailable.
+     * @param healthProvider Produces this service's current aggregated health response, or `undefined` if unavailable.
+     * @param minimumIntervalMs Minimum time between opportunistic publishes (ms). Defaults to 5 minutes.
+     */
+    constructor(serviceName: string, specProvider: () => Promise<string | undefined>, healthProvider: () => Promise<HealthCheckResponse | undefined>, minimumIntervalMs?: number);
+}

package/dist/MeshSelfReportOptions.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MeshSelfReportOptions = exports.DefaultMinimumIntervalMs = void 0;
+/** Default minimum interval between opportunistic publishes: 5 minutes, in milliseconds. */
+exports.DefaultMinimumIntervalMs = 5 * 60 * 1000;
+/**
+ * Configures `MeshSelfReportMiddleware` - how to name this service, how to obtain its own current
+ * spec/health on demand, and how often that's allowed to happen. The spec/health providers are delegates
+ * (a self-reporting service already knows how to produce both), keeping this package free of a dependency
+ * on the spec/health generators.
+ *
+ * `Func<Task<string?>>`/`Func<Task<HealthCheckResponse?>>` -> `() => Promise<... | undefined>`; `TimeSpan`
+ * -> millisecond `number`.
+ */
+class MeshSelfReportOptions {
+    serviceName;
+    specProvider;
+    healthProvider;
+    minimumIntervalMs;
+    /**
+     * @param serviceName This service's name (matches its registry entry's `name`).
+     * @param specProvider Produces this service's current spec document, verbatim, or `undefined` if unavailable.
+     * @param healthProvider Produces this service's current aggregated health response, or `undefined` if unavailable.
+     * @param minimumIntervalMs Minimum time between opportunistic publishes (ms). Defaults to 5 minutes.
+     */
+    constructor(serviceName, specProvider, healthProvider, minimumIntervalMs = exports.DefaultMinimumIntervalMs) {
+        this.serviceName = serviceName;
+        this.specProvider = specProvider;
+        this.healthProvider = healthProvider;
+        this.minimumIntervalMs = minimumIntervalMs;
+    }
+}
+exports.MeshSelfReportOptions = MeshSelfReportOptions;

package/dist/MeshSelfReportState.d.ts

@@ -0,0 +1,14 @@
+/** Port of Benzene.Mesh.Reporting.MeshSelfReportState. */
+/**
+ * Tracks when `MeshSelfReportMiddleware` last published, so the `minimumIntervalMs` throttle survives across
+ * requests within one running process. Registered as a singleton (not static) so independent pipelines
+ * don't share type-local state.
+ *
+ * C#'s `Interlocked`-guarded `long` ticks collapse to a plain `number | undefined` (epoch ms): Node is
+ * single-threaded, so there's no torn read/write to guard against. On an ephemeral host this resets on cold
+ * start (an idle instance stops reporting rather than reporting stale data forever).
+ */
+export declare class MeshSelfReportState {
+    /** When the middleware last published (epoch ms), or `undefined` if it never has. */
+    lastPublishedAtUtc: number | undefined;
+}

package/dist/MeshSelfReportState.js

@@ -0,0 +1,18 @@
+"use strict";
+/** Port of Benzene.Mesh.Reporting.MeshSelfReportState. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MeshSelfReportState = void 0;
+/**
+ * Tracks when `MeshSelfReportMiddleware` last published, so the `minimumIntervalMs` throttle survives across
+ * requests within one running process. Registered as a singleton (not static) so independent pipelines
+ * don't share type-local state.
+ *
+ * C#'s `Interlocked`-guarded `long` ticks collapse to a plain `number | undefined` (epoch ms): Node is
+ * single-threaded, so there's no torn read/write to guard against. On an ephemeral host this resets on cold
+ * start (an idle instance stops reporting rather than reporting stale data forever).
+ */
+class MeshSelfReportState {
+    /** When the middleware last published (epoch ms), or `undefined` if it never has. */
+    lastPublishedAtUtc;
+}
+exports.MeshSelfReportState = MeshSelfReportState;

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Port of Benzene.Mesh.Reporting - push-based mesh self-reporting for services an aggregator can't poll:
+ * `HttpMeshReportPublisher` (POSTs a `MeshServiceReport` to an aggregator's ingestion endpoint) and
+ * `MeshSelfReportMiddleware` (opportunistically publishes the service's own spec/health after real traffic,
+ * throttled and best-effort), wired via `addMeshHttpReporting`/`addMeshSelfReport`/`useMeshSelfReport`.
+ */
+export * from './MeshReportingOptions';
+export * from './HttpMeshReportPublisher';
+export * from './MeshSelfReportOptions';
+export * from './MeshSelfReportState';
+export * from './MeshSelfReportMiddleware';
+export * from './Extensions';

package/dist/index.js

@@ -0,0 +1,28 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Port of Benzene.Mesh.Reporting - push-based mesh self-reporting for services an aggregator can't poll:
+ * `HttpMeshReportPublisher` (POSTs a `MeshServiceReport` to an aggregator's ingestion endpoint) and
+ * `MeshSelfReportMiddleware` (opportunistically publishes the service's own spec/health after real traffic,
+ * throttled and best-effort), wired via `addMeshHttpReporting`/`addMeshSelfReport`/`useMeshSelfReport`.
+ */
+__exportStar(require("./MeshReportingOptions"), exports);
+__exportStar(require("./HttpMeshReportPublisher"), exports);
+__exportStar(require("./MeshSelfReportOptions"), exports);
+__exportStar(require("./MeshSelfReportState"), exports);
+__exportStar(require("./MeshSelfReportMiddleware"), exports);
+__exportStar(require("./Extensions"), exports);

package/package.json

@@ -1,6 +1,18 @@
 {
   "name": "@benzenejs/mesh-reporting",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-beta.2",
+  "description": "TypeScript port of Benzene.Mesh.Reporting",
+  "license": "MIT",
+  "type": "commonjs",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "dependencies": {
+    "@benzenejs/abstractions": "0.1.0-beta.2",
+    "@benzenejs/abstractions-middleware": "0.1.0-beta.2",
+    "@benzenejs/health-checks-core": "0.1.0-beta.2",
+    "@benzenejs/mesh-contracts": "0.1.0-beta.2"
+  },
+  "files": [
+    "dist"
+  ]
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.