@vincent_su/microservice-lite 1.0.0

package/index.mjs

@@ -0,0 +1,3 @@
+import { CreateService } from "./src/main.mjs";
+export { CreateService };
+export default CreateService;

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@vincent_su/microservice-lite",
+  "version": "1.0.0",
+  "description": "",
+  "license": "ISC",
+  "author": "",
+  "type": "commonjs",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "dependencies": {
+    "dotenv": "^17.4.1",
+    "got": "^15.0.1",
+    "js-yaml": "^4.1.1",
+    "pino": "^10.3.1",
+    "redis": "^5.11.0",
+    "tough-cookie": "^6.0.1"
+  }
+}

package/src/assert.mjs

@@ -0,0 +1,5 @@
+function assert(cond, msg) {
+  if (!cond) throw new Error(`[config] ${msg}`);
+}
+
+export { assert };

package/src/bindFunc.mjs

@@ -0,0 +1,35 @@
+import { config } from "./config.mjs";
+import { startJob } from "./job.mjs";
+import { logger } from "./logger.mjs";
+import { compute } from "./compute.mjs";
+import { init, saveState, loadState, subscribeState } from "./states.mjs";
+import { publish, subscribe } from "./pubsub.mjs";
+import { assert } from "./assert.mjs";
+import { getService } from "./service.mjs";
+
+let bindFunc = null;
+
+async function start() {
+  await new Promise(() => {});
+}
+
+const _setupFunc = async () => {
+  init();
+  bindFunc = {
+    config,
+    startJob,
+    assert,
+    logger,
+    compute,
+    loadState,
+    saveState,
+    subscribeState,
+    publish,
+    subscribe,
+    getService,
+    start,
+    
+  };
+};
+
+export { _setupFunc, bindFunc };

package/src/compute.mjs

