@reventlessdev/reventless-local 3.0.0-alpha.200 → 3.0.0-alpha.202

package/src/adapter/LocalStateChangeDescriptor.res

@@ -0,0 +1,93 @@
+// Local implementation of the live-update change descriptor — the JSON a
+// subscriber receives on `/default/{listFieldName}/{entityKey}` after a read
+// model row changes.
+//
+//   { changeKind, id, sortKeyValue?, seq, state? }
+//
+// One wire format, three independent implementations: this one (both local
+// backends), the DynamoDB stream relay in `StateTopic_AppSync_Ops`, and the
+// Postgres projection-side publisher in `StateTopicPublish.mjs`. They share no
+// code — the relay's module is deliberately Pulumi-free so a core import can't
+// drag deploy-time code into its Lambda graph. `StateChangeDescriptorParityTest`
+// (reventless-aws) drives all three and asserts they agree.
+//
+// `state` is ADVISORY. A subscriber may always ignore it and refetch; that is
+// what keeps the channel best-effort. A protocol that required the payload to be
+// applied would have to be lossless, and this one is not — see
+// `docs/analysis/live-update-descriptor-sequencing.md`.
+
+/** Cap on the serialised state payload, in characters.
+    AppSync Events caps a publish at ~240 KB, and the descriptor travels as a
+    JSON string nested inside the publish body, so escaping inflates it. Counting
+    characters rather than bytes keeps the rule identical across the three
+    implementations without a UTF-8 length binding; the limit is set low enough
+    that worst-case UTF-8 (3 bytes per character) plus escaping still fits.
+    Over the cap the state is dropped and the downgrade logged — a metadata-only
+    descriptor still tells the client to refetch, where a failed publish would
+    tell it nothing. */
+let maxStateChars = 60 * 1024
+
+let pickSortKeyValue = (state: JSON.t): option<string> =>
+  switch state->JSON.Decode.object {
+  | Some(obj) =>
+    switch obj->Dict.get("updatedAt") {
+    | Some(JSON.String(v)) => Some(v)
+    | _ =>
+      switch obj->Dict.get("createdAt") {
+      | Some(JSON.String(v)) => Some(v)
+      | _ => None
+      }
+    }
+  | None => None
+  }
+
+// Monotonic ordering token. Seeded from the wall clock and never allowed to go
+// backwards, so it keeps rising across process restarts — a client that held a
+// value from a previous run won't reject everything the new run publishes.
+//
+// Monotonic, NOT consecutive: it is shared by every read model in the process,
+// so one entity's values skip. That is deliberate — the DynamoDB relay reads its
+// sequence off the stream record, which is equally sparse, and a dense counter
+// would mean maintaining a version on every row (the analysis file has the cost).
+// The client rule is "greater than what I hold", never "exactly one more".
+let lastSequence = ref(0.0)
+
+let nextSequence = (): string => {
+  let now = Date.now()
+  let next = now > lastSequence.contents ? now : lastSequence.contents +. 1.0
+  lastSequence := next
+  next->Float.toString
+}
+
+/** Build a state-change descriptor.
+    - `changeKind`: one of "Added" | "Updated" | "Removed". save() emits "Added"
+      when no visible row held the key and "Updated" otherwise; delete() emits
+      "Removed".
+    - `id`: entity key. Single-key projections: the partition-key value.
+      Composite projections: `partition ++ "-" ++ subKey`.
+    - `state`: the resulting row for save(); `None` for delete(), which has no new
+      row — the descriptor then omits both `state` and `sortKeyValue`.
+    - `seq`: monotonic ordering token, from `nextSequence`. */
+let make = (~changeKind: string, ~id: string, ~state: option<JSON.t>, ~seq: string): JSON.t => {
+  let descriptor = Dict.make()
+  descriptor->Dict.set("changeKind", JSON.Encode.string(changeKind))
+  descriptor->Dict.set("id", JSON.Encode.string(id))
+  switch state->Option.flatMap(pickSortKeyValue) {
+  | Some(v) => descriptor->Dict.set("sortKeyValue", JSON.Encode.string(v))
+  | None => ()
+  }
+  descriptor->Dict.set("seq", JSON.Encode.string(seq))
+  switch state {
+  | Some(s) =>
+    let encoded = s->JSON.stringify
+    if encoded->String.length <= maxStateChars {
+      descriptor->Dict.set("state", s)
+    } else {
+      Console.warn(
+        `STATE_PAYLOAD_DOWNGRADED id=${id} chars=${encoded->String.length->Int.toString}`,
+      )
+    }
+  | None => ()
+  }
+  descriptor->JSON.Encode.object
+}

