pepr 0.12.2 → 0.13.1

package/src/lib/capability.ts

@@ -1,62 +1,60 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: 2023-Present The Pepr Authors
 
-import { modelToGroupVersionKind } from "./k8s/index";
+import { pickBy } from "ramda";
+
+import { isWatchMode, modelToGroupVersionKind } from "./k8s/index";
 import { GroupVersionKind } from "./k8s/types";
-import logger from "./logger";
+import Log from "./logger";
 import {
-  BindToAction,
   Binding,
   BindingFilter,
   BindingWithName,
-  CapabilityAction,
   CapabilityCfg,
-  DeepPartial,
+  CapabilityExport,
   Event,
   GenericClass,
-  HookPhase,
+  MutateAction,
+  MutateActionChain,
+  ValidateAction,
   WhenSelector,
 } from "./types";
 
 /**
  * A capability is a unit of functionality that can be registered with the Pepr runtime.
  */
-export class Capability implements CapabilityCfg {
-  private _name: string;
-  private _description: string;
-  private _namespaces?: string[] | undefined;
-
-  // Currently everything is considered a mutation
-  private _mutateOrValidate = HookPhase.mutate;
-
-  private _bindings: Binding[] = [];
-
-  get bindings(): Binding[] {
-    return this._bindings;
+export class Capability implements CapabilityExport {
+  #name: string;
+  #description: string;
+  #namespaces?: string[] | undefined;
+  #bindings: Binding[] = [];
+
+  get bindings() {
+    return this.#bindings;
   }
 
   get name() {
-    return this._name;
+    return this.#name;
   }
 
   get description() {
-    return this._description;
+    return this.#description;
   }
 
   get namespaces() {
-    return this._namespaces || [];
-  }
-
-  get mutateOrValidate() {
-    return this._mutateOrValidate;
+    return this.#namespaces || [];
   }
 
   constructor(cfg: CapabilityCfg) {
-    this._name = cfg.name;
-    this._description = cfg.description;
-    this._namespaces = cfg.namespaces;
-    logger.info(`Capability ${this._name} registered`);
-    logger.debug(cfg);
+    this.#name = cfg.name;
+    this.#description = cfg.description;
+    this.#namespaces = cfg.namespaces;
+
+    // Bind When() to this instance
+    this.When = this.When.bind(this);
+
+    Log.info(`Capability ${this.#name} registered`);
+    Log.debug(cfg);
   }
 
   /**
@@ -68,7 +66,7 @@ export class Capability implements CapabilityCfg {
    * @param kind if using a custom KubernetesObject not available in `a.*`, specify the GroupVersionKind
    * @returns
    */
-  When = <T extends GenericClass>(model: T, kind?: GroupVersionKind): WhenSelector<T> => {
+  When<T extends GenericClass>(model: T, kind?: GroupVersionKind): WhenSelector<T> {
     const matchedKind = modelToGroupVersionKind(model.name);
 
     // If the kind is not specified and the model is not a KubernetesObject, throw an error
@@ -86,69 +84,83 @@ export class Capability implements CapabilityCfg {
         labels: {},
         annotations: {},
       },
-      callback: () => undefined,
     };
 
-    const prefix = `${this._name}: ${model.name}`;
+    const bindings = this.#bindings;
+    const prefix = `${this.#name}: ${model.name}`;
+    const commonChain = { WithLabel, WithAnnotation, Mutate, Validate };
+    const isNotEmpty = (value: object) => Object.keys(value).length > 0;
+    const log = (message: string, cbString: string) => {
+      const filteredObj = pickBy(isNotEmpty, binding.filters);
 
-    logger.info(`Binding created`, prefix);
+      Log.info(`${message} configured for ${binding.event}`, prefix);
+      Log.info(filteredObj, prefix);
+      Log.debug(cbString, prefix);
+    };
 
-    const Then = (cb: CapabilityAction<T>): BindToAction<T> => {
-      logger.info(`Binding action created`, prefix);
-      logger.debug(cb.toString(), prefix);
-      // Push the binding to the list of bindings for this capability as a new BindingAction
-      // with the callback function to preserve
-      this._bindings.push({
-        ...binding,
-        callback: cb,
-      });
+    function Validate(validateCallback: ValidateAction<T>): void {
+      if (!isWatchMode) {
+        log("Validate Action", validateCallback.toString());
+
+        // Push the binding to the list of bindings for this capability as a new BindingAction
+        // with the callback function to preserve
+        bindings.push({
+          ...binding,
+          isValidate: true,
+          validateCallback,
+        });
+      }
+    }
 
-      // Now only allow adding actions to the same binding
-      return { Then };
-    };
+    function Mutate(mutateCallback: MutateAction<T>): MutateActionChain<T> {
+      if (!isWatchMode) {
+        log("Mutate Action", mutateCallback.toString());
 
-    const ThenSet = (merge: DeepPartial<InstanceType<T>>): BindToAction<T> => {
-      // Add the new action to the binding
-      Then(req => req.Merge(merge));
+        // Push the binding to the list of bindings for this capability as a new BindingAction
+        // with the callback function to preserve
+        bindings.push({
+          ...binding,
+          isMutate: true,
+          mutateCallback,
+        });
+      }
 
-      return { Then };
-    };
+      // Now only allow adding actions to the same binding
+      return { Validate };
+    }
 
     function InNamespace(...namespaces: string[]): BindingWithName<T> {
-      logger.debug(`Add namespaces filter ${namespaces}`, prefix);
+      Log.debug(`Add namespaces filter ${namespaces}`, prefix);
       binding.filters.namespaces.push(...namespaces);
-      return { WithLabel, WithAnnotation, WithName, Then, ThenSet };
+      return { ...commonChain, WithName };
     }
 
     function WithName(name: string): BindingFilter<T> {
-      logger.debug(`Add name filter ${name}`, prefix);
+      Log.debug(`Add name filter ${name}`, prefix);
       binding.filters.name = name;
-      return { WithLabel, WithAnnotation, Then, ThenSet };
+      return commonChain;
     }
 
     function WithLabel(key: string, value = ""): BindingFilter<T> {
-      logger.debug(`Add label filter ${key}=${value}`, prefix);
+      Log.debug(`Add label filter ${key}=${value}`, prefix);
       binding.filters.labels[key] = value;
-      return { WithLabel, WithAnnotation, Then, ThenSet };
+      return commonChain;
     }
 
-    const WithAnnotation = (key: string, value = ""): BindingFilter<T> => {
-      logger.debug(`Add annotation filter ${key}=${value}`, prefix);
+    function WithAnnotation(key: string, value = ""): BindingFilter<T> {
+      Log.debug(`Add annotation filter ${key}=${value}`, prefix);
       binding.filters.annotations[key] = value;
-      return { WithLabel, WithAnnotation, Then, ThenSet };
-    };
+      return commonChain;
+    }
 
-    const bindEvent = (event: Event) => {
+    function bindEvent(event: Event) {
       binding.event = event;
       return {
+        ...commonChain,
         InNamespace,
-        Then,
-        ThenSet,
-        WithAnnotation,
-        WithLabel,
         WithName,
       };
-    };
+    }
 
     return {
       IsCreatedOrUpdated: () => bindEvent(Event.CreateOrUpdate),
@@ -156,5 +168,5 @@ export class Capability implements CapabilityCfg {
       IsUpdated: () => bindEvent(Event.Update),
       IsDeleted: () => bindEvent(Event.Delete),
     };
-  };
+  }
 }

package/src/lib/controller.ts

@@ -1,58 +1,73 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: 2023-Present The Pepr Authors
 
-import express from "express";
+import express, { NextFunction } from "express";
 import fs from "fs";
 import https from "https";
 
 import { Capability } from "./capability";
-import { Request, Response } from "./k8s/types";
+import { isWatchMode } from "./k8s";
+import { MutateResponse, Request, ValidateResponse } from "./k8s/types";
 import Log from "./logger";
-import { processor } from "./processor";
-import { ModuleConfig } from "./types";
 import { MetricsCollector } from "./metrics";
+import { mutateProcessor } from "./mutate-processor";
+import { ModuleConfig } from "./types";
+import { validateProcessor } from "./validate-processor";
 
 export class Controller {
-  private readonly app = express();
-  private running = false;
-  private metricsCollector = new MetricsCollector("pepr");
+  // Track whether the server is running
+  #running = false;
+
+  // Metrics collector
+  #metricsCollector = new MetricsCollector("pepr");
 
   // The token used to authenticate requests
-  private token = "";
+  #token = "";
+
+  // The express app instance
+  readonly #app = express();
+
+  // Initialized with the constructor
+  readonly #config: ModuleConfig;
+  readonly #capabilities: Capability[];
+  readonly #beforeHook?: (req: Request) => void;
+  readonly #afterHook?: (res: MutateResponse) => void;
 
   constructor(
-    private readonly config: ModuleConfig,
-    private readonly capabilities: Capability[],
-    private readonly beforeHook?: (req: Request) => void,
-    private readonly afterHook?: (res: Response) => void
+    config: ModuleConfig,
+    capabilities: Capability[],
+    beforeHook?: (req: Request) => void,
+    afterHook?: (res: MutateResponse) => void,
   ) {
-    // Middleware for logging requests
-    this.app.use(this.logger);
-
-    // Middleware for parsing JSON, limit to 2mb vs 100K for K8s compatibility
-    this.app.use(express.json({ limit: "2mb" }));
+    this.#config = config;
+    this.#capabilities = capabilities;
+    this.#beforeHook = beforeHook;
+    this.#afterHook = afterHook;
 
-    // Health check endpoint
-    this.app.get("/healthz", this.healthz);
+    // Bind public methods
+    this.startServer = this.startServer.bind(this);
 
-    // Metrics endpoint
-    this.app.get("/metrics", this.metrics);
+    // Middleware for logging requests
+    this.#app.use(Controller.#logger);
 
-    // Mutate endpoint
-    this.app.post("/mutate/:token", this.mutate);
+    // Middleware for parsing JSON, limit to 2mb vs 100K for K8s compatibility
+    this.#app.use(express.json({ limit: "2mb" }));
 
     if (beforeHook) {
-      console.info(`Using beforeHook: ${beforeHook}`);
+      Log.info(`Using beforeHook: ${beforeHook}`);
     }
 
     if (afterHook) {
-      console.info(`Using afterHook: ${afterHook}`);
+      Log.info(`Using afterHook: ${afterHook}`);
     }
+
+    // Bind endpoints
+    this.#bindEndpoints();
   }
 
   /** Start the webhook server */
-  public startServer = (port: number) => {
-    if (this.running) {
+  startServer(port: number) {
+    if (this.#running) {
       throw new Error("Cannot start Pepr module: Pepr module was not instantiated with deferStart=true");
     }
 
@@ -62,29 +77,32 @@ export class Controller {
       cert: fs.readFileSync(process.env.SSL_CERT_PATH || "/etc/certs/tls.crt"),
     };
 
-    // Get the API token from the environment variable or the mounted secret
-    this.token = process.env.PEPR_API_TOKEN || fs.readFileSync("/app/api-token/value").toString().trim();
-    console.info(`Using API token: ${this.token}`);
+    // Get the API token if not in watch mode
+    if (!isWatchMode) {
+      // Get the API token from the environment variable or the mounted secret
+      this.#token = process.env.PEPR_API_TOKEN || fs.readFileSync("/app/api-token/value").toString().trim();
+      Log.info(`Using API token: ${this.#token}`);
 
-    if (!this.token) {
-      throw new Error("API token not found");
+      if (!this.#token) {
+        throw new Error("API token not found");
+      }
     }
 
     // Create HTTPS server
-    const server = https.createServer(options, this.app).listen(port);
+    const server = https.createServer(options, this.#app).listen(port);
 
     // Handle server listening event
     server.on("listening", () => {
-      console.log(`Server listening on port ${port}`);
+      Log.info(`Server listening on port ${port}`);
       // Track that the server is running
-      this.running = true;
+      this.#running = true;
     });
 
     // Handle EADDRINUSE errors
     server.on("error", (e: { code: string }) => {
       if (e.code === "EADDRINUSE") {
-        console.log(
-          `Address in use, retrying in 2 seconds. If this persists, ensure ${port} is not in use, e.g. "lsof -i :${port}"`
+        Log.warn(
+          `Address in use, retrying in 2 seconds. If this persists, ensure ${port} is not in use, e.g. "lsof -i :${port}"`,
         );
         setTimeout(() => {
           server.close();
@@ -95,92 +113,174 @@ export class Controller {
 
     // Listen for the SIGTERM signal and gracefully close the server
     process.on("SIGTERM", () => {
-      console.log("Received SIGTERM, closing server");
+      Log.info("Received SIGTERM, closing server");
       server.close(() => {
-        console.log("Server closed");
+        Log.info("Server closed");
         process.exit(0);
       });
     });
-  };
+  }
 
-  private logger = (req: express.Request, res: express.Response, next: express.NextFunction) => {
-    const startTime = Date.now();
+  #bindEndpoints = () => {
+    // Health check endpoint
+    this.#app.get("/healthz", Controller.#healthz);
 
-    res.on("finish", () => {
-      const now = new Date().toISOString();
-      const elapsedTime = Date.now() - startTime;
-      const message = `[${now}] ${req.method} ${req.originalUrl} [${res.statusCode}] ${elapsedTime} ms\n`;
+    // Metrics endpoint
+    this.#app.get("/metrics", this.#metrics);
 
-      res.statusCode >= 400 ? console.error(message) : console.info(message);
-    });
+    if (isWatchMode) {
+      return;
+    }
 
-    next();
+    // Require auth for webhook endpoints
+    this.#app.use(["/mutate/:token", "/validate/:token"], this.#validateToken);
+
+    // Mutate endpoint
+    this.#app.post("/mutate/:token", this.#admissionReq("Mutate"));
+
+    // Validate endpoint
+    this.#app.post("/validate/:token", this.#admissionReq("Validate"));
   };
 
-  private healthz = (req: express.Request, res: express.Response) => {
-    try {
-      res.send("OK");
-    } catch (err) {
-      console.error(err);
-      res.status(500).send("Internal Server Error");
+  /**
+   * Validate the token in the request path
+   *
+   * @param req The incoming request
+   * @param res The outgoing response
+   * @param next The next middleware function
+   * @returns
+   */
+  #validateToken = (req: express.Request, res: express.Response, next: NextFunction) => {
+    // Validate the token
+    const { token } = req.params;
+    if (token !== this.#token) {
+      const err = `Unauthorized: invalid token '${token.replace(/[^\w]/g, "_")}'`;
+      Log.warn(err);
+      res.status(401).send(err);
+      this.#metricsCollector.alert();
+      return;
     }
+
+    // Token is valid, continue
+    next();
   };
 
-  private metrics = async (req: express.Request, res: express.Response) => {
+  /**
+   * Metrics endpoint handler
+   *
+   * @param req the incoming request
+   * @param res the outgoing response
+   */
+  #metrics = async (req: express.Request, res: express.Response) => {
     try {
-      res.send(await this.metricsCollector.getMetrics());
+      res.send(await this.#metricsCollector.getMetrics());
     } catch (err) {
-      console.error(err);
+      Log.error(err);
       res.status(500).send("Internal Server Error");
     }
   };
 
-  private mutate = async (req: express.Request, res: express.Response) => {
-    const startTime = this.metricsCollector.observeStart();
-
-    try {
-      // Validate the token
-      const { token } = req.params;
-      if (token !== this.token) {
-        const err = `Unauthorized: invalid token '${token.replace(/[^\w]/g, "_")}'`;
-        console.warn(err);
-        res.status(401).send(err);
-        this.metricsCollector.alert();
-        return;
+  /**
+   * Admission request handler for both mutate and validate requests
+   *
+   * @param admissionKind the type of admission request
+   * @returns the request handler
+   */
+  #admissionReq = (admissionKind: "Mutate" | "Validate") => {
+    // Create the admission request handler
+    return async (req: express.Request, res: express.Response) => {
+      // Start the metrics timer
+      const startTime = this.#metricsCollector.observeStart();
+
+      try {
+        // Get the request from the body or create an empty request
+        const request: Request = req.body?.request || ({} as Request);
+
+        // Run the before hook if it exists
+        this.#beforeHook && this.#beforeHook(request || {});
+
+        // Setup identifiers for logging
+        const name = request?.name ? `/${request.name}` : "";
+        const namespace = request?.namespace || "";
+        const gvk = request?.kind || { group: "", version: "", kind: "" };
+
+        const reqMetadata = {
+          uid: request.uid,
+          namespace,
+          name,
+        };
+
+        Log.info({ ...reqMetadata, gvk, operation: request.operation, admissionKind }, "Incoming request");
+        Log.debug({ ...reqMetadata, request }, "Incoming request body");
+
+        // Process the request
+        let response: MutateResponse | ValidateResponse;
+
+        // Call mutate or validate based on the admission kind
+        if (admissionKind === "Mutate") {
+          response = await mutateProcessor(this.#config, this.#capabilities, request, reqMetadata);
+        } else {
+          response = await validateProcessor(this.#capabilities, request, reqMetadata);
+        }
+
+        // Run the after hook if it exists
+        this.#afterHook && this.#afterHook(response);
+
+        // Log the response
+        Log.debug({ ...reqMetadata, response }, "Outgoing response");
+
+        // Send a no prob bob response
+        res.send({
+          apiVersion: "admission.k8s.io/v1",
+          kind: "AdmissionReview",
+          response,
+        });
+        this.#metricsCollector.observeEnd(startTime, admissionKind);
+      } catch (err) {
+        Log.error(err);
+        res.status(500).send("Internal Server Error");
+        this.#metricsCollector.error();
       }
+    };
+  };
 
-      const request: Request = req.body?.request || ({} as Request);
-
-      // Run the before hook if it exists
-      this.beforeHook && this.beforeHook(request || {});
-
-      const name = request?.name ? `/${request.name}` : "";
-      const namespace = request?.namespace || "";
-      const gvk = request?.kind || { group: "", version: "", kind: "" };
-      const prefix = `${request.uid} ${namespace}${name}`;
-
-      Log.info(`Mutate [${request.operation}] ${gvk.group}/${gvk.version}/${gvk.kind}`, prefix);
-
-      // Process the request
-      const response = await processor(this.config, this.capabilities, request, prefix);
-
-      // Run the after hook if it exists
-      this.afterHook && this.afterHook(response);
+  /**
+   * Middleware for logging requests
+   *
+   * @param req the incoming request
+   * @param res the outgoing response
+   * @param next the next middleware function
+   */
+  static #logger(req: express.Request, res: express.Response, next: express.NextFunction) {
+    const startTime = Date.now();
 
-      // Log the response
-      Log.debug(response, prefix);
+    res.on("finish", () => {
+      const elapsedTime = Date.now() - startTime;
+      const message = {
+        uid: req.body?.request?.uid,
+        method: req.method,
+        url: req.originalUrl,
+        status: res.statusCode,
+        duration: `${elapsedTime} ms`,
+      };
+
+      res.statusCode >= 300 ? Log.warn(message) : Log.info(message);
+    });
 
-      // Send a no prob bob response
-      res.send({
-        apiVersion: "admission.k8s.io/v1",
-        kind: "AdmissionReview",
-        response,
-      });
-      this.metricsCollector.observeEnd(startTime);
+    next();
+  }
+  /**
+   * Health check endpoint handler
+   *
+   * @param req the incoming request
+   * @param res the outgoing response
+   */
+  static #healthz(req: express.Request, res: express.Response) {
+    try {
+      res.send("OK");
     } catch (err) {
-      console.error(err);
+      Log.error(err);
       res.status(500).send("Internal Server Error");
-      this.metricsCollector.error();
     }
-  };
+  }
 }

package/src/lib/errors.ts

@@ -0,0 +1,20 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+
+export const Errors = {
+  audit: "audit",
+  ignore: "ignore",
+  reject: "reject",
+};
+
+export const ErrorList = Object.values(Errors);
+
+/**
+ * Validate the error or throw an error
+ * @param error
+ */
+export function ValidateError(error = "") {
+  if (!ErrorList.includes(error)) {
+    throw new Error(`Invalid error: ${error}. Must be one of: ${ErrorList.join(", ")}`);
+  }
+}

package/src/lib/fetch.ts

@@ -30,7 +30,7 @@ export type FetchResponse<T> = {
 export async function fetch<T>(url: URL | RequestInfo, init?: RequestInit): Promise<FetchResponse<T>> {
   let data = undefined as unknown as T;
   try {
-    logger.debug(`Fetching ${url}`);
+    logger.debug(init, `Fetching ${url}`);
 
     const resp = await fetchRaw(url, init);
     const contentType = resp.headers.get("content-type") || "";

package/src/lib/filter.ts

@@ -8,7 +8,7 @@ import { Binding, Event } from "./types";
 /**
  * shouldSkipRequest determines if a request should be skipped based on the binding filters.
  *
- * @param binding the capability action binding
+ * @param binding the action binding
  * @param req the incoming request
  * @returns
  */
@@ -20,8 +20,6 @@ export function shouldSkipRequest(binding: Binding, req: Request) {
   const srcObject = operation === Operation.DELETE ? req.oldObject : req.object;
   const { metadata } = srcObject || {};
 
-  console.log(metadata);
-
   // Test for matching operation
   if (!binding.event.includes(operation) && !binding.event.includes(Event.Any)) {
     return true;

package/src/lib/k8s/index.ts

@@ -3,9 +3,12 @@
 
 // Export kinds as a single object
 import * as kind from "./upstream";
-/** a is a collection of K8s types to be used within a CapabilityAction: `When(a.Configmap)` */
+/** a is a collection of K8s types to be used within a action: `When(a.Configmap)` */
 export { kind as a };
 
 export { modelToGroupVersionKind, gvkMap, RegisterKind } from "./kinds";
 
+// If the hostname is pepr-static-test-watcher-0, then we are running in watch mode
+export const isWatchMode = process.env.PEPR_WATCH_MODE === "true";
+
 export * from "./types";