pepr 0.0.8 → 0.1.0

package/src/lib/capability.ts

@@ -0,0 +1,158 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+
+import { modelToGroupVersionKind } from "./k8s";
+import logger from "./logger";
+import {
+  Binding,
+  BindingFilter,
+  BindingWithName,
+  BindToAction,
+  CapabilityAction,
+  CapabilityCfg,
+  DeepPartial,
+  Event,
+  GenericClass,
+  HookPhase,
+  WhenSelector,
+} from "./types";
+
+/**
+ * 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;
+
+  // Currently everything is considered a mutation
+  private _mutateOrValidate = HookPhase.mutate;
+
+  private _bindings: Binding[] = [];
+
+  get bindings(): Binding[] {
+    return this._bindings;
+  }
+
+  get name() {
+    return this._name;
+  }
+
+  get description() {
+    return this._description;
+  }
+
+  get namespaces() {
+    return this._namespaces || [];
+  }
+
+  get mutateOrValidate() {
+    return this._mutateOrValidate;
+  }
+
+  constructor(cfg: CapabilityCfg) {
+    this._name = cfg.name;
+    this._description = cfg.description;
+    this._namespaces = cfg.namespaces;
+    logger.info(`Capability ${this._name} registered`);
+    logger.debug(cfg);
+  }
+
+  /**
+   * The Register method is used to register a capability with the Pepr runtime. This method is
+   * called in the order that the capabilities should be executed.
+   *
+   * @param callback the state register method to call, passing the capability as an argument
+   */
+  Register = (register: (capability: Capability) => void) => register(this);
+
+  /**
+   * The When method is used to register a capability action to be executed when a Kubernetes resource is
+   * processed by Pepr. The action will be executed if the resource matches the specified kind and any
+   * filters that are applied.
+   *
+   * @param model if using a custom KubernetesObject not available in `a.*`, specify the GroupVersionKind
+   * @returns
+   */
+  When = <T extends GenericClass>(model: T): WhenSelector<T> => {
+    const binding: Binding = {
+      // If the kind is not specified, use the default KubernetesObject
+      kind: modelToGroupVersionKind(model.name),
+      filters: {
+        name: "",
+        namespaces: [],
+        labels: {},
+        annotations: {},
+      },
+      callback: () => null,
+    };
+
+    const prefix = `${this._name}: ${model.name}`;
+
+    logger.info(`Binding created`, prefix);
+
+    const Then = (cb: CapabilityAction<T>): BindToAction<T> => {
+      logger.info(`Binding action created`, prefix);
+      logger.debug(cb.toString(), prefix);
+      // Push the binding to the list of bindings for this capability as a new BindingAction
+      // with the callback function to preserve
+      this._bindings.push({
+        ...binding,
+        callback: cb,
+      });
+
+      // Now only allow adding actions to the same binding
+      return { Then };
+    };
+
+    const ThenSet = (merge: DeepPartial<InstanceType<T>>): BindToAction<T> => {
+      // Add the new action to the binding
+      Then(req => req.Merge(merge));
+
+      return { Then };
+    };
+
+    function InNamespace(...namespaces: string[]): BindingWithName<T> {
+      logger.debug(`Add namespaces filter ${namespaces}`, prefix);
+      binding.filters.namespaces.push(...namespaces);
+      return { WithLabel, WithAnnotation, WithName, Then, ThenSet };
+    }
+
+    function WithName(name: string): BindingFilter<T> {
+      logger.debug(`Add name filter ${name}`, prefix);
+      binding.filters.name = name;
+      return { WithLabel, WithAnnotation, Then, ThenSet };
+    }
+
+    function WithLabel(key: string, value = ""): BindingFilter<T> {
+      logger.debug(`Add label filter ${key}=${value}`, prefix);
+      binding.filters.labels[key] = value;
+      return { WithLabel, WithAnnotation, Then, ThenSet };
+    }
+
+    const WithAnnotation = (key: string, value = ""): BindingFilter<T> => {
+      logger.debug(`Add annotation filter ${key}=${value}`, prefix);
+      binding.filters.annotations[key] = value;
+      return { WithLabel, WithAnnotation, Then, ThenSet };
+    };
+
+    const bindEvent = (event: Event) => {
+      binding.event = event;
+      return {
+        InNamespace,
+        Then,
+        ThenSet,
+        WithAnnotation,
+        WithLabel,
+        WithName,
+      };
+    };
+
+    return {
+      IsCreatedOrUpdated: () => bindEvent(Event.CreateOrUpdate),
+      IsCreated: () => bindEvent(Event.Create),
+      IsUpdated: () => bindEvent(Event.Update),
+      IsDeleted: () => bindEvent(Event.Delete),
+    };
+  };
+}

