bhooai-nexus 0.1.2

package/packages/nexus-cache/src/Cache.ts

@@ -0,0 +1,155 @@
+import { createClient, type RedisClientType } from 'redis';
+import type { CacheOptions } from './types.js';
+
+/**
+ * Redis-backed cache wrapper. Lazily creates and connects a `node-redis`
+ * client on first use. All keys pass through {@link Cache.key} to apply an
+ * optional namespace/prefix.
+ */
+export class Cache {
+  private client: RedisClientType;
+  private connectPromise: Promise<void> | null = null;
+  private readonly keyPrefix: string;
+  protected readonly url?: string;
+  protected readonly connectTimeout?: number;
+
+  constructor(opts: CacheOptions = {}) {
+    this.url = opts.url;
+    this.connectTimeout = opts.connectTimeout;
+    this.keyPrefix = opts.keyPrefix ?? (opts.namespace ? `${opts.namespace}:` : '');
+    // `redis` v4 createClient returns a client in a closed state; we connect
+    // lazily on first use via ensureConnected().
+    this.client = createClient({
+      ...(this.url ? { url: this.url } : {}),
+      ...(this.connectTimeout != null ? { socket: { connectTimeout: this.connectTimeout } } : {}),
+    });
+  }
+
+  /** Connect the underlying client if not already connected. Idempotent. */
+  async ensureConnected(): Promise<void> {
+    if (this.client.isOpen) return;
+    if (!this.connectPromise) {
+      this.connectPromise = this.client.connect().then(() => {
+        // connected
+      });
+    }
+    try {
+      await this.connectPromise;
+    } catch (err) {
+      // Reset so a later retry can attempt reconnection.
+      this.connectPromise = null;
+      throw err;
+    }
+  }
+
+  /** Build the fully-prefixed redis key for a logical name. */
+  key(name: string): string {
+    return `${this.keyPrefix}${name}`;
+  }
+
+  /** The underlying redis client (connected after `ensureConnected`). */
+  protected getClient(): RedisClientType {
+    return this.client;
+  }
+
+  /** Get a JSON-decoded value, or undefined on miss/null. */
+  async get<T>(name: string): Promise<T | undefined> {
+    await this.ensureConnected();
+    const raw = await this.client.get(this.key(name));
+    if (raw == null) return undefined;
+    return JSON.parse(raw) as T;
+  }
+
+  /** Set a JSON-encoded value, optionally with a TTL in seconds. */
+  async set<T>(name: string, value: T, ttlSeconds?: number): Promise<void> {
+    await this.ensureConnected();
+    const encoded = JSON.stringify(value);
+    if (ttlSeconds != null) {
+      await this.client.set(this.key(name), encoded, { EX: ttlSeconds });
+    } else {
+      await this.client.set(this.key(name), encoded);
+    }
+  }
+
+  /** Delete a key. */
+  async del(name: string): Promise<void> {
+    await this.ensureConnected();
+    await this.client.del(this.key(name));
+  }
+
+  /**
+   * INCR a key. When `ttlSeconds` is supplied and the result becomes 1 (first
+   * hit in a fresh window) the key is expired after `ttlSeconds` seconds.
+   * Returns the post-increment integer value.
+   */
+  async incr(name: string, ttlSeconds?: number): Promise<number> {
+    await this.ensureConnected();
+    const key = this.key(name);
+    const count = await this.client.incr(key);
+    if (ttlSeconds != null && count === 1) {
+      await this.client.expire(key, ttlSeconds);
+    }
+    return count;
+  }
+
+  /** Whether a key exists. */
+  async exists(name: string): Promise<boolean> {
+    await this.ensureConnected();
+    const n = await this.client.exists(this.key(name));
+    return n > 0;
+  }
+
+  /** Set an expiry (seconds) on an existing key. */
+  async expire(name: string, ttlSeconds: number): Promise<void> {
+    await this.ensureConnected();
+    await this.client.expire(this.key(name), ttlSeconds);
+  }
+
+  /** Remaining TTL in seconds (-1 no expiry, -2 missing key). */
+  async ttl(name: string): Promise<number> {
+    await this.ensureConnected();
+    return this.client.ttl(this.key(name));
+  }
+
+  /**
+   * Delete all keys matching a glob pattern using non-blocking SCAN + DEL.
+   * Returns the number of keys removed.
+   */
+  async flushPattern(pattern: string): Promise<number> {
+    await this.ensureConnected();
+    const fullPattern = `${this.keyPrefix}${pattern}`;
+    let cursor = 0;
+    let removed = 0;
+    do {
+      const reply = await this.client.scan(cursor, { MATCH: fullPattern, COUNT: 100 });
+      cursor = Number(reply.cursor);
+      const keys = reply.keys;
+      if (keys.length > 0) {
+        await this.client.del(keys);
+        removed += keys.length;
+      }
+    } while (cursor !== 0);
+    return removed;
+  }
+
+  /**
+   * Cache-aside helper: return the cached value if present, otherwise invoke
+   * `loader`, store its result with `ttlSeconds`, and return it. No negative
+   * caching in v1 — loader errors propagate to the caller.
+   */
+  async cacheAside<T>(name: string, ttlSeconds: number, loader: () => Promise<T>): Promise<T> {
+    const cached = await this.get<T>(name);
+    if (cached !== undefined) return cached;
+    const fresh = await loader();
+    await this.set(name, fresh, ttlSeconds);
+    return fresh;
+  }
+
+  /** Disconnect the underlying client. */
+  async close(): Promise<void> {
+    if (this.client.isOpen) {
+      await this.client.quit();
+    }
+    this.connectPromise = null;
+  }
+}

