kubernetes-fluent-client 1.5.0 → 1.6.0

package/src/fluent/types.ts

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: Apache-2.0
-// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+// SPDX-FileCopyrightText: 2023-Present The Kubernetes Fluent Client Authors
 
 import { KubernetesListObject, KubernetesObject } from "@kubernetes/client-node";
 import { Operation } from "fast-json-patch";
@@ -28,6 +28,14 @@ export interface Filters {
   namespace?: string;
 }
 
+/**
+ * Get the resource or resources matching the filters.
+ * If no filters are specified, all resources will be returned.
+ * If a name is specified, only a single resource will be returned.
+ *
+ * @param name - (optional) the name of the resource to get
+ * @returns the resource or list of resources
+ */
 export type GetFunction<K extends KubernetesObject> = {
   (): Promise<KubernetesListObject<K>>;
   (name: string): Promise<K>;
@@ -42,16 +50,18 @@ export type K8sFilteredActions<K extends KubernetesObject> = {
   Get: GetFunction<K>;
 
   /**
-   * Delete the resource if it exists.
+   * Delete the resource matching the filters.
    *
    * @param filter - the resource or resource name to delete
    */
   Delete: (filter?: K | string) => Promise<void>;
 
   /**
+   * Watch the resource matching the filters.
    *
-   * @param callback
-   * @returns
+   * @param callback - the callback function to call when an event occurs
+   * @param watchCfg - (optional) watch configuration
+   * @returns a watch controller
    */
   Watch: (
     callback: (payload: K, phase: WatchPhase) => void,
@@ -63,16 +73,17 @@ export type K8sUnfilteredActions<K extends KubernetesObject> = {
   /**
    * Perform a server-side apply of the provided K8s resource.
    *
-   * @param resource
-   * @returns
+   * @param resource - the resource to apply
+   * @param applyCfg - (optional) apply configuration
+   * @returns the applied resource
    */
   Apply: (resource: PartialDeep<K>, applyCfg?: ApplyCfg) => Promise<K>;
 
   /**
    * Create the provided K8s resource or throw an error if it already exists.
    *
-   * @param resource
-   * @returns
+   * @param resource - the resource to create
+   * @returns the created resource
    */
   Create: (resource: K) => Promise<K>;
 
@@ -94,18 +105,18 @@ export type K8sWithFilters<K extends KubernetesObject> = K8sFilteredActions<K> &
    *
    * ```ts
    * K8s(kind.Deployment)
-   *  .WithField("metadata.name", "bar")
-   *  .WithField("metadata.namespace", "qux")
-   *  .Delete(...)
+   * .WithField("metadata.name", "bar")
+   * .WithField("metadata.namespace", "qux")
+   * .Delete(...)
    * ```
    *
    * Will only delete the Deployment if it has the `metadata.name=bar` and `metadata.namespace=qux` fields.
    * Not all fields are supported, see https://kubernetes.io/docs/concepts/overview/working-with-objects/field-selectors/#supported-fields,
    * but Typescript will limit to only fields that exist on the resource.
    *
-   * @param key  The field key
-   * @param value The field value
-   * @returns
+   * @param key - the field key
+   * @param value - the field value
+   * @returns the fluent API
    */
   WithField: <P extends Paths<K>>(key: P, value: string) => K8sWithFilters<K>;
 
@@ -115,15 +126,16 @@ export type K8sWithFilters<K extends KubernetesObject> = K8sFilteredActions<K> &
    *
    * ```ts
    * K8s(kind.Deployment)
-   *   .WithLabel("foo", "bar")
-   *   .WithLabel("baz", "qux")
-   *   .Delete(...)
+   * .WithLabel("foo", "bar")
+   * .WithLabel("baz", "qux")
+   * .Delete(...)
    * ```
    *
    * Will only delete the Deployment if it has the`foo=bar` and `baz=qux` labels.
    *
-   * @param key The label key
-   * @param value (optional) The label value
+   * @param key - the label key
+   * @param value - the label value
+   * @returns the fluent API
    */
   WithLabel: (key: string, value: string) => K8sWithFilters<K>;
 };
@@ -131,10 +143,10 @@ export type K8sWithFilters<K extends KubernetesObject> = K8sFilteredActions<K> &
 export type K8sInit<K extends KubernetesObject> = K8sWithFilters<K> &
   K8sUnfilteredActions<K> & {
     /**
-     * Filter the query by the given namespace.
+     * Set the namespace filter.
      *
-     * @param namespace
-     * @returns
+     * @param namespace - the namespace to filter on
+     * @returns the fluent API
      */
     InNamespace: (namespace: string) => K8sWithFilters<K>;
   };

package/src/fluent/utils.test.ts

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: Apache-2.0
-// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+// SPDX-FileCopyrightText: 2023-Present The Kubernetes Fluent Client Authors
 
 import { beforeEach, describe, expect, it, jest } from "@jest/globals";
 

package/src/fluent/utils.ts

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: Apache-2.0
-// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+// SPDX-FileCopyrightText: 2023-Present The Kubernetes Fluent Client Authors
 
 import { KubeConfig, PatchStrategy } from "@kubernetes/client-node";
 
@@ -16,11 +16,11 @@ const SSA_CONTENT_TYPE = "application/apply-patch+yaml";
 /**
  * Generate a path to a Kubernetes resource
  *
- * @param serverUrl
- * @param model
- * @param filters
- * @param excludeName
- * @returns
+ * @param serverUrl - the URL of the Kubernetes API server
+ * @param model - the model to use for the API
+ * @param filters - (optional) filter overrides, can also be chained
+ * @param excludeName - (optional) exclude the name from the path
+ * @returns the path to the resource
  */
 export function pathBuilder<T extends GenericClass>(
   serverUrl: string,
@@ -90,8 +90,8 @@ export function pathBuilder<T extends GenericClass>(
  * - We have to create an agent to handle the TLS connection (for the custom CA + mTLS in some cases)
  * - The K8s lib uses request instead of node-fetch today so the object is slightly different
  *
- * @param method
- * @returns
+ * @param method - the HTTP method to use
+ * @returns the fetch options and server URL
  */
 export async function k8sCfg(method: FetchMethods) {
   const kubeConfig = new KubeConfig();
@@ -119,6 +119,17 @@ export async function k8sCfg(method: FetchMethods) {
   return { opts, serverUrl: cluster.server };
 }
 
+/**
+ * Execute a request against the Kubernetes API server.
+ *
+ * @param model - the model to use for the API
+ * @param filters - (optional) filter overrides, can also be chained
+ * @param method - the HTTP method to use
+ * @param payload - (optional) the payload to send
+ * @param applyCfg - (optional) configuration for the apply method
+ *
+ * @returns the parsed JSON response
+ */
 export async function k8sExec<T extends GenericClass, K>(
   model: T,
   filters: Filters,

package/src/fluent/watch.ts

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: Apache-2.0
-// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+// SPDX-FileCopyrightText: 2023-Present The Kubernetes Fluent Client Authors
 
 import byline from "byline";
 import fetch from "node-fetch";
@@ -14,13 +14,14 @@ import { k8sCfg, pathBuilder } from "./utils";
 export type WatchController = {
   /**
    * Abort the watch.
+   *
    * @param reason optional reason for aborting the watch
-   * @returns
    */
   abort: (reason?: string) => void;
   /**
    * Get the AbortSignal for the watch.
-   * @returns
+   *
+   * @returns the AbortSignal
    */
   signal: () => AbortSignal;
 };
@@ -49,6 +50,12 @@ export type WatchCfg = {
 
 /**
  * Execute a watch on the specified resource.
+ *
+ * @param model - the model to use for the API
+ * @param filters - (optional) filter overrides, can also be chained
+ * @param callback - the callback function to call when an event is received
+ * @param watchCfg - (optional) watch configuration
+ * @returns a WatchController to allow the watch to be aborted externally
  */
 export async function ExecWatch<T extends GenericClass>(
   model: T,
@@ -94,6 +101,9 @@ export async function ExecWatch<T extends GenericClass>(
   // Create a wrapped AbortController to allow the watch to be aborted externally
   const abortWrapper = {} as WatchController;
 
+  /**
+   * Bind the abort controller to the wrapper.
+   */
   function bindAbortController() {
     // Create a new AbortController
     abortController = new AbortController();
@@ -106,6 +116,9 @@ export async function ExecWatch<T extends GenericClass>(
     opts.signal = abortController.signal;
   }
 
+  /**
+   * The main watch runner. This will run until the process is terminated or the watch is aborted.
+   */
   async function runner() {
     let doneCalled = false;
 
@@ -130,6 +143,7 @@ export async function ExecWatch<T extends GenericClass>(
       }
     };
 
+    // Cleanup the stream listeners
     const cleanup = () => {
       if (!doneCalled) {
         doneCalled = true;
@@ -181,7 +195,11 @@ export async function ExecWatch<T extends GenericClass>(
       onError(e);
     }
 
-    // On unhandled errors, retry the watch
+    /**
+     * Reload the watch.
+     *
+     * @param e - the error that caused the reload
+     */
     async function reload(e: Error) {
       // If there are more attempts, retry the watch
       if (watchCfg.retryMax! > retryCount) {

package/src/generate.test.ts

@@ -0,0 +1,266 @@
+import { beforeEach, describe, expect, jest, test } from "@jest/globals";
+import { generate } from "./generate";
+import fs from "fs";
+
+const sampleYaml = `
+# non-crd should be ignored
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: test
+  namespace: default
+data:
+  any: bleh
+---
+apiVersion: apiextensions.k8s.io/v1
+kind: CustomResourceDefinition
+metadata:
+  name: movies.example.com
+spec:
+  group: example.com
+  names:
+    kind: Movie
+    plural: movies
+  scope: Namespaced
+  versions:
+    - name: v1
+      schema:
+        openAPIV3Schema:
+          type: object
+          description: Movie nerd
+          properties:
+            spec:
+              properties:
+                title:
+                  type: string
+                author:
+                  type: string
+              type: object
+---
+# duplicate entries should not break things
+apiVersion: apiextensions.k8s.io/v1
+kind: CustomResourceDefinition
+metadata:
+  name: movies.example.com
+spec:
+  group: example.com
+  names:
+    kind: Movie
+    plural: movies
+  scope: Namespaced
+  versions:
+    - name: v1
+      schema:
+        openAPIV3Schema:
+          type: object
+          description: Movie nerd
+          properties:
+            spec:
+              properties:
+                title:
+                  type: string
+                author:
+                  type: string
+              type: object
+---            
+# should support multiple versions
+apiVersion: apiextensions.k8s.io/v1
+kind: CustomResourceDefinition
+metadata:
+  name: books.example.com
+spec:
+  group: example.com
+  names:
+    kind: Book
+    plural: books
+  scope: Namespaced
+  versions:
+    - name: v1
+      schema:
+        openAPIV3Schema:
+          type: object
+          description: Book nerd
+          properties:
+            spec:
+              properties:
+                title:
+                  type: string
+                author:
+                  type: string
+              type: object
+    - name: v2
+      schema:
+        openAPIV3Schema:
+          type: object
+          description: Book nerd
+          properties:
+            spec:
+              properties:
+                author:
+                  type: string
+              type: object
+      served: true
+      storage: true
+`;
+
+jest.mock("./fetch", () => ({
+  fetch: jest.fn(),
+}));
+
+jest.mock("./fluent", () => ({
+  K8s: jest.fn(),
+}));
+
+describe("CRD to TypeScript Conversion", () => {
+  const originalReadFileSync = fs.readFileSync;
+
+  jest.isolateModules(() => {
+    jest.spyOn(fs, "existsSync").mockReturnValue(true);
+    jest.spyOn(fs, "readFileSync").mockImplementation((...args) => {
+      // Super janky hack due ot source-map-support calling readFileSync internally
+      if (args[0].toString().includes("test-crd.yaml")) {
+        return sampleYaml;
+      }
+      return originalReadFileSync(...args);
+    });
+    jest.spyOn(fs, "mkdirSync").mockReturnValue(undefined);
+    jest.spyOn(fs, "writeFileSync").mockReturnValue(undefined);
+  });
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  test("converts CRD to TypeScript", async () => {
+    const options = { source: "test-crd.yaml", language: "ts" }; // specify your options
+
+    const actual = await generate(options);
+    const expectedMovie = [
+      "// This file is auto-generated by kubernetes-fluent-client, do not edit manually\n",
+      'import { GenericKind, RegisterKind } from "kubernetes-fluent-client";\n',
+      "/**",
+      " * Movie nerd",
+      " */",
+      "export class Movie extends GenericKind {",
+      "    spec?: Spec;",
+      "}",
+      "",
+      "export interface Spec {",
+      "    author?: string;",
+      "    title?:  string;",
+      "}",
+      "",
+      "RegisterKind(Movie, {",
+      '  group: "example.com",',
+      '  version: "v1",',
+      '  kind: "Movie",',
+      "});",
+    ];
+    const expectedBookV1 = [
+      "// This file is auto-generated by kubernetes-fluent-client, do not edit manually\n",
+      'import { GenericKind, RegisterKind } from "kubernetes-fluent-client";\n',
+      "/**",
+      " * Book nerd",
+      " */",
+      "export class Book extends GenericKind {",
+      "    spec?: Spec;",
+      "}",
+      "",
+      "export interface Spec {",
+      "    author?: string;",
+      "    title?:  string;",
+      "}",
+      "",
+      "RegisterKind(Book, {",
+      '  group: "example.com",',
+      '  version: "v1",',
+      '  kind: "Book",',
+      "});",
+    ];
+    const expectedBookV2 = expectedBookV1
+      .filter(line => !line.includes("title?"))
+      .map(line => line.replace("v1", "v2"));
+
+    expect(actual["movie-v1"]).toEqual(expectedMovie);
+    expect(actual["book-v1"]).toEqual(expectedBookV1);
+    expect(actual["book-v2"]).toEqual(expectedBookV2);
+  });
+
+  test("converts CRD to TypeScript with plain option", async () => {
+    const options = { source: "test-crd.yaml", language: "ts", plain: true }; // specify your options
+
+    const actual = await generate(options);
+    const expectedMovie = [
+      "/**",
+      " * Movie nerd",
+      " */",
+      "export interface Movie {",
+      "    spec?: Spec;",
+      "}",
+      "",
+      "export interface Spec {",
+      "    author?: string;",
+      "    title?:  string;",
+      "}",
+      "",
+    ];
+    const expectedBookV1 = [
+      "/**",
+      " * Book nerd",
+      " */",
+      "export interface Book {",
+      "    spec?: Spec;",
+      "}",
+      "",
+      "export interface Spec {",
+      "    author?: string;",
+      "    title?:  string;",
+      "}",
+      "",
+    ];
+    const expectedBookV2 = expectedBookV1
+      .filter(line => !line.includes("title?"))
+      .map(line => line.replace("v1", "v2"));
+
+    expect(actual["movie-v1"]).toEqual(expectedMovie);
+    expect(actual["book-v1"]).toEqual(expectedBookV1);
+    expect(actual["book-v2"]).toEqual(expectedBookV2);
+  });
+
+  test("converts CRD to Go", async () => {
+    const options = { source: "test-crd.yaml", language: "go" }; // specify your options
+
+    const actual = await generate(options);
+    const expectedMovie = [
+      "// Movie nerd",
+      "type Movie struct {",
+      '\tSpec *Spec `json:"spec,omitempty"`',
+      "}",
+      "",
+      "type Spec struct {",
+      '\tAuthor *string `json:"author,omitempty"`',
+      '\tTitle  *string `json:"title,omitempty"`',
+      "}",
+      "",
+    ];
+    const expectedBookV1 = [
+      "// Book nerd",
+      "type Book struct {",
+      '\tSpec *Spec `json:"spec,omitempty"`',
+      "}",
+      "",
+      "type Spec struct {",
+      '\tAuthor *string `json:"author,omitempty"`',
+      '\tTitle  *string `json:"title,omitempty"`',
+      "}",
+      "",
+    ];
+    const expectedBookV2 = expectedBookV1
+      .filter(line => !line.includes("Title"))
+      .map(line => line.replace("v1", "v2"));
+
+    expect(actual["movie-v1"]).toEqual(expectedMovie);
+    expect(actual["book-v1"]).toEqual(expectedBookV1);
+    expect(actual["book-v2"]).toEqual(expectedBookV2);
+  });
+});