package/src/lib/filter.test.ts

@@ -0,0 +1,211 @@
+import { gvkMap } from "@k8s";
+import test from "ava";
+import { POD1 } from "@fixtures/loader";
+import { shouldSkipRequest } from "./filter";
+
+test("should reject when kind does not match", t => {
+  const binding = {
+    kind: gvkMap.V1ConfigMap,
+    filters: {
+      name: "",
+      namespaces: [],
+      labels: {},
+      annotations: {},
+    },
+    callback: () => null,
+  };
+  const pod = POD1();
+
+  t.true(shouldSkipRequest(binding, pod));
+});
+
+test("should reject when group does not match", t => {
+  const binding = {
+    kind: gvkMap.V1CronJob,
+    filters: {
+      name: "",
+      namespaces: [],
+      labels: {},
+      annotations: {},
+    },
+    callback: () => null,
+  };
+  const pod = POD1();
+
+  t.true(shouldSkipRequest(binding, pod));
+});
+
+test("should reject when version does not match", t => {
+  const binding = {
+    kind: {
+      group: "",
+      version: "v2",
+      kind: "Pod",
+    },
+    filters: {
+      name: "",
+      namespaces: [],
+      labels: {},
+      annotations: {},
+    },
+    callback: () => null,
+  };
+  const pod = POD1();
+
+  t.true(shouldSkipRequest(binding, pod));
+});
+
+test("should allow when group, version, and kind match", t => {
+  const binding = {
+    kind: gvkMap.V1Pod,
+    filters: {
+      name: "",
+      namespaces: [],
+      labels: {},
+      annotations: {},
+    },
+    callback: () => null,
+  };
+  const pod = POD1();
+
+  t.false(shouldSkipRequest(binding, pod));
+});
+
+test("should allow when kind match and others are empty", t => {
+  const binding = {
+    kind: {
+      group: "",
+      version: "",
+      kind: "Pod",
+    },
+    filters: {
+      name: "",
+      namespaces: [],
+      labels: {},
+      annotations: {},
+    },
+    callback: () => null,
+  };
+  const pod = POD1();
+
+  t.false(shouldSkipRequest(binding, pod));
+});
+
+test("should reject when namespace does not match", t => {
+  const binding = {
+    kind: gvkMap.V1Pod,
+    filters: {
+      name: "",
+      namespaces: ["bleh"],
+      labels: {},
+      annotations: {},
+    },
+    callback: () => null,
+  };
+  const pod = POD1();
+
+  t.true(shouldSkipRequest(binding, pod));
+});
+
+test("should allow when namespace is match", t => {
+  const binding = {
+    kind: gvkMap.V1Pod,
+    filters: {
+      name: "",
+      namespaces: ["default", "unicorn", "things"],
+      labels: {},
+      annotations: {},
+    },
+    callback: () => null,
+  };
+  const pod = POD1();
+
+  t.false(shouldSkipRequest(binding, pod));
+});
+
+test("should reject when label does not match", t => {
+  const binding = {
+    kind: gvkMap.V1Pod,
+    filters: {
+      name: "",
+      namespaces: [],
+      labels: {
+        foo: "bar",
+      },
+      annotations: {},
+    },
+    callback: () => null,
+  };
+  const pod = POD1();
+
+  t.true(shouldSkipRequest(binding, pod));
+});
+
+test("should allow when label is match", t => {
+  const binding = {
+    kind: gvkMap.V1Pod,
+    filters: {
+      name: "",
+
+      namespaces: [],
+      labels: {
+        foo: "bar",
+        test: "test1",
+      },
+      annotations: {},
+    },
+    callback: () => null,
+  };
+
+  const pod = POD1();
+  pod.object.metadata.labels = {
+    foo: "bar",
+    test: "test1",
+    test2: "test2",
+  };
+
+  t.false(shouldSkipRequest(binding, pod));
+});
+
+test("should reject when annotation does not match", t => {
+  const binding = {
+    kind: gvkMap.V1Pod,
+    filters: {
+      name: "",
+      namespaces: [],
+      labels: {},
+      annotations: {
+        foo: "bar",
+      },
+    },
+    callback: () => null,
+  };
+  const pod = POD1();
+
+  t.true(shouldSkipRequest(binding, pod));
+});
+
+test("should allow when annotation is match", t => {
+  const binding = {
+    kind: gvkMap.V1Pod,
+    filters: {
+      name: "",
+      namespaces: [],
+      labels: {},
+      annotations: {
+        foo: "bar",
+        test: "test1",
+      },
+    },
+    callback: () => null,
+  };
+
+  const pod = POD1();
+  pod.object.metadata.annotations = {
+    foo: "bar",
+    test: "test1",
+    test2: "test2",
+  };
+
+  t.false(shouldSkipRequest(binding, pod));
+});

