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

package/dist/IMeshArtifactStore.d.ts

@@ -0,0 +1,25 @@
+/** Port of Benzene.Mesh.Aggregator.IMeshArtifactStore. */
+import { ServiceToken } from '@benzenejs/abstractions';
+/**
+ * Publishes (and reads back) the JSON artifacts a `MeshAggregator` produces.
+ *
+ * Kept as a small port so a blob-storage adapter (S3, Azure Blob) can be added later as a drop-in
+ * implementation of this interface, without changing `MeshAggregator`'s own logic. Only a local-disk
+ * implementation (`FileSystemMeshArtifactStore`) ships in this package.
+ */
+export interface IMeshArtifactStore {
+    /**
+     * Writes `content` to `relativePath`, creating or overwriting it.
+     * @param relativePath A path relative to the store's root, e.g. `"manifest.json"` or `"services/orders-api.json"`.
+     * @param content The content to write.
+     */
+    publishAsync(relativePath: string, content: string): Promise<void>;
+    /**
+     * Reads the content previously published at `relativePath`, if any.
+     * @param relativePath A path relative to the store's root.
+     * @returns The content, or `undefined` if nothing has been published at that path.
+     */
+    tryReadAsync(relativePath: string): Promise<string | undefined>;
+}
+/** Container token: the aggregator resolves the configured artifact store by this interface. */
+export declare const IMeshArtifactStore: ServiceToken<IMeshArtifactStore>;

package/dist/IMeshArtifactStore.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IMeshArtifactStore = void 0;
+/** Port of Benzene.Mesh.Aggregator.IMeshArtifactStore. */
+const abstractions_1 = require("@benzenejs/abstractions");
+/** Container token: the aggregator resolves the configured artifact store by this interface. */
+exports.IMeshArtifactStore = (0, abstractions_1.serviceToken)('IMeshArtifactStore');

package/dist/IMeshServiceSource.d.ts

@@ -0,0 +1,44 @@
+/** Port of Benzene.Mesh.Aggregator.IMeshServiceSource. */
+import { ServiceToken } from '@benzenejs/abstractions';
+import { MeshServiceRegistryEntry } from '@benzenejs/mesh-contracts';
+/**
+ * Fetches a registered service's spec and health documents however fits that service's
+ * `MeshServiceRegistryEntry.source` - HTTP (`HttpMeshServiceSource`, the only implementation this package
+ * ships), an AWS Lambda Invoke, or any other transport an adapter package chooses to add. `MeshAggregator`
+ * is decoupled from any one transport by depending on this port rather than a `fetch`/`HttpClient` directly.
+ *
+ * `CancellationToken` -> optional `AbortSignal`. C#'s default-interface-method `TryFetchSpecAsync` (returns
+ * a completed `null` task) has no TS interface default; sources that don't override it are handled by the
+ * aggregator treating a missing method as "not supported" - so it is declared optional here.
+ */
+export interface IMeshServiceSource {
+    /**
+     * The `MeshServiceRegistryEntry.source` value this source answers for (see `MeshServiceSource`).
+     * Matched case-insensitively.
+     */
+    readonly key: string;
+    /**
+     * Fetches `entry`'s spec document, verbatim, as raw JSON text. Should throw on failure (connection
+     * error, timeout, non-success response) rather than returning nothing - `MeshAggregator` catches and
+     * records the exception's type name.
+     */
+    fetchSpecAsync(entry: MeshServiceRegistryEntry, cancellationToken?: AbortSignal): Promise<string>;
+    /**
+     * Fetches `entry`'s health check response, verbatim, as raw JSON text (to be deserialized by the
+     * caller). Should throw only on a genuine fetch failure - an unhealthy-but-successfully-fetched response
+     * (e.g. HTTP 503 with a valid body) must still be returned, not treated as a failure, so it can be
+     * distinguished from a truly unreachable service.
+     */
+    fetchHealthAsync(entry: MeshServiceRegistryEntry, cancellationToken?: AbortSignal): Promise<string>;
+    /**
+     * Fetches `entry`'s spec in an alternate representation (e.g. `"asyncapi"` - the same `spec` endpoint's
+     * other `type`), or `undefined` when this source can't serve that type. Best-effort and additive: unlike
+     * {@link fetchSpecAsync} (whose failure marks the service unreachable), a source that doesn't support
+     * alternate spec types just returns `undefined` and the aggregator omits that service from whatever
+     * artifact is built on it. Optional (C#'s default interface method returned `null`), so existing sources
+     * don't have to implement it.
+     */
+    tryFetchSpecAsync?(entry: MeshServiceRegistryEntry, specType: string, cancellationToken?: AbortSignal): Promise<string | undefined>;
+}
+/** Container token: sources are registered and collected via `getServices(IMeshServiceSource)`. */
+export declare const IMeshServiceSource: ServiceToken<IMeshServiceSource>;

