pepr 0.2.9 → 0.3.0-rc0

package/src/lib/logger.ts

@@ -0,0 +1,136 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+
+/**
+ * Enumeration representing different logging levels.
+ */
+export enum LogLevel {
+  debug = 0,
+  info = 1,
+  warn = 2,
+  error = 3,
+}
+
+enum ConsoleColors {
+  Reset = "\x1b[0m",
+  Bright = "\x1b[1m",
+  Dim = "\x1b[2m",
+  Underscore = "\x1b[4m",
+  Blink = "\x1b[5m",
+  Reverse = "\x1b[7m",
+  Hidden = "\x1b[8m",
+
+  FgBlack = "\x1b[30m",
+  FgRed = "\x1b[31m",
+  FgGreen = "\x1b[32m",
+  FgYellow = "\x1b[33m",
+  FgBlue = "\x1b[34m",
+  FgMagenta = "\x1b[35m",
+  FgCyan = "\x1b[36m",
+  FgWhite = "\x1b[37m",
+
+  BgBlack = "\x1b[40m",
+  BgRed = "\x1b[41m",
+  BgGreen = "\x1b[42m",
+  BgYellow = "\x1b[43m",
+  BgBlue = "\x1b[44m",
+  BgMagenta = "\x1b[45m",
+  BgCyan = "\x1b[46m",
+  BgWhite = "\x1b[47m",
+}
+
+/**
+ * Simple logger class that logs messages at different log levels.
+ */
+export class Logger {
+  private _logLevel: LogLevel;
+
+  /**
+   * Create a new logger instance.
+   * @param logLevel - The minimum log level to log messages for.
+   */
+  constructor(logLevel: LogLevel) {
+    this._logLevel = logLevel;
+  }
+
+  /**
+   * Change the log level of the logger.
+   * @param logLevel - The log level to log the message at.
+   */
+  public SetLogLevel(logLevel: string): void {
+    this._logLevel = LogLevel[logLevel as keyof typeof LogLevel];
+    this.debug(`Log level set to ${logLevel}`);
+  }
+
+  /**
+   * Log a debug message.
+   * @param message - The message to log.
+   */
+  public debug<T>(message: T, prefix?: string): void {
+    this.log(LogLevel.debug, message, prefix);
+  }
+
+  /**
+   * Log an info message.
+   * @param message - The message to log.
+   */
+  public info<T>(message: T, prefix?: string): void {
+    this.log(LogLevel.info, message, prefix);
+  }
+
+  /**
+   * Log a warning message.
+   * @param message - The message to log.
+   */
+  public warn<T>(message: T, prefix?: string): void {
+    this.log(LogLevel.warn, message, prefix);
+  }
+
+  /**
+   * Log an error message.
+   * @param message - The message to log.
+   */
+  public error<T>(message: T, prefix?: string): void {
+    this.log(LogLevel.error, message, prefix);
+  }
+
+  /**
+   * Log a message at the specified log level.
+   * @param logLevel - The log level of the message.
+   * @param message - The message to log.
+   */
+  private log<T>(logLevel: LogLevel, message: T, callerPrefix = ""): void {
+    const color = {
+      [LogLevel.debug]: ConsoleColors.FgBlack,
+      [LogLevel.info]: ConsoleColors.FgCyan,
+      [LogLevel.warn]: ConsoleColors.FgYellow,
+      [LogLevel.error]: ConsoleColors.FgRed,
+    };
+
+    if (logLevel >= this._logLevel) {
+      // Prefix the message with the colored log level.
+      let prefix = "[" + LogLevel[logLevel] + "]\t" + callerPrefix;
+
+      prefix = this.colorize(prefix, color[logLevel]);
+
+      // If the message is not a string, use the debug method to log the object.
+      if (typeof message !== "string") {
+        console.log(prefix);
+        console.debug("%o", message);
+      } else {
+        console.log(prefix + "\t" + message);
+      }
+    }
+  }
+
+  private colorize(text: string, color: ConsoleColors): string {
+    return color + text + ConsoleColors.Reset;
+  }
+}
+
+/** Log is an instance of Logger used to generate log entries. */
+const Log = new Logger(LogLevel.info);
+if (process.env.LOG_LEVEL) {
+  Log.SetLogLevel(process.env.LOG_LEVEL);
+}
+export default Log;

package/src/lib/module.ts

