@zlink-systems/zlink 0.17.3

package/dist/zlink/runtime/eventing/poller.d.ts

@@ -0,0 +1,34 @@
+import { type PollEventFlagValue } from '../../contracts/sockets/socket_constants';
+import { PollEvents } from './poll_events';
+import { Timer } from './timer';
+import { MonitorSocket } from './monitor_socket';
+import type { RuntimeBaseSocket as BaseSocket } from '../sockets';
+type BasePollable = BaseSocket | MonitorSocket;
+export declare class Poller {
+    private _native;
+    private readonly _socketRegistrations;
+    private readonly _timerRegistrations;
+    private readonly _fdRegistrations;
+    private readonly _registrationsByToken;
+    private _nextRegistrationToken;
+    constructor();
+    add(socket: BasePollable, events: readonly PollEventFlagValue[], slot: number): void;
+    add(timer: Timer, slot: number): void;
+    modify(socket: BasePollable, events: readonly PollEventFlagValue[]): void;
+    remove(socket: BasePollable): boolean;
+    remove(timer: Timer): boolean;
+    addFd(fd: number, events: readonly PollEventFlagValue[], slot: number): void;
+    modifyFd(fd: number, events: readonly PollEventFlagValue[]): void;
+    removeFd(fd: number): boolean;
+    get size(): number;
+    wait(events: PollEvents, timeoutMs: number): number;
+    destroy(): void;
+    close(): void;
+    private addSocketInternal;
+    private modifySocketInternal;
+    private removeSocketInternal;
+    private allocateRegistrationToken;
+    private addTimerInternal;
+    private removeTimerInternal;
+}
+export { Poller as RuntimePoller };

package/dist/zlink/runtime/eventing/poller.js

