kuberpc-node 2.0.0

package/README.md

@@ -0,0 +1,185 @@
+# kubeRPC - Node.js SDK
+
+Node.js SDK for [kubeRPC](https://github.com/darksuei/kubeRPC). Register callable methods on your service and invoke methods on other services over a persistent TCP connection with MessagePack framing.
+
+---
+
+## Installation
+
+```bash
+npm install kuberpc-node
+```
+
+---
+
+## Kubernetes usage (zero-config)
+
+When kubeRPC core is deployed with the admission webhook enabled, annotate your pod and all required environment variables are injected automatically at pod creation time:
+
+```yaml
+annotations:
+  kuberpc.suei.io/enabled: "true"       # inject KUBERPC_CORE_URL
+  kuberpc.suei.io/service: "my-service" # inject KUBERPC_SERVICE_NAME, KUBERPC_HOST, KUBERPC_PORT
+  kuberpc.suei.io/port: "7749"          # optional - defaults to 7749
+```
+
+With those env vars present, the constructor takes no arguments:
+
+```js
+import { KubeRPC } from "kuberpc-node";
+
+const rpc = new KubeRPC();
+```
+
+> The Kubernetes Service fronting your pod **must be named to match** `kuberpc.suei.io/service`. That name is what kubeRPC core stores as the reachable host for your service.
+
+---
+
+## Non-Kubernetes usage
+
+Pass configuration explicitly. These values override any environment variables.
+
+```js
+import { KubeRPC } from "kuberpc-node";
+
+const rpc = new KubeRPC({
+  coreURL: "http://localhost:8080", // kubeRPC core endpoint
+  serviceName: "my-service",        // unique name for this service
+  host: "localhost",                // address other services use to reach this one
+  port: 7749,                       // TCP port this service listens on for inbound RPC calls
+});
+```
+
+---
+
+## Register a method
+
+Expose a callable method. The TCP listener starts on the first `register()` call, and the service is registered with kubeRPC core.
+
+```js
+await rpc.register("getUser", async ({ id }) => {
+  return db.users.findById(id);
+});
+```
+
+---
+
+## Call a method
+
+Get a proxy for a target service, then call a method on it. The first call resolves the endpoint from kubeRPC core and opens a persistent TCP connection. Subsequent calls reuse the connection.
+
+```js
+const userService = rpc.service("user-service");
+
+const user = await userService.call("getUser", { id: "123" });
+```
+
+---
+
+## Full example
+
+**service-a** - registers a method:
+
+```js
+import { KubeRPC } from "kuberpc-node";
+
+// In Kubernetes: no args needed, env vars are injected by the webhook.
+// Outside Kubernetes: pass config explicitly.
+const rpc = new KubeRPC({
+  coreURL: "http://localhost:8080",
+  serviceName: "service-a",
+  host: "localhost",
+  port: 7749,
+});
+
+await rpc.register("greet", async ({ name }) => {
+  return `Hello, ${name}!`;
+});
+```
+
+**service-b** - calls the method:
+
+```js
+import { KubeRPC } from "kuberpc-node";
+
+const rpc = new KubeRPC({
+  coreURL: "http://localhost:8080",
+  serviceName: "service-b",
+  host: "localhost",
+  port: 7750,
+});
+
+const serviceA = rpc.service("service-a");
+const message = await serviceA.call("greet", { name: "world" });
+
+console.log(message); // Hello, world!
+
+rpc.close();
+```
+
+---
+
+## API reference
+
+### `new KubeRPC(config?)`
+
+All fields are optional. Environment variables are the fallback when a field is omitted.
+
+| Field | Env var | Default | Description |
+|---|---|---|---|
+| `coreURL` | `KUBERPC_CORE_URL` | - | kubeRPC core base URL. **Required** (via config or env). |
+| `serviceName` | `KUBERPC_SERVICE_NAME` | `""` | Name this service registers under. Required when calling `register()`. |
+| `host` | `KUBERPC_HOST` | `"localhost"` | Address other services use to reach this one. |
+| `port` | `KUBERPC_PORT` | `7749` | TCP port for inbound RPC calls. |
+
+---
+
+### `rpc.register(name, handler)`
+
+Registers a method and starts the TCP listener if not already running. Returns a `Promise<void>` that resolves once the method is registered with kubeRPC core.
+
+```ts
+await rpc.register("methodName", async (args) => {
+  return result;
+});
+```
+
+---
+
+### `rpc.service(name): ServiceProxy`
+
+Returns a lightweight proxy for a named service. Does not make any network calls.
+
+```ts
+const svc = rpc.service("other-service");
+```
+
+---
+
+### `ServiceProxy.call(method, args?): Promise<any>`
+
+Invokes a method on the target service. Resolves the endpoint from kubeRPC core on the first call (cached for subsequent calls), then sends the request over a persistent TCP connection.
+
+```ts
+const result = await svc.call("methodName", { key: "value" });
+```
+
+---
+
+### `rpc.close()`
+
+Closes all outbound TCP connections, destroys the inbound TCP listener, and clears internal state. Call this on graceful shutdown.
+
+```ts
+rpc.close();
+```
+
+---
+
+## Transport behaviour
+
+- **Wire format**: length-prefixed MessagePack frames. Each frame is a 4-byte big-endian length followed by a MessagePack-encoded positional array.
+- **Connection pooling**: one persistent TCP socket per target service, opened on first call and reused for all subsequent calls.
+- **Endpoint cache**: service host/port is resolved from kubeRPC core once and cached. The cache is invalidated if the connection drops.
+- **Concurrency**: concurrent calls to the same service are serialised through an internal queue. If you need parallel throughput across services, each target service gets its own independent queue and connection.
+- **Reconnect**: if the socket drops, the next call attempts a single reconnect. There are no automatic retries beyond that - error handling is left to the caller.

package/dist/errors.d.ts

@@ -0,0 +1,7 @@
+export declare class KubeRpcError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+    static methodNotFound(method: string, service: string): KubeRpcError;
+    static connectionFailed(host: string, port: number): KubeRpcError;
+    static coreUnreachable(url: string): KubeRpcError;
+}