@@ -0,0 +1,186 @@
+import { config } from "./config.mjs";
+import { logger } from "./logger.mjs";
+import { bindFunc } from "./bindFunc.mjs";
+import __path from "path";
+import { saveState } from "./states.mjs";
+import os from "os";
+
+const compute_modules = new Map();
+
+const getComputeModule = async (compute_name, compute_path) => {
+  if (compute_modules.has(compute_name)) {
+    return compute_modules.get(compute_name);
+  }
+  try {
+    const module = await import(
+      `${__path.resolve(compute_path)}/${compute_name}.mjs`
+    );
+    compute_modules.set(compute_name, module.default);
+    return module.default;
+  } catch (error) {
+    const safeError =
+      error.response?.body?.errorMessage ||
+      error.response?.statusCode + error.response?.statusMessage ||
+      error.message ||
+      error.code;
+    return { error: safeError };
+  }
+};
+
+async function compute({
+  compute_path = "./compute",
+  COMPUTES = [],
+  STATE = {},
+  breakOnError = true,
+}) {
+  STATE.COMPUTE = {
+    STATS: [],
+    ERRORS: [],
+  };
+
+  for (let i = 0; i < COMPUTES.length; i++) {
+    const sequence = COMPUTES[i];
+
+    const _promises = [];
+    const startTime = Date.now();
+    for (const compute of sequence) {
+      const computeFunc = await getComputeModule(compute, compute_path);
+
+      if (computeFunc.error) {
+        _promises.push(
+          tryCompute(async () => {
+            throw new Error(`Compute module error ${computeFunc.error}`);
+          }),
+        );
+      } else {
+        _promises.push(tryCompute(computeFunc, STATE));
+      }
+    }
+
+    const results = await Promise.all(_promises);
+
+    const computeInfo = {
+      completed: `${Date.now() - startTime}ms`,
+      hasError: false,
+    };
+
+    await saveState(STATE);
+
+    computeInfo.saved = `${Date.now() - startTime}ms`;
+
+    computeInfo.cpu_single_core = 0;
+    computeInfo.cpu_all_cores = 0;
+
+    for (let j = 0; j < results.length; j++) {
+      const sequenceInfo = {
+        name: sequence[j],
+        result: results[j],
+      };
+
+      computeInfo[sequenceInfo.name] = {
+        error: sequenceInfo.result.error,
+        timeElapsed: sequenceInfo.result.timeElapsed,
+        cpu_single_core: sequenceInfo.result.cpu.percentSingleCore,
+        cpu_all_cores: sequenceInfo.result.cpu.percentAllCores,
+      };
+
+      if (
+        sequenceInfo.result.cpu.percentSingleCore > computeInfo.cpu_single_core
+      ) {
+        computeInfo.cpu_single_core = sequenceInfo.result.cpu.percentSingleCore;
+      }
+
+      if (sequenceInfo.result.cpu.percentAllCores > computeInfo.cpu_all_cores) {
+        computeInfo.cpu_all_cores = sequenceInfo.result.cpu.percentAllCores;
+      }
+
+      //console.log(sequenceInfo.result);
+      /*
+      computeInfo[sequenceInfo.name] = sequenceInfo.result.error
+        ? `error: ${sequenceInfo.result.error}`
+        : sequenceInfo.result.success
+          ? `lapsed:${sequenceInfo.result.timeElapsed}ms, single-core:${sequenceInfo.result.cpu.percentSingleCore}%, all-cores:${sequenceInfo.result.cpu.percentAllCores}% `
+          : sequenceInfo.result;
+*/
+      if (sequenceInfo.result && sequenceInfo.result.error) {
+        computeInfo.hasError = true;
+        STATE.COMPUTE.ERRORS.push({
+          name: sequenceInfo.name,
+          error: sequenceInfo.result.error,
+        });
+      }
+    }
+
+    STATE.COMPUTE.STATS.push(computeInfo);
+
+    if (computeInfo.hasError) {
+      if (breakOnError) break;
+    }
+  }
+
+  if (config.server?.computeShowStats) {
+    logger.info("Compute stats:", STATE.COMPUTE);
+  }
+
+  if (STATE.COMPUTE.ERRORS.length > 0) {
+    logger.error("Errors STATE from compute:", STATE.COMPUTE.ERRORS);
+  }
+
+  return STATE.COMPUTE;
+}
+
+async function tryCompute(func, STATE = {}) {
+  const _startTime = Date.now();
+
+  const cpuStart = process.cpuUsage();
+  const hrStart = process.hrtime.bigint();
+
+  let errorResult = null;
+
+  try {
+    await func(bindFunc, STATE);
+  } catch (error) {
+    const safeError =
+      error.response?.body?.errorMessage ||
+      error.response?.body ||
+      error.response?.statusCode + error.response?.statusMessage ||
+      error.message ||
+      error.code;
+    errorResult = { error: safeError };
+  } finally {
+    const hrEnd = process.hrtime.bigint();
+    const cpuDelta = process.cpuUsage(cpuStart);
+
+    const wallMs = Number(hrEnd - hrStart) / 1e6;
+    const userMs = cpuDelta.user / 1000;
+    const systemMs = cpuDelta.system / 1000;
+    const totalCpuMs = userMs + systemMs;
+
+    const coreCount =
+      typeof os.availableParallelism === "function"
+        ? os.availableParallelism()
+        : os.cpus().length;
+
+    const percentSingleCore = wallMs > 0 ? (totalCpuMs / wallMs) * 100 : 0;
+
+    const percentAllCores =
+      wallMs > 0 ? (totalCpuMs / (wallMs * coreCount)) * 100 : 0;
+
+    const result = {
+      ...(errorResult ?? { success: true }),
+      timeElapsed: Date.now() - _startTime,
+      cpu: {
+        userMs: Number(userMs.toFixed(3)),
+        systemMs: Number(systemMs.toFixed(3)),
+        totalMs: Number(totalCpuMs.toFixed(3)),
+        wallMs: Number(wallMs.toFixed(3)),
+        percentSingleCore: Number(percentSingleCore.toFixed(2)),
+        percentAllCores: Number(percentAllCores.toFixed(2)),
+      },
+    };
+
+    return result;
+  }
+}
+
+export { compute };

package/src/config.mjs

@@ -0,0 +1,27 @@
+import fs from "fs";
+import yaml from "js-yaml";
+import { assert } from "./assert.mjs";
+import "dotenv/config";
+
+function expandEnv(str) {
+  return str.replace(/\$\{(\w+)\}/g, (_, name) => process.env[name] ?? "");
+}
+
+function loadConfig(path) {
+  const raw = fs.readFileSync(path, "utf8");
+  const cfg = yaml.load(expandEnv(raw));
+  Object.freeze(cfg);
+  return cfg;
+}
+
+let config = null;
+const _loadConfig = async (path = "./config.yml") => {
+  config = loadConfig(path);
+  assert(config.server, "Missing server config");
+  assert(config.server.appName, "Missing server.appName config");
+  assert(config.server.port, "Missing server.port config");
+
+  console.log(`====>config`, config)
+};
+
+export { config, _loadConfig };

