pepr 0.32.0 → 0.32.2

package/dist/lib/metrics.d.ts

@@ -0,0 +1,39 @@
+/**
+ * MetricsCollector class handles metrics collection using prom-client and performance hooks.
+ */
+export declare class MetricsCollector {
+    #private;
+    /**
+     * Creates a MetricsCollector instance with prefixed metrics.
+     * @param [prefix='pepr'] - The prefix for the metric names.
+     */
+    constructor(prefix?: string);
+    addCounter: (name: string, help: string) => void;
+    addSummary: (name: string, help: string) => void;
+    incCounter: (name: string) => void;
+    /**
+     * Increments the error counter.
+     */
+    error: () => void;
+    /**
+     * Increments the alerts counter.
+     */
+    alert: () => void;
+    /**
+     * Observes the duration since the provided start time and updates the summary.
+     * @param startTime - The start time.
+     * @param name - The metrics summary to increment.
+     */
+    observeEnd: (startTime: number, name?: string) => void;
+    /**
+     * Fetches the current metrics from the registry.
+     * @returns The metrics.
+     */
+    getMetrics: () => Promise<string>;
+    /**
+     * Returns the current timestamp from performance.now() method. Useful for start timing an operation.
+     * @returns The timestamp.
+     */
+    static observeStart(): number;
+}
+//# sourceMappingURL=metrics.d.ts.map

package/dist/lib/module.d.ts

