@bjoernboss/mws 1.0.0 → 1.1.0

package/dist/server.js

@@ -13,232 +13,306 @@ export class Server extends libLog.Logger {
     _stop;
     _cache;
     _config;
-    _nextId;
+    _nextEndpoint;
     constructor(config) {
-        super('server');
+        super(config?.name ?? 'server');
         this.info(`Server created`);
         this._config = new BurntServerConfig(config);
         if (config?.cache instanceof libCache.CacheHost)
             this._cache = config.cache;
         else
             this._cache = libCache.createCache(config?.cache);
-        this._nextId = 0;
+        this._nextEndpoint = 0;
         let stoppedResolver = () => { };
-        this._stop = { listener: [], stoppedPromise: new Promise((res) => stoppedResolver = res), stoppedResolver: () => { }, stopping: false };
+        this._stop = { list: [], stoppedPromise: new Promise((res) => stoppedResolver = res), stoppedResolver: () => { }, stopping: false };
         this._stop.stoppedResolver = stoppedResolver;
     }
-    async handleClient(request, client, handler, id) {
-        this.log(`Listener[${id}]: Client [${client.logIdentity}] connected using [method: ${request.method ?? '_'}] from [${request.socket.remoteAddress}]:${request.socket.remotePort} to [${client.url.hostname}]:[${request.url}] (user-agent: [${request.headers['user-agent'] ?? ''}])`);
+    /** listener is automatically stopped when the server is stopped or the handler stops itself */
+    listen(handler, options) {
+        return Listener._fromParams(this, handler, ++this._nextEndpoint, this._stop, options ?? {});
+    }
+    /** shutdown the server and unlink all modules (immediately kills all open connections and listener; can be called multiple times) */
+    stop() {
+        if (this._stop.stopping)
+            return this._stop.stoppedPromise;
+        this._stop.stopping = true;
+        (async () => {
+            /* stop all connections and listener */
+            this.info('Stopping server connections and modules');
+            const promises = [];
+            for (const cb of this._stop.list)
+                promises.push(cb());
+            await Promise.all(promises);
+            this.info('Server stopped');
+            this._stop.stoppedResolver();
+        })();
+        return this._stop.stoppedPromise;
+    }
+    /** cache host used by this server */
+    get cache() {
+        return this._cache;
+    }
+    /** configuration used by this server */
+    get config() {
+        return this._config;
+    }
+    /** resolves once the server has stopped */
+    get stopped() {
+        return this._stop.stoppedPromise;
+    }
+    /** check if the server is still running */
+    get running() {
+        return !this._stop.stopping;
+    }
+    /** link the given module to the server (automatically unlinked upon server stop) */
+    linkModule(module, unlinked) {
+        const cleanup = () => attached.unlink();
+        this._stop.list.push(cleanup);
+        const attached = module._rootAttachToServer(this, () => {
+            if (unlinked != null)
+                unlinked();
+            if (!this._stop.stopping)
+                this._stop.list = this._stop.list.filter((v) => v != cleanup);
+        });
+        return attached;
+    }
+}
+/**
+*	Either 'listening' or 'failed' is fired, followed at some point by a 'stopped' event.
+*	'address' of 'listening' event is null for serverless listener.
+*/
+export class Listener {
+    _host;
+    _self;
+    _stop;
+    _native;
+    _handling;
+    _emitter;
+    _config;
+    constructor(server, id, hostStop, clientConfig, handler) {
+        this._host = { self: server, stop: hostStop };
+        this._self = { endpoint: `endpoint!${id}`, listening: null, protocol: '' };
+        this._emitter = new libEvents.EventEmitter();
+        this._config = clientConfig;
+        this._handling = { count: 0, promise: null, resolver: () => { } };
+        let stoppedResolver = () => { };
+        this._stop = { stoppedPromise: new Promise((res) => stoppedResolver = res), stoppedResolver: () => { }, stopping: false };
+        this._stop.stoppedResolver = stoppedResolver;
+        /* register the handler and the cleanup callback */
+        const attached = handler._rootAttachToServer(this._host.self, () => this.stop());
+        const wss = new libWs.WebSocketServer({ noServer: true });
+        this._native = { wss, attached, server: null, cleanup: () => this.stop() };
+        this._host.stop.list.push(this._native.cleanup);
+    }
+    emitEventSync(event, ...args) {
         try {
-            await handler.handle(client);
+            this._emitter.emit(event, ...args);
         }
         catch (err) {
-            client.respondInternalError(`Uncaught exception: ${err.message}`);
+            this._host.self.error(`Unhandled exception in ${event} listener: ${err.message}`);
         }
-        /* kill the connection on any errors, as the finalizing normally ensures that the response is completed */
+    }
+    performServerListening(address) {
+        if (typeof address == 'string')
+            address = { address, port: 0, family: 'unix' };
+        if (address == null)
+            this._self.listening = 'serverless';
+        else
+            this._self.listening = `[${address.address}]:${address.port} [family: ${address.family}]`;
+        this._host.self.info(`Successfully started ${this._self.endpoint} on ${this._self.listening} with handler [${this._native.attached.module.identity}]`);
+        this.emitEventSync('listening', address);
+    }
+    async handleClient(request, client) {
+        if (this._handling.count++ == 0)
+            this._handling.promise = new Promise((res) => this._handling.resolver = res);
+        const endpoint = `${this._host.self.identity}.${this._self.endpoint}`;
+        /* register the completed log immediately to ensure it is logged as the first thing before the other completed awaits execute */
+        client.log(`Connected to [${endpoint}] using [method: ${request.method ?? '_'}] from [${request.socket.remoteAddress}]:${request.socket.remotePort} to [${client.url.hostname}]:[${request.url}] (user-agent: [${request.headers['user-agent'] ?? ''}])`);
+        client.completed.then(() => client.log(`Completed on [${endpoint}]`));
         try {
-            await client.finalizeConnection();
+            await this._native.attached.handle(client);
         }
         catch (err) {
-            this.error(`Fatal error while finalizing client: ${err.message}`);
-            request.destroy(new Error('Unhandled exception'));
-        }
-        this.log(`Listener[${id}]: Client [${client.logIdentity}] completed`);
-    }
-    fetchAddress(server) {
-        const raw = server.address();
-        if (raw == null)
-            return null;
-        if (typeof raw == 'string')
-            return { address: raw, port: 0, family: 'unix' };
-        return raw;
-    }
-    async performServerCleanup(server, id, who, attached, wss) {
-        /* close the server and any existing connections within it */
-        const address = this.fetchAddress(server);
-        if (address != null && id != null)
-            this.info(`Stopping ${who} on [${address.address}]:${address.port} [family: ${address.family}] as listener [${id}] with handler [${attached.module.logIdentity}]`);
-        const serverStopped = new Promise((res) => server.close(() => res()));
-        server.closeAllConnections();
-        /* close all of the web-sockets (after unlinking the module to
-        *	ensure it has a chance to clean the connections itself) */
-        await attached.unlink();
-        const sockets = [];
-        for (const ws of [...wss.clients]) {
-            if (ws.readyState == libWs.WebSocket.CLOSED)
-                continue;
-            sockets.push(new Promise((res) => ws.on('close', () => res())));
-            ws.terminate();
+            client.respondInternalError(`Uncaught exception: ${err.message}`);
         }
-        await Promise.all(sockets);
-        /* await the server being fully stopped */
-        await serverStopped;
-    }
-    emitEventSync(emitter, event, ...args) {
+        /* kill the connection on any errors, as the finalizing normally ensures that the response is completed */
         try {
-            emitter.emit(event, ...args);
+            await client._finalizeConnection();
         }
         catch (err) {
-            this.error(`Unhandled exception in ${event} listener: ${err.message}`);
+            client.error(`Fatal error while finalizing [${client.identity}]: ${err.message}`);
+            request.destroy(new Error('Unhandled exception'));
         }
-    }
-    makeServer(options) {
-        if (options?.tls != null) {
-            const config = {
-                requireHostHeader: true,
-                key: libFs.readFileSync(options.tls.key),
-                cert: libFs.readFileSync(options.tls.cert),
-                connectionsCheckingInterval: CONNECTION_TIMEOUT_CHECKING
-            };
-            return libHttps.createServer(config);
+        if (--this._handling.count == 0) {
+            this._handling.promise = null;
+            this._handling.resolver();
         }
-        if (options?.server != null)
-            return options.server.server;
-        return libHttp.createServer({ requireHostHeader: true, connectionsCheckingInterval: CONNECTION_TIMEOUT_CHECKING });
     }
-    /* listener is automatically stopped when the server is stopped or the handler stops itself */
-    listen(handler, options) {
-        const protocol = ((options?.tls != null || options?.server?.secure === true) ? 'https' : 'http');
-        const who = `${protocol}:${options?.hostname ?? ''}:${options?.port ?? 0}`, idListener = this._nextId++;
-        const emitter = new libEvents.EventEmitter();
-        /* setup the listener interface to be returned */
-        let stopping = null, listenLogged = false;
-        let server = null;
-        const listener = {
-            on: function (event, cb) { emitter.on(event, cb); return this; },
-            once: function (event, cb) { emitter.once(event, cb); return this; },
-            off: function (event, cb) { emitter.off(event, cb); return this; },
-            stop: () => {
-                if (stopping != null)
-                    return stopping;
-                /* already setup the promise to ensure nested stop-calls will already see it set */
-                let resolver = () => { };
-                stopping = new Promise((res) => resolver = res);
-                (async () => {
-                    if (server != null)
-                        await this.performServerCleanup(server, (listenLogged ? idListener : null), who, attached, wss);
-                    /* check if the cleanup can be removed from the stop list (only if stopping is not already in progress) */
-                    if (!this._stop.stopping)
-                        this._stop.listener = this._stop.listener.filter((v) => v != listener.stop);
-                    this.emitEventSync(emitter, 'stopped');
-                    resolver();
-                })();
-                return stopping;
-            }
-        };
+    configure(options) {
+        this._self.protocol = ((options.tls != null || options.server?.secure === true || (options.server == null && options.serverless?.secure === true)) ? 'https' : 'http');
+        const who = (options.tls == null && options.server == null && options.serverless != null ? 'serverless' : `${this._self.protocol}|${options.hostname ?? ''}:${options.port ?? 0}`);
+        /* defer the failure to allow the caller to attach listeners */
         const performFailure = (err) => {
-            /* defer the failure to allow the caller to attach listeners */
             process.nextTick(() => {
-                if (stopping == null)
-                    this.emitEventSync(emitter, 'failed', err);
-                listener.stop();
+                if (!this._stop.stopping)
+                    this.emitEventSync('failed', err);
+                this.stop();
             });
         };
+        this._host.self.trace(`Setting up listening to [${who}] and handler [${this._native.attached.module.identity}]`);
         /* check if the server is being stopped, in which case nothing will be listened to */
-        if (this._stop.stopping) {
-            this.error(`Stopped server cannot listen to ${who}`);
-            performFailure(new Error('Server already stopped'));
-            return listener;
+        if (this._host.stop.stopping) {
+            this._host.self.error(`Stopped server cannot listen to [${who}]`);
+            return performFailure(new Error('Server already stopped'));
         }
-        /* setup the origin server */
+        let server = null;
         try {
-            server = this.makeServer(options);
+            /* setup the actual server server */
+            if (options.tls != null) {
+                const config = {
+                    requireHostHeader: true,
+                    key: libFs.readFileSync(options.tls.key),
+                    cert: libFs.readFileSync(options.tls.cert),
+                    connectionsCheckingInterval: CONNECTION_TIMEOUT_CHECKING
+                };
+                server = libHttps.createServer(config);
+            }
+            else if (options.server != null)
+                server = options.server.server;
+            else if (options.serverless == null)
+                server = libHttp.createServer({ requireHostHeader: true, connectionsCheckingInterval: CONNECTION_TIMEOUT_CHECKING });
         }
         catch (err) {
-            this.error(`Error creating server ${who}: ${err.message}`);
-            performFailure(err);
-            return listener;
+            this._host.self.error(`Error creating server [${who}]: ${err.message}`);
+            return performFailure(err);
         }
-        /* register the handler properly and register the cleanup callback */
-        const attached = handler._rootAttachToServer(this, () => listener.stop());
-        const wss = new libWs.WebSocketServer({ noServer: true });
-        this._stop.listener.push(listener.stop);
+        /* check if this is a serverless run, in which case the server does not need to be configured further */
+        if (server == null)
+            return this.performServerListening(null);
+        this._native.server = server;
         /* register the corresponding connection handlers and error handlers */
-        const clientConfig = (options?.client != null ? libClient.BurntClientConfig.from(options.client) : this._config.client);
-        server.on('request', (req, resp) => {
-            const client = libClient.ClientRequest.fromRequest(protocol, req, resp, { cache: this._cache, config: clientConfig });
-            this.handleClient(req, client, attached, idListener);
-        });
-        server.on('upgrade', (req, sock, head) => {
-            const client = libClient.ClientRequest.fromUpgrade(protocol, req, sock, head, { cache: this._cache, config: clientConfig, wss });
-            this.handleClient(req, client, attached, idListener);
-        });
+        server.on('request', (req, resp) => this.handleRequest(req, resp));
+        server.on('upgrade', (req, sock, head) => this.handleUpgrade(req, sock, head));
         server.once('error', (err) => {
-            if (stopping != null)
+            if (this._stop.stopping)
                 return;
-            this.error(`Error while listening to ${who}: ${err.message}`);
-            this.emitEventSync(emitter, 'failed', err);
-            listener.stop();
+            this._host.self.error(`Error while listening to [${who}]: ${err.message}`);
+            this.emitEventSync('failed', err);
+            this.stop();
         });
         server.on('listening', () => {
-            if (stopping != null)
-                return;
-            const address = this.fetchAddress(server);
-            this.info(`Successfully started ${who} on [${address.address}]:${address.port} [family: ${address.family}] as listener [${idListener}] with handler [${handler.logIdentity}]`);
-            listenLogged = true;
-            this.emitEventSync(emitter, 'listening', address);
+            if (!this._stop.stopping)
+                this.performServerListening(server.address());
         });
         /* configure the server to have a minimum header receive timeout, overall connection-loss timeout,
         *	and keep-alive timeout (no request-timeout, as this is handled manually by the throughput control) */
-        server.headersTimeout = this._config.headerTimeout;
-        server.timeout = this._config.connectionTimeout;
-        server.keepAliveTimeout = this._config.keepAliveTimeout;
+        server.headersTimeout = this._host.self.config.headerTimeout;
+        server.timeout = this._host.self.config.connectionTimeout;
+        server.keepAliveTimeout = this._host.self.config.keepAliveTimeout;
         server.requestTimeout = 0;
         /* start the actual server listening */
         try {
-            server.listen(options?.port, options?.hostname);
+            server.listen(options.port, options.hostname);
         }
         catch (err) {
-            this.error(`Error starting listener ${who}: ${err.message}`);
-            performFailure(err);
+            this._host.self.error(`Error starting listener [${who}]: ${err.message}`);
+            return performFailure(err);
         }
+    }
+    static _fromParams(server, handler, id, hostStop, options) {
+        const clientConfig = (options.client != null ? libClient.BurntClientConfig.from(options.client) : server.config.client);
+        const listener = new Listener(server, id, hostStop, clientConfig, handler);
+        listener.configure(options);
         return listener;
     }
-    /* shutdown the server and unlink all modules (immediately kills all open connections and listener; can be called multiple times) */
-    async stop() {
-        if (this._stop.stopping)
-            return this._stop.stoppedPromise;
-        this._stop.stopping = true;
-        /* stop all connections and listener */
-        this.info('Stopping server connections and modules');
-        const promises = [];
-        for (const cb of this._stop.listener)
-            promises.push(cb());
-        await Promise.all(promises);
-        this.info('Server stopped');
-        this._stop.stoppedResolver();
-        return this._stop.stoppedPromise;
+    /** manually pass a request through the listener (takes ownership of the request; will kill the connection if the listener is not running anymore) */
+    async handleRequest(request, response) {
+        if (this._stop.stopping) {
+            request.destroy(new Error('Listener not running anymore'));
+            return;
+        }
+        const client = libClient.ClientRequest._fromRequest(this._self.protocol, request, response, this._config, this._host.self);
+        await this.handleClient(request, client);
     }
-    /* cache host used by this server */
-    get cache() {
-        return this._cache;
+    /** manually pass an upgrade through the listener (takes ownership of the connection; immediately closes the connection if the listener is not running anymore) */
+    async handleUpgrade(request, socket, head) {
+        if (this._stop.stopping) {
+            request.destroy(new Error('Listener not running anymore'));
+            return;
+        }
+        const client = libClient.ClientRequest._fromUpgrade(this._self.protocol, request, socket, head, this._config, this._host.self, this._native.wss);
+        await this.handleClient(request, client);
+    }
+    /** server this listener belongs to */
+    get server() {
+        return this._host.self;
     }
-    /* configuration used by this server */
+    /** client configuration used for this listener */
     get config() {
         return this._config;
     }
-    /* resolves once the server has stopped */
+    /** stop the listener and return promise which resolves once fully stopped */
+    stop() {
+        if (this._stop.stopping)
+            return this._stop.stoppedPromise;
+        this._stop.stopping = true;
+        (async () => {
+            /* close the server and any existing connections within it */
+            let serverStopped = null;
+            if (this._native.server != null) {
+                serverStopped = new Promise((res) => this._native.server.close(() => res()));
+                this._native.server.closeAllConnections();
+            }
+            else
+                serverStopped = Promise.resolve();
+            await this._native.attached.unlink();
+            /* close all of the web-sockets (after unlinking the module to
+            *	ensure it has a chance to clean the connections itself) */
+            const sockets = [];
+            for (const ws of [...this._native.wss.clients]) {
+                if (ws.readyState == libWs.WebSocket.CLOSED)
+                    continue;
+                sockets.push(new Promise((res) => ws.on('close', () => res())));
+                ws.terminate();
+            }
+            await Promise.all(sockets);
+            /* wait for any handled connections to be over and for the server to be fully stopped */
+            while (this._handling.promise != null)
+                await this._handling.promise;
+            await serverStopped;
+            if (this._self.listening != null)
+                this._host.self.info(`Stopped ${this._self.endpoint} on ${this._self.listening} with handler [${this._native.attached.module.identity}]`);
+            /* check if the cleanup can be removed from the stop list (only if stopping is not already in progress) */
+            if (!this._host.stop.stopping)
+                this._host.stop.list = this._host.stop.list.filter((v) => v != this._native.cleanup);
+            this.emitEventSync('stopped');
+            this._stop.stoppedResolver();
+        })();
+        return this._stop.stoppedPromise;
+    }
+    /** resolves once the server has stopped */
     get stopped() {
         return this._stop.stoppedPromise;
     }
-    /* check if the server is still running */
+    /** check if the server is still running */
     get running() {
         return !this._stop.stopping;
     }
-    /* link the given module to the server (automatically unlinked upon server stop) */
-    linkModule(module, unlinked) {
-        const cleanup = () => attached.unlink();
-        this._stop.listener.push(cleanup);
-        const attached = module._rootAttachToServer(this, () => {
-            if (unlinked != null)
-                unlinked();
-            if (!this._stop.stopping)
-                this._stop.listener = this._stop.listener.filter((v) => v != cleanup);
-        });
-        return attached;
+    /* -------- event handler interfaces -------- */
+    on(event, listener) {
+        this._emitter.on(event, listener);
+        return this;
+    }
+    once(event, listener) {
+        this._emitter.once(event, listener);
+        return this;
+    }
+    off(event, listener) {
+        this._emitter.off(event, listener);
+        return this;
     }
 }
-/* wrapper to create a simple server */
+/** wrapper to create a simple server */
 export function createServer(config) {
     return new Server(config);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@bjoernboss/mws",
-	"version": "1.0.0",
+	"version": "1.1.0",
 	"type": "module",
 	"description": "Modular Web Server — a TypeScript framework for hosting isolated modules behind HTTP/HTTPS+WebSocket endpoints",
 	"license": "BSD-3-Clause",
@@ -16,12 +16,12 @@
 	"types": "dist/index.d.ts",
 	"exports": {
 		".": {
-			"types": "./dist/index.d.ts",
-			"default": "./dist/index.js"
+			"default": "./dist/index.js",
+			"types": "./dist/index.d.ts"
 		},
 		"./*.js": {
-			"types": "./dist/*.d.ts",
-			"default": "./dist/*.js"
+			"default": "./dist/*.js",
+			"types": "./dist/*.d.ts"
 		},
 		"./package.json": "./package.json"
 	},