@devindex/api-kit 0.1.0

package/jobs/index.js

@@ -0,0 +1,156 @@
+import { noopLogger } from '../internal/logger.js';
+import {
+  assertDuration,
+  assertHandler,
+  assertKey,
+  assertName,
+} from '../internal/validation.js';
+import {
+  DEFAULTS,
+  dedupId,
+  normalizeBackoff,
+  resolveDefinition,
+} from '../internal/retry.js';
+import { memoryBackend } from './drivers/memory.js';
+import { bullmqBackend } from './drivers/bullmq.js';
+
+// Named for what runs the jobs, not for its store: the distributed backend is
+// BullMQ (Redis is only where it keeps state), so the semantics a caller gets —
+// stalled recovery, deduplication, retention — are BullMQ's, and the name says so.
+const BACKENDS = { memory: memoryBackend, bullmq: bullmqBackend };
+
+/**
+ * Creates a volatile local queue or a distributed BullMQ queue.
+ *
+ * The lifecycle — declaration, dedup keys, state — lives here; each backend only
+ * add()s, work()s and stop()s. enqueue() needs neither define() nor start(), so a
+ * producer-only process dispatches by name without running a worker.
+ *
+ * @param {object} [options]
+ * @param {'memory'|'bullmq'} [options.driver='memory']
+ * @param {string} [options.redisUrl] - Required by the BullMQ driver.
+ * @param {string} [options.prefix='app']
+ * @param {object} [options.logger]
+ * @param {object} [options.defaults] - `attempts`, `backoff`, `concurrency`.
+ * @return {object} The queue: define, enqueue, start, stop, idle and state.
+ */
+export function createJobQueue({
+  driver = 'memory',
+  redisUrl,
+  prefix = 'app',
+  logger = noopLogger,
+  defaults = {},
+} = {}) {
+  const createBackend = BACKENDS[driver];
+  if (!createBackend) {
+    throw new Error(`unknown job driver "${driver}", expected ${Object.keys(BACKENDS).join(' or ')}`);
+  }
+  const merged = Object.freeze({
+    attempts: defaults.attempts ?? DEFAULTS.attempts,
+    backoff: normalizeBackoff(defaults.backoff ?? DEFAULTS.backoff),
+    concurrency: defaults.concurrency ?? DEFAULTS.concurrency,
+  });
+
+  const definitions = new Map();
+  const backend = createBackend({ redisUrl, prefix, logger });
+  let state = 'idle';
+
+  /**
+   * Declares a job before start(); the name must be unique.
+   *
+   * @param {string} name
+   * @param {(payload: *, context: object) => (void|Promise<void>)} handler
+   * @param {object} [options] - Per-job overrides: `attempts`, `backoff`, `concurrency`.
+   * @return {void}
+   */
+  function define(name, handler, options = {}) {
+    if (state !== 'idle') throw new Error('jobs must be declared before start()');
+    const jobName = assertName(name);
+    assertHandler(jobName, handler);
+    if (definitions.has(jobName)) throw new Error(`job "${jobName}" is already declared`);
+    definitions.set(jobName, { handler, ...resolveDefinition(merged, options) });
+  }
+
+  /**
+   * Enqueues a job by name; the name need not be declared in this process.
+   *
+   * @param {string} name
+   * @param {*} payload - Passed to the handler as its first argument.
+   * @param {object} options
+   * @param {string} options.key - Required, non-empty idempotency key.
+   * @param {number} [options.delay=0] - Milliseconds before the job becomes runnable.
+   * @return {Promise<{jobId: string, name: string, key: string}>}
+   */
+  async function enqueue(name, payload, { key: givenKey, delay = 0 } = {}) {
+    // No define()/start() required: a producer-only process enqueues by name.
+    if (state === 'stopping' || state === 'stopped') {
+      throw new Error('cannot enqueue on a stopped job queue');
+    }
+    const jobName = assertName(name);
+    const key = assertKey(givenKey);
+    assertDuration('delay', delay);
+    // A producer that never declared the job takes its retry policy from
+    // `defaults`; per-job overrides live on the consumer's define().
+    const policy = definitions.get(jobName) ?? merged;
+    const jobId = await backend.add(jobName, payload, {
+      key,
+      dedupId: dedupId(jobName, key),
+      attempts: policy.attempts,
+      backoff: policy.backoff,
+      delay,
+    });
+    return Object.freeze({ jobId, name: jobName, key });
+  }
+
+  async function start() {
+    if (state === 'started') return;
+    if (state === 'stopped') throw new Error('a stopped job queue cannot be restarted');
+    if (state !== 'idle') throw new Error('the job queue is already changing state');
+    state = 'starting';
+    // allSettled lets every worker register before a failure surfaces, so a
+    // rejection mid-start can't leak the workers its siblings already created.
+    const results = await Promise.allSettled(
+      [...definitions].map(([name, definition]) => backend.work(name, definition)),
+    );
+    const failed = results.find((result) => result.status === 'rejected');
+    if (failed) {
+      state = 'stopping';
+      await backend.stop({});
+      state = 'stopped';
+      throw failed.reason;
+    }
+    state = 'started';
+  }
+
+  /**
+   * Stops intake and drains in-flight jobs.
+   *
+   * @param {object} [options]
+   * @param {number} [options.timeoutMs=30000] - Drain deadline before abandoning
+   *   in-flight jobs (memory driver; the BullMQ driver lets BullMQ own the deadline).
+   * @return {Promise<void>}
+   */
+  async function stop(options = {}) {
+    if (state === 'stopped') return;
+    state = 'stopping';
+    await backend.stop(options);
+    state = 'stopped';
+  }
+
+  /** Resolves once nothing is delayed, queued or running. */
+  function idle() {
+    return backend.idle();
+  }
+
+  return Object.freeze({
+    driver,
+    define,
+    enqueue,
+    start,
+    stop,
+    idle,
+    get state() {
+      return state;
+    },
+  });
+}

