@reventlessdev/reventless-aws 3.0.0-alpha.239 → 3.0.0-alpha.241

package/src/util/Util_StoreLayout.res

@@ -0,0 +1,136 @@
+// How a stack lays out the object stores its plugins declare, and how hard it
+// protects them. Pure functions so both decisions are decidable and unit-
+// testable without touching Pulumi — the same shape `Util_HostUiDomain` uses
+// for the host-shell FQDN.
+//
+// Two decisions, deliberately independent:
+//
+//   layout      — one bucket per store, or one bucket per stack with `{store}/…`
+//                 prefixes inside it
+//   protection  — whether an accidental removal may destroy the store
+//
+// It is tempting to make one switch decide both, and that is wrong. `alpha`
+// shares a bucket *and* holds hand-entered data worth protecting; a `pr-*`
+// stack shares a bucket and must be destroyable or teardown leaks exactly the
+// buckets sharing exists to save. Layout answers "how many buckets"; protection
+// answers "is this data disposable". Those are different questions about the
+// same stack.
+//
+// Why production alone gets per-store buckets: the growth term is
+// `plugins × stores × stacks`, and stacks is the factor that actually grows —
+// the stack allowlist admits `pr-*`, so per-PR environments multiply every
+// plugin's every store against a 100-bucket account default. Production does
+// not multiply. It is also the only environment where a bucket boundary (rather
+// than a prefix boundary) is worth its cost, since the honest price of sharing
+// is that per-store least-privilege degrades from a bucket ARN to a prefix ARN.
+
+/** How many buckets a stack's declared stores get. */
+type t =
+  | PerStore
+  | SharedBucket
+
+/** Whether a store may be destroyed by an accidental removal. */
+type protection =
+  | Protected
+  | Unprotected
+
+/** Which distribution fronts the declared stores. */
+type serving =
+  /** No store is declared, so nothing is served. */
+  | NoStores
+  /** The host shell's own distribution serves them same-origin, so a minted
+      `/{prefix}/…` ref resolves relative and there is no base URL. */
+  | HostShell
+  /** The platform fronts them itself, because no host shell is deployed. */
+  | PlatformOwned
+
+/**
+Stack-name prefixes whose stacks are disposable.
+
+`pr-*` matches the stack allowlist's per-PR environments. A prefix rather than
+an exact list because the whole point of these stacks is that nobody enumerates
+them in advance.
+*/
+let defaultEphemeralPrefixes = ["pr-"]
+
+/**
+Production gets a bucket per store; every other stack shares one.
+
+`prodStacks` comes from `Util_HostUiDomain.resolveProdStacks` — the same notion
+of "production" that names the host-shell domain, on purpose.
+
+Note this polarity **fails open**: a new production stack whose name is not on
+the list (`production`, `live`, `prod-eu`) silently gets the weaker layout and
+nothing errors. That is the accepted cost of keying off a name allowlist, paid
+down by the list being config-overridable and by the deploy logging the layout
+it chose — a silent fail-open is only dangerous while it is silent.
+*/
+let layoutFor = (~stack: string, ~prodStacks: array<string>): t =>
+  prodStacks->Array.includes(stack) ? PerStore : SharedBucket
+
+/**
+Destroy semantics follow disposability, **not** layout.
+
+`alpha` shares a bucket and is still protected: it declares
+`reventless:wipeable`, but that authorises the reset tool to empty stores
+*deliberately*, after a scope prompt and a typed confirmation. It does not say a
+field rename may destroy a bucket by accident. Only stacks that are routinely
+torn down are unprotected.
+*/
+let protectionFor = (~stack: string, ~ephemeralPrefixes: array<string>=defaultEphemeralPrefixes): protection =>
+  ephemeralPrefixes->Array.some(p => stack->String.startsWith(p)) ? Unprotected : Protected
+
+/**
+The bucket a store's objects live in.
+
+Per-store: `{plugin}-{store}`, so the physical name traces back to the
+declaration that required it — a store rename becomes a visible replace in
+review rather than a silent one. Shared: one `{stack}-stores` bucket for every
+declared store on the stack.
+
+Pulumi appends its own suffix for global uniqueness, so neither form has to
+carry an account or region discriminator.
+*/
+let bucketNameFor = (~layout: t, ~stack: string, ~plugin: string, ~store: string): string =>
+  switch layout {
+  | PerStore => `${plugin}-${store}`
+  | SharedBucket => `${stack}-stores`
+  }
+
+/**
+The prefix a store's object keys are rooted at — the store name, in **both**
+layouts.
+
+This is the property that keeps the two layouts one model rather than a fork.
+The presign service mints `{store}/{identity}{uuid}/{file}` either way, so the
+stored ref is `/{store}/…` regardless of which bucket sits behind it, and only
+the CDN origin differs. Refs live in an append-only event log: one that encoded
+its bucket layout would be environment-specific and unrewritable, so a prod dump
+restored into a PR stack would carry refs that cannot resolve.
+
+The cost is a slightly redundant prefix inside a dedicated bucket
+(`catalog-productImages/productImages/…`). Take the redundancy.
+*/
+let keyPrefixFor = (~store: string): string => store
+
+/**
+Who serves the declared stores — and the answer is never "both".
+
+A store's bucket blocks public policy and takes its read grant solely from a
+distribution's `BucketPolicy`. **S3 permits exactly one bucket policy per
+bucket**, so two distributions fronting one store would each write that single
+policy and silently unpick the other's grant: green deploy, 404s afterwards.
+Making this one function's return a three-way choice is what keeps "both" from
+being expressible.
+
+The polarity is the useful part. Provisioning a store and serving it are
+separate; before this, serving happened only as a side car to a host-UI bundle,
+so a platform whose UI shipped from its own stack provisioned stores that
+nothing could read.
+*/
+let servingFor = (~hasHostUiBundle: bool, ~declaredBucketCount: int): serving =>
+  switch (hasHostUiBundle, declaredBucketCount) {
+  | (_, 0) => NoStores
+  | (true, _) => HostShell
+  | (false, _) => PlatformOwned
+  }

