pepr 0.13.3 → 0.14.0

package/src/lib/metrics.ts

@@ -51,29 +51,19 @@ export class MetricsCollector {
     this.addSummary(this.#metricNames.validate, "Validation operation summary");
   }
 
-  #getMetricName(name: string) {
-    return `${this.#prefix}_${name}`;
-  }
+  #getMetricName = (name: string) => `${this.#prefix}_${name}`;
 
-  #addMetric<T extends Counter<string> | Summary<string>>(
+  #addMetric = <T extends Counter<string> | Summary<string>>(
     collection: Map<string, T>,
     MetricType: new (args: MetricArgs) => T,
     name: string,
     help: string,
-  ) {
+  ) => {
     if (collection.has(this.#getMetricName(name))) {
       Log.debug(`Metric for ${name} already exists`, loggingPrefix);
       return;
     }
 
-    // Bind public methods
-    this.incCounter = this.incCounter.bind(this);
-    this.error = this.error.bind(this);
-    this.alert = this.alert.bind(this);
-    this.observeStart = this.observeStart.bind(this);
-    this.observeEnd = this.observeEnd.bind(this);
-    this.getMetrics = this.getMetrics.bind(this);
-
     const metric = new MetricType({
       name: this.#getMetricName(name),
       help,
@@ -81,56 +71,50 @@ export class MetricsCollector {
     });
 
     collection.set(this.#getMetricName(name), metric);
-  }
+  };
 
-  addCounter(name: string, help: string) {
+  addCounter = (name: string, help: string) => {
     this.#addMetric(this.#counters, promClient.Counter, name, help);
-  }
+  };
 
-  addSummary(name: string, help: string) {
+  addSummary = (name: string, help: string) => {
     this.#addMetric(this.#summaries, promClient.Summary, name, help);
-  }
+  };
 
-  incCounter(name: string) {
+  incCounter = (name: string) => {
     this.#counters.get(this.#getMetricName(name))?.inc();
-  }
+  };
 
   /**
    * Increments the error counter.
    */
-  error() {
-    this.incCounter(this.#metricNames.errors);
-  }
+  error = () => this.incCounter(this.#metricNames.errors);
 
   /**
    * Increments the alerts counter.
    */
-  alert() {
-    this.incCounter(this.#metricNames.alerts);
-  }
-
-  /**
-   * Returns the current timestamp from performance.now() method. Useful for start timing an operation.
-   * @returns The timestamp.
-   */
-  observeStart() {
-    return performance.now();
-  }
+  alert = () => this.incCounter(this.#metricNames.alerts);
 
   /**
    * Observes the duration since the provided start time and updates the summary.
    * @param startTime - The start time.
    * @param name - The metrics summary to increment.
    */
-  observeEnd(startTime: number, name: string = this.#metricNames.mutate) {
+  observeEnd = (startTime: number, name: string = this.#metricNames.mutate) => {
     this.#summaries.get(this.#getMetricName(name))?.observe(performance.now() - startTime);
-  }
+  };
 
   /**
    * Fetches the current metrics from the registry.
    * @returns The metrics.
    */
-  async getMetrics() {
-    return this.#registry.metrics();
+  getMetrics = () => this.#registry.metrics();
+
+  /**
+   * Returns the current timestamp from performance.now() method. Useful for start timing an operation.
+   * @returns The timestamp.
+   */
+  static observeStart() {
+    return performance.now();
   }
 }

package/src/lib/module.ts

@@ -6,8 +6,29 @@ import { clone } from "ramda";
 import { Capability } from "./capability";
 import { Controller } from "./controller";
 import { ValidateError } from "./errors";
-import { MutateResponse, Request, ValidateResponse } from "./k8s/types";
-import { CapabilityExport, ModuleConfig } from "./types";
+import { AdmissionRequest, MutateResponse, ValidateResponse, WebhookIgnore } from "./k8s";
+import { CapabilityExport } from "./types";
+import { setupWatch } from "./watch-processor";
+
+/** Global configuration for the Pepr runtime. */
+export type ModuleConfig = {
+  /** The user-defined name for the module */
+  name: string;
+  /** The Pepr version this module uses */
+  peprVersion?: string;
+  /** The user-defined version of the module */
+  appVersion?: string;
+  /** A unique identifier for this Pepr module. This is automatically generated by Pepr. */
+  uuid: string;
+  /** A description of the Pepr module and what it does. */
+  description?: string;
+  /** Reject K8s resource AdmissionRequests on error. */
+  onError?: string;
+  /** Configure global exclusions that will never be processed by Pepr. */
+  alwaysIgnore: WebhookIgnore;
+  /** Define the log level for the in-cluster controllers */
+  logLevel?: string;
+};
 
 export type PackageJSON = {
   description: string;
@@ -18,12 +39,20 @@ export type PeprModuleOptions = {
   deferStart?: boolean;
 
   /** A user-defined callback to pre-process or intercept a Pepr request from K8s immediately before it is processed */
-  beforeHook?: (req: Request) => void;
+  beforeHook?: (req: AdmissionRequest) => void;
 
   /** A user-defined callback to post-process or intercept a Pepr response just before it is returned to K8s */
   afterHook?: (res: MutateResponse | ValidateResponse) => void;
 };
 
+// Track if this is a watch mode controller
+export const isWatchMode = () => process.env.PEPR_WATCH_MODE === "true";
+
+// Track if Pepr is running in build mode
+export const isBuildMode = () => process.env.PEPR_MODE === "build";
+
+export const isDevMode = () => process.env.PEPR_MODE === "dev";
+
 export class PeprModule {
   #controller!: Controller;
 
@@ -41,11 +70,13 @@ export class PeprModule {
     // Need to validate at runtime since TS gets sad about parsing the package.json
     ValidateError(config.onError);
 
-    // Bind public methods
-    this.start = this.start.bind(this);
-
     // Handle build mode
-    if (process.env.PEPR_MODE === "build" && process.send) {
+    if (isBuildMode()) {
+      // Fail if process.send is not defined
+      if (!process.send) {
+        throw new Error("process.send is not defined");
+      }
+
       const exportedCapabilities: CapabilityExport[] = [];
 
       // Send capability map to parent process
@@ -59,12 +90,18 @@ export class PeprModule {
         });
       }
 
+      // Send the capabilities back to the parent process
       process.send(exportedCapabilities);
 
       return;
     }
 
-    this.#controller = new Controller(config, capabilities, opts.beforeHook, opts.afterHook);
+    this.#controller = new Controller(config, capabilities, opts.beforeHook, opts.afterHook, () => {
+      // Wait for the controller to be ready before setting up watches
+      if (isWatchMode() || isDevMode()) {
+        setupWatch(capabilities);
+      }
+    });
 
     // Stop processing if deferStart is set to true
     if (opts.deferStart) {
@@ -80,7 +117,7 @@ export class PeprModule {
    *
    * @param port
    */
-  start(port = 3000) {
+  start = (port = 3000) => {
     this.#controller.startServer(port);
-  }
+  };
 }

package/src/lib/mutate-processor.ts

@@ -2,21 +2,21 @@
 // SPDX-FileCopyrightText: 2023-Present The Pepr Authors
 
 import jsonPatch from "fast-json-patch";
+import { kind } from "kubernetes-fluent-client";
 
 import { Capability } from "./capability";
 import { Errors } from "./errors";
 import { shouldSkipRequest } from "./filter";
-import { MutateResponse, Request } from "./k8s/types";
-import { Secret } from "./k8s/upstream";
+import { MutateResponse, AdmissionRequest } from "./k8s";
 import Log from "./logger";
+import { ModuleConfig } from "./module";
 import { PeprMutateRequest } from "./mutate-request";
-import { ModuleConfig } from "./types";
 import { base64Encode, convertFromBase64Map, convertToBase64Map } from "./utils";
 
 export async function mutateProcessor(
   config: ModuleConfig,
   capabilities: Capability[],
-  req: Request,
+  req: AdmissionRequest,
   reqMetadata: Record<string, string>,
 ): Promise<MutateResponse> {
   const wrapped = new PeprMutateRequest(req);
@@ -35,7 +35,7 @@ export async function mutateProcessor(
   // If the resource is a secret, decode the data
   const isSecret = req.kind.version == "v1" && req.kind.kind == "Secret";
   if (isSecret) {
-    skipDecode = convertFromBase64Map(wrapped.Raw as unknown as Secret);
+    skipDecode = convertFromBase64Map(wrapped.Raw as unknown as kind.Secret);
   }
 
   Log.info(reqMetadata, `Processing request`);
@@ -124,7 +124,7 @@ export async function mutateProcessor(
 
   // Post-process the Secret requests to convert it back to the original format
   if (isSecret) {
-    convertToBase64Map(transformed as unknown as Secret, skipDecode);
+    convertToBase64Map(transformed as unknown as kind.Secret, skipDecode);
   }
 
   // Compare the original request to the modified request to get the patches

package/src/lib/mutate-request.ts

@@ -1,9 +1,10 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: 2023-Present The Pepr Authors
 
+import { KubernetesObject } from "kubernetes-fluent-client";
 import { clone, mergeDeepRight } from "ramda";
 
-import { KubernetesObject, Operation, Request } from "./k8s/types";
+import { AdmissionRequest, Operation } from "./k8s";
 import { DeepPartial } from "./types";
 
 /**
@@ -13,7 +14,7 @@ import { DeepPartial } from "./types";
 export class PeprMutateRequest<T extends KubernetesObject> {
   Raw: T;
 
-  #input: Request<T>;
+  #input: AdmissionRequest<T>;
 
   get PermitSideEffects() {
     return !this.#input.dryRun;
@@ -47,18 +48,9 @@ export class PeprMutateRequest<T extends KubernetesObject> {
    * Creates a new instance of the action class.
    * @param input - The request object containing the Kubernetes resource to modify.
    */
-  constructor(input: Request<T>) {
+  constructor(input: AdmissionRequest<T>) {
     this.#input = input;
 
-    // Bind public methods
-    this.Merge = this.Merge.bind(this);
-    this.SetLabel = this.SetLabel.bind(this);
-    this.SetAnnotation = this.SetAnnotation.bind(this);
-    this.RemoveLabel = this.RemoveLabel.bind(this);
-    this.RemoveAnnotation = this.RemoveAnnotation.bind(this);
-    this.HasLabel = this.HasLabel.bind(this);
-    this.HasAnnotation = this.HasAnnotation.bind(this);
-
     // If this is a DELETE operation, use the oldObject instead
     if (input.operation.toUpperCase() === Operation.DELETE) {
       this.Raw = clone(input.oldObject as T);
@@ -77,9 +69,9 @@ export class PeprMutateRequest<T extends KubernetesObject> {
    *
    * @param obj - The object to merge with the current resource.
    */
-  Merge(obj: DeepPartial<T>) {
+  Merge = (obj: DeepPartial<T>) => {
     this.Raw = mergeDeepRight(this.Raw, obj) as unknown as T;
-  }
+  };
 
   /**
    * Updates a label on the Kubernetes resource.
@@ -87,7 +79,7 @@ export class PeprMutateRequest<T extends KubernetesObject> {
    * @param value - The value of the label.
    * @returns The current action instance for method chaining.
    */
-  SetLabel(key: string, value: string) {
+  SetLabel = (key: string, value: string) => {
     const ref = this.Raw;
 
     ref.metadata = ref.metadata ?? {};
@@ -95,7 +87,7 @@ export class PeprMutateRequest<T extends KubernetesObject> {
     ref.metadata.labels[key] = value;
 
     return this;
-  }
+  };
 
   /**
    * Updates an annotation on the Kubernetes resource.
@@ -103,7 +95,7 @@ export class PeprMutateRequest<T extends KubernetesObject> {
    * @param value - The value of the annotation.
    * @returns The current action instance for method chaining.
    */
-  SetAnnotation(key: string, value: string) {
+  SetAnnotation = (key: string, value: string) => {
     const ref = this.Raw;
 
     ref.metadata = ref.metadata ?? {};
@@ -111,33 +103,33 @@ export class PeprMutateRequest<T extends KubernetesObject> {
     ref.metadata.annotations[key] = value;
 
     return this;
-  }
+  };
 
   /**
    * Removes a label from the Kubernetes resource.
    * @param key - The key of the label to remove.
    * @returns The current Action instance for method chaining.
    */
-  RemoveLabel(key: string) {
+  RemoveLabel = (key: string) => {
     if (this.Raw.metadata?.labels?.[key]) {
       delete this.Raw.metadata.labels[key];
     }
 
     return this;
-  }
+  };
 
   /**
    * Removes an annotation from the Kubernetes resource.
    * @param key - The key of the annotation to remove.
    * @returns The current Action instance for method chaining.
    */
-  RemoveAnnotation(key: string) {
+  RemoveAnnotation = (key: string) => {
     if (this.Raw.metadata?.annotations?.[key]) {
       delete this.Raw.metadata.annotations[key];
     }
 
     return this;
-  }
+  };
 
   /**
    * Check if a label exists on the Kubernetes resource.
@@ -145,9 +137,9 @@ export class PeprMutateRequest<T extends KubernetesObject> {
    * @param key the label key to check
    * @returns
    */
-  HasLabel(key: string) {
+  HasLabel = (key: string) => {
     return this.Raw.metadata?.labels?.[key] !== undefined;
-  }
+  };
 
   /**
    * Check if an annotation exists on the Kubernetes resource.
@@ -155,7 +147,7 @@ export class PeprMutateRequest<T extends KubernetesObject> {
    * @param key the annotation key to check
    * @returns
    */
-  HasAnnotation(key: string) {
+  HasAnnotation = (key: string) => {
     return this.Raw.metadata?.annotations?.[key] !== undefined;
-  }
+  };
 }

package/src/lib/storage.ts

@@ -0,0 +1,128 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+
+import { clone } from "ramda";
+import Log from "./logger";
+
+export type DataOp = "add" | "remove";
+export type DataStore = Record<string, string>;
+export type DataSender = (op: DataOp, keys: string[], value?: string) => void;
+export type DataReceiver = (data: DataStore) => void;
+export type Unsubscribe = () => void;
+
+export interface PeprStore {
+  /**
+   * Returns the current value associated with the given key, or null if the given key does not exist.
+   */
+  getItem(key: string): string | null;
+  /**
+   * Removes all key/value pairs, if there are any.
+   */
+  clear(): void;
+  /**
+   * Removes the key/value pair with the given key, if a key/value pair with the given key exists.
+   */
+  removeItem(key: string): void;
+  /**
+   * Sets the value of the pair identified by key to value, creating a new key/value pair if none existed for key previously.
+   */
+  setItem(key: string, value: string): void;
+
+  /**
+   * Subscribe to changes in the store. This API behaves similarly to the [Svelte Store API](https://vercel.com/docs/beginner-sveltekit/svelte-stores#using-the-store).
+   *
+   * @param listener - The callback to be invoked when the store changes.
+   * @returns A function to unsubscribe from the listener.
+   */
+  subscribe(listener: DataReceiver): Unsubscribe;
+
+  /**
+   * Register a function to be called when the store is ready.
+   */
+  onReady(callback: DataReceiver): void;
+}
+
+/**
+ * A key-value data store that can be used to persist data that should be shared across Pepr controllers and capabilities.
+ *
+ * The API is similar to the [Storage API](https://developer.mozilla.org/docs/Web/API/Storage)
+ */
+export class Storage implements PeprStore {
+  #store: DataStore = {};
+  #send!: DataSender;
+  #subscribers: Record<number, DataReceiver> = {};
+  #subscriberId = 0;
+  #readyHandlers: DataReceiver[] = [];
+
+  registerSender = (send: DataSender) => {
+    this.#send = send;
+  };
+
+  receive = (data: DataStore) => {
+    Log.debug(data, `Pepr store data received`);
+    this.#store = data || {};
+
+    this.#onReady();
+
+    // Notify all subscribers
+    for (const idx in this.#subscribers) {
+      // Send a unique clone of the store to each subscriber
+      this.#subscribers[idx](clone(this.#store));
+    }
+  };
+
+  getItem = (key: string) => {
+    // Return null if the value is the empty string
+    return this.#store[key] || null;
+  };
+
+  clear = () => {
+    this.#dispatchUpdate("remove", Object.keys(this.#store));
+  };
+
+  removeItem = (key: string) => {
+    this.#dispatchUpdate("remove", [key]);
+  };
+
+  setItem = (key: string, value: string) => {
+    this.#dispatchUpdate("add", [key], value);
+  };
+
+  subscribe = (subscriber: DataReceiver) => {
+    const idx = this.#subscriberId++;
+    this.#subscribers[idx] = subscriber;
+    return () => this.unsubscribe(idx);
+  };
+
+  onReady = (callback: DataReceiver) => {
+    this.#readyHandlers.push(callback);
+  };
+
+  /**
+   * Remove a subscriber from the list of subscribers.
+   * @param idx - The index of the subscriber to remove.
+   */
+  unsubscribe = (idx: number) => {
+    delete this.#subscribers[idx];
+  };
+
+  #onReady = () => {
+    // Notify all ready handlers with a clone of the store
+    for (const handler of this.#readyHandlers) {
+      handler(clone(this.#store));
+    }
+
+    // Make this a noop so that it can't be called again
+    this.#onReady = () => {};
+  };
+
+  /**
+   * Dispatch an update to the store and notify all subscribers.
+   * @param  op - The type of operation to perform.
+   * @param  keys - The keys to update.
+   * @param  [value] - The new value.
+   */
+  #dispatchUpdate = (op: DataOp, keys: string[], value?: string) => {
+    this.#send(op, keys, value);
+  };
+}

package/src/lib/types.ts

@@ -1,15 +1,12 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: 2023-Present The Pepr Authors
 
-import { GroupVersionKind, KubernetesObject, WebhookIgnore } from "./k8s/types";
+import { GenericClass, GroupVersionKind, KubernetesObject } from "kubernetes-fluent-client";
+import { WatchAction } from "kubernetes-fluent-client/dist/fluent/types";
+
 import { PeprMutateRequest } from "./mutate-request";
 import { PeprValidateRequest } from "./validate-request";
 
-export type PackageJSON = {
-  description: string;
-  pepr: ModuleConfig;
-};
-
 /**
  * Recursively make all properties in T optional.
  */
@@ -48,49 +45,6 @@ export interface CapabilityExport extends CapabilityCfg {
   bindings: Binding[];
 }
 
-export type ModuleSigning = {
-  /**
-   * Specifies the signing policy.
-   * "requireAuthorizedKey" - only authorized keys are accepted.
-   * "requireAnyKey" - any key is accepted, as long as it's valid.
-   * "none" - no signing required.
-   */
-  signingPolicy?: "requireAuthorizedKey" | "requireAnyKey" | "none";
-  /**
-   * List of authorized keys for the "requireAuthorizedKey" policy.
-   * These keys are allowed to sign Pepr capabilities.
-   */
-  authorizedKeys?: string[];
-};
-
-/** Global configuration for the Pepr runtime. */
-export type ModuleConfig = {
-  /** The user-defined name for the module */
-  name: string;
-  /** The Pepr version this module uses */
-  peprVersion?: string;
-  /** The user-defined version of the module */
-  appVersion?: string;
-  /** A unique identifier for this Pepr module. This is automatically generated by Pepr. */
-  uuid: string;
-  /** A description of the Pepr module and what it does. */
-  description?: string;
-  /** Reject K8s resource AdmissionRequests on error. */
-  onError?: string;
-  /** Configure global exclusions that will never be processed by Pepr. */
-  alwaysIgnore: WebhookIgnore;
-  /**
-   * FUTURE USE.
-   *
-   * Configure the signing policy for Pepr capabilities.
-   * This setting determines the requirements for signing keys in Pepr.
-   */
-  signing?: ModuleSigning;
-};
-
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export type GenericClass = abstract new () => any;
-
 export type WhenSelector<T extends GenericClass> = {
   /** Register an action to be executed when a Kubernetes resource is created or updated. */
   IsCreatedOrUpdated: () => BindingAll<T>;
@@ -106,6 +60,8 @@ export type Binding = {
   event: Event;
   isMutate?: boolean;
   isValidate?: boolean;
+  isWatch?: boolean;
+  readonly model: GenericClass;
   readonly kind: GroupVersionKind;
   readonly filters: {
     name: string;
@@ -115,6 +71,7 @@ export type Binding = {
   };
   readonly mutateCallback?: MutateAction<GenericClass, InstanceType<GenericClass>>;
   readonly validateCallback?: ValidateAction<GenericClass, InstanceType<GenericClass>>;
+  readonly watchCallback?: WatchAction<GenericClass, InstanceType<GenericClass>>;
 };
 
 export type BindingFilter<T extends GenericClass> = CommonActionChain<T> & {
@@ -170,16 +127,36 @@ export type CommonActionChain<T extends GenericClass> = MutateActionChain<T> & {
   /**
    * Create a new MUTATE action with the specified callback function and previously specified
    * filters.
+   *
+   * @since 0.13.0
+   *
    * @param action The action to be executed when the Kubernetes resource is processed by the AdmissionController.
    */
   Mutate: (action: MutateAction<T, InstanceType<T>>) => MutateActionChain<T>;
 };
 
-export type MutateActionChain<T extends GenericClass> = {
+export type ValidateActionChain<T extends GenericClass> = {
+  /**
+   * Establish a watcher for the specified resource. The callback function will be executed after the admission controller has
+   * processed the resource and the request has been persisted to the cluster.
+   *
+   * **Beta Function**: This method is still in early testing and edge cases may still exist.
+   *
+   * @since 0.14.0
+   *
+   * @param action
+   * @returns
+   */
+  Watch: (action: WatchAction<T, InstanceType<T>>) => void;
+};
+
+export type MutateActionChain<T extends GenericClass> = ValidateActionChain<T> & {
   /**
    * Create a new VALIDATE action with the specified callback function and previously specified
    * filters. Return the `request.Approve()` or `Request.Deny()` methods to approve or deny the request:
    *
+   * @since 0.13.0
+   *
    * @example
    * ```ts
    * When(a.Deployment)
@@ -195,7 +172,7 @@ export type MutateActionChain<T extends GenericClass> = {
    *
    * @param action The action to be executed when the Kubernetes resource is processed by the AdmissionController.
    */
-  Validate: (action: ValidateAction<T, InstanceType<T>>) => void;
+  Validate: (action: ValidateAction<T, InstanceType<T>>) => ValidateActionChain<T>;
 };
 
 export type MutateAction<T extends GenericClass, K extends KubernetesObject = InstanceType<T>> = (
@@ -204,9 +181,9 @@ export type MutateAction<T extends GenericClass, K extends KubernetesObject = In
 
 export type ValidateAction<T extends GenericClass, K extends KubernetesObject = InstanceType<T>> = (
   req: PeprValidateRequest<K>,
-) => Promise<ValidateResponse> | ValidateResponse;
+) => Promise<ValidateActionResponse> | ValidateActionResponse;
 
-export type ValidateResponse = {
+export type ValidateActionResponse = {
   allowed: boolean;
   statusCode?: number;
   statusMessage?: string;

package/src/lib/validate-processor.ts

@@ -1,17 +1,18 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: 2023-Present The Pepr Authors
 
+import { kind } from "kubernetes-fluent-client";
+
 import { Capability } from "./capability";
 import { shouldSkipRequest } from "./filter";
-import { Request, ValidateResponse } from "./k8s/types";
-import { Secret } from "./k8s/upstream";
+import { AdmissionRequest, ValidateResponse } from "./k8s";
 import Log from "./logger";
 import { convertFromBase64Map } from "./utils";
 import { PeprValidateRequest } from "./validate-request";
 
 export async function validateProcessor(
   capabilities: Capability[],
-  req: Request,
+  req: AdmissionRequest,
   reqMetadata: Record<string, string>,
 ): Promise<ValidateResponse> {
   const wrapped = new PeprValidateRequest(req);
@@ -23,7 +24,7 @@ export async function validateProcessor(
   // If the resource is a secret, decode the data
   const isSecret = req.kind.version == "v1" && req.kind.kind == "Secret";
   if (isSecret) {
-    convertFromBase64Map(wrapped.Raw as unknown as Secret);
+    convertFromBase64Map(wrapped.Raw as unknown as kind.Secret);
   }
 
   Log.info(reqMetadata, `Processing validation request`);