@reventlessdev/reventless-spec 3.0.0-alpha.154 → 3.0.0-alpha.156

package/src/types/Environments.res

@@ -0,0 +1,230 @@
+/***
+The environments an app deploys to, as a file: `environments.yaml`, beside its
+`deploy-manifest.yaml`.
+
+```yaml
+environments:
+  - { name: review,     purpose: review,     pullRequestsInto: dev }
+  - { name: dev,        purpose: dev,        branch: dev }
+  - { name: test,       purpose: test,       branch: test }
+  - { name: production, purpose: production, branch: main, tags: "v*", stack: prod }
+  - { name: demo,       purpose: demo,       tags: "v*" }
+```
+
+A *shared* environment has one stack and is fed by a branch, by tags, or by both.
+A *review* environment is fed by the pull requests into one branch and has one
+stack per open pull request, named `<name>-pr-<number>`.
+
+Here rather than in the AWS package because more than the deploy reads it: a
+tool that shows which commit runs where needs the same answer to *which branch
+feeds which environment* as the workflow that deploys, and a second reading of
+the file is how the two would come to disagree.
+
+The file is optional. Without it a deploy uses the branch name as the stack, as
+it always has; nothing here is consulted.
+*/
+
+/**
+What an environment is for. `Other` keeps a team's own word rather than refusing
+the file, because a purpose nothing here branches on costs nothing to carry.
+*/
+type purpose =
+  | Dev
+  | Test
+  | Production
+  | Demo
+  | Review
+  | Other(string)
+
+let purposeSchema: S.t<purpose> = S.union([
+  S.literal("dev")->S.shape(_ => Dev),
+  S.literal("test")->S.shape(_ => Test),
+  S.literal("production")->S.shape(_ => Production),
+  S.literal("demo")->S.shape(_ => Demo),
+  S.literal("review")->S.shape(_ => Review),
+  S.string->S.shape(other => Other(other)),
+])
+
+let purposeName = (purpose: purpose): string =>
+  switch purpose {
+  | Dev => "dev"
+  | Test => "test"
+  | Production => "production"
+  | Demo => "demo"
+  | Review => "review"
+  | Other(name) => name
+  }
+
+/** One entry as the file spells it. [parseString] turns it into an [environment]. */
+@schema
+type entry = {
+  name: string,
+  purpose: @s.matches(purposeSchema) purpose,
+  branch?: string,
+  tags?: string,
+  stack?: string,
+  pullRequestsInto?: string,
+  drafts?: bool,
+}
+
+@schema
+type file = {environments: array<entry>}
+
+/** What feeds an environment, and so how many stacks it has. */
+type feed =
+  | Shared({branch: option<string>, tags: option<string>, stack: string})
+  | ReviewOf({into: string, drafts: bool})
+
+type environment = {name: string, purpose: purpose, feed: feed}
+
+type t = array<environment>
+
+// ── Reading ──────────────────────────────────────────────────────────────────
+
+@module("yaml") external parseYaml: string => JSON.t = "parse"
+@module("yaml") external stringifyYaml: JSON.t => string = "stringify"
+
+let environmentOf = (entry: entry): result<environment, string> =>
+  switch (entry.pullRequestsInto, entry.branch, entry.tags) {
+  | (Some(_), Some(_), _) | (Some(_), _, Some(_)) =>
+    Error(`${entry.name}: pullRequestsInto cannot be combined with branch or tags`)
+  | (Some(_), None, None) if entry.stack->Option.isSome =>
+    Error(`${entry.name}: a review environment names its stacks itself; remove stack`)
+  | (Some(into), None, None) =>
+    Ok({
+      name: entry.name,
+      purpose: entry.purpose,
+      feed: ReviewOf({into, drafts: entry.drafts->Option.getOr(false)}),
+    })
+  | (None, None, None) =>
+    Error(`${entry.name}: says neither branch, tags nor pullRequestsInto, so nothing feeds it`)
+  | (None, _, _) if entry.drafts->Option.isSome =>
+    Error(`${entry.name}: drafts is only meaningful with pullRequestsInto`)
+  | (None, branch, tags) =>
+    Ok({
+      name: entry.name,
+      purpose: entry.purpose,
+      feed: Shared({branch, tags, stack: entry.stack->Option.getOr(entry.name)}),
+    })
+  }
+
+/** Parses an environments document. Strict, like the accounts manifest: a
+  malformed entry refuses the whole file, because a skipped environment is a
+  branch that silently stops deploying. */
+let parseString = (yamlText: string): result<t, string> =>
+  switch try Ok(S.parseOrThrow(parseYaml(yamlText), ~to=fileSchema)) catch {
+  | JsExn(err) => Error(JsExn.message(err)->Option.getOr("YAML parse error"))
+  | _ => Error("YAML parse error")
+  } {
+  | Error(_) as e => e
+  | Ok({environments}) =>
+    let names = environments->Array.map(e => e.name)
+    switch names->Array.find(n => names->Array.filter(m => m == n)->Array.length > 1) {
+    | Some(duplicate) => Error(`${duplicate}: named twice`)
+    | None =>
+      environments->Array.reduce(Ok([]), (acc, entry) =>
+        switch (acc, environmentOf(entry)) {
+        | (Error(_) as e, _) => e
+        | (Ok(_), Error(message)) => Error(message)
+        | (Ok(done), Ok(environment)) => Ok(done->Array.concat([environment]))
+        }
+      )
+    }
+  }
+
+let parseFile = (path: string): result<t, string> =>
+  try {
+    parseString(NodeFs.readFileSync(path))
+  } catch {
+  | JsExn(err) => Error(JsExn.message(err)->Option.getOr(`Cannot read ${path}`))
+  | _ => Error(`Cannot read ${path}`)
+  }
+
+let entryOf = (environment: environment): entry =>
+  switch environment.feed {
+  | Shared({branch, tags, stack}) => {
+      name: environment.name,
+      purpose: environment.purpose,
+      ?branch,
+      ?tags,
+      stack: ?(stack == environment.name ? None : Some(stack)),
+    }
+  | ReviewOf({into, drafts}) => {
+      name: environment.name,
+      purpose: environment.purpose,
+      pullRequestsInto: into,
+      drafts: ?(drafts ? Some(true) : None),
+    }
+  }
+
+/** The document for a set of environments. Comments are not kept: this writes a
+  new file, it does not edit one. */
+let print = (environments: t): string =>
+  {environments: environments->Array.map(entryOf)}->Util_Sury.toJson(fileSchema)->stringifyYaml
+
+/** Where a deploy looks for it: beside the deploy manifest. */
+let fileName = "environments.yaml"
+
+let pathBeside = (~manifest: string): string =>
+  NodePath.join([NodePath.dirname(manifest), fileName])
+
+// ── Resolving ────────────────────────────────────────────────────────────────
+
+/**
+A branch or tag pattern as GitHub's workflow filters spell them: `*` matches
+within one path segment, `**` across segments. Nothing else is special.
+*/
+let matches = (~pattern: string, name: string): bool => {
+  let escaped =
+    pattern
+    ->String.split("**")
+    ->Array.map(part =>
+      part
+      ->String.replaceRegExp(/[.+?^${}()|[\]\\]/g, "\\$&")
+      ->String.replaceAll("*", "[^/]*")
+    )
+    ->Array.join(".*")
+  RegExp.fromString(`^${escaped}$`)->RegExp.test(name)
+}
+
+/** What a push or a tag deploys to. */
+type ref_ =
+  | Branch(string)
+  | Tag(string)
+
+/** `refs/heads/test` and `refs/tags/v1`; anything else is not deployable. */
+let refOf = (ref: string): option<ref_> =>
+  if ref->String.startsWith("refs/heads/") {
+    Some(Branch(ref->String.slice(~start=11)))
+  } else if ref->String.startsWith("refs/tags/") {
+    Some(Tag(ref->String.slice(~start=10)))
+  } else {
+    None
+  }
+
+type resolved = {name: string, stack: string, purpose: purpose}
+
+/** The first shared environment, in file order, that the branch or tag feeds. */
+let resolve = (environments: t, ref: ref_): option<resolved> =>
+  environments->Array.findMap(({name, purpose, feed}) =>
+    switch (feed, ref) {
+    | (Shared({branch: Some(pattern), stack}), Branch(branch)) if matches(~pattern, branch) =>
+      Some({name, stack, purpose})
+    | (Shared({tags: Some(pattern), stack}), Tag(tag)) if matches(~pattern, tag) =>
+      Some({name, stack, purpose})
+    | (Shared(_), _) | (ReviewOf(_), _) => None
+    }
+  )
+
+/** The review stack of one pull request, if the branch it targets has a review
+  environment. `draft` pull requests get one only where the environment asks. */
+let resolvePullRequest = (environments: t, ~base: string, ~number: int, ~draft: bool): option<
+  resolved,
+> =>
+  environments->Array.findMap(({name, purpose, feed}) =>
+    switch feed {
+    | ReviewOf({into, drafts}) if matches(~pattern=into, base) && (drafts || !draft) =>
+      Some({name, stack: `${name}-pr-${number->Int.toString}`, purpose})
+    | ReviewOf(_) | Shared(_) => None
+    }
+  )

