pepr 0.0.0-development

package/src/lib/module.ts

@@ -0,0 +1,136 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+import { clone } from "ramda";
+import { Capability } from "./capability";
+import { Controller } from "./controller";
+import { ValidateError } from "./errors";
+import { AdmissionRequest, MutateResponse, ValidateResponse, WebhookIgnore } from "./k8s";
+import { CapabilityExport } from "./types";
+import { setupWatch } from "./watch-processor";
+import { Log } from "../lib";
+
+/** Custom Labels Type for package.json */
+export interface CustomLabels {
+  namespace?: Record<string, string>;
+}
+/** Global configuration for the Pepr runtime. */
+export type ModuleConfig = {
+  /** 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;
+  /** The webhookTimeout */
+  webhookTimeout?: number;
+  /** 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;
+  /** Propagate env variables to in-cluster controllers */
+  env?: Record<string, string>;
+  /** Custom Labels for Kubernetes Objects */
+  customLabels?: CustomLabels;
+};
+
+export type PackageJSON = {
+  description: string;
+  pepr: ModuleConfig;
+};
+
+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: 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;
+
+  /**
+   * Create a new Pepr runtime
+   *
+   * @param config The configuration for the Pepr runtime
+   * @param capabilities The capabilities to be loaded into the Pepr runtime
+   * @param opts Options for the Pepr runtime
+   */
+  constructor({ description, pepr }: PackageJSON, capabilities: Capability[] = [], opts: PeprModuleOptions = {}) {
+    const config: ModuleConfig = clone(pepr);
+    config.description = description;
+
+    // Need to validate at runtime since TS gets sad about parsing the package.json
+    ValidateError(config.onError);
+
+    // Handle build mode
+    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
+      for (const capability of capabilities) {
+        // Convert the capability to a capability config
+        exportedCapabilities.push({
+          name: capability.name,
+          description: capability.description,
+          namespaces: capability.namespaces,
+          bindings: capability.bindings,
+          hasSchedule: capability.hasSchedule,
+        });
+      }
+
+      // Send the capabilities back to the parent process
+      process.send(exportedCapabilities);
+
+      return;
+    }
+
+    this.#controller = new Controller(config, capabilities, opts.beforeHook, opts.afterHook, () => {
+      // Wait for the controller to be ready before setting up watches
+      if (isWatchMode() || isDevMode()) {
+        try {
+          setupWatch(capabilities);
+        } catch (e) {
+          Log.error(e, "Error setting up watch");
+          process.exit(1);
+        }
+      }
+    });
+
+    // Stop processing if deferStart is set to true
+    if (opts.deferStart) {
+      return;
+    }
+
+    this.start();
+  }
+
+  /**
+   * Start the Pepr runtime manually.
+   * Normally this is called automatically when the Pepr module is instantiated, but can be called manually if `deferStart` is set to `true` in the constructor.
+   *
+   * @param port
+   */
+  start = (port = 3000) => {
+    this.#controller.startServer(port);
+  };
+}

package/src/lib/mutate-processor.ts

