redweb 0.8.0 → 0.9.0

package/src/http/BaseHttpServer.js

@@ -1,9 +1,9 @@
-const express = require('express');
-const path = require('path');
+const express = require('express');
+const path = require('path');
 const cors = require('cors');
 const fs = require('fs');
-const HtmxRenderer = require('../htmx/HtmxRenderer'); // Import the HtmxRenderer module
-const { validateListenerOptions } = require('../serverLifecycle');
+const HtmxRenderer = require('../htmx/HtmxRenderer'); // Import the HtmxRenderer module
+const { validateListenerOptions } = require('../serverLifecycle');
 
 /**
  * @typedef {'json' | 'urlencoded'} RedWebEncoding
@@ -15,14 +15,14 @@ const { validateListenerOptions } = require('../serverLifecycle');
  * @property {number} [port=80] - The port number to bind the server.
  * @property {string} [bind='0.0.0.0'] - The bind address for the server.
  * @property {string[]} [publicPaths=['./public']] - An array of paths to serve static files from.
- * @property {Array<{serviceName: string, method: string, function: Function}>} [services=[]] - An array of services with their endpoints and handlers.
- * @property {boolean} [listen=true] - Whether HttpServer/HttpsServer should automatically start listening.
- * @property {Function} [listenCallback] - Callback function to execute once the server starts listening.
+ * @property {Array<{serviceName: string, method: string, function: Function}>} [services=[]] - An array of services with their endpoints and handlers.
+ * @property {boolean} [listen=true] - Whether HttpServer/HttpsServer should automatically start listening.
+ * @property {Function} [listenCallback] - Callback function to execute once the server starts listening.
  * @property {RedWebEncoding} [encoding='json'] - The encoding type for the request bodies ('json' or 'urlencoded').
  * @property {Object} [ssl] - SSL configuration for HTTPS server.
  * @property {string} [ssl.key] - Path to the SSL key file.
  * @property {string} [ssl.cert] - Path to the SSL certificate file.
- * @property {import('express').Application} [server] - Existing Express application to configure.
+ * @property {import('express').Application} [server] - Existing Express application to configure.
  * @property {import('cors').CorsOptions} [corsOptions] - The CORS Options.
  * @property {boolean} [enableHtmxRendering=false] - Enable dynamic HTMX file rendering.
  */