@@ -0,0 +1,275 @@
+"use strict";
+// SPDX-License-Identifier: MPL-2.0
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RuntimePoller = exports.Poller = void 0;
+const socket_constants_1 = require("../../contracts/sockets/socket_constants");
+const error_mapping_1 = require("../errors/error_mapping");
+const native_errors_1 = require("../errors/native_errors");
+const native_handle_1 = require("../handles/native_handle");
+const native_1 = require("../native/native");
+const socket_options_1 = require("../sockets/socket_options");
+const timer_1 = require("./timer");
+const monitor_socket_1 = require("./monitor_socket");
+const completion_owner_1 = require("../messaging/completion_owner");
+function validateSlot(slot) {
+    if (!Number.isSafeInteger(slot) || slot < 0) {
+        throw new RangeError('slot must be a non-negative safe integer');
+    }
+    return slot;
+}
+function acquireCompletionOwner(owner, poller) {
+    try {
+        return owner.transferToPublic(poller);
+    }
+    catch (error) {
+        throw (0, error_mapping_1.createError)('config', 16, (0, native_errors_1.nativeErrorMessage)(error, 'poller completion ownership transfer failed'));
+    }
+}
+function validateMonitorEvents(events) {
+    if (events !== socket_constants_1.PollEventFlag.PollIn) {
+        throw (0, error_mapping_1.createError)('config', 22, 'socket monitor poll events must contain PollIn only');
+    }
+    return events;
+}
+class Poller {
+    _native;
+    _socketRegistrations = new Map();
+    _timerRegistrations = new Map();
+    _fdRegistrations = new Map();
+    _registrationsByToken = new Map();
+    _nextRegistrationToken = 1;
+    constructor() { this._native = (0, native_1.requireNative)().pollerNew(); }
+    add(item, eventsOrSlot, slot) {
+        if (item instanceof timer_1.Timer) {
+            this.addTimerInternal(item, eventsOrSlot);
+            return;
+        }
+        const events = (0, socket_options_1.flagsToMask)(eventsOrSlot);
+        this.addSocketInternal(item, item instanceof monitor_socket_1.MonitorSocket ? validateMonitorEvents(events) : events, slot);
+    }
+    modify(socket, events) {
+        const mask = (0, socket_options_1.flagsToMask)(events);
+        this.modifySocketInternal(socket, socket instanceof monitor_socket_1.MonitorSocket ? validateMonitorEvents(mask) : mask);
+    }
+    remove(item) {
+        if (item instanceof timer_1.Timer) {
+            return this.removeTimerInternal(item);
+        }
+        return this.removeSocketInternal(item);
+    }
+    addFd(fd, events, slot) {
+        const mask = (0, socket_options_1.flagsToMask)(events);
+        const normalizedFd = fd | 0;
+        const normalizedSlot = validateSlot(slot);
+        const nativeToken = this.allocateRegistrationToken();
+        try {
+            (0, native_1.requireNative)().pollerAddFd(this._native, normalizedFd, BigInt(nativeToken), mask);
+            const registration = {
+                source: normalizedFd,
+                slot: normalizedSlot,
+                nativeToken,
+            };
+            this._fdRegistrations.set(normalizedFd, registration);
+            this._registrationsByToken.set(nativeToken, registration);
+        }
+        catch (error) {
+            throw (0, error_mapping_1.createError)('config', (0, native_errors_1.readErrno)(), (0, native_errors_1.nativeErrorMessage)(error, 'poller fd add failed'));
+        }
+    }
+    modifyFd(fd, events) {
+        const mask = (0, socket_options_1.flagsToMask)(events);
+        const normalizedFd = fd | 0;
+        (0, native_errors_1.configCall)('poller fd modify failed', () => {
+            (0, native_1.requireNative)().pollerModifyFd(this._native, normalizedFd, mask);
+        });
+    }
+    removeFd(fd) {
+        const normalizedFd = fd | 0;
+        (0, native_errors_1.configCall)('poller fd remove failed', () => {
+            (0, native_1.requireNative)().pollerRemoveFd(this._native, normalizedFd);
+        });
+        const registration = this._fdRegistrations.get(normalizedFd);
+        this._fdRegistrations.delete(normalizedFd);
+        if (registration)
+            this._registrationsByToken.delete(registration.nativeToken);
+        return true;
+    }
+    get size() {
+        return (0, native_errors_1.configCall)('poller size failed', () => (0, native_1.requireNative)().pollerSize(this._native));
+    }
+    wait(events, timeoutMs) {
+        let nativeCount;
+        try {
+            nativeCount = (0, native_1.requireNative)().pollerWaitInto(this._native, (0, native_handle_1.getNativeHandle)(events), events.capacity | 0, timeoutMs | 0);
+        }
+        catch (error) {
+            if ((0, native_errors_1.isWouldBlock)()) {
+                events.markCombined(0, []);
+                return 0;
+            }
+            throw (0, native_errors_1.recvNativeError)(error, socket_constants_1.RecvFlags.None, 'poller wait failed');
+        }
+        events.markReadyCount(nativeCount | 0);
+        const processedEvents = [];
+        for (let index = 0; index < nativeCount; index += 1) {
+            let revents = events.revents(index);
+            const sourceKind = events.sourceKind(index);
+            const nativeSlot = events.slot(index);
+            const registration = this._registrationsByToken.get(nativeSlot);
+            if (!registration)
+                continue;
+            const socketRegistration = typeof registration.source === 'number'
+                ? undefined
+                : this._socketRegistrations.get(registration.source);
+            if (socketRegistration?.owner
+                && (revents & (socket_constants_1.PollEventFlag.PollOut | socket_constants_1.PollEventFlag.PollCompletion)) !== 0) {
+                const completionReady = socketRegistration.transferred
+                    && (revents & socket_constants_1.PollEventFlag.PollCompletion) !== 0;
+                const managedWritableReady = (revents & socket_constants_1.PollEventFlag.PollOut) !== 0
+                    && socketRegistration.owner.hasManagedWritableWait();
+                const processed = completionReady || managedWritableReady
+                    ? socketRegistration.owner.drain(this)
+                    : 0;
+                if (processed === 0) {
+                    revents &= ~socket_constants_1.PollEventFlag.PollCompletion;
+                }
+            }
+            if (revents === 0)
+                continue;
+            processedEvents.push({
+                source: registration.source,
+                sourceKind,
+                slot: registration.slot,
+                revents,
+                fd: events.fd(index),
+            });
+        }
+        events.markCombined(0, processedEvents);
+        return processedEvents.length;
+    }
+    destroy() {
+        if (this._native) {
+            (0, native_errors_1.closeCall)('poller close failed', () => {
+                (0, native_1.requireNative)().pollerDestroy(this._native);
+            });
+            this._native = null;
+            for (const registration of this._socketRegistrations.values()) {
+                if (registration.transferred)
+                    registration.owner.transferToRuntime(this);
+            }
+        }
+        this._socketRegistrations.clear();
+        this._timerRegistrations.clear();
+        this._fdRegistrations.clear();
+        this._registrationsByToken.clear();
+    }
+    close() { this.destroy(); }
+    addSocketInternal(socket, events, slot) {
+        const normalizedSlot = validateSlot(slot);
+        const owner = socket instanceof monitor_socket_1.MonitorSocket ? null : (0, completion_owner_1.completionOwnerOf)(socket);
+        const transferred = owner !== null
+            && (events & socket_constants_1.PollEventFlag.PollCompletion) !== 0;
+        const nativeToken = this.allocateRegistrationToken();
+        const handle = (0, native_handle_1.getNativeHandle)(socket);
+        const acquired = transferred ? acquireCompletionOwner(owner, this) : false;
+        try {
+            (0, native_1.requireNative)().pollerAdd(this._native, handle, BigInt(nativeToken), events | 0);
+            const registration = {
+                source: socket,
+                events: events | 0,
+                handle,
+                slot: normalizedSlot,
+                nativeToken,
+                owner,
+                transferred,
+            };
+            this._socketRegistrations.set(socket, registration);
+            this._registrationsByToken.set(nativeToken, registration);
+        }
+        catch (error) {
+            if (acquired)
+                owner.transferToRuntime(this);
+            throw (0, error_mapping_1.createError)('config', (0, native_errors_1.readErrno)(), (0, native_errors_1.nativeErrorMessage)(error, 'poller socket add failed'));
+        }
+    }
+    modifySocketInternal(socket, events) {
+        const handle = (0, native_handle_1.getNativeHandle)(socket);
+        const registration = this._socketRegistrations.get(socket);
+        const shouldTransfer = registration?.owner != null
+            && (events & socket_constants_1.PollEventFlag.PollCompletion) !== 0;
+        const acquired = registration?.owner && shouldTransfer && !registration.transferred
+            ? acquireCompletionOwner(registration.owner, this)
+            : false;
+        try {
+            (0, native_errors_1.configCall)('poller socket modify failed', () => {
+                (0, native_1.requireNative)().pollerModify(this._native, handle, events | 0);
+            });
+        }
+        catch (error) {
+            if (acquired)
+                registration.owner.transferToRuntime(this);
+            throw error;
+        }
+        if (registration) {
+            if (!shouldTransfer && registration.transferred) {
+                registration.owner.transferToRuntime(this);
+            }
+            registration.events = events | 0;
+            registration.transferred = shouldTransfer;
+        }
+    }
+    removeSocketInternal(socket) {
+        (0, native_errors_1.configCall)('poller socket remove failed', () => {
+            (0, native_1.requireNative)().pollerRemove(this._native, (0, native_handle_1.getNativeHandle)(socket));
+        });
+        const registration = this._socketRegistrations.get(socket);
+        if (registration?.transferred)
+            registration.owner.transferToRuntime(this);
+        this._socketRegistrations.delete(socket);
+        if (registration)
+            this._registrationsByToken.delete(registration.nativeToken);
+        return true;
+    }
+    allocateRegistrationToken() {
+        if (this._registrationsByToken.size >= Number.MAX_SAFE_INTEGER) {
+            throw new RangeError('poller registration token space exhausted');
+        }
+        for (;;) {
+            const token = this._nextRegistrationToken;
+            this._nextRegistrationToken = token === Number.MAX_SAFE_INTEGER
+                ? 1
+                : token + 1;
+            if (!this._registrationsByToken.has(token))
+                return token;
+        }
+    }
+    addTimerInternal(timer, slot) {
+        const normalizedSlot = validateSlot(slot);
+        const nativeToken = this.allocateRegistrationToken();
+        try {
+            (0, native_1.requireNative)().pollerAddTimer(this._native, (0, native_handle_1.getNativeHandle)(timer), BigInt(nativeToken));
+            const registration = {
+                source: timer,
+                slot: normalizedSlot,
+                nativeToken,
+            };
+            this._timerRegistrations.set(timer, registration);
+            this._registrationsByToken.set(nativeToken, registration);
+        }
+        catch (error) {
+            throw (0, error_mapping_1.createError)('config', (0, native_errors_1.readErrno)(), (0, native_errors_1.nativeErrorMessage)(error, 'poller timer add failed'));
+        }
+    }
+    removeTimerInternal(timer) {
+        (0, native_errors_1.configCall)('poller timer remove failed', () => {
+            (0, native_1.requireNative)().pollerRemoveTimer(this._native, (0, native_handle_1.getNativeHandle)(timer));
+        });
+        const registration = this._timerRegistrations.get(timer);
+        this._timerRegistrations.delete(timer);
+        if (registration)
+            this._registrationsByToken.delete(registration.nativeToken);
+        return true;
+    }
+}
+exports.Poller = Poller;
+exports.RuntimePoller = Poller;