package/src/job.mjs

@@ -0,0 +1,50 @@
+function startJob(state, loop, onError = () => {}, intervalMs = 1000) {
+  let stopped = false;
+  let running = false;
+  let timer = null;
+  let errorIntervalMs = null;
+  let specialIntervalMs = null;
+
+  const tick = async () => {
+    if (stopped || running) return;
+    running = true;
+    try {
+      await loop(state, (intervalMs) => {
+        if (typeof intervalMs === "number") {
+          specialIntervalMs = intervalMs;
+        }
+      });
+    } catch (err) {
+      try {
+        onError(err, (intervalMs) => {
+          if (typeof intervalMs === "number") {
+            errorIntervalMs = intervalMs;
+          }
+        });
+      } catch {}
+    } finally {
+      running = false;
+      if (!stopped) {
+        timer = setTimeout(
+          tick,
+          errorIntervalMs || specialIntervalMs || intervalMs,
+        );
+        if (timer.unref) timer.unref();
+        errorIntervalMs = null;
+        specialIntervalMs = null;
+      }
+    }
+  };
+
+  timer = setTimeout(tick, 0);
+  if (timer.unref) timer.unref();
+
+  return {
+    abort() {
+      stopped = true;
+      if (timer) clearTimeout(timer);
+    },
+  };
+}
+
+export { startJob };

package/src/logger.mjs

