@noxfly/noxus 3.0.0-dev.4 → 3.0.0-dev.5

package/src/internal/exceptions.ts

@@ -1,57 +0,0 @@
-/**
- * @copyright 2025 NoxFly
- * @license MIT
- * @author NoxFly
- */
-
-export class ResponseException extends Error {
-    public readonly status: number = 0;
-
-    constructor(message?: string);
-    constructor(statusCode?: number, message?: string);
-    constructor(statusOrMessage?: number | string, message?: string) {
-        let statusCode: number | undefined;
-        
-        if(typeof statusOrMessage === 'number') {
-            statusCode = statusOrMessage;
-        }
-        else if(typeof statusOrMessage === 'string') {
-            message = statusOrMessage;
-        }
-
-        super(message ?? "");
-
-        if(statusCode !== undefined) {
-            this.status = statusCode;
-        }
-        
-        this.name = this.constructor.name
-            .replace(/([A-Z])/g, ' $1');
-    }
-}
-
-// 4XX
-export class BadRequestException extends ResponseException { public override readonly status = 400; }
-export class UnauthorizedException extends ResponseException { public override readonly status = 401; }
-export class PaymentRequiredException extends ResponseException { public override readonly status = 402; }
-export class ForbiddenException extends ResponseException { public override readonly status = 403; }
-export class NotFoundException extends ResponseException { public override readonly status = 404; }
-export class MethodNotAllowedException extends ResponseException { public override readonly status = 405; }
-export class NotAcceptableException extends ResponseException { public override readonly status = 406; }
-export class RequestTimeoutException extends ResponseException { public override readonly status = 408; }
-export class ConflictException extends ResponseException { public override readonly status = 409; }
-export class UpgradeRequiredException extends ResponseException { public override readonly status = 426; }
-export class TooManyRequestsException extends ResponseException { public override readonly status = 429; }
-// 5XX
-export class InternalServerException extends ResponseException { public override readonly status = 500; }
-export class NotImplementedException extends ResponseException { public override readonly status = 501; }
-export class BadGatewayException extends ResponseException { public override readonly status = 502; }
-export class ServiceUnavailableException extends ResponseException { public override readonly status = 503; }
-export class GatewayTimeoutException extends ResponseException { public override readonly status = 504; }
-export class HttpVersionNotSupportedException extends ResponseException { public override readonly status = 505; }
-export class VariantAlsoNegotiatesException extends ResponseException { public override readonly status = 506; }
-export class InsufficientStorageException extends ResponseException { public override readonly status = 507; }
-export class LoopDetectedException extends ResponseException { public override readonly status = 508; }
-export class NotExtendedException extends ResponseException { public override readonly status = 510; }
-export class NetworkAuthenticationRequiredException extends ResponseException { public override readonly status = 511; }
-export class NetworkConnectTimeoutException extends ResponseException { public override readonly status = 599; }

package/src/internal/preload-bridge.ts

