pepr 0.1.27 → 0.1.29

package/dist/src/lib/processor.js

@@ -0,0 +1,73 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.processor = void 0;
+const fast_json_patch_1 = require("fast-json-patch");
+const filter_1 = require("./filter");
+const logger_1 = __importDefault(require("./logger"));
+const request_1 = require("./request");
+function processor(config, capabilities, req) {
+    const wrapped = new request_1.RequestWrapper(req);
+    const response = {
+        uid: req.uid,
+        patchType: "JSONPatch",
+        warnings: [],
+        allowed: false,
+    };
+    logger_1.default.info(`Processing '${req.uid}' for '${req.kind.kind}' '${req.name}'`);
+    for (const { name, bindings } of capabilities) {
+        const prefix = `${req.uid} ${req.name}: ${name}`;
+        logger_1.default.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 ((0, filter_1.shouldSkipRequest)(action, req)) {
+                continue;
+            }
+            logger_1.default.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 { metadata } = wrapped.Raw;
+            const identifier = `pepr.dev/${config.uuid}/${name}`;
+            metadata.annotations = metadata.annotations || {};
+            metadata.annotations[identifier] = "started";
+            try {
+                // Run the action
+                action.callback(wrapped);
+                // Add annotations to the request to indicate that the capability succeeded
+                metadata.annotations[identifier] = "succeeded";
+            }
+            catch (e) {
+                response.warnings.push(`Action failed: ${e}`);
+                // If errors are not allowed, note the failure in the Reponse
+                if (config.onError) {
+                    logger_1.default.error(`Action failed: ${e}`, prefix);
+                    response.result = "Pepr module configured to reject on error";
+                    return response;
+                }
+                else {
+                    logger_1.default.warn(`Action failed: ${e}`, prefix);
+                    metadata.annotations[identifier] = "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 = (0, fast_json_patch_1.compare)(req.object, wrapped.Raw);
+    // Only add the patch if there are patches to apply
+    if (patches.length > 0) {
+        response.patch = JSON.stringify(patches);
+    }
+    // Remove the warnings array if it's empty
+    if (response.warnings.length < 1) {
+        delete response.warnings;
+    }
+    logger_1.default.debug(patches);
+    return response;
+}
+exports.processor = processor;

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

@@ -0,0 +1,77 @@
+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 declare class RequestWrapper<T extends KubernetesObject> {
+    private _input;
+    Raw: T;
+    get PermitSideEffects(): boolean;
+    /**
+     * Indicates whether the request is a dry run.
+     * @returns true if the request is a dry run, false otherwise.
+     */
+    get IsDryRun(): boolean;
+    /**
+     * Provides access to the old resource in the request if available.
+     * @returns The old Kubernetes resource object or null if not available.
+     */
+    get OldResource(): T;
+    /**
+     * Provides access to the request object.
+     * @returns The request object containing the Kubernetes resource.
+     */
+    get Request(): Request<T>;
+    /**
+     * Creates a new instance of the Action class.
+     * @param input - The request object containing the Kubernetes resource to modify.
+     */
+    constructor(input: Request<T>);
+    /**
+     * Deep merges the provided object with the current resource.
+     *
+     * @param obj - The object to merge with the current resource.
+     */
+    Merge(obj: DeepPartial<T>): void;
+    /**
+     * 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): 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): 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): 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): this;
+    /**
+     * Check if a label exists on the Kubernetes resource.
+     *
+     * @param key the label key to check
+     * @returns
+     */
+    HasLabel(key: string): boolean;
+    /**
+     * Check if an annotation exists on the Kubernetes resource.
+     *
+     * @param key the annotation key to check
+     * @returns
+     */
+    HasAnnotation(key: string): boolean;
+}

package/dist/src/lib/request.js

@@ -0,0 +1,144 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RequestWrapper = void 0;
+const R = __importStar(require("ramda"));
+/**
+ * The RequestWrapper class provides methods to modify Kubernetes objects in the context
+ * of a mutating webhook request.
+ */
+class RequestWrapper {
+    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) {
+        // 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) {
+        this.Raw = R.mergeDeepRight(this.Raw, obj);
+    }
+    /**
+     * 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, value) {
+        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, value) {
+        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) {
+        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) {
+        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) {
+        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) {
+        return this.Raw?.metadata?.annotations?.[key] !== undefined;
+    }
+}
+exports.RequestWrapper = RequestWrapper;

package/dist/src/lib/types.d.ts

@@ -0,0 +1,187 @@
+import { GroupVersionKind, KubernetesObject, WebhookIgnore } from "./k8s";
+import { RequestWrapper } from "./request";
+/**
+ * The behavior of this module when an error occurs.
+ */
+export declare 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 declare enum HookPhase {
+    mutate = "mutate",
+    valdiate = "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 ethat the capability action is registered for.
+ */
+export declare 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;
+};
+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 cabability 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: RequestWrapper<K>) => void;

package/dist/src/lib/types.js

@@ -0,0 +1,34 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Event = exports.HookPhase = exports.ErrorBehavior = void 0;
+/**
+ * The behavior of this module when an error occurs.
+ */
+var ErrorBehavior;
+(function (ErrorBehavior) {
+    ErrorBehavior["ignore"] = "ignore";
+    ErrorBehavior["audit"] = "audit";
+    ErrorBehavior["reject"] = "reject";
+})(ErrorBehavior = exports.ErrorBehavior || (exports.ErrorBehavior = {}));
+/**
+ * The phase of the Kubernetes admission webhook that the capability is registered for.
+ *
+ * Currently only `mutate` is supported.
+ */
+var HookPhase;
+(function (HookPhase) {
+    HookPhase["mutate"] = "mutate";
+    HookPhase["valdiate"] = "validate";
+})(HookPhase = exports.HookPhase || (exports.HookPhase = {}));
+/**
+ * The type of Kubernetes mutating webhook event ethat the capability action is registered for.
+ */
+var Event;
+(function (Event) {
+    Event["Create"] = "create";
+    Event["Update"] = "update";
+    Event["Delete"] = "delete";
+    Event["CreateOrUpdate"] = "createOrUpdate";
+})(Event = exports.Event || (exports.Event = {}));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pepr",
-  "version": "0.1.27",
+  "version": "0.1.29",
   "description": "Kubernetes application engine",
   "author": "Defense Unicorns",
   "homepage": "https://github.com/defenseunicorns/pepr",
@@ -10,6 +10,8 @@
   "engines": {
     "node": ">=18.0.0"
   },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "pepr": {
     "name": "Development Module",
     "uuid": "20e17cf6-a2e4-46b2-b626-75d88d96c88b",
@@ -23,7 +25,7 @@
   },
   "scripts": {
     "preversion": "npm run prepublishOnly",
-    "build": "rollup -c",
+    "build": "tsc -p tsconfig.build.json",
     "test": "ava",
     "lint": "npx eslint src",
     "lint:fix": "npm run lint -- --fix",
@@ -31,9 +33,7 @@
     "prettier:fix": "npm run prettier -- --write",
     "prepublishOnly": "rm -fr dist/* && npm run lint:fix && npm run prettier:fix && npm run test && npm run build",
     "e2e-dev-setup": "k3d cluster delete pepr-dev && k3d cluster create pepr-dev",
-    "e2e-dev": "npm run build && docker buildx build --tag pepr:dev . && k3d image import pepr:dev -c pepr-dev && node dist/pepr-cli.js deploy -f -i pepr:dev",
-    "prestart": "ts-node src/cli dev",
-    "start": "chokidar 'src/**/*.ts' -c 'SSL_KEY_PATH=insecure-tls.key SSL_CERT_PATH=insecure-tls.crt ts-node src/controller/index.ts' --initial --silent"
+    "e2e-dev": "npm run build && docker buildx build --tag pepr:dev . && k3d image import pepr:dev -c pepr-dev && node dist/pepr-cli.js deploy -f -i pepr:dev"
   },
   "dependencies": {
     "@kubernetes/client-node": "^0.18.1",
@@ -52,6 +52,7 @@
     "rollup": "^3.20.2",
     "tslib": "^2.5.0",
     "typescript": "^5.0.2",
+    "ts-node": "^10.9.1",
     "uuid": "^9.0.0"
   },
   "devDependencies": {
@@ -62,18 +63,14 @@
     "@typescript-eslint/eslint-plugin": "^5.57.0",
     "@typescript-eslint/parser": "^5.57.0",
     "ava": "^5.2.0",
-    "chokidar-cli": "^3.0.0",
-    "eslint": "^8.37.0",
-    "ts-node": "^10.9.1",
-    "tsconfig-paths": "^4.1.2"
+    "eslint": "^8.37.0"
   },
   "ava": {
     "extensions": [
       "ts"
     ],
     "require": [
-      "ts-node/register",
-      "tsconfig-paths/register"
+      "ts-node/register"
     ]
   }
 }

package/tsconfig.build.json

@@ -0,0 +1,4 @@
+{
+    "extends": "./tsconfig.json",
+    "exclude": ["node_modules", "dist", "fixtures", "**/*.test.ts"]
+}