felix-client 0.5.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,184 @@
+# felix-client for Node.js and TypeScript
+
+Node bindings for Felix, built as a wrapper over the Rust client rather than a
+reimplementation of the protocol.
+
+That distinction is the point. Reconnection, redirect-following, retry
+classification and offset bookkeeping are hard to get right and expensive to
+get wrong — a second implementation is a second set of subtle bugs in exactly
+the places that matter. Here they exist once, in `felix-client`, and every
+language binds to them. The Python binding is built on the same reasoning and
+exposes the same surface.
+
+## One surface, and it is asynchronous
+
+Python offers two surfaces because its sync one is the older idiom. Node has no
+such split: blocking the event loop is not something a library may do, so every
+call here returns a `Promise`. napi-rs runs the future on its own Tokio runtime
+and settles the promise from there, which keeps the event loop free while a
+publish is in flight.
+
+```ts
+import { Client } from "felix-client";
+
+const client = await Client.connect("127.0.0.1:5000", "t1", token, "localhost", caFile);
+
+await client.publish("t1", "default", "events", Buffer.from("hello"));
+
+const events = await client.subscribe("t1", "default", "events");
+for (;;) {
+  const event = await events.nextEvent();
+  if (event === null) break;
+  console.log(event.payload.toString(), event.offset);
+}
+await events.close();
+```
+
+## What it wraps
+
+Everything the Python binding wraps, with one exception noted below.
+
+| | |
+|---|---|
+| Publish | `publish(tenant, ns, stream, payload, key?, ack?, atLeastOnce?)` |
+| Subscribe | `subscribe(...)` → `nextEvent()`, `close()`, `closed` |
+| Sharded subscribe | `subscribeSharded(..., start?, resume?)` → `nextEvent()`, `positions()`, `shards` |
+| Stream shape | `streamShards(...)`, `endpoints()` |
+| Cache | `cachePut` (with TTL), `cacheGet`, `cacheDelete` |
+| Counters | `counterAdd`, `counterGet` |
+| Cache watches | `watchCache(..., key?, prefix?, start?, retained?)` → `recv()`, `retainedCount` |
+| Consumer groups | `groupPoll`, `groupAck`, `groupNack`, `groupDeadLetters`, `groupDiscard`, `groupRedrive` |
+
+Every handle has an idempotent `close()` and implements `Symbol.asyncDispose`,
+so on Node 24 and newer a `throw` releases it on the way out:
+
+```ts
+await using events = await client.subscribe("t1", "default", "events");
+```
+
+The package itself asks only for Node 18 — `await using` is the syntax that
+needs the newer runtime, not the disposal.
+
+### Routing keys decide the shard
+
+`publish` takes an optional key. Without one every record lands on shard 0, so
+a multi-shard stream behaves like a single-shard one:
+
+```ts
+await client.publish("t1", "default", "orders", payload, Buffer.from(customerId));
+```
+
+Records sharing a key share a shard and stay ordered with respect to each
+other. Records with different keys do not, once a stream has more than one
+shard.
+
+### Offsets are how you notice a drop
+
+Subscriber queues shed under the default policy rather than blocking the
+publisher, so a subscriber can silently miss records. On a durable stream each
+delivered event carries its log offset, and a jump in them is exactly a drop —
+which is why `event.offset` is worth reading even when you do not resume from
+it.
+
+### A sharded subscription surfaces shard trouble rather than hiding it
+
+`subscribeSharded` merges every shard, and each item says which shard it came
+from. A lost shard arrives as an item of its own and does not disturb the
+others: they keep delivering, and the lost one resumes from its own last offset
+so nothing is skipped. Per-shard ordering is all a sharded stream has, and the
+handle does not pretend otherwise.
+
+### TLS is not optional
+
+QUIC has no unencrypted mode, so there are two trust choices and no third: the
+platform trust store (omit `caFile`) or an explicit CA file (what a self-signed
+development broker needs). There is deliberately no "skip verification" switch
+— it is the one setting that silently turns a secure deployment insecure, and a
+CA file covers the development case without it.
+
+### At-least-once publishing duplicates, and says so
+
+By default a publish whose outcome was ambiguous — the broker may or may not
+have written it before the connection went — is **reported, not re-sent**.
+Nothing downstream can tell two copies apart, so re-sending silently changes
+the delivery guarantee.
+
+```ts
+await client.publish("t1", "default", "events", payload, undefined, "per_message", true);
+```
+
+That is the opt-in. The record is then certain to land and **may land twice**.
+It cannot be combined with a routing key: the re-send path does not carry one
+yet, and honouring the key on the first attempt but not the re-send would move
+the duplicate to a different shard, so the combination is refused rather than
+resolved.
+
+### Errors carry an identity, not just a message
+
+```ts
+try {
+  await client.publish("t1", "default", "events", payload);
+} catch (err) {
+  if (err instanceof ConnectionError) retry();   // err.retryable === true
+  else if (err instanceof AuthError) giveUp();   // no amount of retrying grants a permission
+}
+```
+
+`FelixError` is the base; `ConnectionError`, `AuthError`, `NotFoundError`,
+`CursorError` and `InvalidArgumentError` are the branches, mirroring the Python
+binding's exceptions. Each carries a stable `code` as well, for code that would
+rather switch than test `instanceof`. Never match on the message — it is prose,
+and it will be reworded.
+
+## What is not wrapped
+
+- **Idempotent producers** (`producer_init` / `publish_idempotent`). They turn
+  an ambiguous publish into one the broker can recognise as a re-send and
+  refuse to append twice — at-least-once without the duplication. Surface over
+  a primitive that already exists, not protocol work.
+
+## Conformance
+
+This binding runs the client conformance suite and passes every required
+scenario in the catalogue, which is what makes "the Node client behaves like
+the Rust one" a checked claim rather than an intention.
+
+The suite is not a mock. `felix-cluster client-fixture` starts a real
+three-node cluster, and the tests drive it: a redirect needs a broker that does
+not own the shard, and `reconnect.survives_broker_loss` kills the broker its
+client is connected to. Each test names the scenarios it demonstrates; the run
+writes a results document, and `felix-conformance verify` checks it against the
+catalogue. A test that fails, errors, or never runs becomes a non-passing
+outcome, so a green run that quietly skipped a required scenario is still
+reported as non-conformant.
+
+```bash
+task ts:conformance          # build what it needs, run it, verify the verdict
+task conformance:scenarios   # the catalogue itself
+```
+
+Two optional scenarios are recorded as skipped with their reason:
+idempotent producers, which this binding does not wrap, and
+`error.bad_offset_is_typed`, which needs a trimmed log that a client has no way
+to produce.
+
+## Building
+
+The crate lives outside the workspace, like `felix-python` and the crates under
+`demos/`: a Node addon is a `cdylib` whose Node symbols the host process
+resolves at load time, which is correct for an addon and fatal for a test
+binary linked by `cargo test --workspace`.
+
+```bash
+task ts:check     # fmt, clippy, build — what CI runs
+task ts:build     # napi build --release (needs `npm i -g @napi-rs/cli@2`)
+```
+
+Without the napi CLI you can still load the addon, because `napi build` is
+mostly a rename: build the `cdylib` and point Node at it directly.
+
+```bash
+cargo build --release
+cp ../../target/release/libfelix_typescript.dylib ./felix.node   # .so on Linux
+node -e "console.log(Object.keys(require('./felix.node')))"
+```

