@reventlessdev/reventless-local 3.0.0-alpha.243 → 3.0.0-alpha.245

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')
+  },
+})

package/tests/LocalEventTapTest.res

@@ -0,0 +1,154 @@
+// The tap's second sink. A tool that did not spawn the platform has no stdout to
+// read, so an attached runner's timeline is dark without this.
+
+@@warning("-44")
+
+open JestGlobals
+
+type recorder = {socket: NodeNet.socket, written: array<string>}
+
+@module("./EventTapSocketFixtures.mjs")
+external recordingSocket: unit => recorder = "recordingSocket"
+
+@module("./EventTapSocketFixtures.mjs")
+external throwingSocket: unit => NodeNet.socket = "throwingSocket"
+
+let envWith = (value: option<string>): dict<string> =>
+  switch value {
+  | Some(v) => Dict.fromArray([(LocalEventTap.envVar, v)])
+  | None => Dict.make()
+  }
+
+describe("LocalEventTap.settingFromEnv", () => {
+  // The default is the point: the runner attaches to whatever `pnpm run serve`
+  // started, and a tap nobody remembered to switch on is a dark timeline.
+  testSync("defaults to an ephemeral socket when the var is unset", () => {
+    expect(LocalEventTap.settingFromEnv(~env=envWith(None)))->toEqual(LocalEventTap.Ephemeral)
+    expect(LocalEventTap.settingFromEnv(~env=envWith(Some(""))))->toEqual(LocalEventTap.Ephemeral)
+  })
+
+  testSync("takes a port when the value is one", () =>
+    expect(LocalEventTap.settingFromEnv(~env=envWith(Some("4100"))))->toEqual(
+      LocalEventTap.Fixed(4100),
+    )
+  )
+
+  // `ndjson` is what the runner has passed since the tap existed, and `=1` means
+  // "on" to anyone who writes it — never port 1. Both take the default socket.
+  testSync("treats a non-port value as the default, not as a port", () => {
+    expect(LocalEventTap.settingFromEnv(~env=envWith(Some("ndjson"))))->toEqual(
+      LocalEventTap.Ephemeral,
+    )
+    expect(LocalEventTap.settingFromEnv(~env=envWith(Some("1"))))->toEqual(LocalEventTap.Ephemeral)
+    expect(LocalEventTap.settingFromEnv(~env=envWith(Some("80"))))->toEqual(LocalEventTap.Ephemeral)
+    expect(LocalEventTap.settingFromEnv(~env=envWith(Some("70000"))))->toEqual(
+      LocalEventTap.Ephemeral,
+    )
+  })
+
+  testSync("switches the socket off on request", () =>
+    ["off", "false", "none"]->Array.forEach(v =>
+      expect(LocalEventTap.settingFromEnv(~env=envWith(Some(v))))->toEqual(LocalEventTap.Off)
+    )
+  )
+})
+
+describe("LocalEventTap.stdoutEnabled", () => {
+  // The half with a visible cost keeps its opt-in: a line per event would drown
+  // `pnpm run serve`, which is the command the socket default exists to serve.
+  testSync("stays off unless the var is set", () => {
+    expect(LocalEventTap.stdoutEnabled(~env=envWith(None)))->toEqual(false)
+    expect(LocalEventTap.stdoutEnabled(~env=envWith(Some("ndjson"))))->toEqual(true)
+    expect(LocalEventTap.stdoutEnabled(~env=envWith(Some("4100"))))->toEqual(true)
+  })
+
+  testSync("is silenced by off, along with the socket", () =>
+    expect(LocalEventTap.stdoutEnabled(~env=envWith(Some("off"))))->toEqual(false)
+  )
+})
+
+describe("LocalEventTap.broadcast", () => {
+  testSync("hands every reader the line, newline-terminated", () => {
+    LocalEventTap.resetForTests()
+    let a = recordingSocket()
+    let b = recordingSocket()
+    LocalEventTap.addConnectionForTests(a.socket)
+    LocalEventTap.addConnectionForTests(b.socket)
+
+    LocalEventTap.broadcast(`@@RVLESS_EVT@@ {"seq":1}`)
+
+    expect(a.written)->toEqual([`@@RVLESS_EVT@@ {"seq":1}\n`])
+    expect(b.written)->toEqual([`@@RVLESS_EVT@@ {"seq":1}\n`])
+  })
+
+  // A write to a closed peer throws. One dead reader must not cost the others
+  // their events, or the platform its run.
+  testSync("drops a reader whose write throws, and keeps serving the rest", () => {
+    LocalEventTap.resetForTests()
+    let live = recordingSocket()
+    LocalEventTap.addConnectionForTests(throwingSocket())
+    LocalEventTap.addConnectionForTests(live.socket)
+
+    LocalEventTap.broadcast("first")
+    LocalEventTap.broadcast("second")
+
+    expect(live.written)->toEqual(["first\n", "second\n"])
+  })
+
+  testSync("is inert with no readers", () => {
+    LocalEventTap.resetForTests()
+    LocalEventTap.broadcast("nobody is listening")
+    expect(LocalEventTap.port())->toEqual(None)
+  })
+})
+
+describe("LocalEventTap.start", () => {
+  testSync("does not listen when the socket is switched off", () => {
+    LocalEventTap.resetForTests()
+    LocalEventTap.start(~env=envWith(Some("off")), ())
+    expect(LocalEventTap.port())->toEqual(None)
+  })
+
+  // The default path, and the one that matters: no env var at all, a port the OS
+  // picks, reported only once it is actually bound.
+  test("binds an ephemeral port by default and reports the one it got", async () => {
+    LocalEventTap.resetForTests()
+    let bound = await Promise.make((resolve, _reject) =>
+      LocalEventTap.start(~env=envWith(None), ~onBound=p => resolve(p), ())
+    )
+    expect(bound > 0)->toEqual(true)
+    // What the registry entry will carry — the real port, not a hoped-for one.
+    expect(LocalEventTap.port())->toEqual(Some(bound))
+    await LocalEventTap.stopForTests()
+  })
+
+  // The round trip the runner will make: connect to the advertised port, read
+  // the same sentinel-prefixed lines it reads off stdout today.
+  test("serves the lines it is sent on the port it was named", async () => {
+    LocalEventTap.resetForTests()
+    let port = 47311
+    let bound = await Promise.make((resolve, _reject) =>
+      LocalEventTap.start(~env=envWith(Some(port->Int.toString)), ~onBound=p => resolve(p), ())
+    )
+    expect(bound)->toEqual(port)
+
+    let received = await Promise.make((resolve, _reject) => {
+      let socket = NodeNet.connect(port, "127.0.0.1", () => ())
+      socket->NodeNet.setEncoding("utf8")
+      socket->NodeNet.onSocketError(e =>
+        resolve("connect failed: " ++ e->JsExn.message->Option.getOr("unknown"))
+      )
+      // Re-sent until it lands: the server's accept and the client's connect are
+      // separate events, so a single broadcast could beat the connection.
+      let ticker = ref(None)
+      socket->NodeNet.onSocketData(chunk => {
+        ticker.contents->Option.forEach(clearInterval)
+        resolve(chunk)
+      })
+      ticker := Some(setInterval(() => LocalEventTap.broadcast(`@@RVLESS_EVT@@ {"seq":7}`), 5))
+    })
+
+    expect(received)->toEqual(`@@RVLESS_EVT@@ {"seq":7}\n`)
+    await LocalEventTap.stopForTests()
+  })
+})