@@ -0,0 +1,63 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+
+import R from "ramda";
+import { Capability } from "./capability";
+import { Controller } from "./controller";
+import { Request, Response } from "./k8s/types";
+import { ModuleConfig } from "./types";
+
+const alwaysIgnore = {
+  namespaces: ["kube-system", "pepr-system"],
+  labels: [{ "pepr.dev": "ignore" }],
+};
+
+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: Request) => void;
+
+  /** A user-defined callback to post-process or intercept a Pepr response just before it is returned to K8s */
+  afterHook?: (res: Response) => void;
+};
+
+export class PeprModule {
+  private _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 _deferStart (optional) If set to `true`, the Pepr runtime will not be started automatically. This can be used to start the Pepr runtime manually with `start()`.
+   */
+  constructor({ description, pepr }: PackageJSON, capabilities: Capability[] = [], opts: PeprModuleOptions = {}) {
+    const config: ModuleConfig = R.mergeDeepWith(R.concat, pepr, alwaysIgnore);
+    config.description = description;
+
+    this._controller = new Controller(config, capabilities, opts.beforeHook, opts.afterHook);
+
+    // 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/processor.ts

@@ -0,0 +1,98 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+
+import { compare } from "fast-json-patch";
+import { Capability } from "./capability";
+import { shouldSkipRequest } from "./filter";
+import { Request, Response } from "./k8s/types";
+import logger from "./logger";
+import { PeprRequest } from "./request";
+import { ModuleConfig } from "./types";
+
+export async function processor(config: ModuleConfig, capabilities: Capability[], req: Request): Promise<Response> {
+  const wrapped = new PeprRequest(req);
+  const response: Response = {
+    uid: req.uid,
+    warnings: [],
+    allowed: false,
+  };
+
+  logger.info(`Processing '${req.uid}' for '${req.kind.kind}' '${req.name}'`);
+
+  for (const { name, bindings } of capabilities) {
+    const prefix = `${req.uid} ${req.name}: ${name}`;
+    logger.info(`Processing capability ${name}`, prefix);
+
+    for (const action of bindings) {
+      // Continue to the next action without doing anything if this one should be skipped
+      if (shouldSkipRequest(action, req)) {
+        continue;
+      }
+
+      logger.info(`Processing matched action ${action.kind.kind}`, prefix);
+
+      // 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.callback(wrapped);
+
+        logger.info(`Action succeeded`, prefix);
+
+        // Add annotations to the request to indicate that the capability succeeded
+        updateStatus("succeeded");
+      } catch (e) {
+        // Annoying ts false positive
+        response.warnings = response.warnings || [];
+        response.warnings.push(`Action failed: ${e}`);
+
+        // If errors are not allowed, note the failure in the Response
+        if (config.onError) {
+          logger.error(`Action failed: ${e}`, prefix);
+          response.result = "Pepr module configured to reject on error";
+          return response;
+        } else {
+          logger.warn(`Action failed: ${e}`, prefix);
+          updateStatus("warning");
+        }
+      }
+    }
+  }
+
+  // If we've made it this far, the request is allowed
+  response.allowed = true;
+
+  // Compare the original request to the modified request to get the patches
+  const patches = compare(req.object, wrapped.Raw);
+
+  // 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 = Buffer.from(JSON.stringify(patches)).toString("base64");
+  }
+
+  // Remove the warnings array if it's empty
+  if (response.warnings && response.warnings.length < 1) {
+    delete response.warnings;
+  }
+
+  logger.debug(patches);
+
+  return response;
+}

package/src/lib/request.ts