@@ -1,75 +0,0 @@
-/**
- * @copyright 2025 NoxFly
- * @license MIT
- * @author NoxFly
- */
-
-import { contextBridge, ipcRenderer } from 'electron/renderer';
-import type { IPortRequester } from './renderer-client';
-
-export interface NoxusPreloadAPI extends IPortRequester {}
-
-export interface NoxusPreloadOptions {
-    exposeAs?: string;
-    initMessageType?: string;
-    requestChannel?: string;
-    responseChannel?: string;
-    targetWindow?: Window;
-}
-
-const DEFAULT_EXPOSE_NAME = 'noxus';
-const DEFAULT_INIT_EVENT = 'init-port';
-const DEFAULT_REQUEST_CHANNEL = 'gimme-my-port';
-const DEFAULT_RESPONSE_CHANNEL = 'port';
-
-/**
- * Exposes a minimal bridge in the isolated preload context so renderer processes
- * can request the two MessagePorts required by Noxus. The bridge forwards both
- * request/response and socket ports to the renderer via window.postMessage.
- */
-export function exposeNoxusBridge(options: NoxusPreloadOptions = {}): NoxusPreloadAPI {
-    const {
-        exposeAs = DEFAULT_EXPOSE_NAME,
-        initMessageType = DEFAULT_INIT_EVENT,
-        requestChannel = DEFAULT_REQUEST_CHANNEL,
-        responseChannel = DEFAULT_RESPONSE_CHANNEL,
-        targetWindow = window,
-    } = options;
-
-    const api: NoxusPreloadAPI = {
-        requestPort: () => {
-            ipcRenderer.send(requestChannel);
-
-            ipcRenderer.once(responseChannel, (event, message: { senderId: number }) => {
-                const ports = (event.ports ?? []).filter((port): port is MessagePort => port !== undefined);
-
-                if(ports.length === 0) {
-                    console.error('[Noxus] No MessagePort received from main process.');
-                    return;
-                }
-
-                for(const port of ports) {
-                    try {
-                        port.start();
-                    }
-                    catch(error) {
-                        console.error('[Noxus] Failed to start MessagePort.', error);
-                    }
-                }
-
-                targetWindow.postMessage(
-                    {
-                        type: initMessageType,
-                        senderId: message?.senderId,
-                    },
-                    '*',
-                    ports,
-                );
-            });
-        },
-    };
-
-    contextBridge.exposeInMainWorld(exposeAs, api);
-
-    return api;
-}

package/src/internal/renderer-client.ts

