@homeflare/seat-runtime 0.1.0

package/src/state-valkey-connection.ts

@@ -0,0 +1,113 @@
+/**
+ * Keeping one `Bun.RedisClient` connected for as long as its layer lives.
+ *
+ * 🔴 BUN GIVES UP, AND A CLIENT THAT HAS GIVEN UP STAYS DEAD. Measured 2026-09-29 (Bun 1.4.0, a raw
+ *   client with `enableOfflineQueue: false` and the default `maxRetries` of 20, the server killed
+ *   for 60 s, then restarted): Bun retried on its own for 31 s (commands failed `Connection is
+ *   closed and offline queue is disabled`), then GAVE UP: `onclose` ran once and every command
+ *   after failed `Connection has failed`, still so 10 s after the server was back. Only calling
+ *   `connect()` again revived it (it resolved at once and `PING` answered). The budget is a sum of
+ *   backoffs, so it is not one number: the review that found this measured recovery after 30 s and
+ *   none after 45 s. A seat whose Valkey restarts for a minute (a container restart, CT100 booting)
+ *   would keep a dead client until the process restarted, and no retry in Effect could help, since
+ *   every retry hit the same dead client.
+ * ★ SO THE LAYER RECONNECTS ITSELF, off `onclose`: single-flight, each attempt bounded by
+ *   `connectionTimeout` (which does not bound DNS; see state-valkey.ts), backing off 250 ms up to
+ *   5 s between attempts, one `valkey reconnect` span per attempt and a warning and an info line
+ *   around the outage. It stops when the layer's scope closes.
+ * ⚠️ `onclose` IS A HINT AND `connected` IS THE FACT. Measured on the same client: `onclose` also
+ *   runs for every `connect()` that fails (each rejected after ~155 ms with `Connection closed`)
+ *   and for the client's own `close()`, so a reconnect that trusted it would start itself. The
+ *   loop therefore runs only while `connected` is false, and a wake-up that arrives after a
+ *   successful reconnect finds nothing to do.
+ * ⚠️ COMMANDS STILL FAIL AT ONCE WHILE IT IS DOWN (the offline queue is off on purpose): the
+ *   caller's retry is what spans an outage, and from now on the retry is answered once this loop
+ *   has reconnected, within the pause plus one attempt of the server coming back.
+ */
+import type { RedisClient } from 'bun';
+import * as Duration from 'effect/Duration';
+import * as Effect from 'effect/Effect';
+import * as Queue from 'effect/Queue';
+import type * as Scope from 'effect/Scope';
+
+/** What this file needs of `Bun.RedisClient`. */
+export type Reconnectable = Pick<RedisClient, 'connected' | 'connect' | 'onclose'>;
+
+export type KeepOptions = {
+  /** How long one reconnect attempt may take before it is abandoned and retried. */
+  readonly connectionTimeout: Duration.Input;
+  /** Span attributes every attempt carries: the server address, no secrets. */
+  readonly attributes: Readonly<Record<string, unknown>>;
+  /** The pause after the first failed attempt, doubled up to `longestPause`. Default 250 ms. */
+  readonly firstPause?: Duration.Input | undefined;
+  /** The longest pause between attempts. Default 5 s. */
+  readonly longestPause?: Duration.Input | undefined;
+};
+
+const DEFAULT_FIRST_PAUSE_MS = 250;
+const DEFAULT_LONGEST_PAUSE_MS = 5000;
+
+/**
+ * Reconnect `client` whenever Bun gives up on it, for the life of the enclosing scope. Call it
+ * AFTER the first `connect()` succeeded, so a wrong URL or password still fails the layer's build
+ * instead of being retried forever.
+ */
+export const keepConnected: (
+  client: Reconnectable,
+  options: KeepOptions,
+) => Effect.Effect<void, never, Scope.Scope> = Effect.fnUntraced(function* (
+  client: Reconnectable,
+  options: KeepOptions,
+) {
+  const wake = yield* Queue.sliding<void>(1);
+  const firstPause = Duration.toMillis(options.firstPause ?? DEFAULT_FIRST_PAUSE_MS);
+  const longestPause = Duration.toMillis(options.longestPause ?? DEFAULT_LONGEST_PAUSE_MS);
+  // ⛔ ONE `connect()` IN FLIGHT AT A TIME. An attempt that times out is abandoned, but Bun's own
+  //   promise is still pending (a name that does not resolve took 31 s), and a second `connect()`
+  //   on top of it is not something Bun documents. The next attempt awaits the same promise.
+  let connecting: Promise<void> | undefined;
+  const connectOnce = (): Promise<void> => {
+    connecting ??= client.connect().finally(() => {
+      connecting = undefined;
+    });
+    return connecting;
+  };
+  const attempt = Effect.tryPromise({ try: connectOnce, catch: (cause) => cause }).pipe(
+    Effect.timeoutOrElse({
+      duration: options.connectionTimeout,
+      orElse: () => Effect.fail(new Error('a reconnect attempt did not finish in time')),
+    }),
+    Effect.withSpan('valkey reconnect', { kind: 'client', attributes: options.attributes }),
+    Effect.as(true),
+    Effect.orElseSucceed(() => false),
+  );
+  const reconnect = Effect.gen(function* () {
+    if (client.connected) return;
+    yield* Effect.logWarning('SeatState valkey: the connection is down, reconnecting');
+    let pause = firstPause;
+    let attempts = 0;
+    while (!client.connected) {
+      attempts += 1;
+      yield* attempt;
+      // ⚠️ `connected` decides, not the attempt's own answer: an attempt that resolved without the
+      //   client being connected must pause like a failed one, not spin.
+      if (client.connected) break;
+      yield* Effect.sleep(pause);
+      pause = Math.min(pause * 2, longestPause);
+    }
+    yield* Effect.logInfo(`SeatState valkey: reconnected after ${String(attempts)} attempt(s)`);
+  });
+  client.onclose = () => {
+    Queue.offerUnsafe(wake, undefined);
+  };
+  // ⛔ A NO-OP, NEVER `null`: measured 2026-09-29 (Bun 1.4.0), `client.onclose = null` (or
+  //   `undefined`) is accepted, and then `close()` calls the null and throws `TypeError: ... is not
+  //   a function` (worded with whatever call site is on the stack, `c.close()` or a fiber's
+  //   `this[args]()`). bun-types types `onclose` as `... | null`; Bun does not honour it.
+  yield* Effect.addFinalizer(() =>
+    Effect.sync(() => {
+      client.onclose = () => {};
+    }),
+  );
+  yield* Effect.forkScoped(Effect.forever(Queue.take(wake).pipe(Effect.andThen(reconnect))));
+});

