@reventlessdev/trait-notification 1.0.0-alpha.3 → 1.0.0-alpha.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/trait-notification",
-  "version": "1.0.0-alpha.3",
+  "version": "1.0.0-alpha.5",
   "description": "Notification domain trait: rules, host contract, conformance suite and emitter for a per-recipient contact directory, a kind x channel subscription matrix, and the decision to send, suppress or record a message as undeliverable",
   "license": "Apache-2.0",
   "files": [
@@ -13,8 +13,8 @@
   "dependencies": {
     "sury": "11.0.0-rc.2",
     "sury-ppx": "11.0.0-rc.2",
-    "@reventlessdev/reventless-gwt": "1.0.0-alpha.201",
-    "@reventlessdev/reventless-spec": "3.0.0-alpha.127"
+    "@reventlessdev/reventless-gwt": "1.0.0-alpha.203",
+    "@reventlessdev/reventless-spec": "3.0.0-alpha.129"
   },
   "devDependencies": {
     "rescript": "12.3.0"

package/src/Notification.res

@@ -74,12 +74,27 @@ module type Binding = {
   let announcedC: string => Spec.consumedEvent
   let subscribedC: (category, Notification_Rules.channel) => Spec.consumedEvent
   let unsubscribedC: (category, Notification_Rules.channel) => Spec.consumedEvent
+  /** A source taken over, as the slice reads it back. Claims are per source and
+      not per recipient, so a host produces these from wherever it keeps them —
+      what this contract requires is only that the decision can see them. */
+  let claimedC: (string, string) => Spec.consumedEvent
+  let releasedC: string => Spec.consumedEvent
 
   let announce: string => Spec.command
   let subscribe: (category, Notification_Rules.channel) => Spec.command
   let unsubscribe: (category, Notification_Rules.channel) => Spec.command
-  /** `reference` is the requester's key, echoed on whichever outcome follows. */
+  /** `reference` is the requester's key, echoed on whichever outcome follows.
+      The host's own relay's request: `Default` origin, from `defaultSource`. */
   let request: (category, string) => Spec.command
+  /** The same, with the two fields the handover turns on spelled out. */
+  let requestFrom: (
+    category,
+    string,
+    ~source: string,
+    ~origin: Notification_Rules.origin,
+  ) => Spec.command
+  /** The source `request` above comes from, and one nothing ever claims. */
+  let defaultSource: string
 
   /** The competency's facts, as the slice emits them. */
   let announced: string => Spec.event
@@ -88,6 +103,17 @@ module type Binding = {
   let requested: (category, string, Notification_Rules.channel, string) => Spec.event
   let suppressed: (category, string) => Spec.event
   let undeliverable: (category, string) => Spec.event
+  /** `(reference, source)` — the request another producer owns. */
+  let deferred: (string, string) => Spec.event
+  /** `requested` as it comes out for a `Configured` request. A separate member
+      because *which* rule asked is the host's own shape — the trait's fact
+      carries no origin at all, so it cannot construct this one. */
+  let requestedConfigured: (
+    category,
+    string,
+    Notification_Rules.channel,
+    string,
+  ) => Spec.event
 
   /** The refusal for managing preferences for somebody nobody has announced. */
   let recipientUnknown: Spec.error

package/src/Notification_Conformance.res

@@ -113,6 +113,65 @@ module Make = (B: Notification.Binding) => {
         ->G.thenEvent(B.undeliverable(B.transactional, "ref-4"))
       )
 
+      // ── The handover ────────────────────────────────────────────────────────
+      //
+      // A second producer takes over one source and the compiled table yields on
+      // that source alone. The first of these is the one that matters most: it is
+      // the assertion that a host with nobody claiming anything behaves exactly as
+      // it did before any of this existed.
+
+      G.test("with nothing claimed, a default request is decided as usual", () =>
+        G.givenEvents(announced)
+        ->G.whenCmd(
+          B.requestFrom(B.transactional, "ref-6", ~source=B.defaultSource, ~origin=Default),
+        )
+        ->G.thenEvent(B.requested(B.transactional, "ref-6", B.announcedChannel, B.addressA))
+      )
+
+      G.test("a default request for a claimed source is deferred", () =>
+        G.givenEvents(Array.concat(announced, [B.claimedC("other:Source", "second-producer")]))
+        ->G.whenCmd(
+          B.requestFrom(B.transactional, "ref-7", ~source="other:Source", ~origin=Default),
+        )
+        ->G.thenEvent(B.deferred("ref-7", "other:Source"))
+      )
+
+      // The claim is per source, not per recipient or per deployment: the table
+      // keeps firing everywhere it was not taken over. Without this, a single
+      // claim would silence the whole competency.
+      G.test("a claim on one source leaves every other source alone", () =>
+        G.givenEvents(Array.concat(announced, [B.claimedC("other:Source", "second-producer")]))
+        ->G.whenCmd(
+          B.requestFrom(B.transactional, "ref-8", ~source=B.defaultSource, ~origin=Default),
+        )
+        ->G.thenEvent(B.requested(B.transactional, "ref-8", B.announcedChannel, B.addressA))
+      )
+
+      // The producer that owns the source is the one that must get through, or
+      // the handover would silence the entry rather than move it.
+      G.test("a configured request for a claimed source goes through", () =>
+        G.givenEvents(Array.concat(announced, [B.claimedC("other:Source", "second-producer")]))
+        ->G.whenCmd(
+          B.requestFrom(B.transactional, "ref-9", ~source="other:Source", ~origin=Configured),
+        )
+        ->G.thenEvent(
+          B.requestedConfigured(B.transactional, "ref-9", B.announcedChannel, B.addressA),
+        )
+      )
+
+      G.test("a released source stops deferring", () =>
+        G.givenEvents(
+          Array.concat(
+            announced,
+            [B.claimedC("other:Source", "second-producer"), B.releasedC("other:Source")],
+          ),
+        )
+        ->G.whenCmd(
+          B.requestFrom(B.transactional, "ref-10", ~source="other:Source", ~origin=Default),
+        )
+        ->G.thenEvent(B.requested(B.transactional, "ref-10", B.announcedChannel, B.addressA))
+      )
+
       // Wanted, and unreachable — the distinction the whole `Undeliverable` arm
       // exists for. Skipped by a host that announces an address for every channel
       // it offers, because there is then no way to be in this state.

package/src/Notification_Conformance.res.mjs

@@ -28,6 +28,14 @@ function Make(B) {
     G.test("an optional request is suppressed with no explicit subscription", () => G.thenEvent(G.whenCmd(G.givenEvents(announced), B.request(B.optional, "ref-2")), B.suppressed(B.optional, "ref-2")));
     G.test("a recipient who opted out is suppressed", () => G.thenEvent(G.whenCmd(G.givenEvents(announced.concat([B.unsubscribedC(B.transactional, B.announcedChannel)])), B.request(B.transactional, "ref-3")), B.suppressed(B.transactional, "ref-3")));
     G.test("a request for a recipient nobody announced is undeliverable", () => G.thenEvent(G.whenCmd(G.givenEvents(B.created), B.request(B.transactional, "ref-4")), B.undeliverable(B.transactional, "ref-4")));
+    G.test("with nothing claimed, a default request is decided as usual", () => G.thenEvent(G.whenCmd(G.givenEvents(announced), B.requestFrom(B.transactional, "ref-6", B.defaultSource, "Default")), B.requested(B.transactional, "ref-6", B.announcedChannel, B.addressA)));
+    G.test("a default request for a claimed source is deferred", () => G.thenEvent(G.whenCmd(G.givenEvents(announced.concat([B.claimedC("other:Source", "second-producer")])), B.requestFrom(B.transactional, "ref-7", "other:Source", "Default")), B.deferred("ref-7", "other:Source")));
+    G.test("a claim on one source leaves every other source alone", () => G.thenEvent(G.whenCmd(G.givenEvents(announced.concat([B.claimedC("other:Source", "second-producer")])), B.requestFrom(B.transactional, "ref-8", B.defaultSource, "Default")), B.requested(B.transactional, "ref-8", B.announcedChannel, B.addressA)));
+    G.test("a configured request for a claimed source goes through", () => G.thenEvent(G.whenCmd(G.givenEvents(announced.concat([B.claimedC("other:Source", "second-producer")])), B.requestFrom(B.transactional, "ref-9", "other:Source", "Configured")), B.requestedConfigured(B.transactional, "ref-9", B.announcedChannel, B.addressA)));
+    G.test("a released source stops deferring", () => G.thenEvent(G.whenCmd(G.givenEvents(announced.concat([
+      B.claimedC("other:Source", "second-producer"),
+      B.releasedC("other:Source")
+    ])), B.requestFrom(B.transactional, "ref-10", "other:Source", "Default")), B.requested(B.transactional, "ref-10", B.announcedChannel, B.addressA)));
     let channel = B.unreachableChannel;
     if (channel !== undefined) {
       return G.test("a channel with no address on file is undeliverable, not suppressed", () => G.thenEvent(G.whenCmd(G.givenEvents(announced.concat([

package/src/Notification_Rule.res

@@ -0,0 +1,248 @@
+/**
+One notification rule as a value: which stream of occurrences it answers to, who
+it is for, which kind it is, and what it says.
+
+The shape a compiled table and a configured one both hold. That is why the filter
+is a typed tree and not an expression string — a string needs a parser at
+evaluation time, and a parser that runs on data from outside is an injection
+surface. It is also why the wording is `Reventless.Template` source: readable
+text rather than ReScript interpolation, rendered against the payload's schema so
+a semantic formats itself and a `@sensitive` field is withheld.
+*/
+
+/** How a field is compared. */
+@schema
+type comparison =
+  | Eq
+  | Ne
+  | Lt
+  | Lte
+  | Gt
+  | Gte
+  | Contains
+
+/** What it is compared against. */
+@schema
+type literal =
+  | Text(string)
+  | Number(float)
+  | Flag(bool)
+
+/** Whether a rule answers to this occurrence. */
+@schema
+type rec predicate =
+  | Always
+  | Compare({path: string, op: comparison, value: literal})
+  | All(array<predicate>)
+  | Any(array<predicate>)
+  | Not(predicate)
+
+/** One wording, in one locale. Both fields are `Reventless.Template` sources. */
+@schema
+type content = {locale: string, subject: string, body: string}
+
+/** The stream of occurrences a rule answers to, as the two halves of the
+    `"<log>:<eventType>"` a claim is made against. */
+@schema
+type source = {log: string, eventType: string}
+
+/** How a rule's occurrences reach the recipient: one message each, or gathered
+    into one message per window.
+
+    Routing is a field on the rule and not a negotiation between producers. A
+    digest is scheduler-driven and therefore its own component, but *which*
+    occurrences are its to gather is a table entry — so a relay serves the half it
+    can deliver and leaves the rest, with nothing to arbitrate.
+
+    `windowSeconds` is the one thing a digest cannot read off the rule. Where a
+    window starts and ends is the gathering component's own, deliberately: aligning
+    to a local midnight is a decision this table has no input for. */
+@schema
+type delivery =
+  | Immediate
+  | Digest({windowSeconds: int})
+
+@schema
+type t = {
+  /** Stable, because it is also the namespace of every reference this rule's
+      requests carry — renaming it re-keys their delivery rows. */
+  id: string,
+  /** Which version of this rule wrote a message, for the request to record. */
+  version: string,
+  source: source,
+  filter: predicate,
+  /** The host's kind of notification, as a key — see `Notification_Rules.category`. */
+  category: string,
+  delivery: delivery,
+  /** Where in the payload the person to notify is named. */
+  recipientPath: string,
+  /** What the notification is about: the component's name as the deployment
+      registers it, and where that row's own id sits in the payload. */
+  subjectType: string,
+  subjectPath: string,
+  content: array<content>,
+}
+
+/** The stream this rule answers to, in the form a claim is made against. */
+let sourceId = (rule: t) => `${rule.source.log}:${rule.source.eventType}`
+
+/** The correlation key a request carries. One per rule per subject, so an order
+    that is placed and then ships is two notifications and two delivery rows. */
+let referenceFor = (~ruleId: string, ~subject: string) => `${ruleId}:${subject}`
+
+let reference = (rule: t, ~subject: string) => referenceFor(~ruleId=rule.id, ~subject)
+
+let byId = (rules: array<t>, id: string) => rules->Array.find(rule => rule.id == id)
+
+/** Whether the per-event relay is the one that delivers this rule. A digest's
+    occurrences are gathered by its own component, so the relay passes over them
+    rather than sending one message each. */
+let isImmediate = (rule: t) => rule.delivery == Immediate
+
+/** Every rule answering to one occurrence. Two rules on one event type are two
+    notifications, which is what makes adding one a table change and not a code
+    change. */
+let forEvent = (rules: array<t>, ~log: string, ~eventType: string) =>
+  rules->Array.filter(rule => rule.source.log == log && rule.source.eventType == eventType)
+
+/** A mismatch of kinds is `false`, `Ne` included: a filter that cannot be read
+    against this payload does not fire. */
+let compare = (actual: JSON.t, op: comparison, expected: literal): bool => {
+  let ordered = (a, b) =>
+    switch op {
+    | Eq => a == b
+    | Ne => a != b
+    | Lt => a < b
+    | Lte => a <= b
+    | Gt => a > b
+    | Gte => a >= b
+    | Contains => false
+    }
+  switch (actual, expected) {
+  | (String(a), Text(b)) => op == Contains ? a->String.includes(b) : ordered(a, b)
+  | (Number(a), Number(b)) => ordered(a, b)
+  | (Boolean(a), Flag(b)) =>
+    switch op {
+    | Eq => a == b
+    | Ne => a != b
+    | _ => false
+    }
+  | (Array(items), Text(b)) =>
+    op == Contains &&
+      items->Array.some(item =>
+        switch item {
+        | String(text) => text == b
+        | _ => false
+        }
+      )
+  | _ => false
+  }
+}
+
+let rec matches = (predicate: predicate, ~payload: JSON.t): bool =>
+  switch predicate {
+  | Always => true
+  | Compare({path, op, value}) =>
+    switch Reventless.Template.lookup(payload, path) {
+    | Some(actual) => compare(actual, op, value)
+    | None => false
+    }
+  | All(parts) => parts->Array.every(part => matches(part, ~payload))
+  | Any(parts) => parts->Array.some(part => matches(part, ~payload))
+  | Not(part) => !matches(part, ~payload)
+  }
+
+let stringAt = (payload: JSON.t, path: string) =>
+  switch Reventless.Template.lookup(payload, path) {
+  | Some(String(text)) => Some(text)
+  | _ => None
+  }
+
+/** Who to notify. `None` is a rule whose path does not name a person in this
+    payload, which is a rule that cannot be acted on rather than one that sends
+    to nobody. */
+let recipientOf = (rule: t, ~payload: JSON.t) => stringAt(payload, rule.recipientPath)
+
+/** What it is about. Empty is legal — a notification about nothing in particular
+    is a real case, and a fabricated subject is worse than an absent one. */
+let subjectOf = (rule: t, ~payload: JSON.t) =>
+  stringAt(payload, rule.subjectPath)->Option.getOr("")
+
+/** The wording to use, the asked-for locale if the rule has it and the first
+    otherwise. Which locale to ask for is the caller's — nothing here knows who
+    is being written to. */
+let contentFor = (rule: t, ~locale: option<string>=?) =>
+  switch locale {
+  | Some(wanted) =>
+    switch rule.content->Array.find(entry => entry.locale == wanted) {
+    | Some(_) as found => found
+    | None => rule.content->Array.get(0)
+    }
+  | None => rule.content->Array.get(0)
+  }
+
+// A template that does not parse falls back to its own source: the renderer's
+// posture is that a fault is visible rather than silent, and `validate` is what
+// keeps a compiled table from reaching this.
+let render = (source: string, ~payload: JSON.t, ~schema: S.t<'a>) =>
+  Reventless.Template.renderSource(source, ~payload, ~schema)->Result.getOr(source)
+
+/** The rendered `(subject, body)`. */
+let compose = (rule: t, ~payload: JSON.t, ~schema: S.t<'a>, ~locale: option<string>=?) =>
+  switch contentFor(rule, ~locale?) {
+  | None => ("", "")
+  | Some({subject, body}) => (
+      render(subject, ~payload, ~schema),
+      render(body, ~payload, ~schema),
+    )
+  }
+
+/**
+The problems in a table, empty when it is sound.
+
+What a compiled table's own test asserts, so `compose`'s fallbacks and
+`recipientOf`'s `None` stay unreachable in a build rather than merely unlikely.
+`sample` is one payload of the shape the table's rules read.
+
+`~digestRouted` says whether this deployment has a component that gathers
+digests. It defaults to `false` because most do not, and there a `Digest` rule is
+a rule whose occurrences the per-event relay passes over and nobody else picks
+up — silence, which is the failure this competency is careful about everywhere
+else.
+*/
+let validate = (rules: array<t>, ~digestRouted: bool=false, ~sample: JSON.t): array<string> =>
+  rules->Array.flatMap(rule => {
+    let problems = []
+    let note = message => problems->Array.push(`${rule.id}: ${message}`)
+    if rule.id == "" {
+      note("a rule needs an id — it is the namespace of every reference it writes")
+    }
+    if Array.length(rule.content) == 0 {
+      note("no wording at all")
+    }
+    rule.content->Array.forEach(({locale, subject, body}) =>
+      [("subject", subject), ("body", body)]->Array.forEach(((which, template)) =>
+        switch Reventless.Template.parse(template) {
+        | Ok(_) => ()
+        | Error(why) => note(`${locale} ${which} does not parse — ${why}`)
+        }
+      )
+    )
+    if recipientOf(rule, ~payload=sample) == None {
+      note(`recipientPath "${rule.recipientPath}" names nobody in the sample payload`)
+    }
+    if stringAt(sample, rule.subjectPath) == None {
+      note(`subjectPath "${rule.subjectPath}" resolves to nothing in the sample payload`)
+    }
+    switch rule.delivery {
+    | Immediate => ()
+    | Digest({windowSeconds}) =>
+      if !digestRouted {
+        note("delivered as a digest, and nothing in this deployment gathers one")
+      }
+      if windowSeconds <= 0 {
+        note(`a digest window of ${windowSeconds->Int.toString}s gathers nothing`)
+      }
+    }
+    problems
+  })