pepr 0.13.0 → 0.13.1

package/src/lib/capability.ts

@@ -11,6 +11,7 @@ import {
   BindingFilter,
   BindingWithName,
   CapabilityCfg,
+  CapabilityExport,
   Event,
   GenericClass,
   MutateAction,
@@ -22,35 +23,37 @@ import {
 /**
  * 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;
-
-  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 || [];
+    return this.#namespaces || [];
   }
 
   constructor(cfg: CapabilityCfg) {
-    this._name = cfg.name;
-    this._description = cfg.description;
-    this._namespaces = cfg.namespaces;
+    this.#name = cfg.name;
+    this.#description = cfg.description;
+    this.#namespaces = cfg.namespaces;
 
-    Log.info(`Capability ${this._name} registered`);
+    // Bind When() to this instance
+    this.When = this.When.bind(this);
+
+    Log.info(`Capability ${this.#name} registered`);
     Log.debug(cfg);
   }
 
@@ -63,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
@@ -83,8 +86,9 @@ export class Capability implements CapabilityCfg {
       },
     };
 
-    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);
@@ -94,27 +98,27 @@ export class Capability implements CapabilityCfg {
       Log.debug(cbString, prefix);
     };
 
-    const Validate = (validateCallback: ValidateAction<T>): void => {
+    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
-        this._bindings.push({
+        bindings.push({
           ...binding,
           isValidate: true,
           validateCallback,
         });
       }
-    };
+    }
 
-    const Mutate = (mutateCallback: MutateAction<T>): MutateActionChain<T> => {
+    function Mutate(mutateCallback: MutateAction<T>): MutateActionChain<T> {
       if (!isWatchMode) {
         log("Mutate Action", mutateCallback.toString());
 
         // Push the binding to the list of bindings for this capability as a new BindingAction
         // with the callback function to preserve
-        this._bindings.push({
+        bindings.push({
           ...binding,
           isMutate: true,
           mutateCallback,
@@ -123,7 +127,7 @@ export class Capability implements CapabilityCfg {
 
       // Now only allow adding actions to the same binding
       return { Validate };
-    };
+    }
 
     function InNamespace(...namespaces: string[]): BindingWithName<T> {
       Log.debug(`Add namespaces filter ${namespaces}`, prefix);
@@ -143,22 +147,20 @@ export class Capability implements CapabilityCfg {
       return commonChain;
     }
 
-    const WithAnnotation = (key: string, value = ""): BindingFilter<T> => {
+    function WithAnnotation(key: string, value = ""): BindingFilter<T> {
       Log.debug(`Add annotation filter ${key}=${value}`, prefix);
       binding.filters.annotations[key] = value;
       return commonChain;
-    };
-
-    const commonChain = { WithLabel, WithAnnotation, Mutate, Validate };
+    }
 
-    const bindEvent = (event: Event) => {
+    function bindEvent(event: Event) {
       binding.event = event;
       return {
         ...commonChain,
         InNamespace,
         WithName,
       };
-    };
+    }
 
     return {
       IsCreatedOrUpdated: () => bindEvent(Event.CreateOrUpdate),
@@ -166,5 +168,5 @@ export class Capability implements CapabilityCfg {
       IsUpdated: () => bindEvent(Event.Update),
       IsDeleted: () => bindEvent(Event.Delete),
     };
-  };
+  }
 }

package/src/lib/controller.ts

@@ -15,61 +15,59 @@ 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: MutateResponse) => void,
+    config: ModuleConfig,
+    capabilities: Capability[],
+    beforeHook?: (req: Request) => void,
+    afterHook?: (res: MutateResponse) => void,
   ) {
+    this.#config = config;
+    this.#capabilities = capabilities;
+    this.#beforeHook = beforeHook;
+    this.#afterHook = afterHook;
+
+    // Bind public methods
+    this.startServer = this.startServer.bind(this);
+
     // Middleware for logging requests
-    this._app.use(this.logger);
+    this.#app.use(Controller.#logger);
 
     // Middleware for parsing JSON, limit to 2mb vs 100K for K8s compatibility
-    this._app.use(express.json({ limit: "2mb" }));
+    this.#app.use(express.json({ limit: "2mb" }));
 
-    if (_beforeHook) {
-      Log.info(`Using beforeHook: ${_beforeHook}`);
+    if (beforeHook) {
+      Log.info(`Using beforeHook: ${beforeHook}`);
     }
 
-    if (_afterHook) {
-      Log.info(`Using afterHook: ${_afterHook}`);
+    if (afterHook) {
+      Log.info(`Using afterHook: ${afterHook}`);
     }
 
     // Bind endpoints
-    this.bindEndpoints();
+    this.#bindEndpoints();
   }
 
-  private bindEndpoints = () => {
-    // Health check endpoint
-    this._app.get("/healthz", this.healthz);
-
-    // Metrics endpoint
-    this._app.get("/metrics", this.metrics);
-
-    if (isWatchMode) {
-      return;
-    }
-
-    // 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"));
-  };
-
   /** 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");
     }
 
@@ -82,22 +80,22 @@ export class Controller {
     // 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}`);
+      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) {
+      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", () => {
       Log.info(`Server listening on port ${port}`);
       // Track that the server is running
-      this._running = true;
+      this.#running = true;
     });
 
     // Handle EADDRINUSE errors
@@ -121,32 +119,27 @@ export class Controller {
         process.exit(0);
       });
     });
-  };
+  }
 
-  /**
-   * Middleware for logging requests
-   *
-   * @param req the incoming request
-   * @param res the outgoing response
-   * @param next the next middleware function
-   */
-  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 elapsedTime = Date.now() - startTime;
-      const message = {
-        uid: req.body?.request?.uid,
-        method: req.method,
-        url: req.originalUrl,
-        status: res.statusCode,
-        duration: `${elapsedTime} ms`,
-      };
+    // Metrics endpoint
+    this.#app.get("/metrics", this.#metrics);
 
-      res.statusCode >= 300 ? Log.warn(message) : Log.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"));
   };
 
   /**
@@ -157,14 +150,14 @@ export class Controller {
    * @param next The next middleware function
    * @returns
    */
-  private validateToken = (req: express.Request, res: express.Response, next: NextFunction) => {
+  #validateToken = (req: express.Request, res: express.Response, next: NextFunction) => {
     // Validate the token
     const { token } = req.params;
-    if (token !== this._token) {
+    if (token !== this.#token) {
       const err = `Unauthorized: invalid token '${token.replace(/[^\w]/g, "_")}'`;
       Log.warn(err);
       res.status(401).send(err);
-      this.metricsCollector.alert();
+      this.#metricsCollector.alert();
       return;
     }
 
@@ -172,30 +165,15 @@ export class Controller {
     next();
   };
 
-  /**
-   * Health check endpoint handler
-   *
-   * @param req the incoming request
-   * @param res the outgoing response
-   */
-  private healthz = (req: express.Request, res: express.Response) => {
-    try {
-      res.send("OK");
-    } catch (err) {
-      Log.error(err);
-      res.status(500).send("Internal Server Error");
-    }
-  };
-
   /**
    * Metrics endpoint handler
    *
    * @param req the incoming request
    * @param res the outgoing response
    */
-  private metrics = async (req: express.Request, res: express.Response) => {
+  #metrics = async (req: express.Request, res: express.Response) => {
     try {
-      res.send(await this.metricsCollector.getMetrics());
+      res.send(await this.#metricsCollector.getMetrics());
     } catch (err) {
       Log.error(err);
       res.status(500).send("Internal Server Error");
@@ -208,18 +186,18 @@ export class Controller {
    * @param admissionKind the type of admission request
    * @returns the request handler
    */
-  private admissionReq = (admissionKind: "Mutate" | "Validate") => {
+  #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();
+      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 || {});
+        this.#beforeHook && this.#beforeHook(request || {});
 
         // Setup identifiers for logging
         const name = request?.name ? `/${request.name}` : "";
@@ -240,13 +218,13 @@ export class Controller {
 
         // Call mutate or validate based on the admission kind
         if (admissionKind === "Mutate") {
-          response = await mutateProcessor(this._config, this._capabilities, request, reqMetadata);
+          response = await mutateProcessor(this.#config, this.#capabilities, request, reqMetadata);
         } else {
-          response = await validateProcessor(this._capabilities, request, reqMetadata);
+          response = await validateProcessor(this.#capabilities, request, reqMetadata);
         }
 
         // Run the after hook if it exists
-        this._afterHook && this._afterHook(response);
+        this.#afterHook && this.#afterHook(response);
 
         // Log the response
         Log.debug({ ...reqMetadata, response }, "Outgoing response");
@@ -257,12 +235,52 @@ export class Controller {
           kind: "AdmissionReview",
           response,
         });
-        this.metricsCollector.observeEnd(startTime, admissionKind);
+        this.#metricsCollector.observeEnd(startTime, admissionKind);
       } catch (err) {
         Log.error(err);
         res.status(500).send("Internal Server Error");
-        this.metricsCollector.error();
+        this.#metricsCollector.error();
       }
     };
   };
+
+  /**
+   * 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();
+
+    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);
+    });
+
+    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) {
+      Log.error(err);
+      res.status(500).send("Internal Server 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/k8s/types.ts

@@ -144,7 +144,11 @@ export interface MutateResponse {
   /** The type of Patch. Currently we only allow "JSONPatch". */
   patchType?: "JSONPatch";
 
-  /** AuditAnnotations is an unstructured key value map set by remote admission controller (e.g. error=image-blacklisted). */
+  /**
+   * AuditAnnotations is an unstructured key value map set by remote admission controller (e.g. error=image-blacklisted).
+   *
+   * See https://kubernetes.io/docs/reference/labels-annotations-taints/audit-annotations/ for more information
+   */
   auditAnnotations?: {
     [key: string]: string;
   };

package/src/lib/metrics.ts

@@ -1,8 +1,10 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: 2023-Present The Pepr Authors
 
-import promClient, { Counter, Summary, Registry } from "prom-client";
+/* eslint-disable class-methods-use-this */
+
 import { performance } from "perf_hooks";
+import promClient, { Counter, Registry, Summary } from "prom-client";
 import Log from "./logger";
 
 const loggingPrefix = "MetricsCollector";
@@ -24,12 +26,12 @@ interface MetricArgs {
  * MetricsCollector class handles metrics collection using prom-client and performance hooks.
  */
 export class MetricsCollector {
-  private _registry: Registry;
-  private _counters: Map<string, Counter<string>> = new Map();
-  private _summaries: Map<string, Summary<string>> = new Map();
-  private _prefix: string;
+  #registry: Registry;
+  #counters: Map<string, Counter<string>> = new Map();
+  #summaries: Map<string, Summary<string>> = new Map();
+  #prefix: string;
 
-  private _metricNames: MetricNames = {
+  #metricNames: MetricNames = {
     errors: "errors",
     alerts: "alerts",
     mutate: "Mutate",
@@ -38,67 +40,78 @@ export class MetricsCollector {
 
   /**
    * Creates a MetricsCollector instance with prefixed metrics.
-   * @param {string} [prefix='pepr'] - The prefix for the metric names.
+   * @param [prefix='pepr'] - The prefix for the metric names.
    */
   constructor(prefix = "pepr") {
-    this._registry = new Registry();
-    this._prefix = prefix;
-    this.addCounter(this._metricNames.errors, "Mutation/Validate errors encountered");
-    this.addCounter(this._metricNames.alerts, "Mutation/Validate bad api token received");
-    this.addSummary(this._metricNames.mutate, "Mutation operation summary");
-    this.addSummary(this._metricNames.validate, "Validation operation summary");
+    this.#registry = new Registry();
+    this.#prefix = prefix;
+    this.addCounter(this.#metricNames.errors, "Mutation/Validate errors encountered");
+    this.addCounter(this.#metricNames.alerts, "Mutation/Validate bad api token received");
+    this.addSummary(this.#metricNames.mutate, "Mutation operation summary");
+    this.addSummary(this.#metricNames.validate, "Validation operation summary");
   }
-  private getMetricName(name: string) {
-    return `${this._prefix}_${name}`;
+
+  #getMetricName(name: string) {
+    return `${this.#prefix}_${name}`;
   }
 
-  private 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))) {
+    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),
+      name: this.#getMetricName(name),
       help,
-      registers: [this._registry],
+      registers: [this.#registry],
     });
-    collection.set(this.getMetricName(name), metric);
+
+    collection.set(this.#getMetricName(name), metric);
   }
 
   addCounter(name: string, help: string) {
-    this.addMetric(this._counters, promClient.Counter, name, help);
+    this.#addMetric(this.#counters, promClient.Counter, name, help);
   }
 
   addSummary(name: string, help: string) {
-    this.addMetric(this._summaries, promClient.Summary, name, help);
+    this.#addMetric(this.#summaries, promClient.Summary, name, help);
   }
 
   incCounter(name: string) {
-    this._counters.get(this.getMetricName(name))?.inc();
+    this.#counters.get(this.#getMetricName(name))?.inc();
   }
 
   /**
    * Increments the error counter.
    */
   error() {
-    this.incCounter(this._metricNames.errors);
+    this.incCounter(this.#metricNames.errors);
   }
 
   /**
    * Increments the alerts counter.
    */
   alert() {
-    this.incCounter(this._metricNames.alerts);
+    this.incCounter(this.#metricNames.alerts);
   }
 
   /**
    * Returns the current timestamp from performance.now() method. Useful for start timing an operation.
-   * @returns {number} The timestamp.
+   * @returns The timestamp.
    */
   observeStart() {
     return performance.now();
@@ -106,18 +119,18 @@ export class MetricsCollector {
 
   /**
    * Observes the duration since the provided start time and updates the summary.
-   * @param {number} startTime - The start time.
-   * @param {string} name - The metrics summary to increment.
+   * @param startTime - The start time.
+   * @param name - The metrics summary to increment.
    */
-  observeEnd(startTime: number, name: string = this._metricNames.mutate) {
-    this._summaries.get(this.getMetricName(name))?.observe(performance.now() - startTime);
+  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 {Promise<string>} The metrics.
+   * @returns The metrics.
    */
   async getMetrics() {
-    return this._registry.metrics();
+    return this.#registry.metrics();
   }
 }