@reventlessdev/trait-notification 1.0.0-alpha.1 → 1.0.0-alpha.11

package/src/Notification_Rule.res.mjs

@@ -0,0 +1,348 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Sury from "sury";
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+import * as Stdlib_Result from "@rescript/runtime/lib/es6/Stdlib_Result.js";
+import * as Primitive_object from "@rescript/runtime/lib/es6/Primitive_object.js";
+import * as Template$Reventless from "@reventlessdev/reventless-spec/src/semantic/Template.res.mjs";
+
+let comparisonSchema = Sury.union([
+  Sury.literal("Eq"),
+  Sury.literal("Ne"),
+  Sury.literal("Lt"),
+  Sury.literal("Lte"),
+  Sury.literal("Gt"),
+  Sury.literal("Gte"),
+  Sury.literal("Contains")
+]);
+
+let literalSchema = Sury.union([
+  Sury.$schema(s => ({
+    TAG: "Text",
+    _0: s.m(Sury.string)
+  })),
+  Sury.$schema(s => ({
+    TAG: "Number",
+    _0: s.m(Sury.float)
+  })),
+  Sury.$schema(s => ({
+    TAG: "Flag",
+    _0: s.m(Sury.bool)
+  }))
+]);
+
+let predicateSchema = Sury.recursive("predicate", predicateSchema => Sury.union([
+  Sury.literal("Always"),
+  Sury.$schema(s => ({
+    TAG: "Compare",
+    path: s.m(Sury.string),
+    op: s.m(comparisonSchema),
+    value: s.m(literalSchema)
+  })),
+  Sury.$schema(s => ({
+    TAG: "All",
+    _0: s.m(Sury.array(predicateSchema))
+  })),
+  Sury.$schema(s => ({
+    TAG: "Any",
+    _0: s.m(Sury.array(predicateSchema))
+  })),
+  Sury.$schema(s => ({
+    TAG: "Not",
+    _0: s.m(predicateSchema)
+  }))
+]));
+
+let contentSchema = Sury.$schema(s => ({
+  locale: s.m(Sury.string),
+  subject: s.m(Sury.string),
+  body: s.m(Sury.string)
+}));
+
+let sourceSchema = Sury.$schema(s => ({
+  log: s.m(Sury.string),
+  eventType: s.m(Sury.string)
+}));
+
+let deliverySchema = Sury.union([
+  Sury.literal("Immediate"),
+  Sury.$schema(s => ({
+    TAG: "Digest",
+    windowSeconds: s.m(Sury.int)
+  }))
+]);
+
+let schema = Sury.$schema(s => ({
+  id: s.m(Sury.string),
+  version: s.m(Sury.string),
+  source: s.m(sourceSchema),
+  filter: s.m(predicateSchema),
+  category: s.m(Sury.string),
+  delivery: s.m(deliverySchema),
+  recipientPath: s.m(Sury.string),
+  subjectType: s.m(Sury.string),
+  subjectPath: s.m(Sury.string),
+  content: s.m(Sury.array(contentSchema))
+}));
+
+function sourceId(rule) {
+  return rule.source.log + `:` + rule.source.eventType;
+}
+
+function referenceFor(ruleId, subject) {
+  return ruleId + `:` + subject;
+}
+
+function reference(rule, subject) {
+  return referenceFor(rule.id, subject);
+}
+
+function byId(rules, id) {
+  return rules.find(rule => rule.id === id);
+}
+
+function isImmediate(rule) {
+  return rule.delivery === "Immediate";
+}
+
+function forEvent(rules, log, eventType) {
+  return rules.filter(rule => {
+    if (rule.source.log === log) {
+      return rule.source.eventType === eventType;
+    } else {
+      return false;
+    }
+  });
+}
+
+function compare(actual, op, expected) {
+  let ordered = (a, b) => {
+    switch (op) {
+      case "Eq" :
+        return Primitive_object.equal(a, b);
+      case "Ne" :
+        return Primitive_object.notequal(a, b);
+      case "Lt" :
+        return Primitive_object.lessthan(a, b);
+      case "Lte" :
+        return Primitive_object.lessequal(a, b);
+      case "Gt" :
+        return Primitive_object.greaterthan(a, b);
+      case "Gte" :
+        return Primitive_object.greaterequal(a, b);
+      case "Contains" :
+        return false;
+    }
+  };
+  if (actual === null) {
+    return false;
+  }
+  if (Array.isArray(actual)) {
+    switch (expected.TAG) {
+      case "Text" :
+        let b = expected._0;
+        if (op === "Contains") {
+          return actual.some(item => {
+            if (typeof item === "string") {
+              return item === b;
+            } else {
+              return false;
+            }
+          });
+        } else {
+          return false;
+        }
+      case "Number" :
+      case "Flag" :
+        return false;
+    }
+  } else {
+    switch (typeof actual) {
+      case "boolean" :
+        switch (expected.TAG) {
+          case "Text" :
+          case "Number" :
+            return false;
+          case "Flag" :
+            let b$1 = expected._0;
+            switch (op) {
+              case "Eq" :
+                return actual === b$1;
+              case "Ne" :
+                return actual !== b$1;
+              default:
+                return false;
+            }
+        }
+      case "string" :
+        switch (expected.TAG) {
+          case "Text" :
+            let b$2 = expected._0;
+            if (op === "Contains") {
+              return actual.includes(b$2);
+            } else {
+              return ordered(actual, b$2);
+            }
+          case "Number" :
+          case "Flag" :
+            return false;
+        }
+      case "number" :
+        switch (expected.TAG) {
+          case "Number" :
+            return ordered(actual, expected._0);
+          case "Text" :
+          case "Flag" :
+            return false;
+        }
+      case "object" :
+        return false;
+    }
+  }
+}
+
+function matches(predicate, payload) {
+  if (typeof predicate !== "object") {
+    return true;
+  }
+  switch (predicate.TAG) {
+    case "Compare" :
+      let actual = Template$Reventless.lookup(payload, predicate.path);
+      if (actual !== undefined) {
+        return compare(actual, predicate.op, predicate.value);
+      } else {
+        return false;
+      }
+    case "All" :
+      return predicate._0.every(part => matches(part, payload));
+    case "Any" :
+      return predicate._0.some(part => matches(part, payload));
+    case "Not" :
+      return !matches(predicate._0, payload);
+  }
+}
+
+function stringAt(payload, path) {
+  let match = Template$Reventless.lookup(payload, path);
+  if (typeof match === "string") {
+    return match;
+  }
+}
+
+function recipientOf(rule, payload) {
+  return stringAt(payload, rule.recipientPath);
+}
+
+function subjectOf(rule, payload) {
+  return Stdlib_Option.getOr(stringAt(payload, rule.subjectPath), "");
+}
+
+function contentFor(rule, locale) {
+  if (locale === undefined) {
+    return rule.content[0];
+  }
+  let found = rule.content.find(entry => entry.locale === locale);
+  if (found !== undefined) {
+    return found;
+  } else {
+    return rule.content[0];
+  }
+}
+
+function render(source, payload, schema) {
+  return Stdlib_Result.getOr(Template$Reventless.renderSource(source, payload, schema), source);
+}
+
+function compose(rule, payload, schema, locale) {
+  let match = contentFor(rule, locale);
+  if (match !== undefined) {
+    return [
+      render(match.subject, payload, schema),
+      render(match.body, payload, schema)
+    ];
+  } else {
+    return [
+      "",
+      ""
+    ];
+  }
+}
+
+function validate(rules, digestRoutedOpt, sample) {
+  let digestRouted = digestRoutedOpt !== undefined ? digestRoutedOpt : false;
+  return rules.flatMap(rule => {
+    let problems = [];
+    let note = message => {
+      problems.push(rule.id + `: ` + message);
+    };
+    if (rule.id === "") {
+      note("a rule needs an id — it is the namespace of every reference it writes");
+    }
+    if (rule.content.length === 0) {
+      note("no wording at all");
+    }
+    rule.content.forEach(param => {
+      let locale = param.locale;
+      [
+        [
+          "subject",
+          param.subject
+        ],
+        [
+          "body",
+          param.body
+        ]
+      ].forEach(param => {
+        let why = Template$Reventless.parse(param[1]);
+        if (why.TAG === "Ok") {
+          return;
+        } else {
+          return note(locale + ` ` + param[0] + ` does not parse — ` + why._0);
+        }
+      });
+    });
+    if (stringAt(sample, rule.recipientPath) === undefined) {
+      note(`recipientPath "` + rule.recipientPath + `" names nobody in the sample payload`);
+    }
+    if (stringAt(sample, rule.subjectPath) === undefined) {
+      note(`subjectPath "` + rule.subjectPath + `" resolves to nothing in the sample payload`);
+    }
+    let match = rule.delivery;
+    if (typeof match === "object") {
+      let windowSeconds = match.windowSeconds;
+      if (!digestRouted) {
+        note("delivered as a digest, and nothing in this deployment gathers one");
+      }
+      if (windowSeconds <= 0) {
+        note(`a digest window of ` + windowSeconds.toString() + `s gathers nothing`);
+      }
+    }
+    return problems;
+  });
+}
+
+export {
+  comparisonSchema,
+  literalSchema,
+  predicateSchema,
+  contentSchema,
+  sourceSchema,
+  deliverySchema,
+  schema,
+  sourceId,
+  referenceFor,
+  reference,
+  byId,
+  isImmediate,
+  forEvent,
+  compare,
+  matches,
+  stringAt,
+  recipientOf,
+  subjectOf,
+  contentFor,
+  render,
+  compose,
+  validate,
+}
+/* comparisonSchema Not a pure module */