@@ -0,0 +1,160 @@
+// SPDX-License-Identifier: Apache-2.0
+// 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, AdmissionRequest } from "./k8s";
+import Log from "./logger";
+import { ModuleConfig } from "./module";
+import { PeprMutateRequest } from "./mutate-request";
+import { base64Encode, convertFromBase64Map, convertToBase64Map } from "./utils";
+
+export async function mutateProcessor(
+  config: ModuleConfig,
+  capabilities: Capability[],
+  req: AdmissionRequest,
+  reqMetadata: Record<string, string>,
+): Promise<MutateResponse> {
+  const wrapped = new PeprMutateRequest(req);
+  const response: MutateResponse = {
+    uid: req.uid,
+    warnings: [],
+    allowed: false,
+  };
+
+  // Track whether any capability matched the request
+  let matchedAction = false;
+
+  // Track data fields that should be skipped during decoding
+  let skipDecode: string[] = [];
+
+  // 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 kind.Secret);
+  }
+
+  Log.info(reqMetadata, `Processing request`);
+
+  for (const { name, bindings, namespaces } of capabilities) {
+    const actionMetadata = { ...reqMetadata, name };
+
+    for (const action of bindings) {
+      // Skip this action if it's not a mutate action
+      if (!action.mutateCallback) {
+        continue;
+      }
+
+      // Continue to the next action without doing anything if this one should be skipped
+      if (shouldSkipRequest(action, req, namespaces)) {
+        continue;
+      }
+
+      const label = action.mutateCallback.name;
+      Log.info(actionMetadata, `Processing mutation action (${label})`);
+
+      matchedAction = true;
+
+      // Add annotations to the request to indicate that the capability started processing
+      // this will allow tracking of failed mutations that were permitted to continue
+      const updateStatus = (status: string) => {
+        // Only update the status if the request is a CREATE or UPDATE (we don't use CONNECT)
+        if (req.operation == "DELETE") {
+          return;
+        }
+
+        const identifier = `${config.uuid}.pepr.dev/${name}`;
+        wrapped.Raw.metadata = wrapped.Raw.metadata || {};
+        wrapped.Raw.metadata.annotations = wrapped.Raw.metadata.annotations || {};
+        wrapped.Raw.metadata.annotations[identifier] = status;
+      };
+
+      updateStatus("started");
+
+      try {
+        // Run the action
+        await action.mutateCallback(wrapped);
+
+        Log.info(actionMetadata, `Mutation action succeeded (${label})`);
+
+        // Add annotations to the request to indicate that the capability succeeded
+        updateStatus("succeeded");
+      } catch (e) {
+        updateStatus("warning");
+        response.warnings = response.warnings || [];
+
+        let errorMessage = "";
+
+        try {
+          if (e.message && e.message !== "[object Object]") {
+            errorMessage = e.message;
+          } else {
+            throw new Error("An error occurred in the mutate action.");
+          }
+        } catch (e) {
+          errorMessage = "An error occurred with the mutate action.";
+        }
+
+        Log.error(actionMetadata, `Action failed: ${errorMessage}`);
+        response.warnings.push(`Action failed: ${errorMessage}`);
+
+        switch (config.onError) {
+          case Errors.reject:
+            Log.error(actionMetadata, `Action failed: ${errorMessage}`);
+            response.result = "Pepr module configured to reject on error";
+            return response;
+
+          case Errors.audit:
+            response.auditAnnotations = response.auditAnnotations || {};
+            response.auditAnnotations[Date.now()] = `Action failed: ${errorMessage}`;
+            break;
+        }
+      }
+    }
+  }
+
+  // If we've made it this far, the request is allowed
+  response.allowed = true;
+
+  // If no capability matched the request, exit early
+  if (!matchedAction) {
+    Log.info(reqMetadata, `No matching actions found`);
+    return response;
+  }
+
+  // delete operations can't be mutate, just return before the transformation
+  if (req.operation == "DELETE") {
+    return response;
+  }
+
+  const transformed = wrapped.Raw;
+
+  // Post-process the Secret requests to convert it back to the original format
+  if (isSecret) {
+    convertToBase64Map(transformed as unknown as kind.Secret, skipDecode);
+  }
+
+  // Compare the original request to the modified request to get the patches
+  const patches = jsonPatch.compare(req.object, transformed);
+
+  // Only add the patch if there are patches to apply
+  if (patches.length > 0) {
+    response.patchType = "JSONPatch";
+    // Webhook must be base64-encoded
+    // https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/#response
+    response.patch = base64Encode(JSON.stringify(patches));
+  }
+
+  // Remove the warnings array if it's empty
+  if (response.warnings && response.warnings.length < 1) {
+    delete response.warnings;
+  }
+
+  Log.debug({ ...reqMetadata, patches }, `Patches generated`);
+
+  return response;
+}

package/src/lib/mutate-request.ts

