@zlink-systems/zlink 0.17.3

package/dist/zlink/runtime/sockets/index.js

@@ -0,0 +1,27 @@
+"use strict";
+// SPDX-License-Identifier: MPL-2.0
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RuntimeStreamSocket = exports.RuntimeRouterSocket = exports.RuntimeDealerSocket = exports.RuntimeXSubSocket = exports.RuntimeSubSocket = exports.RuntimeXPubSocket = exports.RuntimePubSocket = exports.RuntimePairSocket = exports.RuntimeSubSocketOptions = exports.RuntimeStreamSocketOptions = exports.RuntimeRouterSocketOptions = exports.RuntimePubSocketOptions = exports.RuntimeDealerSocketOptions = exports.RuntimeCommonSocketOptions = void 0;
+var socket_options_1 = require("./socket_options");
+Object.defineProperty(exports, "RuntimeCommonSocketOptions", { enumerable: true, get: function () { return socket_options_1.CommonSocketOptions; } });
+Object.defineProperty(exports, "RuntimeDealerSocketOptions", { enumerable: true, get: function () { return socket_options_1.DealerSocketOptions; } });
+Object.defineProperty(exports, "RuntimePubSocketOptions", { enumerable: true, get: function () { return socket_options_1.PubSocketOptions; } });
+Object.defineProperty(exports, "RuntimeRouterSocketOptions", { enumerable: true, get: function () { return socket_options_1.RouterSocketOptions; } });
+Object.defineProperty(exports, "RuntimeStreamSocketOptions", { enumerable: true, get: function () { return socket_options_1.StreamSocketOptions; } });
+Object.defineProperty(exports, "RuntimeSubSocketOptions", { enumerable: true, get: function () { return socket_options_1.SubSocketOptions; } });
+var pair_socket_1 = require("./pair_socket");
+Object.defineProperty(exports, "RuntimePairSocket", { enumerable: true, get: function () { return pair_socket_1.PairSocket; } });
+var pub_socket_1 = require("./pub_socket");
+Object.defineProperty(exports, "RuntimePubSocket", { enumerable: true, get: function () { return pub_socket_1.PubSocket; } });
+var xpub_socket_1 = require("./xpub_socket");
+Object.defineProperty(exports, "RuntimeXPubSocket", { enumerable: true, get: function () { return xpub_socket_1.XPubSocket; } });
+var sub_socket_1 = require("./sub_socket");
+Object.defineProperty(exports, "RuntimeSubSocket", { enumerable: true, get: function () { return sub_socket_1.SubSocket; } });
+var xsub_socket_1 = require("./xsub_socket");
+Object.defineProperty(exports, "RuntimeXSubSocket", { enumerable: true, get: function () { return xsub_socket_1.XSubSocket; } });
+var dealer_socket_1 = require("./dealer_socket");
+Object.defineProperty(exports, "RuntimeDealerSocket", { enumerable: true, get: function () { return dealer_socket_1.DealerSocket; } });
+var router_socket_1 = require("./router_socket");
+Object.defineProperty(exports, "RuntimeRouterSocket", { enumerable: true, get: function () { return router_socket_1.RouterSocket; } });
+var stream_socket_1 = require("./stream_socket");
+Object.defineProperty(exports, "RuntimeStreamSocket", { enumerable: true, get: function () { return stream_socket_1.StreamSocket; } });

package/dist/zlink/runtime/sockets/pair_socket.d.ts

@@ -0,0 +1,7 @@
+import { CommonSocketOptions } from './socket_options';
+import { SendSocket } from './socket_operations';
+import type { RuntimeContext as Context } from '../core/context';
+export declare class PairSocket extends SendSocket {
+    readonly options: CommonSocketOptions;
+    constructor(ctx: Context);
+}

package/dist/zlink/runtime/sockets/pair_socket.js

@@ -0,0 +1,12 @@
+"use strict";
+// SPDX-License-Identifier: MPL-2.0
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PairSocket = void 0;
+const socket_options_1 = require("./socket_options");
+const socket_operations_1 = require("./socket_operations");
+const socket_constants_1 = require("../../contracts/sockets/socket_constants");
+class PairSocket extends socket_operations_1.SendSocket {
+    options;
+    constructor(ctx) { super(ctx, socket_constants_1.SocketType.PAIR); this.options = socket_options_1.CommonSocketOptions.create(this); }
+}
+exports.PairSocket = PairSocket;

package/dist/zlink/runtime/sockets/pub_socket.d.ts

@@ -0,0 +1,7 @@
+import { PubSocketOptions } from './socket_options';
+import { PublisherSocket } from './socket_operations';
+import type { RuntimeContext as Context } from '../core/context';
+export declare class PubSocket extends PublisherSocket {
+    readonly options: PubSocketOptions;
+    constructor(ctx: Context);
+}

