From 7efc8a2fb2e436aca627565cfec149a362fb42c4 Mon Sep 17 00:00:00 2001 From: Ruslan Pislari Date: Tue, 10 Mar 2026 08:38:34 +0200 Subject: [PATCH] docs: update usage guide for fastedge-run tool with detailed command options and examples --- README.md | 154 ++++++++++++++++++++++++++++++++- crates/http-service/src/lib.rs | 2 +- 2 files changed, 154 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index f3f7353..84e306e 100644 --- a/README.md +++ b/README.md @@ -68,4 +68,156 @@ Note: It also creates a PR for `releases/**` branch to merge it to `main` as soo # Running ## Fastedge Run Tool -* run with `cargo run --bin fastedge-run -- --help` flag to list run commands and options + +`fastedge-run` is a local test tool for running FastEdge Wasm applications over HTTP. + +``` +fastedge-run + +Commands: + http Execute http handler + help Print this message or the help of the given subcommand(s) +``` + +Run `cargo run --bin fastedge-run -- --help` to list commands, or +`cargo run --bin fastedge-run -- http --help` for full flag reference. + +### `http` subcommand + +Starts a local HTTP server that runs a Wasm application on every request. + +``` +fastedge-run http [OPTIONS] --port --wasm +``` + +#### Required flags + +| Flag | Description | +|------|-------------| +| `-p, --port ` | TCP port the server listens on (`127.0.0.1` only) | +| `-w, --wasm ` | Path to the compiled `.wasm` file | + +#### Optional flags + +| Flag | Description | +|------|-------------| +| `-e, --env ` | Environment variable passed to the Wasm app (repeatable) | +| `-s, --secret ` | Secret variable passed to the Wasm app (repeatable) | +| `--headers ` | Request headers injected before execution (repeatable) | +| `--rsp-headers ` | Extra headers added to every response (repeatable) | +| `--propagate-header ` | Forward this header from the incoming request as-is (repeatable) | +| `--kv-stores ` | Key-value store: map a store name to a Redis URL (repeatable) | +| `--geo` | Inject sample Gcore PoP geo headers into each request | +| `-m ` | Memory limit for the Wasm instance (default: 128 MB) | +| `--max-duration ` | Max execution time in milliseconds (default: 60 000 ms) | +| `--wasi-http ` | Enable the WASI HTTP interface | +| `--dotenv [PATH]` | Load variables from dotenv files (see [Dotenv support](#dotenv-support)) | + +#### Basic example + +```bash +fastedge-run http --port 8080 --wasm ./my_app.wasm +``` + +#### Passing environment variables and secrets + +```bash +fastedge-run http \ + --port 8080 \ + --wasm ./my_app.wasm \ + --env HOST=localhost \ + --env PORT=5432 \ + --secret API_KEY=supersecret +``` + +#### Injecting request headers + +Use `--headers` to add fixed headers to every request before the Wasm handler sees it, and +`--propagate-header` to pass through a header from the real incoming request unchanged: + +```bash +fastedge-run http \ + --port 8080 \ + --wasm ./my_app.wasm \ + --headers X-Client-ID=test-client \ + --propagate-header Authorization +``` + +#### Key-value stores + +Map a store name (as used by the Wasm app) to a Redis URL with `--kv-stores `. +Multiple stores can be specified by repeating the flag. + +```bash +fastedge-run http \ + --port 8080 \ + --wasm ./my_app.wasm \ + --kv-stores sessions=redis://localhost:6379 \ + --kv-stores cache=redis://cache-host:6379 +``` + +The store name on the left (`sessions`, `cache`) is the identifier the Wasm app uses to open +the store. The value on the right is the Redis connection URL passed to the Redis client. + +#### Geo headers + +`--geo` injects a set of sample Gcore PoP location headers so the app can be tested locally +without a real CDN: + +``` +pop-lat, pop-long, pop-reg, pop-city, pop-continent, pop-country-code, pop-country-name +``` + +```bash +fastedge-run http --port 8080 --wasm ./my_app.wasm --geo +``` + +#### Resource limits + +```bash +fastedge-run http \ + --port 8080 \ + --wasm ./my_app.wasm \ + -m 67108864 \ # 64 MB memory limit + --max-duration 5000 # 5-second execution timeout +``` + +### Dotenv support + +Pass `--dotenv` (optionally with a directory path; defaults to the current directory) to load +variables from dotenv files. CLI flags take precedence over file values. + +| File | Populated into | +|------|----------------| +| `.env` | All categories via `FASTEDGE_VAR__` prefixed keys, and bare keys into env vars | +| `.env.variables` | Environment variables (`--env`) | +| `.env.secrets` | Secrets (`--secret`) | +| `.env.req_headers` | Request headers (`--headers`) | +| `.env.rsp_headers` | Response headers (`--rsp-headers`) | +| `.env.kv_stores` | Key-value store mappings (`--kv-stores`) | + +Prefix keys in `.env` with `FASTEDGE_VAR__` to target a specific category: + +| Prefix | Category | +|--------|----------| +| `FASTEDGE_VAR_ENV_` | Environment variables | +| `FASTEDGE_VAR_SECRET_` | Secrets | +| `FASTEDGE_VAR_REQ_HEADER_` | Request headers | +| `FASTEDGE_VAR_RSP_HEADER_` | Response headers | +| `FASTEDGE_VAR_KV_STORE` | Key-value stores | + +Bare keys in `.env` (without a `FASTEDGE_VAR_` prefix) are added as environment variables. + +**Example `.env`:** +``` +DB_HOST=localhost +FASTEDGE_VAR_SECRET_API_KEY=s3cr3t +FASTEDGE_VAR_RSP_HEADER_Cache-Control=no-store +FASTEDGE_VAR_KV_STORE=sessions=redis://localhost:6379 +``` + +```bash +fastedge-run http --port 8080 --wasm ./my_app.wasm --dotenv +# or point to a specific directory: +fastedge-run http --port 8080 --wasm ./my_app.wasm --dotenv ./config/ +``` diff --git a/crates/http-service/src/lib.rs b/crates/http-service/src/lib.rs index 1f36d88..9d9fe83 100644 --- a/crates/http-service/src/lib.rs +++ b/crates/http-service/src/lib.rs @@ -307,7 +307,7 @@ where Err(error) => { #[cfg(feature = "metrics")] metrics::metrics(AppResult::UNKNOWN, HTTP_LABEL, None, None); - tracing::warn!(cause=?error, + tracing::warn!(cause=?error, app=%app_name, "failure on getting context" ); return internal_fastedge_error("context error");