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

package/dist/ArtifactStoreMeshReportPublisher.d.ts

@@ -0,0 +1,18 @@
+/** Port of Benzene.Mesh.Aggregator.ArtifactStoreMeshReportPublisher. */
+import { IMeshReportPublisher, MeshServiceReport } from '@benzenejs/mesh-contracts';
+import { IMeshArtifactStore } from './IMeshArtifactStore';
+/**
+ * The direct-write `IMeshReportPublisher` - turns a self-reported `MeshServiceReport` into a full
+ * `MeshServiceSnapshot` (via the same `MeshSnapshotBuilder` a pulled fetch uses, so both compute
+ * `MeshServiceSnapshot.contractDrift` identically) and writes it straight into the shared
+ * `IMeshArtifactStore` - the same `services/{name}.json` path `MeshAggregator` itself writes to.
+ *
+ * Fits a reporter colocated with the aggregator's own storage (e.g. sharing a mounted volume in a Docker
+ * Compose deployment). A reporter that isn't colocated should use `@benzenejs/mesh-reporting`'s
+ * `HttpMeshReportPublisher` instead. `JsonSerializerOptions` (camelCase, indented) -> `JSON.stringify(x, null, 2)`.
+ */
+export declare class ArtifactStoreMeshReportPublisher implements IMeshReportPublisher {
+    private readonly store;
+    constructor(store: IMeshArtifactStore);
+    publishAsync(report: MeshServiceReport): Promise<void>;
+}

package/dist/ArtifactStoreMeshReportPublisher.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ArtifactStoreMeshReportPublisher = void 0;
+const MeshSnapshotBuilder_1 = require("./MeshSnapshotBuilder");
+/**
+ * The direct-write `IMeshReportPublisher` - turns a self-reported `MeshServiceReport` into a full
+ * `MeshServiceSnapshot` (via the same `MeshSnapshotBuilder` a pulled fetch uses, so both compute
+ * `MeshServiceSnapshot.contractDrift` identically) and writes it straight into the shared
+ * `IMeshArtifactStore` - the same `services/{name}.json` path `MeshAggregator` itself writes to.
+ *
+ * Fits a reporter colocated with the aggregator's own storage (e.g. sharing a mounted volume in a Docker
+ * Compose deployment). A reporter that isn't colocated should use `@benzenejs/mesh-reporting`'s
+ * `HttpMeshReportPublisher` instead. `JsonSerializerOptions` (camelCase, indented) -> `JSON.stringify(x, null, 2)`.
+ */
+class ArtifactStoreMeshReportPublisher {
+    store;
+    constructor(store) {
+        this.store = store;
+    }
+    async publishAsync(report) {
+        const snapshot = await MeshSnapshotBuilder_1.MeshSnapshotBuilder.buildAsync(this.store, report.name, report.reportedAtUtc, report.specJson, report.health, report.error);
+        await this.store.publishAsync(`services/${report.name}.json`, JSON.stringify(snapshot, null, 2));
+    }
+}
+exports.ArtifactStoreMeshReportPublisher = ArtifactStoreMeshReportPublisher;

package/dist/AsyncApiCompositor.d.ts

@@ -0,0 +1,21 @@
+/** One service's fetched AsyncAPI doc plus what the merge needs to namespace/filter it. */
+export interface ServiceDocument {
+    /** The service name - the namespace discriminator (channels/operations/schemas/tags). */
+    readonly serviceName: string;
+    /** The service's raw AsyncAPI 3.0 JSON. */
+    readonly asyncApiJson: string;
+    /**
+     * Extra reserved (utility) topic ids whose channels/operations are skipped. Every `benzene:`-prefixed topic
+     * is skipped regardless (`BenzeneTopic.isReserved`): a Contract Document no longer lists reserved topics,
+     * so the prefix is the rule.
+     */
+    readonly reservedTopics: ReadonlySet<string>;
+}
+export declare const AsyncApiCompositor: {
+    /**
+     * Merges the given services' AsyncAPI 3.0 docs into one composite AsyncAPI 3.0 JSON document. A service
+     * whose doc is missing/unparseable is skipped (best-effort); an empty input still produces a valid empty
+     * document, so a published `asyncapi.json` is always loadable. `generatedAt` is epoch ms.
+     */
+    merge(services: readonly ServiceDocument[], generatedAt: number): string;
+};

package/dist/AsyncApiCompositor.js