@@ -0,0 +1,140 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+
+import R from "ramda";
+import { KubernetesObject, Request } 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 PeprRequest<T extends KubernetesObject> {
+  private _input: Request<T>;
+
+  public Raw: 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: Request<T>) {
+    // Deep clone the object to prevent mutation of the original object
+    this.Raw = R.clone(input.object);
+    // Store the input
+    this._input = input;
+  }
+
+  /**
+   * 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 = R.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/types.ts

@@ -0,0 +1,211 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+
+import { GroupVersionKind, KubernetesObject, WebhookIgnore } from "./k8s";
+import { PeprRequest } from "./request";
+
+/**
+ * The behavior of this module when an error occurs.
+ */
+export enum ErrorBehavior {
+  ignore = "ignore",
+  audit = "audit",
+  reject = "reject",
+}
+
+/**
+ * The phase of the Kubernetes admission webhook that the capability is registered for.
+ *
+ * Currently only `mutate` is supported.
+ */
+export enum HookPhase {
+  mutate = "mutate",
+  validate = "validate",
+}
+
+/**
+ * Recursively make all properties in T optional.
+ */
+export type DeepPartial<T> = {
+  [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
+};
+
+/**
+ * The type of Kubernetes mutating webhook event that the capability action is registered for.
+ */
+
+export enum Event {
+  Create = "CREATE",
+  Update = "UPDATE",
+  Delete = "DELETE",
+  CreateOrUpdate = "CREATEORUPDATE",
+}
+
+export interface CapabilityCfg {
+  /**
+   * The name of the capability. This should be unique.
+   */
+  name: string;
+  /**
+   * A description of the capability and what it does.
+   */
+  description: string;
+  /**
+   * List of namespaces that this capability applies to, if empty, applies to all namespaces (cluster-wide).
+   * This does not supersede the `alwaysIgnore` global configuration.
+   */
+  namespaces?: string[];
+
+  /**
+   * FUTURE USE.
+   *
+   * Declare if this capability should be used for mutation or validation. Currently this is not used
+   * and everything is considered a mutation.
+   */
+  mutateOrValidate?: HookPhase;
+}
+
+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 version of Pepr that the module was originally generated with */
+  version?: 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: ErrorBehavior | 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 a capability action to be executed when a Kubernetes resource is created or updated. */
+  IsCreatedOrUpdated: () => BindingAll<T>;
+  /** Register a capability action to be executed when a Kubernetes resource is created. */
+  IsCreated: () => BindingAll<T>;
+  /** Register a capability action to be executed when a Kubernetes resource is updated. */
+  IsUpdated: () => BindingAll<T>;
+  /** Register a capability action to be executed when a Kubernetes resource is deleted. */
+  IsDeleted: () => BindingAll<T>;
+};
+
+export type Binding = {
+  event?: Event;
+  readonly kind: GroupVersionKind;
+  readonly filters: {
+    name: string;
+    namespaces: string[];
+    labels: Record<string, string>;
+    annotations: Record<string, string>;
+  };
+  readonly callback: CapabilityAction<GenericClass, InstanceType<GenericClass>>;
+};
+
+export type BindingFilter<T extends GenericClass> = BindToActionOrSet<T> & {
+  /**
+   * Only apply the capability action if the resource has the specified label. If no value is specified, the label must exist.
+   * Note multiple calls to this method will result in an AND condition. e.g.
+   *
+   * ```ts
+   * When(a.Deployment)
+   *   .IsCreated()
+   *   .WithLabel("foo", "bar")
+   *   .WithLabel("baz", "qux")
+   *   .Then(...)
+   * ```
+   *
+   * Will only apply the capability action if the resource has both the `foo=bar` and `baz=qux` labels.
+   *
+   * @param key
+   * @param value
+   */
+  WithLabel: (key: string, value?: string) => BindingFilter<T>;
+  /**
+   * Only apply the capability action if the resource has the specified annotation. If no value is specified, the annotation must exist.
+   * Note multiple calls to this method will result in an AND condition. e.g.
+   *
+   * ```ts
+   * When(a.Deployment)
+   *   .IsCreated()
+   *   .WithAnnotation("foo", "bar")
+   *   .WithAnnotation("baz", "qux")
+   *   .Then(...)
+   * ```
+   *
+   * Will only apply the capability action if the resource has both the `foo=bar` and `baz=qux` annotations.
+   *
+   * @param key
+   * @param value
+   */
+  WithAnnotation: (key: string, value?: string) => BindingFilter<T>;
+};
+
+export type BindingWithName<T extends GenericClass> = BindingFilter<T> & {
+  /** Only apply the capability action if the resource name matches the specified name. */
+  WithName: (name: string) => BindingFilter<T>;
+};
+
+export type BindingAll<T extends GenericClass> = BindingWithName<T> & {
+  /** Only apply the capability action if the resource is in one of the specified namespaces.*/
+  InNamespace: (...namespaces: string[]) => BindingFilter<T>;
+};
+
+export type BindToAction<T extends GenericClass> = {
+  /**
+   * Create a new capability action with the specified callback function and previously specified
+   * filters.
+   * @param action The capability action to be executed when the Kubernetes resource is processed by the AdmissionController.
+   */
+  Then: (action: CapabilityAction<T, InstanceType<T>>) => BindToAction<T>;
+};
+
+export type BindToActionOrSet<T extends GenericClass> = BindToAction<T> & {
+  /**
+   * Merge the specified updates into the resource, this can only be used once per binding.
+   * Note this is just a convenience method for `request.Merge(values)`.
+   *
+   * Example change the `minReadySeconds` to 3 of a deployment when it is created:
+   *
+   * ```ts
+   * When(a.Deployment)
+   *  .IsCreated()
+   *  .ThenSet({ spec: { minReadySeconds: 3 } });
+   * ```
+   *
+   * @param merge
+   * @returns
+   */
+  ThenSet: (val: DeepPartial<InstanceType<T>>) => BindToAction<T>;
+};
+
+export type CapabilityAction<T extends GenericClass, K extends KubernetesObject = InstanceType<T>> = (
+  req: PeprRequest<K>
+) => Promise<void> | void | Promise<PeprRequest<K>> | PeprRequest<K>;

package/dist/cli.d.ts

@@ -1,2 +0,0 @@
-#!/usr/bin/env node
-import "./src/cli";

package/dist/cli.js

@@ -1,4 +0,0 @@
-#!/usr/bin/env node
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-require("./src/cli");

package/dist/run.d.ts

@@ -1,2 +0,0 @@
-#!/usr/bin/env node
-import "./src/cli/run";

package/dist/run.js

@@ -1,4 +0,0 @@
-#!/usr/bin/env node
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-require("./src/cli/run");