package/packages/nexus-cache/src/PubSub.ts

@@ -0,0 +1,98 @@
+import { createClient, type RedisClientType } from 'redis';
+import type { Cache } from './Cache.js';
+
+type Handler = (msg: unknown) => void;
+
+/**
+ * Redis pub/sub helper. Uses the {@link Cache} client for publishing and a
+ * separate, dedicated subscriber client (required by `redis` v4) for
+ * subscriptions. Both clients are connected lazily.
+ */
+export class PubSub {
+  private subscriber: RedisClientType;
+  private subscriberConnectPromise: Promise<void> | null = null;
+  private handlers = new Map<string, Set<Handler>>();
+
+  constructor(private cache: Cache) {
+    // Reuse the same URL/connection options as the cache's publisher client.
+    // The cache exposes its url/connectTimeout via protected fields; here we
+    // reconstruct from the cache's key prefix-agnostic config by reading the
+    // same options the cache used. We mirror the cache's createClient call.
+    const url = (cache as unknown as { url?: string }).url;
+    const connectTimeout = (cache as unknown as { connectTimeout?: number }).connectTimeout;
+    this.subscriber = createClient({
+      ...(url ? { url } : {}),
+      ...(connectTimeout != null ? { socket: { connectTimeout } } : {}),
+    });
+  }
+
+  private async ensureSubscriberConnected(): Promise<void> {
+    if (this.subscriber.isOpen) return;
+    if (!this.subscriberConnectPromise) {
+      this.subscriberConnectPromise = this.subscriber.connect().then(() => undefined);
+    }
+    try {
+      await this.subscriberConnectPromise;
+    } catch (err) {
+      this.subscriberConnectPromise = null;
+      throw err;
+    }
+  }
+
+  /** Publish a JSON-encoded message to `channel`. */
+  async publish(channel: string, message: unknown): Promise<void> {
+    // Ensure the cache (publisher) client is connected.
+    await this.cache.ensureConnected();
+    const publisher = (this.cache as unknown as { getClient: () => RedisClientType }).getClient();
+    await publisher.publish(channel, JSON.stringify(message));
+  }
+
+  /**
+   * Subscribe to `channel`; `handler` is invoked with the JSON-parsed payload.
+   * Returns an unsubscribe function that removes the handler and, when no
+   * handlers remain for the channel, unsubscribes from Redis.
+   */
+  async subscribe(channel: string, handler: Handler): Promise<() => Promise<void>> {
+    await this.ensureSubscriberConnected();
+    let set = this.handlers.get(channel);
+    if (!set) {
+      set = new Set();
+      this.handlers.set(channel, set);
+      // `redis` v4 subscribe(channel, callback) registers a per-channel
+      // listener that receives the message string.
+      await this.subscriber.subscribe(channel, (message) => {
+        const handlers = this.handlers.get(channel);
+        if (!handlers) return;
+        let parsed: unknown;
+        try {
+          parsed = JSON.parse(message);
+        } catch {
+          parsed = message;
+        }
+        for (const h of handlers) h(parsed);
+      });
+    }
+    set.add(handler);
+    return async () => {
+      const current = this.handlers.get(channel);
+      if (!current) return;
+      current.delete(handler);
+      if (current.size === 0) {
+        this.handlers.delete(channel);
+        try {
+          await this.subscriber.unsubscribe(channel);
+        } catch {
+          /* ignore — client may be closing */
+        }
+      }
+    };
+  }
+
+  /** Close the dedicated subscriber client. */
+  async close(): Promise<void> {
+    if (this.subscriber.isOpen) {
+      await this.subscriber.quit();
+    }
+    this.subscriberConnectPromise = null;
+  }
+}