package/dist/zlink/runtime/sockets/pub_socket.js

@@ -0,0 +1,12 @@
+"use strict";
+// SPDX-License-Identifier: MPL-2.0
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PubSocket = void 0;
+const socket_options_1 = require("./socket_options");
+const socket_operations_1 = require("./socket_operations");
+const socket_constants_1 = require("../../contracts/sockets/socket_constants");
+class PubSocket extends socket_operations_1.PublisherSocket {
+    options;
+    constructor(ctx) { super(ctx, socket_constants_1.SocketType.PUB); this.options = socket_options_1.PubSocketOptions.create(this); }
+}
+exports.PubSocket = PubSocket;

package/dist/zlink/runtime/sockets/router_socket.d.ts

@@ -0,0 +1,19 @@
+import { ReplyToken, RoutingId, type MessageLike } from '../../contracts';
+import type { ReplyOperation, RequestOperation, SendOperation } from '../../contracts/messaging';
+import type { RuntimeContext as Context } from '../core/context';
+import { RoutedMessageSocket } from './socket_operations';
+import { RouterSocketOptions } from './socket_options';
+export declare class RouterSocket extends RoutedMessageSocket {
+    readonly options: RouterSocketOptions;
+    constructor(ctx: Context);
+    setRoutingId(routingId: RoutingId): void;
+    getRoutingId(): RoutingId;
+    send(peerRid: RoutingId): SendOperation;
+    request(peerRid: RoutingId): RequestOperation;
+    reply(peerRid: RoutingId, token: ReplyToken): ReplyOperation;
+    protected replyToRoutedMessage(sourceRid: RoutingId, token: ReplyToken, parts: readonly MessageLike[]): void;
+    protected sendReceivedManaged(routingId: Buffer, parts: readonly import('../../contracts').Message[]): Promise<void>;
+    private replyDirect;
+    private validateReplyToken;
+    private resolveRequestTimeout;
+}

package/dist/zlink/runtime/sockets/router_socket.js

@@ -0,0 +1,70 @@
+"use strict";
+// SPDX-License-Identifier: MPL-2.0
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RouterSocket = void 0;
+const contracts_1 = require("../../contracts");
+const received_1 = require("../../contracts/messaging/received");
+const socket_constants_1 = require("../../contracts/sockets/socket_constants");
+const message_conversion_1 = require("../buffers/message_conversion");
+const routing_id_1 = require("../core/routing_id");
+const native_errors_1 = require("../errors/native_errors");
+const native_handle_1 = require("../handles/native_handle");
+const completion_owner_1 = require("../messaging/completion_owner");
+const native_1 = require("../native/native");
+const socket_operations_1 = require("./socket_operations");
+const socket_options_1 = require("./socket_options");
+const native = (0, native_1.requireNative)();
+class RouterSocket extends socket_operations_1.RoutedMessageSocket {
+    options;
+    constructor(ctx) {
+        super(ctx, socket_constants_1.SocketType.ROUTER);
+        this.options = socket_options_1.RouterSocketOptions.create(this);
+    }
+    setRoutingId(routingId) {
+        const normalized = (0, routing_id_1.normalizeRoutingId)(routingId);
+        (0, native_errors_1.configCall)('routing id set failed', () => native.handleSetRoutingId((0, native_handle_1.getNativeHandle)(this), normalized));
+    }
+    getRoutingId() {
+        return contracts_1.RoutingId.from((0, native_errors_1.configCall)('routing id get failed', () => native.handleGetRoutingId((0, native_handle_1.getNativeHandle)(this))));
+    }
+    send(peerRid) {
+        const target = Buffer.from((0, routing_id_1.normalizeRoutingId)(peerRid, 'peerRid'));
+        return new socket_operations_1.RuntimeSendOperation((parts) => (0, completion_owner_1.completionOwnerOf)(this).submitSend(parts, target), (parts) => (0, completion_owner_1.completionOwnerOf)(this).sendSync(parts, target));
+    }
+    request(peerRid) {
+        const target = Buffer.from((0, routing_id_1.normalizeRoutingId)(peerRid, 'peerRid'));
+        return new socket_operations_1.RuntimeRequestOperation((parts, timeoutMs) => (0, completion_owner_1.completionOwnerOf)(this).submitRequest(parts, target, this.resolveRequestTimeout(timeoutMs)), (parts, timeoutMs) => (0, completion_owner_1.completionOwnerOf)(this).requestSync(parts, target, this.resolveRequestTimeout(timeoutMs)));
+    }
+    reply(peerRid, token) {
+        const target = Buffer.from((0, routing_id_1.normalizeRoutingId)(peerRid, 'peerRid'));
+        this.validateReplyToken(token);
+        return new socket_operations_1.RuntimeReplyOperation((parts) => this.replyDirect(target, token, parts));
+    }
+    replyToRoutedMessage(sourceRid, token, parts) {
+        this.replyDirect((0, routing_id_1.normalizeRoutingId)(sourceRid), token, parts);
+    }
+    sendReceivedManaged(routingId, parts) {
+        return (0, completion_owner_1.completionOwnerOf)(this).submitSend(parts, routingId);
+    }
+    replyDirect(sourceRid, token, payload) {
+        this.validateReplyToken(token);
+        try {
+            native.socketReply((0, native_handle_1.getNativeHandle)(this), sourceRid, (0, received_1.replyTokenNativeValue)(token), (0, message_conversion_1.normalizeOperationPayload)(payload));
+        }
+        catch (error) {
+            throw (0, native_errors_1.submitNativeError)(error, 0, 'reply failed');
+        }
+        (0, completion_owner_1.consumeSubmittedMessages)(payload);
+    }
+    validateReplyToken(token) {
+        if (!(token instanceof contracts_1.ReplyToken) || !(0, received_1.replyTokenOwnerMatches)(token, this.replyOwner)) {
+            throw new TypeError('ReplyToken belongs to a different RouterSocket');
+        }
+    }
+    resolveRequestTimeout(timeoutMs) {
+        return timeoutMs === 0
+            ? (this.options.requestTimeout === 0 ? 5_000 : this.options.requestTimeout)
+            : timeoutMs;
+    }
+}
+exports.RouterSocket = RouterSocket;