package/src/types/Environments.res.mjs

@@ -0,0 +1,314 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Sury from "sury";
+import * as Yaml from "yaml";
+import * as Nodefs from "node:fs";
+import * as Nodepath from "node:path";
+import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
+import * as Stdlib_JsExn from "@rescript/runtime/lib/es6/Stdlib_JsExn.js";
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+import * as Primitive_exceptions from "@rescript/runtime/lib/es6/Primitive_exceptions.js";
+import * as Util_Sury$Reventless from "../util/Util_Sury.res.mjs";
+
+let purposeSchema = Sury.union([
+  Sury.shape(Sury.literal("dev"), param => "Dev"),
+  Sury.shape(Sury.literal("test"), param => "Test"),
+  Sury.shape(Sury.literal("production"), param => "Production"),
+  Sury.shape(Sury.literal("demo"), param => "Demo"),
+  Sury.shape(Sury.literal("review"), param => "Review"),
+  Sury.shape(Sury.string, other => ({
+    TAG: "Other",
+    _0: other
+  }))
+]);
+
+function purposeName(purpose) {
+  if (typeof purpose === "object") {
+    return purpose._0;
+  }
+  switch (purpose) {
+    case "Dev" :
+      return "dev";
+    case "Test" :
+      return "test";
+    case "Production" :
+      return "production";
+    case "Demo" :
+      return "demo";
+    case "Review" :
+      return "review";
+  }
+}
+
+let entrySchema = Sury.$schema(s => ({
+  name: s.m(Sury.string),
+  purpose: s.m(purposeSchema),
+  branch: s.m(Sury.$option(Sury.string)),
+  tags: s.m(Sury.$option(Sury.string)),
+  stack: s.m(Sury.$option(Sury.string)),
+  pullRequestsInto: s.m(Sury.$option(Sury.string)),
+  drafts: s.m(Sury.$option(Sury.boolean))
+}));
+
+let fileSchema = Sury.$schema(s => ({
+  environments: s.m(Sury.array(entrySchema))
+}));
+
+function environmentOf(entry) {
+  let match = entry.pullRequestsInto;
+  let match$1 = entry.branch;
+  let match$2 = entry.tags;
+  if (match !== undefined) {
+    if (match$1 === undefined && match$2 === undefined) {
+      if (Stdlib_Option.isSome(entry.stack)) {
+        return {
+          TAG: "Error",
+          _0: entry.name + `: a review environment names its stacks itself; remove stack`
+        };
+      } else {
+        return {
+          TAG: "Ok",
+          _0: {
+            name: entry.name,
+            purpose: entry.purpose,
+            feed: {
+              TAG: "ReviewOf",
+              into: match,
+              drafts: Stdlib_Option.getOr(entry.drafts, false)
+            }
+          }
+        };
+      }
+    }
+  } else {
+    let exit = 0;
+    if (match$1 !== undefined) {
+      exit = 2;
+    } else {
+      if (match$2 === undefined) {
+        return {
+          TAG: "Error",
+          _0: entry.name + `: says neither branch, tags nor pullRequestsInto, so nothing feeds it`
+        };
+      }
+      exit = 2;
+    }
+    if (exit === 2) {
+      if (Stdlib_Option.isSome(entry.drafts)) {
+        return {
+          TAG: "Error",
+          _0: entry.name + `: drafts is only meaningful with pullRequestsInto`
+        };
+      } else {
+        return {
+          TAG: "Ok",
+          _0: {
+            name: entry.name,
+            purpose: entry.purpose,
+            feed: {
+              TAG: "Shared",
+              branch: match$1,
+              tags: match$2,
+              stack: Stdlib_Option.getOr(entry.stack, entry.name)
+            }
+          }
+        };
+      }
+    }
+  }
+  return {
+    TAG: "Error",
+    _0: entry.name + `: pullRequestsInto cannot be combined with branch or tags`
+  };
+}
+
+function parseString(yamlText) {
+  let e;
+  try {
+    e = {
+      TAG: "Ok",
+      _0: Sury.parseOrThrow(Yaml.parse(yamlText), fileSchema)
+    };
+  } catch (raw_err) {
+    let err = Primitive_exceptions.internalToException(raw_err);
+    e = err.RE_EXN_ID === "JsExn" ? ({
+        TAG: "Error",
+        _0: Stdlib_Option.getOr(Stdlib_JsExn.message(err._1), "YAML parse error")
+      }) : ({
+        TAG: "Error",
+        _0: "YAML parse error"
+      });
+  }
+  if (e.TAG !== "Ok") {
+    return e;
+  }
+  let environments = e._0.environments;
+  let names = environments.map(e => e.name);
+  let duplicate = names.find(n => names.filter(m => m === n).length > 1);
+  if (duplicate !== undefined) {
+    return {
+      TAG: "Error",
+      _0: duplicate + `: named twice`
+    };
+  } else {
+    return Stdlib_Array.reduce(environments, {
+      TAG: "Ok",
+      _0: []
+    }, (acc, entry) => {
+      let match = environmentOf(entry);
+      if (acc.TAG === "Ok") {
+        if (match.TAG === "Ok") {
+          return {
+            TAG: "Ok",
+            _0: acc._0.concat([match._0])
+          };
+        } else {
+          return {
+            TAG: "Error",
+            _0: match._0
+          };
+        }
+      } else {
+        return acc;
+      }
+    });
+  }
+}
+
+function parseFile(path) {
+  try {
+    return parseString(Nodefs.readFileSync(path, "utf8"));
+  } catch (raw_err) {
+    let err = Primitive_exceptions.internalToException(raw_err);
+    if (err.RE_EXN_ID === "JsExn") {
+      return {
+        TAG: "Error",
+        _0: Stdlib_Option.getOr(Stdlib_JsExn.message(err._1), `Cannot read ` + path)
+      };
+    } else {
+      return {
+        TAG: "Error",
+        _0: `Cannot read ` + path
+      };
+    }
+  }
+}
+
+function entryOf(environment) {
+  let match = environment.feed;
+  if (match.TAG !== "Shared") {
+    return {
+      name: environment.name,
+      purpose: environment.purpose,
+      pullRequestsInto: match.into,
+      drafts: match.drafts ? true : undefined
+    };
+  }
+  let stack = match.stack;
+  return {
+    name: environment.name,
+    purpose: environment.purpose,
+    branch: match.branch,
+    tags: match.tags,
+    stack: stack === environment.name ? undefined : stack
+  };
+}
+
+function print(environments) {
+  return Yaml.stringify(Util_Sury$Reventless.toJson({
+    environments: environments.map(entryOf)
+  }, fileSchema));
+}
+
+let fileName = "environments.yaml";
+
+function pathBeside(manifest) {
+  return Nodepath.join(Nodepath.dirname(manifest), fileName);
+}
+
+function matches(pattern, name) {
+  let escaped = pattern.split("**").map(part => part.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replaceAll("*", "[^/]*")).join(".*");
+  return new RegExp(`^` + escaped + `$`).test(name);
+}
+
+function refOf(ref) {
+  if (ref.startsWith("refs/heads/")) {
+    return {
+      TAG: "Branch",
+      _0: ref.slice(11)
+    };
+  } else if (ref.startsWith("refs/tags/")) {
+    return {
+      TAG: "Tag",
+      _0: ref.slice(10)
+    };
+  } else {
+    return;
+  }
+}
+
+function resolve(environments, ref) {
+  return Stdlib_Array.findMap(environments, param => {
+    let feed = param.feed;
+    let purpose = param.purpose;
+    let name = param.name;
+    if (feed.TAG !== "Shared") {
+      return;
+    }
+    let pattern = feed.branch;
+    if (pattern !== undefined && ref.TAG === "Branch") {
+      if (matches(pattern, ref._0)) {
+        return {
+          name: name,
+          stack: feed.stack,
+          purpose: purpose
+        };
+      } else {
+        return;
+      }
+    }
+    let pattern$1 = feed.tags;
+    if (pattern$1 !== undefined && ref.TAG !== "Branch" && matches(pattern$1, ref._0)) {
+      return {
+        name: name,
+        stack: feed.stack,
+        purpose: purpose
+      };
+    }
+  });
+}
+
+function resolvePullRequest(environments, base, number, draft) {
+  return Stdlib_Array.findMap(environments, param => {
+    let feed = param.feed;
+    let name = param.name;
+    if (feed.TAG === "Shared" || !(matches(feed.into, base) && (feed.drafts || !draft))) {
+      return;
+    } else {
+      return {
+        name: name,
+        stack: name + `-pr-` + number.toString(),
+        purpose: param.purpose
+      };
+    }
+  });
+}
+
+export {
+  purposeSchema,
+  purposeName,
+  entrySchema,
+  fileSchema,
+  environmentOf,
+  parseString,
+  parseFile,
+  entryOf,
+  print,
+  fileName,
+  pathBeside,
+  matches,
+  refOf,
+  resolve,
+  resolvePullRequest,
+}
+/* purposeSchema Not a pure module */