package/packages/nexus-cache/src/RateLimiter.ts

@@ -0,0 +1,43 @@
+import type { Cache } from './Cache.js';
+import type { RateLimitResult, RateLimitRule } from './types.js';
+
+/**
+ * Fixed-window counter rate limiter backed by Redis INCR via a {@link Cache}.
+ * Each call to {@link RateLimiter.check} atomically increments a per-key
+ * counter and, on the first hit of a window, sets the window expiry.
+ */
+export class RateLimiter {
+  constructor(private cache: Cache) {}
+
+  /**
+   * Check (and consume) one unit against the rule for `key`. Redis INCR both
+   * increments and returns the count, so the counter is consumed regardless of
+   * whether the request is allowed — matching the in-memory store semantics.
+   */
+  async check(key: string, rule: RateLimitRule): Promise<RateLimitResult> {
+    const redisKey = `${key}:rate`;
+    const count = await this.cache.incr(redisKey, rule.windowSeconds);
+    const limit = rule.max;
+    const allowed = count <= limit;
+    const remaining = Math.max(0, limit - count);
+    // Use the live TTL to compute resetAt; falls back to now + window.
+    let ttl = await this.cache.ttl(redisKey);
+    if (ttl < 0) ttl = rule.windowSeconds;
+    const resetAt = Date.now() + ttl * 1000;
+    const result: RateLimitResult = {
+      allowed,
+      limit,
+      remaining,
+      resetAt,
+    };
+    if (!allowed) {
+      result.retryAfter = rule.windowSeconds;
+    }
+    return result;
+  }
+
+  /** Alias of {@link check}; the counter is already consumed by INCR. */
+  async consume(key: string, rule: RateLimitRule): Promise<RateLimitResult> {
+    return this.check(key, rule);
+  }
+}

package/packages/nexus-cache/src/index.ts

@@ -0,0 +1,9 @@
+export { Cache } from './Cache.js';
+export { RateLimiter } from './RateLimiter.js';
+export { PubSub } from './PubSub.js';
+export type {
+  CacheOptions,
+  CacheEntry,
+  RateLimitResult,
+  RateLimitRule,
+} from './types.js';

package/packages/nexus-cache/src/types.ts