package/dist/errors.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KubeRpcError = void 0;
+class KubeRpcError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "KubeRpcError";
+        Object.setPrototypeOf(this, KubeRpcError.prototype);
+    }
+    static methodNotFound(method, service) {
+        return new KubeRpcError("METHOD_NOT_FOUND", `Method "${method}" not found in service "${service}"`);
+    }
+    static connectionFailed(host, port) {
+        return new KubeRpcError("CONNECTION_FAILED", `Failed to connect to ${host}:${port}`);
+    }
+    static coreUnreachable(url) {
+        return new KubeRpcError("CORE_UNREACHABLE", `kubeRPC core unreachable at ${url}`);
+    }
+}
+exports.KubeRpcError = KubeRpcError;

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { KubeRPC, ServiceProxy } from "./kuberpc";
+export { KubeRpcError } from "./errors";
+export type { KubeRPCConfig, Handler } from "./@types";

package/dist/index.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KubeRpcError = exports.ServiceProxy = exports.KubeRPC = void 0;
+var kuberpc_1 = require("./kuberpc");
+Object.defineProperty(exports, "KubeRPC", { enumerable: true, get: function () { return kuberpc_1.KubeRPC; } });
+Object.defineProperty(exports, "ServiceProxy", { enumerable: true, get: function () { return kuberpc_1.ServiceProxy; } });
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "KubeRpcError", { enumerable: true, get: function () { return errors_1.KubeRpcError; } });

package/dist/kuberpc.d.ts

@@ -0,0 +1,29 @@
+import { Handler, KubeRPCConfig } from "./@types";
+export declare class ServiceProxy {
+    private readonly name;
+    private readonly rpc;
+    constructor(name: string, rpc: KubeRPC);
+    call(method: string, args?: Record<string, any>): Promise<any>;
+}
+export declare class KubeRPC {
+    private http;
+    private config;
+    private handlers;
+    private server;
+    private pool;
+    private endpointCache;
+    private locks;
+    constructor(config?: KubeRPCConfig);
+    service(name: string): ServiceProxy;
+    register(name: string, handler: Handler): Promise<void>;
+    call(service: string, method: string, args?: Record<string, any>): Promise<any>;
+    close(): void;
+    private startServer;
+    private drainInbound;
+    private handleInboundFrame;
+    private writeFrame;
+    private resolve;
+    private getConnection;
+    private enqueue;
+    private sendFrame;
+}

package/dist/kuberpc.js

