Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: fix typo dom intellisense discussion #318

Merged
merged 12 commits into from
Oct 19, 2023
118 changes: 75 additions & 43 deletions docs/webassembly.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,13 @@
# WASM Support: Introducing WebAssembly to Pepr Guide
# 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.

Pepr now supports embedding `*.wasm` files into your Pepr modules during the build process. This is achieved through adding an array of files to the `includedFiles` section under `pepr` in the `package.json`.

## High-Level Overview

At its core, WASM support is achieved through adding layers on top of the Pepr controller image accesible by the module. The key components of WASM support are:
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`
Expand Down Expand Up @@ -68,7 +71,73 @@ if (typeof globalThis.crypto === 'undefined') {
}
```

### Calling WASM from the Capability

### 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`

Expand All @@ -88,7 +157,7 @@ async function callWASM(a,b) {
await WebAssembly.instantiate(wasmData, go.importObject).then(wasmModule => {
go.run(wasmModule.instance);

concated = global.peprWasm(a,b);
concated = global.concats(a,b);
});
return concated;
}
Expand All @@ -106,47 +175,10 @@ When(a.Pod)
});
```

### Updating the package.json

After adding the files to the root (adjacent to `pepr.ts`) 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"
]
},
...
}
```

### Run Pepr Build

Build your Pepr module with registry into specified.
Build your Pepr module with the registry specified.

```bash
npx pepr build -r docker.io/defenseunicorns
```

2 changes: 1 addition & 1 deletion src/templates/tsconfig.module.json
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
"declarationMap": true,
"emitDeclarationOnly": true,
"esModuleInterop": true,
"lib": ["ES2022", "DOM"],
"lib": ["ES2022"],
"module": "CommonJS",
"moduleResolution": "node",
"outDir": "dist",
Expand Down