package/src/state-valkey-scrub.ts

@@ -0,0 +1,60 @@
+/**
+ * What a Valkey error may say once it has left the layer.
+ *
+ * 🔴 THE SERVER'S ERROR TEXT ECHOES THE ARGUMENTS OF THE CALL THAT FAILED. Measured 2026-09-29
+ *   (Valkey 9.1.1, through `Bun.RedisClient`, with canary values):
+ *     ERR unknown command 'JSON.SET', with args beginning with: 'seat:key-…' '$' '{"secret":…}'
+ *     ERR unknown subcommand 'seat:key-…'. Try OBJECT HELP.
+ *   Keys are seat data and values are whatever the seat stored, and Effect's `OtlpTracer` exports
+ *   every FAILED span's error as `exception.message` and `exception.stacktrace` (with the whole
+ *   `cause` chain, `includeCauseInStack: true`), so those two errors put a key and a value into
+ *   the exported trace: the OTLP payload a Victoria service would receive held both (a wire test
+ *   in tests/state-error-text.test.ts asserts it now does not). A `Logger` that prints a failed
+ *   call does the same.
+ * ★ SO THE ERROR THAT LEAVES THE LAYER IS A NEW `Error` WITH THE ARGUMENTS CUT OUT, and the
+ *   original is not chained (a `cause` would carry its text straight back into the stack). Kept:
+ *   Bun's `code` and `name`, and the server's own words up to the first quote that opens
+ *   something other than the command that was sent. That keeps `NOPERM User seat has no
+ *   permissions to run the 'flushall' command` whole (so `isPermissionDenied` and the wording are
+ *   unchanged) and cuts `unknown command 'JSON.SET', with args beginning with: ` at the first
+ *   argument, even when an argument holds a quote itself.
+ * ⚠️ WHAT THIS DOES NOT COVER, said plainly: a server text that echoes an argument WITHOUT quotes,
+ *   and the text a Lua script raises itself (`error(...)` comes back as `ERR user_script:1: <text>`;
+ *   measured). Bun's own errors (`Connection closed`, a timeout) quote nothing.
+ */
+
+/** What replaces the arguments. */
+export const OMITTED = '[arguments omitted]';
+
+/**
+ * `message` up to the first quoted thing that is not `command` (or one of its subcommands, which
+ * the server writes `command|sub`), with `OMITTED` where the rest was.
+ */
+export function cutArguments(message: string, command: string): string {
+  const name = command.toLowerCase();
+  let at = message.indexOf("'");
+  while (at !== -1) {
+    const close = message.indexOf("'", at + 1);
+    const quoted = close === -1 ? undefined : message.slice(at + 1, close).toLowerCase();
+    if (quoted === undefined || !(quoted === name || quoted.startsWith(`${name}|`))) {
+      return `${message.slice(0, at)}${OMITTED}`;
+    }
+    at = message.indexOf("'", close + 1);
+  }
+  return message;
+}
+
+/**
+ * The client's rejection as an `Error` that is safe to put in a span, a log or a `RedisError`:
+ * a fresh one, keeping Bun's `name` and `code`, with the arguments cut out of the text.
+ */
+export function scrubbedError(cause: unknown, command: string): Error {
+  const original = cause instanceof Error ? cause : undefined;
+  const scrubbed = new Error(cutArguments(original?.message ?? String(cause), command));
+  if (original !== undefined) {
+    scrubbed.name = original.name;
+    const code: unknown = (original as { readonly code?: unknown }).code;
+    if (typeof code === 'string') Object.assign(scrubbed, { code });
+  }
+  return scrubbed;
+}

