@reventlessdev/reventless-local 3.0.0-alpha.244 → 3.0.0-alpha.246

package/src/adapter/EventHistory/EventHistoryResolvers_GraphQL.res.mjs

@@ -8,6 +8,7 @@ import * as Primitive_object from "@rescript/runtime/lib/es6/Primitive_object.js
 import * as Message$Reventless from "@reventlessdev/reventless-spec/src/types/Message.res.mjs";
 import * as Logger$ReventlessCore from "@reventlessdev/reventless-core/src/util/Logger.res.mjs";
 import * as QueryDbListQuery$ReventlessCore from "@reventlessdev/reventless-core/src/components/Api/QueryDbListQuery.res.mjs";
+import * as Auth_GraphqlContext$ReventlessLocal from "../Auth/Auth_GraphqlContext.res.mjs";
 import * as Plugin_EventQuerySchema$ReventlessCore from "@reventlessdev/reventless-core/src/plugin/component/Plugin_EventQuerySchema.res.mjs";
 
 function comparePosition(a, b) {
@@ -153,6 +154,62 @@ function readFilter(args) {
   };
 }
 
+function suppliedFilterKeys(f) {
+  return Stdlib_Array.filterMap([
+    [
+      "entityId",
+      Stdlib_Option.isSome(f.entityId)
+    ],
+    [
+      "tagKey",
+      Stdlib_Option.isSome(f.tagKey)
+    ],
+    [
+      "tagValue",
+      Stdlib_Option.isSome(f.tagValue)
+    ],
+    [
+      "eventTypes",
+      Stdlib_Option.isSome(f.eventTypes)
+    ],
+    [
+      "user",
+      Stdlib_Option.isSome(f.user)
+    ],
+    [
+      "timeFrom",
+      Stdlib_Option.isSome(f.timeFrom)
+    ],
+    [
+      "timeTo",
+      Stdlib_Option.isSome(f.timeTo)
+    ]
+  ], param => {
+    if (param[1]) {
+      return param[0];
+    }
+  });
+}
+
+function callerOf(ctx) {
+  let operation = Stdlib_Option.flatMap(Stdlib_Option.flatMap(Stdlib_Option.flatMap(Stdlib_Option.flatMap(Stdlib_JSON.Decode.object(ctx), d => d["params"]), Stdlib_JSON.Decode.object), d => d["operationName"]), Stdlib_JSON.Decode.string);
+  let user = Auth_GraphqlContext$ReventlessLocal.extractIdentity(ctx).userId;
+  if (operation !== undefined) {
+    return `operation "` + operation + `" as ` + user;
+  } else {
+    return `an unnamed operation as ` + user;
+  }
+}
+
+function describeCaller(ctx, filter) {
+  let keys = suppliedFilterKeys(filter);
+  if (keys.length !== 0) {
+    return callerOf(ctx) + `, with filter [` + keys.join(", ") + `]`;
+  } else {
+    return callerOf(ctx) + `, with no filter`;
+  }
+}
+
 function matchesTag(r, f) {
   let match = f.tagKey;
   let match$1 = f.tagValue;
@@ -305,7 +362,7 @@ function Make(Bus) {
       }
       seen.add(displayName);
       let fieldName = Plugin_EventQuerySchema$ReventlessCore.historyFieldName(params.pluginName, displayName);
-      let resolver = async (_root, args, _ctx) => {
+      let resolver = async (_root, args, ctx) => {
         let f = readFilter(args);
         let replay = Bus.getEventLogReplay(entry.busKey);
         let records;
@@ -314,7 +371,7 @@ function Make(Bus) {
           if (entityId !== undefined) {
             records = await readAggregate(replay, entityId);
           } else {
-            log.warn("EventHistoryResolvers_GraphQL", undefined, fieldName + `: ` + displayName + ` is an aggregate event log — it can only be read per entity. Supply filter.entityId.`);
+            log.warn("EventHistoryResolvers_GraphQL", undefined, fieldName + `: ` + displayName + ` is an aggregate event log — it can only be read per entity. ` + (`Supply filter.entityId. Asked by ` + describeCaller(ctx, f) + `.`));
             records = [];
           }
         } else {
@@ -353,6 +410,9 @@ export {
   metaJsonFromEnvelope,
   recordJson,
   readFilter,
+  suppliedFilterKeys,
+  callerOf,
+  describeCaller,
   matchesTag,
   matchesFilter,
   paginate,

package/src/adapter/LocalBus.res

@@ -51,34 +51,39 @@ type queuedEvent = {
 // it is one of three implementations of a shared wire format and is covered by
 // its own parity test, so it stays out of the bus.
 
-// Opt-in NDJSON domain-event tap for the VS Code local platform runner (features
-// plan Phase 9). Enabled when REVENTLESS_EVENT_TAP is set; off by default so normal
-// runs stay quiet. Emitted from publishEvent so every event is captured with its
-// real topic name (the EventTopic resource name consumers subscribe to) — no need
-// to guess topic names from EventLog registry keys. Each line is sentinel-prefixed
-// so the runner's line parser can pick it out of the platform's ANSI log noise on
-// stdout. The emit is a plain Console.log, so it never perturbs publishEvent's
-// subscriber-countdown delivery semantics.
-// Read per publish (not once at import) so the runner can toggle it live and so
-// hermetic tests can flip it between cases. The cost is one dict lookup per event.
-let eventTapEnabled = () => NodeProcess.env->Dict.get("REVENTLESS_EVENT_TAP")->Option.isSome
+// NDJSON domain-event tap, emitted from publishEvent so each line carries the real
+// topic name, sentinel-prefixed so a parser can pick it out of the log noise.
+//
+// Two sinks with different costs, so different defaults: stdout is opt-in via
+// REVENTLESS_EVENT_TAP (a line per event would drown `pnpm run serve`), the socket
+// is on by default (see LocalEventTap). Read per publish, not at import, so it can
+// be toggled live.
 let eventTapSeq = ref(0)
-// Seed the in-memory tap counter from a persistent store's existing event count
-// so the timeline's #N continues across process restarts / app switches instead
-// of restarting at 1. Called once at platform startup for the sqlite backend.
+// Continues the timeline's #N across restarts for a persistent store.
 let seedEventTapSeq = (n: int) => eventTapSeq := n
 let emitEventTap = (~topic: string, ~service: string, ~payload: JSON.t) => {
+  // Counted even when nothing is listening, so the sequence a reader that connects
+  // later sees is the event's ordinal rather than the ordinal of its own arrival.
   eventTapSeq := eventTapSeq.contents + 1
-  let line =
-    Dict.fromArray([
-      ("event", JSON.Encode.string("domainEvent")),
-      ("seq", JSON.Encode.int(eventTapSeq.contents)),
-      ("topic", JSON.Encode.string(topic)),
-      ("service", JSON.Encode.string(service)),
-      ("payload", payload),
-      ("ts", JSON.Encode.string(Date.make()->Date.toISOString)),
-    ])->JSON.Encode.object
-  Console.log("@@RVLESS_EVT@@ " ++ line->JSON.stringify)
+  let toStdout = LocalEventTap.stdoutEnabled()
+  // The line is built only for somebody: serialising every event for no reader is
+  // pure cost on the publish path.
+  if toStdout || LocalEventTap.hasReaders() {
+    let line =
+      Dict.fromArray([
+        ("event", JSON.Encode.string("domainEvent")),
+        ("seq", JSON.Encode.int(eventTapSeq.contents)),
+        ("topic", JSON.Encode.string(topic)),
+        ("service", JSON.Encode.string(service)),
+        ("payload", payload),
+        ("ts", JSON.Encode.string(Date.make()->Date.toISOString)),
+      ])->JSON.Encode.object
+    let tapLine = "@@RVLESS_EVT@@ " ++ line->JSON.stringify
+    if toStdout {
+      Console.log(tapLine)
+    }
+    LocalEventTap.broadcast(tapLine)
+  }
 }
 
 module type T = {
@@ -327,9 +332,7 @@ module Impl = (C: BusConfig): T => {
   }
 
   let publishEvent = async (topicName, service, meta, json) => {
-    if eventTapEnabled() {
-      emitEventTap(~topic=topicName, ~service, ~payload=json)
-    }
+    emitEventTap(~topic=topicName, ~service, ~payload=json)
     switch eventHubs.contents->Dict.get(topicName) {
     | None => ()
     | Some(hub) =>

package/src/adapter/LocalBus.res.mjs

@@ -10,10 +10,7 @@ import * as Stream from "effect/Stream";
 import * as Stdlib_Promise from "@rescript/runtime/lib/es6/Stdlib_Promise.js";
 import * as Deferred from "effect/Deferred";
 import * as Primitive_option from "@rescript/runtime/lib/es6/Primitive_option.js";
-
-function eventTapEnabled() {
-  return Stdlib_Option.isSome(process.env["REVENTLESS_EVENT_TAP"]);
-}
+import * as LocalEventTap$ReventlessLocal from "./LocalEventTap.res.mjs";
 
 let eventTapSeq = {
   contents: 0
@@ -25,6 +22,10 @@ function seedEventTapSeq(n) {
 
 function emitEventTap(topic, service, payload) {
   eventTapSeq.contents = eventTapSeq.contents + 1 | 0;
+  let toStdout = LocalEventTap$ReventlessLocal.stdoutEnabled(undefined);
+  if (!(toStdout || LocalEventTap$ReventlessLocal.hasReaders())) {
+    return;
+  }
   let line = Object.fromEntries([
     [
       "event",
@@ -51,7 +52,11 @@ function emitEventTap(topic, service, payload) {
       new Date().toISOString()
     ]
   ]);
-  console.log("@@RVLESS_EVT@@ " + JSON.stringify(line));
+  let tapLine = "@@RVLESS_EVT@@ " + JSON.stringify(line);
+  if (toStdout) {
+    console.log(tapLine);
+  }
+  LocalEventTap$ReventlessLocal.broadcast(tapLine);
 }
 
 function Impl(C) {
@@ -132,9 +137,7 @@ function Impl(C) {
     }), Queue.shutdown(queue))), queue => Stream.fromQueue(queue));
   };
   let publishEvent = async (topicName, service, meta, json) => {
-    if (Stdlib_Option.isSome(process.env["REVENTLESS_EVENT_TAP"])) {
-      emitEventTap(topicName, service, json);
-    }
+    emitEventTap(topicName, service, json);
     let hub = eventHubs.contents[topicName];
     if (hub === undefined) {
       return;
@@ -407,9 +410,7 @@ function Make($star) {
     }), Queue.shutdown(queue))), queue => Stream.fromQueue(queue));
   };
   let publishEvent = async (topicName, service, meta, json) => {
-    if (Stdlib_Option.isSome(process.env["REVENTLESS_EVENT_TAP"])) {
-      emitEventTap(topicName, service, json);
-    }
+    emitEventTap(topicName, service, json);
     let hub = eventHubs.contents[topicName];
     if (hub === undefined) {
       return;
@@ -682,9 +683,7 @@ function MakeSilent($star) {
     }), Queue.shutdown(queue))), queue => Stream.fromQueue(queue));
   };
   let publishEvent = async (topicName, service, meta, json) => {
-    if (Stdlib_Option.isSome(process.env["REVENTLESS_EVENT_TAP"])) {
-      emitEventTap(topicName, service, json);
-    }
+    emitEventTap(topicName, service, json);
     let hub = eventHubs.contents[topicName];
     if (hub === undefined) {
       return;
@@ -958,9 +957,7 @@ function MakeBounded(C) {
     }), Queue.shutdown(queue))), queue => Stream.fromQueue(queue));
   };
   let publishEvent = async (topicName, service, meta, json) => {
-    if (Stdlib_Option.isSome(process.env["REVENTLESS_EVENT_TAP"])) {
-      emitEventTap(topicName, service, json);
-    }
+    emitEventTap(topicName, service, json);
     let hub = eventHubs.contents[topicName];
     if (hub === undefined) {
       return;
@@ -1160,7 +1157,6 @@ function MakeBounded(C) {
 }
 
 export {
-  eventTapEnabled,
   eventTapSeq,
   seedEventTapSeq,
   emitEventTap,

package/src/adapter/LocalEventTap.res

@@ -0,0 +1,139 @@
+// The event tap's second sink: LocalBus's NDJSON lines, unchanged, over a loopback
+// socket — so a tool that did not spawn this platform can read its timeline.
+//
+// On by default, on an ephemeral port published in the registry entry. A socket
+// nobody connects to costs nothing visible, and the registry is already how a
+// reader finds this platform — so the port never needed to be well-known, which is
+// what let it stop being configured. The noisy half (a line per event on stdout)
+// stays opt-in. `REVENTLESS_EVENT_TAP=off` disables the socket too.
+// See docs/plans/done/one-local-platform-one-store.md.
+
+let log = ReventlessCore.Logger.fromEnv()
+
+let envVar = "REVENTLESS_EVENT_TAP"
+
+type setting =
+  | Off
+  | Ephemeral
+  | Fixed(int)
+
+let envValue = (~env: dict<string>): option<string> =>
+  env->Dict.get(envVar)->Option.map(String.trim)->Option.filter(v => v != "")
+
+/** What the env var asks the socket to do.
+
+    A port only when the value IS one in the unprivileged range: the runner has
+    passed `ndjson` since the tap existed, and someone writing `=1` means "on", not
+    port 1. Everything else — unset included — takes the ephemeral default. */
+let settingFromEnv = (~env=NodeProcess.env): setting =>
+  switch envValue(~env) {
+  | Some("off") | Some("false") | Some("none") => Off
+  | Some(v) =>
+    switch Int.fromString(v) {
+    | Some(p) if p >= 1024 && p <= 65535 => Fixed(p)
+    | _ => Ephemeral
+    }
+  | None => Ephemeral
+  }
+
+/** Whether to ALSO write each line to stdout. Opt-in and unchanged: this is the
+    half with a visible cost, and it exists for the child whose stdout the runner
+    reads. `off` silences both. */
+let stdoutEnabled = (~env=NodeProcess.env): bool =>
+  switch envValue(~env) {
+  | Some("off") | Some("false") | Some("none") | None => false
+  | Some(_) => true
+  }
+
+let connections: ref<array<NodeNet.socket>> = ref([])
+let server: ref<option<NodeNet.server>> = ref(None)
+let listeningPort: ref<option<int>> = ref(None)
+
+/** The port the socket is actually bound to, known only once `listen` calls back —
+    which is why {!start} takes `~onBound` rather than the caller reading this
+    straight after. `None` until then, and if the bind fails. */
+let port = () => listeningPort.contents
+
+/** Whether anyone is reading, so the hot path can skip building a line nobody
+    wants. */
+let hasReaders = () => connections.contents->Array.length > 0
+
+let drop = (socket: NodeNet.socket) =>
+  connections := connections.contents->Array.filter(s => s !== socket)
+
+/** Guarded per socket: a write to a closed peer throws, and one dead reader must
+    not cost the others their events or the platform its run. */
+let broadcast = (line: string): unit =>
+  if hasReaders() {
+    connections.contents->Array.forEach(socket =>
+      switch socket->NodeNet.write(line ++ "\n") {
+      | _ => ()
+      | exception _ => drop(socket)
+      }
+    )
+  }
+
+/** Binds the tap socket and reports the port it got.
+
+    `~onBound` fires only after a successful bind, so a caller publishes a port
+    that is genuinely listening rather than one it hoped for. Best-effort in every
+    failure mode: a platform whose diagnostic socket cannot bind must still serve,
+    and simply carries no tap port. */
+let start = (~env=NodeProcess.env, ~onBound: int => unit=_ => (), ()): unit =>
+  switch (settingFromEnv(~env), server.contents) {
+  | (Off, _) | (_, Some(_)) => ()
+  | (setting, None) =>
+    let requested = switch setting {
+    | Fixed(p) => p
+    // 0 lets the OS pick, so parallel platforms in one directory never collide and
+    // no unrelated service can be advertised as ours.
+    | Off | Ephemeral => 0
+    }
+    let s = NodeNet.createServer(socket => {
+      socket->NodeNet.setEncoding("utf8")
+      socket->NodeNet.onSocketError(_ => drop(socket))
+      socket->NodeNet.onSocketClose(() => drop(socket))
+      connections := connections.contents->Array.concat([socket])
+    })
+    s->NodeNet.onServerError(err => {
+      log.warn(
+        ~comp="EventTap",
+        `could not listen: ${err->JsExn.message->Option.getOr("unknown error")}`,
+      )
+      server := None
+      listeningPort := None
+    })
+    // A diagnostic listener must never be why the process stays alive.
+    s->NodeNet.unref
+    s->NodeNet.listen(requested, "127.0.0.1", () =>
+      switch s->NodeNet.address->Nullable.toOption {
+      | Some(addr) =>
+        let bound = addr["port"]
+        listeningPort := Some(bound)
+        log.info(~comp="EventTap", `listening on 127.0.0.1:${bound->Int.toString}`)
+        onBound(bound)
+      | None => ()
+      }
+    )
+    server := Some(s)
+  }
+
+/** Test seam: forgets connections and server without closing anything. */
+let resetForTests = () => {
+  connections := []
+  server := None
+  listeningPort := None
+}
+
+let addConnectionForTests = (socket: NodeNet.socket) =>
+  connections := connections.contents->Array.concat([socket])
+
+/** Test seam: actually releases the port, so a suite can bind it again. */
+let stopForTests = (): promise<unit> =>
+  switch server.contents {
+  | None => Promise.resolve()
+  | Some(s) =>
+    connections.contents->Array.forEach(NodeNet.destroySocket)
+    resetForTests()
+    Promise.make((resolve, _reject) => s->NodeNet.closeServer(() => resolve()))
+  }

package/src/adapter/LocalEventTap.res.mjs

@@ -0,0 +1,177 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Nodenet from "node:net";
+import * as Stdlib_Int from "@rescript/runtime/lib/es6/Stdlib_Int.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_option from "@rescript/runtime/lib/es6/Primitive_option.js";
+import * as Logger$ReventlessCore from "@reventlessdev/reventless-core/src/util/Logger.res.mjs";
+
+let log = Logger$ReventlessCore.fromEnv();
+
+let envVar = "REVENTLESS_EVENT_TAP";
+
+function envValue(env) {
+  return Stdlib_Option.filter(Stdlib_Option.map(env[envVar], prim => prim.trim()), v => v !== "");
+}
+
+function settingFromEnv(envOpt) {
+  let env = envOpt !== undefined ? envOpt : process.env;
+  let v = envValue(env);
+  if (v === undefined) {
+    return "Ephemeral";
+  }
+  switch (v) {
+    case "false" :
+    case "none" :
+    case "off" :
+      return "Off";
+    default:
+      let p = Stdlib_Int.fromString(v, undefined);
+      if (p !== undefined && p >= 1024 && p <= 65535) {
+        return {
+          TAG: "Fixed",
+          _0: p
+        };
+      } else {
+        return "Ephemeral";
+      }
+  }
+}
+
+function stdoutEnabled(envOpt) {
+  let env = envOpt !== undefined ? envOpt : process.env;
+  let match = envValue(env);
+  if (match === undefined) {
+    return false;
+  }
+  switch (match) {
+    case "false" :
+    case "none" :
+    case "off" :
+      return false;
+    default:
+      return true;
+  }
+}
+
+let connections = {
+  contents: []
+};
+
+let server = {
+  contents: undefined
+};
+
+let listeningPort = {
+  contents: undefined
+};
+
+function port() {
+  return listeningPort.contents;
+}
+
+function hasReaders() {
+  return connections.contents.length !== 0;
+}
+
+function drop(socket) {
+  connections.contents = connections.contents.filter(s => s !== socket);
+}
+
+function broadcast(line) {
+  if (connections.contents.length !== 0) {
+    connections.contents.forEach(socket => {
+      try {
+        socket.write(line + "\n");
+        return;
+      } catch (exn) {
+        return drop(socket);
+      }
+    });
+    return;
+  }
+}
+
+function start(envOpt, onBoundOpt, param) {
+  let env = envOpt !== undefined ? envOpt : process.env;
+  let onBound = onBoundOpt !== undefined ? onBoundOpt : param => {};
+  let match = settingFromEnv(env);
+  let match$1 = server.contents;
+  if (typeof match !== "object" && match === "Off") {
+    return;
+  }
+  if (match$1 !== undefined) {
+    return;
+  }
+  let requested;
+  requested = typeof match !== "object" ? 0 : match._0;
+  let s = Nodenet.createServer(socket => {
+    socket.setEncoding("utf8");
+    socket.on("error", param => drop(socket));
+    socket.on("close", () => drop(socket));
+    connections.contents = connections.contents.concat([socket]);
+  });
+  s.on("error", err => {
+    log.warn("EventTap", undefined, `could not listen: ` + Stdlib_Option.getOr(Stdlib_JsExn.message(err), "unknown error"));
+    server.contents = undefined;
+    listeningPort.contents = undefined;
+  });
+  s.unref();
+  s.listen(requested, "127.0.0.1", () => {
+    let addr = s.address();
+    if (addr == null) {
+      return;
+    }
+    let bound = addr.port;
+    listeningPort.contents = bound;
+    log.info("EventTap", undefined, `listening on 127.0.0.1:` + bound.toString());
+    onBound(bound);
+  });
+  server.contents = Primitive_option.some(s);
+}
+
+function resetForTests() {
+  connections.contents = [];
+  server.contents = undefined;
+  listeningPort.contents = undefined;
+}
+
+function addConnectionForTests(socket) {
+  connections.contents = connections.contents.concat([socket]);
+}
+
+function stopForTests() {
+  let s = server.contents;
+  if (s === undefined) {
+    return Promise.resolve();
+  }
+  let s$1 = Primitive_option.valFromOption(s);
+  connections.contents.forEach(prim => {
+    prim.destroy();
+  });
+  resetForTests();
+  return new Promise((resolve, _reject) => {
+    s$1.close(() => resolve());
+  });
+}
+
+export {
+  log,
+  envVar,
+  envValue,
+  settingFromEnv,
+  stdoutEnabled,
+  connections,
+  server,
+  listeningPort,
+  port,
+  hasReaders,
+  drop,
+  broadcast,
+  start,
+  resetForTests,
+  addConnectionForTests,
+  stopForTests,
+}
+/* log Not a pure module */

package/tests/EventTapSocketFixtures.mjs

@@ -0,0 +1,17 @@
+// Stand-in sockets for the tap's broadcast, which touches nothing on a socket but
+// `write`. Here rather than in an `Obj.magic` inside the test, per the repo
+// convention that untyped reflection lives in a companion `.mjs`.
+
+/** Records every line written, so a test can assert what a reader received. */
+export const recordingSocket = () => {
+  const written = []
+  return { socket: { write: line => written.push(line) }, written }
+}
+
+/** A reader whose peer is gone: `write` throws, the way it does on a closed pipe.
+    Broadcast has to survive this without losing the other readers. */
+export const throwingSocket = () => ({
+  write: () => {
+    throw new Error('EPIPE')
+  },
+})