package/src/lib/filter.ts

@@ -0,0 +1,55 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+
+import { Request } from "./k8s";
+import logger from "./logger";
+import { Binding } from "./types";
+
+/**
+ * shouldSkipRequest determines if a request should be skipped based on the binding filters.
+ *
+ * @param binding the capability action binding
+ * @param req the incoming request
+ * @returns
+ */
+export function shouldSkipRequest(binding: Binding, req: Request) {
+  const { group, kind, version } = binding.kind;
+  const { namespaces, labels, annotations } = binding.filters;
+  const { metadata } = req.object;
+
+  if (kind !== req.kind.kind) {
+    logger.debug(`${req.kind.kind} does not match ${kind}`);
+    return true;
+  }
+
+  if (group && group !== req.kind.group) {
+    logger.debug(`${req.kind.group} does not match ${group}`);
+    return true;
+  }
+
+  if (version && version !== req.kind.version) {
+    logger.debug(`${req.kind.version} does not match ${version}`);
+    return true;
+  }
+
+  if (namespaces.length && !namespaces.includes(req.namespace || "")) {
+    logger.debug(`${req.namespace} is not in ${namespaces}`);
+    return true;
+  }
+
+  for (const [key, value] of Object.entries(labels)) {
+    if (metadata?.labels?.[key] !== value) {
+      logger.debug(`${metadata?.labels?.[key]} does not match ${value}`);
+      return true;
+    }
+  }
+
+  for (const [key, value] of Object.entries(annotations)) {
+    if (metadata?.annotations?.[key] !== value) {
+      logger.debug(`${metadata?.annotations?.[key]} does not match ${value}`);
+      return true;
+    }
+  }
+
+  return false;
+}

package/src/lib/index.ts

@@ -0,0 +1,10 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+
+import logger from "./logger";
+
+export { logger as Log };
+export * from "./capability";
+export * from "./request";
+export * from "./module";
+export * from "./types";

package/src/lib/k8s/index.ts

@@ -0,0 +1,10 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+
+// Export kinds as a single object
+import * as kind from "./upstream";
+export { kind as a };
+
+export { modelToGroupVersionKind, gvkMap } from "./kinds";
+
+export * from "./types";