package/dist/zlink/runtime/eventing/thread.d.ts

@@ -0,0 +1,6 @@
+export declare class Thread {
+    private readonly _state;
+    private readonly _worker;
+    constructor(handler: () => void);
+    join(): void;
+}

package/dist/zlink/runtime/eventing/thread.js

@@ -0,0 +1,52 @@
+"use strict";
+// SPDX-License-Identifier: MPL-2.0
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Thread = void 0;
+const node_worker_threads_1 = require("node:worker_threads");
+class Thread {
+    _state = new Int32Array(new SharedArrayBuffer(4));
+    _worker;
+    constructor(handler) {
+        if (typeof handler !== 'function') {
+            throw new TypeError('handler must be a function');
+        }
+        const source = `
+      const { workerData } = require('node:worker_threads');
+      const state = new Int32Array(workerData.state);
+      (async () => {
+        try {
+          const handler = (${handler.toString()});
+          await handler();
+          Atomics.store(state, 0, 1);
+        } catch {
+          Atomics.store(state, 0, 2);
+        } finally {
+          Atomics.notify(state, 0);
+        }
+      })();
+    `;
+        this._worker = new node_worker_threads_1.Worker(source, {
+            eval: true,
+            workerData: { state: this._state.buffer }
+        });
+        this._worker.on('error', () => {
+            Atomics.store(this._state, 0, 2);
+            Atomics.notify(this._state, 0);
+        });
+        this._worker.on('exit', (code) => {
+            if (code !== 0 && Atomics.load(this._state, 0) === 0) {
+                Atomics.store(this._state, 0, 2);
+                Atomics.notify(this._state, 0);
+            }
+        });
+    }
+    join() {
+        while (Atomics.load(this._state, 0) === 0) {
+            Atomics.wait(this._state, 0, 0);
+        }
+        if (Atomics.load(this._state, 0) === 2) {
+            throw new Error('thread handler failed');
+        }
+    }
+}
+exports.Thread = Thread;

