@gcoredev/proxy-wasm-sdk-as 1.1.0 → 1.2.1-alpha.1

package/README.md

@@ -5,11 +5,12 @@
 [![GitHub top language](https://img.shields.io/github/languages/top/G-Core/proxy-wasm-sdk-as)](https://github.com/G-Core/proxy-wasm-sdk-as)
 [![GitHub License](https://img.shields.io/github/license/G-Core/proxy-wasm-sdk-as)](https://github.com/G-Core/proxy-wasm-sdk-as/blob/main/LICENSE)
 [![NPM Version](https://img.shields.io/npm/v/@gcoredev/proxy-wasm-sdk-as)](https://www.npmjs.com/package/@gcoredev/proxy-wasm-sdk-as)
+[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2FG-Core%2Fproxy-wasm-sdk-as.svg?type=shield)](https://app.fossa.com/projects/git%2Bgithub.com%2FG-Core%2Fproxy-wasm-sdk-as?ref=badge_shield)
 
 This is a friendly fork of https://github.com/Kong/proxy-wasm-assemblyscript-sdk/,
 mantained to address an incompatibility between the AssemblyScript SDK and the Rust SDK,
 
-It also adds some FastEdge specific functionality.
+It also provides FastEdge specific functionality for accessing resources.
 
 ## How to use this SDK
 
@@ -99,3 +100,7 @@ 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)
+
+## License
+
+[![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)

package/assembly/fastedge/env.ts

@@ -0,0 +1,14 @@
+/**
+ * Function to get the value for the provided environment variable name.
+ * @param {string} name - The name of the environment variable.
+ * @returns {string} The value of the environment variable.
+ */
+function getEnvVar(name: string): string {
+  const hasKey = process.env.has(name);
+  if (hasKey) {
+    return process.env.get(name);
+  }
+  return "";
+}
+
+export { getEnvVar };

package/assembly/fastedge/index.ts

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

package/assembly/fastedge/kvStore.ts

@@ -0,0 +1,228 @@
+import * as imports from "../imports";
+
+import {
+  globalArrayBufferReference,
+  Reference,
+  WasmResultValues,
+} from "../runtime";
+import { ItemParser, StringParser, parseBufferToList } from "./utils";
+
+/**
+ * KvStore provides access to the FastEdge Key-Value store
+ */
+export class KvStore {
+  private handle: u32;
+
+  private constructor(handle: u32) {
+    this.handle = handle;
+  }
+
+  /**
+   * Opens a connection to the specified KV store
+   * @param storeName - The name of the KV store to open
+   * @returns A new KvStore instance or null if the store cannot be opened
+   */
+  static open(storeName: string): KvStore | null {
+    const buffer = String.UTF8.encode(storeName);
+    const returnHandlerRef = new Reference<u32>();
+
+    const status = imports.proxy_kv_store_open(
+      changetype<usize>(buffer),
+      buffer.byteLength,
+      returnHandlerRef.ptr() as u32
+    );
+
+    if (status == WasmResultValues.Ok) {
+      return new KvStore(returnHandlerRef.data);
+    }
+    return null;
+  }
+
+  /**
+   * Retrieves the value associated with the given key from the KV store.
+   * @param {string} key  The key to retrieve the value for.
+   * @returns {ArrayBuffer | null} The value associated with the key, or null if not found.
+   */
+  get(key: string): ArrayBuffer | null {
+    const buffer = String.UTF8.encode(key);
+    const status = imports.proxy_kv_store_get(
+      this.getHandle(),
+      changetype<usize>(buffer),
+      buffer.byteLength,
+      globalArrayBufferReference.bufferPtr(),
+      globalArrayBufferReference.sizePtr()
+    );
+    if (status == WasmResultValues.Ok) {
+      return globalArrayBufferReference.toArrayBuffer();
+    }
+    return null;
+  }
+
+  /**
+   * Retrieves all key prefix matches from the KV store.
+   * @param {string} pattern  The prefix pattern to match keys against. e.g. 'foo*' ( Must include wildcard )
+   * @returns {Array<string>} The keys matching the pattern, or empty array if none found.
+   */
+  scan(pattern: string): Array<string> {
+    const match = String.UTF8.encode(pattern);
+    const status = imports.proxy_kv_store_scan(
+      this.getHandle(),
+      changetype<usize>(match),
+      match.byteLength,
+      globalArrayBufferReference.bufferPtr(),
+      globalArrayBufferReference.sizePtr()
+    );
+    if (status == WasmResultValues.Ok) {
+      return parseBufferToList<string>(
+        globalArrayBufferReference.toArrayBuffer(),
+        new StringParser()
+      );
+    }
+    return new Array<string>();
+  }
+
+  /**
+   * Retrieves all the values from ZSet with scores between the given range.
+   * @param {string} key  The key for the Sorted Set.
+   * @param {f64} min  The minimum score for the range.
+   * @param {f64} max  The maximum score for the range.
+   * @returns {Array<ValueScoreTuple>} Array of [value, score] tuples within range for the key, or an empty array if none found.
+   */
+  zrangeByScore(key: string, min: f64, max: f64): Array<ValueScoreTuple> {
+    const keyBuffer = String.UTF8.encode(key);
+    const status = imports.proxy_kv_store_zrange_by_score(
+      this.getHandle(),
+      changetype<usize>(keyBuffer),
+      keyBuffer.byteLength,
+      min,
+      max,
+      globalArrayBufferReference.bufferPtr(),
+      globalArrayBufferReference.sizePtr()
+    );
+    if (status == WasmResultValues.Ok) {
+      return parseBufferToList<ValueScoreTuple>(
+        globalArrayBufferReference.toArrayBuffer(),
+        new ValueScoreTupleParser()
+      );
+    }
+    return new Array<ValueScoreTuple>();
+  }
+
+  /**
+   * Retrieves all value prefix matches from the KV ZSet.
+   * @param {string} key  The key for the Sorted Set.
+   * @param {string} pattern  The prefix pattern to match values against. e.g. 'foo*' ( Must include wildcard )
+   * @returns {Array<ValueScoreTuple>} Array of [value, score] tuples which match the prefix pattern, or an empty array if none found.
+   */
+  zscan(key: string, pattern: string): Array<ValueScoreTuple> {
+    const match = String.UTF8.encode(pattern);
+    const keyBuffer = String.UTF8.encode(key);
+    const status = imports.proxy_kv_store_zscan(
+      this.getHandle(),
+      changetype<usize>(keyBuffer),
+      keyBuffer.byteLength,
+      changetype<usize>(match),
+      match.byteLength,
+      globalArrayBufferReference.bufferPtr(),
+      globalArrayBufferReference.sizePtr()
+    );
+    if (status == WasmResultValues.Ok) {
+      return parseBufferToList<ValueScoreTuple>(
+        globalArrayBufferReference.toArrayBuffer(),
+        new ValueScoreTupleParser()
+      );
+    }
+    return new Array<ValueScoreTuple>();
+  }
+
+  /**
+   * Checks if a given item exists within the KV stores Bloom Filter.
+   * @param {string} key  The key for the Bloom Filter.
+   * @param {string} item  The item to check for existence.
+   * @returns {boolean} True if the item exists, false otherwise.
+   */
+  bfExists(key: string, item: string): boolean {
+    const keyBuffer = String.UTF8.encode(key);
+    const itemBuffer = String.UTF8.encode(item);
+    const returnHandlerRef = new Reference<u32>();
+
+    const status = imports.proxy_kv_store_bf_exists(
+      this.getHandle(),
+      changetype<usize>(keyBuffer),
+      keyBuffer.byteLength,
+      changetype<usize>(itemBuffer),
+      itemBuffer.byteLength,
+      returnHandlerRef.ptr() as u32
+    );
+
+    if (status == WasmResultValues.Ok) {
+      return returnHandlerRef.data != 0;
+    }
+    return false;
+  }
+
+  /**
+   * Gets the handle of this KV store instance
+   * @returns The handle
+   */
+  getHandle(): u32 {
+    return this.handle;
+  }
+}
+
+export class ValueScoreTuple {
+  value: ArrayBuffer;
+  score: number;
+
+  constructor(value: ArrayBuffer, score: number) {
+    this.value = value;
+    this.score = score;
+  }
+}
+
+// ValueScoreTuple parser implementation
+class ValueScoreTupleParser extends ItemParser<ValueScoreTuple> {
+  parseItem(
+    buffer: ArrayBuffer,
+    dataIndex: u32,
+    itemSize: u32
+  ): ValueScoreTuple | null {
+    // Each item contains value bytes + 8-byte f64 score
+    const scoreSize: u32 = 8; // f64 = 8 bytes
+    if (itemSize < scoreSize) {
+      // Invalid item, skip
+      return null;
+    }
+
+    const valueSize = itemSize - scoreSize;
+
+    // Extract value data
+    const valueData = buffer.slice(
+      <i32>dataIndex,
+      <i32>(dataIndex + valueSize)
+    );
+
+    // Extract score data (last 8 bytes of the item)
+    const scoreData = buffer.slice(
+      <i32>(dataIndex + valueSize),
+      <i32>(dataIndex + itemSize)
+    );
+
+    // Convert score bytes to f64 (little-endian)
+    const scoreBytes = new Uint8Array(scoreSize);
+    const sourceScoreBytes = Uint8Array.wrap(scoreData);
+    for (let j: u32 = 0; j < scoreSize; j++) {
+      scoreBytes[j] = sourceScoreBytes[j];
+    }
+
+    // Convert little-endian bytes to f64
+    const scoreView = new DataView(scoreBytes.buffer);
+    const score = scoreView.getFloat64(0, true); // true = little-endian
+
+    return new ValueScoreTuple(valueData, score);
+  }
+
+  createEmptyArray(): Array<ValueScoreTuple> {
+    return new Array<ValueScoreTuple>();
+  }
+}

package/assembly/fastedge/secrets.ts

@@ -0,0 +1,51 @@
+import * as imports from "../imports";
+
+import { globalArrayBufferReference, WasmResultValues } from "../runtime";
+
+/**
+ * Function to get the value for the provided secret variable name.
+ * @param {string} name - The name of the secret variable.
+ * @returns {string} The value of the secret variable.
+ */
+function getSecretVar(name: string): string {
+  const buffer = String.UTF8.encode(name);
+  const status = imports.proxy_get_secret(
+    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 "";
+}
+
+/**
+ * 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)
+ * @returns {string} The value of the secret variable.
+ */
+function getSecretVarEffectiveAt(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()
+  );
+  if (status == WasmResultValues.Ok) {
+    const arrBuff = globalArrayBufferReference.toArrayBuffer();
+    if (arrBuff.byteLength > 0) {
+      return String.UTF8.decode(arrBuff);
+    }
+  }
+  return "";
+}
+
+export { getSecretVar, getSecretVarEffectiveAt };

package/assembly/fastedge/utils/index.ts

@@ -0,0 +1,2 @@
+export { getCurrentTime, log, LogLevelValues, setLogLevel } from "./runtime";
+export { ItemParser, StringParser, parseBufferToList } from "./listParser";

package/assembly/fastedge/utils/listParser.ts

@@ -0,0 +1,70 @@
+// Abstract base class for item parsers
+abstract class ItemParser<T> {
+  abstract parseItem(
+    buffer: ArrayBuffer,
+    dataIndex: u32,
+    itemSize: u32
+  ): T | null;
+  abstract createEmptyArray(): Array<T>;
+}
+
+// String parser implementation
+class StringParser extends ItemParser<string> {
+  parseItem(buffer: ArrayBuffer, dataIndex: u32, itemSize: u32): string | null {
+    // Extract string data
+    const stringData = buffer.slice(
+      <i32>dataIndex,
+      <i32>(dataIndex + itemSize)
+    );
+    return String.UTF8.decode(stringData);
+  }
+
+  createEmptyArray(): Array<string> {
+    return new Array<string>();
+  }
+}
+
+// Generic deserialization function
+function parseBufferToList<T>(
+  buffer: ArrayBuffer,
+  parser: ItemParser<T>
+): Array<T> {
+  // Check if buffer is valid
+  if (!buffer || buffer.byteLength === 0) {
+    return parser.createEmptyArray();
+  }
+
+  // Read number of items
+  const numItems = Uint32Array.wrap(buffer, 0, 1)[0];
+
+  if (numItems === 0) {
+    return parser.createEmptyArray();
+  }
+
+  // Read sizes array
+  const sizes = Uint32Array.wrap(buffer, sizeof<u32>(), numItems);
+
+  // Start of actual data
+  let dataIndex: u32 = sizeof<u32>() * (1 + numItems);
+  const result = parser.createEmptyArray();
+
+  for (let i: u32 = 0; i < numItems; i++) {
+    const itemSize = sizes[i];
+
+    if (dataIndex + itemSize > <u32>buffer.byteLength) {
+      break;
+    }
+
+    const item = parser.parseItem(buffer, dataIndex, itemSize);
+    if (item !== null) {
+      result.push(item);
+    }
+
+    // Move to next item (including null terminator if present)
+    dataIndex += itemSize + 1; // +1 for null terminator
+  }
+
+  return result;
+}
+
+export { ItemParser, StringParser, parseBufferToList };

package/assembly/fastedge/utils/runtime.ts

@@ -0,0 +1,31 @@
+import { get_current_time_nanoseconds, LogLevelValues } from "../../runtime";
+
+let logLevel: LogLevelValues = LogLevelValues.info;
+
+/**
+ * Sets the logging level, proxy_get_log_level is not yet implemented in FastEdge.
+ * @param {LogLevelValues} level  The logging level to set.
+ * @returns {void}
+ */
+function setLogLevel(level: LogLevelValues): void {
+  logLevel = level;
+}
+
+/**
+ * Temporary fix for proxy_log not being implemented in FastEdge.
+ * The function relies on @assemblyscript/wasi-shim to print to standard output.
+ * @param {LogLevelValues} level  The logging level to use.
+ * @param {string} logMessage  The logging message to log.
+ * @returns {void}
+ */
+function log(level: LogLevelValues, logMessage: string): void {
+  if (level >= logLevel) {
+    process.stdout.write(logMessage + "\n");
+  }
+}
+
+function getCurrentTime(): u64 {
+  return get_current_time_nanoseconds() / 1_000_000; // Convert nanoseconds to milliseconds
+}
+
+export { getCurrentTime, log, LogLevelValues, setLogLevel };

package/assembly/imports.ts

@@ -201,3 +201,68 @@ export declare function proxy_get_effective_at_secret(
   return_value_size: usize
 ): u32;
 
+
+// KV Store
+// @ts-ignore: decorator
+@external("env", "proxy_kv_store_open")
+export declare function proxy_kv_store_open(
+  key_data: usize,
+  key_size: usize,
+  return_handle: u32
+): u32;
+
+// @ts-ignore: decorator
+@external("env", "proxy_kv_store_get")
+export declare function proxy_kv_store_get(
+  handle: u32,
+  key_data: usize,
+  key_size: usize,
+  return_value_data: usize,
+  return_value_size: usize,
+): u32;
+
+// @ts-ignore: decorator
+@external("env", "proxy_kv_store_scan")
+export declare function proxy_kv_store_scan(
+  handle: u32,
+  pattern_data: usize,
+  pattern_size: usize,
+  return_value_data: usize,
+  return_value_size: usize,
+): u32;
+
+// @ts-ignore: decorator
+@external("env", "proxy_kv_store_zrange_by_score")
+export declare function proxy_kv_store_zrange_by_score(
+  handle: u32,
+  key_data: usize,
+  key_size: usize,
+  min: f64,
+  max: f64,
+  return_value_data: usize,
+  return_value_size: usize,
+): u32;
+
+// @ts-ignore: decorator
+@external("env", "proxy_kv_store_zscan")
+export declare function proxy_kv_store_zscan(
+  handle: u32,
+  key_data: usize,
+  key_size: usize,
+  pattern_data: usize,
+  pattern_size: usize,
+  return_value_data: usize,
+  return_value_size: usize,
+): u32;
+
+// @ts-ignore: decorator
+@external("env", "proxy_kv_store_bf_exists")
+export declare function proxy_kv_store_bf_exists(
+  handle: u32,
+  key_data: usize,
+  key_size: usize,
+  item_data: usize,
+  item_size: usize,
+  return_handle: u32,
+): u32;
+

package/assembly/index.ts

@@ -41,11 +41,3 @@ export {
   stream_context,
   WasmResultValues,
 } from "./runtime";
-
-export {
-  getCurrentTime,
-  getEnvVar,
-  getSecretVar,
-  getSecretVarEffectiveAt,
-  setLogLevel,
-} from "./fastedge";

package/assembly/runtime.ts

@@ -3,6 +3,7 @@ import { free } from "./malloc";
 
 import { log as wasiLog } from "./fastedge";
 
+
 // abort function.
 // use with:
 // --use abort=index/abort_proc_exit
@@ -32,7 +33,6 @@ function CHECK_RESULT(c: imports.WasmResult): void {
 }
 
 /////////////// Access helpers
-
 export class Reference<T> {
   data: T;
 
@@ -55,8 +55,12 @@ class ArrayBufferReference {
     return changetype<usize>(this) + offsetof<ArrayBufferReference>("buffer");
   }
 
-  // Before calling toArrayBuffer below, you must call out to the host to fill in the values.
-  // toArrayBuffer below **must** be called once and only once.
+  /**
+   * Before calling toArrayBuffer below, you must call out to the host to fill in the values.
+   * toArrayBuffer below **must** be called once and only once.
+   * Host code used malloc to allocate this buffer.
+   * This method consumes the buffer and handles memory cleanup automatically.
+   */
   toArrayBuffer(): ArrayBuffer {
     if (this.size == 0) {
       return new ArrayBuffer(0);
@@ -71,6 +75,8 @@ class ArrayBufferReference {
   }
 }
 
+
+
 export const globalArrayBufferReference = new ArrayBufferReference();
 let globalU32Ref = new Reference<u32>();
 let globalLogLevelRef = new Reference<imports.LogLevel>();
@@ -633,7 +639,6 @@ export function get_buffer_bytes(typ: BufferTypeValues, start: u32, length: u32)
 
 export function set_buffer_bytes(typ: BufferTypeValues, start: u32, length: u32, value: ArrayBuffer): WasmResultValues {
   const result = imports.proxy_set_buffer_bytes(typ, start, length, changetype<usize>(value), value.byteLength);
-	wasiLog(LogLevelValues.info, 'Farq: setBuffer result: ' + result.toString());
   return result
 }
 

package/package.json

@@ -1,4 +1,8 @@
 {
+  "name": "@gcoredev/proxy-wasm-sdk-as",
+  "description": "Use this SDK to write extensions for the proxy WASM ABI",
+  "version": "1.2.1-alpha.1",
+  "main": "assembly/index.ts",
   "scripts": {
     "asbuild:debug": "asc assembly/index.ts --target debug",
     "asbuild:release": "asc assembly/index.ts --target release",
@@ -15,10 +19,6 @@
     "minimist": ">=1.2.2",
     "typedoc": "^0.27.7"
   },
-  "name": "@gcoredev/proxy-wasm-sdk-as",
-  "description": "Use this SDK to write extensions for the proxy WASM ABI",
-  "version": "1.1.0",
-  "main": "assembly/index.ts",
   "directories": {
     "doc": "docs"
   },

package/assembly/fastedge.ts

@@ -1,82 +0,0 @@
-import * as imports from "./imports";
-
-import {
-  get_current_time_nanoseconds,
-  globalArrayBufferReference,
-  LogLevelValues,
-} from "./runtime";
-
-let logLevel: LogLevelValues = LogLevelValues.info;
-
-function setLogLevel(level: LogLevelValues): void {
-  logLevel = level;
-}
-
-function log(level: LogLevelValues, logMessage: string): void {
-  // Temporary fix for proxy_log not being implemented in fastedge:
-  // relies on @assemblyscript/wasi-shim to print to standard output
-  if (level >= logLevel) {
-    process.stdout.write(logMessage + "\n");
-  }
-}
-
-function getCurrentTime(): u64 {
-  return get_current_time_nanoseconds() / 1_000_000; // Convert nanoseconds to milliseconds
-}
-
-function getEnvVar(key: string): string {
-  const hasKey = process.env.has(key);
-  if (hasKey) {
-    return process.env.get(key);
-  }
-  return "";
-}
-
-function getSecretVar(key: string): string {
-  const buffer = String.UTF8.encode(key);
-  const status = imports.proxy_get_secret(
-    changetype<usize>(buffer),
-    buffer.byteLength,
-    globalArrayBufferReference.bufferPtr(),
-    globalArrayBufferReference.sizePtr()
-  );
-  if (status != 0) {
-    // Something went wrong - returns 0 with an empty ArrayBuffer if not found
-    return "";
-  }
-  const arrBuff = globalArrayBufferReference.toArrayBuffer();
-  if (arrBuff.byteLength == 0) {
-    return ""; // Not found
-  }
-  return String.UTF8.decode(arrBuff);
-}
-
-function getSecretVarEffectiveAt(key: string, at: u32): string {
-  const buffer = String.UTF8.encode(key);
-  const status = imports.proxy_get_effective_at_secret(
-    changetype<usize>(buffer),
-    buffer.byteLength,
-    at,
-    globalArrayBufferReference.bufferPtr(),
-    globalArrayBufferReference.sizePtr()
-  );
-  if (status != 0) {
-    // Something went wrong - returns 0 with an empty ArrayBuffer if not found
-    return "";
-  }
-  const arrBuff = globalArrayBufferReference.toArrayBuffer();
-  if (arrBuff.byteLength == 0) {
-    return ""; // Not found
-  }
-  return String.UTF8.decode(arrBuff);
-}
-
-export {
-  getCurrentTime,
-  getEnvVar,
-  getSecretVar,
-  getSecretVarEffectiveAt,
-  log,
-  LogLevelValues,
-  setLogLevel,
-};