package/index.d.ts

@@ -0,0 +1,422 @@
+// Hand-written to stay readable. `napi build` also emits a generated
+// `index.d.ts`; this file is the checked-in contract and the generated one is
+// expected to agree with it. `task ts:check` is where a drift shows up.
+
+/// <reference types="node" />
+
+/** One delivered record. */
+export interface Event {
+  tenantId: string;
+  namespace: string;
+  stream: string;
+  payload: Buffer;
+  /**
+   * The record's log offset on a durable stream, absent on an ephemeral one.
+   *
+   * A jump in these is exactly a drop: subscriber queues shed under the
+   * default policy rather than blocking the publisher, so a gap here is the
+   * signal that it happened.
+   */
+  offset: bigint | null;
+}
+
+/** One record handed out by a consumer group. */
+export interface GroupRecord {
+  /** What to pass to `groupAck` or `groupNack` to settle this record. */
+  offset: bigint;
+  payload: Buffer;
+  /**
+   * How many times this record has been handed out, this delivery included.
+   * `1` is a first attempt; anything higher is a redelivery, so a consumer can
+   * treat a retry differently. `0` means the broker did not report it.
+   */
+  attempts: number;
+}
+
+/** One change observed by a cache watch. */
+export interface CacheChange {
+  key: string;
+  /** `null` when the key was deleted or expired, which is not `Buffer.alloc(0)`. */
+  value: Buffer | null;
+  /** This change's cache-log offset. Re-watch from `offset + 1n` to resume. */
+  offset: bigint;
+  expiresAtMillis: bigint;
+}
+
+/**
+ * An item from a cache watch: a change, or notice that the watch fell behind.
+ *
+ * Exactly one field is set. Lag is a value rather than a rejection because it
+ * is not a failure — the watch did its job by saying so — and a filtered
+ * watch's offsets are sparse by construction, so loss cannot be inferred the
+ * way a stream subscriber infers it.
+ */
+export interface CacheWatchItem {
+  change: CacheChange | null;
+  /**
+   * Set when the watch lagged and the broker ended it. Re-watching with
+   * `start = laggedResumeFrom` is gapless.
+   */
+  laggedResumeFrom: bigint | null;
+}
+
+/**
+ * An item from a sharded subscription.
+ *
+ * Exactly one of `event`, `lostError` and `recovered` is set, and `shard` says
+ * which shard it concerns. A lost shard does not affect the others: they keep
+ * delivering while that one is re-established, and it resumes from its own
+ * last offset so nothing is skipped.
+ */
+export interface ShardEvent {
+  shard: number;
+  event: Event | null;
+  lostError: string | null;
+  recovered: boolean | null;
+}
+
+/** How much the broker must have done before a publish resolves. */
+export type AckMode = "none" | "per_message" | "per_batch";
+
+/** Where a new subscription begins. */
+export type StartPosition = "latest" | "earliest" | bigint;
+
+/** Per-shard offsets, keyed by shard number. */
+export type ShardPositions = Record<string, bigint>;
+
+/** Base class for every error this client raises. */
+export declare class FelixError extends Error {
+  /**
+   * A stable identifier for *why* this failed. Branch on this, or on the
+   * class, rather than on the message — the message is prose and will be
+   * reworded.
+   */
+  readonly code: string;
+  /** Whether retrying could plausibly succeed. Only `ConnectionError` says yes. */
+  readonly retryable: boolean;
+}
+
+/** The broker could not be reached, or the connection was lost mid-call. */
+export declare class ConnectionError extends FelixError {}
+/** The token was rejected, or lacks the permission this call needs. */
+export declare class AuthError extends FelixError {}
+/** The tenant, namespace, stream or cache does not exist on the broker. */
+export declare class NotFoundError extends FelixError {}
+/** The requested start offset is gone — retention discarded it. */
+export declare class CursorError extends FelixError {}
+/** A bad argument to this client, rather than a failure of the call. */
+export declare class InvalidArgumentError extends FelixError {}
+
+/** A live subscription. Read it with `nextEvent`, and `close` it when done. */
+export declare class SubscriptionHandle {
+  /**
+   * The next record, or `null` once the subscription has ended.
+   *
+   * There is no timeout argument because a caller that wants one can race this
+   * promise against a timer — but the losing `nextEvent` stays in flight and
+   * will resolve with the next record, so keep the promise rather than calling
+   * again.
+   */
+  nextEvent(): Promise<Event | null>;
+  /** Release the subscription. Idempotent. */
+  close(): Promise<void>;
+  readonly closed: boolean;
+  [Symbol.asyncDispose](): Promise<void>;
+}
+
+/** A subscription across every shard of a stream. */
+export declare class ShardedSubscriptionHandle {
+  /** How many shards this subscription covers. */
+  readonly shards: number;
+  /** The next item, or `null` once every shard has ended. */
+  nextEvent(): Promise<ShardEvent | null>;
+  /**
+   * The last offset seen from each shard, for resuming.
+   *
+   * Only shards that have delivered something appear. Pass it back as
+   * `resume`: each listed shard continues at `offset + 1`, and the rest start
+   * wherever `start` says.
+   */
+  positions(): Promise<ShardPositions>;
+  close(): Promise<void>;
+  readonly closed: boolean;
+  [Symbol.asyncDispose](): Promise<void>;
+}
+
+/** A live cache watch. Close it when done. */
+export declare class CacheWatchHandle {
+  /**
+   * The offset live delivery began at. Everything the broker sent before it —
+   * replay, or a retained snapshot — was already reflected there.
+   */
+  readonly resumeOffset: bigint;
+  /**
+   * True when the requested start predated what compaction kept, so the watch
+   * began from each key's current value instead of replaying history.
+   */
+  readonly resnapshot: boolean;
+  /**
+   * How many retained values arrive before live delivery on a retained watch,
+   * so an application knows the exact moment its state is complete.
+   *
+   * `0n` is a definite answer — the key or prefix held nothing at join — not a
+   * silence to wait through. `null` on a watch that did not ask for retained
+   * delivery.
+   */
+  readonly retainedCount: bigint | null;
+  /** The next item, or `null` once the watch has ended. */
+  recv(): Promise<CacheWatchItem | null>;
+  close(): Promise<void>;
+  readonly closed: boolean;
+  [Symbol.asyncDispose](): Promise<void>;
+}
+
+/** A connected Felix client. */
+export declare class Client {
+  /**
+   * Connect to a cluster.
+   *
+   * Any reachable seed address is enough; the client discovers the rest.
+   * TLS is not optional — QUIC has no unencrypted mode. Pass `caFile` to trust
+   * a specific CA (what a self-signed development broker needs), or omit it to
+   * use the operating system's trust store.
+   */
+  static connect(
+    addrs: string | string[],
+    tenantId: string,
+    token: string,
+    serverName?: string,
+    caFile?: string,
+  ): Promise<Client>;
+
+  /**
+   * Publish one record.
+   *
+   * `key` is the routing key, and it decides the shard. Without one every
+   * record lands on shard 0, so a multi-shard stream behaves like a
+   * single-shard one. Records sharing a key stay ordered with respect to each
+   * other; records with different keys do not.
+   *
+   * `atLeastOnce` **may duplicate the record.** By default a publish that
+   * fails after the broker may already have written it is reported, not
+   * re-sent, because nothing downstream can tell the copies apart. With
+   * `atLeastOnce` it is re-sent to another broker instead: the record is then
+   * certain to land, and may land twice. That is a delivery guarantee you
+   * choose, never one this client assumes — and it cannot be combined with
+   * `key`, which the re-send path does not yet carry.
+   */
+  publish(
+    tenantId: string,
+    namespace: string,
+    stream: string,
+    payload: Buffer,
+    key?: Buffer,
+    ack?: AckMode,
+    atLeastOnce?: boolean,
+  ): Promise<void>;
+
+  /**
+   * Subscribe to a stream.
+   *
+   * `start` is the first record you have *not* seen, so a resuming client
+   * passes the offset it last handled plus one.
+   *
+   * A subscription reads **one shard**. For a multi-shard stream that is shard
+   * 0; `subscribeSharded` is what reads the whole stream.
+   */
+  subscribe(
+    tenantId: string,
+    namespace: string,
+    stream: string,
+    start?: StartPosition,
+  ): Promise<SubscriptionHandle>;
+
+  /**
+   * Subscribe to **every** shard of a stream and merge them.
+   *
+   * Per-shard ordering only — that is all a sharded stream has. A lost shard
+   * does not disturb the others, and resumes from its own offset.
+   *
+   * `resume` is a `positions()` result. Offsets are per shard, so resuming is
+   * a map rather than a number: one number carried across shards replays on
+   * all but one of them.
+   */
+  subscribeSharded(
+    tenantId: string,
+    namespace: string,
+    stream: string,
+    start?: StartPosition,
+    resume?: ShardPositions,
+  ): Promise<ShardedSubscriptionHandle>;
+
+  /**
+   * How many shards a stream was placed with.
+   *
+   * `0` means the broker knows nothing of the stream, which is deliberately
+   * not `1`: told "one shard" for a stream that does not exist, a consumer
+   * would read shard 0, report success, and find out later as missing data.
+   */
+  streamShards(tenantId: string, namespace: string, stream: string): Promise<number>;
+
+  /** Every broker this client would try, seeds included. */
+  endpoints(): Promise<string[]>;
+
+  /** Store a value, optionally with a time-to-live in seconds. */
+  cachePut(
+    tenantId: string,
+    namespace: string,
+    cache: string,
+    key: string,
+    value: Buffer,
+    ttlSeconds?: number,
+  ): Promise<void>;
+
+  /** Read a value, or `null` if the key is absent or expired. */
+  cacheGet(
+    tenantId: string,
+    namespace: string,
+    cache: string,
+    key: string,
+  ): Promise<Buffer | null>;
+
+  /**
+   * Remove a key, returning what it held, or `null` if it held nothing.
+   *
+   * The previous value is the return rather than a discard: it is what lets a
+   * caller tell "I deleted something" from "it was already gone" without a
+   * second round trip.
+   */
+  cacheDelete(
+    tenantId: string,
+    namespace: string,
+    cache: string,
+    key: string,
+  ): Promise<Buffer | null>;
+
+  /** Add to a counter and return its new value. `delta` may be negative. */
+  counterAdd(
+    tenantId: string,
+    namespace: string,
+    cache: string,
+    key: string,
+    delta: number,
+  ): Promise<number>;
+
+  /**
+   * Read a counter's current value, or `null` if it does not exist.
+   *
+   * Absent is not zero: a counter nobody has added to has never been written,
+   * and the distinction is the caller's to make.
+   */
+  counterGet(
+    tenantId: string,
+    namespace: string,
+    cache: string,
+    key: string,
+  ): Promise<number | null>;
+
+  /**
+   * Watch one cache for changes.
+   *
+   * Exactly one of `key` or `prefix` selects what to watch; a `prefix` of `""`
+   * is every key in the shard.
+   *
+   * `start` is the first cache-log offset you have *not* seen, so a resuming
+   * watcher passes the offset it last handled plus one. `retained` instead
+   * delivers each matching key's current value first and then live changes —
+   * join a room and immediately hold the roster. The two are mutually
+   * exclusive, and asking for both is refused rather than resolved.
+   */
+  watchCache(
+    tenantId: string,
+    namespace: string,
+    cache: string,
+    key?: string,
+    prefix?: string,
+    start?: bigint,
+    retained?: boolean,
+  ): Promise<CacheWatchHandle>;
+
+  /**
+   * Claim up to `maxRecords` from a consumer group, waiting up to `waitMs` for
+   * one to appear.
+   *
+   * Each record stays claimed until acked or the visibility timeout lapses, at
+   * which point it is handed to someone else — which is why `attempts` is
+   * worth reading. An empty array is an answer, not a failure: the group is
+   * owed nothing right now.
+   */
+  groupPoll(
+    tenantId: string,
+    namespace: string,
+    stream: string,
+    shard: number,
+    group: string,
+    maxRecords?: number,
+    waitMs?: number,
+  ): Promise<GroupRecord[]>;
+
+  /** Finish a record: it will not be handed out again. */
+  groupAck(
+    tenantId: string,
+    namespace: string,
+    stream: string,
+    shard: number,
+    group: string,
+    offset: bigint,
+  ): Promise<void>;
+
+  /** Return a record for redelivery without waiting out its timeout. */
+  groupNack(
+    tenantId: string,
+    namespace: string,
+    stream: string,
+    shard: number,
+    group: string,
+    offset: bigint,
+  ): Promise<void>;
+
+  /** Offsets this group gave up on after exhausting their attempts. */
+  groupDeadLetters(
+    tenantId: string,
+    namespace: string,
+    stream: string,
+    shard: number,
+    group: string,
+  ): Promise<bigint[]>;
+
+  /** Drop a dead-lettered record permanently. */
+  groupDiscard(
+    tenantId: string,
+    namespace: string,
+    stream: string,
+    shard: number,
+    group: string,
+    offset: bigint,
+  ): Promise<void>;
+
+  /** Put a dead-lettered record back into the group for another attempt. */
+  groupRedrive(
+    tenantId: string,
+    namespace: string,
+    stream: string,
+    shard: number,
+    group: string,
+    offset: bigint,
+  ): Promise<void>;
+
+  /**
+   * Release the client. Idempotent.
+   *
+   * Later calls fail rather than quietly using a connection that was meant to
+   * be gone. Subscriptions already handed out hold their own connection and
+   * keep running — closing the client is not a way to stop them, and `close`
+   * on the subscription is.
+   */
+  close(): void;
+  readonly closed: boolean;
+  [Symbol.asyncDispose](): Promise<void>;
+}
+
+/** The unwrapped addon, for anyone who wants it. Errors are untyped there. */
+export declare const native: unknown;