package/dist/zlink/runtime/sockets/socket_base.d.ts

@@ -0,0 +1,21 @@
+import { RuntimeContext as Context } from '../core/context';
+import { NativeHandle } from '../handles/native_handle';
+import { RoutingId } from '../../contracts';
+import { type MonitorEventType } from '../../contracts/eventing';
+import { type ReceiveFlowState } from '../../contracts/sockets/socket_constants';
+import { MonitorSocket } from '../eventing/monitor_socket';
+export declare class SocketBase extends NativeHandle {
+    constructor(ctx: Context, type: number);
+    bind(endpoint: string): void;
+    unbind(endpoint: string): void;
+    setTlsServer(cert: string, key: string, requireClientCert?: boolean): void;
+    setTlsClient(ca: string, hostname: string, trustSystem?: boolean): void;
+    setReceiveFlowState(state: ReceiveFlowState): void;
+    monitorOpen(events?: readonly MonitorEventType[], monitorHwmBytes?: bigint): MonitorSocket;
+    close(): void;
+}
+export declare class ConnectableSocket extends SocketBase {
+    connect(endpoint: string): void;
+    disconnect(endpoint: string): void;
+    disconnectRid(routingId: RoutingId): void;
+}

package/dist/zlink/runtime/sockets/socket_base.js

