pepr 0.14.2 → 0.16.0

package/src/lib/assets/rbac.ts

@@ -2,26 +2,42 @@
 // SPDX-FileCopyrightText: 2023-Present The Pepr Authors
 
 import { kind } from "kubernetes-fluent-client";
-
+import { CapabilityExport } from "../types";
+import { createRBACMap } from "../helpers";
 /**
  * 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
  */
-export function clusterRole(name: string): kind.ClusterRole {
+export function clusterRole(name: string, capabilities: CapabilityExport[], rbacMode: string = ""): kind.ClusterRole {
+  const rbacMap = createRBACMap(capabilities);
   return {
     apiVersion: "rbac.authorization.k8s.io/v1",
     kind: "ClusterRole",
     metadata: { name },
-    rules: [
-      {
-        // @todo: make this configurable
-        apiGroups: ["*"],
-        resources: ["*"],
-        verbs: ["create", "delete", "get", "list", "patch", "update", "watch"],
-      },
-    ],
+    rules:
+      rbacMode === "scoped"
+        ? [
+            ...Object.keys(rbacMap).map(key => {
+              // let group:string, version:string, kind:string;
+              let group: string;
+              key.split("/").length < 3 ? (group = "") : (group = key.split("/")[0]);
+
+              return {
+                apiGroups: [group],
+                resources: [rbacMap[key].plural],
+                verbs: rbacMap[key].verbs,
+              };
+            }),
+          ]
+        : [
+            {
+              apiGroups: ["*"],
+              resources: ["*"],
+              verbs: ["create", "delete", "get", "list", "patch", "update", "watch"],
+            },
+          ],
   };
 }
 
@@ -64,7 +80,7 @@ export function storeRole(name: string): kind.Role {
     metadata: { name, namespace: "pepr-system" },
     rules: [
       {
-        apiGroups: ["pepr.dev/*"],
+        apiGroups: ["pepr.dev"],
         resources: ["peprstores"],
         resourceNames: [""],
         verbs: ["create", "get", "patch", "watch"],

package/src/lib/assets/yaml.ts

@@ -40,7 +40,7 @@ export function zarfYaml({ name, image, config }: Assets, path: string) {
   return dumpYaml(zarfCfg, { noRefs: true });
 }
 
-export async function allYaml(assets: Assets) {
+export async function allYaml(assets: Assets, rbacMode: string) {
   const { name, tls, apiToken, path } = assets;
 
   const code = await fs.readFile(path);
@@ -54,7 +54,7 @@ export async function allYaml(assets: Assets) {
 
   const resources = [
     namespace,
-    clusterRole(name),
+    clusterRole(name, assets.capabilities, rbacMode),
     clusterRoleBinding(name),
     serviceAccount(name),
     apiTokenSecret(name, apiToken),

package/src/lib/capability.ts

@@ -8,6 +8,7 @@ import { pickBy } from "ramda";
 import Log from "./logger";
 import { isBuildMode, isDevMode, isWatchMode } from "./module";
 import { PeprStore, Storage } from "./storage";
+import { OnSchedule, Schedule } from "./schedule";
 import {
   Binding,
   BindingFilter,
@@ -34,7 +35,39 @@ export class Capability implements CapabilityExport {
   #namespaces?: string[] | undefined;
   #bindings: Binding[] = [];
   #store = new Storage();
+  #scheduleStore = new Storage();
   #registered = false;
+  #scheduleRegistered = false;
+  hasSchedule: boolean;
+
+  /**
+   * Run code on a schedule with the capability.
+   *
+   * @param schedule The schedule to run the code on
+   * @returns
+   */
+  OnSchedule: (schedule: Schedule) => void = (schedule: Schedule) => {
+    const { name, every, unit, run, startTime, completions } = schedule;
+
+    if (process.env.PEPR_WATCH_MODE === "true") {
+      // Only create/watch schedule store if necessary
+      this.hasSchedule = true;
+
+      // Create a new schedule
+      const newSchedule: Schedule = {
+        name,
+        every,
+        unit,
+        run,
+        startTime,
+        completions,
+      };
+
+      this.#scheduleStore.onReady(() => {
+        new OnSchedule(newSchedule).setStore(this.#scheduleStore);
+      });
+    }
+  };
 
   /**
    * Store is a key-value data store that can be used to persist data that should be shared
@@ -50,6 +83,24 @@ export class Capability implements CapabilityExport {
     setItem: this.#store.setItem,
     subscribe: this.#store.subscribe,
     onReady: this.#store.onReady,
+    setItemAndWait: this.#store.setItemAndWait,
+  };
+
+  /**
+   * ScheduleStore is a key-value data store used to persist schedule data that should be shared
+   * between intervals. Each Schedule shares store, and the data is persisted in Kubernetes
+   * in the `pepr-system` namespace.
+   *
+   * Note: There is no direct access to schedule store
+   */
+  ScheduleStore: PeprStore = {
+    clear: this.#scheduleStore.clear,
+    getItem: this.#scheduleStore.getItem,
+    removeItem: this.#scheduleStore.removeItem,
+    setItemAndWait: this.#scheduleStore.setItemAndWait,
+    setItem: this.#scheduleStore.setItem,
+    subscribe: this.#scheduleStore.subscribe,
+    onReady: this.#scheduleStore.onReady,
   };
 
   get bindings() {
@@ -72,11 +123,32 @@ export class Capability implements CapabilityExport {
     this.#name = cfg.name;
     this.#description = cfg.description;
     this.#namespaces = cfg.namespaces;
+    this.hasSchedule = false;
 
     Log.info(`Capability ${this.#name} registered`);
     Log.debug(cfg);
   }
 
+  /**
+   * Register the store with the capability. This is called automatically by the Pepr controller.
+   *
+   * @param store
+   */
+  registerScheduleStore = () => {
+    Log.info(`Registering schedule store for ${this.#name}`);
+
+    if (this.#scheduleRegistered) {
+      throw new Error(`Schedule store already registered for ${this.#name}`);
+    }
+
+    this.#scheduleRegistered = true;
+
+    // Pass back any ready callback to the controller
+    return {
+      scheduleStore: this.#scheduleStore,
+    };
+  };
+
   /**
    * Register the store with the capability. This is called automatically by the Pepr controller.
    *

package/src/lib/controller/index.ts

@@ -44,10 +44,14 @@ export class Controller {
     this.#capabilities = capabilities;
 
     // Initialize the Pepr store for each capability
-    new PeprControllerStore(config, capabilities, () => {
+    new PeprControllerStore(config, capabilities, `pepr-${config.uuid}-store`, () => {
       this.#bindEndpoints();
       onReady && onReady();
       Log.info("✅ Controller startup complete");
+      // Initialize the schedule store for each capability
+      new PeprControllerStore(config, capabilities, `pepr-${config.uuid}-schedule`, () => {
+        Log.info("✅ Scheduling processed");
+      });
     });
 
     // Middleware for logging requests

package/src/lib/controller/store.ts

@@ -12,7 +12,7 @@ import { ModuleConfig } from "../module";
 import { DataOp, DataSender, DataStore, Storage } from "../storage";
 
 const namespace = "pepr-system";
-const debounceBackoff = 5000;
+export const debounceBackoff = 5000;
 
 export class PeprControllerStore {
   #name: string;
@@ -20,22 +20,40 @@ export class PeprControllerStore {
   #sendDebounce: NodeJS.Timeout | undefined;
   #onReady?: () => void;
 
-  constructor(config: ModuleConfig, capabilities: Capability[], onReady?: () => void) {
+  constructor(config: ModuleConfig, capabilities: Capability[], name: string, onReady?: () => void) {
     this.#onReady = onReady;
 
     // Setup Pepr State bindings
-    this.#name = `pepr-${config.uuid}-store`;
+    this.#name = name;
+
+    if (name.includes("schedule")) {
+      // Establish the store for each capability
+      for (const { name, registerScheduleStore, hasSchedule } of capabilities) {
+        // Guard Clause to exit  early
+        if (hasSchedule !== true) {
+          return;
+        }
+        // Register the scheduleStore with the capability
+        const { scheduleStore } = registerScheduleStore();
+
+        // Bind the store sender to the capability
+        scheduleStore.registerSender(this.#send(name));
 
-    // Establish the store for each capability
-    for (const { name, registerStore } of capabilities) {
-      // Register the store with the capability
-      const { store } = registerStore();
+        // Store the storage instance
+        this.#stores[name] = scheduleStore;
+      }
+    } else {
+      // Establish the store for each capability
+      for (const { name, registerStore } of capabilities) {
+        // Register the store with the capability
+        const { store } = registerStore();
 
-      // Bind the store sender to the capability
-      store.registerSender(this.#send(name));
+        // Bind the store sender to the capability
+        store.registerSender(this.#send(name));
 
-      // Store the storage instance
-      this.#stores[name] = store;
+        // Store the storage instance
+        this.#stores[name] = store;
+      }
     }
 
     // Add a jitter to the Store creation to avoid collisions

package/src/lib/helpers.ts

@@ -0,0 +1,52 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+
+import { CapabilityExport } from "./types";
+import { promises as fs } from "fs";
+
+type RBACMap = {
+  [key: string]: {
+    verbs: string[];
+    plural: string;
+  };
+};
+
+export const addVerbIfNotExists = (verbs: string[], verb: string) => {
+  if (!verbs.includes(verb)) {
+    verbs.push(verb);
+  }
+};
+
+export const createRBACMap = (capabilities: CapabilityExport[]): RBACMap => {
+  return capabilities.reduce((acc: RBACMap, capability: CapabilityExport) => {
+    capability.bindings.forEach(binding => {
+      const key = `${binding.kind.group}/${binding.kind.version}/${binding.kind.kind}`;
+
+      acc["pepr.dev/v1/peprstore"] = {
+        verbs: ["create", "get", "patch", "watch"],
+        plural: "peprstores",
+      };
+
+      if (!acc[key] && binding.isWatch) {
+        acc[key] = {
+          verbs: ["watch"],
+          plural: binding.kind.plural || `${binding.kind.kind.toLowerCase()}s`,
+        };
+      }
+    });
+
+    return acc;
+  }, {});
+};
+
+export async function createDirectoryIfNotExists(path: string) {
+  try {
+    await fs.access(path);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      await fs.mkdir(path, { recursive: true });
+    } else {
+      throw error;
+    }
+  }
+}

package/src/lib/module.ts

@@ -87,6 +87,7 @@ export class PeprModule {
           description: capability.description,
           namespaces: capability.namespaces,
           bindings: capability.bindings,
+          hasSchedule: capability.hasSchedule,
         });
       }
 

package/src/lib/schedule.ts

@@ -0,0 +1,175 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+
+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 class OnSchedule implements Schedule {
+  intervalId: NodeJS.Timeout | null = 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) {
+    this.name = schedule.name;
+    this.run = schedule.run;
+    this.every = schedule.every;
+    this.unit = schedule.unit;
+    this.startTime = schedule?.startTime;
+    this.completions = schedule?.completions;
+  }
+  setStore(store: PeprStore) {
+    this.store = store;
+    this.startInterval();
+  }
+  startInterval() {
+    this.checkStore();
+    this.getDuration();
+    this.setupInterval();
+  }
+  /**
+   * Checks the store for this schedule and sets the values if it exists
+   * @returns
+   */
+  checkStore() {
+    const result = this.store && this.store.getItem(this.name);
+    if (result) {
+      const storedSchedule = JSON.parse(result);
+      this.completions = storedSchedule?.completions;
+      this.startTime = storedSchedule?.startTime;
+      this.lastTimestamp = storedSchedule?.lastTimestamp;
+    }
+  }
+
+  /**
+   * Saves the schedule to the store
+   * @returns
+   */
+  saveToStore() {
+    const schedule = {
+      completions: this.completions,
+      startTime: this.startTime,
+      lastTimestamp: new Date(),
+      name: this.name,
+    };
+    this.store && this.store.setItem(this.name, JSON.stringify(schedule));
+  }
+
+  /**
+   * Gets the durations in milliseconds
+   */
+  getDuration() {
+    switch (this.unit) {
+      case "seconds":
+        if (this.every < 10) throw new Error("10 Seconds in the smallest interval allowed");
+        this.duration = 1000 * this.every;
+        break;
+      case "minutes":
+      case "minute":
+        this.duration = 1000 * 60 * this.every;
+        break;
+      case "hours":
+      case "hour":
+        this.duration = 1000 * 60 * 60 * this.every;
+        break;
+      default:
+        throw new Error("Invalid time unit");
+    }
+  }
+
+  /**
+   * Sets up the interval
+   */
+  setupInterval() {
+    const now = new Date();
+    let delay: number | undefined;
+
+    if (this.lastTimestamp && this.startTime) {
+      this.startTime = undefined;
+    }
+
+    if (this.startTime) {
+      delay = this.startTime.getTime() - now.getTime();
+    } else if (this.lastTimestamp && this.duration) {
+      const lastTimestamp = new Date(this.lastTimestamp);
+      delay = this.duration - (now.getTime() - lastTimestamp.getTime());
+    }
+
+    if (delay === undefined || delay <= 0) {
+      this.start();
+    } else {
+      setTimeout(() => {
+        this.start();
+      }, delay);
+    }
+  }
+
+  /**
+   * Starts the interval
+   */
+  start() {
+    this.intervalId = setInterval(() => {
+      if (this.completions === 0) {
+        this.stop();
+        return;
+      } else {
+        this.run();
+
+        if (this.completions && this.completions !== 0) {
+          this.completions -= 1;
+        }
+        this.saveToStore();
+      }
+    }, this.duration);
+  }
+
+  /**
+   * Stops the interval
+   */
+  stop() {
+    if (this.intervalId) {
+      clearInterval(this.intervalId);
+      this.intervalId = null;
+    }
+    this.store && this.store.removeItem(this.name);
+  }
+}

package/src/lib/storage.ts

@@ -10,6 +10,7 @@ export type DataSender = (op: DataOp, keys: string[], value?: string) => void;
 export type DataReceiver = (data: DataStore) => void;
 export type Unsubscribe = () => void;
 
+const MAX_WAIT_TIME = 15000;
 export interface PeprStore {
   /**
    * Returns the current value associated with the given key, or null if the given key does not exist.
@@ -40,6 +41,12 @@ export interface PeprStore {
    * 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>;
 }
 
 /**
@@ -88,6 +95,32 @@ export class Storage implements PeprStore {
     this.#dispatchUpdate("add", [key], value);
   };
 
+  /**
+   * 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) => {
+    this.#dispatchUpdate("add", [key], value);
+    return new Promise<void>((resolve, reject) => {
+      const unsubscribe = this.subscribe(data => {
+        if (data[key] === value) {
+          unsubscribe();
+          resolve();
+        }
+      });
+
+      // If promise has not resolved before MAX_WAIT_TIME reject
+      setTimeout(() => {
+        unsubscribe();
+        return reject();
+      }, MAX_WAIT_TIME);
+    });
+  };
+
   subscribe = (subscriber: DataReceiver) => {
     const idx = this.#subscriberId++;
     this.#subscribers[idx] = subscriber;

package/src/lib/types.ts

@@ -43,6 +43,7 @@ export interface CapabilityCfg {
 
 export interface CapabilityExport extends CapabilityCfg {
   bindings: Binding[];
+  hasSchedule: boolean;
 }
 
 export type WhenSelector<T extends GenericClass> = {

package/src/lib.ts

@@ -1,32 +1,25 @@
-import { K8s, RegisterKind, fetch, kind, kind as a, fetchStatus } from "kubernetes-fluent-client";
+import { K8s, RegisterKind, kind as a, fetch, fetchStatus, kind } from "kubernetes-fluent-client";
 import * as R from "ramda";
 
 import { Capability } from "./lib/capability";
 import Log from "./lib/logger";
 import { PeprModule } from "./lib/module";
 import { PeprMutateRequest } from "./lib/mutate-request";
-import { PeprValidateRequest } from "./lib/validate-request";
 import * as PeprUtils from "./lib/utils";
-
-// Import type information for external packages
-import type * as RTypes from "ramda";
+import { PeprValidateRequest } from "./lib/validate-request";
 
 export {
-  a,
-  kind,
-  /** PeprModule is used to setup a complete Pepr Module: `new PeprModule(cfg, {...capabilities})` */
+  Capability,
+  K8s,
+  Log,
   PeprModule,
   PeprMutateRequest,
-  PeprValidateRequest,
   PeprUtils,
-  RegisterKind,
-  K8s,
-  Capability,
-  Log,
+  PeprValidateRequest,
   R,
+  RegisterKind,
+  a,
   fetch,
   fetchStatus,
-
-  // Export the imported type information for external packages
-  RTypes,
+  kind,
 };

package/src/templates/capabilities/hello-pepr.ts

@@ -52,19 +52,24 @@ When(a.Namespace)
   .Watch(async ns => {
     Log.info("Namespace pepr-demo-2 was created.");
 
+    try {
+      // Apply the ConfigMap using K8s server-side apply
+      await K8s(kind.ConfigMap).Apply({
+        metadata: {
+          name: "pepr-ssa-demo",
+          namespace: "pepr-demo-2",
+        },
+        data: {
+          "ns-uid": ns.metadata.uid,
+        },
+      });
+    } catch (error) {
+      // You can use the Log object to log messages to the Pepr controller pod
+      Log.error(error, "Failed to apply ConfigMap using server-side apply.");
+    }
+
     // You can share data between actions using the Store, including between different types of actions
     Store.setItem("watch-data", "This data was stored by a Watch Action.");
-
-    // Apply the ConfigMap using K8s server-side apply
-    await K8s(kind.ConfigMap).Apply({
-      metadata: {
-        name: "pepr-ssa-demo",
-        namespace: "pepr-demo-2",
-      },
-      data: {
-        "ns-uid": ns.metadata.uid,
-      },
-    });
   });
 
 /**

package/website/.linkinator.config.json

@@ -0,0 +1,8 @@
+{
+  "recurse": true,
+  "skip": "^(https://example.com), ^(https://github.com), ^(https://twitter.com)",
+  "verbosity": "error",
+  "timeout": 0,
+  "markdown": true,
+  "directoryListing": true
+}

package/website/.markdownlint.json

@@ -0,0 +1,6 @@
+{
+  "default": true,
+  "MD033": false,
+  "MD013": false,
+  "MD036": false
+}

package/website/.prettierignore

@@ -0,0 +1,12 @@
+public/
+node_modules/
+.cache
+.history
+dist
+coverage
+docs/app
+__mocks__
+userguide/
+.release-please-manifest.json
+CHANGELOG.md
+.vscode/