package/index.js

@@ -0,0 +1,252 @@
+// The package's JavaScript half: load the addon, and give its errors an
+// identity a caller can branch on.
+//
+// The native layer cannot set `err.code` itself — napi puts an error's status
+// there and `#[napi]` requires that status to be napi's own fixed enum. So it
+// prefixes the message with a Felix code and this file lifts it onto a typed
+// error. Both halves ship as one package, so that prefix is an internal detail
+// rather than something a caller parses.
+//
+// The class hierarchy mirrors the Python binding's exceptions, because the
+// distinction is the same one in both languages: what an application can
+// *decide* from a failure. A connection failure is worth another attempt
+// against another broker; an authorization failure, a missing stream, or a
+// discarded offset will fail the same way every time.
+
+"use strict";
+
+const { existsSync } = require("node:fs");
+const { join } = require("node:path");
+
+/** Base class for every error this client raises. */
+class FelixError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = new.target.name;
+    /**
+     * A stable identifier for *why* this failed. Branch on this, or on the
+     * class, rather than on the message — the message is prose and will be
+     * reworded.
+     */
+    this.code = code;
+  }
+
+  /**
+   * Whether retrying could plausibly succeed.
+   *
+   * Only `ConnectionError` says yes. An authorization failure, a missing
+   * stream, or a discarded offset fails the same way every time — retrying
+   * them burns a budget on a call that cannot succeed.
+   */
+  get retryable() {
+    return false;
+  }
+}
+
+/** The broker could not be reached, or the connection was lost mid-call. */
+class ConnectionError extends FelixError {
+  get retryable() {
+    return true;
+  }
+}
+
+/** The token was rejected, or lacks the permission this call needs. */
+class AuthError extends FelixError {}
+
+/** The tenant, namespace, stream or cache does not exist on the broker. */
+class NotFoundError extends FelixError {}
+
+/** The requested start offset is gone — retention discarded it. */
+class CursorError extends FelixError {}
+
+/** A bad argument to this client, rather than a failure of the call. */
+class InvalidArgumentError extends FelixError {}
+
+const CLASSES = new Map([
+  ["FELIX_CONNECTION", ConnectionError],
+  ["FELIX_AUTH", AuthError],
+  ["FELIX_NOT_FOUND", NotFoundError],
+  ["FELIX_CURSOR", CursorError],
+  ["FELIX_INVALID", InvalidArgumentError],
+  ["FELIX_ERROR", FelixError],
+]);
+
+/** Lift a native error into a typed one, leaving anything else alone. */
+function typed(err) {
+  const message = err && typeof err.message === "string" ? err.message : "";
+  const at = message.indexOf(": ");
+  if (at > 0) {
+    const Class = CLASSES.get(message.slice(0, at));
+    if (Class) {
+      const out = new Class(message.slice(0, at), message.slice(at + 2));
+      // Keep the native stack: it names the call that failed.
+      if (err.stack) out.stack = err.stack.replace(message, out.message);
+      return out;
+    }
+  }
+  return err;
+}
+
+/**
+ * What this machine's binary is called, in napi's naming.
+ *
+ * It names both the platform package (`felix-client-linux-x64-gnu`) and the
+ * file inside it (`felix.linux-x64-gnu.node`), so the two cannot drift.
+ */
+function platformTag() {
+  const { platform, arch } = process;
+  if (platform === "linux") {
+    // A glibc build will not load on musl. `glibcVersionRuntime` is absent on
+    // musl, which is the only reliable check from inside Node — reading
+    // `process.report` costs nothing and is not gated on a flag.
+    let libc = "musl";
+    try {
+      if (process.report?.getReport()?.header?.glibcVersionRuntime) libc = "gnu";
+    } catch {
+      // A locked-down runtime can refuse the report. Assume glibc, which is
+      // what is published; the load below fails with a clear message if wrong.
+      libc = "gnu";
+    }
+    return `linux-${arch}-${libc}`;
+  }
+  if (platform === "win32") return `win32-${arch}-msvc`;
+  return `${platform}-${arch}`;
+}
+
+function loadAddon() {
+  const tag = platformTag();
+
+  // The repository shares one target directory across every crate, this one
+  // included (`.cargo/config.toml`), so a development build lands at the root
+  // rather than beside this file.
+  const roots = [join(__dirname, "target"), join(__dirname, "..", "..", "target")];
+  const names = [
+    "libfelix_typescript.dylib",
+    "libfelix_typescript.so",
+    "felix_typescript.dll",
+  ];
+  // `napi build --platform` writes the tagged name; a plain `napi build` the
+  // bare one. Both are checked before the installed package, so a local
+  // rebuild wins over whatever npm put in node_modules.
+  const candidates = [
+    join(__dirname, `felix.${tag}.node`),
+    join(__dirname, "felix.node"),
+  ];
+  // A plain `cargo build` is enough to use this package, which is what keeps it
+  // usable without the napi CLI — `napi build` is mostly a rename.
+  for (const profile of ["release", "debug"]) {
+    for (const root of roots) {
+      for (const name of names) candidates.push(join(root, profile, name));
+    }
+  }
+  for (const path of candidates) {
+    if (!existsSync(path)) continue;
+    if (path.endsWith(".node")) return require(path);
+    // Node only `require`s files named `.node`, but `process.dlopen` — which
+    // is what `require` calls underneath — takes any path. That is what lets a
+    // plain `cargo build` be enough, with no rename step.
+    const shim = { exports: {} };
+    process.dlopen(shim, path);
+    return shim.exports;
+  }
+
+  // An installed package has none of the above: npm ships one package per
+  // platform and this package declares them all as optional dependencies, so
+  // exactly the matching one is present.
+  const pkg = `felix-client-${tag}`;
+  try {
+    return require(pkg);
+  } catch (err) {
+    // MODULE_NOT_FOUND here means this platform has no published binary, which
+    // is worth saying plainly — the alternative is a stack trace about a
+    // package the caller never named.
+    if (err?.code !== "MODULE_NOT_FOUND") throw err;
+  }
+
+  throw new Error(
+    `felix-client: no native addon for ${tag}. Either this platform has no ` +
+      `published binary, or the optional dependency ${pkg} did not install. ` +
+      `From a checkout, build it with \`napi build --release\` or ` +
+      `\`cargo build --release\` in crates/felix-typescript.`,
+  );
+}
+
+const native = loadAddon();
+
+/**
+ * Whether `value` is one of the addon's own classes.
+ *
+ * Only those get wrapped. Everything else a method resolves with — a Buffer, an
+ * array of records, a plain object — is the caller's data, and a Proxy around
+ * it is not that data: `deepStrictEqual` sees through to the handler,
+ * `Buffer.concat` and other brand checks can reject it, and the caller has no
+ * way to unwrap. Wrapping only the handles keeps the typed-error layer on the
+ * calls, where it belongs, and leaves the payloads alone.
+ */
+function isHandle(value) {
+  const constructor = value?.constructor;
+  return typeof constructor === "function" && native[constructor.name] === constructor;
+}
+
+/**
+ * Wrap a native handle so every rejection arrives typed.
+ *
+ * A Proxy rather than patching the prototype: napi defines its methods
+ * non-configurable, so `defineProperty` refuses. Proxying also means a method
+ * added to the Rust side is covered without being listed here — nothing to
+ * forget.
+ *
+ * `Symbol.asyncDispose` is added on top so `await using` releases a handle on
+ * every path out of a block, including a throw. It resolves to `close` when
+ * the instance has one, and to nothing when it does not.
+ */
+function wrap(value) {
+  if (!isHandle(value)) return value;
+  return new Proxy(value, {
+    get(target, prop) {
+      if (prop === Symbol.asyncDispose) {
+        if (typeof target.close !== "function") return undefined;
+        return async function dispose() {
+          await target.close();
+        };
+      }
+      const member = Reflect.get(target, prop, target);
+      if (typeof member !== "function") return member;
+      return function called(...args) {
+        try {
+          const out = member.apply(target, args);
+          if (out && typeof out.then === "function") {
+            return out.then(wrap, (err) => Promise.reject(typed(err)));
+          }
+          return wrap(out);
+        } catch (err) {
+          throw typed(err);
+        }
+      };
+    },
+  });
+}
+
+/** The public `Client`: a façade over the native one that types its errors. */
+const Client = {
+  async connect(addrs, tenantId, token, serverName, caFile) {
+    try {
+      const client = await native.Client.connect(addrs, tenantId, token, serverName, caFile);
+      return wrap(client);
+    } catch (err) {
+      throw typed(err);
+    }
+  },
+};
+
+module.exports = {
+  Client,
+  FelixError,
+  ConnectionError,
+  AuthError,
+  NotFoundError,
+  CursorError,
+  InvalidArgumentError,
+  /** The unwrapped addon, for anyone who wants it. Errors are untyped there. */
+  native,
+};

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "felix-client",
+  "version": "0.5.0",
+  "description": "Node.js/TypeScript bindings for the Felix client, over the Rust client rather than a reimplementation of it",
+  "keywords": [
+    "felix",
+    "quic",
+    "pubsub",
+    "streaming",
+    "cache",
+    "queue",
+    "napi",
+    "bindings"
+  ],
+  "license": "Apache-2.0",
+  "author": "Gabriel Loewen",
+  "homepage": "https://gabloe.github.io/felix/clients/typescript/",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gabloe/felix.git",
+    "directory": "crates/felix-typescript"
+  },
+  "bugs": {
+    "url": "https://github.com/gabloe/felix/issues"
+  },
+  "main": "index.js",
+  "types": "index.d.ts",
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "napi": {
+    "name": "felix",
+    "triples": {
+      "defaults": false,
+      "additional": [
+        "aarch64-apple-darwin",
+        "aarch64-unknown-linux-gnu",
+        "x86_64-apple-darwin",
+        "x86_64-pc-windows-msvc",
+        "x86_64-unknown-linux-gnu"
+      ]
+    }
+  },
+  "scripts": {
+    "build": "napi build --platform --release",
+    "build:debug": "napi build --platform",
+    "test": "node --test test/conformance.test.mjs"
+  },
+  "optionalDependencies": {
+    "felix-client-darwin-arm64": "0.5.0",
+    "felix-client-darwin-x64": "0.5.0",
+    "felix-client-linux-arm64-gnu": "0.5.0",
+    "felix-client-linux-x64-gnu": "0.5.0",
+    "felix-client-win32-x64-msvc": "0.5.0"
+  }
+}