@@ -0,0 +1,47 @@
+/**
+ * Options for constructing a {@link Cache} instance.
+ */
+export interface CacheOptions {
+  /** Redis connection URL (e.g. `redis://localhost:6379`). */
+  url?: string;
+  /** Logical namespace applied to all keys as `${namespace}:` prefix. */
+  namespace?: string;
+  /** Explicit key prefix (overrides namespace prefix when provided). */
+  keyPrefix?: string;
+  /** Connection timeout in milliseconds passed to the redis client. */
+  connectTimeout?: number;
+}
+
+/**
+ * A cached value entry (kept for symmetry; values are JSON-stringified as-is).
+ */
+export interface CacheEntry<T> {
+  value: T;
+  expiresAt?: number;
+}
+
+/**
+ * Result of a rate-limit check.
+ */
+export interface RateLimitResult {
+  /** Whether the request is allowed under the current window. */
+  allowed: boolean;
+  /** Maximum requests permitted in the window. */
+  limit: number;
+  /** Remaining requests in the current window (>= 0). */
+  remaining: number;
+  /** Epoch ms when the current window resets. */
+  resetAt: number;
+  /** Seconds until the next request would be allowed (present when denied). */
+  retryAfter?: number;
+}
+
+/**
+ * Fixed-window rate-limit rule.
+ */
+export interface RateLimitRule {
+  /** Window length in seconds. */
+  windowSeconds: number;
+  /** Maximum requests permitted per window. */
+  max: number;
+}

package/packages/nexus-cli/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@bhooai/nexus-cli",
+  "version": "0.1.0",
+  "publishConfig": { "access": "public" },
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "bin": {
+    "nexus": "./bin/nexus.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@bhooai/nexus-cluster": "^0.1.0",
+    "@bhooai/nexus-core": "^0.1.0",
+    "@bhooai/nexus-data": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.5.0",
+    "typescript": "^5.6.2",
+    "vitest": "^2.1.1"
+  }
+}

package/packages/nexus-cli/src/commands/cluster.ts