@@ -0,0 +1,102 @@
+"use strict";
+// SPDX-License-Identifier: MPL-2.0
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConnectableSocket = exports.SocketBase = void 0;
+const native_handle_1 = require("../handles/native_handle");
+const native_1 = require("../native/native");
+const native_errors_1 = require("../errors/native_errors");
+const validation_1 = require("../options/validation");
+const socket_constants_1 = require("../../contracts/sockets/socket_constants");
+const routing_id_1 = require("../core/routing_id");
+const monitor_socket_1 = require("../eventing/monitor_socket");
+const byte_values_1 = require("../options/byte_values");
+const completion_owner_1 = require("../messaging/completion_owner");
+class SocketBase extends native_handle_1.NativeHandle {
+    constructor(ctx, type) {
+        super((0, native_1.requireNative)().socketNew((0, native_handle_1.getNativeHandle)(ctx), type));
+        if (!this._native) {
+            throw (0, native_errors_1.lastError)('config', 'socket creation failed');
+        }
+        (0, completion_owner_1.installCompletionOwner)(this, this._native);
+    }
+    bind(endpoint) {
+        const normalizedEndpoint = (0, validation_1.validateCString)(endpoint, 'endpoint');
+        (0, native_errors_1.bindCall)('socket bind failed', () => {
+            (0, native_1.requireNative)().socketBind((0, native_handle_1.getNativeHandle)(this), normalizedEndpoint);
+        });
+    }
+    unbind(endpoint) {
+        const normalizedEndpoint = (0, validation_1.validateCString)(endpoint, 'endpoint');
+        (0, native_errors_1.connectCall)('socket unbind failed', () => {
+            (0, native_1.requireNative)().socketUnbind((0, native_handle_1.getNativeHandle)(this), normalizedEndpoint);
+        });
+    }
+    setTlsServer(cert, key, requireClientCert = false) {
+        const normalizedCert = (0, validation_1.validateCString)(cert, 'cert', Number.MAX_SAFE_INTEGER);
+        const normalizedKey = (0, validation_1.validateCString)(key, 'key', Number.MAX_SAFE_INTEGER);
+        (0, native_errors_1.configCall)('socket TLS server configuration failed', () => {
+            (0, native_1.requireNative)().socketSetTlsServer((0, native_handle_1.getNativeHandle)(this), normalizedCert, normalizedKey, requireClientCert ? 1 : 0);
+        });
+    }
+    setTlsClient(ca, hostname, trustSystem = false) {
+        const normalizedCa = (0, validation_1.validateCString)(ca, 'ca', Number.MAX_SAFE_INTEGER);
+        const normalizedHostname = (0, validation_1.validateCString)(hostname, 'hostname', Number.MAX_SAFE_INTEGER);
+        (0, native_errors_1.configCall)('socket TLS client configuration failed', () => {
+            (0, native_1.requireNative)().socketSetTlsClient((0, native_handle_1.getNativeHandle)(this), normalizedCa, normalizedHostname, trustSystem ? 1 : 0);
+        });
+    }
+    setReceiveFlowState(state) {
+        (0, native_errors_1.configCall)('socket receive-flow-state configuration failed', () => {
+            (0, native_1.requireNative)().socketSetReceiveFlowState((0, native_handle_1.getNativeHandle)(this), state | 0);
+        });
+    }
+    /** @internal */
+    setSockOptRaw(option, value) {
+        const buf = typeof value === 'number' ? Buffer.from([value & 0xff, 0, 0, 0]) : value;
+        (0, native_errors_1.configCall)('socket option set failed', () => {
+            (0, native_1.requireNative)().socketSetOpt((0, native_handle_1.getNativeHandle)(this), option | 0, buf);
+        });
+    }
+    /** @internal */
+    getSockOptRaw(option) {
+        return (0, native_errors_1.configCall)('socket option get failed', () => (0, native_1.requireNative)().socketGetOpt((0, native_handle_1.getNativeHandle)(this), option | 0));
+    }
+    monitorOpen(events, monitorHwmBytes = 0n) {
+        const mask = events === undefined
+            ? socket_constants_1.SOCKET_MONITOR_EVENT_ALL
+            : events.reduce((current, event) => current | (event | 0), 0);
+        const exactMonitorHwmBytes = (0, byte_values_1.validateUInt64)(monitorHwmBytes, 'monitorHwmBytes');
+        return new monitor_socket_1.MonitorSocket((0, native_errors_1.configCall)('monitor open failed', () => (0, native_1.requireNative)().monitorOpen((0, native_handle_1.getNativeHandle)(this), mask | 0, exactMonitorHwmBytes)));
+    }
+    close() {
+        if (!this._native)
+            return;
+        (0, completion_owner_1.releaseCompletionOwner)(this);
+        (0, native_errors_1.closeCall)('socket close failed', () => {
+            (0, native_1.requireNative)().socketClose(this._native);
+        });
+        this._native = null;
+    }
+}
+exports.SocketBase = SocketBase;
+class ConnectableSocket extends SocketBase {
+    connect(endpoint) {
+        const normalizedEndpoint = (0, validation_1.validateCString)(endpoint, 'endpoint');
+        (0, native_errors_1.connectCall)('socket connect failed', () => {
+            (0, native_1.requireNative)().socketConnect((0, native_handle_1.getNativeHandle)(this), normalizedEndpoint);
+        });
+    }
+    disconnect(endpoint) {
+        const normalizedEndpoint = (0, validation_1.validateCString)(endpoint, 'endpoint');
+        (0, native_errors_1.connectCall)('socket disconnect failed', () => {
+            (0, native_1.requireNative)().socketDisconnect((0, native_handle_1.getNativeHandle)(this), normalizedEndpoint);
+        });
+    }
+    disconnectRid(routingId) {
+        const normalizedRoutingId = (0, routing_id_1.normalizeRoutingId)(routingId);
+        (0, native_errors_1.connectCall)('socket disconnect by routing id failed', () => {
+            (0, native_1.requireNative)().socketDisconnectRid((0, native_handle_1.getNativeHandle)(this), normalizedRoutingId);
+        });
+    }
+}
+exports.ConnectableSocket = ConnectableSocket;

package/dist/zlink/runtime/sockets/socket_operation_builders.d.ts

