pepr 0.15.0 → 0.17.0

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

@@ -2,6 +2,7 @@
 // SPDX-FileCopyrightText: 2023-Present The Pepr Authors
 
 import { CapabilityExport } from "./types";
+import { promises as fs } from "fs";
 
 type RBACMap = {
   [key: string]: {
@@ -37,3 +38,15 @@ export const createRBACMap = (capabilities: CapabilityExport[]): RBACMap => {
     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/website/assets/scss/_variables_project.scss

@@ -1 +1 @@
-$secondary: #EFCA81;
+$secondary: #EFCA81;

package/website/content/en/docs/OnSchedule.md

@@ -0,0 +1,86 @@
+---
+title: OnSchedule
+linkTitle: OnSchedule
+---
+
+# OnSchedule
+
+The `OnSchedule` feature allows you to schedule and automate the execution of specific code at predefined intervals or schedules. This feature is designed to simplify recurring tasks and can serve as an alternative to traditional CronJobs. This code is designed to be run at the top level on a Capability, not within a function like `When`. 
+  
+> **Note -** To use this feature in dev mode you MUST set `PEPR_WATCH_MODE="true"`. This is because the scheduler only runs on the watch controller and the watch controller is not started by default in dev mode.
+
+For example: `PEPR_WATCH_MODE="true" npx pepr dev`
+
+## Best Practices
+
+`OnSchedule` is designed for targeting intervals equal to or larger than 30 seconds due to the storage mechanism used to archive schedule info.
+  
+## Usage
+
+Create a recurring task execution by calling the OnSchedule function with the following parameters:
+
+**name** - The unique name of the schedule.
+
+**every** - An integer that represents the frequency of the schedule in number of _units_.
+
+**unit** - A string specifying the time unit for the schedule (e.g., `seconds`, `minute`, `minutes`, `hour`, `hours`). 
+
+**startTime** - (Optional) A UTC timestamp indicating when the schedule should start. All date times must be provided in GMT. If not specified the schedule will start when the schedule store reports ready.
+
+**run** - A function that contains the code you want to execute on the defined schedule.  
+
+**completions** - (Optional) An integer indicating the maximum number of times the schedule should run to completion. If not specified the schedule will run indefinitely.
+
+
+## Examples
+
+Update the curr ConfigMap every 15 seconds and use the store to track the current count:
+
+```typescript
+OnSchedule({
+    name: "hello-interval",
+    every: 30,
+    unit: "seconds",
+    run: async () => {
+      Log.info("Wait 30 seconds and create/update a ConfigMap");
+
+      try {
+        await K8s(kind.ConfigMap).Apply({
+          metadata: {
+            name: "last-updated",
+            namespace: "default",
+          },
+          data: {
+            count: `${new Date()}`,
+          },
+        });
+
+      } catch (error) {
+        Log.error(error, "Failed to apply ConfigMap using server-side apply.");
+      }
+    },
+  });
+```
+
+Refresh an AWSToken every 24 hours, with a delayed start of 30 seconds, running a total of 3 times:
+
+```typescript
+
+OnSchedule({
+  name: "refresh-aws-token",
+  every: 24,
+  unit: "hours",
+  startTime: new Date(new Date().getTime() + 1000 * 30),
+  run: async () => {
+    await RefreshAWSToken();
+  },
+  completions: 3,
+});
+```
+
+## Advantages 
+
+- Simplifies scheduling recurring tasks without the need for complex CronJob configurations.
+- Provides flexibility to define schedules in a human-readable format.
+- Allows you to execute code with precision at specified intervals.
+- Supports limiting the number of schedule completions for finite tasks.

package/website/content/en/docs/cli.md

@@ -59,6 +59,9 @@ Create a [zarf.yaml](https://zarf.dev) and K8s manifest for the current module.
 
 **Options:**
 
-- `-r, --registry-info [<registry>/<username>]` - Registry Info: Image registry and username. Note: You must be signed into the registry
-- `--rbac-mode [admin|scoped]` - Rbac Mode: admin, scoped (default: admin)
 - `-l, --log-level [level]` - Log level: debug, info, warn, error (default: "info")
+- `-e, --entry-point [file]` - Specify the entry point file to build with. (default: "pepr.ts")
+- `-n, --no-embed` - Disables embedding of deployment files into output module. Useful when creating library modules intended solely for reuse/distribution via NPM
+- `-r, --registry-info [<registry>/<username>]` - Registry Info: Image registry and username. Note: You must be signed into the registry
+- `-o, --output-dir [output directory]` - Define where to place build output
+- `--rbac-mode [admin|scoped]` - Rbac Mode: admin, scoped (default: admin) (choices: "admin", "scoped", default: "admin")

package/website/content/en/docs/store.md

@@ -0,0 +1,48 @@
+---
+title: Store
+linkTitle: Store
+---
+
+# Pepr Store: A Lightweight Key-Value Store for Pepr Modules
+
+The nature of admission controllers and general watch operations (the `Mutate`, `Validate` and `Watch` actions in Pepr) make some types of complex and long-running operations difficult. There are also times when you need to share data between different actions. While you could manually create your own K8s resources and manage their cleanup, this can be very hard to track and keep performant at scale. 
+
+The Pepr Store solves this by exposing a simple, [Web Storage API](https://developer.mozilla.org/en-US/docs/Web/API/Storage)-compatible mechanism for use within capabilities. Additionally, as Pepr runs multiple replicas of the admission controller along with a watch controller, the Pepr Store provides a unique way to share data between these different instances automatically.
+
+Each Pepr Capability has a `Store` instance that can be used to get, set and delete data as well as subscribe to any changes to the Store. Behind the scenes, all capability store instances in a single Pepr Module are stored within a single CRD in the cluster. This CRD is automatically created when the Pepr Module is deployed. Care is taken to make the read and write operations as efficient as possible by using K8s watches, batch processing and patch operations for writes.
+
+## Key Features
+
+- **Asynchronous Key-Value Store**: Provides an asynchronous interface for storing small amounts of data, making it ideal for sharing information between various actions and capabilities.
+- **Web Storage API Compatibility**: The store's API is aligned with the standard [Web Storage API](https://developer.mozilla.org/en-US/docs/Web/API/Storage), simplifying the learning curve.
+- **Real-time Updates**: The `.subscribe()` and `onReady()` methods enable real-time updates, allowing you to react to changes in the data store instantaneously.
+
+- **Automatic CRD Management**: Each Pepr Module has its data stored within a single Custom Resource Definition (CRD) that is automatically created upon deployment.
+- **Efficient Operations**: Pepr Store uses Kubernetes watches, batch processing, and patch operations to make read and write operations as efficient as possible.
+
+## Quick Start
+
+```typescript
+// Example usage for Pepr Store
+Store.setItem("example-1", "was-here");
+Store.setItem("example-1-data", JSON.stringify(request.Raw.data));
+Store.onReady(data => {
+  Log.info(data, "Pepr Store Ready");
+});
+const unsubscribe = Store.subscribe(data => {
+  Log.info(data, "Pepr Store Updated");
+  unsubscribe();
+});
+```
+
+## API Reference
+
+### Methods
+
+- `getItem(key: string)`: Retrieves a value by its key. Returns `null` if the key doesn't exist.
+- `setItem(key: string, value: string)`: Sets a value for a given key. Creates a new key-value pair if the key doesn't exist.
+- `setItemAndWait(key: string, value: string)`: Sets a value for a given key. Creates a new key-value pair if the key doesn't exist. Returns a promise when the new key and value show up in the store. Should only be used on a `Watch` to avoid [timeouts](https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/#timeouts).
+- `removeItem(key: string)`: Deletes a key-value pair by its key.
+- `clear()`: Clears all key-value pairs from the store.
+- `subscribe(listener: DataReceiver)`: Subscribes to store updates.
+- `onReady(callback: DataReceiver)`: Executes a callback when the store is ready.