@@ -1,374 +0,0 @@
-/**
- * @copyright 2025 NoxFly
- * @license MIT
- * @author NoxFly
- */
-
-import { IBatchRequestItem, IBatchResponsePayload, IRequest, IResponse } from './request';
-import { RendererEventRegistry } from './renderer-events';
-
-export interface IPortRequester {
-    requestPort(): void;
-}
-
-export interface RendererClientOptions {
-    bridge?: IPortRequester | null;
-    bridgeName?: string | string[];
-    initMessageType?: string;
-    windowRef?: Window;
-    generateRequestId?: () => string;
-    /**
-     * Timeout in milliseconds for IPC requests.
-     * If the main process does not respond within this duration,
-     * the request Promise is rejected and the pending entry cleaned up.
-     * Defaults to 10 000 ms. Set to 0 to disable.
-     */
-    requestTimeout?: number;
-    /** @default true */
-    enableLogging?: boolean;
-}
-
-interface PendingRequest<T = unknown> {
-    resolve: (value: T) => void;
-    reject: (reason: IResponse<T>) => void;
-    request: IRequest;
-    submittedAt: number;
-    timer?: ReturnType<typeof setTimeout>;
-}
-
-const DEFAULT_INIT_EVENT = 'init-port';
-const DEFAULT_BRIDGE_NAMES = ['noxus', 'ipcRenderer'];
-
-function defaultRequestId(): string {
-    if(typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
-        return crypto.randomUUID();
-    }
-
-    return `${Date.now().toString(16)}-${Math.floor(Math.random() * 1e8).toString(16)}`;
-}
-
-function normalizeBridgeNames(preferred?: string | string[]): string[] {
-    const names: string[] = [];
-
-    const add = (name: string | undefined): void => {
-        if(!name)
-            return;
-
-        if(!names.includes(name)) {
-            names.push(name);
-        }
-    };
-
-    if(Array.isArray(preferred)) {
-        for(const name of preferred) {
-            add(name);
-        }
-    }
-    else {
-        add(preferred);
-    }
-
-    for(const fallback of DEFAULT_BRIDGE_NAMES) {
-        add(fallback);
-    }
-
-    return names;
-}
-
-function resolveBridgeFromWindow(windowRef: Window, preferred?: string | string[]): IPortRequester | null {
-    const names = normalizeBridgeNames(preferred);
-    const globalRef = windowRef as unknown as Record<string, unknown> | null | undefined;
-
-    if(!globalRef) {
-        return null;
-    }
-
-    for(const name of names) {
-        const candidate = globalRef[name];
-
-        if(candidate && typeof (candidate as IPortRequester).requestPort === 'function') {
-            return candidate as IPortRequester;
-        }
-    }
-
-    return null;
-}
-
-export class NoxRendererClient {
-    public readonly events = new RendererEventRegistry();
-
-    protected readonly pendingRequests = new Map<string, PendingRequest>();
-
-    protected requestPort: MessagePort | undefined;
-    protected socketPort: MessagePort | undefined;
-    protected senderId: number | undefined;
-
-    private readonly bridge: IPortRequester | null;
-    private readonly initMessageType: string;
-    private readonly windowRef: Window;
-    private readonly generateRequestId: () => string;
-    private readonly requestTimeout: number;
-
-    private isReady = false;
-    private setupPromise: Promise<void> | undefined;
-    private setupResolve: (() => void) | undefined;
-    private setupReject: ((reason: Error) => void) | undefined;
-
-    private enableLogging: boolean;
-
-    constructor(options: RendererClientOptions = {}) {
-        this.windowRef = options.windowRef ?? window;
-        const resolvedBridge = options.bridge ?? resolveBridgeFromWindow(this.windowRef, options.bridgeName);
-        this.bridge = resolvedBridge ?? null;
-        this.initMessageType = options.initMessageType ?? DEFAULT_INIT_EVENT;
-        this.generateRequestId = options.generateRequestId ?? defaultRequestId;
-        this.requestTimeout = options.requestTimeout ?? 10_000;
-        this.enableLogging = options.enableLogging ?? true;
-    }
-
-    public async setup(): Promise<void> {
-        if(this.isReady) {
-            return Promise.resolve();
-        }
-
-        if(this.setupPromise) {
-            return this.setupPromise;
-        }
-
-        if(!this.bridge || typeof this.bridge.requestPort !== 'function') {
-            throw new Error('[Noxus] Renderer bridge is missing requestPort().');
-        }
-
-        this.setupPromise = new Promise<void>((resolve, reject) => {
-            this.setupResolve = resolve;
-            this.setupReject = reject;
-        });
-
-        this.windowRef.addEventListener('message', this.onWindowMessage);
-        this.bridge.requestPort();
-
-        return this.setupPromise;
-    }
-
-    public dispose(): void {
-        this.windowRef.removeEventListener('message', this.onWindowMessage);
-
-        this.requestPort?.close();
-        this.socketPort?.close();
-
-        this.requestPort = undefined;
-        this.socketPort = undefined;
-        this.senderId = undefined;
-        this.isReady = false;
-
-        for(const pending of this.pendingRequests.values()) {
-            if(pending.timer !== undefined) {
-                clearTimeout(pending.timer);
-            }
-        }
-
-        this.pendingRequests.clear();
-    }
-
-    public async request<TResponse, TBody = unknown>(request: Omit<IRequest<TBody>, 'requestId' | 'senderId'>): Promise<TResponse> {
-        const senderId = this.senderId;
-        const requestId = this.generateRequestId();
-
-        if(senderId === undefined) {
-            return Promise.reject(this.createErrorResponse(requestId, 'MessagePort is not available'));
-        }
-
-        const readinessError = this.validateReady(requestId);
-
-        if(readinessError) {
-            return Promise.reject(readinessError as IResponse<TResponse>);
-        }
-
-        const message: IRequest<TBody> = {
-            requestId,
-            senderId,
-            ...request,
-        };
-
-        return new Promise<TResponse>((resolve, reject) => {
-            const pending: PendingRequest<TResponse> = {
-                resolve,
-                reject: (response: IResponse<TResponse>) => reject(response),
-                request: message,
-                submittedAt: Date.now(),
-            };
-
-            if(this.requestTimeout > 0) {
-                pending.timer = setTimeout(() => {
-                    this.pendingRequests.delete(message.requestId);
-                    reject(this.createErrorResponse<TResponse>(message.requestId, `Request timed out after ${this.requestTimeout}ms`) as IResponse<TResponse>);
-                }, this.requestTimeout);
-            }
-
-            this.pendingRequests.set(message.requestId, pending as PendingRequest);
-
-            this.requestPort!.postMessage(message);
-        });
-    }
-
-    public async batch(requests: Omit<IBatchRequestItem<unknown>, 'requestId'>[]): Promise<IBatchResponsePayload> {
-        return this.request<IBatchResponsePayload>({
-            method: 'BATCH',
-            path: '',
-            body: {
-                requests,
-            },
-        });
-    }
-
-    public getSenderId(): number | undefined {
-        return this.senderId;
-    }
-
-    private readonly onWindowMessage = (event: MessageEvent): void => {
-        if(event.data?.type !== this.initMessageType) {
-            return;
-        }
-
-        if(!Array.isArray(event.ports) || event.ports.length < 2) {
-            const error = new Error('[Noxus] Renderer expected two MessagePorts (request + socket).');
-
-            console.error(error);
-            this.setupReject?.(error);
-            this.resetSetupState();
-            return;
-        }
-
-        this.windowRef.removeEventListener('message', this.onWindowMessage);
-
-        this.requestPort = event.ports[0];
-        this.socketPort = event.ports[1];
-        this.senderId = event.data.senderId;
-
-        if(this.requestPort === undefined || this.socketPort === undefined) {
-            const error = new Error('[Noxus] Renderer failed to receive valid MessagePorts.');
-            console.error(error);
-            this.setupReject?.(error);
-            this.resetSetupState();
-            return;
-        }
-
-        this.attachRequestPort(this.requestPort);
-        this.attachSocketPort(this.socketPort);
-
-        this.isReady = true;
-        this.setupResolve?.();
-        this.resetSetupState(true);
-    };
-
-    private readonly onSocketMessage = (event: MessageEvent): void => {
-        if(this.events.tryDispatchFromMessageEvent(event)) {
-            return;
-        }
-
-        console.warn('[Noxus] Received a socket message that is not a renderer event payload.', event.data);
-    };
-
-    private readonly onRequestMessage = (event: MessageEvent): void => {
-        if(this.events.tryDispatchFromMessageEvent(event)) {
-            return;
-        }
-
-        const response: IResponse = event.data;
-
-        if(!response || typeof response.requestId !== 'string') {
-            console.error('[Noxus] Renderer received an invalid response payload.', response);
-            return;
-        }
-
-        const pending = this.pendingRequests.get(response.requestId);
-
-        if(!pending) {
-            console.error(`[Noxus] No pending handler found for request ${response.requestId}.`);
-            return;
-        }
-
-        if(pending.timer !== undefined) {
-            clearTimeout(pending.timer);
-        }
-
-        this.pendingRequests.delete(response.requestId);
-
-        this.onRequestCompleted(pending, response);
-
-        if(response.status >= 400) {
-            pending.reject(response as IResponse<any>);
-            return;
-        }
-
-        pending.resolve(response.body as unknown);
-    };
-
-    protected onRequestCompleted(pending: PendingRequest, response: IResponse): void {
-        if(!this.enableLogging) {
-            return;
-        }
-
-        if(typeof console.groupCollapsed === 'function') {
-            console.groupCollapsed(`${response.status} ${pending.request.method} /${pending.request.path}`);
-        }
-
-        if(response.error) {
-            console.error('error message:', response.error);
-        }
-
-        if(response.body !== undefined) {
-            console.info('response:', response.body);
-        }
-
-        console.info('request:', pending.request);
-        console.info(`Request duration: ${Date.now() - pending.submittedAt} ms`);
-
-        if(typeof console.groupCollapsed === 'function') {
-            console.groupEnd();
-        }
-    }
-
-    private attachRequestPort(port: MessagePort): void {
-        port.onmessage = this.onRequestMessage;
-        port.start();
-    }
-
-    private attachSocketPort(port: MessagePort): void {
-        port.onmessage = this.onSocketMessage;
-        port.start();
-    }
-
-    private validateReady(requestId: string): IResponse | undefined {
-        if(!this.isElectronEnvironment()) {
-            return this.createErrorResponse(requestId, 'Not running in Electron environment');
-        }
-
-        if(!this.requestPort) {
-            return this.createErrorResponse(requestId, 'MessagePort is not available');
-        }
-
-        return undefined;
-    }
-
-    private createErrorResponse<T>(requestId: string, message: string): IResponse<T> {
-        return {
-            status: 500,
-            requestId,
-            error: message,
-        };
-    }
-
-    private resetSetupState(success = false): void {
-        if(!success) {
-            this.setupPromise = undefined;
-        }
-
-        this.setupResolve = undefined;
-        this.setupReject = undefined;
-    }
-
-    public isElectronEnvironment(): boolean {
-        return typeof window !== 'undefined' && /Electron/.test(window.navigator.userAgent);
-    }
-}

