@noxfly/noxus 1.1.10 → 2.0.0

package/src/app.ts

@@ -9,6 +9,7 @@ import { Injectable } from "src/decorators/injectable.decorator";
 import { IMiddleware } from "src/decorators/middleware.decorator";
 import { inject } from "src/DI/app-injector";
 import { IRequest, IResponse, Request } from "src/request";
+import { NoxSocket } from "src/socket";
 import { Router } from "src/router";
 import { Logger } from "src/utils/logger";
 import { Type } from "src/utils/types";
@@ -30,11 +31,41 @@ export interface IApp {
  */
 @Injectable('singleton')
 export class NoxApp {
-    private readonly messagePorts = new Map<number, Electron.MessageChannelMain>();
     private app: IApp | undefined;
 
+    /**
+     *
+     */
+    private readonly onRendererMessage = async (event: Electron.MessageEvent): Promise<void> => {
+        const { senderId, requestId, path, method, body }: IRequest = event.data;
+
+        const channels = this.socket.get(senderId);
+
+        if(!channels) {
+            Logger.error(`No message channel found for sender ID: ${senderId}`);
+            return;
+        }
+
+        try {
+            const request = new Request(event, senderId, requestId, method, path, body);
+            const response = await this.router.handle(request);
+            channels.request.port1.postMessage(response);
+        }
+        catch(err: any) {
+            const response: IResponse = {
+                requestId,
+                status: 500,
+                body: null,
+                error: err.message || 'Internal Server Error',
+            };
+
+            channels.request.port1.postMessage(response);
+        }
+    };
+
     constructor(
         private readonly router: Router,
+        private readonly socket: NoxSocket,
     ) {}
 
     /**
@@ -62,47 +93,20 @@ export class NoxApp {
     private giveTheRendererAPort(event: Electron.IpcMainInvokeEvent): void {
         const senderId = event.sender.id;
 
-        if(this.messagePorts.has(senderId)) {
+        if(this.socket.get(senderId)) {
             this.shutdownChannel(senderId);
         }
 
-        const channel = new MessageChannelMain();
-        this.messagePorts.set(senderId, channel);
-
-        channel.port1.on('message', this.onRendererMessage.bind(this));
-        channel.port1.start();
+        const requestChannel = new MessageChannelMain();
+        const socketChannel = new MessageChannelMain();
 
-        event.sender.postMessage('port', { senderId }, [channel.port2]);
-    }
-
-    /**
-     * Electron specific message handling.
-     * Replaces HTTP calls by using Electron's IPC mechanism.
-     */
-    private async onRendererMessage(event: Electron.MessageEvent): Promise<void> {
-        const { senderId, requestId, path, method, body }: IRequest = event.data;
+        requestChannel.port1.on('message', this.onRendererMessage);
+        requestChannel.port1.start();
+        socketChannel.port1.start();
 
-        const channel = this.messagePorts.get(senderId);
+        this.socket.register(senderId, requestChannel, socketChannel);
 
-        if(!channel) {
-            Logger.error(`No message channel found for sender ID: ${senderId}`);
-            return;
-        }
-        try {
-            const request = new Request(event, requestId, method, path, body);
-            const response = await this.router.handle(request);
-            channel.port1.postMessage(response);
-        }
-        catch(err: any) {
-            const response: IResponse = {
-                requestId,
-                status: 500,
-                body: null,
-                error: err.message || 'Internal Server Error',
-            };
-
-            channel.port1.postMessage(response);
-        }
+        event.sender.postMessage('port', { senderId }, [requestChannel.port2, socketChannel.port2]);
     }
 
     /**
@@ -122,18 +126,21 @@ export class NoxApp {
      * @param remove - Whether to remove the channel from the messagePorts map.
      */
     private shutdownChannel(channelSenderId: number): void {
-        const channel = this.messagePorts.get(channelSenderId);
+        const channels = this.socket.get(channelSenderId);
 
-        if(!channel) {
+        if(!channels) {
             Logger.warn(`No message channel found for sender ID: ${channelSenderId}`);
             return;
         }
 
-        channel.port1.off('message', this.onRendererMessage.bind(this));
-        channel.port1.close();
-        channel.port2.close();
+        channels.request.port1.off('message', this.onRendererMessage);
+        channels.request.port1.close();
+        channels.request.port2.close();
+
+        channels.socket.port1.close();
+        channels.socket.port2.close();
 
-        this.messagePorts.delete(channelSenderId);
+        this.socket.unregister(channelSenderId);
     }
 
     /**
@@ -141,11 +148,9 @@ export class NoxApp {
      * This method is called when all windows are closed, and it cleans up the message channels
      */
     private async onAllWindowsClosed(): Promise<void> {
-        this.messagePorts.forEach((channel, senderId) => {
+        for(const senderId of this.socket.getSenderIds()) {
             this.shutdownChannel(senderId);
-        });
-
-        this.messagePorts.clear();
+        }
 
         Logger.info('All windows closed, shutting down application...');
         await this.app?.dispose();

package/src/decorators/injectable.decorator.ts

@@ -6,7 +6,9 @@
 
 import { Lifetime } from "src/DI/app-injector";
 import { InjectorExplorer } from "src/DI/injector-explorer";
-import { Type } from "src/utils/types";
+import { defineInjectableMetadata } from "src/decorators/injectable.metadata";
+import { Type } from "src/main";
+export { getInjectableMetadata, hasInjectableMetadata, INJECTABLE_METADATA_KEY } from "src/decorators/injectable.metadata";
 
 /**
  * The Injectable decorator marks a class as injectable.
@@ -15,25 +17,12 @@ import { Type } from "src/utils/types";
  * either from the constructor of the class that needs it of from the `inject` function.
  * @param lifetime - The lifetime of the injectable. Can be 'singleton', 'scope', or 'transient'.
  */
-export function Injectable(lifetime: Lifetime = 'scope'): ClassDecorator {
+export function Injectable(lifetime: Lifetime = "scope"): ClassDecorator {
     return (target) => {
-        if(typeof target !== 'function' || !target.prototype) {
+        if (typeof target !== "function" || !target.prototype) {
             throw new Error(`@Injectable can only be used on classes, not on ${typeof target}`);
         }
-
-        Reflect.defineMetadata(INJECTABLE_METADATA_KEY, lifetime, target);
+        defineInjectableMetadata(target, lifetime);
         InjectorExplorer.register(target as unknown as Type<any>, lifetime);
     };
 }
-
-/**
- * Gets the injectable metadata for a given target class.
- * This metadata includes the lifetime of the injectable defined by the @Injectable decorator.
- * @param target - The target class to get the injectable metadata from.
- * @returns The lifetime of the injectable if it exists, otherwise undefined.
- */
-export function getInjectableMetadata(target: Type<unknown>): Lifetime | undefined {
-    return Reflect.getMetadata(INJECTABLE_METADATA_KEY, target);
-}
-
-export const INJECTABLE_METADATA_KEY = Symbol('INJECTABLE_METADATA_KEY');

package/src/decorators/injectable.metadata.ts

@@ -0,0 +1,15 @@
+import type { Lifetime } from "src/DI/app-injector";
+
+export const INJECTABLE_METADATA_KEY = Symbol("INJECTABLE_METADATA_KEY");
+
+export function defineInjectableMetadata(target: Function, lifetime: Lifetime): void {
+    Reflect.defineMetadata(INJECTABLE_METADATA_KEY, lifetime, target);
+}
+
+export function getInjectableMetadata(target: Function): Lifetime | undefined {
+    return Reflect.getMetadata(INJECTABLE_METADATA_KEY, target) as Lifetime | undefined;
+}
+
+export function hasInjectableMetadata(target: Function): boolean {
+    return Reflect.hasMetadata(INJECTABLE_METADATA_KEY, target);
+}

package/src/index.ts

@@ -4,17 +4,6 @@
  * @author NoxFly
  */
 
-export * from './DI/app-injector';
-export * from './router';
-export * from './app';
-export * from './bootstrap';
-export * from './exceptions';
-export * from './decorators/middleware.decorator';
-export * from './decorators/guards.decorator';
-export * from './decorators/controller.decorator';
-export * from './decorators/injectable.decorator';
-export * from './decorators/method.decorator';
-export * from './decorators/module.decorator';
-export * from './utils/logger';
-export * from './utils/types';
 export * from './request';
+export * from './renderer-events';
+export * from './renderer-client';

package/src/main.ts

@@ -0,0 +1,28 @@
+/**
+ * @copyright 2025 NoxFly
+ * @license MIT
+ * @author NoxFly
+ */
+
+/**
+ * Entry point for Electron main-process consumers.
+ */
+export * from './DI/app-injector';
+export * from './router';
+export * from './app';
+export * from './bootstrap';
+export * from './exceptions';
+export * from './decorators/middleware.decorator';
+export * from './decorators/guards.decorator';
+export * from './decorators/controller.decorator';
+export * from './decorators/injectable.decorator';
+export * from './decorators/method.decorator';
+export * from './decorators/module.decorator';
+export * from './preload-bridge';
+export * from './utils/logger';
+export * from './utils/types';
+export * from './request';
+export * from './renderer-events';
+export * from './renderer-client';
+export * from './socket';
+

package/src/preload-bridge.ts

@@ -0,0 +1,75 @@
+/**
+ * @copyright 2025 NoxFly
+ * @license MIT
+ * @author NoxFly
+ */
+
+import { contextBridge, ipcRenderer } from 'electron/renderer';
+import type { IPortRequester } from 'src/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/renderer-client.ts

@@ -0,0 +1,338 @@
+/**
+ * @copyright 2025 NoxFly
+ * @license MIT
+ * @author NoxFly
+ */
+
+import { IBatchRequestItem, IBatchResponsePayload, IRequest, IResponse } from 'src/request';
+import { RendererEventRegistry } from 'src/renderer-events';
+
+export interface IPortRequester {
+    requestPort(): void;
+}
+
+export interface RendererClientOptions {
+    bridge?: IPortRequester | null;
+    bridgeName?: string | string[];
+    initMessageType?: string;
+    windowRef?: Window;
+    generateRequestId?: () => string;
+}
+
+interface PendingRequest<T = unknown> {
+    resolve: (value: T) => void;
+    reject: (reason: IResponse<T>) => void;
+    request: IRequest;
+    submittedAt: number;
+}
+
+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 isReady = false;
+    private setupPromise: Promise<void> | undefined;
+    private setupResolve: (() => void) | undefined;
+    private setupReject: ((reason: Error) => void) | undefined;
+
+    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;
+    }
+
+    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;
+
+        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(),
+            };
+
+            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;
+        }
+
+        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(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);
+    }
+}