@@ -0,0 +1,285 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AsyncApiCompositor = void 0;
+/** Port of Benzene.Mesh.Aggregator.AsyncApiCompositor. */
+const abstractions_1 = require("@benzenejs/abstractions");
+const SchemaRefPrefix = '#/components/schemas/';
+const ChannelRefPrefix = '#/channels/';
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isArray(value) {
+    return Array.isArray(value);
+}
+exports.AsyncApiCompositor = {
+    /**
+     * Merges the given services' AsyncAPI 3.0 docs into one composite AsyncAPI 3.0 JSON document. A service
+     * whose doc is missing/unparseable is skipped (best-effort); an empty input still produces a valid empty
+     * document, so a published `asyncapi.json` is always loadable. `generatedAt` is epoch ms.
+     */
+    merge(services, generatedAt) {
+        const channels = {};
+        const operations = {};
+        const schemas = {};
+        const tags = [];
+        const usedOperationKeys = new Set();
+        let merged = 0;
+        for (const service of services) {
+            const doc = tryParse(service.asyncApiJson);
+            if (doc === undefined) {
+                continue;
+            }
+            merged++;
+            tags.push({ name: service.serviceName });
+            const ns = slug(service.serviceName);
+            // 1) Namespace + move component schemas (rewriting every schema $ref across the doc first, so
+            //    channel-message payload refs and nested inter-schema refs all point at the new keys).
+            const schemaRenames = new Map();
+            if (isObject(doc.components) && isObject(doc.components.schemas)) {
+                for (const key of Object.keys(doc.components.schemas)) {
+                    schemaRenames.set(key, schemaKey(service.serviceName, key));
+                }
+            }
+            rewriteSchemaRefs(doc, schemaRenames);
+            if (isObject(doc.components) && isObject(doc.components.schemas)) {
+                const serviceSchemas = doc.components.schemas;
+                for (const [key, value] of Object.entries(serviceSchemas)) {
+                    schemas[schemaRenames.get(key)] = structuredClone(value);
+                }
+            }
+            // 2) Map ALL channel keys old->new (namespaced), capturing each channel's address and a clone.
+            //    Channels are emitted below only if a surviving (non-reserved) operation references them - so
+            //    reserved request channels AND their reply channels fall away regardless of the reply-suffix a
+            //    service happens to use.
+            const channelKeyMap = new Map();
+            const channelAddress = new Map();
+            const clonedChannels = new Map();
+            if (isObject(doc.channels)) {
+                for (const [key, value] of Object.entries(doc.channels)) {
+                    if (!isObject(value)) {
+                        continue;
+                    }
+                    const newKey = `${ns}_${key}`;
+                    channelKeyMap.set(key, newKey);
+                    channelAddress.set(key, typeof value.address === 'string' ? value.address : key);
+                    clonedChannels.set(newKey, structuredClone(value));
+                }
+            }
+            // 3) Namespace operations, dropping any whose channel is a reserved (utility) topic, and rewriting
+            //    their channel/message/reply $refs onto the namespaced channel keys. An operation's primary
+            //    channel address IS the topic id, so reserved detection needs no suffix knowledge.
+            const referencedChannelKeys = new Set();
+            if (isObject(doc.operations)) {
+                for (const [key, value] of Object.entries(doc.operations)) {
+                    if (!isObject(value)) {
+                        continue;
+                    }
+                    const operationObj = structuredClone(value);
+                    const primaryKey = channelKeyOf(operationObj.channel);
+                    if (primaryKey === undefined ||
+                        !channelKeyMap.has(primaryKey) ||
+                        service.reservedTopics.has(channelAddress.get(primaryKey)) ||
+                        abstractions_1.BenzeneTopic.isReserved(channelAddress.get(primaryKey))) {
+                        continue; // no resolvable channel, or a reserved/utility operation - drop it
+                    }
+                    rewriteChannelRef(operationObj.channel, channelKeyMap);
+                    rewriteMessageRefs(operationObj.messages, channelKeyMap);
+                    referencedChannelKeys.add(channelKeyMap.get(primaryKey));
+                    if (isObject(operationObj.reply)) {
+                        const reply = operationObj.reply;
+                        const replyKey = channelKeyOf(reply.channel);
+                        if (replyKey !== undefined && channelKeyMap.has(replyKey)) {
+                            rewriteChannelRef(reply.channel, channelKeyMap);
+                            rewriteMessageRefs(reply.messages, channelKeyMap);
+                            referencedChannelKeys.add(channelKeyMap.get(replyKey));
+                        }
+                        else {
+                            delete operationObj.reply;
+                        }
+                    }
+                    tagOperation(operationObj, service.serviceName);
+                    operations[uniqueKey(`${ns}_${key}`, usedOperationKeys)] = operationObj;
+                }
+            }
+            // 4) Emit only the channels a surviving operation references.
+            for (const referenced of referencedChannelKeys) {
+                const channelObj = clonedChannels.get(referenced);
+                if (channelObj !== undefined) {
+                    channels[referenced] = channelObj;
+                }
+            }
+        }
+        // Reserved-channel drops can orphan the schemas only those channels' messages referenced; drop any
+        // component schema not reachable from a retained channel (validators flag unused components).
+        pruneUnusedSchemas(channels, schemas);
+        const document = {
+            asyncapi: '3.0.0',
+            id: 'urn:benzene:mesh:composite',
+            defaultContentType: 'application/json',
+            info: {
+                title: 'Benzene Mesh — Composite AsyncAPI',
+                version: new Date(generatedAt).toISOString(),
+                description: `Composite of ${merged} service(s)' AsyncAPI specs across the mesh, generated by Benzene Mesh.`,
+                tags,
+            },
+            channels,
+            operations,
+            components: { schemas },
+        };
+        return JSON.stringify(document, null, 2);
+    },
+};
+function tryParse(json) {
+    if (json.trim().length === 0) {
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(json);
+        return isObject(parsed) ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function channelKeyOf(channelRefNode) {
+    if (isObject(channelRefNode) && typeof channelRefNode.$ref === 'string' && channelRefNode.$ref.startsWith(ChannelRefPrefix)) {
+        const rest = channelRefNode.$ref.substring(ChannelRefPrefix.length);
+        const slash = rest.indexOf('/');
+        return slash < 0 ? rest : rest.substring(0, slash);
+    }
+    return undefined;
+}
+function rewriteChannelRef(channelRefNode, channelKeyMap) {
+    if (isObject(channelRefNode) && typeof channelRefNode.$ref === 'string') {
+        channelRefNode.$ref = rewritePointer(channelRefNode.$ref, channelKeyMap);
+    }
+}
+function rewriteMessageRefs(messagesNode, channelKeyMap) {
+    if (!isArray(messagesNode)) {
+        return;
+    }
+    for (const message of messagesNode) {
+        if (isObject(message) && typeof message.$ref === 'string') {
+            message.$ref = rewritePointer(message.$ref, channelKeyMap);
+        }
+    }
+}
+/** Rewrites the channel-id segment of a `#/channels/<key>[/messages/<msg>]` pointer via the map. */
+function rewritePointer(reference, channelKeyMap) {
+    if (!reference.startsWith(ChannelRefPrefix)) {
+        return reference;
+    }
+    const rest = reference.substring(ChannelRefPrefix.length);
+    const slash = rest.indexOf('/');
+    const oldKey = slash < 0 ? rest : rest.substring(0, slash);
+    const tail = slash < 0 ? '' : rest.substring(slash);
+    const newKey = channelKeyMap.get(oldKey);
+    return newKey !== undefined ? ChannelRefPrefix + newKey + tail : reference;
+}
+function tagOperation(operation, serviceName) {
+    let tags = operation.tags;
+    if (!isArray(tags)) {
+        tags = [];
+        operation.tags = tags;
+    }
+    tags.push({ name: serviceName });
+}
+function uniqueKey(candidate, used) {
+    let unique = candidate;
+    let suffix = 2;
+    while (used.has(unique)) {
+        unique = `${candidate}_${suffix++}`;
+    }
+    used.add(unique);
+    return unique;
+}
+/** Removes component schemas not reachable from any retained channel (following $refs transitively). */
+function pruneUnusedSchemas(channels, schemas) {
+    const reachable = new Set();
+    const queue = [];
+    for (const name of findSchemaRefNames(channels)) {
+        if (!reachable.has(name)) {
+            reachable.add(name);
+            queue.push(name);
+        }
+    }
+    while (queue.length > 0) {
+        const name = queue.shift();
+        const schema = schemas[name];
+        if (schema === undefined) {
+            continue;
+        }
+        for (const nested of findSchemaRefNames(schema)) {
+            if (!reachable.has(nested)) {
+                reachable.add(nested);
+                queue.push(nested);
+            }
+        }
+    }
+    for (const key of Object.keys(schemas)) {
+        if (!reachable.has(key)) {
+            delete schemas[key];
+        }
+    }
+}
+function findSchemaRefNames(node) {
+    const results = [];
+    walk(node, results);
+    return results;
+    function walk(n, into) {
+        if (isObject(n)) {
+            if (typeof n.$ref === 'string' && n.$ref.startsWith(SchemaRefPrefix)) {
+                into.push(n.$ref.substring(SchemaRefPrefix.length));
+            }
+            for (const [key, value] of Object.entries(n)) {
+                if (key !== '$ref') {
+                    walk(value, into);
+                }
+            }
+        }
+        else if (isArray(n)) {
+            for (const item of n) {
+                walk(item, into);
+            }
+        }
+    }
+}
+function rewriteSchemaRefs(node, renames) {
+    if (isObject(node)) {
+        if (typeof node.$ref === 'string' && node.$ref.startsWith(SchemaRefPrefix)) {
+            const name = node.$ref.substring(SchemaRefPrefix.length);
+            const renamed = renames.get(name);
+            if (renamed !== undefined) {
+                node.$ref = SchemaRefPrefix + renamed;
+            }
+        }
+        for (const [key, value] of Object.entries(node)) {
+            if (key !== '$ref') {
+                rewriteSchemaRefs(value, renames);
+            }
+        }
+    }
+    else if (isArray(node)) {
+        for (const item of node) {
+            rewriteSchemaRefs(item, renames);
+        }
+    }
+}
+function schemaKey(serviceName, typeName) {
+    const prefix = slug(serviceName)
+        .split('-')
+        .filter((part) => part.length > 0)
+        .map((part) => part.charAt(0).toUpperCase() + part.substring(1))
+        .join('');
+    return prefix.length === 0 ? typeName : prefix + '_' + typeName;
+}
+function slug(value) {
+    let lowered = Array.from((value ?? '').trim().toLowerCase())
+        .map((c) => (/[\p{L}\p{N}]/u.test(c) ? c : '-'))
+        .join('');
+    while (lowered.includes('--')) {
+        lowered = lowered.replace(/--/g, '-');
+    }
+    lowered = lowered.replace(/^-+/, '').replace(/-+$/, '');
+    return lowered.length === 0 ? 'service' : lowered;
+}

package/dist/Extensions.d.ts

@@ -0,0 +1,19 @@
+/** Port of Benzene.Mesh.Aggregator.Extensions. */
+import { IBenzeneServiceContainer, IServiceResolver } from '@benzenejs/abstractions';
+import { MeshServiceRegistry } from '@benzenejs/mesh-contracts';
+import { IMeshArtifactStore } from './IMeshArtifactStore';
+/**
+ * Registers `MeshAggregator` (backed by a `FileSystemMeshArtifactStore` when given a directory string, or a
+ * caller-supplied `IMeshArtifactStore` factory for a blob-storage adapter) against the given service
+ * registry, plus the three mesh message handlers and their HTTP endpoints. C# extension method + two
+ * overloads -> one free function whose third argument is a directory string or a store factory.
+ *
+ * Unlike the C# `AddMeshAggregator` (which registers only the infra and leaves handler *discovery* to the
+ * app's assembly-scanning `.AddMessageHandlers()`), the port also registers the handler definitions,
+ * endpoints and scoped factories here: JS has no assembly scan or constructor-parameter reflection, so a
+ * handler with dependencies can't be discovered or activated without an explicit factory (the same
+ * container-registration convention `@benzenejs/mesh-dispatch` uses). The default `HttpMeshServiceSource` and
+ * `ArtifactStoreMeshReportPublisher` are registered too; other adapter packages add their own
+ * `IMeshServiceSource`/`IMeshReportPublisher` alongside.
+ */
+export declare function addMeshAggregator(services: IBenzeneServiceContainer, registry: MeshServiceRegistry, artifactStore: string | ((resolver: IServiceResolver) => IMeshArtifactStore)): IBenzeneServiceContainer;

package/dist/Extensions.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addMeshAggregator = addMeshAggregator;
+/** Port of Benzene.Mesh.Aggregator.Extensions. */
+const abstractions_1 = require("@benzenejs/abstractions");
+const abstractions_message_handlers_1 = require("@benzenejs/abstractions-message-handlers");
+const core_message_handlers_1 = require("@benzenejs/core-message-handlers");
+const http_1 = require("@benzenejs/http");
+const mesh_contracts_1 = require("@benzenejs/mesh-contracts");
+const ArtifactStoreMeshReportPublisher_1 = require("./ArtifactStoreMeshReportPublisher");
+const FileSystemMeshArtifactStore_1 = require("./FileSystemMeshArtifactStore");
+const HttpMeshServiceSource_1 = require("./HttpMeshServiceSource");
+const IMeshArtifactStore_1 = require("./IMeshArtifactStore");
+const IMeshServiceSource_1 = require("./IMeshServiceSource");
+const MeshAggregateMessageHandler_1 = require("./MeshAggregateMessageHandler");
+const MeshAggregator_1 = require("./MeshAggregator");
+const MeshAnnotationPublisher_1 = require("./MeshAnnotationPublisher");
+const MeshAnnotationsMessageHandler_1 = require("./MeshAnnotationsMessageHandler");
+const MeshReportMessageHandler_1 = require("./MeshReportMessageHandler");
+/**
+ * Registers `MeshAggregator` (backed by a `FileSystemMeshArtifactStore` when given a directory string, or a
+ * caller-supplied `IMeshArtifactStore` factory for a blob-storage adapter) against the given service
+ * registry, plus the three mesh message handlers and their HTTP endpoints. C# extension method + two
+ * overloads -> one free function whose third argument is a directory string or a store factory.
+ *
+ * Unlike the C# `AddMeshAggregator` (which registers only the infra and leaves handler *discovery* to the
+ * app's assembly-scanning `.AddMessageHandlers()`), the port also registers the handler definitions,
+ * endpoints and scoped factories here: JS has no assembly scan or constructor-parameter reflection, so a
+ * handler with dependencies can't be discovered or activated without an explicit factory (the same
+ * container-registration convention `@benzenejs/mesh-dispatch` uses). The default `HttpMeshServiceSource` and
+ * `ArtifactStoreMeshReportPublisher` are registered too; other adapter packages add their own
+ * `IMeshServiceSource`/`IMeshReportPublisher` alongside.
+ */
+function addMeshAggregator(services, registry, artifactStore) {
+    const storeFactory = typeof artifactStore === 'string'
+        ? () => new FileSystemMeshArtifactStore_1.FileSystemMeshArtifactStore(artifactStore)
+        : artifactStore;
+    services.addSingletonInstance(mesh_contracts_1.MeshServiceRegistry, registry);
+    services.addSingletonFactory(IMeshArtifactStore_1.IMeshArtifactStore, (resolver) => storeFactory(resolver));
+    // The default IMeshServiceSource - other adapter packages add their own IMeshServiceSource registration
+    // alongside this one; MeshAggregator resolves all of them via getServices(IMeshServiceSource), keyed by key.
+    services.addSingletonFactory(IMeshServiceSource_1.IMeshServiceSource, () => new HttpMeshServiceSource_1.HttpMeshServiceSource());
+    // The default push-path IMeshReportPublisher - MeshReportMessageHandler resolves this.
+    services.addSingletonFactory(mesh_contracts_1.IMeshReportPublisher, (resolver) => new ArtifactStoreMeshReportPublisher_1.ArtifactStoreMeshReportPublisher(resolver.getService(IMeshArtifactStore_1.IMeshArtifactStore)));
+    services.addSingletonFactory(MeshAnnotationPublisher_1.MeshAnnotationPublisher, (resolver) => new MeshAnnotationPublisher_1.MeshAnnotationPublisher(resolver.getService(IMeshArtifactStore_1.IMeshArtifactStore)));
+    services.addSingletonFactory(MeshAggregator_1.MeshAggregator, (resolver) => new MeshAggregator_1.MeshAggregator(resolver.getServices(IMeshServiceSource_1.IMeshServiceSource), resolver.getService(IMeshArtifactStore_1.IMeshArtifactStore), undefined, resolver.getServices(mesh_contracts_1.IMeshUsageSource)));
+    registerHandler(services, 'benzene:mesh:aggregate', 'POST', '/mesh/aggregate', abstractions_1.VoidResult, mesh_contracts_1.MeshManifest, MeshAggregateMessageHandler_1.MeshAggregateMessageHandler, (resolver) => new MeshAggregateMessageHandler_1.MeshAggregateMessageHandler(resolver.getService(MeshAggregator_1.MeshAggregator), resolver.getService(mesh_contracts_1.MeshServiceRegistry)));
+    registerHandler(services, 'benzene:mesh:report', 'POST', '/mesh/report', mesh_contracts_1.MeshServiceReport, abstractions_1.VoidResult, MeshReportMessageHandler_1.MeshReportMessageHandler, (resolver) => new MeshReportMessageHandler_1.MeshReportMessageHandler(resolver.getService(mesh_contracts_1.IMeshReportPublisher)));
+    registerHandler(services, 'benzene:mesh:annotations:add', 'POST', '/mesh/annotations', mesh_contracts_1.MeshAnnotationRequest, mesh_contracts_1.MeshAnnotationThread, MeshAnnotationsMessageHandler_1.MeshAnnotationsMessageHandler, (resolver) => new MeshAnnotationsMessageHandler_1.MeshAnnotationsMessageHandler(resolver.getService(MeshAnnotationPublisher_1.MeshAnnotationPublisher)));
+    return services;
+}
+function registerHandler(services, topic, method, path, requestType, responseType, handlerType, factory) {
+    services.addScopedFactory(handlerType, factory);
+    services.addSingletonInstance(abstractions_message_handlers_1.IMessageHandlerDefinition, core_message_handlers_1.MessageHandlerDefinition.createInstance(topic, '', requestType, responseType, handlerType));
+    services.addSingletonInstance(http_1.IHttpEndpointDefinition, http_1.HttpEndpointDefinition.createInstance(method, path, topic));
+}

package/dist/FileSystemMeshArtifactStore.d.ts

@@ -0,0 +1,25 @@
+import { IMeshArtifactStore } from './IMeshArtifactStore';
+/**
+ * An `IMeshArtifactStore` that publishes artifacts to a directory on local disk.
+ *
+ * `File.WriteAllTextAsync`/`ReadAllTextAsync`/`Directory.CreateDirectory` -> `node:fs/promises`;
+ * `Path.Combine`/`Path.GetFullPath` -> `node:path`'s `resolve`. A missing file on read surfaces as
+ * `ENOENT`, mapped to `undefined` (C# `File.Exists` check).
+ */
+export declare class FileSystemMeshArtifactStore implements IMeshArtifactStore {
+    private readonly rootDirectory;
+    /**
+     * @param rootDirectory The directory artifacts are written under. Created on first write if it doesn't exist.
+     */
+    constructor(rootDirectory: string);
+    publishAsync(relativePath: string, content: string): Promise<void>;
+    tryReadAsync(relativePath: string): Promise<string | undefined>;
+    /**
+     * Resolves `relativePath` against the store root and asserts the result stays inside it. The relative
+     * path can carry a service name that originated in an untrusted push report (`services/{report.name}.json`),
+     * so a value like `"../../etc/passwd"` or a rooted path would otherwise let path-combination escape the
+     * root and read or overwrite an arbitrary file. Resolving to a full path and checking containment closes
+     * that traversal at the storage boundary, protecting every caller.
+     */
+    private resolveWithinRoot;
+}

package/dist/FileSystemMeshArtifactStore.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileSystemMeshArtifactStore = void 0;
+/** Port of Benzene.Mesh.Aggregator.FileSystemMeshArtifactStore. */
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+/**
+ * An `IMeshArtifactStore` that publishes artifacts to a directory on local disk.
+ *
+ * `File.WriteAllTextAsync`/`ReadAllTextAsync`/`Directory.CreateDirectory` -> `node:fs/promises`;
+ * `Path.Combine`/`Path.GetFullPath` -> `node:path`'s `resolve`. A missing file on read surfaces as
+ * `ENOENT`, mapped to `undefined` (C# `File.Exists` check).
+ */
+class FileSystemMeshArtifactStore {
+    rootDirectory;
+    /**
+     * @param rootDirectory The directory artifacts are written under. Created on first write if it doesn't exist.
+     */
+    constructor(rootDirectory) {
+        this.rootDirectory = rootDirectory;
+    }
+    async publishAsync(relativePath, content) {
+        const fullPath = this.resolveWithinRoot(relativePath);
+        const directory = (0, node_path_1.dirname)(fullPath);
+        if (directory.length > 0) {
+            await (0, promises_1.mkdir)(directory, { recursive: true });
+        }
+        await (0, promises_1.writeFile)(fullPath, content, 'utf8');
+    }
+    async tryReadAsync(relativePath) {
+        const fullPath = this.resolveWithinRoot(relativePath);
+        try {
+            return await (0, promises_1.readFile)(fullPath, 'utf8');
+        }
+        catch (ex) {
+            if (isNotFound(ex)) {
+                return undefined;
+            }
+            throw ex;
+        }
+    }
+    /**
+     * Resolves `relativePath` against the store root and asserts the result stays inside it. The relative
+     * path can carry a service name that originated in an untrusted push report (`services/{report.name}.json`),
+     * so a value like `"../../etc/passwd"` or a rooted path would otherwise let path-combination escape the
+     * root and read or overwrite an arbitrary file. Resolving to a full path and checking containment closes
+     * that traversal at the storage boundary, protecting every caller.
+     */
+    resolveWithinRoot(relativePath) {
+        const rootFull = (0, node_path_1.resolve)(this.rootDirectory);
+        const combined = (0, node_path_1.resolve)(rootFull, relativePath);
+        const rootWithSeparator = rootFull.endsWith(node_path_1.sep) ? rootFull : rootFull + node_path_1.sep;
+        if (combined !== rootFull && !combined.startsWith(rootWithSeparator)) {
+            throw new Error(`The artifact path '${relativePath}' resolves outside the store root and was rejected.`);
+        }
+        return combined;
+    }
+}
+exports.FileSystemMeshArtifactStore = FileSystemMeshArtifactStore;
+function isNotFound(ex) {
+    return typeof ex === 'object' && ex !== null && ex.code === 'ENOENT';
+}

package/dist/HttpMeshServiceSource.d.ts

@@ -0,0 +1,37 @@
+/** Port of Benzene.Mesh.Aggregator.HttpMeshServiceSource. */
+import { MeshServiceRegistryEntry } from '@benzenejs/mesh-contracts';
+import { IMeshServiceSource } from './IMeshServiceSource';
+/** A `fetch`-like function - the port of C# `HttpClient` (`HttpClient` -> injectable `fetch`). */
+export type ServiceFetch = (url: string, init?: RequestInit) => Promise<Response>;
+/**
+ * The port of .NET's `HttpRequestException` - thrown by {@link HttpMeshServiceSource.fetchSpecAsync} on a
+ * non-2xx response (`GetStringAsync`'s `EnsureSuccessStatusCode`). `MeshAggregator` records only its
+ * `name` ("HttpRequestException"), never the message/body, so a failed fetch can't leak a service's payload.
+ */
+export declare class HttpRequestException extends Error {
+    constructor(message: string);
+}
+/**
+ * The default `IMeshServiceSource` - fetches `MeshServiceRegistryEntry.specUrl`/`healthUrl` over HTTP.
+ * This is `MeshAggregator`'s original (pre-`IMeshServiceSource`) behavior.
+ *
+ * `HttpClient` -> an injectable `fetch` (default global `fetch`, the `@benzenejs/health-checks-http` pattern).
+ * `GetStringAsync` throws on a non-2xx response, so the spec fetch throws when `!response.ok`; the health
+ * fetch deliberately reads the body regardless of status (see {@link fetchHealthAsync}).
+ */
+export declare class HttpMeshServiceSource implements IMeshServiceSource {
+    private readonly fetchFn;
+    constructor(fetchFn?: ServiceFetch);
+    get key(): string;
+    fetchSpecAsync(entry: MeshServiceRegistryEntry, cancellationToken?: AbortSignal): Promise<string>;
+    tryFetchSpecAsync(entry: MeshServiceRegistryEntry, specType: string, cancellationToken?: AbortSignal): Promise<string | undefined>;
+    fetchHealthAsync(entry: MeshServiceRegistryEntry, cancellationToken?: AbortSignal): Promise<string>;
+    /** Mirrors `HttpClient.GetStringAsync`: throws on a non-2xx response, otherwise returns the body text. */
+    private getStringAsync;
+    /**
+     * Derives an alternate-spec-type URL from the benzene `specUrl` by setting `type=<specType>&format=json`
+     * and preserving the rest of the URL - the benzene and asyncapi specs are the same `spec` endpoint
+     * differing only by `type`. Returns `undefined` for a blank spec URL.
+     */
+    static specUrlForType(specUrl: string, specType: string): string | undefined;
+}

package/dist/HttpMeshServiceSource.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HttpMeshServiceSource = exports.HttpRequestException = void 0;
+/** Port of Benzene.Mesh.Aggregator.HttpMeshServiceSource. */
+const mesh_contracts_1 = require("@benzenejs/mesh-contracts");
+/**
+ * The port of .NET's `HttpRequestException` - thrown by {@link HttpMeshServiceSource.fetchSpecAsync} on a
+ * non-2xx response (`GetStringAsync`'s `EnsureSuccessStatusCode`). `MeshAggregator` records only its
+ * `name` ("HttpRequestException"), never the message/body, so a failed fetch can't leak a service's payload.
+ */
+class HttpRequestException extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'HttpRequestException';
+    }
+}
+exports.HttpRequestException = HttpRequestException;
+/**
+ * The default `IMeshServiceSource` - fetches `MeshServiceRegistryEntry.specUrl`/`healthUrl` over HTTP.
+ * This is `MeshAggregator`'s original (pre-`IMeshServiceSource`) behavior.
+ *
+ * `HttpClient` -> an injectable `fetch` (default global `fetch`, the `@benzenejs/health-checks-http` pattern).
+ * `GetStringAsync` throws on a non-2xx response, so the spec fetch throws when `!response.ok`; the health
+ * fetch deliberately reads the body regardless of status (see {@link fetchHealthAsync}).
+ */
+class HttpMeshServiceSource {
+    fetchFn;
+    constructor(fetchFn = fetch) {
+        this.fetchFn = fetchFn;
+    }
+    get key() {
+        return mesh_contracts_1.MeshServiceSource.http;
+    }
+    async fetchSpecAsync(entry, cancellationToken) {
+        return this.getStringAsync(entry.specUrl, cancellationToken);
+    }
+    async tryFetchSpecAsync(entry, specType, cancellationToken) {
+        const url = HttpMeshServiceSource.specUrlForType(entry.specUrl, specType);
+        return url === undefined ? undefined : this.getStringAsync(url, cancellationToken);
+    }
+    async fetchHealthAsync(entry, cancellationToken) {
+        // Deliberately not throwing on a non-2xx status: Benzene's own health-check middleware maps an
+        // unhealthy aggregate result to HTTP 503, which a throw-on-error fetch would treat as a fetch
+        // failure indistinguishable from the service being genuinely unreachable. Reading the body
+        // regardless of status code lets a real 503-with-a-valid-unhealthy-body come through as Unhealthy
+        // instead of Unreachable - only a connection-level failure (fetch rejects) counts as unreachable.
+        const response = await this.fetchFn(entry.healthUrl, { signal: cancellationToken });
+        return response.text();
+    }
+    /** Mirrors `HttpClient.GetStringAsync`: throws on a non-2xx response, otherwise returns the body text. */
+    async getStringAsync(url, cancellationToken) {
+        const response = await this.fetchFn(url, { signal: cancellationToken });
+        if (!response.ok) {
+            throw new HttpRequestException(`GET ${url} failed with status ${response.status}.`);
+        }
+        return response.text();
+    }
+    /**
+     * Derives an alternate-spec-type URL from the benzene `specUrl` by setting `type=<specType>&format=json`
+     * and preserving the rest of the URL - the benzene and asyncapi specs are the same `spec` endpoint
+     * differing only by `type`. Returns `undefined` for a blank spec URL.
+     */
+    static specUrlForType(specUrl, specType) {
+        if (specUrl.trim().length === 0) {
+            return undefined;
+        }
+        const fragmentIndex = specUrl.indexOf('#');
+        const fragment = fragmentIndex >= 0 ? specUrl.substring(fragmentIndex) : '';
+        const withoutFragment = fragmentIndex >= 0 ? specUrl.substring(0, fragmentIndex) : specUrl;
+        const queryIndex = withoutFragment.indexOf('?');
+        const basePart = queryIndex >= 0 ? withoutFragment.substring(0, queryIndex) : withoutFragment;
+        const query = queryIndex >= 0 ? withoutFragment.substring(queryIndex + 1) : '';
+        // Keep any pre-existing query params except type/format, which we set ourselves.
+        const pairs = query
+            .split('&')
+            .filter((pair) => pair.length > 0 &&
+            !pair.toLowerCase().startsWith('type=') &&
+            !pair.toLowerCase().startsWith('format='));
+        pairs.unshift('format=json');
+        pairs.unshift('type=' + encodeURIComponent(specType));
+        return basePart + '?' + pairs.join('&') + fragment;
+    }
+}
+exports.HttpMeshServiceSource = HttpMeshServiceSource;