kubernetes-fluent-client 1.9.0 → 2.0.0

package/dist/index.d.ts

@@ -4,10 +4,11 @@ import * as kind from "./upstream";
 export { kind };
 export { fetch } from "./fetch";
 export { StatusCodes as fetchStatus } from "http-status-codes";
+export { WatchCfg, WatchEvent } from "./fluent/watch";
 export { K8s } from "./fluent";
 export { RegisterKind, modelToGroupVersionKind } from "./kinds";
 export { GenericKind } from "./types";
 export * from "./types";
-export * as K8sClientNode from "@kubernetes/client-node";
-export { fromEnv } from "./helpers";
+export * as models from "@kubernetes/client-node/dist/gen/models/all";
+export { fromEnv, waitForCluster } from "./helpers";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,SAAS,CAAC;AAGjB,OAAO,KAAK,IAAI,MAAM,YAAY,CAAC;AAEnC,oGAAoG;AACpG,OAAO,EAAE,IAAI,EAAE,CAAC;AAGhB,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAGhC,OAAO,EAAE,WAAW,IAAI,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAG/D,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAG/B,OAAO,EAAE,YAAY,EAAE,uBAAuB,EAAE,MAAM,SAAS,CAAC;AAGhE,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAEtC,cAAc,SAAS,CAAC;AAExB,OAAO,KAAK,aAAa,MAAM,yBAAyB,CAAC;AAEzD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,SAAS,CAAC;AAGjB,OAAO,KAAK,IAAI,MAAM,YAAY,CAAC;AAEnC,oGAAoG;AACpG,OAAO,EAAE,IAAI,EAAE,CAAC;AAGhB,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAGhC,OAAO,EAAE,WAAW,IAAI,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAG/D,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAGtD,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAG/B,OAAO,EAAE,YAAY,EAAE,uBAAuB,EAAE,MAAM,SAAS,CAAC;AAGhE,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAEtC,cAAc,SAAS,CAAC;AAGxB,OAAO,KAAK,MAAM,MAAM,6CAA6C,CAAC;AAEtE,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC"}

package/dist/index.js

@@ -28,7 +28,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.fromEnv = exports.K8sClientNode = exports.GenericKind = exports.modelToGroupVersionKind = exports.RegisterKind = exports.K8s = exports.fetchStatus = exports.fetch = exports.kind = void 0;
+exports.waitForCluster = exports.fromEnv = exports.models = exports.GenericKind = exports.modelToGroupVersionKind = exports.RegisterKind = exports.K8s = exports.WatchEvent = exports.fetchStatus = exports.fetch = exports.kind = void 0;
 require("./patch");
 // Export kinds as a single object
 const kind = __importStar(require("./upstream"));