@@ -0,0 +1,38 @@
+import { Message, type MessageLike } from '../../contracts';
+import type { PublishOperation as PublishOperationContract, PublishSubmitOperation, RequestOperation, RequestSubmitOperation, ReplyOperation, ReplySubmitOperation, SendOperation, SendSubmitOperation } from '../../contracts/messaging';
+import { PartOperationBase, type OperationPayloadValue } from '../messaging/send_operation_base';
+export type ManagedSendInvoker = (parts: OperationPayloadValue<MessageLike>) => Promise<void>;
+export type SyncSendInvoker = (parts: OperationPayloadValue<MessageLike>) => void;
+export type PublishInvoker = (topic: string, payload: OperationPayloadValue<MessageLike>) => void;
+export type RequestInvoker = (parts: OperationPayloadValue<MessageLike>, timeoutMs: number) => Promise<Message[]>;
+export type SyncRequestInvoker = (parts: OperationPayloadValue<MessageLike>, timeoutMs: number) => Message[];
+export type ReplyInvoker = (parts: OperationPayloadValue<MessageLike>) => void;
+/** Event-loop-driven send builder with WRITABLE-token retry. */
+export declare class RuntimeSendOperation extends PartOperationBase<MessageLike, MessageLike> implements SendOperation, SendSubmitOperation {
+    private readonly _invoke;
+    private readonly _invokeSync;
+    constructor(_invoke: ManagedSendInvoker, _invokeSync: SyncSendInvoker);
+    submit(): Promise<void>;
+    submit_sync(): void;
+}
+/** Synchronous PUB/XPUB builder; Core decides drop versus NODROP error. */
+export declare class PublishOperation extends PartOperationBase<MessageLike, MessageLike> implements PublishOperationContract, PublishSubmitOperation {
+    private readonly _invoke;
+    private readonly _topic;
+    constructor(_invoke: PublishInvoker, _topic: string);
+    submit(): void;
+}
+export declare class RuntimeRequestOperation extends PartOperationBase<MessageLike, MessageLike> implements RequestOperation, RequestSubmitOperation {
+    private readonly _invoke;
+    private readonly _invokeSync;
+    private _timeoutMs;
+    constructor(_invoke: RequestInvoker, _invokeSync: SyncRequestInvoker);
+    timeout(timeoutMs: number): this;
+    submit(): Promise<Message[]>;
+    submit_sync(): Message[];
+}
+export declare class RuntimeReplyOperation extends PartOperationBase<MessageLike, MessageLike> implements ReplyOperation, ReplySubmitOperation {
+    private readonly _invoke;
+    constructor(_invoke: ReplyInvoker);
+    submit(): void;
+}

package/dist/zlink/runtime/sockets/socket_operation_builders.js

@@ -0,0 +1,93 @@
+"use strict";
+// SPDX-License-Identifier: MPL-2.0
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RuntimeReplyOperation = exports.RuntimeRequestOperation = exports.PublishOperation = exports.RuntimeSendOperation = void 0;
+const contracts_1 = require("../../contracts");
+const message_1 = require("../../contracts/messaging/message");
+const send_operation_base_1 = require("../messaging/send_operation_base");
+function consumeSubmittedMessages(payload) {
+    if (payload instanceof contracts_1.Message) {
+        (0, message_1.consumeSubmittedMessage)(payload);
+        return;
+    }
+    if (Array.isArray(payload)) {
+        for (const part of payload) {
+            if (part instanceof contracts_1.Message)
+                (0, message_1.consumeSubmittedMessage)(part);
+        }
+    }
+}
+/** Event-loop-driven send builder with WRITABLE-token retry. */
+class RuntimeSendOperation extends send_operation_base_1.PartOperationBase {
+    _invoke;
+    _invokeSync;
+    constructor(_invoke, _invokeSync) {
+        super();
+        this._invoke = _invoke;
+        this._invokeSync = _invokeSync;
+    }
+    submit() { return this._invoke(this.consumePayload()); }
+    submit_sync() {
+        const payload = this.consumePayload();
+        this._invokeSync(payload);
+        consumeSubmittedMessages(payload);
+    }
+}
+exports.RuntimeSendOperation = RuntimeSendOperation;
+/** Synchronous PUB/XPUB builder; Core decides drop versus NODROP error. */
+class PublishOperation extends send_operation_base_1.PartOperationBase {
+    _invoke;
+    _topic;
+    constructor(_invoke, _topic) {
+        super();
+        this._invoke = _invoke;
+        this._topic = _topic;
+    }
+    submit() {
+        const payload = this.consumePayload();
+        this._invoke(this._topic, payload);
+        consumeSubmittedMessages(payload);
+    }
+}
+exports.PublishOperation = PublishOperation;
+class RuntimeRequestOperation extends send_operation_base_1.PartOperationBase {
+    _invoke;
+    _invokeSync;
+    _timeoutMs = 0;
+    constructor(_invoke, _invokeSync) {
+        super();
+        this._invoke = _invoke;
+        this._invokeSync = _invokeSync;
+    }
+    timeout(timeoutMs) {
+        this.ensureOpen();
+        if (!Number.isInteger(timeoutMs)) {
+            throw new TypeError('timeoutMs must be an integer');
+        }
+        if (timeoutMs < 0 || timeoutMs > 0x7fffffff) {
+            throw new RangeError('timeoutMs must be in the range 0..2147483647');
+        }
+        this._timeoutMs = timeoutMs;
+        return this;
+    }
+    submit() {
+        return this._invoke(this.consumePayload(), this._timeoutMs);
+    }
+    submit_sync() {
+        return this._invokeSync(this.consumePayload(), this._timeoutMs);
+    }
+}
+exports.RuntimeRequestOperation = RuntimeRequestOperation;
+class RuntimeReplyOperation extends send_operation_base_1.PartOperationBase {
+    _invoke;
+    constructor(_invoke) {
+        super();
+        this._invoke = _invoke;
+    }
+    submit() {
+        const payload = this.consumePayload();
+        this._invoke(payload);
+        consumeSubmittedMessages(payload);
+    }
+}
+exports.RuntimeReplyOperation = RuntimeReplyOperation;