package/src/Notification_Rules.res

@@ -17,7 +17,6 @@ is the opposite. So the fallback *rule* lives here — an absent choice defers t
 the posture — and the *table* is passed in as `~posture`. A trait that hard-coded
 either answer would be wrong for half its hosts.
 */
-
 /** How a recipient is reached. Mirrors `Reventless.Messaging.channel`, which is
     the platform capability's vocabulary; this one is the domain's, so it carries
     a host's schema and travels on the wire. `Notification_Send` maps the two. */
@@ -35,6 +34,21 @@ let channels = [Email, Sms, Push]
     vocabulary — this module never enumerates them. */
 type category = string
 
+/** Which stream of occurrences a request came from, as `"<log>:<eventType>"`.
+    Opaque here: the competency never parses it, it only compares it against what
+    has been claimed. */
+type source = string
+
+/** Why a request exists. The compiled table that ships with a host, or a rule
+    somebody configured on top of it.
+
+    No payload on `Configured`: the trait needs exactly one thing from this — which
+    of the two yields when a source has been taken over — and *which* rule it was
+    is the host's fact to record on its own event. */
+type origin =
+  | Default
+  | Configured
+
 /** Refolded per decision, never stored — the host's slice state is. */
 type t = {
   /** One address per channel. An array rather than a single address because the
@@ -44,39 +58,66 @@ type t = {
   contacts: array<(channel, string)>,
   /** Only the cells a recipient has an opinion about; the rest is `~posture`. */
   choices: array<(category, channel, bool)>,
+  /** Sources a second producer has taken over, and who took each one. Empty for
+      every host with one producer, which is what makes the deferral below inert
+      until something actually claims a source. */
+  claims: array<(source, string)>,
 }
 
