pepr 0.14.2 → 0.16.0

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.

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

@@ -0,0 +1,189 @@
+---
+title: WebAssembly
+linkTitle: WebAssembly
+---
+
+# WASM Support: Running WebAssembly in Pepr Guide
+
+Pepr fully supports WebAssembly. Depending on the language used to generate the WASM, certain files can be too large to fit into a `Secret` or `ConfigMap`. Due to this limitation, users have the ability to incorporate `*.wasm` and any other essential files during the build phase, which are then embedded into the Pepr Controller container. This is achieved through adding an array of files to the `includedFiles` section under `pepr` in the `package.json`.
+
+> **NOTE -** In order to instantiate the WebAsembly module in TypeScript, you need the WebAssembly type. This is accomplished through add the "DOM" to the `lib` array in the `compilerOptions` section of the `tsconfig.json`. Ex: `"lib": ["ES2022", "DOM"]`. Be aware that adding the DOM will add a lot of extra types to your project and your developer experience will be impacted in terms of the intellisense. 
+
+
+## High-Level Overview
+
+WASM support is achieved through adding files as layers atop the Pepr controller image, these files are then able to be read by the individual capabilities. The key components of WASM support are:
+
+- Add files to the **base** of the Pepr module.
+- Reference the files in the `includedFiles` section of the `pepr` block of the `package.json` 
+- Run `npx pepr build` with the `-r ` option specifying registry info. Ex: `npx pepr build -r docker.io/cmwylie19`
+- Pepr builds and pushes a custom image that is used in the `Deployment`.
+
+## Using WASM Support 
+
+### Creating a WASM Module in Go
+
+Create a simple Go function that you want to call from your Pepr module
+
+```go
+package main
+
+import (
+	"fmt"
+	"syscall/js"
+)
+
+func concats(this js.Value, args []js.Value) interface{} {
+    fmt.Println("PeprWASM!")
+	stringOne := args[0].String()
+	stringTwo := args[1].String()
+	return fmt.Sprintf("%s%s", stringOne, stringTwo)
+}
+
+func main() {
+	done := make(chan struct{}, 0)
+	js.Global().Set("concats", js.FuncOf(concats))
+	<-done
+}
+```
+
+Compile it to a wasm target and move it to your Pepr module
+
+```bash
+GOOS=js GOARCH=wasm go build -o main.wasm
+cp main.wasm $YOUR_PEPR_MODULE/
+```
+
+Copy the `wasm_exec.js` from `GOROOT` to your Pepr Module
+
+```bash
+cp "$(go env GOROOT)/misc/wasm/wasm_exec.js" $YOUR_PEPR_MODULE/
+```
+
+Update the polyfill to add `globalThis.crypto` in the `wasm_exec.js` since we are not running in the browser. This is needed directly under: `(() => {`
+
+
+```javascript
+// Initialize the polyfill
+if (typeof globalThis.crypto === 'undefined') {
+    globalThis.crypto = {
+        getRandomValues: (array) => {
+        for (let i = 0; i < array.length; i++) {
+            array[i] = Math.floor(Math.random() * 256);
+        }
+        },
+    };
+}
+```
+
+
+### Configure Pepr to use WASM
+
+After adding the files to the root of the Pepr module, reference those files in the `package.json`:
+
+```json
+{
+  "name": "pepr-test-module",
+  "version": "0.0.1",
+  "description": "A test module for Pepr",
+  "keywords": [
+    "pepr",
+    "k8s",
+    "policy-engine",
+    "pepr-module",
+    "security"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "pepr": {
+    "name": "pepr-test-module",
+    "uuid": "static-test",
+    "onError": "ignore",
+    "alwaysIgnore": {
+      "namespaces": [],
+      "labels": []
+    },
+    "includedFiles":[
+      "main.wasm",
+      "wasm_exec.js"
+    ]
+  },
+  ...
+}
+```
+
+Update the `tsconfig.json` to add "DOM" to the `compilerOptions` lib:
+
+```json
+{
+  "compilerOptions": {
+    "allowSyntheticDefaultImports": true,
+    "declaration": true,
+    "declarationMap": true,
+    "emitDeclarationOnly": true,
+    "esModuleInterop": true,
+    "lib": [
+      "ES2022",
+      "DOM" // <- Add this
+    ],
+    "module": "CommonJS",
+    "moduleResolution": "node",
+    "outDir": "dist",
+    "resolveJsonModule": true,
+    "rootDir": ".",
+    "strict": false,
+    "target": "ES2022",
+    "useUnknownInCatchVariables": false
+  },
+  "include": [
+    "**/*.ts"
+  ]
+}
+```
+
+### Call WASM functions from TypeScript
+
+Import the `wasm_exec.js` in the `pepr.ts`
+
+```javascript
+import "./wasm_exec.js";
+```
+
+Create a helper function to load the wasm file in a capability and call it during an event of your choice
+
+```typescript
+async function callWASM(a,b) {
+  const go = new globalThis.Go();
+
+  const wasmData = readFileSync("main.wasm");
+  var concated: string;
+
+  await WebAssembly.instantiate(wasmData, go.importObject).then(wasmModule => {
+    go.run(wasmModule.instance);
+  
+    concated = global.concats(a,b);
+  });
+  return concated;
+}
+
+When(a.Pod)
+.IsCreated()
+.Mutate(async pod => {
+  try {
+    let label_value = await callWASM("loves","wasm")
+    pod.SetLabel("pepr",label_value)
+  } 
+  catch(err) {
+    Log.error(err);
+  }
+});
+```
+
+### Run Pepr Build 
+
+Build your Pepr module with the registry specified.
+
+```bash
+npx pepr build -r docker.io/defenseunicorns
+```

package/website/go.mod

@@ -0,0 +1,8 @@
+module main
+
+go 1.20
+
+require (
+	github.com/defenseunicorns/defense-unicorns-hugo-theme v0.3.9 // indirect
+	github.com/defenseunicorns/defense-unicorns-hugo-theme/dependencies v0.3.9 // indirect
+)

package/website/go.sum

@@ -0,0 +1,4 @@
+github.com/defenseunicorns/defense-unicorns-hugo-theme v0.3.9 h1:o2ptq0ozp8x5R61Ik0E08YI3VEBjJGwUvKs8sRleUC8=
+github.com/defenseunicorns/defense-unicorns-hugo-theme v0.3.9/go.mod h1:qOBlMoMnovWO8PwmHAlpR7WfPLOJiiq4+XIrVblRb8g=
+github.com/defenseunicorns/defense-unicorns-hugo-theme/dependencies v0.3.9 h1:nz4Aiu+ISXKESXgTjPyDyR9L708XjszH6lnQAGFAAVI=
+github.com/defenseunicorns/defense-unicorns-hugo-theme/dependencies v0.3.9/go.mod h1:zQT7gnRyPnVCNxREasYkyewPJLhemxlOGZhbu+9mcfQ=