@@ -0,0 +1,153 @@
+// 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 { AdmissionRequest, Operation } from "./k8s";
+import { DeepPartial } from "./types";
+
+/**
+ * The RequestWrapper class provides methods to modify Kubernetes objects in the context
+ * of a mutating webhook request.
+ */
+export class PeprMutateRequest<T extends KubernetesObject> {
+  Raw: T;
+
+  #input: AdmissionRequest<T>;
+
+  get PermitSideEffects() {
+    return !this.#input.dryRun;
+  }
+
+  /**
+   * Indicates whether the request is a dry run.
+   * @returns true if the request is a dry run, false otherwise.
+   */
+  get IsDryRun() {
+    return this.#input.dryRun;
+  }
+
+  /**
+   * Provides access to the old resource in the request if available.
+   * @returns The old Kubernetes resource object or null if not available.
+   */
+  get OldResource() {
+    return this.#input.oldObject;
+  }
+
+  /**
+   * Provides access to the request object.
+   * @returns The request object containing the Kubernetes resource.
+   */
+  get Request() {
+    return this.#input;
+  }
+
+  /**
+   * Creates a new instance of the action class.
+   * @param input - The request object containing the Kubernetes resource to modify.
+   */
+  constructor(input: AdmissionRequest<T>) {
+    this.#input = input;
+
+    // If this is a DELETE operation, use the oldObject instead
+    if (input.operation.toUpperCase() === Operation.DELETE) {
+      this.Raw = clone(input.oldObject as T);
+    } else {
+      // Otherwise, use the incoming object
+      this.Raw = clone(input.object);
+    }
+
+    if (!this.Raw) {
+      throw new Error("unable to load the request object into PeprRequest.RawP");
+    }
+  }
+
+  /**
+   * Deep merges the provided object with the current resource.
+   *
+   * @param obj - The object to merge with the current resource.
+   */
+  Merge = (obj: DeepPartial<T>) => {
+    this.Raw = mergeDeepRight(this.Raw, obj) as unknown as T;
+  };
+
+  /**
+   * Updates a label on the Kubernetes resource.
+   * @param key - The key of the label to update.
+   * @param value - The value of the label.
+   * @returns The current action instance for method chaining.
+   */
+  SetLabel = (key: string, value: string) => {
+    const ref = this.Raw;
+
+    ref.metadata = ref.metadata ?? {};
+    ref.metadata.labels = ref.metadata.labels ?? {};
+    ref.metadata.labels[key] = value;
+
+    return this;
+  };
+
+  /**
+   * Updates an annotation on the Kubernetes resource.
+   * @param key - The key of the annotation to update.
+   * @param value - The value of the annotation.
+   * @returns The current action instance for method chaining.
+   */
+  SetAnnotation = (key: string, value: string) => {
+    const ref = this.Raw;
+
+    ref.metadata = ref.metadata ?? {};
+    ref.metadata.annotations = ref.metadata.annotations ?? {};
+    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) => {
+    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) => {
+    if (this.Raw.metadata?.annotations?.[key]) {
+      delete this.Raw.metadata.annotations[key];
+    }
+
+    return this;
+  };
+
+  /**
+   * Check if a label exists on the Kubernetes resource.
+   *
+   * @param key the label key to check
+   * @returns
+   */
+  HasLabel = (key: string) => {
+    return this.Raw.metadata?.labels?.[key] !== undefined;
+  };
+
+  /**
+   * Check if an annotation exists on the Kubernetes resource.
+   *
+   * @param key the annotation key to check
+   * @returns
+   */
+  HasAnnotation = (key: string) => {
+    return this.Raw.metadata?.annotations?.[key] !== undefined;
+  };
+}

package/src/lib/queue.ts

@@ -0,0 +1,89 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+import { KubernetesObject } from "@kubernetes/client-node";
+import { WatchPhase } from "kubernetes-fluent-client/dist/fluent/types";
+import Log from "./logger";
+
+type QueueItem<K extends KubernetesObject> = {
+  item: K;
+  type: WatchPhase;
+  resolve: (value: void | PromiseLike<void>) => void;
+  reject: (reason?: string) => void;
+};
+
+/**
+ * Queue is a FIFO queue for reconciling
+ */
+export class Queue<K extends KubernetesObject> {
+  #queue: QueueItem<K>[] = [];
+  #pendingPromise = false;
+  #reconcile?: (obj: KubernetesObject, type: WatchPhase) => Promise<void>;
+
+  constructor() {
+    this.#reconcile = async () => await new Promise(resolve => resolve());
+  }
+
+  setReconcile(reconcile: (obj: KubernetesObject, type: WatchPhase) => Promise<void>) {
+    this.#reconcile = reconcile;
+  }
+
+  /**
+   * Enqueue adds an item to the queue and returns a promise that resolves when the item is
+   * reconciled.
+   *
+   * @param item The object to 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}`);
+    return new Promise<void>((resolve, reject) => {
+      this.#queue.push({ item, type, resolve, reject });
+      return this.#dequeue();
+    });
+  }
+
+  /**
+   * Dequeue reconciles the next item in the queue
+   *
+   * @returns A promise that resolves when the webapp is reconciled
+   */
+  async #dequeue() {
+    // If there is a pending promise, do nothing
+    if (this.#pendingPromise) {
+      Log.debug("Pending promise, not dequeuing");
+      return false;
+    }
+
+    // Take the next element from the queue
+    const element = this.#queue.shift();
+
+    // If there is no element, do nothing
+    if (!element) {
+      Log.debug("No element, not dequeuing");
+      return false;
+    }
+
+    try {
+      // Set the pending promise flag to avoid concurrent reconciliations
+      this.#pendingPromise = true;
+
+      // Reconcile the element
+      if (this.#reconcile) {
+        Log.debug(`Reconciling ${element.item.metadata!.name}`);
+        await this.#reconcile(element.item, element.type);
+      }
+
+      element.resolve();
+    } catch (e) {
+      Log.debug(`Error reconciling ${element.item.metadata!.name}`, { error: e });
+      element.reject(e);
+    } finally {
+      // Reset the pending promise flag
+      Log.debug("Resetting pending promise and dequeuing");
+      this.#pendingPromise = false;
+
+      // After the element is reconciled, dequeue the next element
+      await this.#dequeue();
+    }
+  }
+}