@@ -31,132 +31,132 @@ const ENCODINGS = { json: 'json', urlencoded: 'urlencoded' };
 const HTTP_OPTIONS = {
     port: 80,
     bind: '0.0.0.0',
-    publicPaths: ['./public'],
-    services: [],
-    listen: true,
-    listenCallback: undefined,
+    publicPaths: ['./public'],
+    services: [],
+    listen: true,
+    listenCallback: undefined,
     encoding: ENCODINGS.json,
     ssl: null,
     server: undefined,
     corsOptions: undefined,
-    enableHtmxRendering: false, // New option for HTMX rendering
-    exposeErrors: false,
-    logger: console,
-};
-
-function assertOptions(options) {
-    validateListenerOptions(options);
-    if (!Object.values(ENCODINGS).includes(options.encoding)) {
-        throw new TypeError('`encoding` must be either "json" or "urlencoded".');
-    }
-    if (!Array.isArray(options.publicPaths)) {
-        throw new TypeError('`publicPaths` must be an array.');
-    }
-    if (options.publicPaths.some(publicPath => typeof publicPath !== 'string' || !publicPath)) {
-        throw new TypeError('Every public path must be a non-empty string.');
-    }
-    if (!Array.isArray(options.services)) {
-        throw new TypeError('`services` must be an array.');
-    }
-
-    options.services.forEach((service) => {
-        if (!service || typeof service.serviceName !== 'string' || !service.serviceName) {
-            throw new TypeError('Every service must have a non-empty `serviceName`.');
-        }
-        if (!['get', 'post', 'put', 'delete', 'patch', 'options', 'head', 'all'].includes(service.method)) {
-            throw new TypeError(`Unsupported HTTP service method: ${service.method}`);
-        }
-        if (typeof service.function !== 'function') {
-            throw new TypeError(`Service ${service.serviceName} must provide a function.`);
-        }
-    });
-    if (options.services.filter(service => service.serviceName === '*').length > 1) {
-        throw new TypeError('Only one catch-all service may be registered.');
-    }
-}
-
-function isWithin(root, candidate) {
-    const relative = path.relative(root, candidate);
-    return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative));
-}
+    enableHtmxRendering: false, // New option for HTMX rendering
+    exposeErrors: false,
+    logger: console,
+};
+
+function assertOptions(options) {
+    validateListenerOptions(options);
+    if (!Object.values(ENCODINGS).includes(options.encoding)) {
+        throw new TypeError('`encoding` must be either "json" or "urlencoded".');
+    }
+    if (!Array.isArray(options.publicPaths)) {
+        throw new TypeError('`publicPaths` must be an array.');
+    }
+    if (options.publicPaths.some(publicPath => typeof publicPath !== 'string' || !publicPath)) {
+        throw new TypeError('Every public path must be a non-empty string.');
+    }
+    if (!Array.isArray(options.services)) {
+        throw new TypeError('`services` must be an array.');
+    }
+
+    options.services.forEach((service) => {
+        if (!service || typeof service.serviceName !== 'string' || !service.serviceName) {
+            throw new TypeError('Every service must have a non-empty `serviceName`.');
+        }
+        if (!['get', 'post', 'put', 'delete', 'patch', 'options', 'head', 'all'].includes(service.method)) {
+            throw new TypeError(`Unsupported HTTP service method: ${service.method}`);
+        }
+        if (typeof service.function !== 'function') {
+            throw new TypeError(`Service ${service.serviceName} must provide a function.`);
+        }
+    });
+    if (options.services.filter(service => service.serviceName === '*').length > 1) {
+        throw new TypeError('Only one catch-all service may be registered.');
+    }
+}
+
+function isWithin(root, candidate) {
+    const relative = path.relative(root, candidate);
+    return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative));
+}
 
 /**
  * Base HTTP Server
  * @param {RedWebOptions} options - Configuration options for RedWeb.
  * @return {Object} Express application instance.
  */