package/dist/IMeshServiceSource.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IMeshServiceSource = void 0;
+/** Port of Benzene.Mesh.Aggregator.IMeshServiceSource. */
+const abstractions_1 = require("@benzenejs/abstractions");
+/** Container token: sources are registered and collected via `getServices(IMeshServiceSource)`. */
+exports.IMeshServiceSource = (0, abstractions_1.serviceToken)('IMeshServiceSource');

package/dist/MeshAggregateMessageHandler.d.ts

@@ -0,0 +1,20 @@
+/** Port of Benzene.Mesh.Aggregator.MeshAggregateMessageHandler. */
+import { IBenzeneResultOf, VoidResult } from '@benzenejs/abstractions';
+import { IMessageHandler } from '@benzenejs/abstractions-message-handlers';
+import { MeshManifest, MeshServiceRegistry } from '@benzenejs/mesh-contracts';
+import { MeshAggregator } from './MeshAggregator';
+/**
+ * Exposes `MeshAggregator.runOnceAsync` as a Benzene message handler - reachable on whatever transport the
+ * host already runs (HTTP, a scheduled invocation, a queue message) with no bespoke hosting code.
+ *
+ * The C# `[HttpEndpoint("POST", "/mesh/aggregate")]` + `[Message("benzene:mesh:aggregate")]` attributes are declared
+ * in `addMeshAggregator` (as registered `IHttpEndpointDefinition`/`IMessageHandlerDefinition`s) rather than
+ * class decorators - the port's Extensions-registration convention, since JS has no assembly scan.
+ * `Void` request -> `VoidResult`.
+ */
+export declare class MeshAggregateMessageHandler implements IMessageHandler<VoidResult, MeshManifest> {
+    private readonly aggregator;
+    private readonly registry;
+    constructor(aggregator: MeshAggregator, registry: MeshServiceRegistry);
+    handleAsync(_request: VoidResult): Promise<IBenzeneResultOf<MeshManifest>>;
+}

package/dist/MeshAggregateMessageHandler.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MeshAggregateMessageHandler = void 0;
+const results_1 = require("@benzenejs/results");
+/**
+ * Exposes `MeshAggregator.runOnceAsync` as a Benzene message handler - reachable on whatever transport the
+ * host already runs (HTTP, a scheduled invocation, a queue message) with no bespoke hosting code.
+ *
+ * The C# `[HttpEndpoint("POST", "/mesh/aggregate")]` + `[Message("benzene:mesh:aggregate")]` attributes are declared
+ * in `addMeshAggregator` (as registered `IHttpEndpointDefinition`/`IMessageHandlerDefinition`s) rather than
+ * class decorators - the port's Extensions-registration convention, since JS has no assembly scan.
+ * `Void` request -> `VoidResult`.
+ */
+class MeshAggregateMessageHandler {
+    aggregator;
+    registry;
+    constructor(aggregator, registry) {
+        this.aggregator = aggregator;
+        this.registry = registry;
+    }
+    async handleAsync(_request) {
+        const manifest = await this.aggregator.runOnceAsync(this.registry);
+        return results_1.BenzeneResult.ok(manifest);
+    }
+}
+exports.MeshAggregateMessageHandler = MeshAggregateMessageHandler;

