@gcoredev/proxy-wasm-sdk-as 1.2.1 → 1.2.3

package/README.md

@@ -66,7 +66,7 @@ class AddHeader extends Context {
     } else {
       stream_context.headers.response.add(
         "hello",
-        root_context.getConfiguration()
+        root_context.getConfiguration(),
       );
     }
     return FilterHeadersStatusValues.Continue;
@@ -99,8 +99,26 @@ Please see [Envoy.md](./ENVOY.md)
 
 ## Examples
 
-For more examples on how to use this `proxy-wasm-sdk-as` please see our [examples repo](https://github.com/G-Core/FastEdge-examples/tree/main/assemblyscript)
+The `examples/` directory contains standalone examples demonstrating common use cases. Each example has its own `package.json`, `asconfig.json`, and `README.md`.
 
-## License
+To build any example:
 
-[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2FG-Core%2Fproxy-wasm-sdk-as.svg?type=large)](https://app.fossa.com/projects/git%2Bgithub.com%2FG-Core%2Fproxy-wasm-sdk-as?ref=badge_large)
+```sh
+cd examples/<name>
+pnpm install
+pnpm run asbuild
+```
+
+The compiled binary (`build/<name>.wasm`) can then be uploaded to the [FastEdge portal](https://portal.gcore.com).
+
+| Example                                                | Description                                                        |
+| ------------------------------------------------------ | ------------------------------------------------------------------ |
+| [body](./examples/body)                                | Read and modify request and response bodies                        |
+| [geoBlock](./examples/geoBlock)                        | Block requests from specific countries using a `BLACKLIST` env var |
+| [geoRedirect](./examples/geoRedirect)                  | Route requests to different origins based on country code          |
+| [headers](./examples/headers)                          | Add, remove, and replace HTTP request and response headers         |
+| [jwt](./examples/jwt)                                  | Validate a JWT Bearer token using a secret variable                |
+| [kvStore](./examples/kvStore)                          | Query a FastEdge KV Store (get, scan, zrange, zscan, bfExists)     |
+| [logTime](./examples/logTime)                          | Log UTC timestamps at the request and response phases              |
+| [properties](./examples/properties)                    | Read and expose FastEdge runtime properties as response headers    |
+| [variablesAndSecrets](./examples/variablesAndSecrets/) | Access FastEdge environment varibales and secrets at runtime       |

package/assembly/fastedge/dictionary.ts

@@ -0,0 +1,52 @@
+import * as imports from "../imports";
+
+import { globalArrayBufferReference, WasmResultValues } from "../runtime";
+
+/**
+ * Reads an environment variable by name using the WASI environment interface.
+ *
+ * Use this for normal-sized environment variables (under 64 KB). For values
+ * that may exceed the WASI 64 KB limit, use {@link getDictionary} instead.
+ *
+ * @param {string} name - The name of the environment variable.
+ * @returns {string} The value, or an empty string if not found.
+ */
+function getEnv(name: string): string {
+  const hasKey = process.env.has(name);
+  if (hasKey) {
+    return process.env.get(name);
+  }
+  return "";
+}
+
+/**
+ * Reads a dictionary value by name using the proxy-wasm dictionary API
+ * (`proxy_dictionary_get`).
+ *
+ * This bypasses the WASI 64 KB environment variable size limit and should
+ * be used when a value may be larger than 64 KB (e.g. large JSON configs,
+ * PEM certificates, policy documents).
+ *
+ * For normal-sized environment variables, prefer {@link getEnv}.
+ *
+ * @param {string} name - The dictionary key to look up.
+ * @returns {string} The value, or an empty string if not found.
+ */
+function getDictionary(name: string): string {
+  const buffer = String.UTF8.encode(name);
+  const status = imports.proxy_dictionary_get(
+    changetype<usize>(buffer),
+    buffer.byteLength,
+    globalArrayBufferReference.bufferPtr(),
+    globalArrayBufferReference.sizePtr(),
+  );
+  if (status == WasmResultValues.Ok) {
+    const arrBuff = globalArrayBufferReference.toArrayBuffer();
+    if (arrBuff.byteLength > 0) {
+      return String.UTF8.decode(arrBuff);
+    }
+  }
+  return "";
+}
+
+export { getEnv, getDictionary };

package/assembly/fastedge/env.ts

@@ -1,5 +1,5 @@
 /**
- * Function to get the value for the provided environment variable name.
+ * @deprecated Use {@link getEnv} instead. This function will be removed in a future version.
  * @param {string} name - The name of the environment variable.
  * @returns {string} The value of the environment variable.
  */

package/assembly/fastedge/index.ts

@@ -1,3 +1,4 @@
+export * from "./dictionary";
 export * from "./env";
 export * from "./kvStore";
 export * from "./secrets";

package/assembly/fastedge/secrets.ts

@@ -7,13 +7,13 @@ import { globalArrayBufferReference, WasmResultValues } from "../runtime";
  * @param {string} name - The name of the secret variable.
  * @returns {string} The value of the secret variable.
  */
-function getSecretVar(name: string): string {
+function getSecret(name: string): string {
   const buffer = String.UTF8.encode(name);
   const status = imports.proxy_get_secret(
     changetype<usize>(buffer),
     buffer.byteLength,
     globalArrayBufferReference.bufferPtr(),
-    globalArrayBufferReference.sizePtr()
+    globalArrayBufferReference.sizePtr(),
   );
   if (status == WasmResultValues.Ok) {
     const arrBuff = globalArrayBufferReference.toArrayBuffer();
@@ -27,17 +27,17 @@ function getSecretVar(name: string): string {
 /**
  * Function to get the value for the provided secret variable name from a specific slot.
  * @param {string} name - The name of the secret variable.
- * @param {u32} effectiveAt - The slot index of the secret. (effectiveAt >= secret_slots.slot)
+ * @param {u32} effectiveAt - The numeric slot index to retrieve. Slots are defined in the FastEdge UI and are always numeric (e.g. incremental integers, or Date.now()-style values to represent a point in time).
  * @returns {string} The value of the secret variable.
  */
-function getSecretVarEffectiveAt(name: string, effectiveAt: u32): string {
+function getSecretEffectiveAt(name: string, effectiveAt: u32): string {
   const buffer = String.UTF8.encode(name);
   const status = imports.proxy_get_effective_at_secret(
     changetype<usize>(buffer),
     buffer.byteLength,
     effectiveAt,
     globalArrayBufferReference.bufferPtr(),
-    globalArrayBufferReference.sizePtr()
+    globalArrayBufferReference.sizePtr(),
   );
   if (status == WasmResultValues.Ok) {
     const arrBuff = globalArrayBufferReference.toArrayBuffer();
@@ -48,4 +48,28 @@ function getSecretVarEffectiveAt(name: string, effectiveAt: u32): string {
   return "";
 }
 
-export { getSecretVar, getSecretVarEffectiveAt };
+/**
+ * @deprecated Use {@link getSecret} instead. This function will be removed in a future version.
+ * @param {string} name - The name of the secret variable.
+ * @returns {string} The value of the secret variable.
+ */
+function getSecretVar(name: string): string {
+  return getSecret(name);
+}
+
+/**
+ * @deprecated Use {@link getSecretEffectiveAt} instead. This function will be removed in a future version.
+ * @param {string} name - The name of the secret variable.
+ * @param {u32} effectiveAt - The numeric slot index to retrieve. Slots are defined in the FastEdge UI and are always numeric (e.g. incremental integers, or Date.now()-style values to represent a point in time).
+ * @returns {string} The value of the secret variable.
+ */
+function getSecretVarEffectiveAt(name: string, effectiveAt: u32): string {
+  return getSecretEffectiveAt(name, effectiveAt);
+}
+
+export {
+  getSecret,
+  getSecretEffectiveAt,
+  getSecretVar,
+  getSecretVarEffectiveAt,
+};

package/assembly/fastedge/utils/runtime.ts

@@ -11,6 +11,15 @@ function setLogLevel(level: LogLevelValues): void {
   logLevel = level;
 }
 
+const LOG_LEVEL_PREFIXES: string[] = [
+  "[TRACE]",
+  "[DEBUG]",
+  "[INFO]",
+  "[WARN]",
+  "[ERROR]",
+  "[CRITICAL]",
+];
+
 /**
  * Temporary fix for proxy_log not being implemented in FastEdge.
  * The function relies on @assemblyscript/wasi-shim to print to standard output.
@@ -20,6 +29,8 @@ function setLogLevel(level: LogLevelValues): void {
  */
 function log(level: LogLevelValues, logMessage: string): void {
   if (level >= logLevel) {
+    const prefix = LOG_LEVEL_PREFIXES[level];
+    logMessage = `${prefix}: ${logMessage}`;
     process.stdout.write(logMessage + "\n");
   }
 }

package/assembly/imports.ts

@@ -180,6 +180,16 @@ export declare function proxy_call_foreign_function(function_name: ptr<char>,
 
 // FastEdge HOST Apis
 
+// Dictionary
+// @ts-ignore: decorator
+@external("env", "proxy_dictionary_get")
+export declare function proxy_dictionary_get(
+  key_data: usize,
+  key_size: usize,
+  return_value_data: usize,
+  return_value_size: usize
+): u32;
+
 // Secrets
 // @ts-ignore: decorator
 @external("env", "proxy_get_secret")

package/assembly/runtime.ts

@@ -490,7 +490,7 @@ class HeaderStreamManipulator {
   }
 
   /**
-   * Replace a header.
+   * Replace a header value. No-op if the header is not present.
    * @param key the header name.
    * @param value the header value.
    */
@@ -1125,7 +1125,7 @@ export function deleteContext(context_id: u32): void {
 /**
  * Register a root context factory and make it available to the runtime.
  * @param root_context_factory A function that creates a new root context.
- * @param name Paremeter kept for backwards compatibility. It will be ignored.
+ * @param name Accepted for API compatibility with the proxy-wasm spec but ignored by the FastEdge runtime. The value does not need to match any configuration — pass any descriptive string.
  */
 export function registerRootContext(
   context_factory: (context_id: u32) => RootContext,

package/package.json

@@ -1,26 +1,18 @@
 {
   "name": "@gcoredev/proxy-wasm-sdk-as",
   "description": "Use this SDK to write extensions for the proxy WASM ABI",
-  "version": "1.2.1",
+  "version": "1.2.3",
   "main": "assembly/index.ts",
   "scripts": {
     "asbuild:debug": "asc assembly/index.ts --target debug",
     "asbuild:release": "asc assembly/index.ts --target release",
     "asbuild": "npm run asbuild:debug && npm run asbuild:release",
-    "server": "ws --log.format dev",
-    "docs": "typedoc"
+    "generate:docs": "./fastedge-plugin-source/generate-docs.sh"
   },
   "devDependencies": {
     "@assemblyscript/wasi-shim": "^0.1.0",
     "@semantic-release/changelog": "^6.0.3",
-    "assemblyscript": "^0.27.34",
-    "http-server": "^14.1.1",
-    "local-web-server": "^5.4.0",
-    "minimist": ">=1.2.2",
-    "typedoc": "^0.27.7"
-  },
-  "directories": {
-    "doc": "docs"
+    "assemblyscript": "^0.28.9"
   },
   "repository": {
     "type": "git",