package/src/util/Util_StoreLayout.res.mjs

@@ -0,0 +1,55 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+
+let defaultEphemeralPrefixes = ["pr-"];
+
+function layoutFor(stack, prodStacks) {
+  if (prodStacks.includes(stack)) {
+    return "PerStore";
+  } else {
+    return "SharedBucket";
+  }
+}
+
+function protectionFor(stack, ephemeralPrefixesOpt) {
+  let ephemeralPrefixes = ephemeralPrefixesOpt !== undefined ? ephemeralPrefixesOpt : defaultEphemeralPrefixes;
+  if (ephemeralPrefixes.some(p => stack.startsWith(p))) {
+    return "Unprotected";
+  } else {
+    return "Protected";
+  }
+}
+
+function bucketNameFor(layout, stack, plugin, store) {
+  if (layout === "PerStore") {
+    return plugin + `-` + store;
+  } else {
+    return stack + `-stores`;
+  }
+}
+
+function keyPrefixFor(store) {
+  return store;
+}
+
+function servingFor(hasHostUiBundle, declaredBucketCount) {
+  if (declaredBucketCount !== 0) {
+    if (hasHostUiBundle) {
+      return "HostShell";
+    } else {
+      return "PlatformOwned";
+    }
+  } else {
+    return "NoStores";
+  }
+}
+
+export {
+  defaultEphemeralPrefixes,
+  layoutFor,
+  protectionFor,
+  bucketNameFor,
+  keyPrefixFor,
+  servingFor,
+}
+/* No side effect */

package/tests/Util_StoreLayoutTest.res

