geonix 1.23.8 → 1.30.2

package/PROJECT.md

@@ -1,164 +0,0 @@
-# Geonix
-
-## What It Is
-
-Geonix is a Node.js microservices framework built on top of [NATS](https://nats.io/). It allows you to write self-announcing services as plain JavaScript classes, with HTTP endpoints defined as specially-named class methods. A gateway component dynamically discovers services and routes HTTP/WebSocket traffic to them.
-
-Published on npm as `geonix`, version 1.23.6. MIT licensed. Author: Davor Tarandek, Tria d.o.o.
-
----
-
-## Core Concept
-
-You write a service like this:
-
-```js
-import { Service } from "geonix";
-
-class MyService extends Service {
-    "GET /hello"(req, res) {
-        res.send("Hello World");
-    }
-    someRpcMethod(input) {
-        return input.toUpperCase();
-    }
-}
-
-MyService.start();
-```
-
-That's it. The service:
-- Starts an embedded Express HTTP server on a random port
-- Announces itself on NATS every second (a "beacon")
-- Accepts remote procedure calls over NATS
-- Can be discovered and called by the Gateway or other services
-
----
-
-## Architecture
-
-```
-Client (HTTP/WS)
-       │
-   [Gateway]  ── discovers services via NATS beacons
-       │
-  ┌────┴────┐
-  │  Service │ ── embedded Express HTTP server
-  │  Service │ ── announces on NATS gx2.beacon every 1s
-  │  Service │
-  └─────────┘
-       │
-    [NATS]  ── message bus for beacons, RPC, streaming
-```
-
-### Components
-
-| File | Role |
-|------|------|
-| `src/Service.js` | Base class for all services. Manages HTTP endpoints, NATS RPC listeners, beacons. |
-| `src/Gateway.js` | HTTP reverse proxy. Subscribes to beacons, builds a dynamic Express router. |
-| `src/Connection.js` | Singleton NATS connection wrapper. Supports multiple connections with round-robin. |
-| `src/Registry.js` | Maintains a live map of available services from beacon messages. Entries expire after 5s. |
-| `src/Request.js` | Sends RPC calls to services over NATS. Waits up to 5 minutes for service to appear. |
-| `src/Remote.js` | Proxy-based sugar: `Remote("ServiceName").methodName(args)` → RPC call. |
-| `src/Stream.js` | Wraps large payloads as streamable objects. Can stream over HTTP or NATS. |
-| `src/WebServer.js` | Shared internal Express instance for all services in the same process. |
-| `src/Util.js` | Utilities: multipart parser, HTTP proxy, TCP server creation, ID generation, deep merge. |
-| `src/Codec.js` | NATS JSON codec wrapper. |
-| `src/Logger.js` | Simple timestamped console logger. |
-
----
-
-## Key Mechanisms
-
-### Service Discovery
-- Services publish a beacon on `gx2.beacon` every 1 second
-- The `Registry` class subscribes to beacons and tracks all live services
-- Entries expire after 5 seconds without a beacon
-- Each service has: instance ID, name, version, method list, network addresses
-
-### Routing (Gateway)
-- On startup, the Gateway subscribes to all beacons
-- Every second it checks for newly added or removed services
-- When services change, it rebuilds the Express router with updated routes
-- If the backend service is directly reachable via HTTP (same network), it proxies directly
-- If not, it tunnels HTTP over NATS using a TCP-over-NATS bridge
-
-### RPC Calls
-- `Request("ServiceName", "methodName", [args])` resolves the service identifier from the registry
-- It publishes to `gx2.service.<sha256(identifier)>` with a reply-to subject
-- The service picks it up from its queue subscription and responds
-- Load balancing is built-in: multiple instances of `ServiceName@version` use NATS queue groups
-
-### Streaming
-- When a payload exceeds NATS max payload size (~512KB), it's automatically converted to a `Stream` object
-- The `Stream` object contains `{ $: "stream", id, a: [addresses] }`
-- Consumers use `getReadable()` to retrieve the stream via HTTP or NATS
-
-### Versioning
-- Services can specify a version via `process.env.VERSION`, options, or `this.version`
-- The gateway does semver-aware routing and always routes to the highest version
-- RPC calls can target a specific version: `Request("MyService@1.2.x", "method", [])`
-
----
-
-## Endpoint Declaration Syntax
-
-Methods on a Service class are matched against this pattern:
-```
-[options|]VERB /path
-```
-
-Examples:
-- `"GET /api/users"` — HTTP GET endpoint
-- `"POST /upload"` — HTTP POST endpoint
-- `"WS /chat"` — WebSocket endpoint
-- `"SUB my.nats.subject"` — NATS subscription handler
-- `"order=10|GET /api"` — HTTP GET with routing priority 10
-
----
-
-## Transport
-
-- **NATS** (required): service discovery, RPC, streaming fallback
-- **HTTP**: direct service-to-service and gateway-to-service communication
-- **TCP-over-NATS**: tunnel for HTTP traffic when direct addressing is not possible
-
----
-
-## Built-in Service Methods
-
-All services expose these internal methods (callable over NATS, not over HTTP):
-
-| Method | Returns |
-|--------|---------|
-| `$createConnection(streamId)` | Opens a TCP tunnel for proxying HTTP |
-| `$getEnv()` | System info, Node.js version, `process.env`, memory/CPU usage |
-| `$getServiceInfo()` | Service metadata (name, version, methods, addresses) |
-
----
-
-## Configuration
-
-| Env Variable | Default | Description |
-|---|---|---|
-| `TRANSPORT` | `nats://localhost` | NATS server URL |
-| `PORT` | `8080` | Gateway listen port |
-| `LOCAL_PORT` | random | Force service HTTP server to a specific port |
-| `VERSION` | auto-generated | Service version |
-| `NODE_ENV` | — | Set to `production` to disable debug endpoint |
-| `TRANSPORT_DEBUG` | `false` | Enable NATS debug logging |
-
----
-
-## Dependencies
-
-| Package | Purpose |
-|---------|---------|
-| `express` | HTTP server |
-| `express-ws` | WebSocket support for Express |
-| `express-async-errors` | Async error handling for Express |
-| `nats` | NATS client |
-| `cookie-parser` | Cookie parsing middleware |
-| `semver` | Semantic versioning comparisons |
-| `ws` | WebSocket client (for gateway WS proxy) |

package/REVIEW.md

@@ -1,372 +0,0 @@
-# Code Review: Geonix
-
----
-
-## Honest Opinion on the Idea
-
-The core idea is clever and genuinely useful: service discovery + RPC + HTTP routing in one framework, with zero external service registry. Classes become services, methods become endpoints, and everything discovers each other automatically via NATS beacons. For small teams deploying Node.js microservices on the same NATS network, this could eliminate a lot of boilerplate.
-
-The design does lean heavily on some opinionated tradeoffs:
-
-- **The method-name-as-endpoint convention** (`"GET /path"`) is novel but weird. It works in JS, but it's surprising to most developers, not statically typed, and can silently misbehave when method names overlap or are substrings of each other (see bugs below). It also means your service's public interface is entangled with its internal class structure.
-- **Using NATS as both the transport and the discovery layer** is clever but means you're fully coupled to NATS. If NATS goes down, everything stops. There's no degraded-mode operation.
-- **The gateway rebuilding its routing table from live beacons** is interesting but creates a window during which newly deployed services are unreachable, and destroyed services may still receive traffic.
-- **Trust model is zero**: any process on the NATS bus can call any method on any service, including methods that expose `process.env`. This is the biggest design-level concern.
-
-Overall: a reasonable idea for a trusted internal microservices environment, but it needs significant hardening before it's safe for anything facing external networks or for multi-tenant deployments.
-
----
-
-## Security Issues
-
-### S1 — `$getEnv()` exposes all environment variables to any NATS caller (CRITICAL)
-
-**File:** `src/Service.js:312-324`
-
-```js
-$getEnv() {
-    return {
-        ...
-        env: process.env,   // all secrets: API keys, DB passwords, tokens
-        ...
-    };
-}
-```
-
-This method is accessible to any service on the NATS bus. It is **not** gated by authentication. Methods prefixed with `$` are excluded from HTTP routes (`m: fields.filter(methodName => !methodName.startsWith("$"))`), but they can be called directly over NATS via:
-
-```js
-await Request("MyService", "$getEnv");
-```
-
-Any compromised service, or any process that can connect to NATS, can harvest credentials from all other services. There is no way to opt out of this method — it is always present on every service.
-
-The same information is available at the debug endpoint's `/info` route (`Gateway.js:260-272`).
-
----
-
-### S2 — CORS configuration allows credential theft from any origin (HIGH)
-
-**File:** `src/Gateway.js:71-85`
-
-```js
-res.set("Access-Control-Allow-Credentials", "true");
-res.set("Access-Control-Allow-Origin", origin || "*");
-res.set("Access-Control-Allow-Methods", requestMethod || allMethods);
-res.set("Access-Control-Allow-Headers", requestHeaders || allHeaders);
-```
-
-This reflects the request's `Origin` back as the allowed origin, which is effectively "allow all origins." Combined with `Allow-Credentials: true`, this means **any website on the internet can make authenticated cross-origin requests** (including requests with cookies or auth headers) to the gateway.
-
-This is actually more dangerous than `Access-Control-Allow-Origin: *` because `*` does not allow credentials, but the current implementation does.
-
----
-
-### S3 — Debug endpoint exposes `process.env` and internal state in non-production (HIGH)
-
-**File:** `src/Gateway.js:13`, `src/Gateway.js:260-272`
-
-```js
-const DEBUG_ENDPOINT = "/lZ6jD2eC3iP0zB3jJ1yJ9pM8gG3yI3vS";
-```
-
-The debug endpoint is "protected" by a random-looking path, but that path is published in source code (visible on npm and any git host). The `/info` route sends the full `process.env`. The endpoint is disabled in `NODE_ENV=production`, but any non-production deployment with an exposed gateway leaks all secrets.
-
-Additionally, the `/router-registry` route dumps the entire internal registry including backend addresses.
-
----
-
-### S4 — No authentication or authorization on NATS RPC layer (HIGH)
-
-**File:** `src/Service.js` (entire file), `src/Request.js`
-
-The NATS bus is fully trusted. Any process that can publish to `gx2.service.<hash>` can invoke any method on any service. This includes:
-- Internal business logic methods
-- `$createConnection` — can open TCP tunnels into the service
-- `$getEnv` — leaks secrets
-- `$getServiceInfo` — leaks internal service metadata
-
-If NATS is ever exposed to an untrusted network (misconfigured firewall, a compromised service, etc.), the entire cluster is fully compromised. There is no way to add per-method authorization at the framework level.
-
----
-
-### S5 — `randomSafeId` uses `Math.random()` (MEDIUM)
-
-**File:** `src/Util.js:389-398`
-
-```js
-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;
-}
-```
-
-This is used in `tempFilename()` to generate temporary file paths. `Math.random()` is not cryptographically secure and is predictable. An attacker who can observe some outputs can predict future filenames and pre-create symlinks to redirect where uploaded files are written. `randomBytes` is already imported and used by `picoid()` — `randomSafeId` should use it too.
-
----
-
-### S6 — Multipart parser ignores declared `maxFileSize` and `maxFiles` limits (MEDIUM)
-
-**File:** `src/Util.js:255-383`, `src/Types.js:3-6`
-
-`parseMultipartOptions` is typed to accept `maxFileSize` and `maxFiles`, but neither is checked anywhere in `parseMultipart()`. A caller relying on these options to enforce upload limits gets no protection. With the default body limit of 1GB (`express.raw({ limit: "1024mb" })`), a single request could consume all disk space.
-
----
-
-## Performance Issues
-
-### P1 — RPC resolution uses a CPU-burning polling loop (HIGH)
-
-**File:** `src/Request.js:77-84`
-
-```js
-const delay = 5;
-let retries = Math.floor(registryTimeout / delay);  // 60,000 iterations for 5-minute timeout
-while (identifier == null && retries-- > 0) {
-    identifier = registry.getIdentifier(name, version, id);
-    if (!identifier) {
-        await sleep(delay);
-    }
-}
-```
-
-For every call to a service that hasn't been discovered yet, this executes up to 60,000 iterations, each calling `registry.getIdentifier()` (which iterates all registry entries) and sleeping 5ms. With a 5-minute default timeout, a failed RPC call keeps a tight polling loop running for 5 minutes.
-
-If many concurrent requests target a missing service, this creates severe CPU pressure. The registry already emits events via `EventEmitter` — waiting on the `"added"` event would be far more efficient.
-
----
-
-### P2 — Beacon frequency vs. expiry creates unnecessary NATS traffic (MEDIUM)
-
-**File:** `src/Service.js:121-130`, `src/Registry.js:8`
-
-```js
-const REGISTRY_ENTRY_TIMEOUT = 5000;   // entries expire after 5s
-// but beacons are sent every 1s:
-await sleep(1000);
-```
-
-Each service sends a beacon every 1 second, but entries only expire after 5 seconds. With N services all sending beacons every second, this is N messages/second on `gx2.beacon`. With `fullBeacon: false` (short beacon), there's an additional `$getServiceInfo` RPC call per short beacon per receiving node. At scale this creates significant traffic with no value beyond faster failure detection. The interval should be configurable, or should use NATS's built-in heartbeat facilities.
-
----
-
-### P3 — Large payload streams are double-encoded for Stream fallback (MEDIUM)
-
-**File:** `src/Connection.js:116-120`
-
-```js
-if (payload.length > this.getMaxPayloadSize()) {
-    payload = encode(Stream(JSON.stringify(json)));
-}
-```
-
-When a payload exceeds the max size, it is:
-1. JSON-encoded by `JSON.stringify`
-2. Wrapped in a `Stream` object
-3. JSON-encoded again by `encode()`
-
-The inner `JSON.stringify` + outer `encode()` (which is also JSON) means the data is encoded twice. The receiver must decode twice, which is handled correctly, but it's wasteful for large payloads where performance matters most.
-
----
-
-### P4 — The endpoint ordering sort in `Service.#start` is O(n²) per endpoint (LOW)
-
-**File:** `src/Service.js:68-77`
-
-```js
-fields.sort((a, b, ia = -1, ib = -1) => {
-    for (let line = 0; line < serviceSource.length; line++) {
-        ia = serviceSource[line].includes(a) ? line : ia;
-    }
-    for (let line = 0; line < serviceSource.length; line++) {
-        ib = serviceSource[line].includes(b) ? line : ib;
-    }
-    return ia - ib;
-});
-```
-
-The sort comparator does two full O(lines) scans of the source code for every comparison. For a service with N endpoints and M source lines, this is O(N log N × M) total. This only runs once at startup, but for large services it could cause noticeable startup delay. It also has a correctness issue (see B3).
-
----
-
-## Bugs
-
-### B1 — WebSocket load balancing is broken: backend is fixed at router build time (HIGH)
-
-**File:** `src/Gateway.js:394-406`
-
-```js
-// Outside the handler — backend selected ONCE at build time:
-let backend = endpoint.backend[endpoint.requests++ % endpoint.backend.length];
-
-if (verb === "ws") {
-    router.ws(uri, (ws, req) => {
-        let target = cleanupWebsocketUrl(`ws://${backend}${req.originalUrl}`);
-        this.#proxyWebsocketOverNats(target, ws, req);  // always uses the same backend
-    });
-```
-
-For HTTP routes, there is a runtime re-evaluation at line 410 (`backend = endpoint.backend[endpoint.requests++ % endpoint.backend.length]`). But for WebSocket routes, the `backend` variable is captured by closure at router build time and never updated. All WebSocket connections after the first router build will target the same backend instance, even when multiple instances exist.
-
----
-
-### B2 — `Gateway.#start()` accepts connections before middleware is registered (MEDIUM)
-
-**File:** `src/Gateway.js:59-127`
-
-```js
-async #start(port = 8080) {
-    await connection.waitUntilReady();
-
-    this.#port = process.env.PORT || port;
-    this.#api.listen(this.#port);   // server starts accepting connections here
-
-    logger.debug(...);
-
-    // middleware added AFTER listen:
-    this.#api.use(requestLogger);
-    this.#api.use(/* CORS */);
-    this.#api.use(DEBUG_ENDPOINT, this.#debugRouter());
-    ...
-```
-
-Express registers middleware in order, and while this works for middleware definitions (Express adds them to a list for subsequent requests), there is a race condition: requests arriving between `listen()` and the `use()` calls will be processed with no CORS headers, no request logging, and potentially no debug route protection. The correct pattern is to register all middleware before calling `listen()`.
-
----
-
-### B3 — Endpoint ordering sort is broken for methods whose names are substrings of each other (MEDIUM)
-
-**File:** `src/Service.js:68-77`
-
-```js
-ia = serviceSource[line].includes(a) ? line : ia;
-```
-
-This uses `String.includes()` instead of an exact match. If you have methods `"GET /user"` and `"GET /users"`, any line containing `"GET /users"` will also match `"GET /user"` because `"GET /user"` is a substring of `"GET /users"`. This can assign the wrong line number for endpoint ordering, causing routes to be registered in the wrong order — which matters for Express routing (more specific routes should come first).
-
----
-
-### B4 — WebSocket proxy does not close the inbound socket on backend connection failure (MEDIUM)
-
-**File:** `src/Gateway.js:310-328`
-
-```js
-#proxyWebsocketOverNats(target, inbound, req) {
-    try {
-        const backend = new WebSocket(target, { headers: { ...req.headers } });
-
-        backend.on("open", () => {
-            // setup relay...
-        });
-    } catch (e) {
-        logger.error(e);  // error is logged, but inbound socket is never closed
-    }
-}
-```
-
-If the `new WebSocket(target)` constructor throws synchronously, or if the `"open"` event never fires because the backend is unreachable, the `inbound` WebSocket is never closed. The client will hang indefinitely with an open connection that receives no data and never closes.
-
----
-
-### B5 — `deepMerge` mutates the shared `defaultServiceOptions` object (MEDIUM)
-
-**File:** `src/Service.js:53-57`, `src/Util.js:400-416`
-
-```js
-#options = defaultServiceOptions;  // shares reference, does not copy
-
-async #start(options = {}) {
-    this.#options = deepMerge(this.#options, options);  // mutates defaultServiceOptions in place
-```
-
-`deepMerge` modifies its first argument in place and returns it. Because `this.#options` is initialized as a reference to the module-level `defaultServiceOptions` constant, the first `Service.start()` call with a non-default `options` argument will mutate the shared default. Subsequent services started in the same process will start with the already-mutated defaults rather than the intended defaults.
-
-Example: if `ServiceA.start({ middleware: { json: false } })` runs first, then `ServiceB.start()` will also have `middleware.json === false`.
-
----
-
-### B6 — `Connection.monitorStatus()` advances the round-robin and only monitors one connection (LOW)
-
-**File:** `src/Connection.js:68-72`
-
-```js
-async monitorStatus() {
-    for await (const event of this.#getConnection().status()) {
-```
-
-`#getConnection()` increments `#connectionRoundRobin` as a side effect. When `monitorStatus()` is called right after `start()` (line 64), it permanently moves the round-robin index forward by one and monitors only one of the available connections. For `connections > 1`, the other connections' disconnections/reconnections are silently unmonitored.
-
----
-
-### B7 — `createHTTPServer` uses `net` (TCP) instead of `http` (LOW)
-
-**File:** `src/Util.js:116`
-
-```js
-export const createHTTPServer = (handler, start = 30000, poolSize = 20000) =>
-    createServerAtFreePort(net, handler, start, poolSize);
-//                         ^^^  should be `http`, not `net`
-```
-
-`createHTTPServer` is named to suggest it creates an HTTP server but calls `createServerAtFreePort` with the `net` module (raw TCP), making it identical to `createTCPServer`. The function is not used anywhere in the codebase currently, but any future caller expecting an HTTP server will get a raw TCP server.
-
----
-
-### B8 — No timeout or cleanup for orphaned streams (LOW)
-
-**File:** `src/Stream.js:41-56`, `src/Service.js:269-310`
-
-In `Stream()`, if the NATS control message on `gx2.stream.<id>.a` never arrives (e.g., the receiver crashed before consuming the stream), the entry persists in `activeStreams` indefinitely, leaking memory and potentially holding open file handles.
-
-Similarly, in `$createConnection`, if the control message on `gx2.stream.<id>.c` never arrives (e.g., the gateway crashed), the TCP connection and both NATS subscriptions stay open indefinitely. There is no timeout to force cleanup of orphaned connections.
-
----
-
-## Design Observations
-
-### D1 — No way to mark methods as non-RPC-callable
-
-All public instance methods (not starting with `$`, not `constructor` or `onStart`) are advertised via beacon and callable over NATS. There is no annotation or convention to make a method private/internal. This means any helper method you add to a service is automatically exposed as an RPC endpoint.
-
-### D2 — Service beacon advertises its HTTP port to all services
-
-Every beacon includes `a: getNetworkAddresses().map(address => \`\${address}:\${webserver.getPort()}\`)`. This means every service on the network learns the internal ports of every other service. In environments where services should not be directly reachable from each other (e.g., different network segments), the gateway acts as the intended chokepoint, but services inadvertently publish their direct addresses.
-
-### D3 — Endpoint options parsed from the method name with `querystring.parse`
-
-**File:** `src/Gateway.js:351-353`
-
-```js
-...(endpoint.options ? querystring.parse(endpoint.options) : {})
-```
-
-The `querystring` module is deprecated (Node.js recommends `URLSearchParams`). More importantly, the `order` option is parsed as a string and later cast with `parseInt()` — type errors are silent. Any typo in endpoint options silently gets an `order` of `NaN` which sorts unpredictably.
-
----
-
-## Summary Table
-
-| ID | Severity | Category | Issue |
-|----|----------|----------|-------|
-| S1 | Critical | Security | `$getEnv()` exposes all secrets to any NATS caller |
-| S2 | High | Security | CORS reflects origin + allows credentials — any site can make authenticated requests |
-| S3 | High | Security | Debug endpoint leaks `process.env` (path is in public source) |
-| S4 | High | Security | Zero authentication on NATS RPC layer |
-| S5 | Medium | Security | `randomSafeId` uses `Math.random()` for temp file names |
-| S6 | Medium | Security | `maxFileSize`/`maxFiles` multipart options are silently ignored |
-| P1 | High | Performance | 60,000-iteration polling loop for unresolved RPC service lookup |
-| P2 | Medium | Performance | Beacon rate (1s) vs. expiry (5s) generates excessive NATS traffic at scale |
-| P3 | Medium | Performance | Large payloads double-encoded on stream fallback path |
-| P4 | Low | Performance | O(n² × lines) endpoint ordering sort at startup |
-| B1 | High | Bug | WebSocket round-robin broken — backend fixed at router build time |
-| B2 | Medium | Bug | Gateway listens before middleware is registered (race at startup) |
-| B3 | Medium | Bug | Endpoint sort uses substring match — breaks ordering for similar-named routes |
-| B4 | Medium | Bug | Inbound WebSocket never closed on backend connection failure |
-| B5 | Medium | Bug | `deepMerge` mutates shared `defaultServiceOptions` across service instances |
-| B6 | Low | Bug | `monitorStatus()` advances round-robin and only monitors one connection |
-| B7 | Low | Bug | `createHTTPServer` creates a TCP server, not an HTTP server |
-| B8 | Low | Bug | No timeout for orphaned stream/connection cleanup |