geonix 1.23.6 → 1.30.2

package/src/Util.js

@@ -1,6 +1,6 @@
 import { createHash, randomBytes } from "crypto";
-import { URL, fileURLToPath } from "url";
-import { readFile } from "fs/promises";
+import { URL } from "url";
+import { createRequire } from "module";
 import { join } from "path";
 import { Transform } from "node:stream";
 import { networkInterfaces } from "os";
@@ -24,7 +24,7 @@ export const sleep = delay => new Promise(resolve => setTimeout(resolve, delay))
  * 
  * @returns 
  */
-export const nextTick = () => sleep(0);
+export const yieldToEventLoop = () => new Promise(resolve => setImmediate(resolve));
 
 /**
  * Parse nats:// URL
@@ -47,12 +47,29 @@ export function parseURL(url) {
     };
 }
 
+const BASE62 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+const LOG256_LOG62 = Math.log(256) / Math.log(62); // ≈ 1.3437
+
+export function encodeBase62(buffer) {
+    if (buffer.length === 0) { return ""; }
+    const len = Math.ceil(buffer.length * LOG256_LOG62);
+    let n = BigInt("0x" + buffer.toString("hex"));
+    const chars = new Array(len);
+    for (let i = len - 1; i >= 0; i--) {
+        chars[i] = BASE62[Number(n % 62n)];
+        n /= 62n;
+    }
+    return chars.join("");
+}
+
 /**
- * Generate small random Base64 encoded ID
- * @param {number} size 
- * @returns 
+ * Generates a cryptographically random Base62-encoded ID string.
+ * Exported as `randomID` in the public API.
+ *
+ * @param {number} [size=16] - Number of random bytes to encode (more bytes → longer, more unique ID).
+ * @returns {string} URL-safe, Base62-encoded random string.
  */
-export const picoid = (size = 12) => randomBytes(size).toString("base64");
+export const picoid = (size = 16) => encodeBase62(randomBytes(size));
 
 /**
  * Get SHA256 hash of a string or a buffer
@@ -81,39 +98,24 @@ export const createServerAtPort = (port, pkg, handler) =>
     });
 
 /**
- * Create TCP or HTTP server at first free port in rage
- * @param {Object} pkg 
- * @param {Function} handler 
- * @param {number} start 
- * @param {number} poolSize 
- * @returns 
+ * Create TCP or HTTP server at an OS-assigned free port
+ * @param {Object} pkg
+ * @param {Function} handler
+ * @returns
  */
-export const createServerAtFreePort = async (pkg, handler, start = 30000, poolSize = 20000) => {
-    for (let port = start; port < start + poolSize; port++) {
-        try {
-            const result = await createServerAtPort(port, pkg, handler);
-            if (result) {
-                return result;
-            }
-        } catch {
-            // silenty ignore errors
-        }
-    }
-};
-
-/**
- * Create TCP server at random port
- * @param {Function} handler 
- * @returns 
- */
-export const createTCPServer = (handler, start = 30000, poolSize = 20000) => createServerAtFreePort(net, handler, start, poolSize);
+export const createServerAtFreePort = (pkg, handler) =>
+    new Promise((resolve, reject) => {
+        const server = pkg.createServer(handler);
+        server.on("error", reject);
+        server.listen(0, () => resolve({ server, port: server.address().port }));
+    });
 
 /**
- * Create HTTP server at random port
- * @param {Function} handler 
- * @returns 
+ * Create TCP server at an OS-assigned free port
+ * @param {Function} handler
+ * @returns
  */