@@ -0,0 +1,155 @@
+open JestGlobals
+
+let prodStacks = Util_HostUiDomain.defaultProdStacks
+
+describe("Util_StoreLayout.layoutFor", () => {
+  testSync("a prod-named stack gets a bucket per store", () =>
+    expect(Util_StoreLayout.layoutFor(~stack="prod", ~prodStacks))->toEqual(Util_StoreLayout.PerStore)
+  )
+
+  testSync("'main' is production too, by the shared prod list", () =>
+    expect(Util_StoreLayout.layoutFor(~stack="main", ~prodStacks))->toEqual(Util_StoreLayout.PerStore)
+  )
+
+  testSync("alpha shares one bucket", () =>
+    expect(Util_StoreLayout.layoutFor(~stack="alpha", ~prodStacks))->toEqual(
+      Util_StoreLayout.SharedBucket,
+    )
+  )
+
+  testSync("a PR stack shares one bucket — the factor that multiplies", () =>
+    expect(Util_StoreLayout.layoutFor(~stack="pr-1234", ~prodStacks))->toEqual(
+      Util_StoreLayout.SharedBucket,
+    )
+  )
+
+  // The accepted fail-open: a production stack whose name is not on the list
+  // gets the weaker layout silently. Asserted so the behaviour is a decision on
+  // record rather than a surprise, and so the config override is the documented
+  // fix rather than a code change.
+  testSync("an unlisted production name falls open to the shared layout", () =>
+    expect(Util_StoreLayout.layoutFor(~stack="production", ~prodStacks))->toEqual(
+      Util_StoreLayout.SharedBucket,
+    )
+  )
+
+  testSync("adding it to the prod list is the fix", () =>
+    expect(Util_StoreLayout.layoutFor(~stack="production", ~prodStacks=["prod", "production"]))->toEqual(
+      Util_StoreLayout.PerStore,
+    )
+  )
+})
+
+describe("Util_StoreLayout.servingFor", () => {
+  testSync("no declared store means nothing to serve", () =>
+    expect(Util_StoreLayout.servingFor(~hasHostUiBundle=false, ~declaredBucketCount=0))->toEqual(
+      Util_StoreLayout.NoStores,
+    )
+  )
+
+  testSync("a host shell serves the stores from its own origin", () =>
+    expect(Util_StoreLayout.servingFor(~hasHostUiBundle=true, ~declaredBucketCount=1))->toEqual(
+      Util_StoreLayout.HostShell,
+    )
+  )
+
+  // The case that was previously unrepresentable and produced a write-only
+  // store: stores are provisioned unconditionally, but serving used to happen
+  // only as a side car to a host-UI bundle.
+  testSync("no host shell means the platform serves them itself", () =>
+    expect(Util_StoreLayout.servingFor(~hasHostUiBundle=false, ~declaredBucketCount=1))->toEqual(
+      Util_StoreLayout.PlatformOwned,
+    )
+  )
+
+  // A bucket carries exactly one policy, so two distributions fronting one
+  // store would unpick each other's read grant. The three-way return is what
+  // makes "both" unrepresentable — asserted so it stays that way.
+  testSync("a host shell wins even with several buckets — never both", () =>
+    expect(Util_StoreLayout.servingFor(~hasHostUiBundle=true, ~declaredBucketCount=3))->toEqual(
+      Util_StoreLayout.HostShell,
+    )
+  )
+
+  // Declaring nothing outranks having a shell: with no store there is no
+  // bucket, no policy and no origin, whoever is deployed.
+  testSync("no store outranks a host shell", () =>
+    expect(Util_StoreLayout.servingFor(~hasHostUiBundle=true, ~declaredBucketCount=0))->toEqual(
+      Util_StoreLayout.NoStores,
+    )
+  )
+})
+
+describe("Util_StoreLayout.protectionFor", () => {
+  // The pairing a single layout-driven switch would have got wrong: alpha
+  // shares a bucket and is still protected.
+  testSync("alpha shares a bucket and is still protected", () => {
+    expect(Util_StoreLayout.layoutFor(~stack="alpha", ~prodStacks))->toEqual(
+      Util_StoreLayout.SharedBucket,
+    )
+    expect(Util_StoreLayout.protectionFor(~stack="alpha"))->toEqual(Util_StoreLayout.Protected)
+  })
+
+  testSync("prod is protected", () =>
+    expect(Util_StoreLayout.protectionFor(~stack="prod"))->toEqual(Util_StoreLayout.Protected)
+  )
+
+  testSync("a PR stack is unprotected so teardown does not leak buckets", () =>
+    expect(Util_StoreLayout.protectionFor(~stack="pr-42"))->toEqual(Util_StoreLayout.Unprotected)
+  )
+
+  testSync("'prepare' is not a PR stack — the prefix is 'pr-', not 'pr'", () =>
+    expect(Util_StoreLayout.protectionFor(~stack="prepare"))->toEqual(Util_StoreLayout.Protected)
+  )
+})
+
+describe("Util_StoreLayout.bucketNameFor", () => {
+  testSync("per-store names the bucket after the declaration", () =>
+    expect(
+      Util_StoreLayout.bucketNameFor(
+        ~layout=PerStore,
+        ~stack="prod",
+        ~plugin="catalog",
+        ~store="productImages",
+      ),
+    )->toBe("catalog-productImages")
+  )
+
+  testSync("shared names one bucket per stack", () =>
+    expect(
+      Util_StoreLayout.bucketNameFor(
+        ~layout=SharedBucket,
+        ~stack="alpha",
+        ~plugin="catalog",
+        ~store="productImages",
+      ),
+    )->toBe("alpha-stores")
+  )
+
+  testSync("every store on a shared stack lands in the same bucket", () =>
+    expect(
+      Util_StoreLayout.bucketNameFor(
+        ~layout=SharedBucket,
+        ~stack="alpha",
+        ~plugin="ordering",
+        ~store="invoices",
+      ),
+    )->toBe(
+      Util_StoreLayout.bucketNameFor(
+        ~layout=SharedBucket,
+        ~stack="alpha",
+        ~plugin="catalog",
+        ~store="productImages",
+      ),
+    )
+  )
+})
+
+describe("Util_StoreLayout.keyPrefixFor", () => {
+  // The assertion the whole dual-layout scheme rests on: a ref is
+  // layout-independent, so the same declaration produces the same stored string
+  // on a per-store stack and a shared one.
+  testSync("the key prefix is the store name in both layouts", () =>
+    expect(Util_StoreLayout.keyPrefixFor(~store="productImages"))->toBe("productImages")
+  )
+})