package/src/internal/renderer-events.ts

@@ -1,110 +0,0 @@
-/**
- * @copyright 2025 NoxFly
- * @license MIT
- * @author NoxFly
- */
-
-/**
- * Lightweight event registry to help renderer processes subscribe to
- * push messages sent by the main process through Noxus.
- */
-import { IRendererEventMessage, isRendererEventMessage } from './request';
-
-export type RendererEventHandler<TPayload = unknown> = (payload: TPayload) => void;
-
-export interface RendererEventSubscription {
-    unsubscribe(): void;
-}
-
-export class RendererEventRegistry {
-    private readonly listeners = new Map<string, Set<RendererEventHandler>>();
-
-    /**
-     *
-     */
-    public subscribe<TPayload>(eventName: string, handler: RendererEventHandler<TPayload>): RendererEventSubscription {
-        const normalizedEventName = eventName.trim();
-
-        if(normalizedEventName.length === 0) {
-            throw new Error('Renderer event name must be a non-empty string.');
-        }
-
-        const handlers = this.listeners.get(normalizedEventName) ?? new Set<RendererEventHandler>();
-
-        handlers.add(handler as RendererEventHandler);
-        this.listeners.set(normalizedEventName, handlers);
-
-        return {
-            unsubscribe: () => this.unsubscribe(normalizedEventName, handler as RendererEventHandler),
-        };
-    }
-
-    /**
-     *
-     */
-    public unsubscribe<TPayload>(eventName: string, handler: RendererEventHandler<TPayload>): void {
-        const handlers = this.listeners.get(eventName);
-
-        if(!handlers) {
-            return;
-        }
-
-        handlers.delete(handler as RendererEventHandler);
-
-        if(handlers.size === 0) {
-            this.listeners.delete(eventName);
-        }
-    }
-
-    /**
-     *
-     */
-    public clear(eventName?: string): void {
-        if(eventName) {
-            this.listeners.delete(eventName);
-            return;
-        }
-
-        this.listeners.clear();
-    }
-
-    /**
-     *
-     */
-    public dispatch<TPayload>(message: IRendererEventMessage<TPayload>): void {
-        const handlers = this.listeners.get(message.event);
-
-        if(!handlers || handlers.size === 0) {
-            return;
-        }
-
-        handlers.forEach((handler) => {
-            try {
-                handler(message.payload as TPayload);
-            }
-            catch(error) {
-                console.error(`[Noxus] Renderer event handler for "${message.event}" threw an error.`, error);
-            }
-        });
-    }
-
-    /**
-     *
-     */
-    public tryDispatchFromMessageEvent(event: MessageEvent): boolean {
-        if(!isRendererEventMessage(event.data)) {
-            return false;
-        }
-
-        this.dispatch(event.data);
-        return true;
-    }
-
-    /**
-     *
-     */
-    public hasHandlers(eventName: string): boolean {
-        const handlers = this.listeners.get(eventName);
-        return !!handlers && handlers.size > 0;
-    }
-}