package/log/index.js

@@ -0,0 +1,161 @@
+import pino from 'pino';
+import { cleanStack } from '../errors/stack.js';
+
+// Wraps pino's std err serializer so every `{ err }` log line carries
+// repo-relative frames instead of absolute, machine-specific paths. The cause
+// chain the std serializer attaches is cleaned too.
+function errSerializer(error) {
+  const serialized = pino.stdSerializers.err(error);
+  if (serialized?.stack) serialized.stack = cleanStack(serialized.stack);
+  if (serialized?.cause?.stack) serialized.cause.stack = cleanStack(serialized.cause.stack);
+  return serialized;
+}
+
+// Redaction is configured once, at logger creation — never at the call site.
+//
+// pino's `*` matches exactly one level, so a key has to be listed per depth.
+// Three tiers cover `{ password }`, `{ body: { password } }` and
+// `{ req: { body: { password } } }` — the shapes a handler actually logs.
+const SECRET_KEYS = [
+  'password',
+  'passwordHash',
+  'token',
+  'tokenHash',
+  'accessToken',
+  'refreshToken',
+  'secret',
+  'apiKey',
+  'authorization',
+  'cookie',
+];
+
+export const DEFAULT_REDACT_PATHS = Object.freeze(
+  SECRET_KEYS.flatMap((key) => [key, `*.${key}`, `*.*.${key}`]),
+);
+
+/**
+ * Closed vocabulary for the `type` field, the discriminator that lets a log
+ * store split request, event, job and integration lines apart after the fact.
+ */
+export const LOG_TYPE = Object.freeze({
+  REQUEST: 'request',
+  EVENT: 'event',
+  JOB: 'job',
+  SCHEDULE: 'schedule',
+  INTEGRATION: 'integration',
+  LIFECYCLE: 'lifecycle',
+});
+
+/**
+ * Whether `pino-pretty` can be loaded, so a `pretty` request degrades to JSON
+ * instead of throwing when the optional peer is absent.
+ *
+ * @return {boolean}
+ */
+export function prettyAvailable() {
+  try {
+    import.meta.resolve('pino-pretty');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Builds the pino transport for human-readable output, or `undefined` for the
+ * JSON default. Exported so it can be asserted without spawning a worker thread.
+ *
+ * @param {boolean|object} [pretty=false] - `true` for the defaults, or pino-pretty options to merge.
+ * @return {object|undefined} A pino `transport` option, or undefined.
+ */
+export function prettyTransport(pretty = false) {
+  if (!pretty) return undefined;
+  return {
+    target: 'pino-pretty',
+    options: {
+      translateTime: 'HH:MM:ss.l',
+      ignore: 'pid,hostname',
+      ...(pretty === true ? {} : pretty),
+    },
+  };
+}
+
+/**
+ * Creates the process logger. Everything that shapes it arrives as data — the
+ * level, where it writes and which transport carries the lines are the app's
+ * decisions, not the environment's.
+ *
+ * @param {object} [options]
+ * @param {string} [options.level='info'] - pino level.
+ * @param {readonly string[]} [options.redact] - Paths to censor. Defaults to `DEFAULT_REDACT_PATHS`.
+ * @param {string} [options.censor='[redacted]'] - Replacement for redacted values.
+ * @param {object} [options.transport] - A pino `transport` (single `{target}` or `{targets:[…]}`). Wins over `pretty`.
+ * @param {boolean|object} [options.pretty=false] - Convenience `pino-pretty` transport; needs the optional peer. Ignored when `transport` is set.
+ * @param {object} [options.base] - Bindings on every line. Omitted leaves pino's default.
+ * @param {import('node:stream').Writable} [options.destination] - Where to write. Cannot combine with a transport.
+ * @param {{get: Function}} [options.context] - A context store; its fields ride on every line as a mixin.
+ * @param {object} [options.serializers] - Merged over the default `err` serializer.
+ * @param {object} [options.pinoOptions] - Escape hatch, merged last.
+ * @return {import('pino').Logger} The logger.
+ */
+export function createLogger({
+  level = 'info',
+  redact = DEFAULT_REDACT_PATHS,
+  censor = '[redacted]',
+  transport,
+  pretty = false,
+  base,
+  destination,
+  context,
+  serializers,
+  pinoOptions = {},
+} = {}) {
+  // An explicit transport is the caller's to get right; the `pretty` convenience
+  // degrades to JSON when its optional peer is missing instead of crashing.
+  const activeTransport = transport ?? (pretty && prettyAvailable() ? prettyTransport(pretty) : undefined);
+
+  // pino writes a transport from a worker thread and a `destination` from the
+  // main one; wiring both leaves two sinks fighting over the same logger.
+  if (activeTransport && destination) {
+    throw new Error('createLogger: a transport (including `pretty`) cannot combine with `destination`');
+  }
+
+  const paths = [...redact];
+  const { mixin: applicationMixin, ...remainingPinoOptions } = pinoOptions;
+
+  // The context store's fields (requestId, correlationId) ride on every line so
+  // a correlation id survives into the log without the call site repeating it.
+  const mixin = context || applicationMixin
+    ? (...args) => ({
+        ...(context?.get() ?? {}),
+        ...(applicationMixin?.(...args) ?? {}),
+      })
+    : undefined;
+
+  const options = {
+    level,
+    ...(paths.length > 0 ? { redact: { paths, censor } } : {}),
+    ...(base === undefined ? {} : { base }),
+    // `{ err }` is the shape the kit's error handler logs; the serializer turns
+    // it into type/message/stack, with paths relativized to the cwd.
+    serializers: { err: errSerializer, ...serializers },
+    ...(activeTransport ? { transport: activeTransport } : {}),
+    ...(mixin ? { mixin } : {}),
+    ...remainingPinoOptions,
+  };
+
+  return destination ? pino(options, destination) : pino(options);
+}
+
+/**
+ * Stamps a category (and optional bindings) onto a child logger, so every line
+ * from that scope carries the same `type` for later filtering.
+ *
+ * @param {import('pino').Logger} logger
+ * @param {string} type - One of `LOG_TYPE`.
+ * @param {object} [bindings] - Extra fields fixed on the child, e.g. `{ jobName }`.
+ * @return {import('pino').Logger} The child logger.
+ */
+export function withType(logger, type, bindings = {}) {
+  return logger.child({ type, ...bindings });
+}

package/package.json

@@ -0,0 +1,110 @@
+{
+  "name": "@devindex/api-kit",
+  "version": "0.1.0",
+  "description": "Building blocks for Fastify services: typed domain errors, HTTP plugins, logging and background runtime",
+  "type": "module",
+  "exports": {
+    "./context": "./context/index.js",
+    "./errors": "./errors/index.js",
+    "./events": "./events/index.js",
+    "./http": "./http/index.js",
+    "./jobs": "./jobs/index.js",
+    "./log": "./log/index.js",
+    "./schedule": "./schedule/index.js",
+    "./runtime": "./runtime/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "context",
+    "errors",
+    "events",
+    "http",
+    "internal",
+    "jobs",
+    "log",
+    "runtime",
+    "schedule"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "test": "node --test \"tests/*.test.js\"",
+    "test:redis": "REQUIRE_REDIS=1 node --test \"tests/*.test.js\""
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/devindex/packages.git",
+    "directory": "packages/api-kit"
+  },
+  "keywords": [
+    "fastify",
+    "api",
+    "backend",
+    "errors",
+    "jobs",
+    "bullmq",
+    "cron",
+    "schedule",
+    "events",
+    "event-bus",
+    "pubsub"
+  ],
+  "peerDependencies": {
+    "@fastify/cors": "^11.0.0",
+    "@fastify/helmet": "^13.0.0",
+    "bullmq": "^6.0.8",
+    "croner": "^10.0.1",
+    "fastify": "^5.11.0",
+    "fastify-plugin": "^6.0.0",
+    "ioredis": "^5.7.0",
+    "pino": "^10.0.0",
+    "pino-pretty": "^13.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@fastify/cors": {
+      "optional": true
+    },
+    "@fastify/helmet": {
+      "optional": true
+    },
+    "bullmq": {
+      "optional": true
+    },
+    "croner": {
+      "optional": true
+    },
+    "fastify": {
+      "optional": true
+    },
+    "fastify-plugin": {
+      "optional": true
+    },
+    "ioredis": {
+      "optional": true
+    },
+    "pino": {
+      "optional": true
+    },
+    "pino-pretty": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@fastify/cors": "^11.0.0",
+    "@fastify/helmet": "^13.0.0",
+    "bullmq": "^6.0.8",
+    "croner": "^10.0.1",
+    "fastify": "^5.11.0",
+    "fastify-plugin": "^6.0.0",
+    "ioredis": "^5.7.0",
+    "pino": "^10.0.0",
+    "pino-pretty": "^13.0.0"
+  },
+  "author": "Sergio Rodrigues <exprodrigues@gmail.com>",
+  "bugs": {
+    "url": "https://github.com/devindex/packages/issues"
+  },
+  "homepage": "https://github.com/devindex/packages/tree/main/packages/api-kit#readme",
+  "license": "MIT"
+}

package/runtime/index.js

@@ -0,0 +1,37 @@
+/**
+ * Runs `close` once on the first termination signal, then exits the process.
+ *
+ * @param {(signal: string) => (void | Promise<void>)} close - The teardown to run.
+ * @param {object} [options]
+ * @param {string[]} [options.signals=['SIGINT','SIGTERM']] - Signals that trigger it.
+ * @param {number} [options.timeoutMs=10000] - Hard deadline; a hung `close` force-exits with 1.
+ * @param {{ error: Function }} [options.logger] - Logs the failure before exiting with 1.
+ */
+export function onShutdown(close, { signals = ['SIGINT', 'SIGTERM'], timeoutMs = 10_000, logger } = {}) {
+  let running = false;
+
+  const handle = async (signal) => {
+    // A second signal mid-drain must not run `close` twice.
+    if (running) return;
+    running = true;
+
+    // Don't unref this timer: a hung `close` that stops pinning the event loop
+    // would then let the process exit 0, reporting success for a failed shutdown.
+    const deadline = setTimeout(() => process.exit(1), timeoutMs);
+
+    try {
+      await close(signal);
+      clearTimeout(deadline);
+      process.exit(0);
+    } catch (error) {
+      clearTimeout(deadline);
+      logger?.error({ err: error }, 'shutdown failed');
+      process.exit(1);
+    }
+  };
+
+  // Wiring the signal is all this owns; teardown order stays inside `close`.
+  for (const signal of signals) {
+    process.once(signal, () => handle(signal));
+  }
+}

package/schedule/drivers/bullmq.js

@@ -0,0 +1,127 @@
+import {
+  loadBullmq,
+  queueName,
+  redisConnection,
+} from '../../internal/bullmq.js';
+import { noopLogger } from '../../internal/logger.js';
+
+const SCHEDULER_ID = 'schedule';
+
+/**
+ * Distributed backend on BullMQ's Job Scheduler, one queue per schedule name.
+ * Every replica upserts the same leaderless scheduler and starts an equivalent
+ * worker; BullMQ coordinates which worker receives each occurrence. Redis is only
+ * its store.
+ *
+ * @param {object} options
+ * @param {string} options.redisUrl
+ * @param {string} [options.prefix='app']
+ * @param {object} [options.logger]
+ * @return {object} A backend: schedule, unschedule and stop.
+ */
+export function bullmqBackend({ redisUrl, prefix = 'app', logger = noopLogger } = {}) {
+  const queueConnection = redisConnection(redisUrl);
+  const workerConnection = redisConnection(redisUrl, { worker: true });
+  const queuePromises = new Map();
+  const workers = new Map();
+
+  /** Get or create the per-name schedule queue: single attempt, small retention. */
+  function getQueue(name) {
+    let promise = queuePromises.get(name);
+    if (!promise) {
+      promise = (async () => {
+        const { Queue } = await loadBullmq();
+        return new Queue(queueName(prefix, 'schedule', name), {
+          connection: queueConnection,
+          defaultJobOptions: {
+            attempts: 1,
+            removeOnComplete: { age: 24 * 60 * 60, count: 100 },
+            removeOnFail: { age: 7 * 24 * 60 * 60 },
+          },
+        });
+      })();
+      queuePromises.set(name, promise);
+    }
+    return promise;
+  }
+
+  /** Remove the shared Job Scheduler from every queue this replica opened. */
+  async function removeAllSchedulers() {
+    await Promise.allSettled([...queuePromises.values()].map(async (queuePromise) => {
+      const queue = await queuePromise;
+      await queue.removeJobScheduler(SCHEDULER_ID);
+    }));
+  }
+
+  /** Close every worker and queue this replica opened, logging each failure. */
+  async function closeResources() {
+    for (const worker of workers.values()) worker.cancelAllJobs(new Error('schedule is stopping'));
+    const workerResults = await Promise.allSettled([...workers.values()].map((worker) => worker.close()));
+    const queueResults = await Promise.allSettled([...queuePromises.values()]);
+    const closeResults = await Promise.allSettled(
+      queueResults.flatMap((result) => (result.status === 'fulfilled' ? [result.value.close()] : [])),
+    );
+    for (const result of [...workerResults, ...queueResults, ...closeResults]) {
+      if (result.status === 'rejected') logger.error({ err: result.reason }, 'schedule close failed');
+    }
+    workers.clear();
+    queuePromises.clear();
+  }
+
+  return {
+    /** Start a worker and upsert the leaderless Job Scheduler for one schedule. */
+    async schedule(name, definition) {
+      const { Worker } = await loadBullmq();
+      const queue = await getQueue(name);
+      await queue.setGlobalConcurrency(1);
+      const worker = new Worker(queue.name, async (job, _token, signal) => {
+        if (job.name !== name) throw new Error(`schedule "${job.name}" reached the worker for "${name}"`);
+        const log = logger.child({ schedule: name, runId: job.id });
+        try {
+          return await definition.handler({ name, signal, log });
+        } catch (error) {
+          logger.error({ err: error, schedule: name, runId: job.id }, 'schedule failed');
+          throw error;
+        }
+      }, { connection: workerConnection, concurrency: 1 });
+      workers.set(name, worker);
+      worker.on('error', (error) => logger.error({ err: error, schedule: name }, 'schedule worker error'));
+      worker.on('stalled', (jobId) => {
+        logger.error({ schedule: name, runId: jobId }, 'schedule stalled and will be delivered again');
+      });
+      await worker.waitUntilReady();
+      await queue.upsertJobScheduler(
+        SCHEDULER_ID,
+        { pattern: definition.spec.pattern, tz: definition.spec.timeZone },
+        { name, data: {} },
+      );
+    },
+
+    /** Remove one schedule's Job Scheduler and close its local worker and queue. */
+    async unschedule(name) {
+      // Before start() (or after stop()) nothing exists in Redis yet, so dropping
+      // the declaration is enough — this mirrors the memory backend's inert removal.
+      if (!queuePromises.has(name)) return;
+      const queue = await getQueue(name);
+      await queue.removeJobScheduler(SCHEDULER_ID);
+      const worker = workers.get(name);
+      if (worker) {
+        worker.cancelAllJobs(new Error(`schedule "${name}" was removed`));
+        await worker.close();
+        workers.delete(name);
+      }
+      await queue.close();
+      queuePromises.delete(name);
+    },
+
+    // BullMQ owns the drain deadline once worker.close() starts, so `timeoutMs` is
+    // accepted for a uniform signature but not used here.
+    async stop({ removeSchedulers = false } = {}) {
+      // A failed start owns the schedulers it upserted and removes them, or they
+      // orphan jobs into queues no worker drains; a normal stop leaves the shared
+      // scheduler so other replicas keep it (leaderless).
+      if (removeSchedulers) await removeAllSchedulers();
+      await closeResources();
+    },
+  };
+}

package/schedule/drivers/memory.js

@@ -0,0 +1,59 @@
+import { Cron } from 'croner';
+import { noopLogger } from '../../internal/logger.js';
+
+/**
+ * In-process backend on Croner. Runs each schedule directly in this process,
+ * skipping a tick while its previous run is still active, and keeps nothing once
+ * the process exits.
+ *
+ * @param {object} [options]
+ * @param {object} [options.logger]
+ * @return {object} A backend: schedule, unschedule and stop.
+ */
+export function memoryBackend({ logger = noopLogger } = {}) {
+  const clocks = new Map();
+  const active = new Map();
+
+  /** Run one tick unless the previous run is still active; each run gets its own abort signal. */
+  function run(name, definition) {
+    if (active.has(name)) {
+      logger.warn({ schedule: name }, 'schedule tick skipped because the previous run is active');
+      return;
+    }
+    const controller = new AbortController();
+    const log = logger.child({ schedule: name });
+    const promise = Promise.resolve()
+      .then(() => definition.handler({ name, signal: controller.signal, log }))
+      .catch((error) => logger.error({ err: error, schedule: name }, 'schedule failed'))
+      .finally(() => active.delete(name));
+    active.set(name, { controller, promise });
+  }
+
+  return {
+    /** Start a croner clock that fires run() on each occurrence. */
+    async schedule(name, definition) {
+      const clock = new Cron(
+        definition.spec.pattern,
+        { name, timezone: definition.spec.timeZone },
+        () => run(name, definition),
+      );
+      clocks.set(name, clock);
+    },
+
+    /** Stop future ticks for one schedule and drop its clock. */
+    async unschedule(name) {
+      clocks.get(name)?.stop();
+      clocks.delete(name);
+    },
+
+    // No drain deadline today: aborted runs are awaited unbounded, so `timeoutMs`
+    // is ignored. `removeSchedulers` has no meaning in-process — there is no shared
+    // scheduler, only local clocks, which stop either way.
+    async stop() {
+      for (const clock of clocks.values()) clock.stop();
+      clocks.clear();
+      for (const entry of active.values()) entry.controller.abort();
+      await Promise.allSettled([...active.values()].map((entry) => entry.promise));
+    },
+  };
+}