package/dist/MeshAggregator.d.ts

@@ -0,0 +1,67 @@
+import { IMeshUsageSource, MeshManifest, MeshServiceRegistry } from '@benzenejs/mesh-contracts';
+import { IMeshArtifactStore } from './IMeshArtifactStore';
+import { IMeshServiceSource } from './IMeshServiceSource';
+/**
+ * Polls every service in a `MeshServiceRegistry` for its spec and health documents, computes contract-drift,
+ * and publishes the resulting catalog to an `IMeshArtifactStore`. `System.Text.Json` (nodes + document) ->
+ * native `JSON.parse`/`JSON.stringify`; `DateTimeOffset` clock -> `() => number` (epoch ms); `Task.WhenAll`
+ * -> `Promise.all`; LINQ `GroupBy`/`ToDictionary` -> `Map`s.
+ */
+export declare class MeshAggregator {
+    private readonly sources;
+    private readonly store;
+    private readonly clock;
+    private readonly usageSources;
+    /**
+     * @param sources Every registered `IMeshServiceSource`, keyed by `key` (case-insensitive) to resolve each
+     * entry's `source` against. An entry whose `source` has no matching source here is recorded as that
+     * service's own fetch error, not a run-wide failure.
+     * @param store Where generated catalog artifacts are published (and, for drift comparison, read back from).
+     * @param clock Supplies the current time (epoch ms); defaults to `Date.now`. Overridable for deterministic tests.
+     * @param usageSources Every registered `IMeshUsageSource`. Optional and empty by default: with none
+     * registered no `usage.json` is ever published, so the artifact's absence keeps meaning "no usage feed wired".
+     */
+    constructor(sources: Iterable<IMeshServiceSource>, store: IMeshArtifactStore, clock?: () => number, usageSources?: Iterable<IMeshUsageSource>);
+    /**
+     * Polls every registered service once, publishing a `services/{name}.json` snapshot per service and a
+     * top-level `manifest.json` summarizing all of them. A single service's spec/health fetch failing (or
+     * timing out) does not prevent the rest from being processed and published. Services are polled
+     * concurrently, so one slow service adds to the run's total time only up to its own timeout.
+     */
+    runOnceAsync(registry: MeshServiceRegistry): Promise<MeshManifest>;
+    /**
+     * Polls every registered usage adapter (bounded by the per-service timeout each; a throwing/timing-out
+     * source contributes nothing rather than failing the run) and merges the reports into one `MeshUsage`.
+     * Returns `undefined` when no source reported.
+     */
+    private fetchUsageAsync;
+    private fetchOneUsageAsync;
+    /**
+     * Builds the composite AsyncAPI document from every service that returned an AsyncAPI doc, passing each
+     * service's reserved-topic ids (from its benzene spec) so utility channels are dropped.
+     */
+    private buildCompositeAsyncApi;
+    /**
+     * Derives the structural topology: for every domain topic a service declares it *sends* (the spec's
+     * `events` and `sends`), an edge to every service that *handles* it (the spec's `requests`). Where the merged `usage`
+     * feed can attribute a topic's observed traffic to a specific edge *unambiguously*, that edge also carries
+     * a usage-derived req/min and (when the outcome is classifiable) error rate.
+     */
+    private buildTopology;
+    /**
+     * Builds the cross-service topic catalog: every (topic, version) pair seen anywhere in the fleet, who
+     * consumes it (spec `requests`) and who produces it (spec `events`), plus an informational status.
+     */
+    private buildTopicCatalog;
+    /**
+     * Annotates the freshly-built catalog with what changed since the previous run, by reading back the
+     * store's own last `topics.json`. A first run, or an unreadable/unparseable previous catalog, claims no
+     * changes at all - never a wall of "added" noise, and never a failed run.
+     */
+    private applyCatalogDiffAsync;
+    private buildServiceAsync;
+    private fetchSpecAsync;
+    private fetchHealthAsync;
+    private fetchAsyncApiAsync;
+    private resolveSource;
+}