@@ -0,0 +1,175 @@
+import { config } from "./config.mjs";
+
+import pino from "pino";
+import { Writable } from "stream";
+
+let logger = null;
+
+/* ---------------- helpers ---------------- */
+function isRetryableMongoErr(err) {
+  const labelsArr =
+    (err?.errorLabelSet && Array.from(err.errorLabelSet)) ||
+    (Array.isArray(err?.labels) ? err.labels : []);
+  const labels = new Set(labelsArr);
+
+  const has = (k) => labels.has(k);
+
+  if (
+    has("RetryableWriteError") ||
+    has("ResumableChangeStreamError") ||
+    has("TransientTransactionError") ||
+    has("NetworkError") ||
+    has("ResetPool") ||
+    has("InterruptInUseConnections") ||
+    has("PoolRequestedRetry")
+  )
+    return true;
+
+  const n = err?.name;
+  return (
+    n === "MongoNetworkError" ||
+    n === "MongoNetworkTimeoutError" ||
+    n === "MongoServerSelectionError" ||
+    n === "MongoNotConnectedError"
+  );
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const jitter = (min, max) => Math.floor(Math.random() * (max - min + 1)) + min;
+
+/* ---------------- Wrap pino so it captures ALL args ---------------- */
+function wrapLogger(base) {
+  const levels = ["trace", "debug", "info", "warn", "error", "fatal"];
+
+  const normalizeArg = (a) =>
+    a instanceof Error
+      ? { error: { name: a.name, message: a.message, stack: a.stack } }
+      : a;
+
+  const mergeArgs = (obj, extraArgs) => {
+    if (!extraArgs?.length) return obj;
+    if (obj && typeof obj === "object" && obj._args === undefined) {
+      return { ...obj, _args: extraArgs.map(normalizeArg) };
+    }
+    return {
+      _args: extraArgs.map(normalizeArg),
+      ...(obj && typeof obj === "object" ? obj : {}),
+    };
+  };
+
+  // helper: only attach _args if there’s something beyond a lone string
+  const shouldAttach = (extras) => {
+    if (!extras?.length) return false;
+    if (extras.length === 1 && typeof extras[0] === "string") return false; // <- skip lone string
+    return true; // objects, errors, multiple args, etc.
+  };
+
+  const wrapper = Object.create(base);
+
+  for (const lvl of levels) {
+    const fn = base[lvl];
+    wrapper[lvl] = function (...args) {
+      if (!args.length) return fn.call(base);
+
+      // Case 1: first arg is an object (Pino-style: logger.info(obj, msg, ...rest))
+      if (typeof args[0] === "object" && args[0] !== null) {
+        const [obj, msg, ...rest] = args;
+        const extras = [msg, ...rest].filter((x) => x !== undefined);
+
+        if (shouldAttach(extras)) {
+          const merged = mergeArgs(obj, extras);
+          return fn.call(base, merged, msg);
+        } else {
+          // just pass through without _args
+          return fn.call(base, obj, msg);
+        }
+      }
+
+      // Case 2: first arg is not an object (logger.info(msg, ...rest))
+      const [msg, ...rest] = args;
+
+      // lone string -> no _args
+      if (rest.length === 0 && typeof msg === "string") {
+        return fn.call(base, msg);
+      }
+
+      const extras = [msg, ...rest];
+      if (shouldAttach(extras)) {
+        const merged = mergeArgs({}, extras);
+        return fn.call(base, merged, msg);
+      } else {
+        return fn.call(base, msg);
+      }
+    };
+  }
+
+  return wrapper;
+}
+
+/* ---------------- setupLogger ---------------- */
+export async function setupLogger({ logLevel }) {
+  const env = (process.env.NODE_ENV || "").toLowerCase();
+  const isDev = env === "development" || env === "dev";
+
+  const consoleDest = new Writable({
+    write(chunk, _enc, cb) {
+      try {
+        const obj = JSON.parse(chunk.toString());
+        const level =
+          obj.level >= 50
+            ? "ERROR"
+            : obj.level >= 40
+              ? "WARN"
+              : obj.level >= 30
+                ? "INFO"
+                : "DEBUG";
+
+        console.log(
+          `[${new Date(obj.time).toLocaleTimeString()}] ${level}: ${obj.msg}`,
+        );
+
+        for (let i = 1; i < obj._args?.length; i++) {
+          console.log(
+            `[${new Date(obj.time).toLocaleTimeString()}] ${level}:`,
+            obj._args[i],
+          );
+        }
+      } catch {
+        console.log("Failed to parse log line:");
+        console.log(chunk.toString());
+      }
+      cb();
+    },
+  });
+
+  const streams = [{ stream: consoleDest }];
+
+  const base = pino(
+    {
+      level: logLevel || "info",
+      errorLikeObjectKeys: ["err", "error"],
+      errorProps: "type,message,stack,cause",
+    },
+    pino.multistream(streams),
+  );
+
+  const onSig = async (sig) => {
+    process.kill(process.pid, sig); // default handler runs now
+  };
+
+  process.once("SIGINT", onSig);
+  process.once("SIGTERM", onSig);
+
+  return { logger: wrapLogger(base) };
+}
+
+const _setupLogger = async () => {
+  const result = await setupLogger({
+    logLevel: config.server?.logLevel || "info",
+  });
+
+  logger = result.logger;
+  logger.info("Logger initialized");
+};
+
+export { logger, _setupLogger };

package/src/main.mjs

@@ -0,0 +1,28 @@
+import { _loadConfig } from "./config.mjs";
+import { logger, _setupLogger } from "./logger.mjs";
+import { _setupFunc, bindFunc } from "./bindFunc.mjs";
+
+async function start() {
+  logger.info("Service started");
+
+  setInterval(() => {
+    logger.info("heartbeat");
+  }, 60_000);
+}
+
+async function CreateService(
+  { path = "./config.yml" } = { path: "./config.yml" },
+) {
+  await _loadConfig(path);
+  await _setupLogger();
+  await _setupFunc();
+
+  start().catch((err) => {
+    logger.error("Fatal error:", err);
+    process.exit(1);
+  });
+
+  return bindFunc;
+}
+
+export { CreateService };

package/src/pubsub.mjs

@@ -0,0 +1,251 @@
+import { createClient } from "redis";
+import { assert } from "./assert.mjs";
+import { logger } from "./logger.mjs";
+import { config } from "./config.mjs";
+
+let redisClient = null;
+let redisConnectPromise = null;
+
+async function ensureRedis() {
+  if (redisClient?.isOpen) return redisClient;
+  if (redisConnectPromise) return redisConnectPromise;
+
+  const url = config?.server?.redisUrl || "redis://127.0.0.1:6379";
+
+  redisClient = createClient({
+    url,
+    socket: {
+      reconnectStrategy(retries) {
+        return Math.min(retries * 100, 3000);
+      },
+    },
+  });
+
+  redisClient.on("error", (error) => {
+    logger.error(`redis client error: ${error?.message || error}`);
+  });
+
+  redisClient.on("connect", () => {
+    logger.info(`redis socket connected: ${url}`);
+  });
+
+  redisClient.on("ready", () => {
+    logger.info("redis client ready");
+  });
+
+  redisClient.on("reconnecting", () => {
+    logger.info("redis reconnecting");
+  });
+
+  redisClient.on("end", () => {
+    logger.info("redis connection ended");
+  });
+
+  redisConnectPromise = redisClient
+    .connect()
+    .then(() => redisClient)
+    .catch((error) => {
+      redisClient = null;
+      throw error;
+    })
+    .finally(() => {
+      redisConnectPromise = null;
+    });
+
+  return redisConnectPromise;
+}
+
+async function publish(topic, payload) {
+  assert(typeof topic === "string" && topic.trim(), "topic must be a string");
+
+  try {
+    const client = await ensureRedis();
+    const message = JSON.stringify(cleanValue(payload));
+    const receivers = await client.publish(topic, message);
+
+    return {
+      ok: true,
+      topic,
+      receivers,
+    };
+  } catch (error) {
+    logger.error(
+      `error while publishing to redis topic ${topic}: ${error?.message || error}`,
+    );
+    throw error;
+  }
+}
+
+async function subscribe(topic, onMessage, onError) {
+  assert(typeof topic === "string" && topic.trim(), "topic must be a string");
+  assert(typeof onMessage === "function", "onMessage must be a function");
+
+  let subscriber = null;
+  let closed = false;
+
+  try {
+    const client = await ensureRedis();
+
+    subscriber = client.duplicate();
+
+    subscriber.on("error", (error) => {
+      logger.error(
+        `redis subscriber error on topic ${topic}: ${error?.message || error}`,
+      );
+      onError?.(error);
+    });
+
+    subscriber.on("connect", () => {
+      logger.info(`redis subscriber connected: ${topic}`);
+    });
+
+    subscriber.on("ready", () => {
+      logger.info(`redis subscriber ready: ${topic}`);
+    });
+
+    subscriber.on("reconnecting", () => {
+      logger.info(`redis subscriber reconnecting: ${topic}`);
+    });
+
+    subscriber.on("end", () => {
+      logger.info(`redis subscriber ended: ${topic}`);
+    });
+
+    await subscriber.connect();
+
+    await subscriber.subscribe(topic, async (rawMessage, channel) => {
+      if (closed) return;
+
+      try {
+        let message = rawMessage;
+
+        try {
+          message = JSON.parse(rawMessage);
+        } catch {}
+
+        await onMessage(message, {
+          topic: channel,
+          rawMessage,
+        });
+      } catch (error) {
+        onError?.(error);
+      }
+    });
+
+    return {
+      topic,
+      async close() {
+        closed = true;
+
+        try {
+          if (subscriber?.isOpen) {
+            await subscriber.unsubscribe(topic);
+            await subscriber.quit();
+          } else if (subscriber) {
+            subscriber.disconnect();
+          }
+        } catch (error) {
+          onError?.(error);
+          try {
+            subscriber?.disconnect();
+          } catch {}
+        }
+      },
+    };
+  } catch (error) {
+    logger.error(
+      `error while subscribing to redis topic ${topic}: ${error?.message || error}`,
+    );
+    onError?.(error);
+
+    try {
+      if (subscriber?.isOpen) {
+        await subscriber.quit();
+      } else if (subscriber) {
+        subscriber.disconnect();
+      }
+    } catch {}
+
+    return null;
+  }
+}
+
+async function closeRedis() {
+  try {
+    if (redisClient?.isOpen) {
+      await redisClient.quit();
+    } else if (redisClient) {
+      redisClient.disconnect();
+    }
+  } catch (error) {
+    logger.error(`error while closing redis: ${error?.message || error}`);
+    try {
+      redisClient?.disconnect();
+    } catch {}
+  } finally {
+    redisClient = null;
+    redisConnectPromise = null;
+  }
+}
+
+function cleanValue(value, seen = new WeakSet()) {
+  if (value && typeof value === "object") {
+    if (seen.has(value)) return undefined;
+    seen.add(value);
+  }
+
+  if (value === null || typeof value !== "object") return value;
+
+  if (value instanceof Date) return value.toISOString();
+
+  if (Buffer.isBuffer(value)) {
+    return value.toString("base64");
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((v) => cleanValue(v, seen)).filter((v) => v !== undefined);
+  }
+
+  if (value instanceof Map) {
+    return Object.fromEntries(
+      [...value.entries()]
+        .map(([k, v]) => [String(k), cleanValue(v, seen)])
+        .filter(([, v]) => v !== undefined),
+    );
+  }
+
+  if (value instanceof Set) {
+    return [...value]
+      .map((v) => cleanValue(v, seen))
+      .filter((v) => v !== undefined);
+  }
+
+  if (value instanceof Error) {
+    return {
+      name: value.name,
+      message: value.message,
+      stack: value.stack,
+    };
+  }
+
+  if (value.constructor && value.constructor !== Object) {
+    return undefined;
+  }
+
+  const out = {};
+  for (const [key, val] of Object.entries(value)) {
+    if (typeof val === "function" || typeof val === "symbol") continue;
+
+    const cleaned = cleanValue(val, seen);
+    if (cleaned !== undefined) out[key] = cleaned;
+  }
+
+  return out;
+}
+
+export {
+  ensureRedis,
+  publish,
+  subscribe,
+  closeRedis,
+};

package/src/service.mjs

@@ -0,0 +1,60 @@
+import http from "http";
+import https from "https";
+import { CookieJar } from "tough-cookie";
+import got from "got";
+
+/* ============================== HTTP ============================== */
+// ---- Shared HTTP agents (reused across all clients) ----
+const SHARED_HTTP_AGENT = new http.Agent({
+  keepAlive: true,
+  maxSockets: 200,
+  maxFreeSockets: 50,
+});
+const SHARED_HTTPS_AGENT = new https.Agent({
+  keepAlive: true,
+  maxSockets: 200,
+  maxFreeSockets: 50,
+});
+
+/* ---------------------------------- HTTP ---------------------------------- */
+function createGotInstance(baseURL, { cookieJar, headers, timeout } = {}) {
+  const options = {
+    prefixUrl: baseURL,
+    agent: { http: SHARED_HTTP_AGENT, https: SHARED_HTTPS_AGENT },
+    timeout: timeout || { request: 60000, connect: 5000 },
+    decompress: true,
+    http2: false,
+    headers: { accept: "application/json, */*;q=0.8", ...(headers || {}) },
+    retry: { limit: 0 }, // disable got retries; let callers decide
+  };
+  if (cookieJar instanceof CookieJar) options.cookieJar = cookieJar;
+  return got.extend(options);
+}
+
+const _services = new Map();
+const _normBase = (u) =>
+  String(u).endsWith("/") ? String(u) : String(u) + "/";
+function getService(serviceUrl) {
+  const key = _normBase(serviceUrl);
+  if (!_services.has(key)) _services.set(key, createGotInstance(key));
+  return _services.get(key);
+}
+
+function getHttpAgentCount() {
+  return {
+    active: Object.fromEntries(
+      Object.entries(SHARED_HTTP_AGENT.sockets).map(([k, v]) => [k, v.length])
+    ),
+    idle: Object.fromEntries(
+      Object.entries(SHARED_HTTP_AGENT.freeSockets).map(([k, v]) => [
+        k,
+        v.length,
+      ])
+    ),
+    queued: Object.fromEntries(
+      Object.entries(SHARED_HTTP_AGENT.requests).map(([k, v]) => [k, v.length])
+    ),
+  };
+}
+
+export { getService, getHttpAgentCount };

package/src/states.mjs

@@ -0,0 +1,423 @@
+import { createClient } from "redis";
+import { assert } from "./assert.mjs";
+import { logger } from "./logger.mjs";
+import { config } from "./config.mjs";
+
+let redisClient = null;
+let redisConnectPromise = null;
+let REDIS_KEY = null;
+let REDIS_CHANNEL = null;
+
+function init() {
+  const appName = config?.server?.appName || "APP";
+  REDIS_KEY = `__STATE_${appName}`;
+  REDIS_CHANNEL = `__STATE_CHANNEL_${appName}`;
+}
+
+function assertInitialized() {
+  assert(REDIS_KEY, "Redis state module not initialized. Call init() first.");
+  assert(
+    REDIS_CHANNEL,
+    "Redis state module not initialized. Call init() first.",
+  );
+}
+
+async function ensureRedis() {
+  assertInitialized();
+
+  if (redisClient?.isOpen) return redisClient;
+  if (redisConnectPromise) return redisConnectPromise;
+
+  const url = config?.server?.redisUrl || "redis://127.0.0.1:6379";
+
+  redisClient = createClient({
+    url,
+    socket: {
+      reconnectStrategy(retries) {
+        return Math.min(retries * 100, 3000);
+      },
+    },
+  });
+
+  redisClient.on("error", (error) => {
+    logger.error(`redis client error: ${error?.message || error}`);
+  });
+
+  redisClient.on("connect", () => {
+    logger.info(`redis socket connected: ${url}`);
+  });
+
+  redisClient.on("ready", () => {
+    logger.info("redis client ready");
+  });
+
+  redisClient.on("reconnecting", () => {
+    logger.info("redis reconnecting");
+  });
+
+  redisClient.on("end", () => {
+    logger.info("redis connection ended");
+  });
+
+  redisConnectPromise = redisClient
+    .connect()
+    .then(() => redisClient)
+    .catch((error) => {
+      redisClient = null;
+      throw error;
+    })
+    .finally(() => {
+      redisConnectPromise = null;
+    });
+
+  return redisConnectPromise;
+}
+
+async function subscribeState(
+  computeName,
+  onStateChange,
+  onError,
+  stateFilter = {},
+) {
+  assertInitialized();
+
+  let subscriber = null;
+  let closed = false;
+
+  try {
+    const client = await ensureRedis();
+
+    subscriber = client.duplicate();
+
+    subscriber.on("error", (error) => {
+      logger.error(`redis subscriber error: ${error?.message || error}`);
+      onError?.(error);
+    });
+
+    subscriber.on("connect", () => {
+      logger.info(`redis subscriber connected: ${REDIS_CHANNEL}`);
+    });
+
+    subscriber.on("ready", () => {
+      logger.info(`redis subscriber ready: ${REDIS_CHANNEL}`);
+    });
+
+    subscriber.on("end", () => {
+      logger.info(`redis subscriber ended: ${REDIS_CHANNEL}`);
+    });
+
+    await subscriber.connect();
+
+    const triggerRead = async () => {
+      if (closed) return;
+
+      try {
+        const state = await loadState();
+
+        if (matchesFilter(state, stateFilter)) {
+          await onStateChange?.(state, {
+            computeName,
+            source: "redis-json",
+            key: REDIS_KEY,
+            channel: REDIS_CHANNEL,
+          });
+        }
+      } catch (error) {
+        onError?.(error);
+      }
+    };
+
+    await triggerRead();
+
+    await subscriber.subscribe(REDIS_CHANNEL, async () => {
+      if (closed) return;
+
+      try {
+        await triggerRead();
+      } catch (error) {
+        onError?.(error);
+      }
+    });
+
+    return {
+      async close() {
+        closed = true;
+
+        try {
+          if (subscriber?.isOpen) {
+            await subscriber.unsubscribe(REDIS_CHANNEL);
+            await subscriber.quit();
+          } else if (subscriber) {
+            subscriber.disconnect();
+          }
+        } catch (error) {
+          onError?.(error);
+          try {
+            subscriber?.disconnect();
+          } catch {}
+        }
+      },
+    };
+  } catch (error) {
+    logger.error(
+      `error while subscribing state from redis: ${error?.message || error}`,
+    );
+    onError?.(error);
+
+    try {
+      if (subscriber?.isOpen) {
+        await subscriber.quit();
+      } else if (subscriber) {
+        subscriber.disconnect();
+      }
+    } catch {}
+
+    return null;
+  }
+}
+
+async function loadState() {
+  assertInitialized();
+
+  try {
+    const client = await ensureRedis();
+
+    const state = await client.json.get(REDIS_KEY, {
+      path: "$",
+    });
+
+    if (state == null) return {};
+
+    if (Array.isArray(state)) {
+      return state[0] ?? {};
+    }
+
+    return state;
+  } catch (error) {
+    logger.error(
+      `error while loading state from redis json: ${error?.message || error}`,
+    );
+    return {};
+  }
+}
+
+async function saveState(STATE) {
+  assertInitialized();
+  assert(STATE && typeof STATE === "object", "STATE must be an object");
+
+  const cleaned = cleanState(STATE);
+
+  try {
+    const client = await ensureRedis();
+
+    await client.json.set(REDIS_KEY, "$", cleaned ?? {});
+
+    await publishStateChange(client, {
+      key: REDIS_KEY,
+      updatedAt: Date.now(),
+      mode: "save",
+    });
+  } catch (error) {
+    logger.error(
+      `error while saving state to redis json: ${error?.message || error}`,
+    );
+    throw error;
+  }
+}
+
+async function updateState(path, value, publish = true) {
+  assertInitialized();
+  assert(typeof path === "string" && path.trim(), "path must be a string");
+
+  const cleaned = cleanState(value);
+  const normalizedPath = normalizePath(path);
+
+  try {
+    const client = await ensureRedis();
+
+    let state = await loadState();
+
+    if (!state || typeof state !== "object" || Array.isArray(state)) {
+      state = {};
+    }
+
+    setByPath(state, normalizedPath, cleaned);
+
+    await client.json.set(REDIS_KEY, "$", state);
+
+    if (publish) {
+      await publishStateChange(client, {
+        key: REDIS_KEY,
+        path: toRedisJsonPath(normalizedPath),
+        updatedAt: Date.now(),
+        mode: "update",
+      });
+    }
+  } catch (error) {
+    logger.error(
+      `error while updating state in redis json: ${error?.message || error}`,
+    );
+    throw error;
+  }
+}
+
+async function getStatePath(path) {
+  assertInitialized();
+  assert(typeof path === "string" && path.trim(), "path must be a string");
+
+  try {
+    const state = await loadState();
+    return getByPath(state, normalizePath(path));
+  } catch (error) {
+    logger.error(
+      `error while getting state path from redis json: ${error?.message || error}`,
+    );
+    return undefined;
+  }
+}
+
+async function closeRedis() {
+  try {
+    if (redisClient?.isOpen) {
+      await redisClient.quit();
+    } else if (redisClient) {
+      redisClient.disconnect();
+    }
+  } catch (error) {
+    logger.error(`error while closing redis: ${error?.message || error}`);
+    try {
+      redisClient?.disconnect();
+    } catch {}
+  } finally {
+    redisClient = null;
+    redisConnectPromise = null;
+  }
+}
+
+async function publishStateChange(client, payload) {
+  await client.publish(REDIS_CHANNEL, JSON.stringify(payload));
+}
+
+function toRedisJsonPath(path) {
+  const normalized = normalizePath(path);
+  if (!normalized) return "$";
+  return `$.${normalized}`;
+}
+
+function normalizePath(path) {
+  const trimmed = String(path).trim();
+
+  if (!trimmed || trimmed === "$") return "";
+  if (trimmed.startsWith("$.")) return trimmed.slice(2);
+  if (trimmed.startsWith("$")) return trimmed.slice(1).replace(/^\./, "");
+
+  return trimmed;
+}
+
+function getByPath(obj, path) {
+  const normalized = normalizePath(path);
+  if (!normalized) return obj;
+
+  return normalized.split(".").reduce((acc, key) => acc?.[key], obj);
+}
+
+function setByPath(obj, path, value) {
+  const normalized = normalizePath(path);
+  if (!normalized) return value;
+
+  const parts = normalized.split(".");
+  let curr = obj;
+
+  for (let i = 0; i < parts.length - 1; i += 1) {
+    const key = parts[i];
+
+    if (
+      curr[key] === undefined ||
+      curr[key] === null ||
+      typeof curr[key] !== "object" ||
+      Array.isArray(curr[key])
+    ) {
+      curr[key] = {};
+    }
+
+    curr = curr[key];
+  }
+
+  curr[parts[parts.length - 1]] = value;
+  return obj;
+}
+
+function cleanState(value, seen = new WeakSet()) {
+  if (value && typeof value === "object") {
+    if (seen.has(value)) return undefined;
+    seen.add(value);
+  }
+
+  if (value === null || typeof value !== "object") return value;
+
+  if (value instanceof Date) return value.toISOString();
+
+  if (Buffer.isBuffer(value)) {
+    return value.toString("base64");
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((v) => cleanState(v, seen)).filter((v) => v !== undefined);
+  }
+
+  if (value instanceof Map) {
+    return Object.fromEntries(
+      [...value.entries()]
+        .map(([k, v]) => [String(k), cleanState(v, seen)])
+        .filter(([, v]) => v !== undefined),
+    );
+  }
+
+  if (value instanceof Set) {
+    return [...value]
+      .map((v) => cleanState(v, seen))
+      .filter((v) => v !== undefined);
+  }
+
+  if (value instanceof Error) {
+    return {
+      name: value.name,
+      message: value.message,
+      stack: value.stack,
+    };
+  }
+
+  if (value.constructor && value.constructor !== Object) {
+    return undefined;
+  }
+
+  const out = {};
+  for (const [key, val] of Object.entries(value)) {
+    if (typeof val === "function" || typeof val === "symbol") continue;
+
+    const cleaned = cleanState(val, seen);
+    if (cleaned !== undefined) out[key] = cleaned;
+  }
+
+  return out;
+}
+
+function matchesFilter(state, filter) {
+  if (!filter || typeof filter !== "object") return true;
+
+  for (const [key, expected] of Object.entries(filter)) {
+    if (getByPath(state, key) !== expected) return false;
+  }
+
+  return true;
+}
+
+export {
+  init,
+  loadState,
+  saveState,
+  updateState,
+  getStatePath,
+  subscribeState,
+  closeRedis,
+};