@@ -0,0 +1,62 @@
+import { Capability } from "./capability";
+import { AdmissionRequest, MutateResponse, ValidateResponse, WebhookIgnore } from "./k8s";
+/** Custom Labels Type for package.json */
+export interface CustomLabels {
+    namespace?: Record<string, string>;
+}
+/** Global configuration for the Pepr runtime. */
+export type ModuleConfig = {
+    /** The Pepr version this module uses */
+    peprVersion?: string;
+    /** The user-defined version of the module */
+    appVersion?: 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;
+    /** The webhookTimeout */
+    webhookTimeout?: number;
+    /** Reject K8s resource AdmissionRequests on error. */
+    onError?: string;
+    /** Configure global exclusions that will never be processed by Pepr. */
+    alwaysIgnore: WebhookIgnore;
+    /** Define the log level for the in-cluster controllers */
+    logLevel?: string;
+    /** Propagate env variables to in-cluster controllers */
+    env?: Record<string, string>;
+    /** Custom Labels for Kubernetes Objects */
+    customLabels?: CustomLabels;
+};
+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: AdmissionRequest) => void;
+    /** A user-defined callback to post-process or intercept a Pepr response just before it is returned to K8s */
+    afterHook?: (res: MutateResponse | ValidateResponse) => void;
+};
+export declare const isWatchMode: () => boolean;
+export declare const isBuildMode: () => boolean;
+export declare const isDevMode: () => boolean;
+export declare class PeprModule {
+    #private;
+    /**
+     * 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 opts Options for the Pepr runtime
+     */
+    constructor({ description, pepr }: PackageJSON, capabilities?: Capability[], opts?: PeprModuleOptions);
+    /**
+     * 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?: number) => void;
+}
+//# sourceMappingURL=module.d.ts.map

package/dist/lib/mutate-processor.d.ts

@@ -0,0 +1,5 @@
+import { Capability } from "./capability";
+import { MutateResponse, AdmissionRequest } from "./k8s";
+import { ModuleConfig } from "./module";
+export declare function mutateProcessor(config: ModuleConfig, capabilities: Capability[], req: AdmissionRequest, reqMetadata: Record<string, string>): Promise<MutateResponse>;
+//# sourceMappingURL=mutate-processor.d.ts.map

package/dist/lib/mutate-request.d.ts

@@ -0,0 +1,79 @@
+import { KubernetesObject } from "kubernetes-fluent-client";
+import { AdmissionRequest } 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 PeprMutateRequest<T extends KubernetesObject> {
+    #private;
+    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 | undefined;
+    /**
+     * 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 | undefined;
+    /**
+     * Provides access to the request object.
+     * @returns The request object containing the Kubernetes resource.
+     */
+    get Request(): AdmissionRequest<T>;
+    /**
+     * Creates a new instance of the action class.
+     * @param input - The request object containing the Kubernetes resource to modify.
+     */
+    constructor(input: AdmissionRequest<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;
+}
+//# sourceMappingURL=mutate-request.d.ts.map

package/dist/lib/queue.d.ts

@@ -0,0 +1,19 @@
+import { KubernetesObject } from "@kubernetes/client-node";
+import { WatchPhase } from "kubernetes-fluent-client/dist/fluent/types";
+/**
+ * Queue is a FIFO queue for reconciling
+ */
+export declare class Queue<K extends KubernetesObject> {
+    #private;
+    constructor();
+    setReconcile(reconcile: (obj: KubernetesObject, type: WatchPhase) => Promise<void>): void;
+    /**
+     * Enqueue adds an item to the queue and returns a promise that resolves when the item is
+     * reconciled.
+     *
+     * @param item The object to reconcile
+     * @returns A promise that resolves when the object is reconciled
+     */
+    enqueue(item: K, type: WatchPhase): Promise<void>;
+}
+//# sourceMappingURL=queue.d.ts.map

package/dist/lib/schedule.d.ts

@@ -0,0 +1,76 @@
+/// <reference types="node" />
+import { PeprStore } from "./storage";
+type Unit = "seconds" | "second" | "minute" | "minutes" | "hours" | "hour";
+export interface Schedule {
+    /**
+     * * The name of the store
+     */
+    name: string;
+    /**
+     * The value associated with a unit of time
+     */
+    every: number;
+    /**
+     * The unit of time
+     */
+    unit: Unit;
+    /**
+     * The code to run
+     */
+    run: () => void;
+    /**
+     * The start time of the schedule
+     */
+    startTime?: Date | undefined;
+    /**
+     * The number of times the schedule has run
+     */
+    completions?: number | undefined;
+    /**
+     * Tje intervalID to clear the interval
+     */
+    intervalID?: NodeJS.Timeout;
+}
+export declare class OnSchedule implements Schedule {
+    intervalId: NodeJS.Timeout | null;
+    store: PeprStore | undefined;
+    name: string;
+    completions?: number | undefined;
+    every: number;
+    unit: Unit;
+    run: () => void;
+    startTime?: Date | undefined;
+    duration: number | undefined;
+    lastTimestamp: Date | undefined;
+    constructor(schedule: Schedule);
+    setStore(store: PeprStore): void;
+    startInterval(): void;
+    /**
+     * Checks the store for this schedule and sets the values if it exists
+     * @returns
+     */
+    checkStore(): void;
+    /**
+     * Saves the schedule to the store
+     * @returns
+     */
+    saveToStore(): void;
+    /**
+     * Gets the durations in milliseconds
+     */
+    getDuration(): void;
+    /**
+     * Sets up the interval
+     */
+    setupInterval(): void;
+    /**
+     * Starts the interval
+     */
+    start(): void;
+    /**
+     * Stops the interval
+     */
+    stop(): void;
+}
+export {};
+//# sourceMappingURL=schedule.d.ts.map

package/dist/lib/storage.d.ts

@@ -0,0 +1,83 @@
+export type DataOp = "add" | "remove";
+export type DataStore = Record<string, string>;
+export type DataSender = (op: DataOp, keys: string[], value?: string) => void;
+export type DataReceiver = (data: DataStore) => void;
+export type Unsubscribe = () => void;
+export interface PeprStore {
+    /**
+     * Returns the current value associated with the given key, or null if the given key does not exist.
+     */
+    getItem(key: string): string | null;
+    /**
+     * Removes all key/value pairs, if there are any.
+     */
+    clear(): void;
+    /**
+     * Removes the key/value pair with the given key, if a key/value pair with the given key exists.
+     */
+    removeItem(key: string): void;
+    /**
+     * Sets the value of the pair identified by key to value, creating a new key/value pair if none existed for key previously.
+     */
+    setItem(key: string, value: string): void;
+    /**
+     * Subscribe to changes in the store. This API behaves similarly to the [Svelte Store API](https://vercel.com/docs/beginner-sveltekit/svelte-stores#using-the-store).
+     *
+     * @param listener - The callback to be invoked when the store changes.
+     * @returns A function to unsubscribe from the listener.
+     */
+    subscribe(listener: DataReceiver): Unsubscribe;
+    /**
+     * Register a function to be called when the store is ready.
+     */
+    onReady(callback: DataReceiver): void;
+    /**
+     * Sets the value of the pair identified by key to value, creating a new key/value pair if none existed for key previously.
+     * Resolves when the key/value show up in the store.
+     */
+    setItemAndWait(key: string, value: string): Promise<void>;
+    /**
+     * Remove the value of the key.
+     * Resolves when the key does not show up in the store.
+     */
+    removeItemAndWait(key: string): Promise<void>;
+}
+/**
+ * A key-value data store that can be used to persist data that should be shared across Pepr controllers and capabilities.
+ *
+ * The API is similar to the [Storage API](https://developer.mozilla.org/docs/Web/API/Storage)
+ */
+export declare class Storage implements PeprStore {
+    #private;
+    registerSender: (send: DataSender) => void;
+    receive: (data: DataStore) => void;
+    getItem: (key: string) => string | null;
+    clear: () => void;
+    removeItem: (key: string) => void;
+    setItem: (key: string, value: string) => void;
+    /**
+     * Creates a promise and subscribes to the store, the promise resolves when
+     * the key and value are seen in the store.
+     *
+     * @param key - The key to add into the store
+     * @param value - The value of the key
+     * @returns
+     */
+    setItemAndWait: (key: string, value: string) => Promise<void>;
+    /**
+     * Creates a promise and subscribes to the store, the promise resolves when
+     * the key is removed from the store.
+     *
+     * @param key - The key to add into the store
+     * @returns
+     */
+    removeItemAndWait: (key: string) => Promise<void>;
+    subscribe: (subscriber: DataReceiver) => () => void;
+    onReady: (callback: DataReceiver) => void;
+    /**
+     * Remove a subscriber from the list of subscribers.
+     * @param idx - The index of the subscriber to remove.
+     */
+    unsubscribe: (idx: number) => void;
+}
+//# sourceMappingURL=storage.d.ts.map

package/dist/lib/tls.d.ts

@@ -0,0 +1,18 @@
+export interface TLSOut {
+    ca: string;
+    crt: string;
+    key: string;
+    pem: {
+        ca: string;
+        crt: string;
+        key: string;
+    };
+}
+/**
+ * Generates a self-signed CA and server certificate with Subject Alternative Names (SANs) for the K8s webhook.
+ *
+ * @param {string} name - The name to use for the server certificate's Common Name and SAN DNS entry.
+ * @returns {TLSOut} - An object containing the Base64-encoded CA, server certificate, and server private key.
+ */
+export declare function genTLS(name: string): TLSOut;
+//# sourceMappingURL=tls.d.ts.map

package/dist/lib/types.d.ts

@@ -0,0 +1,192 @@
+import { GenericClass, GroupVersionKind, KubernetesObject } from "kubernetes-fluent-client";
+import { WatchAction } from "kubernetes-fluent-client/dist/fluent/types";
+import { PeprMutateRequest } from "./mutate-request";
+import { PeprValidateRequest } from "./validate-request";
+/**
+ * Specifically for parsing logs in monitor mode
+ */
+export interface ResponseItem {
+    uid?: string;
+    allowed: boolean;
+    status: {
+        message: string;
+    };
+}
+/**
+ * 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 action is registered for.
+ */
+export declare enum Event {
+    Create = "CREATE",
+    Update = "UPDATE",
+    Delete = "DELETE",
+    CreateOrUpdate = "CREATEORUPDATE",
+    Any = "*"
+}
+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[];
+}
+export interface CapabilityExport extends CapabilityCfg {
+    bindings: Binding[];
+    hasSchedule: boolean;
+}
+export type WhenSelector<T extends GenericClass> = {
+    /** Register an action to be executed when a Kubernetes resource is created or updated. */
+    IsCreatedOrUpdated: () => BindingAll<T>;
+    /** Register an action to be executed when a Kubernetes resource is created. */
+    IsCreated: () => BindingAll<T>;
+    /** Register ann action to be executed when a Kubernetes resource is updated. */
+    IsUpdated: () => BindingAll<T>;
+    /** Register an action to be executed when a Kubernetes resource is deleted. */
+    IsDeleted: () => BindingAll<T>;
+};
+export type Binding = {
+    event: Event;
+    isMutate?: boolean;
+    isValidate?: boolean;
+    isWatch?: boolean;
+    isQueue?: boolean;
+    readonly model: GenericClass;
+    readonly kind: GroupVersionKind;
+    readonly filters: {
+        name: string;
+        namespaces: string[];
+        labels: Record<string, string>;
+        annotations: Record<string, string>;
+    };
+    readonly mutateCallback?: MutateAction<GenericClass, InstanceType<GenericClass>>;
+    readonly validateCallback?: ValidateAction<GenericClass, InstanceType<GenericClass>>;
+    readonly watchCallback?: WatchAction<GenericClass, InstanceType<GenericClass>>;
+};
+export type BindingFilter<T extends GenericClass> = CommonActionChain<T> & {
+    /**
+     * 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
+     * When(a.Deployment)
+     *   .IsCreated()
+     *   .WithLabel("foo", "bar")
+     *   .WithLabel("baz", "qux")
+     *   .Mutate(...)
+     * ```
+     *
+     * 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 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")
+     *   .Mutate(...)
+     * ```
+     *
+     * Will only apply the 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 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 action if the resource is in one of the specified namespaces.*/
+    InNamespace: (...namespaces: string[]) => BindingWithName<T>;
+};
+export type CommonActionChain<T extends GenericClass> = MutateActionChain<T> & {
+    /**
+     * Create a new MUTATE action with the specified callback function and previously specified
+     * filters.
+     *
+     * @since 0.13.0
+     *
+     * @param action The action to be executed when the Kubernetes resource is processed by the AdmissionController.
+     */
+    Mutate: (action: MutateAction<T, InstanceType<T>>) => MutateActionChain<T>;
+};
+export type ValidateActionChain<T extends GenericClass> = {
+    /**
+     * Establish a watcher for the specified resource. The callback function will be executed after the admission controller has
+     * processed the resource and the request has been persisted to the cluster.
+     *
+     * **Beta Function**: This method is still in early testing and edge cases may still exist.
+     *
+     * @since 0.14.0
+     *
+     * @param action
+     * @returns
+     */
+    Watch: (action: WatchAction<T, InstanceType<T>>) => void;
+    /**
+     * Establish a reconcile for the specified resource. The callback function will be executed after the admission controller has
+     * processed the resource and the request has been persisted to the cluster.
+     *
+     * **Beta Function**: This method is still in early testing and edge cases may still exist.
+     *
+     * @since 0.14.0
+     *
+     * @param action
+     * @returns
+     */
+    Reconcile: (action: WatchAction<T, InstanceType<T>>) => void;
+};
+export type MutateActionChain<T extends GenericClass> = ValidateActionChain<T> & {
+    /**
+     * 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:
+     *
+     * @since 0.13.0
+     *
+     * @example
+     * ```ts
+     * When(a.Deployment)
+     *  .IsCreated()
+     *  .Validate(request => {
+     *    if (request.HasLabel("foo")) {
+     *     return request.Approve();
+     *    }
+     *
+     *   return request.Deny("Deployment must have label foo");
+     * });
+     * ```
+     *
+     * @param action The action to be executed when the Kubernetes resource is processed by the AdmissionController.
+     */
+    Validate: (action: ValidateAction<T, InstanceType<T>>) => ValidateActionChain<T>;
+};
+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<ValidateActionResponse> | ValidateActionResponse;
+export type ValidateActionResponse = {
+    allowed: boolean;
+    statusCode?: number;
+    statusMessage?: string;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/lib/utils.d.ts

@@ -0,0 +1,23 @@
+/** Test if a string is ascii or not */
+export declare const isAscii: RegExp;
+/**
+ * Encode all ascii values in a map to base64
+ * @param obj The object to encode
+ * @param skip A list of keys to skip encoding
+ */
+export declare function convertToBase64Map(obj: {
+    data?: Record<string, string>;
+}, skip: string[]): void;
+/**
+ * Decode all ascii values in a map from base64 to utf-8
+ * @param obj The object to decode
+ * @returns A list of keys that were skipped
+ */
+export declare function convertFromBase64Map(obj: {
+    data?: Record<string, string>;
+}): string[];
+/** Decode a base64 string */
+export declare function base64Decode(data: string): string;
+/** Encode a string to base64 */
+export declare function base64Encode(data: string): string;
+//# sourceMappingURL=utils.d.ts.map

package/dist/lib/validate-processor.d.ts

@@ -0,0 +1,4 @@
+import { Capability } from "./capability";
+import { AdmissionRequest, ValidateResponse } from "./k8s";
+export declare function validateProcessor(capabilities: Capability[], req: AdmissionRequest, reqMetadata: Record<string, string>): Promise<ValidateResponse[]>;
+//# sourceMappingURL=validate-processor.d.ts.map

package/dist/lib/validate-request.d.ts

@@ -0,0 +1,55 @@
+import { KubernetesObject } from "kubernetes-fluent-client";
+import { AdmissionRequest } from "./k8s";
+import { ValidateActionResponse } from "./types";
+/**
+ * The RequestWrapper class provides methods to modify Kubernetes objects in the context
+ * of a mutating webhook request.
+ */
+export declare class PeprValidateRequest<T extends KubernetesObject> {
+    #private;
+    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(): T | undefined;
+    /**
+     * Provides access to the request object.
+     * @returns The request object containing the Kubernetes resource.
+     */
+    get Request(): AdmissionRequest<T>;
+    /**
+     * Creates a new instance of the Action class.
+     * @param input - The request object containing the Kubernetes resource to modify.
+     */
+    constructor(input: AdmissionRequest<T>);
+    /**
+     * 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;
+    /**
+     * Create a validation response that allows the request.
+     *
+     * @returns The validation response.
+     */
+    Approve: () => ValidateActionResponse;
+    /**
+     * 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) => ValidateActionResponse;
+}
+//# sourceMappingURL=validate-request.d.ts.map

package/dist/lib/watch-processor.d.ts

@@ -0,0 +1,10 @@
+import { KubernetesObject, WatchEvent } from "kubernetes-fluent-client";
+import { Capability } from "./capability";
+/**
+ * Entrypoint for setting up watches for all capabilities
+ *
+ * @param capabilities The capabilities to load watches for
+ */
+export declare function setupWatch(capabilities: Capability[]): void;
+export declare function logEvent(type: WatchEvent, message?: string, obj?: KubernetesObject): void;
+//# sourceMappingURL=watch-processor.d.ts.map