@intentius/chant-k8s-client 0.58.0 → 0.59.0

package/dist/client.d.ts

@@ -34,6 +34,7 @@
  * path that writes the `Authorization` header — runs for real, which is what
  * makes a test that injects one worth writing.
  */
+import { type WatchFrame } from "./watch.js";
 import type { ApiResourceInfo, ClientProvenance, K8sClientOptions, K8sObject, ObjectRef, ResourceSelector, KubeconfigView } from "./types.js";
 type ClientNode = typeof import("@kubernetes/client-node");
 /**
@@ -136,6 +137,55 @@ export interface ReadLogOptions {
     timestamps?: boolean;
     signal?: AbortSignal;
 }
+/**
+ * Options for {@link K8sClient.watch} (chant #1981).
+ *
+ * A watch is a trigger channel, so the interesting options are the ones that
+ * bound it (a namespace, a label selector) rather than anything about what
+ * comes back.
+ */
+export interface WatchOptions {
+    /** Restrict to one namespace. Omitted watches across all of them. */
+    namespace?: string;
+    /** A label selector, e.g. `app.kubernetes.io/managed-by=chant`. */
+    labelSelector?: string;
+    /**
+     * Called once per event frame, with the frame the server sent.
+     *
+     * The frame is passed through verbatim rather than interpreted, because this
+     * package has no opinion about what a change means. Chant's own consumer
+     * (the k8s lexicon's `subscribeChanges`) ignores it entirely and calls a
+     * no-argument `onChange`, which is the rule that keeps a watch event from
+     * ever becoming an observation.
+     */
+    onEvent?(frame: WatchFrame): void;
+    /**
+     * The watch ended for a reason that is not "you closed it". Called at most
+     * once, and the watch is over when it is: re-establishing is the caller's
+     * decision, made with the caller's own backoff.
+     */
+    onError?(message: string): void;
+    /** Aborts the watch, exactly as {@link WatchHandle.close} does. */
+    signal?: AbortSignal;
+    /**
+     * How long to wait before reopening a stream the server closed cleanly.
+     * The API server ends a watch connection every few minutes by design, which
+     * is a reconnect rather than a failure. @default 1000
+     */
+    reopenDelayMs?: number;
+}
+/** A live watch. Returned by {@link K8sClient.watch}. */
+export interface WatchHandle {
+    /**
+     * Stop the watch and release its connection. Idempotent, and safe to call
+     * after the watch has already ended on its own. Resolves once the reader
+     * has actually unwound, so a caller that closes and then asserts on request
+     * counts is not racing the stream.
+     */
+    close(): Promise<void>;
+    /** Resolves when the watch is over, however it ended. Never rejects. */
+    readonly done: Promise<void>;
+}
 /** The client surface the k8s lexicon consumes. */
 export interface K8sClient {
     /** Where this client is pointed and what authorized it. */
@@ -166,6 +216,19 @@ export interface K8sClient {
     readIfPresent(ref: ObjectRef, options?: ReadOptions): Promise<K8sObject | undefined>;
     /** LIST a kind, optionally namespaced and label-filtered. Follows `continue` tokens. */
     list(selector: ResourceSelector, options?: ListOptions): Promise<K8sObject[]>;
+    /**
+     * WATCH a kind: a long-lived `GET ...?watch=1&resourceVersion=<rv>` whose
+     * NDJSON frames arrive at `options.onEvent` until somebody closes it (chant
+     * #1981).
+     *
+     * The `resourceVersion` comes from a LIST issued first, which is the only
+     * way to start a watch without a gap. A `410 Gone`, the server saying that
+     * version has aged out of its change history, re-LISTs and resumes from the
+     * new version rather than retrying the stale one; a stream the server closes
+     * cleanly is reopened from the last version seen. Anything else ends the
+     * watch through `options.onError`.
+     */
+    watch(selector: ResourceSelector, options?: WatchOptions): Promise<WatchHandle>;
     /**
      * GET a Pod's `/log` subresource — plain text, not JSON, which is why this
      * is its own method rather than a `read` variant. A snapshot only: the

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -12,7 +12,9 @@
  * it stays that way.
  */
 export { createK8sClient, readAmbientContext, readKubeconfigView, loadClientNode, isK8sClientAvailable, apiVersionPath, splitApiVersion, selectorText, refText, } from "./client.js";
-export type { K8sClient, ReadOptions, ApplyOptions, DeleteOptions, ListOptions, ReadLogOptions, SelfSubjectInfo } from "./client.js";
+export type { K8sClient, ReadOptions, ApplyOptions, DeleteOptions, ListOptions, ReadLogOptions, SelfSubjectInfo, WatchOptions, WatchHandle, } from "./client.js";
+export { parseWatchFrames, isExpiredFrame, resourceVersionOf, streamLines } from "./watch.js";
+export type { WatchFrame, WatchEventType } from "./watch.js";
 export { K8sApiError, K8sTransportError, K8sClientUnavailableError, ExecCredentialNotAllowedError, FieldManagerError, KubeConfigError, UnknownResourceError, } from "./errors.js";
 export type { K8sStatus } from "./errors.js";
 export { CHANT_FIELD_MANAGER, FIELD_MANAGER_SEPARATOR, FIELD_MANAGER_MAX_LENGTH, fieldManagerFor, assertValidFieldManager, isChantFieldManager, chantStackOf, } from "./field-manager.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EACL,eAAe,EACf,kBAAkB,EAClB,kBAAkB,EAClB,cAAc,EACd,oBAAoB,EACpB,cAAc,EACd,eAAe,EACf,YAAY,EACZ,OAAO,GACR,MAAM,UAAU,CAAC;AAClB,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAElI,OAAO,EACL,WAAW,EACX,iBAAiB,EACjB,yBAAyB,EACzB,6BAA6B,EAC7B,iBAAiB,EACjB,eAAe,EACf,oBAAoB,GACrB,MAAM,UAAU,CAAC;AAClB,YAAY,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAG1C,OAAO,EACL,mBAAmB,EACnB,uBAAuB,EACvB,wBAAwB,EACxB,eAAe,EACf,uBAAuB,EACvB,mBAAmB,EACnB,YAAY,GACb,MAAM,iBAAiB,CAAC;AACzB,YAAY,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAE5D,OAAO,EACL,yBAAyB,EACzB,sBAAsB,EACtB,mBAAmB,EACnB,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAGhE,OAAO,EACL,eAAe,EACf,WAAW,EACX,UAAU,EACV,aAAa,EACb,gBAAgB,EAChB,WAAW,EACX,YAAY,EACZ,aAAa,GACd,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAE5E,OAAO,EACL,sBAAsB,EACtB,2BAA2B,EAC3B,gBAAgB,EAChB,YAAY,EACZ,eAAe,GAChB,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEhE,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAEnE,YAAY,EACV,eAAe,EACf,gBAAgB,EAChB,cAAc,EACd,gBAAgB,EAChB,qBAAqB,EACrB,cAAc,EACd,SAAS,EACT,SAAS,EACT,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,EAChB,mBAAmB,GACpB,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EACL,eAAe,EACf,kBAAkB,EAClB,kBAAkB,EAClB,cAAc,EACd,oBAAoB,EACpB,cAAc,EACd,eAAe,EACf,YAAY,EACZ,OAAO,GACR,MAAM,UAAU,CAAC;AAClB,YAAY,EACV,SAAS,EAAE,WAAW,EAAE,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,cAAc,EAChF,eAAe,EAAE,YAAY,EAAE,WAAW,GAC3C,MAAM,UAAU,CAAC;AAKlB,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAC3F,YAAY,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE1D,OAAO,EACL,WAAW,EACX,iBAAiB,EACjB,yBAAyB,EACzB,6BAA6B,EAC7B,iBAAiB,EACjB,eAAe,EACf,oBAAoB,GACrB,MAAM,UAAU,CAAC;AAClB,YAAY,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAG1C,OAAO,EACL,mBAAmB,EACnB,uBAAuB,EACvB,wBAAwB,EACxB,eAAe,EACf,uBAAuB,EACvB,mBAAmB,EACnB,YAAY,GACb,MAAM,iBAAiB,CAAC;AACzB,YAAY,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAE5D,OAAO,EACL,yBAAyB,EACzB,sBAAsB,EACtB,mBAAmB,EACnB,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAGhE,OAAO,EACL,eAAe,EACf,WAAW,EACX,UAAU,EACV,aAAa,EACb,gBAAgB,EAChB,WAAW,EACX,YAAY,EACZ,aAAa,GACd,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAE5E,OAAO,EACL,sBAAsB,EACtB,2BAA2B,EAC3B,gBAAgB,EAChB,YAAY,EACZ,eAAe,GAChB,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEhE,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAEnE,YAAY,EACV,eAAe,EACf,gBAAgB,EAChB,cAAc,EACd,gBAAgB,EAChB,qBAAqB,EACrB,cAAc,EACd,SAAS,EACT,SAAS,EACT,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,EAChB,mBAAmB,GACpB,MAAM,SAAS,CAAC"}

package/dist/testing.d.ts

@@ -29,6 +29,13 @@ export interface FakeResponse {
     status?: number;
     body?: unknown;
     headers?: Record<string, string>;
+    /**
+     * A streaming body, for a watch (chant #1981). Anything async-iterable will
+     * do, and {@link fakeWatchStream} is the usual source. Set it and the response
+     * exposes `body.stream()`, which is what the client reads instead of
+     * `text()` for a request it never expects to complete.
+     */
+    stream?: AsyncIterable<string | Uint8Array>;
 }
 export type FakeRequestHandler = (request: RecordedRequest) => FakeResponse | Promise<FakeResponse>;
 /** A recording {@link RequestLayer} driven by `handler`. */
@@ -81,4 +88,31 @@ export declare function apiResourceList(groupVersion: string, resources: Array<{
     shortNames?: string[];
     verbs?: string[];
 }>): Record<string, unknown>;
+/** A watch stream a test drives by hand. */
+export interface FakeWatchStream extends AsyncIterable<string> {
+    /**
+     * Send one NDJSON frame down the stream. Objects are stringified; a string
+     * is sent verbatim, which is how a test produces a malformed or half-written
+     * frame. A newline is appended unless the string already ends in one.
+     */
+    push(frame: unknown): void;
+    /** End the stream, as a server closing the connection does. */
+    close(): void;
+    /** How many frames have been consumed by the reader. */
+    readonly delivered: number;
+}
+/**
+ * A controllable NDJSON stream for driving {@link import("./client.js").K8sClient.watch}
+ * against the fake cluster (chant #1981).
+ *
+ * The client reads it exactly as it reads a live watch: one frame per line,
+ * for as long as the connection stays open. So a test can push an ADDED, an
+ * expired-`410` ERROR, or nothing at all, and assert on what the client does
+ * about it, without a cluster, a socket, or a timer.
+ */
+export declare function fakeWatchStream(): FakeWatchStream;
+/** A watch event frame, the shape the API server sends. */
+export declare function watchFrame(type: string, object: Record<string, unknown>): Record<string, unknown>;
+/** The `410 Gone` frame a watch gets when its resourceVersion has aged out. */
+export declare function expiredWatchFrame(message?: string): Record<string, unknown>;
 //# sourceMappingURL=testing.d.ts.map

package/dist/testing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAsB,YAAY,EAAuB,MAAM,SAAS,CAAC;AAErF,8CAA8C;AAC9C,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,uCAAuC;IACvC,GAAG,EAAE,MAAM,CAAC;IACZ,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,EAAE,OAAO,CAAC;CACf;AAED,qFAAqF;AACrF,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,EAAE,eAAe,KAAK,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;AAEpG,4DAA4D;AAC5D,MAAM,WAAW,gBAAiB,SAAQ,YAAY;IACpD,iDAAiD;IACjD,QAAQ,CAAC,QAAQ,EAAE,eAAe,EAAE,CAAC;IACrC,yDAAyD;IACzD,KAAK,IAAI,MAAM,EAAE,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,kBAAkB,GAAG,gBAAgB,CA8B9E;AAED,8EAA8E;AAC9E,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAUjG;AAED,0CAA0C;AAC1C,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACxF,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uEAAuE;IACvE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yEAAyE;IACzE,IAAI,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,GAAG,CAAC,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;KAAE,CAAC;CAC3F;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,OAAO,GAAE,qBAA0B,GAAG,MAAM,CAkD1E;AAED,qFAAqF;AACrF,wBAAgB,eAAe,CAC7B,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,KAAK,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB,CAAC,GACD,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAczB"}
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -169,6 +169,24 @@ export interface ResponseContextLike {
     headers: Record<string, string>;
     body: {
         text(): Promise<string>;
+        /**
+         * The body as it arrives, rather than once it is complete (chant #1981).
+         *
+         * `text()` reads a response to completion, which is the right shape for
+         * every request this client makes except one: a watch never completes, so
+         * a watch read through `text()` is a promise that resolves when the
+         * cluster hangs up and never before. client-node's own HTTP library
+         * already exposes `stream()` (its `undici` `fetch` response's web
+         * `ReadableStream`), so the seam widens rather than being invented.
+         *
+         * Typed `unknown` for the same reason the rest of this file avoids the
+         * library's classes: the decoder (`./watch.ts`'s `streamLines`) accepts a
+         * web `ReadableStream`, a Node `Readable`, or any async iterable. Optional
+         * because a transport without it is still a valid transport: the watch
+         * falls back to `text()`, which is exactly what a fake returning a
+         * complete NDJSON body wants.
+         */
+        stream?(): unknown;
     };
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/watch.d.ts

@@ -0,0 +1,75 @@
+/**
+ * The Kubernetes watch, as much of it as can be written without a client
+ * (chant #1981).
+ *
+ * A watch is `GET <list path>?watch=1&resourceVersion=<rv>` answered with an
+ * open connection that emits one JSON document per line. NDJSON, forever,
+ * until somebody hangs up. Everything here is the frame side of that: parsing
+ * lines out of a byte stream, reading a frame's `resourceVersion`, and
+ * recognising the one failure a watch is expected to hit.
+ *
+ * ## `410 Gone`
+ *
+ * The API server keeps a bounded history of changes. A watch resuming from a
+ * `resourceVersion` older than that window cannot be told what it missed, and
+ * says so: an `ERROR` frame carrying a `Status` with `code: 410` / `reason:
+ * Expired`. There is exactly one correct response, and it is not to retry with
+ * the same `resourceVersion`. It is to LIST again, take the list's own
+ * `resourceVersion`, and watch from there. Anything else silently drops
+ * whatever happened during the gap.
+ *
+ * For chant's purposes the gap costs nothing anyway: the events are a trigger,
+ * never a fact, and the tick they wake re-observes the estate from scratch. A
+ * re-list is a re-list, not a reconciliation.
+ */
+import type { K8sObject } from "./types.js";
+/** The event types the watch API emits. `BOOKMARK` requires `allowWatchBookmarks`. */
+export type WatchEventType = "ADDED" | "MODIFIED" | "DELETED" | "BOOKMARK" | "ERROR";
+/**
+ * One decoded NDJSON frame. `object` is whatever the server put in the frame:
+ * the changed resource for the four ordinary types, a `Status` for `ERROR`.
+ */
+export interface WatchFrame {
+    type: WatchEventType;
+    object: K8sObject;
+}
+/**
+ * Split a chunk of a watch stream into whole frames, carrying the trailing
+ * partial line over to the next call.
+ *
+ * Frames arrive split across TCP reads at arbitrary byte offsets, so a decoder
+ * that treats each chunk as a set of complete lines drops or corrupts every
+ * frame that straddles a boundary. `carry` is the fix and the reason this is a
+ * function rather than three lines inline.
+ *
+ * A line that is not JSON, or is JSON without a known `type`, is dropped
+ * rather than thrown: a watch is a trigger channel, and the correct response
+ * to a frame nobody can read is to keep watching.
+ */
+export declare function parseWatchFrames(chunk: string, carry?: string): {
+    frames: WatchFrame[];
+    carry: string;
+};
+/**
+ * Whether this frame is the API server saying the watch's `resourceVersion` has
+ * aged out of its history: the `410 Gone` that means re-list, not retry.
+ *
+ * Matched on `code` first and `reason` second, because both are set on the
+ * `Status` the server sends and a cluster that sets only one of them is still
+ * telling us the same thing.
+ */
+export declare function isExpiredFrame(frame: WatchFrame): boolean;
+/** The `resourceVersion` to resume from after this frame, when it carries one. */
+export declare function resourceVersionOf(frame: WatchFrame): string | undefined;
+/**
+ * Decode whatever a response body's `stream()` returned into lines of text.
+ *
+ * Three shapes reach here and all three are real: a web `ReadableStream` (what
+ * `undici`'s `fetch` gives client-node's HTTP library, and so what a live
+ * cluster produces), a Node `Readable` or any other async iterable (what a
+ * hand-rolled transport gives), and `undefined` for a transport with no
+ * streaming seam at all, which is a fake that answered the whole body at once and
+ * is handled by the caller reading `text()` instead.
+ */
+export declare function streamLines(source: unknown): AsyncGenerator<string>;
+//# sourceMappingURL=watch.d.ts.map

package/dist/watch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch.d.ts","sourceRoot":"","sources":["../src/watch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEzC,sFAAsF;AACtF,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,UAAU,GAAG,SAAS,GAAG,UAAU,GAAG,OAAO,CAAC;AAErF;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,cAAc,CAAC;IACrB,MAAM,EAAE,SAAS,CAAC;CACnB;AAID;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,MAAM,EACb,KAAK,SAAK,GACT;IAAE,MAAM,EAAE,UAAU,EAAE,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CA2BzC;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAKzD;AAED,kFAAkF;AAClF,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS,CAGvE;AAED;;;;;;;;;GASG;AACH,wBAAuB,WAAW,CAAC,MAAM,EAAE,OAAO,GAAG,cAAc,CAAC,MAAM,CAAC,CAuC1E"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-k8s-client",
-  "version": "0.58.0",
+  "version": "0.59.0",
   "description": "Typed Kubernetes API client for chant — the read/write path of the k8s lexicon, kept out of the build path",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant/lexicons/k8s/api-client/",

package/src/client.ts

@@ -48,6 +48,7 @@ import { asFieldManagerConflict } from "./conflict";
 import { assertValidFieldManager, CHANT_FIELD_MANAGER } from "./field-manager";
 import { DEFAULT_CONCURRENCY, mapConcurrent } from "./concurrency";
 import { loadKubeConfig } from "./kubeconfig";
+import { isExpiredFrame, parseWatchFrames, resourceVersionOf, streamLines, type WatchFrame } from "./watch";
 import type {
   ApiResourceInfo,
   ClientProvenance,
@@ -224,6 +225,57 @@ export interface ReadLogOptions {
   signal?: AbortSignal;
 }
 
+/**
+ * Options for {@link K8sClient.watch} (chant #1981).
+ *
+ * A watch is a trigger channel, so the interesting options are the ones that
+ * bound it (a namespace, a label selector) rather than anything about what
+ * comes back.
+ */
+export interface WatchOptions {
+  /** Restrict to one namespace. Omitted watches across all of them. */
+  namespace?: string;
+  /** A label selector, e.g. `app.kubernetes.io/managed-by=chant`. */
+  labelSelector?: string;
+  /**
+   * Called once per event frame, with the frame the server sent.
+   *
+   * The frame is passed through verbatim rather than interpreted, because this
+   * package has no opinion about what a change means. Chant's own consumer
+   * (the k8s lexicon's `subscribeChanges`) ignores it entirely and calls a
+   * no-argument `onChange`, which is the rule that keeps a watch event from
+   * ever becoming an observation.
+   */
+  onEvent?(frame: WatchFrame): void;
+  /**
+   * The watch ended for a reason that is not "you closed it". Called at most
+   * once, and the watch is over when it is: re-establishing is the caller's
+   * decision, made with the caller's own backoff.
+   */
+  onError?(message: string): void;
+  /** Aborts the watch, exactly as {@link WatchHandle.close} does. */
+  signal?: AbortSignal;
+  /**
+   * How long to wait before reopening a stream the server closed cleanly.
+   * The API server ends a watch connection every few minutes by design, which
+   * is a reconnect rather than a failure. @default 1000
+   */
+  reopenDelayMs?: number;
+}
+
+/** A live watch. Returned by {@link K8sClient.watch}. */
+export interface WatchHandle {
+  /**
+   * Stop the watch and release its connection. Idempotent, and safe to call
+   * after the watch has already ended on its own. Resolves once the reader
+   * has actually unwound, so a caller that closes and then asserts on request
+   * counts is not racing the stream.
+   */
+  close(): Promise<void>;
+  /** Resolves when the watch is over, however it ended. Never rejects. */
+  readonly done: Promise<void>;
+}
+
 /** The client surface the k8s lexicon consumes. */
 export interface K8sClient {
   /** Where this client is pointed and what authorized it. */
@@ -254,6 +306,19 @@ export interface K8sClient {
   readIfPresent(ref: ObjectRef, options?: ReadOptions): Promise<K8sObject | undefined>;
   /** LIST a kind, optionally namespaced and label-filtered. Follows `continue` tokens. */
   list(selector: ResourceSelector, options?: ListOptions): Promise<K8sObject[]>;
+  /**
+   * WATCH a kind: a long-lived `GET ...?watch=1&resourceVersion=<rv>` whose
+   * NDJSON frames arrive at `options.onEvent` until somebody closes it (chant
+   * #1981).
+   *
+   * The `resourceVersion` comes from a LIST issued first, which is the only
+   * way to start a watch without a gap. A `410 Gone`, the server saying that
+   * version has aged out of its change history, re-LISTs and resumes from the
+   * new version rather than retrying the stale one; a stream the server closes
+   * cleanly is reopened from the last version seen. Anything else ends the
+   * watch through `options.onError`.
+   */
+  watch(selector: ResourceSelector, options?: WatchOptions): Promise<WatchHandle>;
   /**
    * GET a Pod's `/log` subresource — plain text, not JSON, which is why this
    * is its own method rather than a `read` variant. A snapshot only: the
@@ -706,6 +771,172 @@ export async function createK8sClient(options: K8sClientOptions = {}): Promise<K
     return items;
   }
 
+  /**
+   * Open the watch stream itself: the same request-building, auth and
+   * transport path every other call takes, stopping short of reading the body
+   * to completion. `send` cannot be reused because its last act is
+   * `body.text()`, which for a watch is a promise that resolves when the
+   * cluster hangs up.
+   */
+  async function openStream(
+    path: string,
+    query: Record<string, string>,
+    signal: AbortSignal,
+    target: string,
+  ): Promise<{ status: number; lines: AsyncIterable<string> }> {
+    const ctx = configuration.baseServer.makeRequestContext(path, "GET" as k8s.HttpMethod);
+    ctx.setHeaderParam("Accept", "application/json");
+    for (const [key, value] of Object.entries(query)) ctx.setQueryParam(key, value);
+    ctx.setSignal(signal);
+    await kc.applySecurityAuthentication(ctx);
+
+    let response: ResponseContextLike;
+    try {
+      response = (await configuration.httpApi.send(ctx).toPromise()) as unknown as ResponseContextLike;
+    } catch (err) {
+      throw noted(
+        new K8sTransportError(err instanceof Error ? err.message : String(err), target, { cause: err }),
+      );
+    }
+
+    if (response.httpStatusCode < 200 || response.httpStatusCode > 299) {
+      throw noted(K8sApiError.fromResponse(response.httpStatusCode, await response.body.text(), target));
+    }
+
+    // A transport with no streaming seam answered the whole body at once,
+    // which a fake NDJSON fixture does, and a live watch never can.
+    const raw = response.body.stream?.();
+    if (raw === undefined || raw === null) {
+      const text = await response.body.text();
+      return { status: response.httpStatusCode, lines: (async function* () { yield* text.split("\n"); })() };
+    }
+    return { status: response.httpStatusCode, lines: streamLines(raw) };
+  }
+
+  async function watch(selector: ResourceSelector, opts: WatchOptions = {}): Promise<WatchHandle> {
+    const info = await resolveOrThrow(selector, opts.signal);
+    const target = `watch ${selectorText(selector)}`;
+    const reopenDelayMs = opts.reopenDelayMs ?? 1_000;
+    // Own controller so `close()` works whether or not the caller passed a
+    // signal, and so aborting the watch never touches the caller's.
+    const controller = new AbortController();
+    const stopOnCallerAbort = () => controller.abort();
+    if (opts.signal) {
+      if (opts.signal.aborted) controller.abort();
+      else opts.signal.addEventListener("abort", stopOnCallerAbort, { once: true });
+    }
+
+    const listPath = opts.namespace
+      ? objectPath(info, undefined, opts.namespace)
+      : `${apiVersionPath(info.apiVersion)}/${info.name}`;
+    const listQuery: Record<string, string> = {};
+    if (opts.labelSelector) listQuery.labelSelector = opts.labelSelector;
+
+    /** The list's own `resourceVersion`, where a watch with no gap starts. */
+    async function listResourceVersion(): Promise<string | undefined> {
+      const page = await sendJson<{ metadata?: { resourceVersion?: string } }>(listPath, "GET", {
+        signal: controller.signal,
+        // `limit=1` because nothing here wants the objects: the list exists
+        // for the `resourceVersion` in its metadata, which every page carries.
+        query: { ...listQuery, limit: "1" },
+        target: `${target} (initial list)`,
+      });
+      return page.metadata?.resourceVersion;
+    }
+
+    let ended = false;
+    const end = (message?: string) => {
+      if (ended) return;
+      ended = true;
+      if (message !== undefined) opts.onError?.(message);
+    };
+
+    const done = (async () => {
+      try {
+        let resourceVersion = await listResourceVersion();
+        while (!controller.signal.aborted) {
+          const query: Record<string, string> = {
+            ...listQuery,
+            watch: "1",
+            // Bookmarks are how a quiet watch keeps its resourceVersion fresh
+            // without any object changing, which is what keeps a reconnect
+            // from re-listing. A cluster that does not support them ignores it.
+            allowWatchBookmarks: "true",
+          };
+          if (resourceVersion) query.resourceVersion = resourceVersion;
+
+          const { lines } = await openStream(listPath, query, controller.signal, target);
+          let expired = false;
+          // Read the stream one line at a time, racing each read against the
+          // abort. `for await` would not do: a watch that is quiet is parked
+          // inside `next()` with nothing to wake it, so a `close()` that
+          // waited for the loop to notice would wait for the next event on a
+          // cluster that may never send one.
+          const iterator = lines[Symbol.asyncIterator]();
+          const stopped = new Promise<{ done: true; value: undefined }>((resolve) => {
+            const finish = () => resolve({ done: true, value: undefined });
+            if (controller.signal.aborted) finish();
+            else controller.signal.addEventListener("abort", finish, { once: true });
+          });
+          for (;;) {
+            const next = await Promise.race([iterator.next(), stopped]);
+            if (next.done || controller.signal.aborted) break;
+            // `lines` already yields whole lines, so every call here consumes
+            // its input completely and the carry comes back empty.
+            const { frames } = parseWatchFrames(`${next.value}\n`);
+            for (const frame of frames) {
+              if (isExpiredFrame(frame)) {
+                // The one failure a watch is expected to hit. Re-list, never
+                // retry the stale version. See ./watch.ts.
+                expired = true;
+                break;
+              }
+              const rv = resourceVersionOf(frame);
+              if (rv) resourceVersion = rv;
+              if (frame.type !== "ERROR") opts.onEvent?.(frame);
+            }
+            if (expired) break;
+          }
+          // Not awaited: a generator parked on a read that will never complete
+          // would make this the very wait the race above exists to avoid. The
+          // underlying connection is closed by the abort, not by this.
+          void iterator.return?.(undefined)?.catch?.(() => {});
+          if (controller.signal.aborted) break;
+
+          if (expired) {
+            resourceVersion = await listResourceVersion();
+            continue;
+          }
+          // The server closed the stream cleanly, which it does every few
+          // minutes by design. Reopen from where we left off, after a real
+          // timer even at zero delay: a server that closes instantly would
+          // otherwise spin this loop through microtasks alone and starve
+          // every timer in the process, the abort's included.
+          await new Promise((resolve) => {
+            const timer = setTimeout(resolve, reopenDelayMs);
+            controller.signal.addEventListener("abort", () => { clearTimeout(timer); resolve(undefined); }, { once: true });
+          });
+        }
+        end();
+      } catch (err) {
+        // An aborted watch is a closed watch, never a failure to report.
+        if (controller.signal.aborted) return end();
+        end(err instanceof Error ? err.message : String(err));
+      } finally {
+        opts.signal?.removeEventListener("abort", stopOnCallerAbort);
+      }
+    })();
+
+    return {
+      done,
+      async close() {
+        controller.abort();
+        ended = true;
+        await done;
+      },
+    };
+  }
+
   async function apply(object: K8sObject, opts: ApplyOptions = {}): Promise<K8sObject> {
     const apiVersion = object.apiVersion;
     const kind = object.kind;
@@ -837,6 +1068,7 @@ export async function createK8sClient(options: K8sClientOptions = {}): Promise<K
     readIfPresent,
     list,
     readLog,
+    watch,
     apply,
     delete: remove,
     concurrently: (items, fn) => mapConcurrent(items, fn, concurrency),

package/src/index.ts

@@ -23,7 +23,16 @@ export {
   selectorText,
   refText,
 } from "./client";
-export type { K8sClient, ReadOptions, ApplyOptions, DeleteOptions, ListOptions, ReadLogOptions, SelfSubjectInfo } from "./client";
+export type {
+  K8sClient, ReadOptions, ApplyOptions, DeleteOptions, ListOptions, ReadLogOptions,
+  SelfSubjectInfo, WatchOptions, WatchHandle,
+} from "./client";
+
+// The watch (chant #1981): frame decoding, the `410 Gone` rule, and the
+// stream-to-lines adapter. The client owns the connection; these are the
+// pieces a consumer or a test may need to name.
+export { parseWatchFrames, isExpiredFrame, resourceVersionOf, streamLines } from "./watch";
+export type { WatchFrame, WatchEventType } from "./watch";
 
 export {
   K8sApiError,

package/src/testing.ts

@@ -32,6 +32,13 @@ export interface FakeResponse {
   status?: number;
   body?: unknown;
   headers?: Record<string, string>;
+  /**
+   * A streaming body, for a watch (chant #1981). Anything async-iterable will
+   * do, and {@link fakeWatchStream} is the usual source. Set it and the response
+   * exposes `body.stream()`, which is what the client reads instead of
+   * `text()` for a request it never expects to complete.
+   */
+  stream?: AsyncIterable<string | Uint8Array>;
 }
 
 export type FakeRequestHandler = (request: RecordedRequest) => FakeResponse | Promise<FakeResponse>;
@@ -74,7 +81,10 @@ export function fakeRequestLayer(handler: FakeRequestHandler): FakeRequestLayer
       return {
         httpStatusCode: status,
         headers: { "content-type": "application/json", ...(result.headers ?? {}) },
-        body: { text: async () => body },
+        body: {
+          text: async () => body,
+          ...(result.stream ? { stream: () => result.stream } : {}),
+        },
       };
     },
   };
@@ -186,3 +196,77 @@ export function apiResourceList(
     })),
   };
 }
+
+/** A watch stream a test drives by hand. */
+export interface FakeWatchStream extends AsyncIterable<string> {
+  /**
+   * Send one NDJSON frame down the stream. Objects are stringified; a string
+   * is sent verbatim, which is how a test produces a malformed or half-written
+   * frame. A newline is appended unless the string already ends in one.
+   */
+  push(frame: unknown): void;
+  /** End the stream, as a server closing the connection does. */
+  close(): void;
+  /** How many frames have been consumed by the reader. */
+  readonly delivered: number;
+}
+
+/**
+ * A controllable NDJSON stream for driving {@link import("./client").K8sClient.watch}
+ * against the fake cluster (chant #1981).
+ *
+ * The client reads it exactly as it reads a live watch: one frame per line,
+ * for as long as the connection stays open. So a test can push an ADDED, an
+ * expired-`410` ERROR, or nothing at all, and assert on what the client does
+ * about it, without a cluster, a socket, or a timer.
+ */
+export function fakeWatchStream(): FakeWatchStream {
+  const queued: string[] = [];
+  let waiting: (() => void) | undefined;
+  let closed = false;
+  let delivered = 0;
+
+  const wake = () => {
+    const resume = waiting;
+    waiting = undefined;
+    resume?.();
+  };
+
+  return {
+    get delivered() {
+      return delivered;
+    },
+    push(frame: unknown) {
+      if (closed) return;
+      const text = typeof frame === "string" ? frame : JSON.stringify(frame);
+      queued.push(text.endsWith("\n") ? text : `${text}\n`);
+      wake();
+    },
+    close() {
+      closed = true;
+      wake();
+    },
+    async *[Symbol.asyncIterator]() {
+      for (;;) {
+        while (queued.length > 0) {
+          delivered++;
+          yield queued.shift()!;
+        }
+        if (closed) return;
+        await new Promise<void>((resolve) => {
+          waiting = resolve;
+        });
+      }
+    },
+  };
+}
+
+/** A watch event frame, the shape the API server sends. */
+export function watchFrame(type: string, object: Record<string, unknown>): Record<string, unknown> {
+  return { type, object };
+}
+
+/** The `410 Gone` frame a watch gets when its resourceVersion has aged out. */
+export function expiredWatchFrame(message = "too old resource version: 1 (5000)"): Record<string, unknown> {
+  return watchFrame("ERROR", statusBody(410, "Expired", message));
+}

package/src/types.ts

@@ -182,5 +182,25 @@ export interface RequestContextLike {
 export interface ResponseContextLike {
   httpStatusCode: number;
   headers: Record<string, string>;
-  body: { text(): Promise<string> };
+  body: {
+    text(): Promise<string>;
+    /**
+     * The body as it arrives, rather than once it is complete (chant #1981).
+     *
+     * `text()` reads a response to completion, which is the right shape for
+     * every request this client makes except one: a watch never completes, so
+     * a watch read through `text()` is a promise that resolves when the
+     * cluster hangs up and never before. client-node's own HTTP library
+     * already exposes `stream()` (its `undici` `fetch` response's web
+     * `ReadableStream`), so the seam widens rather than being invented.
+     *
+     * Typed `unknown` for the same reason the rest of this file avoids the
+     * library's classes: the decoder (`./watch.ts`'s `streamLines`) accepts a
+     * web `ReadableStream`, a Node `Readable`, or any async iterable. Optional
+     * because a transport without it is still a valid transport: the watch
+     * falls back to `text()`, which is exactly what a fake returning a
+     * complete NDJSON body wants.
+     */
+    stream?(): unknown;
+  };
 }

package/src/watch.test.ts

@@ -0,0 +1,366 @@
+/**
+ * The watch (chant #1981): frame decoding on its own, then the whole watch
+ * driven against the fake cluster, on the same request layer every other client
+ * test uses, so kubeconfig parsing, discovery, auth and URL construction all
+ * run for real and only the socket is fake. No cluster, no k3d, no timer past
+ * a few milliseconds.
+ */
+
+import { describe, test, expect } from "vitest";
+import { createK8sClient } from "./client";
+import { isExpiredFrame, parseWatchFrames, resourceVersionOf, streamLines } from "./watch";
+import {
+  apiResourceList,
+  expiredWatchFrame,
+  fakeKubeconfig,
+  fakeRequestLayer,
+  fakeWatchStream,
+  statusBody,
+  watchFrame,
+} from "./testing";
+import type { RecordedRequest } from "./testing";
+
+const CORE_V1 = apiResourceList("v1", [
+  { name: "configmaps", kind: "ConfigMap" },
+  { name: "namespaces", kind: "Namespace", namespaced: false },
+]);
+const APPS_V1 = apiResourceList("apps/v1", [{ name: "deployments", kind: "Deployment" }]);
+
+const DISCOVERY: Record<string, unknown> = {
+  "/api": { kind: "APIVersions", versions: ["v1"] },
+  "/apis": {
+    kind: "APIGroupList",
+    groups: [{ name: "apps", preferredVersion: { groupVersion: "apps/v1", version: "v1" }, versions: [{ groupVersion: "apps/v1" }] }],
+  },
+  "/api/v1": CORE_V1,
+  "/apis/apps/v1": APPS_V1,
+};
+
+function deployment(name: string, resourceVersion: string): Record<string, unknown> {
+  return {
+    apiVersion: "apps/v1",
+    kind: "Deployment",
+    metadata: { name, namespace: "prod", resourceVersion },
+  };
+}
+
+/** Wait for `predicate`, or give up. Never a bare sleep. */
+async function waitFor(predicate: () => boolean, maxWaitMs = 3_000): Promise<void> {
+  const deadline = Date.now() + maxWaitMs;
+  while (!predicate() && Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, 5));
+  }
+}
+
+/**
+ * A fake cluster that answers discovery, one LIST per call (with an
+ * incrementing `resourceVersion`), and hands each watch request the next
+ * stream the test queued.
+ */
+function watchableCluster(streams: Array<ReturnType<typeof fakeWatchStream>>) {
+  const state = { lists: 0, watches: [] as RecordedRequest[] };
+  const layer = fakeRequestLayer((req) => {
+    if (req.path in DISCOVERY) return { body: DISCOVERY[req.path] };
+    if (req.query.watch === "1") {
+      state.watches.push(req);
+      const stream = streams.shift();
+      if (!stream) return { status: 500, body: statusBody(500, "InternalError", "no stream queued") };
+      return { stream };
+    }
+    if (req.path.endsWith("/deployments") || req.path.endsWith("/configmaps")) {
+      state.lists++;
+      return { body: { kind: "List", metadata: { resourceVersion: `rv-${state.lists}` }, items: [] } };
+    }
+    return { status: 404, body: statusBody(404, "NotFound", `${req.path} not found`) };
+  });
+  return { layer, state };
+}
+
+async function watchingClient(layer: ReturnType<typeof fakeRequestLayer>) {
+  return createK8sClient({ kubeconfig: fakeKubeconfig(), requestLayer: layer });
+}
+
+describe("parseWatchFrames", () => {
+  test("decodes whole NDJSON lines and carries the partial one over", () => {
+    const first = parseWatchFrames('{"type":"ADDED","object":{"kind":"Pod"}}\n{"type":"MODI');
+    expect(first.frames).toHaveLength(1);
+    expect(first.frames[0].type).toBe("ADDED");
+    expect(first.carry).toBe('{"type":"MODI');
+
+    const second = parseWatchFrames('FIED","object":{"kind":"Pod"}}\n', first.carry);
+    expect(second.frames).toHaveLength(1);
+    expect(second.frames[0].type).toBe("MODIFIED");
+    expect(second.carry).toBe("");
+  });
+
+  test("drops a line that is not JSON, or JSON without a known type, and keeps going", () => {
+    const { frames } = parseWatchFrames(
+      ['not json at all', '{"type":"WAT","object":{}}', '{"nope":1}', '{"type":"DELETED","object":{}}', ""].join("\n"),
+    );
+    expect(frames.map((f) => f.type)).toEqual(["DELETED"]);
+  });
+
+  test("a frame with no object still decodes, rather than throwing", () => {
+    const { frames } = parseWatchFrames('{"type":"BOOKMARK"}\n');
+    expect(frames).toEqual([{ type: "BOOKMARK", object: {} }]);
+  });
+});
+
+describe("isExpiredFrame / resourceVersionOf", () => {
+  test("410 by code, and by reason for a cluster that sends only one", () => {
+    expect(isExpiredFrame({ type: "ERROR", object: statusBody(410, "Expired", "too old") })).toBe(true);
+    expect(isExpiredFrame({ type: "ERROR", object: { reason: "Gone" } })).toBe(true);
+    expect(isExpiredFrame({ type: "ERROR", object: statusBody(500, "InternalError", "boom") })).toBe(false);
+    // An ordinary event is never the expiry signal, whatever it carries.
+    expect(isExpiredFrame({ type: "MODIFIED", object: { code: 410 } as never })).toBe(false);
+  });
+
+  test("reads the resumable resourceVersion, and nothing when there is none", () => {
+    expect(resourceVersionOf({ type: "ADDED", object: deployment("api", "77") })).toBe("77");
+    expect(resourceVersionOf({ type: "ADDED", object: { metadata: {} } })).toBeUndefined();
+  });
+});
+
+describe("streamLines", () => {
+  test("reassembles lines split across chunks, from bytes or strings", async () => {
+    const encoder = new TextEncoder();
+    const chunks = [encoder.encode('{"a":'), encoder.encode("1}\n{\"b\":2}\n"), "tail-without-newline"];
+    const source = (async function* () {
+      yield* chunks;
+    })();
+    const lines: string[] = [];
+    for await (const line of streamLines(source)) lines.push(line);
+    expect(lines).toEqual(['{"a":1}', '{"b":2}', "tail-without-newline"]);
+  });
+
+  test("a web ReadableStream reads the same way", async () => {
+    const encoder = new TextEncoder();
+    const stream = new ReadableStream<Uint8Array>({
+      start(controller) {
+        controller.enqueue(encoder.encode("one\ntw"));
+        controller.enqueue(encoder.encode("o\n"));
+        controller.close();
+      },
+    });
+    const lines: string[] = [];
+    for await (const line of streamLines(stream)) lines.push(line);
+    expect(lines).toEqual(["one", "two"]);
+  });
+
+  test("no stream at all yields nothing rather than throwing", async () => {
+    const lines: string[] = [];
+    for await (const line of streamLines(undefined)) lines.push(line);
+    expect(lines).toEqual([]);
+  });
+});
+
+describe("K8sClient.watch, against the fake cluster", () => {
+  test("LISTs first for a resourceVersion, then opens the watch from it", async () => {
+    const stream = fakeWatchStream();
+    const { layer, state } = watchableCluster([stream]);
+    const c = await watchingClient(layer);
+
+    const seen: string[] = [];
+    const handle = await c.watch(
+      { apiVersion: "apps/v1", kind: "Deployment" },
+      { namespace: "prod", onEvent: (f) => seen.push(f.type) },
+    );
+
+    await waitFor(() => state.watches.length > 0);
+    const request = state.watches[0];
+    expect(request.path).toBe("/apis/apps/v1/namespaces/prod/deployments");
+    expect(request.query.watch).toBe("1");
+    expect(request.query.resourceVersion).toBe("rv-1");
+    expect(request.query.allowWatchBookmarks).toBe("true");
+    // The auth path ran for real, above the seam.
+    expect(request.headers.Authorization).toBe("Bearer test-token");
+
+    stream.push(watchFrame("ADDED", deployment("api", "43")));
+    stream.push(watchFrame("MODIFIED", deployment("api", "44")));
+    await waitFor(() => seen.length >= 2);
+    expect(seen).toEqual(["ADDED", "MODIFIED"]);
+
+    await handle.close();
+  });
+
+  test("no namespace watches across all of them, and a label selector rides along", async () => {
+    const stream = fakeWatchStream();
+    const { layer, state } = watchableCluster([stream]);
+    const c = await watchingClient(layer);
+    const handle = await c.watch(
+      { apiVersion: "apps/v1", kind: "Deployment" },
+      { labelSelector: "app.kubernetes.io/managed-by=chant" },
+    );
+    await waitFor(() => state.watches.length > 0);
+    expect(state.watches[0].path).toBe("/apis/apps/v1/deployments");
+    expect(state.watches[0].query.labelSelector).toBe("app.kubernetes.io/managed-by=chant");
+    await handle.close();
+  });
+
+  test("a 410 Gone re-LISTs and resumes from the new resourceVersion, never retrying the stale one", async () => {
+    const first = fakeWatchStream();
+    const second = fakeWatchStream();
+    const { layer, state } = watchableCluster([first, second]);
+    const c = await watchingClient(layer);
+
+    const seen: string[] = [];
+    const errors: string[] = [];
+    const handle = await c.watch(
+      { apiVersion: "apps/v1", kind: "Deployment" },
+      { namespace: "prod", reopenDelayMs: 0, onEvent: (f) => seen.push(f.type), onError: (m) => errors.push(m) },
+    );
+
+    await waitFor(() => state.watches.length >= 1);
+    first.push(expiredWatchFrame());
+
+    await waitFor(() => state.watches.length >= 2);
+    expect(state.watches[1].query.resourceVersion).toBe("rv-2"); // a fresh list, not "rv-1"
+    expect(state.lists).toBe(2);
+
+    // And the watch is still live: the expiry was a re-list, not an ending.
+    second.push(watchFrame("ADDED", deployment("api", "99")));
+    await waitFor(() => seen.length >= 1);
+    expect(seen).toEqual(["ADDED"]);
+    expect(errors).toEqual([]);
+
+    await handle.close();
+  });
+
+  test("a stream the server closes cleanly is reopened from the last version seen", async () => {
+    const first = fakeWatchStream();
+    const second = fakeWatchStream();
+    const { layer, state } = watchableCluster([first, second]);
+    const c = await watchingClient(layer);
+
+    const errors: string[] = [];
+    const handle = await c.watch(
+      { apiVersion: "apps/v1", kind: "Deployment" },
+      { namespace: "prod", reopenDelayMs: 0, onError: (m) => errors.push(m) },
+    );
+
+    await waitFor(() => state.watches.length >= 1);
+    first.push(watchFrame("MODIFIED", deployment("api", "555")));
+    await waitFor(() => first.delivered >= 1);
+    first.close();
+
+    await waitFor(() => state.watches.length >= 2);
+    // Resumed from the frame, without paying for another LIST.
+    expect(state.watches[1].query.resourceVersion).toBe("555");
+    expect(state.lists).toBe(1);
+    expect(errors).toEqual([]);
+
+    await handle.close();
+  });
+
+  test("a watch that cannot be opened reports once through onError and ends, never throwing into the caller", async () => {
+    const layer = fakeRequestLayer((req) => {
+      if (req.path in DISCOVERY) return { body: DISCOVERY[req.path] };
+      if (req.query.watch === "1") return { status: 403, body: statusBody(403, "Forbidden", "watch denied") };
+      return { body: { kind: "List", metadata: { resourceVersion: "rv-1" }, items: [] } };
+    });
+    const c = await watchingClient(layer);
+
+    const errors: string[] = [];
+    const handle = await c.watch(
+      { apiVersion: "apps/v1", kind: "Deployment" },
+      { namespace: "prod", onError: (m) => errors.push(m) },
+    );
+
+    await handle.done;
+    expect(errors).toHaveLength(1);
+    expect(errors[0]).toContain("watch denied");
+    await handle.close(); // idempotent
+    expect(errors).toHaveLength(1);
+  });
+
+  test("close() stops the watch, reports nothing, and is safe to call twice", async () => {
+    const stream = fakeWatchStream();
+    const { layer, state } = watchableCluster([stream]);
+    const c = await watchingClient(layer);
+
+    const errors: string[] = [];
+    const handle = await c.watch(
+      { apiVersion: "apps/v1", kind: "Deployment" },
+      { namespace: "prod", reopenDelayMs: 0, onError: (m) => errors.push(m) },
+    );
+    await waitFor(() => state.watches.length >= 1);
+
+    await handle.close();
+    await handle.close();
+    await handle.done;
+    // A closed watch is not a failed watch.
+    expect(errors).toEqual([]);
+
+    // And nothing reopens after the close.
+    const watchesAtClose = state.watches.length;
+    stream.close();
+    await new Promise((r) => setTimeout(r, 50));
+    expect(state.watches.length).toBe(watchesAtClose);
+  });
+
+  test("an aborted caller signal closes the watch without reporting a failure", async () => {
+    const stream = fakeWatchStream();
+    const { layer, state } = watchableCluster([stream]);
+    const c = await watchingClient(layer);
+    const controller = new AbortController();
+
+    const errors: string[] = [];
+    const handle = await c.watch(
+      { apiVersion: "apps/v1", kind: "Deployment" },
+      { namespace: "prod", reopenDelayMs: 0, signal: controller.signal, onError: (m) => errors.push(m) },
+    );
+    await waitFor(() => state.watches.length >= 1);
+
+    controller.abort();
+    await handle.done;
+    expect(errors).toEqual([]);
+  });
+
+  test("a kind the cluster's discovery does not serve refuses by name, before any stream", async () => {
+    const { layer } = watchableCluster([]);
+    const c = await watchingClient(layer);
+    await expect(c.watch({ apiVersion: "ray.io/v1", kind: "RayCluster" })).rejects.toThrow(/ray.io\/v1 RayCluster/);
+  });
+
+  test("a cluster-scoped kind watches without a namespace segment", async () => {
+    const stream = fakeWatchStream();
+    const layer = fakeRequestLayer((req) => {
+      if (req.path in DISCOVERY) return { body: DISCOVERY[req.path] };
+      if (req.query.watch === "1") return { stream };
+      return { body: { kind: "List", metadata: { resourceVersion: "rv-1" }, items: [] } };
+    });
+    const c = await watchingClient(layer);
+    const handle = await c.watch({ apiVersion: "v1", kind: "Namespace" }, { namespace: "ignored" });
+    await waitFor(() => layer.requests.some((r) => r.query.watch === "1"));
+    expect(layer.requests.find((r) => r.query.watch === "1")!.path).toBe("/api/v1/namespaces");
+    await handle.close();
+  });
+
+  test("a transport with no streaming seam falls back to the complete body", async () => {
+    // What a fixture returning a canned NDJSON document looks like: no
+    // `stream`, just text. The watch reads it as frames and then ends the
+    // stream, exactly as a server closing the connection would.
+    const ndjson =
+      [JSON.stringify(watchFrame("ADDED", deployment("api", "43"))), JSON.stringify(watchFrame("DELETED", deployment("api", "44")))].join("\n") + "\n";
+    const held = fakeWatchStream(); // keeps the reopened watch open, as a server does
+    let watches = 0;
+    const layer = fakeRequestLayer((req) => {
+      if (req.path in DISCOVERY) return { body: DISCOVERY[req.path] };
+      if (req.query.watch === "1") {
+        watches++;
+        return watches === 1 ? { body: ndjson } : { stream: held };
+      }
+      return { body: { kind: "List", metadata: { resourceVersion: "rv-1" }, items: [] } };
+    });
+    const c = await watchingClient(layer);
+
+    const seen: string[] = [];
+    const handle = await c.watch(
+      { apiVersion: "apps/v1", kind: "Deployment" },
+      { namespace: "prod", reopenDelayMs: 0, onEvent: (f) => seen.push(f.type) },
+    );
+    await waitFor(() => seen.length >= 2);
+    expect(seen).toEqual(["ADDED", "DELETED"]);
+    await handle.close();
+  });
+});