-let empty = {contacts: [], choices: []}
+let empty = {contacts: [], choices: [], claims: []}
+
+let claimedBy = (t, source) =>
+  t.claims->Array.find(((s, _)) => s == source)->Option.map(((_, by)) => by)
 
 /** What a host asks the competency to do. */
 type op =
-  | /** Relayed from whatever the host publishes when it learns where somebody is.
+  /** Relayed from whatever the host publishes when it learns where somebody is.
         Not a client's command: a caller who could announce another person's
         address would be redirecting their mail. */
-  Announce({channel: channel, address: string})
+  | Announce({channel: channel, address: string})
   | Subscribe({category: category, channel: channel})
   | Unsubscribe({category: category, channel: channel})
-  | /** Something worth telling them about happened. `reference` is the caller's
+  /** Something worth telling them about happened. `reference` is the caller's
         own key for it, echoed back on whichever outcome follows, so the relay
-        that asked can tell its work is finished. Opaque here on purpose. */
-  Request({category: category, reference: string})
+        that asked can tell its work is finished. Opaque here on purpose.
+
+        `source` says which stream it came from and `origin` says who is asking;
+        together they are the whole of the handover — see `decide`. */
+  | Request({category: category, reference: string, source: source, origin: origin})
+  /** A second producer takes over one source. Relayed like `Announce`: a
+        client that could claim a source would be silencing somebody else's mail. */
+  | Claim({source: source, by: string})
+  | Release({source: source})
 
 /** What the competency decided, for the host to name in its own events. */
 type fact =
   | Announced({channel: channel, address: string})
   | Subscribed({category: category, channel: channel})
   | Unsubscribed({category: category, channel: channel})
