pepr 0.2.9 → 0.3.0-rc0

package/dist/src/lib/k8s/kinds.d.ts

@@ -1,11 +0,0 @@
-import { GenericClass } from "../types";
-import { GroupVersionKind } from "./types";
-export declare const gvkMap: Record<string, GroupVersionKind>;
-export declare function modelToGroupVersionKind(key: string): GroupVersionKind;
-/**
- * Registers a new model and GroupVersionKind with Pepr for use with `When(a.<Kind>)`
- *
- * @param model Used to match the GroupVersionKind and define the type-data for the request
- * @param groupVersionKind Contains the match parameters to determine the request should be handled
- */
-export declare const RegisterKind: (model: GenericClass, groupVersionKind: GroupVersionKind) => void;

package/dist/src/lib/k8s/tls.d.ts

@@ -1,17 +0,0 @@
-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;

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

@@ -1,147 +0,0 @@
-import { V1ListMeta, V1ObjectMeta } from "@kubernetes/client-node";
-export declare enum Operation {
-    CREATE = "CREATE",
-    UPDATE = "UPDATE",
-    DELETE = "DELETE",
-    CONNECT = "CONNECT"
-}
-export interface KubernetesObject {
-    apiVersion?: string;
-    kind?: string;
-    metadata?: V1ObjectMeta;
-}
-export interface KubernetesListObject<T extends KubernetesObject> {
-    apiVersion?: string;
-    kind?: string;
-    metadata?: V1ListMeta;
-    items: T[];
-}
-/**
- * GenericKind is a generic Kubernetes object that can be used to represent any Kubernetes object
- * that is not explicitly supported by Pepr. This can be used on its own or as a base class for
- * other types. See the examples in `HelloPepr.ts` for more information.
- */
-export declare class GenericKind {
-    apiVersion?: string;
-    kind?: string;
-    metadata?: V1ObjectMeta;
-    [key: string]: any;
-}
-/**
- * GroupVersionKind unambiguously identifies a kind. It doesn't anonymously include GroupVersion
- * to avoid automatic coercion. It doesn't use a GroupVersion to avoid custom marshalling
- **/
-export interface GroupVersionKind {
-    /** The K8s resource kind, e..g "Pod". */
-    readonly kind: string;
-    readonly group: string;
-    readonly version?: string;
-}
-/**
- * GroupVersionResource unambiguously identifies a resource. It doesn't anonymously include GroupVersion
- * to avoid automatic coercion. It doesn't use a GroupVersion to avoid custom marshalling
- */
-export interface GroupVersionResource {
-    readonly group: string;
-    readonly version: string;
-    readonly resource: string;
-}
-/**
- * A Kubernetes admission request to be processed by a capability.
- */
-export interface Request<T = KubernetesObject> {
-    /** UID is an identifier for the individual request/response. */
-    readonly uid: string;
-    /** Kind is the fully-qualified type of object being submitted (for example, v1.Pod or autoscaling.v1.Scale) */
-    readonly kind: GroupVersionKind;
-    /** Resource is the fully-qualified resource being requested (for example, v1.pods) */
-    readonly resource: GroupVersionResource;
-    /** SubResource is the sub-resource being requested, if any (for example, "status" or "scale") */
-    readonly subResource?: string;
-    /** RequestKind is the fully-qualified type of the original API request (for example, v1.Pod or autoscaling.v1.Scale). */
-    readonly requestKind?: GroupVersionKind;
-    /** RequestResource is the fully-qualified resource of the original API request (for example, v1.pods). */
-    readonly requestResource?: GroupVersionResource;
-    /** RequestSubResource is the sub-resource of the original API request, if any (for example, "status" or "scale"). */
-    readonly requestSubResource?: string;
-    /**
-     * Name is the name of the object as presented in the request. On a CREATE operation, the client may omit name and
-     * rely on the server to generate the name. If that is the case, this method will return the empty string.
-     */
-    readonly name: string;
-    /** Namespace is the namespace associated with the request (if any). */
-    readonly namespace?: string;
-    /**
-     * Operation is the operation being performed. This may be different than the operation
-     * requested. e.g. a patch can result in either a CREATE or UPDATE Operation.
-     */
-    readonly operation: Operation;
-    /** UserInfo is information about the requesting user */
-    readonly userInfo: {
-        /** The name that uniquely identifies this user among all active users. */
-        username?: string;
-        /**
-         * A unique value that identifies this user across time. If this user is deleted
-         * and another user by the same name is added, they will have different UIDs.
-         */
-        uid?: string;
-        /** The names of groups this user is a part of. */
-        groups?: string[];
-        /** Any additional information provided by the authenticator. */
-        extra?: {
-            [key: string]: string[];
-        };
-    };
-    /** Object is the object from the incoming request prior to default values being applied */
-    readonly object: T;
-    /** OldObject is the existing object. Only populated for UPDATE requests. */
-    readonly oldObject?: T;
-    /** DryRun indicates that modifications will definitely not be persisted for this request. Defaults to false. */
-    readonly dryRun?: boolean;
-    /**
-     * Options contains the options for the operation being performed.
-     * e.g. `meta.k8s.io/v1.DeleteOptions` or `meta.k8s.io/v1.CreateOptions`. This may be
-     * different than the options the caller provided. e.g. for a patch request the performed
-     * Operation might be a CREATE, in which case the Options will a
-     * `meta.k8s.io/v1.CreateOptions` even though the caller provided `meta.k8s.io/v1.PatchOptions`.
-     */
-    readonly options?: any;
-}
-export interface Response {
-    /** UID is an identifier for the individual request/response. This must be copied over from the corresponding AdmissionRequest. */
-    uid: string;
-    /** Allowed indicates whether or not the admission request was permitted. */
-    allowed: boolean;
-    /** Result contains extra details into why an admission request was denied. This field IS NOT consulted in any way if "Allowed" is "true". */
-    result?: string;
-    /** The patch body. Currently we only support "JSONPatch" which implements RFC 6902. */
-    patch?: string;
-    /** 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?: {
-        [key: string]: string;
-    };
-    /** warnings is a list of warning messages to return to the requesting API client. */
-    warnings?: string[];
-}
-export type WebhookIgnore = {
-    /**
-     * List of Kubernetes namespaces to always ignore.
-     * Any resources in these namespaces will be ignored by Pepr.
-     *
-     * Note: `kube-system` and `pepr-system` are always ignored.
-     */
-    namespaces?: string[];
-    /**
-     * List of Kubernetes labels to always ignore.
-     * Any resources with these labels will be ignored by Pepr.
-     *
-     * The example below will ignore any resources with the label `my-label=ulta-secret`:
-     * ```
-     * alwaysIgnore:
-     *   labels: [{ "my-label": "ultra-secret" }]
-     * ```
-     */
-    labels?: Record<string, string>[];
-};