package/src/types/Message.res

@@ -2,6 +2,23 @@
 @schema
 type service = string
 
+/**
+The issuing caller, classified for `@owner` enforcement (`OwnerScope.toClaim`).
+
+Written only by the command generator, from the authenticated identity, so a
+handler can tell an owner from an operator without seeing the caller's groups.
+Absent on every command that did not come through the generator — an
+automation's follow-up, an internal dispatch — which a handler reads as the
+platform acting for itself.
+*/
+module CallerClaim = {
+  @schema
+  type t =
+    | Owned({userId: string})
+    | Exempt
+    | Unidentified
+}
+
 /**
 Envelope metadata attached to every event and command.
 
@@ -50,6 +67,10 @@ type meta = {
   /** Extensible header bag for cross-cutting context (tenantId, feature flags, etc.).
       Absent when empty — consumers normalise with `->Option.getOr(Dict.make())`. */
   headers?: dict<string>,
+  /** Commands only: the caller as the generator classified it. Deliberately not
+      inherited by `deriveMeta`, so an event or a follow-up command never carries
+      the claim of the command that caused it. */
+  callerClaim?: CallerClaim.t,
 }
 
 /**

package/src/types/Message.res.mjs

@@ -6,6 +6,19 @@ import * as Util_Sury$Reventless from "../util/Util_Sury.res.mjs";
 
 let serviceSchema = Sury.string;
 
+let schema = Sury.union([
+  Sury.$schema(s => ({
+    TAG: "Owned",
+    userId: s.m(Sury.string)
+  })),
+  Sury.literal("Exempt"),
+  Sury.literal("Unidentified")
+]);
+
+let CallerClaim = {
+  schema: schema
+};
+
 let metaSchema = Sury.$schema(s => ({
   service: s.m(serviceSchema),
   time: s.m(Sury.string),
@@ -16,7 +29,8 @@ let metaSchema = Sury.$schema(s => ({
   causationId: s.m(Sury.$option(Sury.string)),
   traceparent: s.m(Sury.$option(Sury.string)),
   schemaVersion: s.m(Sury.$option(Sury.string)),
-  headers: s.m(Sury.$option(Sury.record(Sury.string)))
+  headers: s.m(Sury.$option(Sury.record(Sury.string))),
+  callerClaim: s.m(Sury.$option(schema))
 }));
 
 let contextSchema = Sury.$schema(s => ({
@@ -189,6 +203,7 @@ function composeEventJson$p(id, meta, eventJson) {
 
 export {
   serviceSchema,
+  CallerClaim,
   metaSchema,
   contextSchema,
   statusChangeSchema,