@@ -39,6 +39,9 @@ Object.defineProperty(exports, "fetch", { enumerable: true, get: function () { r
 // Export the HTTP status codes
 var http_status_codes_1 = require("http-status-codes");
 Object.defineProperty(exports, "fetchStatus", { enumerable: true, get: function () { return http_status_codes_1.StatusCodes; } });
+// Export the Watch Config and Event types
+var watch_1 = require("./fluent/watch");
+Object.defineProperty(exports, "WatchEvent", { enumerable: true, get: function () { return watch_1.WatchEvent; } });
 // Export the fluent API entrypoint
 var fluent_1 = require("./fluent");
 Object.defineProperty(exports, "K8s", { enumerable: true, get: function () { return fluent_1.K8s; } });
@@ -50,6 +53,8 @@ Object.defineProperty(exports, "modelToGroupVersionKind", { enumerable: true, ge
 var types_1 = require("./types");
 Object.defineProperty(exports, "GenericKind", { enumerable: true, get: function () { return types_1.GenericKind; } });
 __exportStar(require("./types"), exports);
-exports.K8sClientNode = __importStar(require("@kubernetes/client-node"));
+// Export the upstream raw models
+exports.models = __importStar(require("@kubernetes/client-node/dist/gen/models/all"));
 var helpers_1 = require("./helpers");
 Object.defineProperty(exports, "fromEnv", { enumerable: true, get: function () { return helpers_1.fromEnv; } });
+Object.defineProperty(exports, "waitForCluster", { enumerable: true, get: function () { return helpers_1.waitForCluster; } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kubernetes-fluent-client",
-  "version": "1.9.0",
+  "version": "2.0.0",
   "description": "A @kubernetes/client-node fluent API wrapper that leverages K8s Server Side Apply",
   "bin": "./dist/cli.js",
   "main": "dist/index.js",
@@ -35,13 +35,13 @@
   },
   "homepage": "https://github.com/defenseunicorns/kubernetes-fluent-client#readme",
   "dependencies": {
-    "@kubernetes/client-node": "1.0.0-rc3",
+    "@kubernetes/client-node": "1.0.0-rc4",
     "byline": "5.0.0",
     "fast-json-patch": "3.1.1",
     "http-status-codes": "2.3.0",
     "node-fetch": "2.7.0",
     "quicktype-core": "23.0.80",
-    "type-fest": "4.8.2",
+    "type-fest": "4.9.0",
     "yargs": "17.7.2"
   },
   "devDependencies": {
@@ -49,17 +49,17 @@
     "@commitlint/config-conventional": "18.4.3",
     "@jest/globals": "29.7.0",
     "@types/byline": "4.2.36",
-    "@types/readable-stream": "4.0.9",
+    "@types/readable-stream": "4.0.10",
     "@types/yargs": "17.0.32",
-    "@typescript-eslint/eslint-plugin": "6.13.1",
-    "@typescript-eslint/parser": "6.13.1",
-    "eslint-plugin-jsdoc": "46.9.0",
+    "@typescript-eslint/eslint-plugin": "6.15.0",
+    "@typescript-eslint/parser": "6.15.0",
+    "eslint-plugin-jsdoc": "46.9.1",
     "jest": "29.7.0",
     "nock": "13.4.0",
-    "prettier": "3.1.0",
-    "semantic-release": "22.0.8",
+    "prettier": "3.1.1",
+    "semantic-release": "22.0.12",
     "ts-jest": "29.1.1",
-    "typescript": "5.3.2"
+    "typescript": "5.3.3"
   },
   "release": {
     "branches": [

package/src/fluent/index.test.ts

@@ -1,12 +1,15 @@
 import { beforeEach, describe, expect, it, jest } from "@jest/globals";
+import { V1APIGroup } from "@kubernetes/client-node";
 import { Operation } from "fast-json-patch";
 
-import { Pod } from "../upstream";
 import { K8s } from ".";
-import { k8sExec } from "./utils";
+import { fetch } from "../fetch";
+import { Pod } from "../upstream";
+import { k8sCfg, k8sExec } from "./utils";
 
 // Setup mocks
 jest.mock("./utils");
+jest.mock("../fetch");
 
 const generateFakePodManagedFields = (manager: string) => {
   return [
@@ -52,6 +55,7 @@ describe("Kube", () => {
     },
   };
 
+  const mockedKubeCfg = jest.mocked(k8sCfg);
   const mockedKubeExec = jest.mocked(k8sExec).mockResolvedValue(fakeResource);
 
   beforeEach(() => {
@@ -194,4 +198,35 @@ describe("Kube", () => {
       expect.objectContaining({ status: 500 }),
     );
   });
+
+  it("should create a raw api request", async () => {
+    mockedKubeCfg.mockReturnValue(
+      new Promise(r =>
+        r({
+          serverUrl: "http://localhost:8080",
+          opts: {},
+        }),
+      ),
+    );
+    const mockResp = {
+      kind: "APIVersions",
+      versions: ["v1"],
+      serverAddressByClientCIDRs: [
+        {
+          serverAddress: "172.27.0.3:6443",
+        },
+      ],
+    };
+
+    jest.mocked(fetch).mockResolvedValue({
+      ok: true,
+      data: mockResp,
+      status: 200,
+      statusText: "OK",
+    });
+
+    const result = await K8s(V1APIGroup).Raw("/api");
+
+    expect(result).toEqual(mockResp);
+  });
 });

package/src/fluent/index.ts

@@ -6,12 +6,13 @@ import { Operation } from "fast-json-patch";
 import { StatusCodes } from "http-status-codes";
 import type { PartialDeep } from "type-fest";
 
+import { fetch } from "../fetch";
 import { modelToGroupVersionKind } from "../kinds";
 import { GenericClass } from "../types";
 import { ApplyCfg } from "./apply";
 import { Filters, K8sInit, Paths, WatchAction } from "./types";
-import { k8sExec } from "./utils";
-import { ExecWatch, WatchCfg } from "./watch";
+import { k8sCfg, k8sExec } from "./utils";
+import { WatchCfg, Watcher } from "./watch";
 
 /**
  * Kubernetes fluent API inspired by Kubectl. Pass in a model, then call filters and actions on it.
@@ -23,7 +24,7 @@ import { ExecWatch, WatchCfg } from "./watch";
 export function K8s<T extends GenericClass, K extends KubernetesObject = InstanceType<T>>(
   model: T,
   filters: Filters = {},
-): K8sInit<K> {
+): K8sInit<T, K> {
   const withFilters = { WithField, WithLabel, Get, Delete, Watch };
   const matchedKind = filters.kindOverride || modelToGroupVersionKind(model.name);
 
@@ -158,16 +159,32 @@ export function K8s<T extends GenericClass, K extends KubernetesObject = Instanc
       throw new Error("No operations specified");
     }
 
-    return k8sExec<T, K>(model, filters, "PATCH", payload);
+    return k8sExec(model, filters, "PATCH", payload);
   }
 
   /**
    * @inheritdoc
    * @see {@link K8sInit.Watch}
    */
-  async function Watch(callback: WatchAction<T>, watchCfg?: WatchCfg) {
-    return ExecWatch(model, filters, callback, watchCfg);
+  function Watch(callback: WatchAction<T>, watchCfg?: WatchCfg) {
+    return new Watcher(model, filters, callback, watchCfg);
   }
 
-  return { InNamespace, Apply, Create, Patch, ...withFilters };
+  /**
+   * @inheritdoc
+   * @see {@link K8sInit.Raw}
+   */
+  async function Raw(url: string) {
+    const thing = await k8sCfg("GET");
+    const { opts, serverUrl } = thing;
+    const resp = await fetch<K>(`${serverUrl}${url}`, opts);
+
+    if (resp.ok) {
+      return resp.data;
+    }
+
+    throw resp;
+  }
+
+  return { InNamespace, Apply, Create, Patch, Raw, ...withFilters };
 }

package/src/fluent/types.ts

@@ -6,8 +6,8 @@ import { Operation } from "fast-json-patch";
 import type { PartialDeep } from "type-fest";
 
 import { GenericClass, GroupVersionKind } from "../types";
-import { WatchCfg, WatchController } from "./watch";
 import { ApplyCfg } from "./apply";
+import { WatchCfg, Watcher } from "./watch";
 
 /**
  * The Phase matched when using the K8s Watch API.
@@ -16,6 +16,8 @@ export enum WatchPhase {
   Added = "ADDED",
   Modified = "MODIFIED",
   Deleted = "DELETED",
+  Bookmark = "BOOKMARK",
+  Error = "ERROR",
 }
 
 export type FetchMethods = "GET" | "APPLY" | "POST" | "PUT" | "DELETE" | "PATCH" | "WATCH";
@@ -41,7 +43,7 @@ export type GetFunction<K extends KubernetesObject> = {
   (name: string): Promise<K>;
 };
 
-export type K8sFilteredActions<K extends KubernetesObject> = {
+export type K8sFilteredActions<T extends GenericClass, K extends KubernetesObject> = {
   /**
    * Get the resource or resources matching the filters.
    * If no filters are specified, all resources will be returned.
@@ -63,10 +65,7 @@ export type K8sFilteredActions<K extends KubernetesObject> = {
    * @param watchCfg - (optional) watch configuration
    * @returns a watch controller
    */
-  Watch: (
-    callback: (payload: K, phase: WatchPhase) => void,
-    watchCfg?: WatchCfg,
-  ) => Promise<WatchController>;
+  Watch: (callback: WatchAction<T>, watchCfg?: WatchCfg) => Watcher<T>;
 };
 
 export type K8sUnfilteredActions<K extends KubernetesObject> = {
@@ -96,9 +95,31 @@ export type K8sUnfilteredActions<K extends KubernetesObject> = {
    * @returns The patched resource
    */
   Patch: (payload: Operation[]) => Promise<K>;
+
+  /**
+   * Perform a raw GET request to the Kubernetes API. This is useful for calling endpoints that are not supported by the fluent API.
+   * This command mirrors the `kubectl get --raw` command.
+   *
+   * E.g.
+   *
+   * ```ts
+   * import { V1APIGroup } from "@kubernetes/client-node";
+   *
+   * K8s(V1APIGroup).Raw("/api")
+   * ```
+   *
+   * will call the `/api` endpoint and is equivalent to `kubectl get --raw /api`.
+   *
+   * @param url the URL to call (e.g. /api)
+   * @returns
+   */
+  Raw: (url: string) => Promise<K>;
 };
 
-export type K8sWithFilters<K extends KubernetesObject> = K8sFilteredActions<K> & {
+export type K8sWithFilters<T extends GenericClass, K extends KubernetesObject> = K8sFilteredActions<
+  T,
+  K
+> & {
   /**
    * Filter the query by the given field.
    * Note multiple calls to this method will result in an AND condition. e.g.
@@ -118,7 +139,7 @@ export type K8sWithFilters<K extends KubernetesObject> = K8sFilteredActions<K> &
    * @param value - the field value
    * @returns the fluent API
    */
-  WithField: <P extends Paths<K>>(key: P, value: string) => K8sWithFilters<K>;
+  WithField: <P extends Paths<K>>(key: P, value: string) => K8sWithFilters<T, K>;
 
   /**
    * Filter the query by the given label. If no value is specified, the label simply must exist.
@@ -138,10 +159,10 @@ export type K8sWithFilters<K extends KubernetesObject> = K8sFilteredActions<K> &
    * @param value - the label value
    * @returns the fluent API
    */
-  WithLabel: (key: string, value?: string) => K8sWithFilters<K>;
+  WithLabel: (key: string, value?: string) => K8sWithFilters<T, K>;
 };
 
-export type K8sInit<K extends KubernetesObject> = K8sWithFilters<K> &
+export type K8sInit<T extends GenericClass, K extends KubernetesObject> = K8sWithFilters<T, K> &
   K8sUnfilteredActions<K> & {
     /**
      * Set the namespace filter.
@@ -149,7 +170,7 @@ export type K8sInit<K extends KubernetesObject> = K8sWithFilters<K> &
      * @param namespace - the namespace to filter on
      * @returns the fluent API
      */
-    InNamespace: (namespace: string) => K8sWithFilters<K>;
+    InNamespace: (namespace: string) => K8sWithFilters<T, K>;
   };
 
 export type WatchAction<T extends GenericClass, K extends KubernetesObject = InstanceType<T>> = (

package/src/fluent/watch.spec.ts

@@ -0,0 +1,264 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+import { afterEach, beforeEach, describe, expect, it, jest } from "@jest/globals";
+import nock from "nock";
+import { PassThrough } from "readable-stream";
+
+import { K8s } from ".";
+import { WatchEvent, kind } from "..";
+import { WatchPhase } from "./types";
+import { Watcher } from "./watch";
+
+describe("Watcher", () => {
+  const evtMock = jest.fn<(update: kind.Pod, phase: WatchPhase) => void>();
+  const errMock = jest.fn<(err: Error) => void>();
+
+  const setupAndStartWatcher = (eventType: WatchEvent, handler: (...args: any[]) => void) => {
+    watcher.events.on(eventType, handler);
+    watcher.start().catch(errMock);
+  };
+
+  let watcher: Watcher<typeof kind.Pod>;
+
+  beforeEach(() => {
+    jest.resetAllMocks();
+    watcher = K8s(kind.Pod).Watch(evtMock, {
+      retryDelaySec: 1,
+    });
+
+    nock("http://jest-test:8080")
+      .get("/api/v1/pods")
+      .query({ watch: "true", allowWatchBookmarks: "true" })
+      .reply(200, () => {
+        const stream = new PassThrough();
+
+        const resources = [
+          { type: "ADDED", object: createMockPod(`pod-0`, `1`) },
+          { type: "BOOKMARK", object: { metadata: { resourceVersion: "1" } } },
+          { type: "MODIFIED", object: createMockPod(`pod-0`, `2`) },
+        ];
+
+        resources.forEach(resource => {
+          stream.write(JSON.stringify(resource) + "\n");
+        });
+
+        stream.end();
+
+        return stream;
+      });
+  });
+
+  afterEach(() => {
+    watcher.close();
+  });
+
+  it("should watch named resources", done => {
+    nock.cleanAll();
+    nock("http://jest-test:8080")
+      .get("/api/v1/namespaces/tester/pods")
+      .query({ watch: "true", allowWatchBookmarks: "true", fieldSelector: "metadata.name=demo" })
+      .reply(200);
+
+    watcher = K8s(kind.Pod, { name: "demo" }).InNamespace("tester").Watch(evtMock);
+
+    setupAndStartWatcher(WatchEvent.CONNECT, () => {
+      done();
+    });
+  });
+
+  it("should start the watch at the specified resource version", done => {
+    nock.cleanAll();
+    nock("http://jest-test:8080")
+      .get("/api/v1/pods")
+      .query({
+        watch: "true",
+        allowWatchBookmarks: "true",
+        resourceVersion: "25",
+      })
+      .reply(200);
+
+    watcher = K8s(kind.Pod).Watch(evtMock, {
+      resourceVersion: "25",
+    });
+
+    setupAndStartWatcher(WatchEvent.CONNECT, () => {
+      done();
+    });
+  });
+
+  it("should handle resource version is too old", done => {
+    nock.cleanAll();
+    nock("http://jest-test:8080")
+      .get("/api/v1/pods")
+      .query({ watch: "true", allowWatchBookmarks: "true", resourceVersion: "45" })
+      .reply(200, () => {
+        const stream = new PassThrough();
+        stream.write(
+          JSON.stringify({
+            type: "ERROR",
+            object: {
+              kind: "Status",
+              apiVersion: "v1",
+              metadata: {},
+              status: "Failure",
+              message: "too old resource version: 123 (391079)",
+              reason: "Gone",
+              code: 410,
+            },
+          }) + "\n",
+        );
+
+        stream.end();
+        return stream;
+      });
+
+    watcher = K8s(kind.Pod).Watch(evtMock, {
+      resourceVersion: "45",
+    });
+
+    setupAndStartWatcher(WatchEvent.OLD_RESOURCE_VERSION, res => {
+      expect(res).toEqual("45");
+      done();
+    });
+  });
+
+  it("should call the event handler for each event", done => {
+    watcher = K8s(kind.Pod).Watch((evt, phase) => {
+      expect(evt.metadata?.name).toEqual(`pod-0`);
+      expect(phase).toEqual(WatchPhase.Added);
+      done();
+    });
+
+    watcher.start().catch(errMock);
+  });
+
+  it("should return the cache id", done => {
+    watcher
+      .start()
+      .then(() => {
+        expect(watcher.id).toEqual("d69b75a611");
+        done();
+      })
+      .catch(errMock);
+  });
+
+  it("should handle calling .id() before .start()", () => {
+    expect(() => watcher.id).toThrowError("watch not started");
+  });
+
+  it("should handle the CONNECT event", done => {
+    setupAndStartWatcher(WatchEvent.CONNECT, () => {
+      done();
+    });
+  });
+
+  it("should handle the DATA event", done => {
+    setupAndStartWatcher(WatchEvent.DATA, (pod, phase) => {
+      expect(pod.metadata?.name).toEqual(`pod-0`);
+      expect(phase).toEqual(WatchPhase.Added);
+      done();
+    });
+  });
+
+  it("should handle the BOOKMARK event", done => {
+    setupAndStartWatcher(WatchEvent.BOOKMARK, bookmark => {
+      expect(bookmark.metadata?.resourceVersion).toEqual("1");
+      done();
+    });
+  });
+
+  it("should handle the NETWORK_ERROR event", done => {
+    nock.cleanAll();
+    nock("http://jest-test:8080")
+      .get("/api/v1/pods")
+      .query({ watch: "true", allowWatchBookmarks: "true" })
+      .replyWithError("Something bad happened");
+
+    setupAndStartWatcher(WatchEvent.NETWORK_ERROR, error => {
+      expect(error.message).toEqual(
+        "request to http://jest-test:8080/api/v1/pods?watch=true&allowWatchBookmarks=true failed, reason: Something bad happened",
+      );
+      done();
+    });
+  });
+
+  it("should handle the RECONNECT event", done => {
+    nock.cleanAll();
+    nock("http://jest-test:8080")
+      .get("/api/v1/pods")
+      .query({ watch: "true", allowWatchBookmarks: "true" })
+      .replyWithError("Something bad happened");
+
+    setupAndStartWatcher(WatchEvent.RECONNECT, error => {
+      expect(error.message).toEqual(
+        "request to http://jest-test:8080/api/v1/pods?watch=true&allowWatchBookmarks=true failed, reason: Something bad happened",
+      );
+      done();
+    });
+  });
+
+  it("should perform a resync after the resync interval", done => {
+    watcher = K8s(kind.Pod).Watch(evtMock, {
+      resyncIntervalSec: 1,
+    });
+
+    setupAndStartWatcher(WatchEvent.RESYNC, err => {
+      expect(err.name).toEqual("Resync");
+      expect(err.message).toEqual("Resync triggered by resyncIntervalSec");
+      done();
+    });
+  });
+
+  it("should handle the GIVE_UP event", done => {
+    nock.cleanAll();
+    nock("http://jest-test:8080");
+
+    watcher = K8s(kind.Pod).Watch(evtMock, {
+      retryMax: 1,
+      retryDelaySec: 1,
+    });
+
+    setupAndStartWatcher(WatchEvent.GIVE_UP, error => {
+      expect(error.message).toContain(
+        "request to http://jest-test:8080/api/v1/pods?watch=true&allowWatchBookmarks=true failed",
+      );
+      done();
+    });
+  });
+});
+
+/**
+ * Creates a mock pod object
+ *
+ * @param name The name of the pod
+ * @param resourceVersion The resource version of the pod
+ * @returns A mock pod object
+ */
+function createMockPod(name: string, resourceVersion: string): kind.Pod {
+  return {
+    kind: "Pod",
+    apiVersion: "v1",
+    metadata: {
+      name: name,
+      resourceVersion: resourceVersion,
+      // ... other metadata fields
+    },
+    spec: {
+      containers: [
+        {
+          name: "nginx",
+          image: "nginx:1.14.2",
+          ports: [
+            {
+              containerPort: 80,
+              protocol: "TCP",
+            },
+          ],
+        },
+      ],
+    },
+    status: {
+      // ... pod status
+    },
+  };
+}