package/dist/zlink/runtime/eventing/timer.d.ts

@@ -0,0 +1,8 @@
+import { NativeHandle } from '../handles/native_handle';
+export declare class Timer extends NativeHandle {
+    constructor();
+    start(intervalNs: bigint, repeatCount: bigint): void;
+    stop(): void;
+    recv(): bigint | null;
+    close(): void;
+}

package/dist/zlink/runtime/eventing/timer.js

@@ -0,0 +1,45 @@
+"use strict";
+// SPDX-License-Identifier: MPL-2.0
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Timer = void 0;
+const errors_1 = require("../../contracts/errors/errors");
+const socket_constants_1 = require("../../contracts/sockets/socket_constants");
+const native_errors_1 = require("../errors/native_errors");
+const native_1 = require("../native/native");
+const native_handle_1 = require("../handles/native_handle");
+class Timer extends native_handle_1.NativeHandle {
+    constructor() {
+        super((0, native_1.requireNative)().timerNew());
+    }
+    start(intervalNs, repeatCount) {
+        (0, native_errors_1.configCall)('timer start failed', () => {
+            (0, native_1.requireNative)().timerStart(this._native, intervalNs, repeatCount);
+        });
+    }
+    stop() {
+        (0, native_errors_1.configCall)('timer stop failed', () => {
+            (0, native_1.requireNative)().timerStop(this._native);
+        });
+    }
+    recv() {
+        const flags = socket_constants_1.RecvFlags.None;
+        try {
+            return (0, native_1.requireNative)().timerRecv(this._native, flags | 0);
+        }
+        catch (error) {
+            const recvError = (0, native_errors_1.recvNativeError)(error, flags, 'timer recv failed');
+            if (recvError.result === errors_1.RecvResult.NoData)
+                return null;
+            throw recvError;
+        }
+    }
+    close() {
+        if (this._native) {
+            (0, native_errors_1.closeCall)('timer close failed', () => {
+                (0, native_1.requireNative)().timerDestroy(this._native);
+            });
+            this._native = null;
+        }
+    }
+}
+exports.Timer = Timer;

package/dist/zlink/runtime/handles/native_handle.d.ts