package/tests/Util_StoreLayoutTest.res.mjs

@@ -0,0 +1,87 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Util_StoreLayout$ReventlessAws from "../src/util/Util_StoreLayout.res.mjs";
+import * as Util_HostUiDomain$ReventlessAws from "../src/util/Util_HostUiDomain.res.mjs";
+
+globalThis.describe("Util_StoreLayout.layoutFor", () => {
+  globalThis.test("a prod-named stack gets a bucket per store", () => {
+    globalThis.expect(Util_StoreLayout$ReventlessAws.layoutFor("prod", Util_HostUiDomain$ReventlessAws.defaultProdStacks)).toEqual("PerStore");
+  });
+  globalThis.test("'main' is production too, by the shared prod list", () => {
+    globalThis.expect(Util_StoreLayout$ReventlessAws.layoutFor("main", Util_HostUiDomain$ReventlessAws.defaultProdStacks)).toEqual("PerStore");
+  });
+  globalThis.test("alpha shares one bucket", () => {
+    globalThis.expect(Util_StoreLayout$ReventlessAws.layoutFor("alpha", Util_HostUiDomain$ReventlessAws.defaultProdStacks)).toEqual("SharedBucket");
+  });
+  globalThis.test("a PR stack shares one bucket — the factor that multiplies", () => {
+    globalThis.expect(Util_StoreLayout$ReventlessAws.layoutFor("pr-1234", Util_HostUiDomain$ReventlessAws.defaultProdStacks)).toEqual("SharedBucket");
+  });
+  globalThis.test("an unlisted production name falls open to the shared layout", () => {
+    globalThis.expect(Util_StoreLayout$ReventlessAws.layoutFor("production", Util_HostUiDomain$ReventlessAws.defaultProdStacks)).toEqual("SharedBucket");
+  });
+  globalThis.test("adding it to the prod list is the fix", () => {
+    globalThis.expect(Util_StoreLayout$ReventlessAws.layoutFor("production", [
+      "prod",
+      "production"
+    ])).toEqual("PerStore");
+  });
+});
+
+globalThis.describe("Util_StoreLayout.servingFor", () => {
+  globalThis.test("no declared store means nothing to serve", () => {
+    globalThis.expect(Util_StoreLayout$ReventlessAws.servingFor(false, 0)).toEqual("NoStores");
+  });
+  globalThis.test("a host shell serves the stores from its own origin", () => {
+    globalThis.expect(Util_StoreLayout$ReventlessAws.servingFor(true, 1)).toEqual("HostShell");
+  });
+  globalThis.test("no host shell means the platform serves them itself", () => {
+    globalThis.expect(Util_StoreLayout$ReventlessAws.servingFor(false, 1)).toEqual("PlatformOwned");
+  });
+  globalThis.test("a host shell wins even with several buckets — never both", () => {
+    globalThis.expect(Util_StoreLayout$ReventlessAws.servingFor(true, 3)).toEqual("HostShell");
+  });
+  globalThis.test("no store outranks a host shell", () => {
+    globalThis.expect(Util_StoreLayout$ReventlessAws.servingFor(true, 0)).toEqual("NoStores");
+  });
+});
+
+globalThis.describe("Util_StoreLayout.protectionFor", () => {
+  globalThis.test("alpha shares a bucket and is still protected", () => {
+    globalThis.expect(Util_StoreLayout$ReventlessAws.layoutFor("alpha", Util_HostUiDomain$ReventlessAws.defaultProdStacks)).toEqual("SharedBucket");
+    globalThis.expect(Util_StoreLayout$ReventlessAws.protectionFor("alpha", undefined)).toEqual("Protected");
+  });
+  globalThis.test("prod is protected", () => {
+    globalThis.expect(Util_StoreLayout$ReventlessAws.protectionFor("prod", undefined)).toEqual("Protected");
+  });
+  globalThis.test("a PR stack is unprotected so teardown does not leak buckets", () => {
+    globalThis.expect(Util_StoreLayout$ReventlessAws.protectionFor("pr-42", undefined)).toEqual("Unprotected");
+  });
+  globalThis.test("'prepare' is not a PR stack — the prefix is 'pr-', not 'pr'", () => {
+    globalThis.expect(Util_StoreLayout$ReventlessAws.protectionFor("prepare", undefined)).toEqual("Protected");
+  });
+});
+
+globalThis.describe("Util_StoreLayout.bucketNameFor", () => {
+  globalThis.test("per-store names the bucket after the declaration", () => {
+    globalThis.expect(Util_StoreLayout$ReventlessAws.bucketNameFor("PerStore", "prod", "catalog", "productImages")).toBe("catalog-productImages");
+  });
+  globalThis.test("shared names one bucket per stack", () => {
+    globalThis.expect(Util_StoreLayout$ReventlessAws.bucketNameFor("SharedBucket", "alpha", "catalog", "productImages")).toBe("alpha-stores");
+  });
+  globalThis.test("every store on a shared stack lands in the same bucket", () => {
+    globalThis.expect(Util_StoreLayout$ReventlessAws.bucketNameFor("SharedBucket", "alpha", "ordering", "invoices")).toBe(Util_StoreLayout$ReventlessAws.bucketNameFor("SharedBucket", "alpha", "catalog", "productImages"));
+  });
+});
+
+globalThis.describe("Util_StoreLayout.keyPrefixFor", () => {
+  globalThis.test("the key prefix is the store name in both layouts", () => {
+    globalThis.expect(Util_StoreLayout$ReventlessAws.keyPrefixFor("productImages")).toBe("productImages");
+  });
+});
+
+let prodStacks = Util_HostUiDomain$ReventlessAws.defaultProdStacks;
+
+export {
+  prodStacks,
+}
+/*  Not a pure module */