@@ -0,0 +1,133 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { loadConfigAuto } from '../../../nexus-core/src/index.js';
+import { ClusterManager } from '@bhooai/nexus-cluster';
+import type { DeepPartial, NexusConfig } from '@bhooai/nexus-core';
+
+const GREEN = '\x1b[32m';
+const RED = '\x1b[31m';
+const YELLOW = '\x1b[33m';
+const CYAN = '\x1b[36m';
+const DIM = '\x1b[2m';
+const RESET = '\x1b[0m';
+
+/**
+ * `nexus cluster <subcommand>` - central-side mesh orchestration.
+ *
+ *   cluster status            list linked nodes + LB RPS
+ *   cluster link <url>        handshake + register a node by its agent URL
+ *   cluster unlink <id>       forget a node
+ *   cluster start|stop|restart|kill <id>
+ *   cluster scale <n>         target exactly n backend nodes
+ *   cluster serve             hold process: LB + autoscaler (foreground)
+ *   cluster check             poll every node once (health + metrics)
+ */
+export async function cluster(args: string[]): Promise<number> {
+  const cfg = await loadConfigAuto({ root: process.cwd() });
+  const [sub, a, b] = args;
+
+  // `serve` is the explicit "start the cluster" command - if a prior admin
+  // stop wrote {cluster:{enabled:false}} into nexus.runtime.json, that
+  // override wins over nexus.config.ts and would silently keep the cluster
+  // off. Re-enable it in runtime.json so the LB actually starts.
+  if (sub === 'serve' && !cfg.cluster.enabled) {
+    enableClusterInRuntime(process.cwd());
+    console.log(`${YELLOW}cluster was disabled in nexus.runtime.json - re-enabling${RESET}`);
+  }
+
+  // For non-serve commands, warn (don't block) when the cluster is off.
+  if (sub !== 'serve' && !cfg.cluster.enabled) {
+    console.warn(`${RED}cluster.enabled is false${RESET} - run ${CYAN}nexus cluster serve${RESET} to start it, or set cluster: { enabled: true } in nexus.config.ts`);
+  }
+
+  const manager = new ClusterManager({ config: cfg.cluster, root: process.cwd(), aiServerUrl: cfg.ai.serverUrl });
+
+  switch (sub ?? 'help') {
+    case 'status': {
+      const nodes = manager.list();
+      const rps = manager.rps();
+      console.log(`${CYAN}cluster${RESET} - ${nodes.length} linked node(s)`);
+      for (const n of nodes) {
+        const color = n.status === 'ready' ? GREEN : n.status === 'unreachable' ? RED : CYAN;
+        console.log(`  ${color}${n.status}${RESET} ${DIM}${n.identity.id}${RESET} role=${n.identity.role} tier=${n.identity.tier} enabled=${n.enabled} rps=${rps[n.identity.id] ?? 0}${n.lastMetrics ? ` cpu=${n.lastMetrics.cpu}% mem=${n.lastMetrics.memoryMb}MiB` : ''}`);
+      }
+      return 0;
+    }
+    case 'link': {
+      if (!a) { console.error('cluster link <agent-url>'); return 1; }
+      try {
+        const node = await manager.link(a);
+        const color = node.status === 'ready' ? GREEN : CYAN;
+        console.log(`${color}linked${RESET} ${node.identity.id} role=${node.identity.role} base=${node.identity.baseUrl}`);
+        return 0;
+      } catch (err) {
+        console.error(`${RED}link failed${RESET}: ${(err as Error).message}`);
+        return 1;
+      }
+    }
+    case 'unlink': {
+      if (!a) { console.error('cluster unlink <id>'); return 1; }
+      return manager.unlink(a) ? (console.log(`removed ${a}`), 0) : (console.error(`no such node: ${a}`), 1);
+    }
+    case 'start':
+    case 'stop':
+    case 'restart':
+    case 'kill': {
+      if (!a) { console.error(`cluster ${sub} <id>`); return 1; }
+      await manager.exec(a, sub === 'kill' ? 'stop' : sub);
+      console.log(`${sub} ${a}`);
+      return 0;
+    }
+    case 'scale': {
+      if (!a || !Number.isFinite(Number(a))) { console.error('cluster scale <n>'); return 1; }
+      try {
+        await manager.scaleTo(Number(a));
+        console.log(`scaled to ${a} backend node(s)`);
+        return 0;
+      } catch (err) {
+        console.error(`${RED}${(err as Error).message}${RESET}`);
+        return 1;
+      }
+    }
+    case 'check': {
+      await manager.pollAll();
+      console.log(`checked ${manager.list().length} node(s)`);
+      return 0;
+    }
+    case 'serve': {
+      console.log(`${CYAN}cluster${RESET} LB on ${cfg.cluster.lbHost}:${cfg.cluster.lbPort}${RESET}`);
+      await manager.listenLb(cfg.cluster.lbHost);
+      manager.autoscaler.start(10_000);
+      setInterval(() => void manager.pollAll().catch(() => {}), 15_000);
+      return 0;
+    }
+    case 'help':
+    default:
+      console.log(`Usage: nexus cluster <status|link|unlink|start|stop|restart|kill|scale|check|serve>`);
+      return 0;
+  }
+}
+
+/**
+ * Patch `nexus.runtime.json` to set `cluster.enabled = true`. The admin
+ * "stop cluster" endpoint writes `{cluster:{enabled:false}}` there, and that
+ * override beats `nexus.config.ts` in the loader precedence - so `nexus
+ * cluster serve` would read `enabled:false` and the LB would never bind.
+ * This removes the stale override so `serve` actually starts the cluster.
+ */
+function enableClusterInRuntime(root: string): void {
+  const runtimePath = resolve(root, 'nexus.runtime.json');
+  let runtime: Record<string, unknown> = {};
+  if (existsSync(runtimePath)) {
+    try {
+      runtime = JSON.parse(readFileSync(runtimePath, 'utf8')) as Record<string, unknown>;
+    } catch {
+      // corrupt runtime file - start fresh
+      runtime = {};
+    }
+  }
+  const cluster = (runtime['cluster'] ?? {}) as Record<string, unknown>;
+  cluster['enabled'] = true;
+  runtime['cluster'] = cluster;
+  writeFileSync(runtimePath, `${JSON.stringify(runtime, null, 2)}\n`);
+}