@@ -0,0 +1,7 @@
+export declare function getNativeHandle(handle: NativeHandle): unknown;
+export declare class NativeHandle {
+    protected constructor(native: unknown);
+    protected get _native(): unknown | null;
+    protected set _native(native: unknown | null);
+    close(): void;
+}

package/dist/zlink/runtime/handles/native_handle.js

@@ -0,0 +1,24 @@
+"use strict";
+// SPDX-License-Identifier: MPL-2.0
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NativeHandle = void 0;
+exports.getNativeHandle = getNativeHandle;
+const nativeHandles = new WeakMap();
+function getNativeHandle(handle) {
+    return nativeHandles.get(handle) ?? null;
+}
+class NativeHandle {
+    constructor(native) {
+        nativeHandles.set(this, native);
+    }
+    get _native() {
+        return nativeHandles.get(this) ?? null;
+    }
+    set _native(native) {
+        nativeHandles.set(this, native);
+    }
+    close() {
+        this._native = null;
+    }
+}
+exports.NativeHandle = NativeHandle;

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

@@ -0,0 +1,86 @@
+import { Message, type MessageLike } from '../../contracts';
+import type { NativeHandle } from '../native/binding_types';
+import type { OperationPayloadValue } from './send_operation_base';
+export interface NativeCompletion {
+    readonly kind: number;
+    readonly completionId: bigint;
+    readonly userContext: bigint;
+    readonly peerRoutingId: Buffer | null;
+    readonly sendResult: number;
+    readonly terminalErrno: number;
+    readonly requestResult: number;
+    readonly parts?: Buffer[];
+}
+export interface NativeSubmitResult {
+    readonly result: number;
+    readonly nativeErrno: number;
+    readonly completionId: bigint;
+}
+export interface NativeSyncRequestResult extends NativeSubmitResult {
+    readonly completions: NativeCompletion[];
+}
+type CompletionKind = 'send' | 'request';
+export declare function consumeSubmittedMessages(payload: OperationPayloadValue<MessageLike>): void;
+/** Two-phase correlation entry: publish and capture may arrive in either order. */
+export declare class CompletionEntry<T> {
+    readonly token: bigint;
+    readonly kind: CompletionKind;
+    readonly expectsUserContext: boolean;
+    readonly promise: Promise<T>;
+    completionId: bigint;
+    published: boolean;
+    captured: boolean;
+    settled: boolean;
+    value: T | undefined;
+    error: unknown;
+    private capturedCompletionId;
+    private resolvePromise;
+    private rejectPromise;
+    constructor(token: bigint, kind: CompletionKind, expectsUserContext?: boolean);
+    publish(completionId: bigint): void;
+    awaitWritable(completionId: bigint): void;
+    succeed(value: T): void;
+    capture(completion: NativeCompletion): void;
+    fail(error: unknown): void;
+    private settleIfJoined;
+    private validateRequestCorrelation;
+}
+export declare class CompletionOwner {
+    private readonly handle;
+    private readonly native;
+    private readonly byToken;
+    private readonly byId;
+    private readonly retries;
+    private readonly writableRetries;
+    private nextToken;
+    private publicOwner;
+    private runtimeWatch;
+    private managedWritableWaitCount;
+    private closed;
+    constructor(handle: NativeHandle);
+    submitSend(payload: OperationPayloadValue<MessageLike>, routingId: Buffer | null): Promise<void>;
+    submitRequest(payload: OperationPayloadValue<MessageLike>, target: Buffer | null, timeoutMs: number): Promise<Message[]>;
+    requestSync(payload: OperationPayloadValue<MessageLike>, target: Buffer | null, timeoutMs: number): Message[];
+    sendSync(payload: OperationPayloadValue<MessageLike>, routingId: Buffer | null): void;
+    transferToPublic(owner: object): boolean;
+    transferToRuntime(owner: object): void;
+    drain(caller?: object): number;
+    hasManagedWritableWait(): boolean;
+    close(): void;
+    private register;
+    private createEntry;
+    private publish;
+    private capture;
+    private captureWritable;
+    private attemptRetry;
+    private failEntry;
+    private removeIfSettled;
+    private removeRetry;
+    private ensureRuntimeWatch;
+    private runtimeWake;
+    private closeRuntimeWatch;
+}
+export declare function installCompletionOwner(socket: object, handle: NativeHandle): CompletionOwner;
+export declare function completionOwnerOf(socket: object): CompletionOwner;
+export declare function releaseCompletionOwner(socket: object): void;
+export {};