-  | /** The addressed message. `address` is the snapshot delivery uses, which is
+  /** The addressed message. `address` is the snapshot delivery uses, which is
         why it is on the fact and not looked up again later. */
-  Requested({category: category, reference: string, channel: channel, address: string})
-  | /** They are reachable and said no. */
-  Suppressed({category: category, reference: string})
-  | /** They want it and nobody can be reached — no address on file for any
+  | Requested({category: category, reference: string, channel: channel, address: string})
+  /** They are reachable and said no. */
+  | Suppressed({category: category, reference: string})
+  /** They want it and nobody can be reached — no address on file for any
         channel they left enabled. A different fact from `Suppressed` on purpose:
         one is the system working and the other is the system falling short, and
         reporting both the same way hides every delivery gap behind a legitimate
         preference. */
-  Undeliverable({category: category, reference: string})
+  | Undeliverable({category: category, reference: string})
+  /** Not acted on because another producer owns this source. A third way of
+        not sending, and its own fact for the same reason `Suppressed` and
+        `Undeliverable` are two rather than one: "they declined", "nobody was
+        reachable" and "somebody else has this" are three different things, and a
+        shared fact would hide two of them behind whichever name it took.
+
+        It is also load-bearing rather than tidy. The relay upstream resolves its
+        TODO row on an outcome; without a fourth one a deferred request retries
+        its whole budget and lands in `onExhausted`, which is a slow silent
+        failure with nothing in the log to explain it. */
+  | Deferred({reference: string, source: source})
+  | Claimed({source: source, by: string})
+  | Released({source: source})
 
 let addressFor = (t, channel) =>
   t.contacts->Array.find(((c, _)) => c == channel)->Option.map(((_, address)) => address)
@@ -108,13 +149,22 @@ let evolve = (t, fact) =>
     }
   | Subscribed({category, channel}) => withChoice(t, category, channel, true)
   | Unsubscribed({category, channel}) => withChoice(t, category, channel, false)
+  // Claims are per source and not per recipient, so they arrive from outside this
+  // recipient's own history — the host reads them across partitions, which is why
+  // the request carries the source it came from.
+  | Claimed({source, by}) => {
+      ...t,
+      claims: Array.concat(t.claims->Array.filter(((s, _)) => s != source), [(source, by)]),
+    }
+  | Released({source}) => {...t, claims: t.claims->Array.filter(((s, _)) => s != source)}
   // Neither the outcome of a request nor a delivery report changes who somebody
   // is or what they want, so the fold ignores them. What a host must NOT do is
   // read them back as consumed events to make this state bigger — the directory
   // is snapshotted, and a set of every reference ever seen would grow forever.
   | Requested(_)
   | Suppressed(_)