package/src/state-valkey-send.ts

@@ -0,0 +1,67 @@
+/**
+ * One Valkey command as a span, with a deadline, failing as `RedisError`.
+ *
+ * ⛔ A SPAN NAMES THE COMMAND, NEVER ITS ARGUMENTS. Keys are seat data and values are whatever the
+ *   seat stored; `AUTH` and `HELLO ... AUTH` carry a password. Only the upper-cased command name
+ *   (`SET`, `GET`) is recorded, so the span is low-cardinality and holds nothing to redact.
+ * 🔴 NOR IS THE ERROR TEXT: the server quotes the arguments of a call it refuses (`unknown command
+ *   'X', with args beginning with: '<key>' '<value>'`), and a failed span exports its error, so
+ *   what a caller receives is `scrubbedError`, never Bun's own (state-valkey-scrub.ts).
+ * 🔴 THE DEADLINE IS NOT OPTIONAL. Measured 2026-09-29 (Bun 1.4.0): a `Bun.RedisClient` on its
+ *   defaults that has lost its server QUEUES every command and never answers it until the server
+ *   is back (a `send` sat unresolved past 8 s against a dead port; after a restart the queued
+ *   command completed ~5 s later). With the offline queue off (`state-valkey.ts` sets it) a dropped
+ *   connection fails at once, but a peer that holds the socket open and says nothing would still
+ *   wedge a seat forever, so every command carries `commandTimeout` too.
+ */
+import * as Effect from 'effect/Effect';
+import * as Redis from 'effect/unstable/persistence/Redis';
+import type * as Duration from 'effect/Duration';
+import { scrubbedError } from './state-valkey-scrub.ts';
+
+/** What this file needs of a client: `Bun.RedisClient` has this exact `send`. */
+export type ValkeyCall = {
+  readonly send: (command: string, args: Array<string>) => Promise<unknown>;
+};
+
+/** `send` as `Redis.make` wants it. */
+export type Send = <A = unknown>(
+  command: string,
+  ...args: ReadonlyArray<string>
+) => Effect.Effect<A, Redis.RedisError>;
+
+export type SendOptions = {
+  /** How long one command may take before it fails as `RedisError`. */
+  readonly commandTimeout: Duration.Input;
+  /** The command deadline in milliseconds, for the message only. */
+  readonly commandTimeoutMs: number;
+  /** Span attributes every command carries: `db.system.name`, the server address, no secrets. */
+  readonly attributes: Readonly<Record<string, unknown>>;
+};
+
+export function instrumentedSend(client: ValkeyCall, options: SendOptions): Send {
+  return <A = unknown>(command: string, ...args: ReadonlyArray<string>) => {
+    const name = command.toUpperCase();
+    return Effect.tryPromise({
+      // ⚠️ Bun's `send` types its argument list as a mutable array; ours is readonly.
+      try: () => client.send(command, [...args]) as Promise<A>,
+      catch: (cause) => new Redis.RedisError({ cause: scrubbedError(cause, command) }),
+    }).pipe(
+      Effect.timeoutOrElse({
+        duration: options.commandTimeout,
+        orElse: () =>
+          Effect.fail(
+            new Redis.RedisError({
+              cause: new Error(
+                `valkey ${name} did not answer within ${String(options.commandTimeoutMs)} ms`,
+              ),
+            }),
+          ),
+      }),
+      Effect.withSpan(`valkey ${name}`, {
+        kind: 'client',
+        attributes: { ...options.attributes, 'db.operation.name': name },
+      }),
+    );
+  };
+}