package/src/watch.ts

@@ -0,0 +1,157 @@
+/**
+ * The Kubernetes watch, as much of it as can be written without a client
+ * (chant #1981).
+ *
+ * A watch is `GET <list path>?watch=1&resourceVersion=<rv>` answered with an
+ * open connection that emits one JSON document per line. NDJSON, forever,
+ * until somebody hangs up. Everything here is the frame side of that: parsing
+ * lines out of a byte stream, reading a frame's `resourceVersion`, and
+ * recognising the one failure a watch is expected to hit.
+ *
+ * ## `410 Gone`
+ *
+ * The API server keeps a bounded history of changes. A watch resuming from a
+ * `resourceVersion` older than that window cannot be told what it missed, and
+ * says so: an `ERROR` frame carrying a `Status` with `code: 410` / `reason:
+ * Expired`. There is exactly one correct response, and it is not to retry with
+ * the same `resourceVersion`. It is to LIST again, take the list's own
+ * `resourceVersion`, and watch from there. Anything else silently drops
+ * whatever happened during the gap.
+ *
+ * For chant's purposes the gap costs nothing anyway: the events are a trigger,
+ * never a fact, and the tick they wake re-observes the estate from scratch. A
+ * re-list is a re-list, not a reconciliation.
+ */
+
+import type { K8sObject } from "./types";
+
+/** The event types the watch API emits. `BOOKMARK` requires `allowWatchBookmarks`. */
+export type WatchEventType = "ADDED" | "MODIFIED" | "DELETED" | "BOOKMARK" | "ERROR";
+
+/**
+ * One decoded NDJSON frame. `object` is whatever the server put in the frame:
+ * the changed resource for the four ordinary types, a `Status` for `ERROR`.
+ */
+export interface WatchFrame {
+  type: WatchEventType;
+  object: K8sObject;
+}
+
+const EVENT_TYPES = new Set<string>(["ADDED", "MODIFIED", "DELETED", "BOOKMARK", "ERROR"]);
+
+/**
+ * Split a chunk of a watch stream into whole frames, carrying the trailing
+ * partial line over to the next call.
+ *
+ * Frames arrive split across TCP reads at arbitrary byte offsets, so a decoder
+ * that treats each chunk as a set of complete lines drops or corrupts every
+ * frame that straddles a boundary. `carry` is the fix and the reason this is a
+ * function rather than three lines inline.
+ *
+ * A line that is not JSON, or is JSON without a known `type`, is dropped
+ * rather than thrown: a watch is a trigger channel, and the correct response
+ * to a frame nobody can read is to keep watching.
+ */
+export function parseWatchFrames(
+  chunk: string,
+  carry = "",
+): { frames: WatchFrame[]; carry: string } {
+  const combined = carry + chunk;
+  const lines = combined.split("\n");
+  // The last element is either "" (the chunk ended on a newline) or a partial
+  // line still waiting for its remainder.
+  const rest = lines.pop() ?? "";
+  const frames: WatchFrame[] = [];
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(trimmed);
+    } catch {
+      continue;
+    }
+    if (!parsed || typeof parsed !== "object") continue;
+    const { type, object } = parsed as { type?: unknown; object?: unknown };
+    if (typeof type !== "string" || !EVENT_TYPES.has(type)) continue;
+    frames.push({
+      type: type as WatchEventType,
+      object: (object && typeof object === "object" ? object : {}) as K8sObject,
+    });
+  }
+
+  return { frames, carry: rest };
+}
+
+/**
+ * Whether this frame is the API server saying the watch's `resourceVersion` has
+ * aged out of its history: the `410 Gone` that means re-list, not retry.
+ *
+ * Matched on `code` first and `reason` second, because both are set on the
+ * `Status` the server sends and a cluster that sets only one of them is still
+ * telling us the same thing.
+ */
+export function isExpiredFrame(frame: WatchFrame): boolean {
+  if (frame.type !== "ERROR") return false;
+  const status = frame.object as { code?: unknown; reason?: unknown };
+  if (status.code === 410) return true;
+  return status.reason === "Expired" || status.reason === "Gone";
+}
+
+/** The `resourceVersion` to resume from after this frame, when it carries one. */
+export function resourceVersionOf(frame: WatchFrame): string | undefined {
+  const rv = frame.object?.metadata?.resourceVersion;
+  return typeof rv === "string" && rv.length > 0 ? rv : undefined;
+}
+
+/**
+ * Decode whatever a response body's `stream()` returned into lines of text.
+ *
+ * Three shapes reach here and all three are real: a web `ReadableStream` (what
+ * `undici`'s `fetch` gives client-node's HTTP library, and so what a live
+ * cluster produces), a Node `Readable` or any other async iterable (what a
+ * hand-rolled transport gives), and `undefined` for a transport with no
+ * streaming seam at all, which is a fake that answered the whole body at once and
+ * is handled by the caller reading `text()` instead.
+ */
+export async function* streamLines(source: unknown): AsyncGenerator<string> {
+  const decoder = new TextDecoder();
+  let carry = "";
+
+  const emit = function* (chunk: string): Generator<string> {
+    const lines = (carry + chunk).split("\n");
+    carry = lines.pop() ?? "";
+    for (const line of lines) yield line;
+  };
+
+  const decode = (value: unknown): string =>
+    typeof value === "string" ? value : decoder.decode(value as Uint8Array, { stream: true });
+
+  if (source && typeof (source as { getReader?: unknown }).getReader === "function") {
+    const reader = (source as ReadableStream<Uint8Array>).getReader();
+    try {
+      for (;;) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        yield* emit(decode(value));
+      }
+    } finally {
+      // Releasing matters: an un-released reader keeps the connection's
+      // backpressure machinery alive after the watch is done with it.
+      try {
+        reader.releaseLock();
+      } catch {
+        // Already released, or the stream is gone. Either is fine.
+      }
+    }
+  } else if (source && typeof (source as AsyncIterable<unknown>)[Symbol.asyncIterator] === "function") {
+    for await (const value of source as AsyncIterable<unknown>) {
+      yield* emit(decode(value));
+    }
+  } else {
+    return;
+  }
+
+  if (carry.trim()) yield carry;
+}