package/dist/zlink/runtime/sockets/socket_operations.d.ts

@@ -0,0 +1,40 @@
+import { ConnectableSocket } from './socket_base';
+import { Message, Received, RoutingId, TopicMessage, type MessageLike } from '../../contracts';
+import { RecvFlags } from '../../contracts/sockets/socket_constants';
+import type { SubscriptionEntry, SendOperation, PublishOperation as PublishOperationContract } from '../../contracts/messaging';
+export { PublishOperation, RuntimeReplyOperation, RuntimeRequestOperation, RuntimeSendOperation, } from './socket_operation_builders';
+export declare class ReceiveSocket extends ConnectableSocket {
+    /**
+     * Receives into caller-provided storage. Pass a long-lived {@link Received}
+     * and the binding refills its internal state in place each successful call.
+     * Returns true on success and false when DontWait finds no data.
+     */
+    recv(result: Received, flags?: RecvFlags): boolean;
+}
+export declare class SendSocket extends ReceiveSocket {
+    send(): SendOperation;
+}
+export declare class PublisherSocket extends ConnectableSocket {
+    private lastPublishTopic;
+    private lastValidatedPublishTopic;
+    private readonly publishInvoker;
+    constructor(ctx: import('../core/context').RuntimeContext, type: number);
+    publish(topic: string): PublishOperationContract;
+}
+export declare class SubscriberSocket extends ConnectableSocket {
+    setSubscription(topicOrPattern: string): void;
+    unsetSubscription(topicOrPattern: string): void;
+    subscriptionAt(index: number): SubscriptionEntry | null;
+    subscribe(result: TopicMessage, flags?: RecvFlags): boolean;
+}
+export declare class RoutedMessageSocket extends ConnectableSocket {
+    protected readonly replyOwner: {};
+    private readonly receivedOperations;
+    protected sendDirect(routingId: RoutingId, payload: MessageLike | readonly MessageLike[]): void;
+    protected replyToRoutedMessage(_sourceRid: RoutingId, _replyToken: import('../../contracts').ReplyToken, _parts: readonly Message[]): void;
+    protected sendReceivedManaged(_routingId: Buffer, _parts: readonly Message[]): Promise<void>;
+    /**
+     * Receives into caller-provided storage. See {@link MessageSocket.recv}.
+     */
+    recv(result: Received, flags?: RecvFlags): boolean;
+}

package/dist/zlink/runtime/sockets/socket_operations.js

