pepr 0.12.2 → 0.13.0

package/src/lib/types.ts

@@ -2,22 +2,14 @@
 // SPDX-FileCopyrightText: 2023-Present The Pepr Authors
 
 import { GroupVersionKind, KubernetesObject, WebhookIgnore } from "./k8s/types";
-import { PeprRequest } from "./request";
+import { PeprMutateRequest } from "./mutate-request";
+import { PeprValidateRequest } from "./validate-request";
 
 export type PackageJSON = {
   description: string;
   pepr: ModuleConfig;
 };
 
-/**
- * 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.
  *
@@ -36,9 +28,8 @@ export type DeepPartial<T> = {
 };
 
 /**
- * The type of Kubernetes mutating webhook event that the capability action is registered for.
+ * The type of Kubernetes mutating webhook event that the action is registered for.
  */
-
 export enum Event {
   Create = "CREATE",
   Update = "UPDATE",
@@ -61,14 +52,6 @@ export interface CapabilityCfg {
    * 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 = {
@@ -99,7 +82,7 @@ export type ModuleConfig = {
   /** A description of the Pepr module and what it does. */
   description?: string;
   /** Reject K8s resource AdmissionRequests on error. */
-  onError: ErrorBehavior | string;
+  onError?: string;
   /** Configure global exclusions that will never be processed by Pepr. */
   alwaysIgnore: WebhookIgnore;
   /**
@@ -115,18 +98,20 @@ export type ModuleConfig = {
 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. */
+  /** Register an 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. */
+  /** Register an 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. */
+  /** Register ann 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. */
+  /** Register an action to be executed when a Kubernetes resource is deleted. */
   IsDeleted: () => BindingAll<T>;
 };
 
 export type Binding = {
   event: Event;
+  isMutate?: boolean;
+  isValidate?: boolean;
   readonly kind: GroupVersionKind;
   readonly filters: {
     name: string;
@@ -134,12 +119,13 @@ export type Binding = {
     labels: Record<string, string>;
     annotations: Record<string, string>;
   };
-  readonly callback: CapabilityAction<GenericClass, InstanceType<GenericClass>>;
+  readonly mutateCallback?: MutateAction<GenericClass, InstanceType<GenericClass>>;
+  readonly validateCallback?: ValidateAction<GenericClass, InstanceType<GenericClass>>;
 };
 
-export type BindingFilter<T extends GenericClass> = BindToActionOrSet<T> & {
+export type BindingFilter<T extends GenericClass> = CommonActionChain<T> & {
   /**
-   * Only apply the capability action if the resource has the specified label. If no value is specified, the label must exist.
+   * Only apply the 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
@@ -147,17 +133,17 @@ export type BindingFilter<T extends GenericClass> = BindToActionOrSet<T> & {
    *   .IsCreated()
    *   .WithLabel("foo", "bar")
    *   .WithLabel("baz", "qux")
-   *   .Then(...)
+   *   .Mutate(...)
    * ```
    *
-   * Will only apply the capability action if the resource has both the `foo=bar` and `baz=qux` labels.
+   * Will only apply the 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.
+   * Only apply the 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
@@ -165,10 +151,10 @@ export type BindingFilter<T extends GenericClass> = BindToActionOrSet<T> & {
    *   .IsCreated()
    *   .WithAnnotation("foo", "bar")
    *   .WithAnnotation("baz", "qux")
-   *   .Then(...)
+   *   .Mutate(...)
    * ```
    *
-   * Will only apply the capability action if the resource has both the `foo=bar` and `baz=qux` annotations.
+   * Will only apply the action if the resource has both the `foo=bar` and `baz=qux` annotations.
    *
    * @param key
    * @param value
@@ -177,43 +163,57 @@ export type BindingFilter<T extends GenericClass> = BindToActionOrSet<T> & {
 };
 
 export type BindingWithName<T extends GenericClass> = BindingFilter<T> & {
-  /** Only apply the capability action if the resource name matches the specified name. */
+  /** Only apply the 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.*/
+  /** Only apply the action if the resource is in one of the specified namespaces.*/
   InNamespace: (...namespaces: string[]) => BindingWithName<T>;
 };
 
-export type BindToAction<T extends GenericClass> = {
+export type CommonActionChain<T extends GenericClass> = MutateActionChain<T> & {
   /**
-   * Create a new capability action with the specified callback function and previously specified
+   * Create a new MUTATE 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.
+   * @param action The action to be executed when the Kubernetes resource is processed by the AdmissionController.
    */
-  Then: (action: CapabilityAction<T, InstanceType<T>>) => BindToAction<T>;
+  Mutate: (action: MutateAction<T, InstanceType<T>>) => MutateActionChain<T>;
 };
 
-export type BindToActionOrSet<T extends GenericClass> = BindToAction<T> & {
+export type MutateActionChain<T extends GenericClass> = {
   /**
-   * 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:
+   * 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:
    *
+   * @example
    * ```ts
    * When(a.Deployment)
    *  .IsCreated()
-   *  .ThenSet({ spec: { minReadySeconds: 3 } });
+   *  .Validate(request => {
+   *    if (request.HasLabel("foo")) {
+   *     return request.Approve();
+   *    }
+   *
+   *   return request.Deny("Deployment must have label foo");
+   * });
    * ```
    *
-   * @param merge
-   * @returns
+   * @param action The action to be executed when the Kubernetes resource is processed by the AdmissionController.
    */
-  ThenSet: (val: DeepPartial<InstanceType<T>>) => BindToAction<T>;
+  Validate: (action: ValidateAction<T, InstanceType<T>>) => void;
 };
 
-export type CapabilityAction<T extends GenericClass, K extends KubernetesObject = InstanceType<T>> = (
-  req: PeprRequest<K>
-) => Promise<void> | void | Promise<PeprRequest<K>> | PeprRequest<K>;
+export type MutateAction<T extends GenericClass, K extends KubernetesObject = InstanceType<T>> = (
+  req: PeprMutateRequest<K>,
+) => Promise<void> | void | Promise<PeprMutateRequest<K>> | PeprMutateRequest<K>;
+
+export type ValidateAction<T extends GenericClass, K extends KubernetesObject = InstanceType<T>> = (
+  req: PeprValidateRequest<K>,
+) => Promise<ValidateResponse> | ValidateResponse;
+
+export type ValidateResponse = {
+  allowed: boolean;
+  statusCode?: number;
+  statusMessage?: string;
+};

package/src/lib/validate-processor.ts

@@ -0,0 +1,68 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+
+import { Capability } from "./capability";
+import { shouldSkipRequest } from "./filter";
+import { Request, ValidateResponse } from "./k8s/types";
+import Log from "./logger";
+import { PeprValidateRequest } from "./validate-request";
+
+export async function validateProcessor(
+  capabilities: Capability[],
+  req: Request,
+  reqMetadata: Record<string, string>,
+): Promise<ValidateResponse> {
+  const wrapped = new PeprValidateRequest(req);
+  const response: ValidateResponse = {
+    uid: req.uid,
+    allowed: true, // Assume it's allowed until a validation check fails
+  };
+
+  Log.info(reqMetadata, `Processing validation request`);
+
+  for (const { name, bindings } of capabilities) {
+    const actionMetadata = { ...reqMetadata, name };
+
+    for (const action of bindings) {
+      // Skip this action if it's not a validation action
+      if (!action.validateCallback) {
+        continue;
+      }
+
+      // Continue to the next action without doing anything if this one should be skipped
+      if (shouldSkipRequest(action, req)) {
+        continue;
+      }
+
+      const label = action.validateCallback.name;
+      Log.info(actionMetadata, `Processing matched action ${label}`);
+
+      try {
+        // Run the validation callback, if it fails set allowed to false
+        const resp = await action.validateCallback(wrapped);
+        response.allowed = resp.allowed;
+
+        // If the validation callback returned a status code or message, set it in the Response
+        if (resp.statusCode || resp.statusMessage) {
+          response.status = {
+            code: resp.statusCode || 400,
+            message: resp.statusMessage || `Validation failed for ${name}`,
+          };
+        }
+
+        Log.info(actionMetadata, `Validation Action completed: ${resp.allowed ? "allowed" : "denied"}`);
+      } catch (e) {
+        // If any validation throws an error, note the failure in the Response
+        Log.error(actionMetadata, `Action failed: ${e}`);
+        response.allowed = false;
+        response.status = {
+          code: 500,
+          message: `Action failed with error: ${e}`,
+        };
+        return response;
+      }
+    }
+  }
+
+  return response;
+}

package/src/lib/validate-request.ts

@@ -0,0 +1,94 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+
+import { clone } from "ramda";
+import { KubernetesObject, Operation, Request } from "./k8s/types";
+import { ValidateResponse } from "./types";
+
+/**
+ * The RequestWrapper class provides methods to modify Kubernetes objects in the context
+ * of a mutating webhook request.
+ */
+export class PeprValidateRequest<T extends KubernetesObject> {
+  public Raw: T;
+
+  /**
+   * 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(protected _input: Request<T>) {
+    // 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");
+    }
+  }
+
+  /**
+   * 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;
+  }
+
+  /**
+   * Create a validation response that allows the request.
+   *
+   * @returns The validation response.
+   */
+  Approve(): ValidateResponse {
+    return {
+      allowed: true,
+    };
+  }
+
+  /**
+   * Create a validation response that denies the request.
+   *
+   * @param statusMessage Optional status message to return to the user.
+   * @param statusCode Optional status code to return to the user.
+   * @returns The validation response.
+   */
+  Deny(statusMessage?: string, statusCode?: number): ValidateResponse {
+    return {
+      allowed: false,
+      statusCode,
+      statusMessage,
+    };
+  }
+}

package/src/lib.ts

@@ -6,7 +6,8 @@ import { fetch, fetchRaw } from "./lib/fetch";
 import { RegisterKind, a } from "./lib/k8s/index";
 import Log from "./lib/logger";
 import { PeprModule } from "./lib/module";
-import { PeprRequest } from "./lib/request";
+import { PeprMutateRequest } from "./lib/mutate-request";
+import { PeprValidateRequest } from "./lib/validate-request";
 import * as PeprUtils from "./lib/utils";
 
 // Import type information for external packages
@@ -17,7 +18,8 @@ export {
   a,
   /** PeprModule is used to setup a complete Pepr Module: `new PeprModule(cfg, {...capabilities})` */
   PeprModule,
-  PeprRequest,
+  PeprMutateRequest,
+  PeprValidateRequest,
   PeprUtils,
   RegisterKind,
   Capability,

package/src/runtime/controller.ts

@@ -26,7 +26,7 @@ function runModule(expectedHash: string) {
   const jsPath = `/app/module-${expectedHash}.js`;
 
   // Set the log level
-  Log.SetLogLevel("debug");
+  Log.level = "info";
 
   // Check if the path is a valid file
   if (!fs.existsSync(gzPath)) {

package/dist/lib/k8s/webhook.d.ts

@@ -1,37 +0,0 @@
-/// <reference types="node" />
-import { V1ClusterRole, V1ClusterRoleBinding, V1Deployment, V1MutatingWebhookConfiguration, V1Namespace, V1RuleWithOperations, V1Secret, V1Service, V1ServiceAccount } from "@kubernetes/client-node";
-import { ModuleConfig } from "../types";
-import { TLSOut } from "./tls";
-export declare class Webhook {
-    private readonly config;
-    private readonly host?;
-    private name;
-    private _tls;
-    private _apiToken;
-    image: string;
-    get tls(): TLSOut;
-    get apiToken(): string;
-    constructor(config: ModuleConfig, host?: string | undefined);
-    /** Generate the pepr-system namespace */
-    namespace(): V1Namespace;
-    /**
-     * Grants the controller access to cluster resources beyond the mutating webhook.
-     *
-     * @todo: should dynamically generate this based on resources used by the module. will also need to explore how this should work for multiple modules.
-     * @returns
-     */
-    clusterRole(): V1ClusterRole;
-    clusterRoleBinding(): V1ClusterRoleBinding;
-    serviceAccount(): V1ServiceAccount;
-    apiTokenSecret(): V1Secret;
-    tlsSecret(): V1Secret;
-    generateWebhookRules(path: string): Promise<V1RuleWithOperations[]>;
-    mutatingWebhook(path: string, timeoutSeconds?: number): Promise<V1MutatingWebhookConfiguration>;
-    deployment(hash: string): V1Deployment;
-    service(): V1Service;
-    moduleSecret(data: Buffer, hash: string): V1Secret;
-    zarfYaml(path: string): string;
-    allYaml(path: string): Promise<string>;
-    deploy(path: string, webhookTimeout?: number): Promise<void>;
-}
-//# sourceMappingURL=webhook.d.ts.map

package/dist/lib/k8s/webhook.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"webhook.d.ts","sourceRoot":"","sources":["../../../src/lib/k8s/webhook.ts"],"names":[],"mappings":";AAGA,OAAO,EAQL,aAAa,EACb,oBAAoB,EACpB,YAAY,EAEZ,8BAA8B,EAC9B,WAAW,EACX,oBAAoB,EACpB,QAAQ,EACR,SAAS,EACT,gBAAgB,EAEjB,MAAM,yBAAyB,CAAC;AAQjC,OAAO,EAA6B,YAAY,EAAE,MAAM,UAAU,CAAC;AACnE,OAAO,EAAE,MAAM,EAAU,MAAM,OAAO,CAAC;AAQvC,qBAAa,OAAO;IAeN,OAAO,CAAC,QAAQ,CAAC,MAAM;IAAgB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC;IAdzE,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,SAAS,CAAS;IAEnB,KAAK,EAAE,MAAM,CAAC;IAErB,IAAW,GAAG,IAAI,MAAM,CAEvB;IAED,IAAW,QAAQ,IAAI,MAAM,CAE5B;gBAE4B,MAAM,EAAE,YAAY,EAAmB,IAAI,CAAC,oBAAQ;IAYjF,yCAAyC;IACzC,SAAS,IAAI,WAAW;IAQxB;;;;;OAKG;IACH,WAAW,IAAI,aAAa;IAgB5B,kBAAkB,IAAI,oBAAoB;IAqB1C,cAAc,IAAI,gBAAgB;IAWlC,cAAc,IAAI,QAAQ;IAe1B,SAAS,IAAI,QAAQ;IAgBrB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,EAAE,CAAC;IAwF7D,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,cAAc,SAAK,GAAG,OAAO,CAAC,8BAA8B,CAAC;IA4DjG,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY;IAoGtC,OAAO,IAAI,SAAS;IAsBpB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,QAAQ;IAkBlD,QAAQ,CAAC,IAAI,EAAE,MAAM;IA4Bf,OAAO,CAAC,IAAI,EAAE,MAAM;IAyBpB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,cAAc,CAAC,EAAE,MAAM;CA6InD"}

package/dist/lib/processor.d.ts

@@ -1,5 +0,0 @@
-import { Capability } from "./capability";
-import { Request, Response } from "./k8s/types";
-import { ModuleConfig } from "./types";
-export declare function processor(config: ModuleConfig, capabilities: Capability[], req: Request, parentPrefix: string): Promise<Response>;
-//# sourceMappingURL=processor.d.ts.map

package/dist/lib/processor.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"processor.d.ts","sourceRoot":"","sources":["../../src/lib/processor.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE1C,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAIhD,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAGvC,wBAAsB,SAAS,CAC7B,MAAM,EAAE,YAAY,EACpB,YAAY,EAAE,UAAU,EAAE,EAC1B,GAAG,EAAE,OAAO,EACZ,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,QAAQ,CAAC,CAsHnB"}

package/dist/lib/request.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"request.d.ts","sourceRoot":"","sources":["../../src/lib/request.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,gBAAgB,EAAa,OAAO,EAAE,MAAM,aAAa,CAAC;AACnE,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAEtC;;;GAGG;AACH,qBAAa,WAAW,CAAC,CAAC,SAAS,gBAAgB;IAmCrC,OAAO,CAAC,MAAM;IAlCnB,GAAG,EAAE,CAAC,CAAC;IAEd,IAAI,iBAAiB,YAEpB;IAED;;;OAGG;IACH,IAAI,QAAQ,wBAEX;IAED;;;OAGG;IACH,IAAI,WAAW,kBAEd;IAED;;;OAGG;IACH,IAAI,OAAO,eAEV;IAED;;;OAGG;gBACiB,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IActC;;;;OAIG;IACH,KAAK,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC,CAAC;IAIzB;;;;;OAKG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;IAUnC;;;;;OAKG;IACH,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;IAUxC;;;;OAIG;IACH,WAAW,CAAC,GAAG,EAAE,MAAM;IAQvB;;;;OAIG;IACH,gBAAgB,CAAC,GAAG,EAAE,MAAM;IAQ5B;;;;;OAKG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM;IAIpB;;;;;OAKG;IACH,aAAa,CAAC,GAAG,EAAE,MAAM;CAG1B"}