@onlineapps/service-common 1.2.0 → 2.0.1

package/README.md

@@ -102,6 +102,61 @@ All helpers fail fast: a missing or non-integer `tenant_id`/`workspace_id`
 throws rather than degrading into "system rows only", which would silently hide
 a workspace's own definitions.
 
+### Registry reader — `createRegistryReader(options)`
+
+The single Redis-backed reader of Service Registry specifications. The Registry
+(`api_services_registry`) is the only writer; every consumer — infrastructure or
+business — reads the same two key shapes:
+
+| Key | Type | Content |
+|---|---|---|
+| `<keyPrefix>services` | HASH | per-service summary |
+| `<keyPrefix>service:<name>:spec` | STRING | full service specification |
+
+Normative contract: [`api/docs/biz/30-operations/registration-wire.md`](../../docs/biz/30-operations/registration-wire.md)
+§4 (storage model) and §7 (consumer contract); namespace per
+[`api/docs/standards/redis-key-contract.md`](../../docs/standards/redis-key-contract.md).
+
+```js
+const { createRegistryReader } = require('@onlineapps/service-common');
+
+const reader = createRegistryReader({
+  keyPrefix: requireEnv('REDIS_REGISTRY_KEY_PREFIX'), // REQUIRED — never assumed
+  redisUrl: requireEnv('REDIS_URL'),                  // or: client: <connected node-redis v4 client>
+  logger                                              // REQUIRED — no console fallback
+});
+await reader.connect();
+
+const op = await reader.getOperation('biz-invoicing', 'create-invoice');
+```
+
+| Export | Purpose |
+|---|---|
+| `connect()` | opens the owned connection (hard `connectTimeoutMs` ceiling), or validates an injected client |
+| `getServiceSpec(name)` | full spec, or `null` when the service is not registered |
+| `getOperation(name, key)` | one operation record, or `null` |
+| `listSummary()` | parsed `<keyPrefix>services` hash |
+| `listAll()` | `[{ name, summary, spec }]` for every summarised service |
+| `listWorkspaceScopedServices()` | `[{ name, version, description }]` for `workspaceScoped === true`, sorted by name; `version`/`description` come from `spec.metadata` (§4: `metadata` is required) |
+| `invalidateCache(name?)` | drop one service or the whole cache — for `registry.changes` listeners |
+| `close()` | quits the connection **only** when the reader created it |
+
+**Connection ownership:** pass exactly one of `redisUrl` (the reader owns and
+closes the client) or `client` (the caller owns it; `close()` never quits it).
+
+**Failure model — an outage is not a cache miss:**
+
+| Situation | Answer |
+|---|---|
+| key absent | `null`, remembered for `negativeTtlMs` (default 30 s) |
+| Redis transport error | the error **propagates** — never `null` |
+| unparseable JSON | throws, naming the key |
+| Redis unreachable at startup | `connect()` rejects after `connectTimeoutMs` (default 15 s) |
+
+`keyPrefix` and `logger` are mandatory and `ttlMs` / `negativeTtlMs` /
+`connectTimeoutMs` are validated: an invalid value throws instead of being
+silently replaced by the module default (`src/defaults.js` owns the defaults).
+
 ## Architecture
 
 This library is used by:

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@onlineapps/service-common",
-  "version": "1.2.0",
-  "description": "Common utilities for both infrastructure services and business services (JWT auth, Redis/Postgres clients, business errors, runtime config)",
+  "version": "2.0.1",
+  "description": "Common utilities for both infrastructure services and business services (JWT auth, Redis client, business errors, runtime config)",
   "main": "src/index.js",
   "scripts": {
     "test": "jest",
     "test:unit": "jest tests/unit",
-    "test:integration": "jest tests/integration"
+    "test:integration": "jest --config=jest.integration.config.js",
+    "test:all": "npm run test && npm run test:integration"
   },
   "keywords": [
     "microservices",
@@ -17,7 +18,7 @@
   "author": "OA Drive Team",
   "license": "MIT",
   "dependencies": {
-    "@onlineapps/runtime-config": "1.0.2",
+    "@onlineapps/runtime-config": "1.0.3",
     "jsonwebtoken": "^9.0.3",
     "nodemailer": "^6.9.8",
     "redis": "^4.6.0"

package/src/defaults.js

@@ -20,6 +20,16 @@ module.exports = {
 
   infrastructureHealthQueueWaitMaxTimeMs: 60000,
   infrastructureHealthQueueWaitCheckIntervalMs: 2000,
+
+  // registryReader in-memory cache (see ./registryReader.js).
+  // Positive entries live 5 minutes; a "service not registered" answer is
+  // remembered for 30 s only, so a fresh registration becomes visible quickly.
+  registryReaderTtlMs: 300000,
+  registryReaderNegativeTtlMs: 30000,
+  // Hard ceiling for the initial connect when the reader owns the client, so a
+  // dead Redis fails startup instead of retrying forever (same 15 s ceiling as
+  // connectRedis in ./redisClient.js).
+  registryReaderConnectTimeoutMs: 15000,
 };
 
 

package/src/index.js

@@ -17,11 +17,7 @@ const {
   createRedisClient,
   connectRedis
 } = require('./redisClient');
-const {
-  buildPostgresUrl,
-  createPostgresPool,
-  connectPostgres
-} = require('./postgresClient');
+const { createRegistryReader } = require('./registryReader');
 const {
   requireEnv,
   requireNumberEnv,
@@ -79,10 +75,9 @@ module.exports = {
   createRedisClient,
   connectRedis,
 
-  // PostgreSQL utilities (shared between services and tests)
-  buildPostgresUrl,
-  createPostgresPool,
-  connectPostgres,
+  // Service Registry reader (the one Redis-backed reader of registry specs)
+  // See: docs/biz/30-operations/registration-wire.md §4/§7
+  createRegistryReader,
 
   // Configuration helpers (NO FALLBACKS for critical infrastructure)
   requireEnv,

package/src/infrastructure/waitForHealthCheckQueueReady.js

@@ -29,7 +29,7 @@ const runtimeCfg = require('../config');
  * @param {string} [options.redisUrl] - Redis URL (default: REDIS_URL env or redis://api_node_cache:6379)
  * @param {number} [options.maxWait] - Maximum wait time in ms (default: 60000 = 1 minute)
  * @param {number} [options.checkInterval] - Check interval in ms (default: 2000 = 2 seconds)
- * @param {Object} [options.logger] - Logger instance (default: console)
+ * @param {Object} options.logger - Logger instance (required; no console fallback)
  * @returns {Promise<boolean>} - True if queue is ready
  * @throws {Error} - If timeout is reached
  */

package/src/infrastructure/waitForInfrastructureReady.js

@@ -37,7 +37,7 @@ const runtimeCfg = require('../config');
  * @param {string} [options.redisUrl] - Redis URL (default: REDIS_URL env or redis://api_node_cache:6379)
  * @param {number} [options.maxWait] - Maximum wait time in ms (default: INFRASTRUCTURE_HEALTH_WAIT_MAX_TIME env or 60000 = 1 minute)
  * @param {number} [options.checkInterval] - Check interval in ms (default: INFRASTRUCTURE_HEALTH_WAIT_CHECK_INTERVAL env or 2000 = 2 seconds)
- * @param {Object} [options.logger] - Logger instance (default: console)
+ * @param {Object} options.logger - Logger instance (required; no console fallback)
  * @returns {Promise<boolean>} - True if all infrastructure services are ready
  * @throws {Error} - If timeout is reached
  * 

package/src/registryReader.js

@@ -0,0 +1,355 @@
+'use strict';
+
+/**
+ * registryReader
+ * --------------
+ * The one Redis-backed reader of the Service Registry specifications.
+ *
+ * The Registry (`api_services_registry`) is the single writer; every consumer —
+ * infrastructure or business — reads the same two key shapes:
+ *
+ *   `<keyPrefix>services`              HASH   — per-service summary
+ *   `<keyPrefix>service:<name>:spec`   STRING — full service specification
+ *
+ * The prefix is NEVER assumed. It is injected by the caller (the platform value
+ * lives in REDIS_REGISTRY_KEY_PREFIX), because a reader that hardcodes a
+ * namespace cannot be pointed at a second one — not in a test, not in a second
+ * environment.
+ *
+ * Failure model (fail-fast, architecture-principles §3/§4):
+ *   - key absent            → `null`, remembered for `negativeTtlMs`
+ *   - Redis transport error → the error PROPAGATES (never `null`)
+ *   - unparseable JSON      → throws, naming the key
+ *
+ * An infrastructure outage and "this service is not registered" are different
+ * facts and must not collapse into the same answer.
+ *
+ * @see api/docs/biz/30-operations/registration-wire.md §4 Redis storage model
+ * @see api/docs/biz/30-operations/registration-wire.md §7 Consumer contract
+ * @see api/docs/standards/redis-key-contract.md — registry namespace
+ */
+
+const { createClient } = require('redis');
+const DEFAULTS = require('./defaults');
+
+const CONTEXT = '[service-common][registryReader]';
+
+function requireKeyPrefix(keyPrefix) {
+  if (typeof keyPrefix !== 'string' || keyPrefix.trim().length === 0) {
+    throw new Error(
+      `${CONTEXT} Missing required option - keyPrefix must be a non-empty string. `
+      + 'Fix: pass the registry key namespace explicitly, e.g. the value of REDIS_REGISTRY_KEY_PREFIX '
+      + `(got ${JSON.stringify(keyPrefix)}).`
+    );
+  }
+  return keyPrefix;
+}
+
+function requireLogger(logger) {
+  const missing = ['info', 'warn', 'error'].filter(
+    (method) => !logger || typeof logger[method] !== 'function'
+  );
+  if (missing.length > 0) {
+    throw new Error(
+      `${CONTEXT} Missing dependency - logger is required and must implement ${missing.join(', ')} `
+      + '(no console fallback). Fix: inject the service logger.'
+    );
+  }
+  return logger;
+}
+
+function requireTtl(value, name, fallbackDefault) {
+  if (value === undefined) return fallbackDefault;
+  if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
+    throw new Error(
+      `${CONTEXT} Invalid option - ${name} must be a finite positive number of milliseconds `
+      + `(got ${JSON.stringify(value)}). Fix: omit it to use the module default, or pass a number > 0.`
+    );
+  }
+  return value;
+}
+
+function requireClientContract(client) {
+  const missing = ['get', 'hGetAll'].filter((method) => typeof client[method] !== 'function');
+  if (missing.length > 0) {
+    throw new Error(
+      `${CONTEXT} Redis client contract mismatch - injected client is missing: ${missing.join(', ')}. `
+      + 'Fix: inject a connected node-redis v4 client.'
+    );
+  }
+  return client;
+}
+
+function requireNonEmptyString(value, label) {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new Error(
+      `${CONTEXT} Invalid argument - ${label} must be a non-empty string (got ${JSON.stringify(value)}).`
+    );
+  }
+  return value;
+}
+
+function parseOrThrow(raw, key, what) {
+  try {
+    return JSON.parse(raw);
+  } catch (err) {
+    throw new Error(
+      `${CONTEXT} Corrupt registry data - ${what} at ${key} is not valid JSON (${err.message}). `
+      + 'Fix: the Registry is the single writer of this key — re-register the service.'
+    );
+  }
+}
+
+/**
+ * Create a registry reader.
+ *
+ * Exactly one connection source must be given:
+ *   - `redisUrl` — the reader creates and owns the client (closed by `close()`)
+ *   - `client`   — an already connected node-redis v4 client owned by the caller
+ *                  (`close()` never quits it)
+ *
+ * @param {object}  options
+ * @param {string}  options.keyPrefix       Registry key namespace (REQUIRED, no default)
+ * @param {string}  [options.redisUrl]      Redis connection URL
+ * @param {object}  [options.client]        Connected node-redis v4 client
+ * @param {object}  options.logger          Logger implementing info/warn/error (REQUIRED)
+ * @param {number}  [options.ttlMs]         TTL of a cached spec (default: defaults.registryReaderTtlMs)
+ * @param {number}  [options.negativeTtlMs] TTL of a cached "not registered" (default: defaults.registryReaderNegativeTtlMs)
+ * @returns {object} reader
+ */
+function createRegistryReader(options) {
+  if (!options || typeof options !== 'object') {
+    throw new Error(
+      `${CONTEXT} Missing options - createRegistryReader({ keyPrefix, redisUrl|client, logger }) is required.`
+    );
+  }
+
+  const { keyPrefix, redisUrl, client, logger, ttlMs, negativeTtlMs, connectTimeoutMs } = options;
+
+  requireKeyPrefix(keyPrefix);
+
+  const hasUrl = redisUrl !== undefined;
+  const hasClient = client !== undefined;
+  if (hasUrl === hasClient) {
+    throw new Error(
+      `${CONTEXT} Invalid connection source - pass exactly one of redisUrl or client `
+      + `(redisUrl: ${hasUrl ? 'set' : 'absent'}, client: ${hasClient ? 'set' : 'absent'}). `
+      + 'Fix: let the reader own the connection (redisUrl) or inject an existing one (client).'
+    );
+  }
+  if (hasUrl && (typeof redisUrl !== 'string' || redisUrl.trim().length === 0)) {
+    throw new Error(
+      `${CONTEXT} Invalid option - redisUrl must be a non-empty string (got ${JSON.stringify(redisUrl)}).`
+    );
+  }
+  if (hasClient) {
+    if (!client || typeof client !== 'object') {
+      throw new Error(`${CONTEXT} Invalid option - client must be a connected node-redis v4 client object.`);
+    }
+    requireClientContract(client);
+  }
+
+  const log = requireLogger(logger);
+  const positiveTtl = requireTtl(ttlMs, 'ttlMs', DEFAULTS.registryReaderTtlMs);
+  const negativeTtl = requireTtl(negativeTtlMs, 'negativeTtlMs', DEFAULTS.registryReaderNegativeTtlMs);
+  const connectTimeout = requireTtl(
+    connectTimeoutMs, 'connectTimeoutMs', DEFAULTS.registryReaderConnectTimeoutMs
+  );
+
+  const ownsClient = hasUrl;
+  let redis = hasClient ? client : null;
+  let connected = false;
+
+  /** @type {Map<string, {spec: object|null, expiresAt: number}>} */
+  const specCache = new Map();
+  let summaryCache = null;
+
+  const summaryKey = () => `${keyPrefix}services`;
+  const specKey = (serviceName) => `${keyPrefix}service:${serviceName}:spec`;
+
+  function assertConnected(method) {
+    if (!connected) {
+      throw new Error(
+        `${CONTEXT} Reader is not connected - ${method} was called before connect(). `
+        + 'Fix: await reader.connect() during service startup.'
+      );
+    }
+  }
+
+  async function connect() {
+    if (connected) return;
+
+    if (ownsClient) {
+      const created = createClient({ url: redisUrl, socket: { connectTimeout } });
+      created.on('error', (err) => {
+        log.error(`${CONTEXT} Redis client error: ${err.message}`);
+      });
+
+      // node-redis keeps retrying a refused connection forever, so the initial
+      // connect gets its own hard ceiling — startup must fail, not hang.
+      let timeoutHandle = null;
+      const deadline = new Promise((_resolve, reject) => {
+        timeoutHandle = setTimeout(() => reject(new Error(
+          `${CONTEXT} Redis connection timeout - no connection to ${redisUrl} within ${connectTimeout}ms. `
+          + 'Fix: check the Redis address and that the instance is running.'
+        )), connectTimeout);
+      });
+
+      try {
+        await Promise.race([created.connect(), deadline]);
+      } catch (err) {
+        try {
+          await created.disconnect();
+        } catch (_ignored) {
+          // The client never opened; nothing to release.
+        }
+        throw err;
+      } finally {
+        clearTimeout(timeoutHandle);
+      }
+      redis = created;
+    }
+
+    connected = true;
+    log.info(`${CONTEXT} Ready (keyPrefix="${keyPrefix}", ttl=${positiveTtl}ms, negativeTtl=${negativeTtl}ms)`);
+  }
+
+  async function getServiceSpec(serviceName) {
+    assertConnected('getServiceSpec()');
+    requireNonEmptyString(serviceName, 'serviceName');
+
+    const now = Date.now();
+    const cached = specCache.get(serviceName);
+    if (cached && cached.expiresAt > now) {
+      return cached.spec;
+    }
+
+    const key = specKey(serviceName);
+    // Transport errors propagate on purpose — see the failure model above.
+    const raw = await redis.get(key);
+
+    if (raw === null || raw === undefined) {
+      specCache.set(serviceName, { spec: null, expiresAt: now + negativeTtl });
+      return null;
+    }
+
+    const spec = parseOrThrow(raw, key, 'service spec');
+    specCache.set(serviceName, { spec, expiresAt: now + positiveTtl });
+    return spec;
+  }
+
+  async function getOperation(serviceName, operationKey) {
+    assertConnected('getOperation()');
+    requireNonEmptyString(serviceName, 'serviceName');
+    requireNonEmptyString(operationKey, 'operationKey');
+
+    const spec = await getServiceSpec(serviceName);
+    const operations = spec && spec.operations;
+    if (!operations || typeof operations !== 'object') {
+      return null;
+    }
+    if (!Object.prototype.hasOwnProperty.call(operations, operationKey)) {
+      return null;
+    }
+    return operations[operationKey];
+  }
+
+  async function listSummary() {
+    assertConnected('listSummary()');
+
+    const now = Date.now();
+    if (summaryCache && summaryCache.expiresAt > now) {
+      return summaryCache.services;
+    }
+
+    const key = summaryKey();
+    const raw = await redis.hGetAll(key);
+
+    const services = {};
+    for (const [name, json] of Object.entries(raw || {})) {
+      services[name] = parseOrThrow(json, key, `summary entry "${name}"`);
+    }
+
+    summaryCache = { services, expiresAt: now + positiveTtl };
+    return services;
+  }
+
+  async function listAll() {
+    assertConnected('listAll()');
+    const summary = await listSummary();
+    return Promise.all(
+      Object.keys(summary).map(async (name) => ({
+        name,
+        summary: summary[name],
+        spec: await getServiceSpec(name)
+      }))
+    );
+  }
+
+  async function listWorkspaceScopedServices() {
+    assertConnected('listWorkspaceScopedServices()');
+    const all = await listAll();
+
+    const scoped = [];
+    for (const { name, spec } of all) {
+      if (!spec || spec.workspaceScoped !== true) continue;
+
+      const metadata = spec.metadata;
+      const version = metadata && metadata.version;
+      const description = metadata && metadata.description;
+      if (typeof version !== 'string' || version.length === 0
+        || typeof description !== 'string' || description.length === 0) {
+        throw new Error(
+          `${CONTEXT} Invalid service spec - service "${name}" declares workspaceScoped: true but its `
+          + 'metadata block does not carry both version and description '
+          + '(registration-wire.md §4: metadata is required). Fix: correct config.json and re-register.'
+        );
+      }
+      scoped.push({ name, version, description });
+    }
+
+    scoped.sort((a, b) => a.name.localeCompare(b.name));
+    return scoped;
+  }
+
+  function invalidateCache(serviceName) {
+    if (serviceName) {
+      specCache.delete(serviceName);
+      return;
+    }
+    specCache.clear();
+    summaryCache = null;
+  }
+
+  async function close() {
+    if (ownsClient && redis && connected) {
+      try {
+        await redis.quit();
+      } catch (err) {
+        log.warn(`${CONTEXT} Redis quit error: ${err.message}`);
+      }
+      redis = null;
+    }
+    connected = false;
+    specCache.clear();
+    summaryCache = null;
+  }
+
+  return {
+    connect,
+    getServiceSpec,
+    getOperation,
+    listSummary,
+    listAll,
+    listWorkspaceScopedServices,
+    invalidateCache,
+    close,
+    get keyPrefix() { return keyPrefix; },
+    get ttlMs() { return positiveTtl; },
+    get negativeTtlMs() { return negativeTtl; },
+    get isConnected() { return connected; },
+    get cacheSize() { return specCache.size; }
+  };
+}
+
+module.exports = { createRegistryReader };

package/src/postgresClient.js

@@ -1,112 +0,0 @@
-'use strict';
-
-/**
- * PostgreSQL Client Utilities
- * 
- * Provides helper functions for building PostgreSQL connection URLs.
- *
- * NO FALLBACKS: Topology must be explicit via ENV/config. This module must not
- * embed docker-compose hostnames or credentials.
- */
-
-/**
- * Build a PostgreSQL connection URL from environment.
- *
- * @param {Object} options - Options
- * @param {Object} [options.env=process.env] - Environment variables
- * @returns {string} PostgreSQL connection URL
- */
-function buildPostgresUrl(options = {}) {
-  const env = options.env || process.env || {};
-
-  const url = env.POSTGRES_URL && typeof env.POSTGRES_URL === 'string' ? env.POSTGRES_URL.trim() : '';
-  if (url) return url;
-
-  const host = env.POSTGRES_HOST && typeof env.POSTGRES_HOST === 'string' ? env.POSTGRES_HOST.trim() : '';
-  const port = env.POSTGRES_PORT && typeof env.POSTGRES_PORT === 'string' ? env.POSTGRES_PORT.trim() : '';
-  const user = env.POSTGRES_USER && typeof env.POSTGRES_USER === 'string' ? env.POSTGRES_USER.trim() : '';
-  const password = env.POSTGRES_PASSWORD && typeof env.POSTGRES_PASSWORD === 'string' ? env.POSTGRES_PASSWORD.trim() : '';
-  const database = env.POSTGRES_DB && typeof env.POSTGRES_DB === 'string' ? env.POSTGRES_DB.trim() : '';
-
-  const anyPartsProvided = Boolean(host || port || user || password || database);
-  if (!anyPartsProvided) {
-    throw new Error(
-      '[service-common][postgres] Missing configuration - POSTGRES_URL is required, or provide all: POSTGRES_HOST, POSTGRES_PORT, POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB.'
-    );
-  }
-
-  const missing = [];
-  if (!host) missing.push('POSTGRES_HOST');
-  if (!port) missing.push('POSTGRES_PORT');
-  if (!user) missing.push('POSTGRES_USER');
-  if (!password) missing.push('POSTGRES_PASSWORD');
-  if (!database) missing.push('POSTGRES_DB');
-  if (missing.length > 0) {
-    throw new Error(
-      `[service-common][postgres] Missing configuration - Partial PostgreSQL config provided. Missing: ${missing.join(', ')}. ` +
-        'Fix: set POSTGRES_URL or set all POSTGRES_* parts.'
-    );
-  }
-
-  // Do not attempt to do smart encoding here; POSTGRES_URL is the recommended option.
-  return `postgres://${user}:${password}@${host}:${port}/${database}`;
-}
-
-/**
- * Create a PostgreSQL connection pool
- * 
- * @param {Object} options - Options
- * @param {Object} [options.env=process.env] - Environment variables
- * @param {Object} [options.defaults] - Default connection parameters
- * @param {Object} [options.poolConfig] - Additional pool configuration (max, idleTimeoutMillis, etc.)
- * @returns {Object} PostgreSQL Pool instance
- */
-function createPostgresPool(options = {}) {
-  const { Pool } = require('pg');
-  
-  const connectionString = buildPostgresUrl({
-    env: options.env
-  });
-
-  const poolConfig = {
-    connectionString,
-    max: options.poolConfig?.max || 10,
-    idleTimeoutMillis: options.poolConfig?.idleTimeoutMillis || 30000,
-    connectionTimeoutMillis: options.poolConfig?.connectionTimeoutMillis || 2000,
-    ...options.poolConfig
-  };
-
-  return new Pool(poolConfig);
-}
-
-/**
- * Connect to PostgreSQL and test connection
- * 
- * @param {Object} pool - PostgreSQL Pool instance
- * @param {Object} logger - Logger object with info/error methods
- * @returns {Promise<void>}
- */
-async function connectPostgres(pool, logger) {
-  if (!logger) {
-    throw new Error('[service-common][postgres] Missing dependency - logger is required (no console fallback).');
-  }
-  try {
-    await pool.query('SELECT NOW()');
-    if (logger && logger.info) {
-      logger.info('[PostgreSQL] Connected');
-    }
-    return true;
-  } catch (error) {
-    if (logger && logger.error) {
-      logger.error('[PostgreSQL] Connection failed:', error);
-    }
-    throw error;
-  }
-}
-
-module.exports = {
-  buildPostgresUrl,
-  createPostgresPool,
-  connectPostgres
-};
-