@zlink-systems/zlink 0.17.3

package/dist/zlink/runtime/messaging/completion_owner.js

@@ -0,0 +1,570 @@
+"use strict";
+// SPDX-License-Identifier: MPL-2.0
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CompletionOwner = exports.CompletionEntry = void 0;
+exports.consumeSubmittedMessages = consumeSubmittedMessages;
+exports.installCompletionOwner = installCompletionOwner;
+exports.completionOwnerOf = completionOwnerOf;
+exports.releaseCompletionOwner = releaseCompletionOwner;
+const contracts_1 = require("../../contracts");
+const errors_1 = require("../../contracts/errors/errors");
+const message_1 = require("../../contracts/messaging/message");
+const message_conversion_1 = require("../buffers/message_conversion");
+const error_mapping_1 = require("../errors/error_mapping");
+const error_state_1 = require("../errors/error_state");
+const native_errors_1 = require("../errors/native_errors");
+const native_1 = require("../native/native");
+const request_executor_1 = require("./request_executor");
+const COMPLETION_REQUEST = 2;
+const COMPLETION_WRITABLE = 3;
+const SEND_ADMITTED = 0;
+const SEND_TERMINAL = 202;
+const DONTWAIT = 1;
+const RESOLVED_SEND = Promise.resolve();
+function snapshotRetryPart(part) {
+    return part instanceof contracts_1.Message ? part.toBytes() : Buffer.from(part);
+}
+function snapshotRetryPayload(payload) {
+    if (!Array.isArray(payload))
+        return snapshotRetryPart(payload);
+    if (payload.length === 1)
+        return snapshotRetryPart(payload[0]);
+    return payload.map(snapshotRetryPart);
+}
+function submitError(result, nativeErrno, message) {
+    return (0, error_state_1.withRuntimeErrorMessage)(new errors_1.SubmitError(result, nativeErrno), message);
+}
+function requestError(result, message) {
+    return (0, error_state_1.withRuntimeErrorMessage)(new errors_1.RequestError(result), message);
+}
+function consumeSubmittedMessages(payload) {
+    if (payload instanceof contracts_1.Message) {
+        (0, message_1.consumeSubmittedMessage)(payload);
+    }
+    else if (Array.isArray(payload)) {
+        for (const part of payload) {
+            if (part instanceof contracts_1.Message)
+                (0, message_1.consumeSubmittedMessage)(part);
+        }
+    }
+}
+/** Two-phase correlation entry: publish and capture may arrive in either order. */
+class CompletionEntry {
+    token;
+    kind;
+    expectsUserContext;
+    promise;
+    completionId = 0n;
+    published = false;
+    captured = false;
+    settled = false;
+    value;
+    error;
+    capturedCompletionId = 0n;
+    resolvePromise;
+    rejectPromise;
+    constructor(token, kind, expectsUserContext = true) {
+        this.token = token;
+        this.kind = kind;
+        this.expectsUserContext = expectsUserContext;
+        this.promise = new Promise((resolve, reject) => {
+            this.resolvePromise = resolve;
+            this.rejectPromise = reject;
+        });
+    }
+    publish(completionId) {
+        this.completionId = completionId;
+        this.published = true;
+        this.validateRequestCorrelation();
+        this.settleIfJoined();
+    }
+    awaitWritable(completionId) {
+        this.completionId = completionId;
+        this.published = true;
+        this.captured = false;
+    }
+    succeed(value) {
+        if (this.settled)
+            return;
+        this.published = true;
+        this.captured = true;
+        this.value = value;
+        this.settleIfJoined();
+    }
+    capture(completion) {
+        if (this.captured)
+            return;
+        this.capturedCompletionId = completion.completionId;
+        try {
+            if (this.kind !== 'request' || completion.kind !== COMPLETION_REQUEST) {
+                throw requestError(errors_1.RequestResult.InternalError, 'request completion kind mismatch');
+            }
+            const expectedContext = this.expectsUserContext ? this.token : 0n;
+            if (completion.userContext !== expectedContext) {
+                throw requestError(errors_1.RequestResult.InternalError, 'request completion context mismatch');
+            }
+            if (completion.requestResult !== errors_1.RequestResult.Ok) {
+                throw requestError(completion.requestResult, 'request failed');
+            }
+            this.value = (0, request_executor_1.messagesFromNativeBuffers)(completion.parts);
+        }
+        catch (error) {
+            this.error = error;
+        }
+        this.captured = true;
+        this.validateRequestCorrelation();
+        this.settleIfJoined();
+    }
+    fail(error) {
+        if (this.settled)
+            return;
+        this.published = true;
+        this.captured = true;
+        this.error = error;
+        this.settleIfJoined();
+    }
+    settleIfJoined() {
+        if (!this.published || !this.captured || this.settled)
+            return;
+        this.settled = true;
+        if (this.error !== undefined)
+            this.rejectPromise(this.error);
+        else
+            this.resolvePromise(this.value);
+    }
+    validateRequestCorrelation() {
+        if (this.kind !== 'request' || !this.published || !this.captured)
+            return;
+        if (this.capturedCompletionId !== this.completionId) {
+            this.error = requestError(errors_1.RequestResult.InternalError, 'request completion id mismatch');
+        }
+    }
+}
+exports.CompletionEntry = CompletionEntry;
+const owners = new WeakMap();
+class CompletionOwner {
+    handle;
+    native = (0, native_1.requireNative)();
+    byToken = new Map();
+    byId = new Map();
+    retries = new Map();
+    writableRetries = [];
+    nextToken = 1n;
+    publicOwner = null;
+    runtimeWatch = null;
+    managedWritableWaitCount = 0;
+    closed = false;
+    constructor(handle) {
+        this.handle = handle;
+    }
+    submitSend(payload, routingId) {
+        if (this.closed)
+            throw submitError(errors_1.SubmitResult.InvalidState, 0, 'socket is closed');
+        const token = this.nextToken++;
+        let nativePayload;
+        try {
+            nativePayload = (0, message_conversion_1.normalizeOperationPayload)(payload);
+        }
+        catch (error) {
+            return Promise.reject((0, native_errors_1.submitNativeError)(error, DONTWAIT, 'send submit failed'));
+        }
+        let result;
+        try {
+            result = this.native.socketSubmitSend(this.handle, nativePayload, routingId, DONTWAIT, token);
+        }
+        catch (error) {
+            return Promise.reject((0, native_errors_1.submitNativeError)(error, DONTWAIT, 'send submit failed'));
+        }
+        if (result.result === errors_1.SubmitResult.Ok) {
+            try {
+                consumeSubmittedMessages(payload);
+            }
+            catch (error) {
+                return Promise.reject(error);
+            }
+            if (result.completionId !== 0n) {
+                return Promise.reject(submitError(errors_1.SubmitResult.InternalError, result.nativeErrno, 'successful send returned a completion token'));
+            }
+            return RESOLVED_SEND;
+        }
+        if (result.result !== errors_1.SubmitResult.Backpressured) {
+            return Promise.reject(submitError(result.result, result.nativeErrno, 'send submit failed'));
+        }
+        if (!(0, native_errors_1.isWouldBlock)(result.nativeErrno) || result.completionId === 0n) {
+            return Promise.reject(submitError(errors_1.SubmitResult.Backpressured, result.nativeErrno, 'backpressured send did not return an EAGAIN wait token'));
+        }
+        let retryPayload;
+        try {
+            // Core retains no SEND payload. Copy only after actual rejection, before
+            // returning control to user code, so later caller mutation is invisible.
+            retryPayload = snapshotRetryPayload(payload);
+            consumeSubmittedMessages(payload);
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
+        const entry = new CompletionEntry(token, 'send', false);
+        entry.awaitWritable(result.completionId);
+        this.byToken.set(token, entry);
+        this.byId.set(result.completionId, entry);
+        this.retries.set(token, {
+            kind: 'send',
+            nativePayload: retryPayload,
+            routingId: routingId === null ? null : Buffer.from(routingId),
+            timeoutMs: 0,
+        });
+        this.managedWritableWaitCount += 1;
+        this.ensureRuntimeWatch();
+        return entry.promise;
+    }
+    submitRequest(payload, target, timeoutMs) {
+        if (this.closed)
+            throw submitError(errors_1.SubmitResult.InvalidState, 0, 'socket is closed');
+        const token = this.nextToken++;
+        let nativePayload;
+        try {
+            nativePayload = (0, message_conversion_1.normalizeOperationPayload)(payload);
+        }
+        catch (error) {
+            return Promise.reject((0, native_errors_1.submitNativeError)(error, DONTWAIT, 'request submit failed'));
+        }
+        let result;
+        try {
+            result = this.native.socketSubmitRequest(this.handle, target, nativePayload, timeoutMs, DONTWAIT, token);
+        }
+        catch (error) {
+            return Promise.reject((0, native_errors_1.submitNativeError)(error, DONTWAIT, 'request submit failed'));
+        }
+        if (result.result === errors_1.SubmitResult.Ok) {
+            if (result.completionId === 0n) {
+                return Promise.reject(submitError(errors_1.SubmitResult.InternalError, result.nativeErrno, 'successful request returned no completion id'));
+            }
+            try {
+                consumeSubmittedMessages(payload);
+            }
+            catch (error) {
+                return Promise.reject(error);
+            }
+            const entry = this.createEntry('request', token);
+            this.publish(entry, result.completionId);
+            this.ensureRuntimeWatch();
+            return entry.promise;
+        }
+        if (result.result !== errors_1.SubmitResult.Backpressured) {
+            return Promise.reject(submitError(result.result, result.nativeErrno, 'request submit failed'));
+        }
+        if (!(0, native_errors_1.isWouldBlock)(result.nativeErrno) || result.completionId === 0n) {
+            return Promise.reject(submitError(errors_1.SubmitResult.Backpressured, result.nativeErrno, 'backpressured request did not return an EAGAIN wait token'));
+        }
+        let retryPayload;
+        try {
+            // Core retains no REQUEST payload before admission. Snapshot only after
+            // refusal, then release the caller-visible Message wrappers immediately.
+            retryPayload = snapshotRetryPayload(payload);
+            consumeSubmittedMessages(payload);
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
+        const entry = this.createEntry('request', token);
+        entry.awaitWritable(result.completionId);
+        this.byId.set(result.completionId, entry);
+        this.retries.set(token, {
+            kind: 'request',
+            nativePayload: retryPayload,
+            routingId: target === null ? null : Buffer.from(target),
+            timeoutMs,
+        });
+        this.managedWritableWaitCount += 1;
+        this.ensureRuntimeWatch();
+        return entry.promise;
+    }
+    requestSync(payload, target, timeoutMs) {
+        const entry = this.register('request', false, false);
+        void entry.promise.catch(() => { });
+        let result;
+        try {
+            result = this.native.socketRequestSync(this.handle, target, (0, message_conversion_1.normalizeOperationPayload)(payload), timeoutMs);
+        }
+        catch (error) {
+            this.failEntry(entry, (0, native_errors_1.submitNativeError)(error, 0, 'request submit failed'));
+            throw entry.error;
+        }
+        if (result.result !== errors_1.SubmitResult.Ok) {
+            this.failEntry(entry, submitError(result.result, result.nativeErrno, 'request submit failed'));
+            throw entry.error;
+        }
+        consumeSubmittedMessages(payload);
+        this.publish(entry, result.completionId);
+        for (const completion of result.completions)
+            this.capture(completion);
+        this.drain();
+        if (!entry.settled) {
+            this.failEntry(entry, requestError(errors_1.RequestResult.InternalError, 'request completion missing'));
+        }
+        if (entry.error !== undefined)
+            throw entry.error;
+        return entry.value ?? [];
+    }
+    sendSync(payload, routingId) {
+        let result;
+        try {
+            result = this.native.socketSubmitSend(this.handle, (0, message_conversion_1.normalizeOperationPayload)(payload), routingId, 0, 0n);
+        }
+        catch (error) {
+            throw (0, native_errors_1.submitNativeError)(error, 0, 'send failed');
+        }
+        if (result.result !== errors_1.SubmitResult.Ok) {
+            throw submitError(result.result, result.nativeErrno, 'send failed');
+        }
+        consumeSubmittedMessages(payload);
+        if (result.completionId !== 0n) {
+            throw submitError(errors_1.SubmitResult.InternalError, result.nativeErrno, 'successful synchronous send returned a completion token');
+        }
+    }
+    transferToPublic(owner) {
+        if (this.closed)
+            throw submitError(errors_1.SubmitResult.InvalidState, 0, 'socket is closed');
+        if (this.publicOwner && this.publicOwner !== owner) {
+            throw submitError(errors_1.SubmitResult.InvalidState, 0, 'completion owner already transferred');
+        }
+        if (this.publicOwner === owner)
+            return false;
+        // Stop the event-loop fd watcher before the public Core poller starts
+        // observing the same socket notification source.
+        this.closeRuntimeWatch();
+        this.publicOwner = owner;
+        return true;
+    }
+    transferToRuntime(owner) {
+        if (this.publicOwner !== owner)
+            return;
+        this.publicOwner = null;
+        this.ensureRuntimeWatch();
+    }
+    drain(caller) {
+        if (this.publicOwner !== null && this.publicOwner !== caller)
+            return 0;
+        let processed = 0;
+        for (;;) {
+            const completion = this.native.socketCompletionRecv(this.handle, 1);
+            if (!completion)
+                break;
+            this.capture(completion);
+            processed += 1;
+        }
+        // Resubmission can enqueue another WRITABLE immediately. It belongs to
+        // the next drain, after this queue has reached NO_DATA.
+        try {
+            for (const entry of this.writableRetries)
+                this.attemptRetry(entry);
+        }
+        finally {
+            this.writableRetries.length = 0;
+        }
+        return processed;
+    }
+    hasManagedWritableWait() {
+        return this.managedWritableWaitCount !== 0;
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.publicOwner = null;
+        for (const entry of this.byToken.values()) {
+            entry.fail(entry.kind === 'request'
+                ? requestError(errors_1.RequestResult.Terminated, 'socket closed')
+                : submitError(errors_1.SubmitResult.Terminated, 0, 'socket closed'));
+        }
+        this.byToken.clear();
+        this.byId.clear();
+        this.retries.clear();
+        this.writableRetries.length = 0;
+        this.managedWritableWaitCount = 0;
+        this.closeRuntimeWatch();
+    }
+    register(kind, schedule = true, expectsUserContext = true) {
+        if (this.closed)
+            throw submitError(errors_1.SubmitResult.InvalidState, 0, 'socket is closed');
+        const entry = this.createEntry(kind, this.nextToken++, expectsUserContext);
+        if (schedule)
+            this.ensureRuntimeWatch();
+        return entry;
+    }
+    createEntry(kind, token, expectsUserContext = true) {
+        const entry = new CompletionEntry(token, kind, expectsUserContext);
+        this.byToken.set(entry.token, entry);
+        return entry;
+    }
+    publish(entry, completionId) {
+        entry.publish(completionId);
+        if (completionId !== 0n)
+            this.byId.set(completionId, entry);
+        this.removeIfSettled(entry);
+    }
+    capture(completion) {
+        const entry = completion.userContext !== 0n
+            ? this.byToken.get(completion.userContext)
+            : this.byId.get(completion.completionId);
+        if (!entry)
+            return; // Native already closed the unclaimed completion.
+        if (this.retries.has(entry.token)) {
+            this.captureWritable(entry, completion);
+            return;
+        }
+        entry.capture(completion);
+        this.removeIfSettled(entry);
+    }
+    captureWritable(entry, completion) {
+        if (completion.kind !== COMPLETION_WRITABLE
+            || completion.completionId !== entry.completionId
+            || completion.userContext !== entry.token) {
+            this.failEntry(entry, submitError(errors_1.SubmitResult.InternalError, completion.terminalErrno, 'writable completion did not match the pending operation'));
+            return;
+        }
+        this.byId.delete(entry.completionId);
+        if (completion.sendResult !== SEND_ADMITTED) {
+            const error = completion.sendResult === SEND_TERMINAL
+                ? (0, error_mapping_1.createError)('submit', completion.terminalErrno, 'submit target became unavailable')
+                : submitError(errors_1.SubmitResult.InternalError, completion.terminalErrno, 'writable completion result mismatch');
+            this.failEntry(entry, error);
+            return;
+        }
+        this.writableRetries.push(entry);
+    }
+    attemptRetry(entry) {
+        const retry = this.retries.get(entry.token);
+        if (!retry) {
+            this.failEntry(entry, submitError(errors_1.SubmitResult.InternalError, 0, 'pending operation payload is missing'));
+            return;
+        }
+        let result;
+        try {
+            result = retry.kind === 'send'
+                ? this.native.socketSubmitSend(this.handle, retry.nativePayload, retry.routingId, DONTWAIT, entry.token)
+                : this.native.socketSubmitRequest(this.handle, retry.routingId, retry.nativePayload, retry.timeoutMs, DONTWAIT, entry.token);
+        }
+        catch (error) {
+            this.failEntry(entry, (0, native_errors_1.submitNativeError)(error, DONTWAIT, `${retry.kind} submit failed`));
+            return;
+        }
+        if (result.result === errors_1.SubmitResult.Ok) {
+            const validCompletionId = retry.kind === 'send'
+                ? result.completionId === 0n
+                : result.completionId !== 0n;
+            if (!validCompletionId) {
+                this.failEntry(entry, submitError(errors_1.SubmitResult.InternalError, result.nativeErrno, `successful ${retry.kind} returned an invalid completion id`));
+                return;
+            }
+            this.removeRetry(entry);
+            if (retry.kind === 'send') {
+                entry.succeed(undefined);
+                this.removeIfSettled(entry);
+            }
+            else {
+                entry.publish(result.completionId);
+                this.byId.set(result.completionId, entry);
+                this.ensureRuntimeWatch();
+            }
+            return;
+        }
+        if (result.result === errors_1.SubmitResult.Backpressured) {
+            if (!(0, native_errors_1.isWouldBlock)(result.nativeErrno) || result.completionId === 0n) {
+                this.failEntry(entry, submitError(errors_1.SubmitResult.Backpressured, result.nativeErrno, `backpressured ${retry.kind} did not return an EAGAIN wait token`));
+                return;
+            }
+            if (entry.completionId !== 0n)
+                this.byId.delete(entry.completionId);
+            entry.awaitWritable(result.completionId);
+            this.byId.set(result.completionId, entry);
+            this.ensureRuntimeWatch();
+            return;
+        }
+        this.failEntry(entry, submitError(result.result, result.nativeErrno, `${retry.kind} submit failed`));
+    }
+    failEntry(entry, error) {
+        entry.fail(error);
+        this.removeIfSettled(entry);
+    }
+    removeIfSettled(entry) {
+        if (!entry.settled)
+            return;
+        this.byToken.delete(entry.token);
+        if (entry.completionId !== 0n)
+            this.byId.delete(entry.completionId);
+        this.removeRetry(entry);
+    }
+    removeRetry(entry) {
+        if (this.retries.delete(entry.token))
+            this.managedWritableWaitCount -= 1;
+    }
+    ensureRuntimeWatch() {
+        if (this.closed || this.publicOwner || this.byToken.size === 0
+            || this.runtimeWatch !== null)
+            return;
+        this.runtimeWatch = this.native.socketReadableWatchStart(this.handle, (status) => this.runtimeWake(status));
+    }
+    runtimeWake(status) {
+        if (this.closed || this.publicOwner)
+            return;
+        try {
+            if (status < 0)
+                throw new Error(`socket readable watch failed (${status})`);
+            this.drain();
+        }
+        catch (error) {
+            const nativeErrno = (0, native_errors_1.readErrno)();
+            const message = (0, native_errors_1.nativeErrorMessage)(error, 'completion drain failed');
+            for (const entry of this.byToken.values()) {
+                entry.fail(this.retries.has(entry.token)
+                    ? (nativeErrno === 0
+                        ? submitError(errors_1.SubmitResult.InternalError, 0, message)
+                        : (0, error_mapping_1.createError)('submit', nativeErrno, message))
+                    : entry.kind === 'request'
+                        ? (nativeErrno === 0
+                            ? requestError(errors_1.RequestResult.InternalError, message)
+                            : (0, error_mapping_1.createError)('request', nativeErrno, message))
+                        : (nativeErrno === 0
+                            ? submitError(errors_1.SubmitResult.InternalError, 0, message)
+                            : (0, error_mapping_1.createError)('submit', nativeErrno, message)));
+            }
+            this.byToken.clear();
+            this.byId.clear();
+            this.retries.clear();
+            this.writableRetries.length = 0;
+            this.managedWritableWaitCount = 0;
+        }
+        if (this.byToken.size === 0)
+            this.closeRuntimeWatch();
+    }
+    closeRuntimeWatch() {
+        const watch = this.runtimeWatch;
+        this.runtimeWatch = null;
+        if (watch === null)
+            return;
+        try {
+            this.native.socketReadableWatchStop(watch);
+        }
+        catch { /* best-effort cleanup */ }
+    }
+}
+exports.CompletionOwner = CompletionOwner;
+function installCompletionOwner(socket, handle) {
+    const owner = new CompletionOwner(handle);
+    owners.set(socket, owner);
+    return owner;
+}
+function completionOwnerOf(socket) {
+    const owner = owners.get(socket);
+    if (!owner)
+        throw new TypeError('socket has no completion owner');
+    return owner;
+}
+function releaseCompletionOwner(socket) {
+    const owner = owners.get(socket);
+    if (!owner)
+        return;
+    owner.close();
+    owners.delete(socket);
+}

package/dist/zlink/runtime/messaging/message_materializer.d.ts

@@ -0,0 +1,36 @@
+import { Message, Received, ReplyToken, TopicMessage, type MessageLike } from '../../contracts';
+import { type MessageSnapshot } from './message_snapshot';
+export interface NativeReceivedEnvelope {
+    parts?: MessageSnapshot[];
+    data?: Buffer;
+    nativeMessage?: unknown;
+    routingId?: Buffer | null;
+    replyToken?: bigint | null;
+}
+type NativeReceivedBufferParts = readonly Buffer[];
+/** Internal receive transfer: either an envelope or an unrouted native frame. */
+export type NativeReceivedRaw = NativeReceivedEnvelope | NativeReceivedBufferParts | object;
+export interface NativeTopicMessageRaw {
+    topic: string;
+    parts?: MessageSnapshot[];
+    data?: Buffer;
+    nativeMessage?: unknown;
+    routingId?: Buffer | null;
+}
+type NativeTopicMessageSinglePart = readonly [Buffer, string];
+type NativeTopicMessageEnvelope = NativeTopicMessageRaw | NativeTopicMessageSinglePart;
+export interface RoutedReceiveOperations {
+    readonly replyOwner: object;
+    send(routingId: Buffer, parts: readonly Message[]): void;
+    sendManaged(routingId: Buffer, parts: readonly Message[]): Promise<void>;
+    reply(routingId: Buffer, token: ReplyToken, parts: readonly MessageLike[]): void;
+}
+export declare function routedReceivedPrefersManagedBuffer(target: Received): boolean;
+export declare function routedReceivedRoutingBytes(target: Received): Buffer | null;
+export declare function nativeReceivedRoutingId(raw: NativeReceivedRaw): Buffer | null;
+export declare function materializeReceived(raw: NativeReceivedRaw, send?: (parts: readonly Message[]) => void, sendManaged?: (parts: readonly Message[]) => Promise<void>): Received;
+export declare function materializeReceivedInto(target: Received, raw: NativeReceivedRaw, send?: (parts: readonly Message[]) => void, sendManaged?: (parts: readonly Message[]) => Promise<void>): void;
+export declare function materializeRoutedReceivedInto(target: Received, raw: NativeReceivedRaw, operations: RoutedReceiveOperations): void;
+export declare function materializeTopicMessage(raw: NativeTopicMessageEnvelope): TopicMessage;
+export declare function adoptTopicMessage(result: TopicMessage, raw: NativeTopicMessageEnvelope): void;
+export {};