package/src/adapter/LocalStateChangeDescriptor.res.mjs

@@ -0,0 +1,61 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Stdlib_JSON from "@rescript/runtime/lib/es6/Stdlib_JSON.js";
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+
+function pickSortKeyValue(state) {
+  let obj = Stdlib_JSON.Decode.object(state);
+  if (obj === undefined) {
+    return;
+  }
+  let match = obj["updatedAt"];
+  if (typeof match === "string") {
+    return match;
+  }
+  let match$1 = obj["createdAt"];
+  if (typeof match$1 === "string") {
+    return match$1;
+  }
+}
+
+let lastSequence = {
+  contents: 0.0
+};
+
+function nextSequence() {
+  let now = Date.now();
+  let next = now > lastSequence.contents ? now : lastSequence.contents + 1.0;
+  lastSequence.contents = next;
+  return next.toString();
+}
+
+function make(changeKind, id, state, seq) {
+  let descriptor = {};
+  descriptor["changeKind"] = changeKind;
+  descriptor["id"] = id;
+  let v = Stdlib_Option.flatMap(state, pickSortKeyValue);
+  if (v !== undefined) {
+    descriptor["sortKeyValue"] = v;
+  }
+  descriptor["seq"] = seq;
+  if (state !== undefined) {
+    let encoded = JSON.stringify(state);
+    if (encoded.length <= 61440) {
+      descriptor["state"] = state;
+    } else {
+      console.warn(`STATE_PAYLOAD_DOWNGRADED id=` + id + ` chars=` + encoded.length.toString());
+    }
+  }
+  return descriptor;
+}
+
+let maxStateChars = 61440;
+
+export {
+  maxStateChars,
+  pickSortKeyValue,
+  lastSequence,
+  nextSequence,
+  make,
+}
+/* No side effect */

package/src/adapter/LocalUploadResolvers.res

@@ -9,8 +9,20 @@
 
 // Mint a same-origin `/{prefix}/{uuid}/{fileName}` ref: both the PUT target and the
 // stored value, mirroring the AWS presign ticket's shape.
-let mintRef = (~fileName: string): string =>
-  `/${LocalObjectStore.defaultUploadPrefix}/${NodeCrypto.randomUUID()}/${fileName}`
+//
+// The prefix is the declaring store's (`{plugin}/{store}`), so an object carries
+// the plugin that owns it in its own key — what lets a scoped reset attribute it,
+// exactly as an S3 key's prefix does. A store no connected plugin declared falls
+// back to the shared `uploads/` space rather than being refused: local plugins
+// need not declare a store to upload during development, and refusing here would
+// make dev stricter than deploy about something dev cannot check.
+let mintRef = (~store: string, ~fileName: string): string => {
+  let prefix =
+    LocalObjectStore.storePrefix(~qualified=store)->Option.getOr(
+      LocalObjectStore.defaultUploadPrefix,
+    )
+  `/${prefix}/${NodeCrypto.randomUUID()}/${fileName}`
+}
 
 // Release a ref: delete iff it sits under a served prefix; idempotent (deleting an
 // absent key still succeeds). Returns `(released, reason)`.