@@ -0,0 +1,177 @@
+"use strict";
+// SPDX-License-Identifier: MPL-2.0
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RoutedMessageSocket = exports.SubscriberSocket = exports.PublisherSocket = exports.SendSocket = exports.ReceiveSocket = exports.RuntimeSendOperation = exports.RuntimeRequestOperation = exports.RuntimeReplyOperation = exports.PublishOperation = void 0;
+const native_1 = require("../native/native");
+const native_handle_1 = require("../handles/native_handle");
+const native_errors_1 = require("../errors/native_errors");
+const message_materializer_1 = require("../messaging/message_materializer");
+const message_conversion_1 = require("../buffers/message_conversion");
+const routing_id_1 = require("../core/routing_id");
+const socket_base_1 = require("./socket_base");
+const contracts_1 = require("../../contracts");
+const validation_1 = require("../options/validation");
+const socket_constants_1 = require("../../contracts/sockets/socket_constants");
+const errors_1 = require("../../contracts/errors/errors");
+const socket_operation_builders_1 = require("./socket_operation_builders");
+const completion_owner_1 = require("../messaging/completion_owner");
+var socket_operation_builders_2 = require("./socket_operation_builders");
+Object.defineProperty(exports, "PublishOperation", { enumerable: true, get: function () { return socket_operation_builders_2.PublishOperation; } });
+Object.defineProperty(exports, "RuntimeReplyOperation", { enumerable: true, get: function () { return socket_operation_builders_2.RuntimeReplyOperation; } });
+Object.defineProperty(exports, "RuntimeRequestOperation", { enumerable: true, get: function () { return socket_operation_builders_2.RuntimeRequestOperation; } });
+Object.defineProperty(exports, "RuntimeSendOperation", { enumerable: true, get: function () { return socket_operation_builders_2.RuntimeSendOperation; } });
+const socket_submit_errors_1 = require("./socket_submit_errors");
+const native = (0, native_1.requireNative)();
+class ReceiveSocket extends socket_base_1.ConnectableSocket {
+    /**
+     * Receives into caller-provided storage. Pass a long-lived {@link Received}
+     * and the binding refills its internal state in place each successful call.
+     * Returns true on success and false when DontWait finds no data.
+     */
+    recv(result, flags = socket_constants_1.RecvFlags.None) {
+        let raw;
+        try {
+            raw = ((flags | 0) & (socket_constants_1.RecvFlags.DontWait | 0))
+                ? native.socketRecvMessageNoWait((0, native_handle_1.getNativeHandle)(this))
+                : native.socketRecvMessage((0, native_handle_1.getNativeHandle)(this), flags | 0);
+        }
+        catch (error) {
+            throw (0, native_errors_1.recvNativeError)(error, flags, 'recv failed');
+        }
+        if (raw == null)
+            return false;
+        (0, message_materializer_1.materializeReceivedInto)(result, raw);
+        return true;
+    }
+}
+exports.ReceiveSocket = ReceiveSocket;
+class SendSocket extends ReceiveSocket {
+    send() {
+        return new socket_operation_builders_1.RuntimeSendOperation((payload) => (0, completion_owner_1.completionOwnerOf)(this).submitSend(payload, null), (payload) => (0, completion_owner_1.completionOwnerOf)(this).sendSync(payload, null));
+    }
+}
+exports.SendSocket = SendSocket;
+class PublisherSocket extends socket_base_1.ConnectableSocket {
+    lastPublishTopic;
+    lastValidatedPublishTopic;
+    publishInvoker = (topic, payload) => this.publishDirect(topic, payload);
+    constructor(ctx, type) {
+        super(ctx, type);
+    }
+    publish(topic) {
+        const normalizedTopic = topic === this.lastPublishTopic
+            ? this.lastValidatedPublishTopic
+            : (0, validation_1.validateCString)(topic, 'topic', Number.MAX_SAFE_INTEGER);
+        this.lastPublishTopic = topic;
+        this.lastValidatedPublishTopic = normalizedTopic;
+        return new socket_operation_builders_1.PublishOperation(this.publishInvoker, normalizedTopic);
+    }
+    /** @internal */
+    publishDirect(topic, payload, flags = socket_constants_1.SendFlags.None) {
+        const normalized = (0, message_conversion_1.normalizeOperationPayload)(payload);
+        if ((flags | 0) & (socket_constants_1.SendFlags.DontWait | 0)) {
+            let result;
+            try {
+                result = native.socketTryPublish((0, native_handle_1.getNativeHandle)(this), topic, normalized);
+            }
+            catch (error) {
+                throw (0, native_errors_1.submitNativeError)(error, flags, 'publish failed');
+            }
+            if (result === errors_1.SubmitResult.Ok)
+                return true;
+            if (result === errors_1.SubmitResult.Backpressured)
+                return false;
+            throw (0, socket_submit_errors_1.submitErrorFromResult)(result, 'publish failed');
+        }
+        try {
+            native.socketPublish((0, native_handle_1.getNativeHandle)(this), topic, normalized, flags | 0);
+            return true;
+        }
+        catch (error) {
+            return (0, native_errors_1.submitOrBackpressure)(error, flags, 'publish failed');
+        }
+    }
+}
+exports.PublisherSocket = PublisherSocket;
+class SubscriberSocket extends socket_base_1.ConnectableSocket {
+    setSubscription(topicOrPattern) {
+        const topic = (0, validation_1.validateCString)(topicOrPattern, 'topicOrPattern', Number.MAX_SAFE_INTEGER);
+        (0, native_errors_1.configCall)('subscription set failed', () => {
+            native.socketSetSubscription((0, native_handle_1.getNativeHandle)(this), topic);
+        });
+    }
+    unsetSubscription(topicOrPattern) {
+        const topic = (0, validation_1.validateCString)(topicOrPattern, 'topicOrPattern', Number.MAX_SAFE_INTEGER);
+        (0, native_errors_1.configCall)('subscription unset failed', () => {
+            native.socketUnsetSubscription((0, native_handle_1.getNativeHandle)(this), topic);
+        });
+    }
+    subscriptionAt(index) {
+        return (0, native_errors_1.configCall)('subscription lookup failed', () => native.subscriptionAt((0, native_handle_1.getNativeHandle)(this), index >>> 0));
+    }
+    subscribe(resultOrFlags = socket_constants_1.RecvFlags.None, maybeFlags = socket_constants_1.RecvFlags.None) {
+        const hasResult = resultOrFlags instanceof contracts_1.TopicMessage;
+        const flags = hasResult ? maybeFlags : resultOrFlags;
+        let raw;
+        try {
+            raw = ((flags | 0) & (socket_constants_1.RecvFlags.DontWait | 0))
+                ? native.socketTrySubscribeMessage((0, native_handle_1.getNativeHandle)(this))
+                : native.socketSubscribeMessage((0, native_handle_1.getNativeHandle)(this), flags | 0);
+        }
+        catch (error) {
+            throw (0, native_errors_1.recvNativeError)(error, flags, 'subscribe failed');
+        }
+        if (!raw) {
+            return hasResult ? false : null;
+        }
+        if (hasResult) {
+            (0, message_materializer_1.adoptTopicMessage)(resultOrFlags, raw);
+            return true;
+        }
+        return (0, message_materializer_1.materializeTopicMessage)(raw);
+    }
+}
+exports.SubscriberSocket = SubscriberSocket;
+class RoutedMessageSocket extends socket_base_1.ConnectableSocket {
+    replyOwner = {};
+    receivedOperations = {
+        replyOwner: this.replyOwner,
+        send: (routingId, parts) => (0, completion_owner_1.completionOwnerOf)(this).sendSync(parts, routingId),
+        sendManaged: (routingId, parts) => this.sendReceivedManaged(routingId, parts),
+        reply: (routingId, token, parts) => this.replyToRoutedMessage((0, routing_id_1.routingIdFromOwnedBuffer)(routingId), token, parts),
+    };
+    sendDirect(routingId, payload) {
+        const normalizedRoutingId = (0, routing_id_1.normalizeRoutingId)(routingId);
+        (0, completion_owner_1.completionOwnerOf)(this).sendSync(payload, normalizedRoutingId);
+    }
+    replyToRoutedMessage(_sourceRid, _replyToken, _parts) {
+        throw (0, socket_submit_errors_1.submitErrorFromResult)(errors_1.SubmitResult.InvalidState, 'request reply is only supported by RouterSocket');
+    }
+    sendReceivedManaged(_routingId, _parts) {
+        return Promise.reject((0, socket_submit_errors_1.submitErrorFromResult)(errors_1.SubmitResult.InvalidState, 'managed received send is not supported by this socket'));
+    }
+    /**
+     * Receives into caller-provided storage. See {@link MessageSocket.recv}.
+     */
+    recv(result, flags = socket_constants_1.RecvFlags.None) {
+        // HOT PATH: terminal readers repeatedly materialize data(), whereas
+        // relays consume the movable native frame. Use the previous refill to
+        // select the next internal storage mode without changing the public API.
+        const preferManagedSinglePart = (0, message_materializer_1.routedReceivedPrefersManagedBuffer)(result);
+        const routingIdStorage = (0, message_materializer_1.routedReceivedRoutingBytes)(result);
+        let raw;
+        try {
+            raw = ((flags | 0) & (socket_constants_1.RecvFlags.DontWait | 0))
+                ? native.routerRecvMessageNoWait((0, native_handle_1.getNativeHandle)(this), preferManagedSinglePart, routingIdStorage)
+                : native.routerRecvMessage((0, native_handle_1.getNativeHandle)(this), flags | 0, preferManagedSinglePart, routingIdStorage);
+        }
+        catch (error) {
+            throw (0, native_errors_1.recvNativeError)(error, flags, 'recv failed');
+        }
+        if (raw == null)
+            return false;
+        (0, message_materializer_1.materializeRoutedReceivedInto)(result, raw, this.receivedOperations);
+        return true;
+    }
+}
+exports.RoutedMessageSocket = RoutedMessageSocket;