-function BaseHttpServer(options = {}) {
-    if (!options || typeof options !== 'object' || Array.isArray(options)) {
-        throw new TypeError('HTTP server options must be an object.');
-    }
-    const mergedOptions = { ...HTTP_OPTIONS, ...options };
-    assertOptions(mergedOptions);
-    this.options = {
-        ...mergedOptions,
-        publicPaths: [...mergedOptions.publicPaths],
-        services: [...mergedOptions.services],
-    };
-    this.app = this.options.server === undefined ? express() : this.options.server;
-    if (typeof this.app.use !== 'function') {
-        throw new TypeError('`server` must be an Express-compatible application.');
-    }
-    Object.assign(this, this.options);
+function BaseHttpServer(options = {}) {
+    if (!options || typeof options !== 'object' || Array.isArray(options)) {
+        throw new TypeError('HTTP server options must be an object.');
+    }
+    const mergedOptions = { ...HTTP_OPTIONS, ...options };
+    assertOptions(mergedOptions);
+    this.options = {
+        ...mergedOptions,
+        publicPaths: [...mergedOptions.publicPaths],
+        services: [...mergedOptions.services],
+    };
+    this.app = this.options.server === undefined ? express() : this.options.server;
+    if (typeof this.app.use !== 'function') {
+        throw new TypeError('`server` must be an Express-compatible application.');
+    }
+    Object.assign(this, this.options);
 
     // Middleware to parse request bodies based on the specified encoding
-    if (this.encoding === ENCODINGS.json) {
-        this.app.use(express.json());
-    } else {
-        this.app.use(express.urlencoded({ extended: true }));
-    }
-
-    if (this.options.corsOptions !== false) {
-        this.app.use(cors(this.options.corsOptions));
-    }
+    if (this.encoding === ENCODINGS.json) {
+        this.app.use(express.json());
+    } else {
+        this.app.use(express.urlencoded({ extended: true }));
+    }
+
+    if (this.options.corsOptions !== false) {
+        this.app.use(cors(this.options.corsOptions));
+    }
 
     // Enable HTMX rendering if the flag is set
     if (this.enableHtmxRendering) {
-        this.app.get('*.htmx', (req, res) => {
-            const match = this.publicPaths
-                .map(publicPath => {
-                    const root = path.resolve(process.cwd(), publicPath);
-                    const filePath = path.resolve(root, `.${req.path}`);
-                    return { root, filePath };
-                })
-                .find(({ root, filePath }) => isWithin(root, filePath) && fs.existsSync(filePath));
-    
-            if (!match) {
-                return res.status(404).send('HTMX template not found');
-            }
-    
-            try {
-                const renderedContent = HtmxRenderer.render(match.filePath, { rootDir: match.root });
-                res.type('html').send(renderedContent);
-            } catch (error) {
-                const message = this.exposeErrors ? `Error rendering HTMX file: ${error.message}` : 'Unable to render HTMX template';
-                res.status(500).send(message);
-            }
-        });
+        this.app.get('*.htmx', (req, res) => {
+            const match = this.publicPaths
+                .map(publicPath => {
+                    const root = path.resolve(process.cwd(), publicPath);
+                    const filePath = path.resolve(root, `.${req.path}`);
+                    return { root, filePath };
+                })
+                .find(({ root, filePath }) => isWithin(root, filePath) && fs.existsSync(filePath));
+    
+            if (!match) {
+                return res.status(404).send('HTMX template not found');
+            }
+    
+            try {
+                const renderedContent = HtmxRenderer.render(match.filePath, { rootDir: match.root });
+                res.type('html').send(renderedContent);
+            } catch (error) {
+                const message = this.exposeErrors ? `Error rendering HTMX file: ${error.message}` : 'Unable to render HTMX template';
+                res.status(500).send(message);
+            }
+        });
     }
     
 
-    // Serve static files from public paths
-    this.publicPaths.forEach((publicPath) =>
-        this.app.use(express.static(path.resolve(process.cwd(), publicPath)))
-    );
+    // Serve static files from public paths
+    this.publicPaths.forEach((publicPath) =>
+        this.app.use(express.static(path.resolve(process.cwd(), publicPath)))
+    );
 
-    const catchAll = this.services.find((service) => service.serviceName === '*');
-    this.services.filter((service) => service !== catchAll).forEach((service) =>
-        this.app[service.method](service.serviceName, service.function)
-    );
+    const catchAll = this.services.find((service) => service.serviceName === '*');
+    this.services.filter((service) => service !== catchAll).forEach((service) =>
+        this.app[service.method](service.serviceName, service.function)
+    );
     if (catchAll) this.app[catchAll.method](catchAll.serviceName, catchAll.function);
 
     return this;
 }
 
 
-module.exports = {
-    BaseHttpServer,
-    ENCODINGS,
-    HTTP_OPTIONS,
-    METHODS: { GET: 'get', POST: 'post', PUT: 'put', PATCH: 'patch', DELETE: 'delete', OPTIONS: 'options', HEAD: 'head', ALL: 'all' },
-};
+module.exports = {
+    BaseHttpServer,
+    ENCODINGS,
+    HTTP_OPTIONS,
+    METHODS: { GET: 'get', POST: 'post', PUT: 'put', PATCH: 'patch', DELETE: 'delete', OPTIONS: 'options', HEAD: 'head', ALL: 'all' },
+};

package/src/http/HttpServer.js

@@ -1,26 +1,26 @@
-const http = require('http');
-const { BaseHttpServer } = require('./BaseHttpServer');
-const { listenServer, closeServer } = require('../serverLifecycle');
+const http = require('http');
+const { BaseHttpServer } = require('./BaseHttpServer');
+const { listenServer, closeServer } = require('../serverLifecycle');
 
 /**
  * HTTP Server
  * @param {RedWebOptions} options - Configuration options for RedWeb.
  * @return {Object} Express application instance.
  */
-function HttpServer(options) {
-    BaseHttpServer.call(this, options);
-    this.server = http.createServer(this.app);
-    this.shutdown = () => closeServer(this.server);
-    if (this.listen !== false) {
-        listenServer(this.server, {
-            port: this.port,
-            bind: this.bind,
-            callback: this.listenCallback,
-            logger: this.logger,
-            name: 'HttpServer',
-        });
-    }
-    return this;
-}
+function HttpServer(options) {
+    BaseHttpServer.call(this, options);
+    this.server = http.createServer(this.app);
+    this.shutdown = () => closeServer(this.server);
+    if (this.listen !== false) {
+        listenServer(this.server, {
+            port: this.port,
+            bind: this.bind,
+            callback: this.listenCallback,
+            logger: this.logger,
+            name: 'HttpServer',
+        });
+    }
+    return this;
+}
 
 module.exports = HttpServer;

package/src/http/HttpsServer.js

@@ -1,30 +1,30 @@
 const https = require('https');
 const { BaseHttpServer } = require('./BaseHttpServer');
-const loadSslConfig = require('../sslConfig');
-const { listenServer, closeServer } = require('../serverLifecycle');
+const loadSslConfig = require('../sslConfig');
+const { listenServer, closeServer } = require('../serverLifecycle');
 
 /**
  * HTTPS Server
  * @param {RedWebOptions} options - Configuration options for RedWeb.
  * @return {Object} Express application instance.
  */
-function HttpsServer(options) {
-    BaseHttpServer.call(this, options);
-    const sslOptions = loadSslConfig(this.ssl);
-    this.server = https.createServer(sslOptions, this.app);
-    this.shutdown = () => closeServer(this.server);
-    if (this.listen === false) {
-        return this;
-    }
-
-    listenServer(this.server, {
-        port: this.port,
-        bind: this.bind,
-        callback: this.listenCallback,
-        logger: this.logger,
-        name: 'HttpsServer',
-    });
-    return this;
-}
+function HttpsServer(options) {
+    BaseHttpServer.call(this, options);
+    const sslOptions = loadSslConfig(this.ssl);
+    this.server = https.createServer(sslOptions, this.app);
+    this.shutdown = () => closeServer(this.server);
+    if (this.listen === false) {
+        return this;
+    }
+
+    listenServer(this.server, {
+        port: this.port,
+        bind: this.bind,
+        callback: this.listenCallback,
+        logger: this.logger,
+        name: 'HttpsServer',
+    });
+    return this;
+}
 
 module.exports = HttpsServer;

package/src/serverLifecycle.js

@@ -1,46 +1,46 @@
-function listenServer(server, { port, bind, callback, logger = console, name = 'Server' }) {
-    const onListening = callback || (() => logger?.log?.(`RedWeb ${name} listening on ${bind}:${port}`));
-    server.listen(port, bind, onListening);
-}
-
-function validateListenerOptions(options) {
-    if (!Number.isInteger(options.port) || options.port < 0 || options.port > 65535) {
-        throw new TypeError('`port` must be an integer between 0 and 65535.');
-    }
-    if (typeof options.bind !== 'string' || !options.bind) {
-        throw new TypeError('`bind` must be a non-empty string.');
-    }
-    if (typeof options.listen !== 'boolean') {
-        throw new TypeError('`listen` must be a boolean.');
-    }
-    if (options.listenCallback !== undefined && typeof options.listenCallback !== 'function') {
-        throw new TypeError('`listenCallback` must be a function.');
-    }
-}
-
-async function settleTasks(tasks) {
-    const results = await Promise.allSettled(tasks.map(task => Promise.resolve().then(task)));
-    return results.filter(result => result.status === 'rejected').map(result => result.reason);
-}
-
-function throwCleanupErrors(errors, message) {
-    if (!errors.length) return;
-    const aggregate = new Error(message);
-    aggregate.errors = errors;
-    throw aggregate;
-}
-
-function closeServer(server) {
-    return new Promise((resolve, reject) => {
-        if (!server?.listening) return resolve();
-        server.close((error) => error ? reject(error) : resolve());
-    });
-}
-
-module.exports = {
-    listenServer,
-    closeServer,
-    settleTasks,
-    throwCleanupErrors,
-    validateListenerOptions,
-};
+function listenServer(server, { port, bind, callback, logger = console, name = 'Server' }) {
+    const onListening = callback || (() => logger?.log?.(`RedWeb ${name} listening on ${bind}:${port}`));
+    server.listen(port, bind, onListening);
+}
+
+function validateListenerOptions(options) {
+    if (!Number.isInteger(options.port) || options.port < 0 || options.port > 65535) {
+        throw new TypeError('`port` must be an integer between 0 and 65535.');
+    }
+    if (typeof options.bind !== 'string' || !options.bind) {
+        throw new TypeError('`bind` must be a non-empty string.');
+    }
+    if (typeof options.listen !== 'boolean') {
+        throw new TypeError('`listen` must be a boolean.');
+    }
+    if (options.listenCallback !== undefined && typeof options.listenCallback !== 'function') {
+        throw new TypeError('`listenCallback` must be a function.');
+    }
+}
+
+async function settleTasks(tasks) {
+    const results = await Promise.allSettled(tasks.map(task => Promise.resolve().then(task)));
+    return results.filter(result => result.status === 'rejected').map(result => result.reason);
+}
+
+function throwCleanupErrors(errors, message) {
+    if (!errors.length) return;
+    const aggregate = new Error(message);
+    aggregate.errors = errors;
+    throw aggregate;
+}
+
+function closeServer(server) {
+    return new Promise((resolve, reject) => {
+        if (!server?.listening) return resolve();
+        server.close((error) => error ? reject(error) : resolve());
+    });
+}
+
+module.exports = {
+    listenServer,
+    closeServer,
+    settleTasks,
+    throwCleanupErrors,
+    validateListenerOptions,
+};

package/src/ws/AdmissionPolicy.js

@@ -0,0 +1,145 @@
+const ADMISSION_CONTEXT = Symbol('redweb.admissionContext');
+const PLACEMENT_REDIRECT = Symbol('redweb.placementRedirect');
+const ADMISSION_SETTLEMENT = Symbol('redweb.admissionSettlement');
+
+class AdmissionPolicy {
+    constructor(options) {
+        const config = typeof options === 'function' ? { authenticate: options } : options;
+        if (!config || typeof config !== 'object' || Array.isArray(config)) {
+            throw new TypeError('`admission` must be a function or an object.');
+        }
+        const {
+            authenticate,
+            origins,
+            place,
+            timeoutMs = 5000,
+            allowedPlacementOrigins,
+            allowInsecurePlacement = false,
+        } = config;
+        if (authenticate !== undefined && typeof authenticate !== 'function') {
+            throw new TypeError('`admission.authenticate` must be a function.');
+        }
+        if (!(Array.isArray(origins) || typeof origins === 'function' || origins === undefined)) {
+            throw new TypeError('`admission.origins` must be an array or a function.');
+        }
+        if (place !== undefined && typeof place !== 'function') {
+            throw new TypeError('`admission.place` must be a function.');
+        }
+        if (Array.isArray(origins) && origins.some(origin => typeof origin !== 'string' || !origin)) {
+            throw new TypeError('Every `admission.origins` entry must be a non-empty string.');
+        }
+        if (!Number.isInteger(timeoutMs) || timeoutMs < 1) {
+            throw new TypeError('`admission.timeoutMs` must be a positive integer.');
+        }
+        if (typeof allowInsecurePlacement !== 'boolean') {
+            throw new TypeError('`admission.allowInsecurePlacement` must be a boolean.');
+        }
+        if (allowedPlacementOrigins !== undefined && !Array.isArray(allowedPlacementOrigins)) {
+            throw new TypeError('`admission.allowedPlacementOrigins` must be an array.');
+        }
+        this.allowedPlacementOrigins = allowedPlacementOrigins?.map(origin => this.validatePlacementOrigin(origin));
+        if (this.allowedPlacementOrigins && new Set(this.allowedPlacementOrigins).size !== this.allowedPlacementOrigins.length) {
+            throw new TypeError('`admission.allowedPlacementOrigins` entries must be unique.');
+        }
+        if (!authenticate && !origins && !place) {
+            throw new TypeError('`admission` requires `authenticate`, `origins`, or `place`.');
+        }
+        this.authenticate = authenticate;
+        this.origins = origins;
+        this.place = place;
+        this.timeoutMs = timeoutMs;
+        this.allowInsecurePlacement = allowInsecurePlacement;
+    }
+
+    async authorize(request, rawSocket, route, externalSignal) {
+        const controller = new AbortController();
+        const onClose = () => controller.abort();
+        const onExternalAbort = () => controller.abort();
+        rawSocket.once('close', onClose);
+        if (externalSignal?.aborted) controller.abort();
+        else externalSignal?.addEventListener('abort', onExternalAbort, { once: true });
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        timer.unref();
+        try {
+            const evaluation = Promise.resolve().then(() => this.evaluate(request, route, controller.signal));
+            request[ADMISSION_SETTLEMENT] = evaluation.then(() => undefined, () => undefined);
+            const cancelled = new Promise((_, reject) => {
+                controller.signal.addEventListener('abort', () => reject(new Error('Admission cancelled.')), { once: true });
+            });
+            const result = await Promise.race([
+                evaluation,
+                cancelled,
+            ]);
+            if (result === false || rawSocket.destroyed || controller.signal.aborted) return false;
+            if (result.redirect) {
+                request[PLACEMENT_REDIRECT] = result.redirect;
+                return false;
+            }
+            request[ADMISSION_CONTEXT] = { principal: result.principal };
+            return true;
+        } catch {
+            return false;
+        } finally {
+            clearTimeout(timer);
+            rawSocket.off?.('close', onClose);
+            externalSignal?.removeEventListener?.('abort', onExternalAbort);
+        }
+    }
+
+    validatePlacementOrigin(origin) {
+        if (typeof origin !== 'string' || !origin) {
+            throw new TypeError('Placement origins must be non-empty strings.');
+        }
+        let parsed;
+        try {
+            parsed = new URL(origin);
+        } catch {
+            throw new TypeError('Placement origins must be valid ws or wss origins.');
+        }
+        if (!['ws:', 'wss:'].includes(parsed.protocol) || parsed.username || parsed.password || parsed.pathname !== '/' || parsed.search || parsed.hash) {
+            throw new TypeError('Placement origins must be ws or wss origins without credentials, paths, queries, or fragments.');
+        }
+        return parsed.origin;
+    }
+
+    isSafeRedirect(value) {
+        if (!value || value.length > 2048 || /[\r\n]/.test(value)) return false;
+        try {
+            const parsed = new URL(value);
+            if (!['ws:', 'wss:'].includes(parsed.protocol) || parsed.username || parsed.password || parsed.hash) return false;
+            if (parsed.protocol === 'ws:' && !this.allowInsecurePlacement) return false;
+            return !this.allowedPlacementOrigins || this.allowedPlacementOrigins.includes(parsed.origin);
+        } catch {
+            return false;
+        }
+    }
+
+    async evaluate(request, route, signal) {
+        if (!await this.acceptsOrigin(request)) return false;
+        const context = {
+            signal,
+            networkIdentity: route.resolveRemoteAddress(request),
+            route,
+        };
+        const principal = this.authenticate ? await this.authenticate(request, context) : undefined;
+        if (principal === false) return false;
+        if (!this.place) return { principal };
+        const placement = await this.place(principal, request, context);
+        if (placement === false) return false;
+        if (typeof placement === 'string') {
+            return this.isSafeRedirect(placement) ? { redirect: placement } : false;
+        }
+        return { principal };
+    }
+
+    async acceptsOrigin(request) {
+        if (!this.origins) return true;
+        const origin = request?.headers?.origin;
+        if (typeof this.origins === 'function') {
+            return Boolean(await this.origins(origin, request));
+        }
+        return typeof origin === 'string' && this.origins.includes(origin);
+    }
+}
+
+module.exports = { AdmissionPolicy, ADMISSION_CONTEXT, PLACEMENT_REDIRECT, ADMISSION_SETTLEMENT };