pepr 0.35.0 → 0.37.0

package/src/lib/queue.ts

@@ -2,11 +2,15 @@
 // SPDX-FileCopyrightText: 2023-Present The Pepr Authors
 import { KubernetesObject } from "@kubernetes/client-node";
 import { WatchPhase } from "kubernetes-fluent-client/dist/fluent/types";
+import { randomBytes } from "node:crypto";
 import Log from "./logger";
 
+type WatchCallback = (obj: KubernetesObject, phase: WatchPhase) => Promise<void>;
+
 type QueueItem<K extends KubernetesObject> = {
   item: K;
-  type: WatchPhase;
+  phase: WatchPhase;
+  callback: WatchCallback;
   resolve: (value: void | PromiseLike<void>) => void;
   reject: (reason?: string) => void;
 };
@@ -15,16 +19,27 @@ type QueueItem<K extends KubernetesObject> = {
  * Queue is a FIFO queue for reconciling
  */
 export class Queue<K extends KubernetesObject> {
+  #name: string;
+  #uid: string;
   #queue: QueueItem<K>[] = [];
   #pendingPromise = false;
-  #reconcile?: (obj: KubernetesObject, type: WatchPhase) => Promise<void>;
 
-  constructor() {
-    this.#reconcile = async () => await new Promise(resolve => resolve());
+  constructor(name: string) {
+    this.#name = name;
+    this.#uid = `${Date.now()}-${randomBytes(2).toString("hex")}`;
+  }
+
+  label() {
+    return { name: this.#name, uid: this.#uid };
   }
 
-  setReconcile(reconcile: (obj: KubernetesObject, type: WatchPhase) => Promise<void>) {
-    this.#reconcile = reconcile;
+  stats() {
+    return {
+      queue: this.label(),
+      stats: {
+        length: this.#queue.length,
+      },
+    };
   }
 
   /**
@@ -32,12 +47,23 @@ export class Queue<K extends KubernetesObject> {
    * reconciled.
    *
    * @param item The object to reconcile
+   * @param type The watch phase requested for reconcile
+   * @param reconcile The callback to enqueue for reconcile
    * @returns A promise that resolves when the object is reconciled
    */
-  enqueue(item: K, type: WatchPhase) {
-    Log.debug(`Enqueueing ${item.metadata!.namespace}/${item.metadata!.name}`);
+  enqueue(item: K, phase: WatchPhase, reconcile: WatchCallback) {
+    const note = {
+      queue: this.label(),
+      item: {
+        name: item.metadata?.name,
+        namespace: item.metadata?.namespace,
+        resourceVersion: item.metadata?.resourceVersion,
+      },
+    };
+    Log.debug(note, "Enqueueing");
     return new Promise<void>((resolve, reject) => {
-      this.#queue.push({ item, type, resolve, reject });
+      this.#queue.push({ item, phase, callback: reconcile, resolve, reject });
+      Log.debug(this.stats(), "Queue stats - push");
       return this.#dequeue();
     });
   }
@@ -68,16 +94,25 @@ export class Queue<K extends KubernetesObject> {
       this.#pendingPromise = true;
 
       // Reconcile the element
-      if (this.#reconcile) {
-        Log.debug(`Reconciling ${element.item.metadata!.name}`);
-        await this.#reconcile(element.item, element.type);
-      }
+      const note = {
+        queue: this.label(),
+        item: {
+          name: element.item.metadata?.name,
+          namespace: element.item.metadata?.namespace,
+          resourceVersion: element.item.metadata?.resourceVersion,
+        },
+      };
+      Log.debug(note, "Reconciling");
+      await element.callback(element.item, element.phase);
+      Log.debug(note, "Reconciled");
 
       element.resolve();
     } catch (e) {
       Log.debug(`Error reconciling ${element.item.metadata!.name}`, { error: e });
       element.reject(e);
     } finally {
+      Log.debug(this.stats(), "Queue stats - shift");
+
       // Reset the pending promise flag
       Log.debug("Resetting pending promise and dequeuing");
       this.#pendingPromise = false;

package/src/lib/schedule.ts

@@ -3,7 +3,7 @@
 
 import { PeprStore } from "./storage";
 
-type Unit = "seconds" | "second" | "minute" | "minutes" | "hours" | "hour";
+export type Unit = "seconds" | "second" | "minute" | "minutes" | "hours" | "hour";
 
 export interface Schedule {
   /**

package/src/lib/storage.ts

@@ -2,7 +2,6 @@
 // SPDX-FileCopyrightText: 2023-Present The Pepr Authors
 
 import { clone } from "ramda";
-import Log from "./logger";
 import pointer from "json-pointer";
 export type DataOp = "add" | "remove";
 export type DataStore = Record<string, string>;
@@ -86,7 +85,6 @@ export class Storage implements PeprStore {
   };
 
   receive = (data: DataStore) => {
-    Log.debug(data, `Pepr store data received`);
     this.#store = data || {};
 
     this.#onReady();
@@ -107,10 +105,11 @@ export class Storage implements PeprStore {
   };
 
   clear = () => {
-    this.#dispatchUpdate(
-      "remove",
-      Object.keys(this.#store).map(key => pointer.escape(key)),
-    );
+    Object.keys(this.#store).length > 0 &&
+      this.#dispatchUpdate(
+        "remove",
+        Object.keys(this.#store).map(key => pointer.escape(key)),
+      );
   };
 
   removeItem = (key: string) => {

package/src/lib/types.ts

@@ -2,11 +2,21 @@
 // SPDX-FileCopyrightText: 2023-Present The Pepr Authors
 
 import { GenericClass, GroupVersionKind, KubernetesObject } from "kubernetes-fluent-client";
-import { WatchAction } from "kubernetes-fluent-client/dist/fluent/types";
+
+import { WatchPhase } from "kubernetes-fluent-client/dist/fluent/types";
 
 import { PeprMutateRequest } from "./mutate-request";
 import { PeprValidateRequest } from "./validate-request";
+import { Answers } from "prompts";
+
+import { Logger } from "pino";
 
+export enum Operation {
+  CREATE = "CREATE",
+  UPDATE = "UPDATE",
+  DELETE = "DELETE",
+  CONNECT = "CONNECT",
+}
 /**
  * Specifically for deploying images with a private registry
  */
@@ -80,24 +90,33 @@ export type WhenSelector<T extends GenericClass> = {
   /** Register an action to be executed when a Kubernetes resource is deleted. */
   IsDeleted: () => BindingAll<T>;
 };
-
+export interface RegExpFilter {
+  obj: RegExp;
+  source: string;
+}
 export type Binding = {
   event: Event;
   isMutate?: boolean;
   isValidate?: boolean;
   isWatch?: boolean;
   isQueue?: boolean;
+  isFinalize?: boolean;
   readonly model: GenericClass;
   readonly kind: GroupVersionKind;
   readonly filters: {
     name: string;
+    regexName: string;
     namespaces: string[];
+    regexNamespaces: string[];
     labels: Record<string, string>;
     annotations: Record<string, string>;
+    deletionTimestamp: boolean;
   };
+  alias?: string;
   readonly mutateCallback?: MutateAction<GenericClass, InstanceType<GenericClass>>;
   readonly validateCallback?: ValidateAction<GenericClass, InstanceType<GenericClass>>;
-  readonly watchCallback?: WatchAction<GenericClass, InstanceType<GenericClass>>;
+  readonly watchCallback?: WatchLogAction<GenericClass, InstanceType<GenericClass>>;
+  readonly finalizeCallback?: FinalizeAction<GenericClass, InstanceType<GenericClass>>;
 };
 
 export type BindingFilter<T extends GenericClass> = CommonActionChain<T> & {
@@ -137,16 +156,22 @@ export type BindingFilter<T extends GenericClass> = CommonActionChain<T> & {
    * @param value
    */
   WithAnnotation: (key: string, value?: string) => BindingFilter<T>;
+  /** Only apply the action if the resource has a deletionTimestamp. */
+  WithDeletionTimestamp: () => BindingFilter<T>;
 };
 
 export type BindingWithName<T extends GenericClass> = BindingFilter<T> & {
   /** Only apply the action if the resource name matches the specified name. */
   WithName: (name: string) => BindingFilter<T>;
+  /** Only apply the action if the resource name matches the specified regex name. */
+  WithNameRegex: (name: RegExp) => BindingFilter<T>;
 };
 
 export type BindingAll<T extends GenericClass> = BindingWithName<T> & {
   /** Only apply the action if the resource is in one of the specified namespaces.*/
   InNamespace: (...namespaces: string[]) => BindingWithName<T>;
+  /** Only apply the action if the resource is in one of the specified regex namespaces.*/
+  InNamespaceRegex: (...namespaces: RegExp[]) => BindingWithName<T>;
 };
 
 export type CommonActionChain<T extends GenericClass> = MutateActionChain<T> & {
@@ -159,6 +184,7 @@ export type CommonActionChain<T extends GenericClass> = MutateActionChain<T> & {
    * @param action The action to be executed when the Kubernetes resource is processed by the AdmissionController.
    */
   Mutate: (action: MutateAction<T, InstanceType<T>>) => MutateActionChain<T>;
+  Alias: (alias: string) => BindingFilter<T>;
 };
 
 export type ValidateActionChain<T extends GenericClass> = {
@@ -173,7 +199,8 @@ export type ValidateActionChain<T extends GenericClass> = {
    * @param action
    * @returns
    */
-  Watch: (action: WatchAction<T, InstanceType<T>>) => void;
+
+  Watch: (action: WatchLogAction<T, InstanceType<T>>) => FinalizeActionChain<T>;
 
   /**
    * Establish a reconcile for the specified resource. The callback function will be executed after the admission controller has
@@ -186,7 +213,8 @@ export type ValidateActionChain<T extends GenericClass> = {
    * @param action
    * @returns
    */
-  Reconcile: (action: WatchAction<T, InstanceType<T>>) => void;
+
+  Reconcile: (action: WatchLogAction<T, InstanceType<T>>) => FinalizeActionChain<T>;
 };
 
 export type MutateActionChain<T extends GenericClass> = ValidateActionChain<T> & {
@@ -216,14 +244,135 @@ export type MutateActionChain<T extends GenericClass> = ValidateActionChain<T> &
 
 export type MutateAction<T extends GenericClass, K extends KubernetesObject = InstanceType<T>> = (
   req: PeprMutateRequest<K>,
+  logger?: Logger,
 ) => Promise<void> | void | Promise<PeprMutateRequest<K>> | PeprMutateRequest<K>;
 
 export type ValidateAction<T extends GenericClass, K extends KubernetesObject = InstanceType<T>> = (
   req: PeprValidateRequest<K>,
+  logger?: Logger,
 ) => Promise<ValidateActionResponse> | ValidateActionResponse;
 
+// Define WatchLogAction by adding an optional logger parameter to the WatchAction
+export type WatchLogAction<T extends GenericClass, K extends KubernetesObject = InstanceType<T>> = (
+  update: K,
+  phase: WatchPhase,
+  logger?: Logger,
+) => Promise<void> | void;
+
 export type ValidateActionResponse = {
   allowed: boolean;
   statusCode?: number;
   statusMessage?: string;
 };
+
+export type FinalizeAction<T extends GenericClass, K extends KubernetesObject = InstanceType<T>> = (
+  update: K,
+  logger?: Logger,
+) => Promise<void> | void;
+
+export type FinalizeActionChain<T extends GenericClass> = {
+  /**
+   * Establish a finalizer for the specified resource. The callback given will be executed by the watch
+   * controller after it has received notification of an update adding a deletionTimestamp.
+   *
+   * **Beta Function**: This method is still in early testing and edge cases may still exist.
+   *
+   * @since 0.35.0
+   *
+   * @param action
+   * @returns
+   */
+  Finalize: (action: FinalizeAction<T, InstanceType<T>>) => void;
+};
+
+export type InitOptions = Answers<"name" | "description" | "errorBehavior">;
+
+/**
+ * A Kubernetes admission request to be processed by a capability.
+ */
+export interface AdmissionRequest<T = KubernetesObject> {
+  /** UID is an identifier for the individual request/response. */
+  readonly uid: string;
+
+  /** Kind is the fully-qualified type of object being submitted (for example, v1.Pod or autoscaling.v1.Scale) */
+  readonly kind: GroupVersionKind;
+
+  /** Resource is the fully-qualified resource being requested (for example, v1.pods) */
+  readonly resource: GroupVersionResource;
+
+  /** SubResource is the sub-resource being requested, if any (for example, "status" or "scale") */
+  readonly subResource?: string;
+
+  /** RequestKind is the fully-qualified type of the original API request (for example, v1.Pod or autoscaling.v1.Scale). */
+  readonly requestKind?: GroupVersionKind;
+
+  /** RequestResource is the fully-qualified resource of the original API request (for example, v1.pods). */
+  readonly requestResource?: GroupVersionResource;
+
+  /** RequestSubResource is the sub-resource of the original API request, if any (for example, "status" or "scale"). */
+  readonly requestSubResource?: string;
+
+  /**
+   * Name is the name of the object as presented in the request. On a CREATE operation, the client may omit name and
+   * rely on the server to generate the name. If that is the case, this method will return the empty string.
+   */
+  readonly name: string;
+
+  /** Namespace is the namespace associated with the request (if any). */
+  readonly namespace?: string;
+
+  /**
+   * Operation is the operation being performed. This may be different than the operation
+   * requested. e.g. a patch can result in either a CREATE or UPDATE Operation.
+   */
+  readonly operation: Operation;
+
+  /** UserInfo is information about the requesting user */
+  readonly userInfo: {
+    /** The name that uniquely identifies this user among all active users. */
+    username?: string;
+
+    /**
+     * A unique value that identifies this user across time. If this user is deleted
+     * and another user by the same name is added, they will have different UIDs.
+     */
+    uid?: string;
+
+    /** The names of groups this user is a part of. */
+    groups?: string[];
+
+    /** Any additional information provided by the authenticator. */
+    extra?: {
+      [key: string]: string[];
+    };
+  };
+
+  /** Object is the object from the incoming request prior to default values being applied */
+  readonly object: T;
+
+  /** OldObject is the existing object. Only populated for UPDATE or DELETE requests. */
+  readonly oldObject?: T;
+
+  /** DryRun indicates that modifications will definitely not be persisted for this request. Defaults to false. */
+  readonly dryRun?: boolean;
+
+  /**
+   * Options contains the options for the operation being performed.
+   * e.g. `meta.k8s.io/v1.DeleteOptions` or `meta.k8s.io/v1.CreateOptions`. This may be
+   * different than the options the caller provided. e.g. for a patch request the performed
+   * Operation might be a CREATE, in which case the Options will a
+   * `meta.k8s.io/v1.CreateOptions` even though the caller provided `meta.k8s.io/v1.PatchOptions`.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  readonly options?: any;
+}
+
+/**
+ * GroupVersionResource unambiguously identifies a resource. It doesn't anonymously include GroupVersion
+ * to avoid automatic coercion. It doesn't use a GroupVersion to avoid custom marshalling
+ */
+export interface GroupVersionResource {
+  readonly group: string;
+  readonly version: string;
+  readonly resource: string;
+}

package/src/lib/validate-processor.ts

@@ -5,12 +5,15 @@ import { kind } from "kubernetes-fluent-client";
 
 import { Capability } from "./capability";
 import { shouldSkipRequest } from "./filter";
-import { AdmissionRequest, ValidateResponse } from "./k8s";
+import { ValidateResponse } from "./k8s";
+import { AdmissionRequest } from "./types";
 import Log from "./logger";
 import { convertFromBase64Map } from "./utils";
 import { PeprValidateRequest } from "./validate-request";
+import { ModuleConfig } from "./module";
 
 export async function validateProcessor(
+  config: ModuleConfig,
   capabilities: Capability[],
   req: AdmissionRequest,
   reqMetadata: Record<string, string>,
@@ -41,7 +44,7 @@ export async function validateProcessor(
       };
 
       // Continue to the next action without doing anything if this one should be skipped
-      if (shouldSkipRequest(action, req, namespaces)) {
+      if (shouldSkipRequest(action, req, namespaces, config?.alwaysIgnore?.namespaces)) {
         continue;
       }
 

package/src/lib/validate-request.test.ts

@@ -3,11 +3,8 @@
 
 import { beforeEach, describe, expect, it } from "@jest/globals";
 import { KubernetesObject } from "kubernetes-fluent-client";
-
-import { Operation, AdmissionRequest } from "./k8s";
-import { ValidateActionResponse } from "./types";
+import { ValidateActionResponse, AdmissionRequest, Operation } from "./types";
 import { PeprValidateRequest } from "./validate-request";
-
 describe("PeprValidateRequest", () => {
   let mockRequest: AdmissionRequest<KubernetesObject>;
 

package/src/lib/validate-request.ts

@@ -6,7 +6,7 @@
 import { KubernetesObject } from "kubernetes-fluent-client";
 
 import { clone } from "ramda";
-import { Operation, AdmissionRequest } from "./k8s";
+import { AdmissionRequest, Operation } from "./types";
 import { ValidateActionResponse } from "./types";
 
 /**