-  | Undeliverable(_) => t
+  | Undeliverable(_)
+  | Deferred(_) => t
   }
 
 /** The whole competency, in one function.
@@ -150,17 +200,36 @@ let decide = (t, op, ~posture: (category, channel) => bool): result<
       ? Ok([Unsubscribed({category, channel})])
       : Ok([])
 
+  | Claim({source: src, by}) =>
+    claimedBy(t, src) == Some(by) ? Ok([]) : Ok([Claimed({source: src, by})])
+
+  | Release({source: src}) =>
+    switch claimedBy(t, src) {
+    | None => Ok([])
+    | Some(_) => Ok([Released({source: src})])
+    }
+
+  // The handover, and the whole of it. A `Configured` request is the second
+  // producer's own and always goes through; a `Default` one is the compiled
+  // table still firing for a source somebody else has taken over, and it yields.
+  //
+  // Precedence has to be per source rather than per deployment, which is why this
+  // is folded state and not a swapped-in implementation: a second producer that
+  // takes over some of the table and leaves the rest compiled cannot be expressed
+  // by choosing one of two implementations at build time.
+  | Request({source, origin: Default, reference}) if claimedBy(t, source) != None =>
+    Ok([Deferred({reference, source})])
+
   | Request({category, reference}) =>
     let wanted = channels->Array.filter(channel => enabled(t, ~posture, category, channel))
-    let addressed =
-      wanted->Array.filterMap(channel =>
-        addressFor(t, channel)->Option.map(address => Requested({
-          category,
-          reference,
-          channel,
-          address,
-        }))
-      )
+    let addressed = wanted->Array.filterMap(channel =>
+      addressFor(t, channel)->Option.map(address => Requested({
+        category,
+        reference,
+        channel,
+        address,
+      }))
+    )
     switch addressed {
     | [] =>
       // Wanted-but-unreachable and not-wanted are the two ways to send nothing,

package/src/Notification_Rules.res.mjs

@@ -14,11 +14,18 @@ let empty_contacts = [];
 
 let empty_choices = [];
 
+let empty_claims = [];
+
 let empty = {
   contacts: empty_contacts,
-  choices: empty_choices
+  choices: empty_choices,
+  claims: empty_claims
 };
 
+function claimedBy(t, source) {
+  return Stdlib_Option.map(t.claims.find(param => param[0] === source), param => param[1]);
+}
+
 function addressFor(t, channel) {
   return Stdlib_Option.map(t.contacts.find(param => param[0] === channel), param => param[1]);
 }
@@ -45,7 +52,8 @@ function withChoice(t, category, channel, isEnabled) {
         category,
         channel,
         isEnabled
-      ]])
+      ]]),
+    claims: t.claims
   };
 }
 
@@ -58,12 +66,30 @@ function evolve(t, fact) {
             channel,
             fact.address
           ]]),
-        choices: t.choices
+        choices: t.choices,
+        claims: t.claims
       };
     case "Subscribed" :
       return withChoice(t, fact.category, fact.channel, true);
     case "Unsubscribed" :
       return withChoice(t, fact.category, fact.channel, false);
+    case "Claimed" :
+      let source = fact.source;
+      return {
+        contacts: t.contacts,
+        choices: t.choices,
+        claims: t.claims.filter(param => param[0] !== source).concat([[
+            source,
+            fact.by
+          ]])
+      };
+    case "Released" :
+      let source$1 = fact.source;
+      return {
+        contacts: t.contacts,
+        choices: t.choices,
+        claims: t.claims.filter(param => param[0] !== source$1)
+      };
     default:
       return t;
   }
@@ -138,8 +164,19 @@ function decide(t, op, posture) {
         };
       }
     case "Request" :
+      let source = op.source;
       let reference = op.reference;
       let category$2 = op.category;
+      if (op.origin === "Default" && claimedBy(t, source) !== undefined) {
+        return {
+          TAG: "Ok",
+          _0: [{
+              TAG: "Deferred",
+              reference: reference,
+              source: source
+            }]
+        };
+      }
       let wanted = channels.filter(channel => enabled(t, posture, category$2, channel));
       let addressed = Stdlib_Array.filterMap(wanted, channel => Stdlib_Option.map(addressFor(t, channel), address => ({
         TAG: "Requested",
@@ -172,12 +209,48 @@ function decide(t, op, posture) {
             }]
         };
       }
+    case "Claim" :
+      let by = op.by;
+      let src = op.source;
+      if (Primitive_object.equal(claimedBy(t, src), by)) {
+        return {
+          TAG: "Ok",
+          _0: []
+        };
+      } else {
+        return {
+          TAG: "Ok",
+          _0: [{
+              TAG: "Claimed",
+              source: src,
+              by: by
+            }]
+        };
+      }
+    case "Release" :
+      let src$1 = op.source;
+      let match = claimedBy(t, src$1);
+      if (match !== undefined) {
+        return {
+          TAG: "Ok",
+          _0: [{
+              TAG: "Released",
+              source: src$1
+            }]
+        };
+      } else {
+        return {
+          TAG: "Ok",
+          _0: []
+        };
+      }
   }
 }
 
 export {
   channels,
   empty,
+  claimedBy,
   addressFor,
   enabled,
   withChoice,