package/src/lib/schedule.ts

@@ -0,0 +1,175 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+
+import { PeprStore } from "./storage";
+
+type Unit = "seconds" | "second" | "minute" | "minutes" | "hours" | "hour";
+
+export interface Schedule {
+  /**
+   * * The name of the store
+   */
+  name: string;
+  /**
+   * The value associated with a unit of time
+   */
+  every: number;
+  /**
+   * The unit of time
+   */
+  unit: Unit;
+  /**
+   * The code to run
+   */
+  run: () => void;
+  /**
+   * The start time of the schedule
+   */
+  startTime?: Date | undefined;
+
+  /**
+   * The number of times the schedule has run
+   */
+  completions?: number | undefined;
+  /**
+   * Tje intervalID to clear the interval
+   */
+  intervalID?: NodeJS.Timeout;
+}
+
+export class OnSchedule implements Schedule {
+  intervalId: NodeJS.Timeout | null = null;
+  store: PeprStore | undefined;
+  name!: string;
+  completions?: number | undefined;
+  every: number;
+  unit: Unit;
+  run!: () => void;
+  startTime?: Date | undefined;
+  duration: number | undefined;
+  lastTimestamp: Date | undefined;
+
+  constructor(schedule: Schedule) {
+    this.name = schedule.name;
+    this.run = schedule.run;
+    this.every = schedule.every;
+    this.unit = schedule.unit;
+    this.startTime = schedule?.startTime;
+    this.completions = schedule?.completions;
+  }
+  setStore(store: PeprStore) {
+    this.store = store;
+    this.startInterval();
+  }
+  startInterval() {
+    this.checkStore();
+    this.getDuration();
+    this.setupInterval();
+  }
+  /**
+   * Checks the store for this schedule and sets the values if it exists
+   * @returns
+   */
+  checkStore() {
+    const result = this.store && this.store.getItem(this.name);
+    if (result) {
+      const storedSchedule = JSON.parse(result);
+      this.completions = storedSchedule?.completions;
+      this.startTime = storedSchedule?.startTime;
+      this.lastTimestamp = storedSchedule?.lastTimestamp;
+    }
+  }
+
+  /**
+   * Saves the schedule to the store
+   * @returns
+   */
+  saveToStore() {
+    const schedule = {
+      completions: this.completions,
+      startTime: this.startTime,
+      lastTimestamp: new Date(),
+      name: this.name,
+    };
+    this.store && this.store.setItem(this.name, JSON.stringify(schedule));
+  }
+
+  /**
+   * Gets the durations in milliseconds
+   */
+  getDuration() {
+    switch (this.unit) {
+      case "seconds":
+        if (this.every < 10) throw new Error("10 Seconds in the smallest interval allowed");
+        this.duration = 1000 * this.every;
+        break;
+      case "minutes":
+      case "minute":
+        this.duration = 1000 * 60 * this.every;
+        break;
+      case "hours":
+      case "hour":
+        this.duration = 1000 * 60 * 60 * this.every;
+        break;
+      default:
+        throw new Error("Invalid time unit");
+    }
+  }
+
+  /**
+   * Sets up the interval
+   */
+  setupInterval() {
+    const now = new Date();
+    let delay: number | undefined;
+
+    if (this.lastTimestamp && this.startTime) {
+      this.startTime = undefined;
+    }
+
+    if (this.startTime) {
+      delay = this.startTime.getTime() - now.getTime();
+    } else if (this.lastTimestamp && this.duration) {
+      const lastTimestamp = new Date(this.lastTimestamp);
+      delay = this.duration - (now.getTime() - lastTimestamp.getTime());
+    }
+
+    if (delay === undefined || delay <= 0) {
+      this.start();
+    } else {
+      setTimeout(() => {
+        this.start();
+      }, delay);
+    }
+  }
+
+  /**
+   * Starts the interval
+   */
+  start() {
+    this.intervalId = setInterval(() => {
+      if (this.completions === 0) {
+        this.stop();
+        return;
+      } else {
+        this.run();
+
+        if (this.completions && this.completions !== 0) {
+          this.completions -= 1;
+        }
+        this.saveToStore();
+      }
+    }, this.duration);
+  }
+
+  /**
+   * Stops the interval
+   */
+  stop() {
+    if (this.intervalId) {
+      clearInterval(this.intervalId);
+      this.intervalId = null;
+    }
+    this.store && this.store.removeItem(this.name);
+  }
+}