package/dist/src/lib/k8s/upstream.d.ts

@@ -1,3 +0,0 @@
-/** a is a colleciton of K8s types to be used within a CapabilityAction: `When(a.Configmap)` */
-export { V1APIService as APIService, V1CertificateSigningRequest as CertificateSigningRequest, V1ConfigMap as ConfigMap, V1ControllerRevision as ControllerRevision, V1CronJob as CronJob, V1CSIDriver as CSIDriver, V1CSIStorageCapacity as CSIStorageCapacity, V1CustomResourceDefinition as CustomResourceDefinition, V1DaemonSet as DaemonSet, V1Deployment as Deployment, V1EndpointSlice as EndpointSlice, V1HorizontalPodAutoscaler as HorizontalPodAutoscaler, V1Ingress as Ingress, V1IngressClass as IngressClass, V1Job as Job, V1LimitRange as LimitRange, V1LocalSubjectAccessReview as LocalSubjectAccessReview, V1MutatingWebhookConfiguration as MutatingWebhookConfiguration, V1Namespace as Namespace, V1NetworkPolicy as NetworkPolicy, V1Node as Node, V1PersistentVolume as PersistentVolume, V1PersistentVolumeClaim as PersistentVolumeClaim, V1Pod as Pod, V1PodDisruptionBudget as PodDisruptionBudget, V1PodTemplate as PodTemplate, V1ReplicaSet as ReplicaSet, V1ReplicationController as ReplicationController, V1ResourceQuota as ResourceQuota, V1RuntimeClass as RuntimeClass, V1Secret as Secret, V1SelfSubjectAccessReview as SelfSubjectAccessReview, V1SelfSubjectRulesReview as SelfSubjectRulesReview, V1Service as Service, V1ServiceAccount as ServiceAccount, V1StatefulSet as StatefulSet, V1StorageClass as StorageClass, V1SubjectAccessReview as SubjectAccessReview, V1TokenReview as TokenReview, V1ValidatingWebhookConfiguration as ValidatingWebhookConfiguration, V1VolumeAttachment as VolumeAttachment, } from "@kubernetes/client-node/dist";
-export { GenericKind } from "./types";

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

