@onlineapps/mq-client-core 4.2.0 → 5.0.0

package/src/scheduler-request.js

@@ -81,7 +81,7 @@ const describeErrors = (errors) => (errors || [])
  */
 function validateRecurrences(document, source) {
   if (typeof source !== 'string' || source.trim() === '') {
-    throw new Error(
+    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").'
@@ -89,7 +89,7 @@ function validateRecurrences(document, source) {
   }
 
   if (!document || typeof document !== 'object' || Array.isArray(document)) {
-    throw new Error(
+    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.'
@@ -97,7 +97,7 @@ function validateRecurrences(document, source) {
   }
 
   if (!validateDeclaration(document)) {
-    throw new Error(
+    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. '
@@ -110,7 +110,7 @@ function validateRecurrences(document, source) {
   const seen = new Set();
   for (const recurrence of document.recurrences) {
     if (seen.has(recurrence.id)) {
-      throw new Error(
+      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. '
@@ -123,6 +123,26 @@ function validateRecurrences(document, source) {
   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;
 
@@ -169,7 +189,7 @@ 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 new Error(
+    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. '
@@ -183,7 +203,7 @@ function requireIdempotencyKey(idempotencyKey) {
 /** The service registering, cancelling or reporting - checked by the scheduler against services.json. */
 function requireRequestedBy(requestedBy) {
   if (typeof requestedBy !== 'string' || requestedBy.trim() === '') {
-    throw new Error(
+    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. "
@@ -197,7 +217,7 @@ function requireRequestedBy(requestedBy) {
 /** Both context ids, under the one rule confirmation `scheduler` 002 fixed. */
 function requireTenancy(tenantId, workspaceId) {
   if (!isContextId(tenantId)) {
-    throw new Error(
+    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). '
@@ -208,7 +228,7 @@ function requireTenancy(tenantId, workspaceId) {
   }
 
   if (!isContextId(workspaceId)) {
-    throw new Error(
+    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 '
@@ -242,7 +262,7 @@ function buildEventRequest({ event, tenantId, workspaceId, requestedBy, idempote
   requireTenancy(tenantId, workspaceId);
 
   if (!event || typeof event !== 'object' || Array.isArray(event)) {
-    throw new Error(
+    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.'
@@ -251,7 +271,7 @@ function buildEventRequest({ event, tenantId, workspaceId, requestedBy, idempote
 
   for (const [field, value] of [['service', event.service], ['name', event.name]]) {
     if (typeof value !== 'string' || !NAME_PATTERN.test(value)) {
-      throw new Error(
+      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). '
@@ -414,7 +434,7 @@ function createSchedulerPublisher({ mqClient, requestedBy } = {}) {
       // 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 new Error(
+          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.'
@@ -472,6 +492,7 @@ function createSchedulerPublisher({ mqClient, requestedBy } = {}) {
 module.exports = {
   schedulerRequestQueue,
   SENDABLE_KINDS,
+  SCHEDULER_REQUEST_INVALID,
   validateRecurrences,
   buildRecurringRequest,
   buildEventRequest,