@onlineapps/mq-client-core 4.1.0 → 5.0.0

package/src/scheduler-request.js

@@ -0,0 +1,502 @@
+'use strict';
+
+/**
+ * The recurrences a service declares, and the request that registers ONE of them.
+ *
+ * `docs/architecture/scheduler.md` §7: a service declares the recurrences it owns and the
+ * wrapper re-asserts them at every boot as `scheduler.request` messages of kind `recurring`.
+ * The service answers with them through ONE hook (`scheduler: { recurrences: async () => [...] }`,
+ * d.834) - platform ones as a constant list, tenant ones derived from its own data - and this
+ * library fixes the SHAPE of a record (`validateRecurrences()`), never where it comes from
+ * (confirmation `scheduler` 011). The scheduler treats a
+ * repeated registration as an upsert — `idempotency_key` for a recurring request IS the
+ * schedule id — so re-asserting the declared state costs nothing and drifts nowhere
+ * (`api/infra/api_scheduler/src/consumer/decideOnRequest.js`, `contracts/scheduler.request.schema.json`).
+ *
+ * ONE RAIL FOR EVERY THING A SERVICE SAYS TO THE SCHEDULER. The queue takes one message with
+ * four branches, and three of them are a service's to send: `recurring` (a schedule, built from
+ * a record the service declared), `event` (a fact that happened, naming no
+ * cookbook - the scheduler starts every recipe whose `triggers` declare it, confirmation
+ * `scheduler` 004) and `cancel` (an item by its key). Each has a pure builder anybody can ask
+ * without a broker, and ONE `publishSchedulerRequest()` sends them all: the kind is a field of
+ * the message, never a second function - the split `./monitoring-initiated.js` uses for
+ * `workflow_initiated`, with one send instead of three.
+ *
+ * THE KEY IS ALWAYS THE CALLER'S. `idempotency_key` sits in the contract's root `required`, and
+ * the consumer decides a one-shot item ONCE by it (a second `event` of a known key answers
+ * `duplicate`). A key invented here would make every retry of one fact a second run, so no
+ * builder makes one up - it is the identity of the thing, and only the caller knows it.
+ *
+ * WHERE IT DIFFERS FROM THAT SIBLING, and why: sending is **fail-fast**. A lost monitoring
+ * copy is a missing record of work that already happened, so that rail returns `false` and
+ * reports. A lost registration is work that will never happen, and nothing rings when a run
+ * does not start — so every refusal here is thrown and the boot stops on it
+ * (`architecture-principles.md` §4).
+ *
+ * WHAT IT NEVER INVENTS: `tenant_id` and `workspace_id`. Both are mandatory and ≥ 1, and the
+ * caller passes them with every request — nothing here reads them from the environment or
+ * supplies a default. For a recurrence the service knows them from its own data, so the records
+ * its boot hook returns carry them; inside a handler `ctx.scheduler` takes them from the
+ * invocation envelope.
+ *
+ * @see api/docs/governance/confirmations/scheduler.md 002
+ * @see api/docs/governance/confirmations/scheduler.md 010
+ * @see api/docs/governance/confirmations/scheduler.md 011
+ *
+ * @see ./config/recurrencesSchema.js — the shape of one declared recurrence
+ * @see ./monitoring-initiated.js — the same split for `workflow_initiated`
+ * @see api/docs/architecture/scheduler.md §4, §7
+ */
+
+const Ajv = require('ajv');
+
+const queueConfig = require('./config/queueConfig');
+const { recurrencesSchema } = require('./config/recurrencesSchema');
+
+/** The queue the scheduler consumes, composed from the declaration rather than typed. */
+const schedulerRequestQueue = queueConfig.queueName('scheduler', 'request');
+
+const ajv = new Ajv({ allErrors: true });
+const validateDeclaration = ajv.compile(recurrencesSchema);
+
+/** Ajv's findings as one sentence a human can act on. */
+const describeErrors = (errors) => (errors || [])
+  .map((error) => {
+    const where = error.instancePath === '' ? 'the document' : error.instancePath;
+    const what = error.params && error.params.additionalProperty
+      ? `${error.message} ("${error.params.additionalProperty}")`
+      : error.message;
+    return `${where} ${what}`;
+  })
+  .join('; ');
+
+/**
+ * Check a parsed declaration document and hand back its records.
+ *
+ * @param {Object} document - `{ recurrences: [...] }`, as the service declared it.
+ * @param {string} source - Where it came from, named in every sentence this function throws.
+ *   Required: a default here would put one caller's name on another caller's mistake.
+ * @returns {Array<Object>} The declared recurrences, in the order they were given.
+ * @throws {Error} When the document does not hold, naming every rule it broke.
+ */
+function validateRecurrences(document, source) {
+  if (typeof source !== 'string' || source.trim() === '') {
+    throw invalidRequest(
+      '[mq-client-core/scheduler-request] Missing source - Expected: a name for what is being '
+        + 'checked, because every refusal below quotes it and a wrong name sends the reader to the '
+        + 'wrong place. Fix: pass what the caller calls this document (e.g. "the declaration").'
+    );
+  }
+
+  if (!document || typeof document !== 'object' || Array.isArray(document)) {
+    throw invalidRequest(
+      `[mq-client-core/scheduler-request] ${source} is not a declaration - Expected: an object with a "recurrences" list, `
+        + `got ${Array.isArray(document) ? 'an array' : typeof document}. `
+        + 'Fix: write { "recurrences": [ … ] }, or remove the file if the service declares none.'
+    );
+  }
+
+  if (!validateDeclaration(document)) {
+    throw invalidRequest(
+      `[mq-client-core/scheduler-request] ${source} does not hold: ${describeErrors(validateDeclaration.errors)} - `
+        + 'Expected: every record carries id, cookbook_ref, cron (five fields) and an explicit '
+        + 'IANA timezone, and nothing this shape does not declare. '
+        + 'Fix: correct the record the message names; the shape is src/config/recurrencesSchema.js. '
+        + 'Note: tenant and workspace do NOT belong here - the caller passes them '
+        + '(confirmations scheduler 010, 011; the tenancy rule itself is scheduler 002).'
+    );
+  }
+
+  const seen = new Set();
+  for (const recurrence of document.recurrences) {
+    if (seen.has(recurrence.id)) {
+      throw invalidRequest(
+        `[mq-client-core/scheduler-request] ${source} declares the id "${recurrence.id}" twice - Expected: one record per `
+          + 'id, because the id travels as the scheduler\'s idempotency_key and a second record '
+          + 'would silently overwrite the first at every boot. '
+          + 'Fix: give each schedule its own id, or remove the duplicate.'
+      );
+    }
+    seen.add(recurrence.id);
+  }
+
+  return document.recurrences;
+}
+
+/**
+ * The code every refusal of a builder carries — and only those (`SCHEDULER_REQUEST_INVALID`).
+ *
+ * A caller has two kinds of failure to tell apart and must never do it by the wording of a
+ * message: a request that cannot be built (a record that breaks the declaration rules, tenancy,
+ * a missing key or requester, a key the port does not declare) and a request that could not be
+ * SENT (no connection, a publish the broker refused). The wrapper's boot phase 0.7b isolates the
+ * first as a failed source and stops the boot on the second (confirmation `scheduler` 020,
+ * operational reading 1). So the builders mark their refusals with this code, and
+ * `publishSchedulerRequest()` and the port's construction never do.
+ */
+const SCHEDULER_REQUEST_INVALID = 'SCHEDULER_REQUEST_INVALID';
+
+/** A builder's refusal: the message as written, plus the code that names its kind. */
+function invalidRequest(message) {
+  const error = new Error(message);
+  error.code = SCHEDULER_REQUEST_INVALID;
+  return error;
+}
+
+/** A whole number a tenant or workspace id may be: ≥ 1, never 0 (confirmation scheduler 002). */
+const isContextId = (value) => Number.isInteger(value) && value >= 1;
+
+/**
+ * Turn ONE declared recurrence into the message the scheduler takes.
+ *
+ * @param {Object} args
+ * @param {Object} args.declaration - One record the service declared.
+ * @param {number} args.tenantId - The tenant the runs execute under; supplied by the caller with
+ *   this recurrence (the service's own data), never a default.
+ * @param {number} args.workspaceId - The workspace the runs execute under; supplied the same way.
+ * @param {string} args.requestedBy - The service registering this schedule.
+ * @returns {Object} The `scheduler.request` message, exactly the keys the contract declares.
+ * @throws {Error} When anything is missing, zero, or not a whole number.
+ */
+function buildRecurringRequest({ declaration, tenantId, workspaceId, requestedBy } = {}) {
+  const [recurrence] = validateRecurrences({ recurrences: [declaration] }, 'the declaration');
+
+  requireTenancy(tenantId, workspaceId);
+  const by = requireRequestedBy(requestedBy);
+
+  const request = {
+    kind: 'recurring',
+    idempotency_key: recurrence.id,
+    cookbook_ref: recurrence.cookbook_ref,
+    recurrence: { cron: recurrence.cron, timezone: recurrence.timezone },
+    tenant_id: tenantId,
+    workspace_id: workspaceId,
+    requested_by: by
+  };
+
+  // Written only when the declaration states them: an absent `input` is no input, and an absent
+  // `catch_up` is the scheduler's own default (§5) - a value materialised here would be a second
+  // owner of it.
+  if (Object.prototype.hasOwnProperty.call(recurrence, 'input')) request.input = recurrence.input;
+  if (Object.prototype.hasOwnProperty.call(recurrence, 'catch_up')) request.catch_up = recurrence.catch_up;
+
+  return request;
+}
+
+/** The platform spelling of a service or an event name, as the consumer's contract defines it. */
+const NAME_PATTERN = /^[a-z][a-z0-9-]*$/;
+
+/** The key that identifies the item, whatever kind it is - required by the contract's root. */
+function requireIdempotencyKey(idempotencyKey) {
+  if (typeof idempotencyKey !== 'string' || idempotencyKey.trim() === '') {
+    throw invalidRequest(
+      '[mq-client-core/scheduler-request] Missing idempotency_key - Expected: the stable identity '
+        + 'of this item, chosen by the caller. The scheduler decides a one-shot item ONCE by this '
+        + 'key, so a key invented here would turn every retry of one fact into a second run. '
+        + 'Fix: pass the key that names the thing (for an event, what it happened to).'
+    );
+  }
+
+  return idempotencyKey.trim();
+}
+
+/** The service registering, cancelling or reporting - checked by the scheduler against services.json. */
+function requireRequestedBy(requestedBy) {
+  if (typeof requestedBy !== 'string' || requestedBy.trim() === '') {
+    throw invalidRequest(
+      '[mq-client-core/scheduler-request] Missing requested_by - Expected: the platform name of the '
+        + 'service sending this request; the scheduler checks it against api/config/services.json '
+        + "and against the cookbook's own trigger declaration. "
+        + 'Fix: pass the service name the wrapper already holds.'
+    );
+  }
+
+  return requestedBy.trim();
+}
+
+/** Both context ids, under the one rule confirmation `scheduler` 002 fixed. */
+function requireTenancy(tenantId, workspaceId) {
+  if (!isContextId(tenantId)) {
+    throw invalidRequest(
+      `[mq-client-core/scheduler-request] Invalid tenant_id ${JSON.stringify(tenantId)} - Expected: `
+        + 'a whole number of at least 1. The owner rejected a reserved value: 0 is not a platform '
+        + 'scope, and an absent tenant is an error rather than a default (confirmation scheduler 002). '
+        + 'Fix: pass tenantId with every request - a recurrence carries it in the record the service '
+        + 'returns from its own data, and ctx.scheduler fills it from the invocation envelope; it is '
+        + 'never read from anywhere else.'
+    );
+  }
+
+  if (!isContextId(workspaceId)) {
+    throw invalidRequest(
+      `[mq-client-core/scheduler-request] Invalid workspace_id ${JSON.stringify(workspaceId)} - `
+        + 'Expected: a whole number of at least 1, under the same rule as the tenant (confirmation '
+        + 'scheduler 002). Fix: pass workspaceId with every request - a recurrence carries it in the '
+        + 'record the service returns from its own data, and ctx.scheduler fills it from the invocation '
+        + 'envelope; it is never read from anywhere else.'
+    );
+  }
+}
+
+/**
+ * Turn a fact into the message that reports it.
+ *
+ * It names NO cookbook, and that is the point: the scheduler starts every recipe whose
+ * `triggers` declare this event (confirmation `scheduler` 004), so a producer naming a recipe
+ * would be mapping work to something it may not own (`ingest-poll-trigger-rail` 001: which
+ * cookbook runs is a platform decision, not the producer's).
+ *
+ * @param {Object} args
+ * @param {{service: string, name: string}} args.event - Who it happened to, and what happened.
+ * @param {number} args.tenantId
+ * @param {number} args.workspaceId
+ * @param {string} args.requestedBy
+ * @param {string} args.idempotencyKey - The identity of this fact; see the module note.
+ * @param {Object} [args.input] - Handed to every cookbook the event starts, unchanged.
+ * @returns {Object} The `scheduler.request` message of kind `event`.
+ * @throws {Error} When anything is missing or not the shape the contract takes.
+ */
+function buildEventRequest({ event, tenantId, workspaceId, requestedBy, idempotencyKey, input } = {}) {
+  const key = requireIdempotencyKey(idempotencyKey);
+  const by = requireRequestedBy(requestedBy);
+  requireTenancy(tenantId, workspaceId);
+
+  if (!event || typeof event !== 'object' || Array.isArray(event)) {
+    throw invalidRequest(
+      `[mq-client-core/scheduler-request] Missing event - Expected: { service, name } - who it `
+        + 'happened to and what happened, both of them. '
+        + 'Fix: pass the fact this service publishes, never a cookbook name.'
+    );
+  }
+
+  for (const [field, value] of [['service', event.service], ['name', event.name]]) {
+    if (typeof value !== 'string' || !NAME_PATTERN.test(value)) {
+      throw invalidRequest(
+        `[mq-client-core/scheduler-request] Invalid event.${field} ${JSON.stringify(value)} - `
+          + 'Expected: the platform spelling, lower case letters, digits and dashes '
+          + '(the pattern the scheduler\'s own contract declares). '
+          + `Fix: pass the ${field} as api/config/services.json spells it.`
+      );
+    }
+  }
+
+  const request = {
+    kind: 'event',
+    idempotency_key: key,
+    event: { service: event.service, name: event.name },
+    tenant_id: tenantId,
+    workspace_id: workspaceId,
+    requested_by: by
+  };
+
+  if (input !== undefined) request.input = input;
+
+  return request;
+}
+
+/**
+ * Take an item back by its key.
+ *
+ * Idempotent by contract: a key that names nothing is answered `cancel-nothing` by the
+ * scheduler, not refused - so this builder judges nothing about the key, it only requires one.
+ * The item carries the context it was registered with, which is why no tenancy travels here.
+ *
+ * @param {Object} args
+ * @param {string} args.idempotencyKey - The key of the schedule or pending item to remove.
+ * @param {string} args.requestedBy - Only the service that registered an item may cancel it.
+ * @returns {Object} The `scheduler.request` message of kind `cancel`.
+ * @throws {Error} When the key or the requester is missing.
+ */
+function buildCancelRequest({ idempotencyKey, requestedBy } = {}) {
+  return {
+    kind: 'cancel',
+    idempotency_key: requireIdempotencyKey(idempotencyKey),
+    requested_by: requireRequestedBy(requestedBy)
+  };
+}
+
+/** Every key the port's `registerRecurring()` takes — anything else is refused, never dropped. */
+const RECURRING_PORT_KEYS = Object.freeze([
+  'id', 'cookbookRef', 'cron', 'timezone', 'tenantId', 'workspaceId', 'input', 'catchUp'
+]);
+
+/** The kinds this library builds, and the only ones it will send. */
+const SENDABLE_KINDS = Object.freeze(['recurring', 'event', 'cancel']);
+
+/**
+ * Send one request of any kind this library builds. Throws on every refusal — see the module
+ * note on fail-fast.
+ *
+ * @param {Object} mqClient - A connected `BaseClient`.
+ * @param {Object} request - What one of the builders above produced.
+ * @returns {Promise<void>}
+ * @throws {Error} When the client is not connected, the request is not one of ours, or the
+ *   publish fails.
+ */
+async function publishSchedulerRequest(mqClient, request) {
+  if (!mqClient || typeof mqClient.publish !== 'function' || typeof mqClient.isConnected !== 'function') {
+    throw new Error(
+      `[mq-client-core/scheduler-request] Missing client - Expected: a connected @onlineapps/mq-client-core BaseClient, so `
+        + `the registration reaches ${schedulerRequestQueue}. `
+        + 'Fix: pass the client the composition root connected.'
+    );
+  }
+
+  if (!mqClient.isConnected()) {
+    throw new Error(
+      `[mq-client-core/scheduler-request] The client is not connected - Expected: a registration reaches `
+        + `${schedulerRequestQueue} before the service starts taking work; a schedule nobody `
+        + 'registered is a run that never happens. Fix: connect the client first.'
+    );
+  }
+
+  if (!request || !SENDABLE_KINDS.includes(request.kind) || typeof request.idempotency_key !== 'string') {
+    throw new Error(
+      '[mq-client-core/scheduler-request] Not a request this library built - Expected: one of '
+        + `${SENDABLE_KINDS.join(', ')}, got kind ${JSON.stringify(request && request.kind)}. `
+        + 'Fix: build the message with buildRecurringRequest(), buildEventRequest() or '
+        + 'buildCancelRequest() before sending it.'
+    );
+  }
+
+  try {
+    await mqClient.publish(schedulerRequestQueue, request);
+  } catch (error) {
+    throw new Error(
+      `[mq-client-core/scheduler-request] Could not send "${request.idempotency_key}" (${request.kind}) `
+        + `on ${schedulerRequestQueue}: ${error.message} - Expected: the request to reach the `
+        + 'scheduler; a request nobody received is work that will not happen. '
+        + 'Fix: act on the reason above - the boot stops here rather than running a service whose '
+        + 'schedules were silently not registered.',
+      { cause: error }
+    );
+  }
+}
+
+/**
+ * A port one service holds: the three things it says, with WHO is speaking already decided.
+ *
+ * TWO CALLERS, TWO DOORS. The wrapper builds `ctx.scheduler` over this factory at boot and fills
+ * the tenancy of each call from the envelope of the run. The operator CLIs of biz-ingest
+ * (`scripts/run-{poll,fetch-source-item,retry-pending-items}.js`) do NOT boot the wrapper - a
+ * bootstrap there would start consumers, the registry and a heartbeat - and today they are the
+ * only way a document of the pilot comes into being, so they call this factory directly with the
+ * service identity and the tenancy of the row they are working on. That is why tenancy is
+ * explicit on every call rather than held by the port: one port, two kinds of caller, and no
+ * hidden context that the CLI would have to fake (BIZ-ingest measurement, 2026-09-23).
+ *
+ * EAGER ON PURPOSE. The client and the name of the queue are decided HERE, when the port is
+ * made, so a service that announces facts falls over at boot rather than at its first document.
+ * (On a pin whose `queueConfig` declares no `scheduler` section this module already refuses at
+ * require time, which is earlier still.) And because a defect of the wiring must never answer in
+ * place of the operation, every refusal names the slot it is about and how to fix it.
+ *
+ * @param {Object} args
+ * @param {Object} args.mqClient - A `BaseClient` (connected by the time a verb is called).
+ * @param {string} args.requestedBy - The service this port speaks for; it becomes `requested_by`
+ *   on every request and `event.service` on every fact.
+ * @returns {{registerRecurring: Function, publishEvent: Function, cancel: Function}}
+ * @throws {Error} When a slot is missing or unusable - at construction, never later.
+ */
+function createSchedulerPublisher({ mqClient, requestedBy } = {}) {
+  if (!mqClient || typeof mqClient.publish !== 'function' || typeof mqClient.isConnected !== 'function') {
+    throw new Error(
+      '[mq-client-core/scheduler-request] Cannot build the scheduler port: slot "mqClient" is '
+        + 'missing or cannot publish - Expected: the @onlineapps/mq-client-core BaseClient this '
+        + `service connects, so a request reaches ${schedulerRequestQueue}. This is decided now, at `
+        + 'construction, because a service that announces facts must fail at boot rather than at '
+        + 'its first document. Fix: pass the client the composition root built.'
+    );
+  }
+
+  const by = (() => {
+    try {
+      return requireRequestedBy(requestedBy);
+    } catch (error) {
+      throw new Error(
+        '[mq-client-core/scheduler-request] Cannot build the scheduler port: slot "requestedBy" is '
+          + `missing - ${error.message} `
+          + 'Fix: pass the platform name of the service this port speaks for (config.serviceName).'
+      );
+    }
+  })();
+
+  return {
+    /**
+     * Re-assert one recurrence. The id is the schedule's identity, so a repeat upserts.
+     *
+     * @param {Object} args - `{ id, cookbookRef, cron, timezone, tenantId, workspaceId, input?, catchUp? }`
+     * @returns {Promise<void>}
+     */
+    async registerRecurring(record = {}) {
+      // As strict as the declaration it becomes (`additionalProperties: false` in
+      // `./config/recurrencesSchema.js`): a key nobody reads is a typo or a second definition of
+      // something, and dropping it in silence hides both (`architecture-principles.md` §3).
+      for (const key of Object.keys(record)) {
+        if (!RECURRING_PORT_KEYS.includes(key)) {
+          throw invalidRequest(
+            `[mq-client-core/scheduler-request] registerRecurring got a key the request does not declare ("${key}") - `
+              + 'Expected: exactly { id, cookbookRef, cron, timezone, tenantId, workspaceId, input?, catchUp? }. '
+              + 'Fix: remove the key from the record the service returns / the ctx.scheduler call.'
+          );
+        }
+      }
+
+      const { id, cookbookRef, cron, timezone, tenantId, workspaceId, input, catchUp } = record;
+      const declaration = { id, cookbook_ref: cookbookRef, cron, timezone };
+      if (input !== undefined) declaration.input = input;
+      if (catchUp !== undefined) declaration.catch_up = catchUp;
+
+      await publishSchedulerRequest(mqClient, buildRecurringRequest({
+        declaration,
+        tenantId,
+        workspaceId,
+        requestedBy: by
+      }));
+    },
+
+    /**
+     * Announce one fact. The service is this port's; the key is the caller's (the identity of the
+     * thing that happened - a job's uuid, not a clock reading), because the scheduler decides a
+     * one-shot item once by it.
+     *
+     * @param {Object} args - `{ name, idempotencyKey, tenantId, workspaceId, input? }`
+     * @returns {Promise<void>}
+     */
+    async publishEvent({ name, idempotencyKey, tenantId, workspaceId, input } = {}) {
+      await publishSchedulerRequest(mqClient, buildEventRequest({
+        event: { service: by, name },
+        idempotencyKey,
+        tenantId,
+        workspaceId,
+        requestedBy: by,
+        input
+      }));
+    },
+
+    /**
+     * Take back an item this service registered, by its id.
+     *
+     * @param {Object} args - `{ id }`
+     * @returns {Promise<void>}
+     */
+    async cancel({ id } = {}) {
+      await publishSchedulerRequest(mqClient, buildCancelRequest({
+        idempotencyKey: id,
+        requestedBy: by
+      }));
+    }
+  };
+}
+
+module.exports = {
+  schedulerRequestQueue,
+  SENDABLE_KINDS,
+  SCHEDULER_REQUEST_INVALID,
+  validateRecurrences,
+  buildRecurringRequest,
+  buildEventRequest,
+  buildCancelRequest,
+  publishSchedulerRequest,
+  createSchedulerPublisher
+};