@@ -1,34 +0,0 @@
-/// <reference types="node" />
-import { V1ClusterRole, V1ClusterRoleBinding, V1Deployment, V1MutatingWebhookConfiguration, V1Namespace, V1NetworkPolicy, 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;
-    image: string;
-    get tls(): TLSOut;
-    constructor(config: ModuleConfig, host?: string);
-    /** 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;
-    tlsSecret(): V1Secret;
-    mutatingWebhook(): V1MutatingWebhookConfiguration;
-    deployment(hash: string): V1Deployment;
-    /** Only permit the kube-system ns ingress access to the controller */
-    networkPolicy(): V1NetworkPolicy;
-    service(): V1Service;
-    moduleSecret(data: Buffer, hash: string): V1Secret;
-    zarfYaml(path: string): string;
-    allYaml(code: Buffer): string;
-    deploy(code: Buffer): Promise<void>;
-}

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

@@ -1,55 +0,0 @@
-/**
- * Enumeration representing different logging levels.
- */
-export declare enum LogLevel {
-    debug = 0,
-    info = 1,
-    warn = 2,
-    error = 3
-}
-/**
- * Simple logger class that logs messages at different log levels.
- */
-export declare class Logger {
-    private _logLevel;
-    /**
-     * Create a new logger instance.
-     * @param logLevel - The minimum log level to log messages for.
-     */
-    constructor(logLevel: LogLevel);
-    /**
-     * Change the log level of the logger.
-     * @param logLevel - The log level to log the message at.
-     */
-    SetLogLevel(logLevel: string): void;
-    /**
-     * Log a debug message.
-     * @param message - The message to log.
-     */
-    debug<T>(message: T, prefix?: string): void;
-    /**
-     * Log an info message.
-     * @param message - The message to log.
-     */
-    info<T>(message: T, prefix?: string): void;
-    /**
-     * Log a warning message.
-     * @param message - The message to log.
-     */
-    warn<T>(message: T, prefix?: string): void;
-    /**
-     * Log an error message.
-     * @param message - The message to log.
-     */
-    error<T>(message: T, prefix?: string): void;
-    /**
-     * Log a message at the specified log level.
-     * @param logLevel - The log level of the message.
-     * @param message - The message to log.
-     */
-    private log;
-    private colorize;
-}
-/** Log is an instance of Logger used to generate log entries. */
-declare const Log: Logger;
-export default Log;

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

@@ -1,32 +0,0 @@
-import { Capability } from "./capability";
-import { Request, Response } from "./k8s/types";
-import { ModuleConfig } from "./types";
-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: Request) => void;
-    /** A user-defined callback to post-process or intercept a Pepr response just before it is returned to K8s */
-    afterHook?: (res: Response) => void;
-};
-export declare class PeprModule {
-    private _controller;
-    /**
-     * 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 _deferStart (optional) If set to `true`, the Pepr runtime will not be started automatically. This can be used to start the Pepr runtime manually with `start()`.
-     */
-    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;
-}

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

@@ -1,4 +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): Promise<Response>;

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

@@ -1,77 +0,0 @@
-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 PeprRequest<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/types.d.ts

@@ -1,187 +0,0 @@
-import { GroupVersionKind, KubernetesObject, WebhookIgnore } from "./k8s";
-import { PeprRequest } 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",
-    validate = "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 that 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 capability 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: PeprRequest<K>) => Promise<void> | void | Promise<PeprRequest<K>> | PeprRequest<K>;