geonix 1.23.8 → 1.30.2

package/LICENSE.md

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 Davor Tarandek <dtarandek@tria.hr>
+Copyright (c) 2026 Davor Tarandek <dtarandek@tria.hr>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,11 +1,355 @@
 ## Geonix
 
-This is a compact yet robust library designed to facilitate Remote Procedure Call (RPC) communication patterns among various components in a system. 
+A Node.js microservices framework built on [NATS](https://nats.io/). Write self-announcing services as plain JavaScript classes with HTTP endpoints defined as specially-named methods. A gateway component automatically discovers services and routes HTTP/WebSocket traffic to them.
 
-At its core, it employs [NATS](https://nats.io/), a high-performance messaging system, as the primary medium for both communication and service discovery. 
+## Install
 
-This library adeptly handles the intricacies of RPC interactions, ensuring seamless and efficient communication between distributed services. It is especially tailored for scenarios requiring reliable and fast message exchanges, making it ideal for microservices architectures where components need to communicate and discover each other's services effectively and efficiently.
+```sh
+npm install geonix
+```
+
+Requires a running NATS server. Default: `nats://localhost`.
+
+---
+
+## Quick Start
+
+### Service
+
+```js
+import { Service } from "geonix";
+
+class GreetingService extends Service {
+    "GET /hello"(req, res) {
+        res.json({ message: `Hello, ${req.query.name || "World"}` });
+    }
+
+    greet(name) {
+        return `Hello, ${name}`;
+    }
+}
+
+GreetingService.start();
+```
+
+### Gateway
+
+```js
+import { Gateway } from "geonix";
+
+Gateway.start();
+```
+
+That's it. The gateway discovers all running services via NATS beacons and proxies HTTP traffic to them. No configuration required for basic use.
+
+---
+
+## Architecture
+
+```
+Client (HTTP/WS)
+       │
+   [Gateway]  ── discovers services via NATS beacons
+       │
+  ┌────┴────┐
+  │ Service │ ── embedded Express HTTP server
+  │ Service │ ── announces on NATS gx2.beacon every 3.5s
+  │ Service │
+  └─────────┘
+       │
+    [NATS]  ── message bus for beacons, RPC, streaming
+```
+
+### Components
+
+| File | Role |
+|------|------|
+| `Service` | Base class for all services. Manages HTTP endpoints, NATS RPC listeners, beacons. |
+| `Gateway` | HTTP reverse proxy. Subscribes to beacons, builds a dynamic Express router. |
+| `Connection` | Singleton NATS connection wrapper. Supports multiple connections with round-robin. |
+| `Registry` | Maintains a live map of available services from beacon messages. Entries expire after 5s. |
+| `Request` | Sends RPC calls to services over NATS. Waits up to 5 minutes for service to appear. |
+| `Remote` | Proxy-based sugar: `Remote("ServiceName").methodName(args)` → RPC call. |
+| `Stream` | Wraps large payloads as streamable objects. Can stream over HTTP or NATS. |
+
+---
+
+## HTTP Endpoints
+
+Methods on a Service class are matched against:
+
+```
+[options|]VERB /path
+```
+
+| Example | Meaning |
+|---------|---------|
+| `"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 |
+
+Multiple endpoints with the same verb+path and the same semver version are automatically load-balanced (round-robin for HTTP, IP-based affinity for WebSocket).
+
+---
+
+## RPC Calls
+
+Call a method on any running service by name:
+
+```js
+import { Request } from "geonix";
+
+// Call a method
+const result = await Request("GreetingService", "greet", ["Alice"]);
+
+// Target a specific version
+const result = await Request("GreetingService@1.2.x", "greet", ["Alice"]);
+```
+
+Or use the proxy sugar:
+
+```js
+import { Remote } from "geonix";
+
+const greeting = Remote("GreetingService");
+const result = await greeting.greet("Alice");
+```
+
+RPC calls use NATS queue groups — multiple instances of the same service share load automatically.
+
+### RequestOptions
+
+Pass `RequestOptions(...)` as the first argument to override per-call options:
+
+```js
+import { Remote, RequestOptions } from "geonix";
+
+const slow = Remote("HeavyService");
+const result = await slow.compute(RequestOptions({ timeout: 60000 }), payload);
+```
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `timeout` | Max wait for service to appear in registry (ms) | 300 000 |
+| `httpTimeout` | Max wait for HTTP RPC response (ms) | 5 000 |
+
+---
+
+## Context Injection
+
+Prefix the first parameter with `$` to receive a context object containing caller info:
+
+```js
+class AuthService extends Service {
+    whoAmI($ctx) {
+        return { caller: $ctx.caller, me: $ctx.me };
+    }
+}
+```
+
+---
+
+## Method Visibility
+
+| Prefix | Beacon | RPC callable | HTTP |
+|--------|--------|--------------|------|
+| (none) | yes | yes | yes (if endpoint pattern) |
+| `$` | no | yes (internal use) | no |
+| `$$` | no | no | no |
+
+`$` methods are framework-reserved built-ins (e.g. `$getServiceInfo`). They are not advertised in beacons but can be called over NATS. `$$` methods are fully private — any remote call attempting to invoke a `$$` method is rejected with an error.
+
+---
+
+## Gateway Options
+
+```js
+Gateway.start({
+    // CORS — four modes:
+    cors: undefined,           // off (default) — no CORS headers
+    cors: "*",                 // wildcard — all origins, no credentials
+    cors: ["https://app.com"], // allowlist — credentials for listed origins only
+    cors: true,                // open — reflect any origin with credentials (for auth-header APIs)
+
+    // Lifecycle hooks
+    beforeRequest: (req, res) => {},
+    afterRequest:  (req, res) => {},
+
+    // Per-route middleware control
+    // handlers: { before: [...], after: [...] }
+});
+```
+
+---
+
+## Streaming
+
+Large payloads are automatically streamed when they exceed the NATS max payload size (~512 KB):
+
+```js
+import { Stream, getReadable, streamToBuffer, streamToString, streamToJSON } from "geonix";
+
+// Sender — return a Stream from a service method
+return Stream(largeBuffer);
+
+// Receiver — materialise the stream
+const readable = await getReadable(result);   // Node.js Readable
+const buf      = await streamToBuffer(result);
+const text     = await streamToString(result);
+const obj      = await streamToJSON(result);
+```
+
+---
+
+## Service Start Options
+
+```js
+MyService.start({
+    name: "MyService",       // override class name
+    version: "1.2.3",        // override VERSION env var
+    id: "custom-id",         // stable instance ID
+
+    middleware: {
+        json: true,          // parse JSON bodies (default: true)
+        raw: true,           // parse raw binary bodies (default: true)
+        cookies: true        // parse cookies (default: true)
+    },
+
+    fullBeacon: true,        // broadcast full service info (default: true)
+                             // set false to broadcast instance ID only (heartbeat)
+
+    handlers: {
+        before: [myAuthMiddleware],   // prepend to all HTTP handlers
+        after:  [myLoggingMiddleware] // append to all HTTP handlers
+        // Note: for WS endpoints, `before` runs as route-scoped Express middleware
+        // before the WebSocket upgrade; `after` does not apply to WS or SUB endpoints.
+    }
+});
+```
+
+---
+
+## Built-in Service Methods
+
+All services expose these internal methods (callable over NATS, not over HTTP):
+
+| Method | Description |
+|--------|-------------|
+| `$createConnection(streamId)` | Opens a TCP tunnel for HTTP-over-NATS proxying |
+| `$getEnv()` | Returns Node.js version, platform, arch, memory and CPU usage |
+| `$getServiceInfo()` | Returns service metadata: name, version, methods, addresses |
+| `$stop()` | Stops the service loop |
+
+---
+
+## Multipart form data
+
+```js
+import { parseMultipart } from "geonix";
+
+class UploadService extends Service {
+    "POST /upload"(req, res) {
+        const parts = await parseMultipart(req, {
+            useMemory: false,     // stream parts to temp files (default)
+                                  // true = keep parts in memory
+            maxFiles: 10,         // throw if more than N parts
+            maxFileSize: 10e6,    // throw if any part exceeds N bytes
+        });
+
+        for (const part of parts) {
+            console.log(part.name, part.filename, part.headers);
+            // part.body is a Node.js Readable
+        }
+
+        res.send("ok");
+    }
+}
+
+UploadService.start({ middleware: { raw: false } });
+// Disable the raw body middleware so the request stream reaches parseMultipart intact.
+```
+
+Each returned part has:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `name` | `string \| undefined` | Value of `name` in `Content-Disposition`, or `undefined` |
+| `filename` | `string \| undefined` | Value of `filename` in `Content-Disposition`, or `undefined` |
+| `headers` | `object` | Lowercased part headers |
+| `body` | `Readable` | Part body as a readable stream |
+| `size` | `number` | Bytes written so far (available during parsing) |
+
+---
+
+## Configuration
+
+| Env Variable | Default | Description |
+|---|---|---|
+| `GX_TRANSPORT` | `nats://localhost` | NATS server URL(s) |
+| `GX_PORT` | `8080` | Gateway listen port |
+| `GX_LOCAL_PORT` | random | Force service HTTP server to a specific port |
+| `GX_VERSION` | `999.999.<seconds>` | Service version |
+| `GX_TRANSPORT_DEBUG` | — | Set to `true` to enable NATS protocol debug logging |
+| `GX_LEVEL` | `info` | Log level: `debug`, `info`, `warn`, `error` |
+| `GX_STREAM_TIMEOUT` | `90000` | Max wait for a stream consumer to connect (ms) |
+| `GX_INACTIVITY_TIMEOUT` | `90000` | TCP proxy (HTTP-over-NATS) inactivity timeout (ms) |
+| `GX_SECRET` | — | Encryption key: AES-256-GCM payloads + HMAC-SHA256 subjects. Services without the same key cannot communicate. |
+| `GX_DEBUG_ENDPOINT` | — | Mount path for the debug router (e.g. `/_debug`). Disabled when unset. |
+
+> **Deprecation notice:** The legacy unprefixed names `TRANSPORT`, `PORT`, `LOCAL_PORT`, `VERSION`, and `TRANSPORT_DEBUG` are still read as fallbacks but will be removed in the next major version. Migrate to the `GX_` prefixed names.
+
+### Bus Encryption (`GX_SECRET`)
+
+When `GX_SECRET` is set, all NATS traffic is encrypted:
+
+- **Payloads** — AES-256-GCM with a random 12-byte IV. Tampered messages are rejected.
+- **Subjects** — each dot-separated segment is replaced with HMAC-SHA256(segment, key). `*` and `>` wildcards are preserved so NATS subscribe semantics are unchanged.
+
+Services sharing the same `GX_SECRET` can communicate; services with a different or missing key cannot read subjects or payloads. This effectively creates a bus partition per environment.
+
+### Debug Router (`GX_DEBUG_ENDPOINT`)
+
+When enabled, exposes diagnostic endpoints under the configured path:
+
+| Path | Returns |
+|------|---------|
+| `/services` | List of all known services |
+| `/endpoints` | All registered HTTP endpoints |
+| `/registry` | Raw registry entries |
+| `/router-registry` | Gateway's internal router state |
+| `/stats` | Request/proxy counters |
+| `/info` | Node.js version, platform, memory, CPU |
+
+---
+
+## Versioning
+
+Services resolve their version in this priority order:
+
+1. `GX_VERSION` env var (or legacy `VERSION` / `version`)
+2. `options.version` passed to `Service.start()`
+3. `this.version` on the class instance
+4. Development default: `999.999.<seconds-since-midnight>`
+
+The gateway routes requests to the highest semver version. Multiple versions of the same service can coexist. RPC calls can target a specific version range: `Request("MyService@1.2.x", "method", [])`.
+
+---
+
+## Dependencies
+
+| Package | Purpose |
+|---------|---------|
+| `nats` | NATS client |
+| `express` | HTTP server |
+| `express-ws` | WebSocket support for Express |
+| `cookie-parser` | Cookie parsing middleware |
+| `semver` | Semantic versioning comparisons |
+| `ws` | WebSocket client (for gateway WS proxy) |
+
+---
 
 ## License
 
-  [MIT](LICENSE)
+[MIT](LICENSE)

package/exports.js

@@ -11,6 +11,4 @@ export { Request, Subscribe, Publish } from "./src/Request.js";
 export { RequestOptions } from "./src/RequestOptions.js";
 export { picoid as randomID } from "./src/Util.js";
 
-export { stats as StreamStats } from "./src/Stream.js";
-
 export { parseMultipart } from "./src/Util.js";