-export const createHTTPServer = (handler, start = 30000, poolSize = 20000) => createServerAtFreePort(net, handler, start, poolSize);
+export const createTCPServer = (handler) => createServerAtFreePort(net, handler);
 
 /**
  * Return number of seconds passed from the start of the day (0-86399)
@@ -124,39 +126,6 @@ export const getSecondsSinceMidnight = () => {
     return Math.floor((date.getTime() - date.setHours(0, 0, 0, 0)) / 1000);
 };
 
-/**
- * Parse function body and return array of param names
- * @param {*} fn 
- * @returns string[]
- */
-export const getFunctionParams = (fn) => {
-    const code = fn.toString();
-    const endParenthesisPosition = code.indexOf(")");
-    let params;
-
-    if (endParenthesisPosition != -1) {
-        params = code.substring(code.indexOf("(") + 1, endParenthesisPosition);
-    } else {
-        params = code.substring(0, code.indexOf("=>"));
-    }
-
-    params = params
-        // cleanup spaces
-        .replaceAll(" ", "")
-        // split into array
-        .split(",");
-
-    // remove potential default values
-    for (let index = 0; index < params.length; index++) {
-        const defaultValueAssignmentPosition = params[index].indexOf("=");
-        if (defaultValueAssignmentPosition != -1) {
-            params[index] = params[index].substring(0, defaultValueAssignmentPosition - 1);
-        }
-    }
-
-    return params;
-};
-
 export const proxyHttp = (target, req, res) =>
     new Promise((resolve, reject) => {
         const remoteTarget = `${target}${req.originalUrl}`;
@@ -188,37 +157,40 @@ export const proxyHttp = (target, req, res) =>
  */
 export const OverlayObject = (object, overlay) => new Proxy(object, { get: (t, p) => overlay[p] !== undefined ? overlay[p] : t[p] });
 
-let _geonix_version = "N/A";
-try {
-    const __dirname = fileURLToPath(new URL("..", import.meta.url));
-    const local = JSON.parse(await readFile(join(__dirname, "package.json")));
-    _geonix_version = local.version;
-} catch {
-    // ignore errors
-}
-
-export const GeonixVersion = _geonix_version;
-
-export const StreamChunker = (chunkSize = 65536) => {
-    let chunker = new Transform();
+/**
+ * The version string of the currently installed Geonix package, read from `package.json` at
+ * module load time. Equals `"N/A"` when the package metadata cannot be found.
+ *
+ * @type {string}
+ */
+export const GeonixVersion = (() => {
+    try {
+        return createRequire(import.meta.url)("../package.json").version ?? "N/A";
+    } catch {
+        return "N/A";
+    }
+})();
 
-    chunker._transform = function (chunk, encoding, done) {
+/**
+ * Chunk a stream into smaller chunks
+ * 
+ * @param {*} chunkSize 
+ * @returns 
+ */
+export const StreamChunker = (chunkSize = 65536) => new Transform({
+    transform(chunk, _encoding, done) {
         let offset = 0;
         while (offset < chunk.length) {
             const sliceSize = Math.min(chunkSize, chunk.length - offset);
             this.push(chunk.slice(offset, offset + sliceSize));
             offset += sliceSize;
         }
-
         done();
-    };
-
-    chunker._flush = function (done) {
+    },
+    flush(done) {
         done();
-    };
-
-    return chunker;
-};
+    }
+});
 
 export async function getFirstItemFromAsyncIterable(asyncIterable) {
     const iterator = asyncIterable[Symbol.asyncIterator]();
@@ -235,6 +207,10 @@ export function getNetworkAddresses() {
             if (addressObject.family === "IPv4") {
                 list.push(addressObject.address);
             }
+
+            if (addressObject.family === "IPv6") {
+                list.push(`[${addressObject.address}]`);
+            }
         }
     }
 
@@ -246,15 +222,24 @@ export function isIterable(obj) {
 }
 
 /**
- * 
- * 
- * @param {Request} req 
- * @param {parseMultipartOptions} options
- * @returns ParsedMultiPart[]
+ * Parses a `multipart/form-data` request body into an array of part objects. Each part
+ * exposes parsed headers (e.g. `content-disposition`), a `name`, an optional `filename`,
+ * and a `body` {@link import('stream').Readable}.
+ *
+ * By default parts are streamed through temporary files on disk; set `options.useMemory` to
+ * `true` to buffer them in memory instead.
+ *
+ * @param {import('http').IncomingMessage} req - Incoming HTTP request with a `multipart/form-data` content-type.
+ * @param {object} [_options] - Parsing options.
+ * @param {boolean} [_options.useMemory=false] - Buffer parts in memory instead of temp files.
+ * @param {number} [_options.maxFileSize] - Maximum allowed size in bytes for a single part.
+ * @param {number} [_options.maxFiles] - Maximum number of parts allowed.
+ * @returns {Promise<Array<{ name: string|null, filename: string|null, headers: object, body: import('stream').Readable, size: number }>>}
+ * @throws {Error} If the content-type is not `multipart/form-data` or a size/count limit is exceeded.
  */
 export async function parseMultipart(req, _options) {
     if (!req.headers["content-type"]?.startsWith("multipart/form-data")) {
-        throw new Error("Invalid content type (multipart/form-data expected)");
+        throw Error("Invalid content type (multipart/form-data expected)");
     }
 
     const BUFFER_SIZE = 1024 * 1024;
@@ -272,15 +257,41 @@ export async function parseMultipart(req, _options) {
         options.useMemory = true;
     }
 
-    const boundary = Buffer.from("\r\n--" + req.headers["content-type"].split("boundary=")[1]);
+    const boundaryValue = req.headers["content-type"].match(/boundary=([^;,\s]+)/)?.[1];
+    if (!boundaryValue) {
+        throw Error("parseMultipart: missing boundary in content-type");
+    }
+    const boundary = Buffer.from("\r\n--" + boundaryValue);
 
-    await nextTick();
+    await yieldToEventLoop();
 
     let lastChunk = Buffer.from("\r\n");
     let activePart;
-    let done = false;
+
+    const cleanup = async () => {
+        for (const part of parts) {
+            if (part.bodyFile) {
+                try {
+                    part.body.destroy();
+                } catch {
+                    // ignore errors
+                }
+                try {
+                    await unlink(part.bodyFile);
+                } catch {
+                    // ignore errors
+                }
+            }
+        }
+    };
 
     const write = (chunk) => {
+        if (options.maxFileSize !== undefined) {
+            activePart.size += chunk.length;
+            if (activePart.size > options.maxFileSize) {
+                throw Error(`parseMultipart: part exceeds maxFileSize of ${options.maxFileSize} bytes`);
+            }
+        }
         if (options.useMemory) {
             activePart.body.push(chunk);
         } else {
@@ -289,75 +300,95 @@ export async function parseMultipart(req, _options) {
     };
 
     const newPart = () => {
-        // create new part
+        if (options.maxFiles !== undefined && parts.length >= options.maxFiles) {
+            throw Error(`parseMultipart: exceeded maxFiles limit of ${options.maxFiles}`);
+        }
         const bodyFile = tempFilename();
         activePart = {
             headers: {},
             bodyFile: options.useMemory ? undefined : bodyFile,
-            body: options.useMemory ? [] : createWriteStream(bodyFile, { flags: "wx" })
+            body: options.useMemory ? [] : createWriteStream(bodyFile, { flags: "wx" }),
+            size: 0
         };
         parts.push(activePart);
     };
 
-    while (stream.readable) {
-        // next next chunk
-        let chunk = stream.read(BUFFER_SIZE);
+    try {
+        while (stream.readable) {
+            // next next chunk
+            let chunk = stream.read(BUFFER_SIZE);
 
-        if (!chunk) {
-            await nextTick();
-            continue;
-        }
+            if (!chunk) {
+                await yieldToEventLoop();
+                continue;
+            }
 
-        let combined = Buffer.concat([lastChunk, chunk]);
+            let combined = Buffer.concat([lastChunk, chunk]);
+            let lookbehindSet = false;
+
+            while (combined.length >= boundary.length + 2) {
+                const boundaryIndex = combined.indexOf(boundary);
+
+                if (boundaryIndex === -1) {
+                    // Keep only the last boundary.length-1 bytes as lookbehind so a
+                    // boundary that straddles a read boundary is not split across chunks.
+                    const safeLength = combined.length - (boundary.length - 1);
+                    if (activePart && safeLength > 0) {
+                        write(combined.subarray(0, safeLength));
+                    }
+                    lastChunk = combined.subarray(safeLength);
+                    lookbehindSet = true;
+                    break;
+                }
 
-        while (combined.length >= boundary.length + 2) {
-            const boundaryIndex = combined.indexOf(boundary);
-            const isLastBoundary = combined[boundaryIndex + boundary.length] === 45 && combined[boundaryIndex + boundary.length + 1] === 45;
+                const isLastBoundary = combined[boundaryIndex + boundary.length] === 45 && combined[boundaryIndex + boundary.length + 1] === 45;
 
-            if (boundaryIndex === -1) {
-                lastChunk = combined;
-                break;
-            }
+                if (boundaryIndex > 0) {
+                    write(combined.subarray(0, boundaryIndex));
+                }
 
-            if (boundaryIndex > 0) {
-                write(combined.subarray(0, boundaryIndex));
-            }
+                if (isLastBoundary) {
+                    break;
+                }
 
-            if (isLastBoundary) {
-                combined = combined.subarray(boundaryIndex + boundary.length + 2);
-                done = true;
-                break;
-            }
+                newPart();
 
-            newPart();
+                const endOfHeaders = combined.indexOf(END_OF_HEADERS, boundaryIndex);
 
-            const endOfHeaders = combined.indexOf(END_OF_HEADERS, boundaryIndex);
+                if (endOfHeaders === -1) {
+                    throw Error("parseMultipart: malformed part — missing header terminator");
+                }
 
-            activePart.headers = combined
-                .subarray(boundaryIndex + boundary.length + 2, endOfHeaders).toString()
-                .split("\r\n")
-                .reduce((acc, val) => {
-                    const [header, value] = val.split(": ");
-                    acc[header.toLowerCase()] = value;
-                    return acc;
-                }, {});
+                activePart.headers = combined
+                    .subarray(boundaryIndex + boundary.length + 2, endOfHeaders).toString()
+                    .split("\r\n")
+                    .reduce((acc, val) => {
+                        const [header, value] = val.split(": ");
+                        acc[header.toLowerCase()] = value;
+                        return acc;
+                    }, Object.create(null));
 
-            combined = combined.subarray(endOfHeaders + END_OF_HEADERS.length);
+                combined = combined.subarray(endOfHeaders + END_OF_HEADERS.length);
 
-            lastChunk = combined;
-        }
+                lastChunk = combined;
+            }
 
-        // there's no boundary in the chunk, add it to active part
-        if (activePart && lastChunk.length > 0 && !done) {
-            write(lastChunk);
-            lastChunk = Buffer.alloc(0);
+            // Carry the unprocessed remainder into the next read so it gets
+            // prepended to the next chunk. Skip when the lookbehind was already
+            // set inside the boundaryIndex === -1 branch above.
+            if (!lookbehindSet) {
+                lastChunk = combined;
+            }
         }
+    } catch (e) {
+        await cleanup();
+        throw e;
     }
 
     for (const part of parts) {
         // extract name and filename from content-disposition header
         if (part.headers["content-disposition"]) {
-            const [, name] = part.headers["content-disposition"].match(/name="([^"]+)"/);
+            const [, name] = part.headers["content-disposition"].match(/name="([^"]+)"/) || [];
             const [, filename] = part.headers["content-disposition"].match(/filename="([^"]+)"/) || [];
             part.name = name ?? null;
             part.filename = filename ?? null;
@@ -383,24 +414,13 @@ export async function parseMultipart(req, _options) {
 }
 
 export function tempFilename() {
-    return join(tmpdir(), `${randomSafeId(12)}.gxtmp`);
-}
-
-export function randomSafeId(size = 12) {
-    const charset = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
-    let result = "";
-
-    for (let i = 0; i < size; i++) {
-        result += charset.charAt(Math.floor(Math.random() * charset.length));
-    }
-
-    return result;
+    return join(tmpdir(), `${picoid(12)}.gxtmp`);
 }
 
 export function deepMerge(target, ...source) {
     for (const src of source) {
-        for (const key in src) {
-            if (src[key] instanceof Object) {
+        for (const key of Object.keys(src)) {
+            if (src[key] instanceof Object && !Array.isArray(src[key])) {
                 if (!target[key]) {
                     target[key] = {};
                 }
@@ -423,4 +443,22 @@ export function cleanupWebsocketUrl(url) {
     } catch {
         return url;
     }
-}
+}
+
+export async function fetchWithTimeout(url, options = {}, timeout = 500) {
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), timeout);
+    try {
+        return await fetch(url, { ...options, signal: ac.signal });
+    } finally {
+        clearTimeout(timer);
+    }
+}
+
+export function withTimeout(promise, timeout) {
+    let timeoutId;
+    const timer = new Promise((_, reject) => {
+        timeoutId = setTimeout(() => reject(Error("Timeout")), timeout);
+    });
+    return Promise.race([promise, timer]).finally(() => clearTimeout(timeoutId));
+}

package/src/WebServer.js

@@ -3,13 +3,21 @@ import express, { Router } from "express";
 import expressWs from "express-ws";
 import { createServerAtFreePort, createServerAtPort, sleep } from "./Util.js";
 import * as http from "http";
-import { Service } from "./Service.js";
 import * as path from "path";
 import { logger } from "./Logger.js";
 import { activeStreams } from "./Stream.js";
 
-export const HEALTH_CHECK_ENDPOINT = "/pA4vY7fT9oG5aI8cA4yV3qW5fP9qR1vI";
-
+/**
+ * Creates an Express router that serves static files from `root`. Supports an optional URL
+ * prefix strip via `options.root` and falls back to `index.html` for unmatched paths when
+ * `options.indexOn404` is `true` (useful for single-page applications).
+ *
+ * @param {string} root - Filesystem path to the directory containing static assets.
+ * @param {object} [options] - Options forwarded to `express.static`, plus:
+ * @param {string} [options.root] - URL prefix to strip before serving.
+ * @param {boolean} [options.indexOn404] - If `true`, respond with `index.html` for all 404s.
+ * @returns {import('express').Router}
+ */
 export const ServeStatic = (root, options = {}) => {
     const router = Router();
     const absoluteRoot = path.resolve(root);
@@ -34,7 +42,6 @@ export const ServeStatic = (root, options = {}) => {
 
     if (options.indexOn404) {
         router.get("*", (req, res) => {
-            logger.info(path.join(absoluteRoot, "index.html"));
             res.sendFile(path.join(absoluteRoot, "index.html"));
         });
     }
@@ -58,14 +65,15 @@ class WebServer {
         this.#started = true;
 
         let srv;
-        if (process.env.LOCAL_PORT) {
-            srv = await createServerAtPort(process.env.LOCAL_PORT, http, this.#app);
+        const localPort = process.env.GX_LOCAL_PORT || process.env.LOCAL_PORT;
+        if (localPort) {
+            srv = await createServerAtPort(localPort, http, this.#app);
         } else {
             srv = await createServerAtFreePort(http, this.#app);
         }
 
         if (!srv) {
-            throw new Error("gx.webserver.start: unable to start");
+            throw Error("gx.webserver.start: unable to start");
         }
 
         this.#server = srv.server;
@@ -74,7 +82,7 @@ class WebServer {
         expressWs(this.#app, srv.server);
 
         // stream endpoint
-        this.#app.get("/!!_____stream/:id", (req, res) => {
+        this.#app.get("/!!_gx/stream/:id", (req, res) => {
             const id = req.params.id;
 
             if (activeStreams[id]) {
@@ -86,8 +94,8 @@ class WebServer {
             }
         });
 
-        this.#app.get(HEALTH_CHECK_ENDPOINT, (req, res) => {
-            res.send({ status: "healthy", services: Service.serviceClasses });
+        this.#app.get("/!!_gx/health", (req, res) => {
+            res.send({ status: "healthy" });
         });
 
         // middleware to handle dynamic routers

package/test/context.js

@@ -1,35 +0,0 @@
-import { Remote, Service } from "../exports.js";
-import { sleep } from "../src/Util.js";
-
-class TimeService extends Service {
-
-    #timestamp() {
-        return new Date().toISOString();
-    }
-
-    getCurrentTime() {
-        const [prefix] = this.context;
-
-        return `${prefix} ${this.#timestamp()}`;
-    }
-
-}
-
-class ApplicationService extends Service {
-
-    #timeService = Remote("TimeService", "prefix");
-
-    async onStart() {
-        while (true) {
-            const time = await this.#timeService.getCurrentTime();
-
-            console.log("TIME =", time);
-
-            await sleep(1000);
-        }
-    }
-
-}
-
-TimeService.start();
-ApplicationService.start();

package/test/delayedStart.js

@@ -1,24 +0,0 @@
-import { Gateway, Service, streamToBuffer } from "../exports.js";
-import { parseMultipart, sleep } from "../src/Util.js";
-
-class TestService extends Service {
-
-    "GET /test/"(req, res) {
-        res.send("Hello World");
-    }
-
-}
-
-class Application extends Service {
-
-    "GET /"(req, res) {
-        res.send("app");
-    }
-
-}
-
-Application.start();
-
-await sleep(3000);
-
-TestService.start();

package/test/gateway.js

@@ -1,34 +0,0 @@
-import { Gateway, Service, streamToBuffer } from "../exports.js";
-import { parseMultipart } from "../src/Util.js";
-
-// class TestService extends Service {
-
-//     "GET /"(req, res) {
-//         res.send("Hello World");
-//     }
-
-//     async "POST /upload"(req, res) {
-//         const parts = await parseMultipart(req, { useMemory: false });
-
-//         for (const part of parts) {
-//             console.log(part.body);
-//         }
-
-//         res.send("OK");
-//     }
-
-// }
-
-// TestService.start({
-//     middleware: {
-//         raw: true,
-//         json: false,
-//         cookies: false,
-//     }
-// });
-// Gateway.start({
-//     beforeRequest: (req, res) => {
-//         res.set("X-Test", "Test");
-//     }
-// });
-Gateway.start();

package/test/middleware.js

@@ -1,24 +0,0 @@
-import { Router } from "express";
-import { ServeStatic, Service } from "../exports.js";
-
-function special(req, res) {
-    console.log("THIS:", this);
-
-    res.send(`Hello ${this.value}`);
-};
-
-class ApplicationService extends Service {
-
-    value = "World!";
-
-    async onStart() {
-    }
-
-    "GET *" = [special, ServeStatic("test/static", { indexOn404: true })];
-    // "GET *" = [(req, res) => {
-    //     res.send(`Hello ${this.value}`);
-    // }];
-
-}
-
-ApplicationService.start();