@@ -30,7 +42,8 @@ let register = (server: ReventlessGraphqlServer.GraphQL_ServerInstance.t): unit
     let obj = args->JSON.Decode.object->Option.getOr(Dict.make())
     let fileName =
       obj->Dict.get("fileName")->Option.flatMap(JSON.Decode.string)->Option.getOr("upload")
-    let ref = mintRef(~fileName)
+    let store = obj->Dict.get("store")->Option.flatMap(JSON.Decode.string)->Option.getOr("")
+    let ref = mintRef(~store, ~fileName)
     Dict.fromArray([
       ("uploadUrl", JSON.Encode.string(ref)),
       ("storageRef", JSON.Encode.string(ref)),

package/src/adapter/LocalUploadResolvers.res.mjs

@@ -3,11 +3,12 @@
 import * as Stdlib_JSON from "@rescript/runtime/lib/es6/Stdlib_JSON.js";
 import * as Nodecrypto from "node:crypto";
 import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
-import * as LocalObjectStore$ReventlessLocal from "./LocalObjectStore.res.mjs";
+import * as LocalObjectStore$ReventlessLocal from "./ObjectStore/LocalObjectStore.res.mjs";
 import * as Platform_AdminApi$ReventlessCore from "@reventlessdev/reventless-core/src/admin/Platform_AdminApi.res.mjs";
 
-function mintRef(fileName) {
-  return `/` + LocalObjectStore$ReventlessLocal.defaultUploadPrefix + `/` + Nodecrypto.randomUUID() + `/` + fileName;
+function mintRef(store, fileName) {
+  let prefix = Stdlib_Option.getOr(LocalObjectStore$ReventlessLocal.storePrefix(store), LocalObjectStore$ReventlessLocal.defaultUploadPrefix);
+  return `/` + prefix + `/` + Nodecrypto.randomUUID() + `/` + fileName;
 }
 
 function release(storageRef) {
@@ -31,7 +32,8 @@ function register(server) {
   resolvers["Upload_Presign"] = async (_root, args, _ctx) => {
     let obj = Stdlib_Option.getOr(Stdlib_JSON.Decode.object(args), {});
     let fileName = Stdlib_Option.getOr(Stdlib_Option.flatMap(obj["fileName"], Stdlib_JSON.Decode.string), "upload");
-    let ref = mintRef(fileName);
+    let store = Stdlib_Option.getOr(Stdlib_Option.flatMap(obj["store"], Stdlib_JSON.Decode.string), "");
+    let ref = mintRef(store, fileName);
     return Object.fromEntries([
       [
         "uploadUrl",

package/src/adapter/ObjectStore/LocalObjectStore.res

@@ -0,0 +1,157 @@
+// Object store dispatcher backing the dev platform's served-bucket routes.
+//
+// The AWS path fronts a private S3 bucket through CloudFront (served-buckets
+// plan); in dev there is no bucket, so objects live wherever the active storage
+// backend keeps its state — the store follows the events rather than choosing
+// its own durability:
+//   - a file-backed SQLite database → ObjectStoreStorage_FileSystem, writing
+//     beside the database (`./.reventless/objects`, `./.reventless/offload`)
+//   - Memory, `:memory:` SQLite, Postgres → ObjectStoreStorage_InMemory
+// BackendState.getObjectStoreRoot makes that choice; the arms are consulted per
+// call rather than at a `make`, since this store has no construction step and a
+// suite may flip the backend between tests.
+//
+// Held outside EventLog/QueryDb storage because it is raw bytes, not event or
+// query state — hence the `Local` prefix on the dispatcher, and `_InMemory` /
+// `_FileSystem` on the arms (not `_Sqlite`: the durable arm is the filesystem,
+// anchored to the database's directory).
+
+type entry = {
+  bytes: NodeBuffer.t,
+  contentType: string,
+}
+
+// The prefix keys are minted under when no declared store claims them. Mirrors
+// the AWS presign `SERVED_PREFIX` default; it stays served even once every store
+// declares its own prefix, because refs already minted under it live in an
+// append-only event log and must keep resolving.
+let defaultUploadPrefix = "uploads"
+
+// Prefixes the dev server serves at `/{prefix}/*` (PUT stores, GET reads).
+// Seeded with the default upload prefix; declared stores add their own.
+let servedPrefixes: ref<array<string>> = ref([defaultUploadPrefix])
+
+let registerServedPrefix = (prefix: string): unit =>
+  if !(servedPrefixes.contents->Array.includes(prefix)) {
+    servedPrefixes.contents = servedPrefixes.contents->Array.concat([prefix])
+  }
+
+// Declared object stores, `{plugin}.{store}` → the prefix its keys are rooted at
+// (`StoreLayout.keyPrefixFor`). The deployed platform threads the same map into
+// its presign service as `UPLOAD_STORES`; here the Platform fills it from every
+// connected plugin's `requiredStores`.
+//
+// Rooting keys at the declaring store — rather than dropping every plugin's
+// uploads into one `uploads/` space — is what makes an object attributable: a
+// scoped wipe reads the plugin back off the key prefix, exactly as it does from
+// an S3 key.
+let declaredStores: dict<string> = Dict.make()
+
+/** Where a declared store's objects sit locally: the deployed `{plugin}/{store}`
+    layout NESTED under the served `uploads/` prefix.
+
+    The nesting is not cosmetic. A dev UI is served by its own dev server and
+    reaches the platform through a proxy that forwards one path — `/uploads` — so a
+    ref minted outside it resolves against the UI server instead of the platform,
+    and the image silently renders as the SPA shell. Keeping every object under
+    `uploads/` means the serve path is a property of the platform, not something
+    each UI dev server has to be reconfigured to know. The `{plugin}/{store}`
+    segments still carry the attribution a scoped reset reads back off the key. */
+let localPrefixFor = (~qualified: string): string =>
+  `${defaultUploadPrefix}/${ReventlessCore.StoreLayout.prefixOfQualified(qualified)}`
+
+let registerStore = (~qualified: string, ~prefix: string): unit => {
+  declaredStores->Dict.set(qualified, prefix)
+  registerServedPrefix(prefix)
+}
+
+let storePrefix = (~qualified: string): option<string> => declaredStores->Dict.get(qualified)
+
+let declaredStoreList = (): array<(string, string)> => declaredStores->Dict.toArray
+
+// A request path is a served-object path when it sits under a registered served
+// prefix with at least one key segment following. Returns the storage key (the
+// path without its leading slash), or None for GraphQL / other paths.
+//
+// Matches the prefix as a path, not as a first segment: a declared store's
+// prefix is `{plugin}/{store}` — two segments — while the default `uploads` is
+// one, and both have to resolve through the same route.
+//
+// `..`, `.` and empty segments are refused here rather than inside the storage
+// arms so that every caller — the HTTP routes and Upload_Release alike — agrees
+// on which paths exist, whichever backend is active. Under the filesystem arm a
+// key becomes a path, and `uploads/../../etc/passwd` would otherwise escape the
+// store.
+let servedKey = (path: string): option<string> => {
+  let trimmed = path->String.startsWith("/") ? path->String.slice(~start=1, ~end=path->String.length) : path
+  let segments = trimmed->String.split("/")
+  let underAPrefix =
+    servedPrefixes.contents->Array.some(p =>
+      p->String.length > 0 && trimmed->String.startsWith(p ++ "/") && trimmed->String.length > p->String.length + 1
+    )
+  if underAPrefix && segments->Array.every(seg => seg != "" && seg != "." && seg != "..") {
+    Some(trimmed)
+  } else {
+    None
+  }
+}
+
+let put = (~key: string, ~bytes: NodeBuffer.t, ~contentType: string): unit =>
+  switch BackendState.getObjectStoreRoot() {
+  | Some(root) => ObjectStoreStorage_FileSystem.put(~root, ~key, ~bytes, ~contentType)
+  | None => ObjectStoreStorage_InMemory.put(~key, ~bytes, ~contentType)
+  }
+
+let get = (~key: string): option<entry> => {
+  let stored = switch BackendState.getObjectStoreRoot() {
+  | Some(root) => ObjectStoreStorage_FileSystem.get(~root, ~key)
+  | None => ObjectStoreStorage_InMemory.get(~key)
+  }
+  stored->Option.map(((bytes, contentType)) => {bytes, contentType})
+}
+
+// Remove a stored object. Idempotent — deleting an absent key is a no-op, matching
+// the release contract (see docs/plans/done/upload-release-path.md, Step 3). The dev
+// store has no identities or clock, so the release resolver enforces only the
+// *shape* of the rule (key under a served prefix), not the identity/age conditions.
+let delete = (~key: string): unit =>
+  switch BackendState.getObjectStoreRoot() {
+  | Some(root) => ObjectStoreStorage_FileSystem.delete(~root, ~key)
+  | None => ObjectStoreStorage_InMemory.delete(~key)
+  }
+
+// ── Offload objects ───────────────────────────────────────────────────────
+// Content-addressed deploy-time objects (`sha256/<hash>`), holding the large
+// pluginDefinition fields the connect handshake carries by reference instead of
+// inline. Deliberately a separate keyspace from the served objects: on AWS these
+// live in a private bucket the ComponentDefinitions Lambda reads through the SDK,
+// never behind a served route, so they must not become reachable over
+// `/{prefix}/*` here either. Bytes are the value's JSON, kept as a string because
+// that is what `Offload.resolve`'s `fetch` hands back.
+
+let putOffload = (~key: string, ~bytes: string): unit =>
+  switch BackendState.getObjectStoreRoot() {
+  | Some(root) => ObjectStoreStorage_FileSystem.putOffload(~root, ~key, ~bytes)
+  | None => ObjectStoreStorage_InMemory.putOffload(~key, ~bytes)
+  }
+
+let getOffload = (~key: string): option<string> =>
+  switch BackendState.getObjectStoreRoot() {
+  | Some(root) => ObjectStoreStorage_FileSystem.getOffload(~root, ~key)
+  | None => ObjectStoreStorage_InMemory.getOffload(~key)
+  }
+
+// Clear stored objects and restore the default served prefix. Called between
+// isolated test suites (from DomainGraphQL_Server.reset) and at Platform
+// construction under `sqlite:…?reset`, where wiping the events has to wipe the
+// bytes they reference too. Clears both arms: the backend is chosen before
+// construction, but a suite that flips backends can leave state in either.
+let reset = (): unit => {
+  ObjectStoreStorage_InMemory.reset()
+  switch BackendState.getObjectStoreRoot() {
+  | Some(root) => ObjectStoreStorage_FileSystem.reset(~root)
+  | None => ()
+  }
+  servedPrefixes.contents = [defaultUploadPrefix]
+  declaredStores->Dict.keysToArray->Array.forEach(k => declaredStores->Dict.delete(k))
+}

package/src/adapter/ObjectStore/LocalObjectStore.res.mjs

@@ -0,0 +1,129 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Stdlib_Dict from "@rescript/runtime/lib/es6/Stdlib_Dict.js";
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+import * as StoreLayout$ReventlessCore from "@reventlessdev/reventless-core/src/util/StoreLayout.res.mjs";
+import * as BackendState$ReventlessLocal from "../BackendState.res.mjs";
+import * as ObjectStoreStorage_InMemory$ReventlessLocal from "./ObjectStoreStorage_InMemory.res.mjs";
+import * as ObjectStoreStorage_FileSystem$ReventlessLocal from "./ObjectStoreStorage_FileSystem.res.mjs";
+
+let defaultUploadPrefix = "uploads";
+
+let servedPrefixes = {
+  contents: [defaultUploadPrefix]
+};
+
+function registerServedPrefix(prefix) {
+  if (!servedPrefixes.contents.includes(prefix)) {
+    servedPrefixes.contents = servedPrefixes.contents.concat([prefix]);
+    return;
+  }
+}
+
+let declaredStores = {};
+
+function localPrefixFor(qualified) {
+  return defaultUploadPrefix + `/` + StoreLayout$ReventlessCore.prefixOfQualified(qualified);
+}
+
+function registerStore(qualified, prefix) {
+  declaredStores[qualified] = prefix;
+  registerServedPrefix(prefix);
+}
+
+function storePrefix(qualified) {
+  return declaredStores[qualified];
+}
+
+function declaredStoreList() {
+  return Object.entries(declaredStores);
+}
+
+function servedKey(path) {
+  let trimmed = path.startsWith("/") ? path.slice(1, path.length) : path;
+  let segments = trimmed.split("/");
+  let underAPrefix = servedPrefixes.contents.some(p => {
+    if (p.length > 0 && trimmed.startsWith(p + "/")) {
+      return trimmed.length > (p.length + 1 | 0);
+    } else {
+      return false;
+    }
+  });
+  if (underAPrefix && segments.every(seg => seg !== "" && seg !== "." ? seg !== ".." : false)) {
+    return trimmed;
+  }
+}
+
+function put(key, bytes, contentType) {
+  let root = BackendState$ReventlessLocal.getObjectStoreRoot();
+  if (root !== undefined) {
+    return ObjectStoreStorage_FileSystem$ReventlessLocal.put(root, key, bytes, contentType);
+  } else {
+    return ObjectStoreStorage_InMemory$ReventlessLocal.put(key, bytes, contentType);
+  }
+}
+
+function get(key) {
+  let root = BackendState$ReventlessLocal.getObjectStoreRoot();
+  let stored = root !== undefined ? ObjectStoreStorage_FileSystem$ReventlessLocal.get(root, key) : ObjectStoreStorage_InMemory$ReventlessLocal.get(key);
+  return Stdlib_Option.map(stored, param => ({
+    bytes: param[0],
+    contentType: param[1]
+  }));
+}
+
+function $$delete(key) {
+  let root = BackendState$ReventlessLocal.getObjectStoreRoot();
+  if (root !== undefined) {
+    return ObjectStoreStorage_FileSystem$ReventlessLocal.$$delete(root, key);
+  } else {
+    return ObjectStoreStorage_InMemory$ReventlessLocal.$$delete(key);
+  }
+}
+
+function putOffload(key, bytes) {
+  let root = BackendState$ReventlessLocal.getObjectStoreRoot();
+  if (root !== undefined) {
+    return ObjectStoreStorage_FileSystem$ReventlessLocal.putOffload(root, key, bytes);
+  } else {
+    return ObjectStoreStorage_InMemory$ReventlessLocal.putOffload(key, bytes);
+  }
+}
+
+function getOffload(key) {
+  let root = BackendState$ReventlessLocal.getObjectStoreRoot();
+  if (root !== undefined) {
+    return ObjectStoreStorage_FileSystem$ReventlessLocal.getOffload(root, key);
+  } else {
+    return ObjectStoreStorage_InMemory$ReventlessLocal.getOffload(key);
+  }
+}
+
+function reset() {
+  ObjectStoreStorage_InMemory$ReventlessLocal.reset();
+  let root = BackendState$ReventlessLocal.getObjectStoreRoot();
+  if (root !== undefined) {
+    ObjectStoreStorage_FileSystem$ReventlessLocal.reset(root);
+  }
+  servedPrefixes.contents = [defaultUploadPrefix];
+  Object.keys(declaredStores).forEach(k => Stdlib_Dict.$$delete(declaredStores, k));
+}
+
+export {
+  defaultUploadPrefix,
+  servedPrefixes,
+  registerServedPrefix,
+  declaredStores,
+  localPrefixFor,
+  registerStore,
+  storePrefix,
+  declaredStoreList,
+  servedKey,
+  put,
+  get,
+  $$delete,
+  putOffload,
+  getOffload,
+  reset,
+}
+/* BackendState-ReventlessLocal Not a pure module */