package/src/state-valkey.ts

@@ -0,0 +1,193 @@
+/**
+ * Valkey as Effect's own `Redis` service, over `Bun.RedisClient`.
+ *
+ * ★ `Redis.make` OVER THE BUILT-IN CLIENT, NOT `@effect/platform-bun`'s `BunRedis`. Rc.115 ships
+ *   `BunRedis.layer`, and it would do; but a dependency on `@effect/platform-bun` drags
+ *   `@effect/platform-node-shared ^rc.115` in behind it, which resolves to rc.118 on a fresh
+ *   install and kills the process at import, and only a ROOT `overrides` fixes that (docs/pairing.md,
+ *   measured 2026-09-29). A library cannot ship one. So this is the same ~30 lines (`send` over
+ *   `client.send`), with the two things `BunRedis` lacks: a connection that must succeed before the
+ *   layer is built, and a deadline on every command.
+ * ⛔ THE URL CARRIES THE ACL USER (`redis://seat:<password>@host:port`, percent-encoded), measured
+ *   2026-09-29 against a scratch Valkey with `user default off`: an unauthenticated client is
+ *   refused `NOAUTH`; the seat user reads and writes its own prefix; a write outside it fails
+ *   `NOPERM No permissions to access a key`, and a command outside its categories fails
+ *   `NOPERM User seat has no permissions to run the 'flushall' command`. All of them arrive as
+ *   `RedisError`, and `isPermissionDenied` names the two `NOPERM` ones.
+ * ⛔ NO `subscribe`. `Redis.subscribe` here fails with `RedisError`: a Valkey subscriber needs a
+ *   connection of its own that this layer does not open. (`BunRedis` opens one, with no reconnect;
+ *   a caller that needs pub/sub can use it beside this layer.)
+ * ⚠️ BUN ONLY, AND SAID SO AT THE FIRST USE. `Bun.RedisClient` is loaded with `import('bun')`, so
+ *   importing this module under Node still works (the Postgres half is portable); BUILDING the
+ *   Valkey layer there fails with a `RedisError` naming the reason.
+ * 🔴 `connectionTimeout` DOES NOT BOUND DNS. Measured 2026-09-29: with `connectionTimeout: 700`, a
+ *   host name that does not resolve failed after 31 s. `connect()` therefore also runs under an
+ *   Effect timeout of the same length.
+ * 🔴 BUN'S OWN RECONNECT ENDS, AND THE CLIENT THEN STAYS DEAD (about 31 s of outage here): the layer
+ *   reconnects it itself, off `onclose` (state-valkey-connection.ts holds the measurement).
+ */
+import * as Config from 'effect/Config';
+import * as Duration from 'effect/Duration';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as Redacted from 'effect/Redacted';
+import * as Redis from 'effect/unstable/persistence/Redis';
+import { valkeyFields } from './state-dsn.ts';
+import { keepConnected } from './state-valkey-connection.ts';
+import { instrumentedSend } from './state-valkey-send.ts';
+
+export type ValkeyOptions = {
+  /**
+   * `redis://<user>:<password>@<host>:<port>[/<db>]` (or `valkey://`, `rediss://` for TLS), the
+   * user and password percent-encoded. Held `Redacted`; never in a span, log or error. Required:
+   * this package holds no host.
+   */
+  readonly url: string | Redacted.Redacted<string>;
+  /**
+   * How long to wait to connect and authenticate when the layer is built, and for each reconnect
+   * attempt after Bun gives up. Default 5 s (Bun's own is 10 s). ⚠️ A finite positive duration of at
+   * most 2 ** 31 - 1 ms, or a `RangeError` defect.
+   */
+  readonly connectionTimeout?: Duration.Input | undefined;
+  /** How long one command may take. Default 10 s; same limits as `connectionTimeout`. */
+  readonly commandTimeout?: Duration.Input | undefined;
+  /**
+   * How many times Bun retries a lost connection before it gives up (its default is 20, about 30
+   * s of outage). After that THE LAYER reconnects until the server is back, so this only sets
+   * when its own loop takes over. A non-negative integer, or a `RangeError` defect.
+   */
+  readonly maxRetries?: number | undefined;
+};
+
+export const DEFAULT_CONNECTION_TIMEOUT: Duration.Duration = Duration.seconds(5);
+export const DEFAULT_COMMAND_TIMEOUT: Duration.Duration = Duration.seconds(10);
+
+/** A duration as whole milliseconds Bun and `setTimeout` accept, or a `RangeError`. */
+function milliseconds(input: Duration.Input, name: string): number {
+  const ms = Duration.toMillis(input);
+  if (!Number.isFinite(ms) || ms <= 0 || ms > 2 ** 31 - 1) {
+    throw new RangeError(`${name} must be a finite duration above 0 and at most 2 ** 31 - 1 ms`);
+  }
+  return Math.ceil(ms);
+}
+
+/** A failure that names the reason and never the URL. */
+const refused = (reason: string): Redis.RedisError =>
+  new Redis.RedisError({ cause: new Error(`SeatState valkey: ${reason}`) });
+
+/**
+ * Whether `error` is the server's `NOPERM`: a key outside the user's prefix, or a command outside
+ * its categories. ⚠️ It reads the message, because Bun reports both as one `code`
+ * (`ERR_REDIS_SERVER_ERROR`) and the server's own text is the only thing that tells them apart
+ * from a real server fault.
+ */
+export function isPermissionDenied(error: unknown): boolean {
+  if (!(error instanceof Redis.RedisError)) return false;
+  const cause: unknown = error.cause;
+  const message = cause instanceof Error ? cause.message : String(cause);
+  return message.startsWith('NOPERM');
+}
+
+/** Subscribing is not offered; see the header. */
+const subscribe = (): Effect.Effect<never, Redis.RedisError> =>
+  Effect.fail(refused('subscribe is not supported here (a subscriber needs its own connection)'));
+
+/** Loads `Bun.RedisClient`, or fails naming why it is not there (Node, workerd). */
+const loadClient = Effect.tryPromise({
+  try: async () => (await import('bun')).RedisClient,
+  catch: () => refused('needs Bun (Bun.RedisClient); this runtime does not have it'),
+});
+
+const build = Effect.fnUntraced(function* (options: ValkeyOptions) {
+  const url = Redacted.value(
+    typeof options.url === 'string' ? Redacted.make(options.url) : options.url,
+  );
+  const fields = valkeyFields(url);
+  if (fields === undefined) {
+    return yield* refused('the URL is not a redis, valkey, rediss or valkeys URL');
+  }
+  const connectionTimeout = options.connectionTimeout ?? DEFAULT_CONNECTION_TIMEOUT;
+  const commandTimeout = options.commandTimeout ?? DEFAULT_COMMAND_TIMEOUT;
+  const connectMs = milliseconds(connectionTimeout, 'connectionTimeout');
+  const commandMs = milliseconds(commandTimeout, 'commandTimeout');
+  const maxRetries = options.maxRetries;
+  if (maxRetries !== undefined && !(Number.isInteger(maxRetries) && maxRetries >= 0)) {
+    throw new RangeError('maxRetries must be a non-negative integer');
+  }
+  const RedisClient = yield* loadClient;
+  // ⛔ OFFLINE QUEUE OFF: a command sent while the connection is down fails at once as
+  //   `RedisError` (a seat retries in Effect, where an attempt is a span) instead of waiting for
+  //   a reconnect that may not come. Measured 2026-09-29: after a server restart the same client
+  //   answered again within 1.5 s; past Bun's retry budget the layer reconnects behind the
+  //   caller's retry (state-valkey-connection.ts). It is also why the layer connects first: an
+  //   unconnected client with the queue off refuses every command.
+  const client = yield* Effect.acquireRelease(
+    Effect.try({
+      try: () =>
+        new RedisClient(url, {
+          connectionTimeout: connectMs,
+          enableOfflineQueue: false,
+          ...(maxRetries === undefined ? {} : { maxRetries }),
+        }),
+      catch: () => refused('Bun.RedisClient refused the URL'),
+    }),
+    (opened) => Effect.sync(() => opened.close()),
+  );
+  yield* Effect.tryPromise({
+    try: () => client.connect(),
+    catch: (cause) => new Redis.RedisError({ cause }),
+  }).pipe(
+    Effect.timeoutOrElse({
+      duration: connectionTimeout,
+      orElse: () => Effect.fail(refused(`did not connect within ${String(connectMs)} ms`)),
+    }),
+  );
+  // ⚠️ Address and namespace only: the URL's user and password never reach an attribute.
+  const attributes = {
+    'db.system.name': 'redis',
+    ...(fields.host === undefined ? {} : { 'server.address': fields.host }),
+    ...(fields.port === undefined ? {} : { 'server.port': fields.port }),
+    ...(fields.database === undefined ? {} : { 'db.namespace': fields.database }),
+  };
+  // ⛔ AFTER the first connect, so a wrong URL or password fails the build instead of being retried.
+  yield* keepConnected(client, { connectionTimeout, attributes });
+  return yield* Redis.make({
+    send: instrumentedSend(client, { commandTimeout, commandTimeoutMs: commandMs, attributes }),
+    subscribe,
+  });
+});
+
+/**
+ * The `Redis` service against one Valkey. ⛔ BUILDING IT CONNECTS AND AUTHENTICATES, so a wrong
+ * URL, user or password fails at startup as `RedisError`, not at the first command (Bun reports a
+ * refused password as `Connection closed`, the same text as a server that is down).
+ * The client is closed when the layer's scope closes.
+ */
+export const valkey = (options: ValkeyOptions): Layer.Layer<Redis.Redis, Redis.RedisError> =>
+  Layer.effect(
+    Redis.Redis,
+    Effect.suspend(() => build(options)),
+  );
+
+/** The environment variable `valkeyFromEnv` reads unless told another. Not a host. */
+export const VALKEY_URL_VARIABLE = 'SEAT_VALKEY_URL';
+
+export type ValkeyFromEnvOptions = Omit<ValkeyOptions, 'url'> & {
+  /** The variable holding the URL. Default `SEAT_VALKEY_URL`. */
+  readonly variable?: string | undefined;
+};
+
+/**
+ * `valkey`, its URL read from an environment variable as a `Redacted` secret. A missing variable
+ * fails as `ConfigError`, naming the variable and nothing else.
+ */
+export const valkeyFromEnv = (
+  options?: ValkeyFromEnvOptions,
+): Layer.Layer<Redis.Redis, Redis.RedisError | Config.ConfigError> => {
+  const { variable, ...rest } = options ?? {};
+  return Layer.unwrap(
+    Config.Redacted(variable ?? VALKEY_URL_VARIABLE).pipe(
+      Effect.map((url) => valkey({ ...rest, url })),
+    ),
+  );
+};

package/src/state.ts

@@ -0,0 +1,8 @@
+/**
+ * `@homeflare/seat-runtime/state` — a seat's Postgres and Valkey state, on its own subpath.
+ *
+ * ⛔ NOT THE ROOT ENTRY, ON PURPOSE. The root stays runtime-neutral (`fetch` only). This one holds
+ *   `node:net` through `@effect/sql-pg` and `Bun.RedisClient`, so a consumer opts in to it
+ *   explicitly, the way the kit's other host-specific code is reached.
+ */
+export * as SeatState from './seat-state.ts';

package/src/version.ts

@@ -0,0 +1,2 @@
+// ⛔ GENERATED by scripts/sync-versions.ts — do not edit. Source: package.json.
+export const VERSION: string = '0.1.0';