@@ -0,0 +1,231 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KubeRPC = exports.ServiceProxy = void 0;
+const net_1 = __importDefault(require("net"));
+const axios_1 = __importDefault(require("axios"));
+const msgpackr_1 = require("msgpackr");
+const errors_1 = require("./errors");
+// Wire format (positional arrays - avoids encoding key strings on every call):
+//   request  → [method: string, args: object]
+//   response → [null, result]  on success
+//   response → [errorMsg: string]  on error
+const DEFAULT_RPC_PORT = 7749;
+class ServiceProxy {
+    constructor(name, rpc) {
+        this.name = name;
+        this.rpc = rpc;
+    }
+    call(method, args = {}) {
+        return this.rpc.call(this.name, method, args);
+    }
+}
+exports.ServiceProxy = ServiceProxy;
+class KubeRPC {
+    constructor(config = {}) {
+        var _a, _b, _c, _d, _e, _f, _g, _h;
+        this.handlers = new Map();
+        this.server = null;
+        this.pool = new Map();
+        this.endpointCache = new Map();
+        this.locks = new Map();
+        const coreURL = (_b = (_a = config.coreURL) !== null && _a !== void 0 ? _a : process.env.KUBERPC_CORE_URL) !== null && _b !== void 0 ? _b : "";
+        const serviceName = (_d = (_c = config.serviceName) !== null && _c !== void 0 ? _c : process.env.KUBERPC_SERVICE_NAME) !== null && _d !== void 0 ? _d : "";
+        const port = (_e = config.port) !== null && _e !== void 0 ? _e : Number((_f = process.env.KUBERPC_PORT) !== null && _f !== void 0 ? _f : DEFAULT_RPC_PORT);
+        const host = (_h = (_g = config.host) !== null && _g !== void 0 ? _g : process.env.KUBERPC_HOST) !== null && _h !== void 0 ? _h : "localhost";
+        if (!coreURL) {
+            throw new Error("kubeRPC: coreURL is required. Pass it via config or set KUBERPC_CORE_URL.");
+        }
+        this.config = { coreURL, serviceName, port, host };
+        this.http = axios_1.default.create({ baseURL: coreURL });
+    }
+    service(name) {
+        return new ServiceProxy(name, this);
+    }
+    register(name, handler) {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.handlers.set(name, handler);
+            if (!this.server) {
+                yield this.startServer();
+            }
+            yield this.http.post("/register-methods", {
+                service_name: this.config.serviceName,
+                methods: [{ name, params: [], description: "" }],
+            });
+        });
+    }
+    call(service_1, method_1) {
+        return __awaiter(this, arguments, void 0, function* (service, method, args = {}) {
+            const endpoint = yield this.resolve(service, method);
+            const socket = yield this.getConnection(service, endpoint);
+            return this.enqueue(service, socket, method, args);
+        });
+    }
+    close() {
+        for (const socket of this.pool.values())
+            socket.destroy();
+        this.pool.clear();
+        this.locks.clear();
+        this.endpointCache.clear();
+        if (this.server)
+            this.server.close();
+    }
+    startServer() {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.http.put(`/update-service?name=${this.config.serviceName}`, {
+                host: this.config.host,
+                port: this.config.port,
+            });
+            return new Promise((resolve, reject) => {
+                this.server = net_1.default.createServer((socket) => {
+                    socket.setNoDelay(true);
+                    socket.setKeepAlive(true, 0);
+                    let buf = Buffer.alloc(0);
+                    socket.on("data", (chunk) => {
+                        buf = Buffer.concat([buf, chunk]);
+                        this.drainInbound(socket, buf).then((remaining) => {
+                            buf = remaining;
+                        });
+                    });
+                    socket.on("error", () => socket.destroy());
+                });
+                this.server.listen(this.config.port, () => resolve());
+                this.server.once("error", reject);
+            });
+        });
+    }
+    drainInbound(socket, buf) {
+        return __awaiter(this, void 0, void 0, function* () {
+            while (buf.length >= 4) {
+                const len = buf.readUInt32BE(0);
+                if (buf.length < 4 + len)
+                    break;
+                const frame = buf.slice(4, 4 + len);
+                buf = buf.slice(4 + len);
+                yield this.handleInboundFrame(socket, frame);
+            }
+            return buf;
+        });
+    }
+    handleInboundFrame(socket, frame) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            try {
+                const [method, args] = (0, msgpackr_1.unpack)(frame);
+                const handler = this.handlers.get(method);
+                if (!handler) {
+                    this.writeFrame(socket, [`Method "${method}" not found`]);
+                    return;
+                }
+                const result = yield handler(args);
+                this.writeFrame(socket, [null, result]);
+            }
+            catch (err) {
+                this.writeFrame(socket, [(_a = err === null || err === void 0 ? void 0 : err.message) !== null && _a !== void 0 ? _a : "Internal error"]);
+            }
+        });
+    }
+    writeFrame(socket, payload) {
+        const body = (0, msgpackr_1.pack)(payload);
+        const frame = Buffer.allocUnsafe(4 + body.byteLength);
+        frame.writeUInt32BE(body.byteLength, 0);
+        frame.set(body, 4);
+        socket.write(frame);
+    }
+    resolve(service, method) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const cached = this.endpointCache.get(service);
+            if (cached)
+                return cached;
+            const { data } = yield this.http
+                .get(`/get-method?name=${service}&method=${method}`)
+                .catch(() => {
+                throw errors_1.KubeRpcError.methodNotFound(method, service);
+            });
+            if (!data.host || !data.port) {
+                throw errors_1.KubeRpcError.methodNotFound(method, service);
+            }
+            const endpoint = { host: data.host, port: Number(data.port) };
+            this.endpointCache.set(service, endpoint);
+            return endpoint;
+        });
+    }
+    getConnection(service, endpoint) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const existing = this.pool.get(service);
+            if (existing && !existing.destroyed)
+                return existing;
+            const socket = yield new Promise((resolve, reject) => {
+                const s = new net_1.default.Socket();
+                s.setNoDelay(true);
+                s.setKeepAlive(true, 0);
+                s.connect(endpoint.port, endpoint.host, () => resolve(s));
+                s.once("error", () => reject(errors_1.KubeRpcError.connectionFailed(endpoint.host, endpoint.port)));
+            });
+            this.pool.set(service, socket);
+            socket.once("close", () => {
+                this.pool.delete(service);
+                this.locks.delete(service);
+                this.endpointCache.delete(service);
+            });
+            socket.once("error", () => {
+                this.pool.delete(service);
+                this.locks.delete(service);
+            });
+            return socket;
+        });
+    }
+    enqueue(service, socket, method, args) {
+        var _a;
+        const tail = ((_a = this.locks.get(service)) !== null && _a !== void 0 ? _a : Promise.resolve()).then(() => this.sendFrame(socket, method, args));
+        this.locks.set(service, tail.catch(() => { }));
+        return tail;
+    }
+    sendFrame(socket, method, args) {
+        return new Promise((resolve, reject) => {
+            const body = (0, msgpackr_1.pack)([method, args]);
+            const frame = Buffer.allocUnsafe(4 + body.byteLength);
+            frame.writeUInt32BE(body.byteLength, 0);
+            frame.set(body, 4);
+            let buf = Buffer.alloc(0);
+            const onData = (chunk) => {
+                buf = Buffer.concat([buf, chunk]);
+                if (buf.length < 4)
+                    return;
+                const len = buf.readUInt32BE(0);
+                if (buf.length < 4 + len)
+                    return;
+                socket.removeListener("data", onData);
+                const r = decodeResponse(buf.slice(4, 4 + len));
+                if (r.ok)
+                    resolve(r.value);
+                else
+                    reject(new Error(r.error));
+            };
+            socket.on("data", onData);
+            socket.once("error", reject);
+            socket.write(frame);
+        });
+    }
+}
+exports.KubeRPC = KubeRPC;
+function decodeResponse(buf) {
+    const raw = (0, msgpackr_1.unpack)(buf);
+    if (!Array.isArray(raw)) {
+        return { ok: false, error: `Protocol mismatch: expected array, got ${typeof raw}. Restart the server.` };
+    }
+    if (raw.length === 1)
+        return { ok: false, error: raw[0] };
+    return { ok: true, value: raw[1] };
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "kuberpc-node",
+  "version": "2.0.0",
+  "description": "Node.js SDK for kubeRPC. Register and invoke service methods over raw TCP.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node dist/index.js",
+    "build": "rimraf dist && tsc",
+    "build:all": "rimraf dist && tsc && yarn --cwd samples/server install --force && yarn --cwd samples/client install --force && yarn --cwd benchmark/server install --force && yarn --cwd benchmark/client install --force"
+  },
+  "keywords": [
+    "RPC",
+    "KubeRPC",
+    "SDK"
+  ],
+  "author": "Folarin Raphael",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/darksuei/kuberpc-sdk.git"
+  },
+  "devDependencies": {
+    "@types/node": "^22.8.5",
+    "rimraf": "^6.0.1",
+    "typescript": "^5.6.3"
+  },
+  "dependencies": {
+    "axios": "^1.7.7",
+    "msgpackr": "^2.0.4"
+  }
+}