Skip to content

Commit 237d074

Browse files
godronusgodronus
committed
docs update
1 parent 89db9ba commit 237d074

6 files changed

Lines changed: 68 additions & 64 deletions

File tree

‎context/reference/PROPERTIES_REFERENCE.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22

33
Properties are read-only metadata about the current request and client, available via `proxy_get_property()` in ProxyWasm apps. They provide context that isn't in the HTTP headers themselves.
44

5+
**Path format:** Always pass the property identifier as a single dotted string in a one-element vec — e.g., `vec!["request.path"]`, `vec!["request.geo.long"]`. Do **not** split on dots (e.g., `vec!["request", "country"]` is incorrect).
6+
57
---
68

79
## Available Properties
@@ -40,13 +42,13 @@ Properties are read-only metadata about the current request and client, availabl
4042
// In an HttpContext implementation
4143
fn on_http_request_headers(&mut self, _: usize, _: bool) -> Action {
4244
// Get client's country
43-
if let Some(country) = self.get_property(vec!["request", "country"]) {
45+
if let Some(country) = self.get_property(vec!["request.country"]) {
4446
let country_str = String::from_utf8(country).unwrap_or_default();
4547
// Use for geo-routing, access control, etc.
4648
}
4749

4850
// Get client IP
49-
if let Some(ip) = self.get_property(vec!["request", "x_real_ip"]) {
51+
if let Some(ip) = self.get_property(vec!["request.x_real_ip"]) {
5052
// Use for rate limiting, logging, etc.
5153
}
5254

‎docs/CDN_APPS.md‎

Lines changed: 40 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -151,11 +151,11 @@ All callbacks have default no-op implementations. Override only the phases your
151151

152152
Every lifecycle callback returns an `Action` that controls what happens next.
153153

154-
| Action | Meaning |
155-
| -------------------------------- | --------------------------------------------------------------------------- |
156-
| `Action::Continue` | Pass the request or response through to the next stage |
157-
| `Action::Pause` | Stop processing; used after `send_http_response` to short-circuit origin |
158-
| `Action::StopIterationAndBuffer` | Buffer the current body chunk; continue accumulating until `end_of_stream` |
154+
| Action | Meaning |
155+
| -------------------------------- | -------------------------------------------------------------------------- |
156+
| `Action::Continue` | Pass the request or response through to the next stage |
157+
| `Action::Pause` | Stop processing; used after `send_http_response` to short-circuit origin |
158+
| `Action::StopIterationAndBuffer` | Buffer the current body chunk; continue accumulating until `end_of_stream` |
159159

160160
For body callbacks, return `Action::StopIterationAndBuffer` until `end_of_stream` is `true`, then process the full body and return `Action::Continue`.
161161

@@ -298,24 +298,26 @@ impl HttpContext for MyApp {
298298

299299
CDN apps access request metadata through `self.get_property(vec![...])`. The return type is `Option<Vec<u8>>`.
300300

301-
| Property | Encoding | Description |
302-
| ---------------------- | --------------------- | ------------------------------------------------------ |
303-
| `request.path` | UTF-8 string | URL path |
304-
| `request.query` | UTF-8 string | Query string |
305-
| `request.url` | UTF-8 string | Full request URL |
306-
| `request.host` | UTF-8 string | Domain (may have `shield_` prefix on edge shield nodes) |
307-
| `request.scheme` | UTF-8 string | HTTP scheme (from X-Forwarded-Proto) |
308-
| `request.extension` | UTF-8 string | File extension |
309-
| `request.x_real_ip` | UTF-8 string | Client IP address |
310-
| `request.country` | UTF-8 string | 2-letter ISO country code (geo-IP lookup) |
311-
| `request.country.name` | UTF-8 string | Full country name |
312-
| `request.city` | UTF-8 string | City name |
313-
| `request.region` | UTF-8 string | Region/state |
314-
| `request.continent` | UTF-8 string | Continent |
315-
| `request.asn` | UTF-8 string | Autonomous System Number |
316-
| `request.geo.lat` | UTF-8 string | Latitude |
317-
| `request.geo.long` | UTF-8 string | Longitude |
318-
| `response.status` | 2-byte big-endian u16 | Response status code (response phase only) |
301+
**Path format:** Always pass the property identifier as a single dotted string in a one-element vec — e.g., `vec!["request.path"]`, `vec!["response.status"]`, `vec!["request.geo.long"]`. Do **not** split on dots (e.g., `vec!["response", "status"]` is incorrect).
302+
303+
| Property | Encoding | Description |
304+
| ---------------------- | --------------------- | -------------------------------------------------------------------------------- |
305+
| `request.path` | UTF-8 string | URL path |
306+
| `request.query` | UTF-8 string | Query string |
307+
| `request.url` | UTF-8 string | Full request URL |
308+
| `request.host` | UTF-8 string | Domain (may have `shield_` prefix on edge shield nodes) |
309+
| `request.scheme` | UTF-8 string | HTTP scheme (from X-Forwarded-Proto) |
310+
| `request.extension` | UTF-8 string | File extension |
311+
| `request.x_real_ip` | UTF-8 string | Client IP address |
312+
| `request.country` | UTF-8 string | 2-letter ISO country code (geo-IP) |
313+
| `request.country.name` | UTF-8 string | Full country name |
314+
| `request.city` | UTF-8 string | City name |
315+
| `request.region` | UTF-8 string | Region/state |
316+
| `request.continent` | UTF-8 string | Continent |
317+
| `request.asn` | UTF-8 string | Autonomous System Number |
318+
| `request.geo.lat` | UTF-8 string | Latitude |
319+
| `request.geo.long` | UTF-8 string | Longitude |
320+
| `response.status` | 2-byte big-endian u16 | Response status code (**binary, NOT a string** — decode with `u16::from_be_bytes`) |
319321

320322
Most properties are UTF-8 strings decoded with `std::str::from_utf8()`. The `response.status` property is binary-encoded and must be decoded as a big-endian `u16`. Do not use `String::from_utf8` for this property.
321323

@@ -329,7 +331,7 @@ Geo-IP properties (`request.country`, `request.country.name`, `request.city`, `r
329331
impl HttpContext for MyApp {
330332
fn on_http_response_headers(&mut self, _: usize, _: bool) -> Action {
331333
// response.status is a 2-byte big-endian u16 — do NOT use String::from_utf8
332-
if let Some(bytes) = self.get_property(vec!["response", "status"]) {
334+
if let Some(bytes) = self.get_property(vec!["response.status"]) {
333335
if bytes.len() == 2 {
334336
let status = u16::from_be_bytes([bytes[0], bytes[1]]);
335337
println!("upstream status: {}", status);
@@ -375,15 +377,15 @@ Provides persistent key-value storage. The API shape mirrors `fastedge::key_valu
375377
pub struct Store { /* ... */ }
376378
```
377379

378-
| Method | Return Type | Description |
379-
| --------------------------------------------------------- | ------------------------------------ | ------------------------------------------------------ |
380-
| `Store::new()` | `Result<Self, Error>` | Open the default store |
381-
| `Store::open(name: &str)` | `Result<Self, Error>` | Open a named store |
382-
| `Store::get(key: &str)` | `Result<Option<Vec<u8>>, Error>` | Get the value for a key; `None` if key does not exist |
383-
| `Store::scan(pattern: &str)` | `Result<Vec<String>, Error>` | List keys matching a glob-style pattern |
384-
| `Store::zrange_by_score(key: &str, min: f64, max: f64)` | `Result<Vec<(Vec<u8>, f64)>, Error>` | Get sorted-set members with scores between min and max |
385-
| `Store::zscan(key: &str, pattern: &str)` | `Result<Vec<(Vec<u8>, f64)>, Error>` | Scan sorted-set members matching a pattern |
386-
| `Store::bf_exists(key: &str, item: &str)` | `Result<bool, Error>` | Test whether an item is in a Bloom filter |
380+
| Method | Return Type | Description |
381+
| ------------------------------------------------------- | ------------------------------------ | ------------------------------------------------------ |
382+
| `Store::new()` | `Result<Self, Error>` | Open the default store |
383+
| `Store::open(name: &str)` | `Result<Self, Error>` | Open a named store |
384+
| `Store::get(key: &str)` | `Result<Option<Vec<u8>>, Error>` | Get the value for a key; `None` if key does not exist |
385+
| `Store::scan(pattern: &str)` | `Result<Vec<String>, Error>` | List keys matching a glob-style pattern |
386+
| `Store::zrange_by_score(key: &str, min: f64, max: f64)` | `Result<Vec<(Vec<u8>, f64)>, Error>` | Get sorted-set members with scores between min and max |
387+
| `Store::zscan(key: &str, pattern: &str)` | `Result<Vec<(Vec<u8>, f64)>, Error>` | Scan sorted-set members matching a pattern |
388+
| `Store::bf_exists(key: &str, item: &str)` | `Result<bool, Error>` | Test whether an item is in a Bloom filter |
387389

388390
#### `Error`
389391

@@ -395,11 +397,11 @@ pub enum Error {
395397
}
396398
```
397399

398-
| Variant | Description |
399-
| --------------- | ------------------------------------------------------------ |
400-
| `NoSuchStore` | The store label is not recognized by the host |
401-
| `AccessDenied` | The application does not have access to the specified store |
402-
| `Other(String)` | An implementation-specific error (e.g., I/O failure) |
400+
| Variant | Description |
401+
| --------------- | ----------------------------------------------------------- |
402+
| `NoSuchStore` | The store label is not recognized by the host |
403+
| `AccessDenied` | The application does not have access to the specified store |
404+
| `Other(String)` | An implementation-specific error (e.g., I/O failure) |
403405

404406
#### Example — Bloom filter check in request headers phase
405407

‎docs/HOST_SERVICES.md‎

Lines changed: 13 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -76,11 +76,11 @@ Scans the store for keys matching a glob-style pattern. Returns a list of matchi
7676

7777
Supported glob syntax:
7878

79-
| Pattern | Matches |
80-
| --------- | ------------------------------------------- |
81-
| `*` | Any sequence of characters within a segment |
82-
| `?` | Any single character |
83-
| `[abc]` | Any character in the set |
79+
| Pattern | Matches |
80+
| ------- | ------------------------------------------- |
81+
| `*` | Any sequence of characters within a segment |
82+
| `?` | Any single character |
83+
| `[abc]` | Any character in the set |
8484

8585
```rust,no_run
8686
use fastedge::key_value::Store;
@@ -345,14 +345,14 @@ async fn main(_request: Request<Body>) -> anyhow::Result<Response<Body>> {
345345

346346
### When to Use Dictionary vs Key-Value vs Secrets
347347

348-
| Criterion | `dictionary` | `key_value` | `secret` |
349-
| ---------------------------- | -------------------------------------- | ----------------------------------------- | ------------------------------------------- |
350-
| **Mutability** | Read-only; set at deployment time | Read-only from application code | Read-only; managed by platform |
351-
| **Value type** | UTF-8 strings only | Arbitrary bytes | Arbitrary bytes |
352-
| **Advanced data structures** | No | Sorted sets, bloom filters, glob scan | No |
353-
| **Confidentiality** | Not encrypted; visible in config | Not encrypted at the application layer | Encrypted at rest; access-controlled |
354-
| **Typical use cases** | Feature flags, routing config, tuning | Caching, counters, state, rate-limit data | API keys, tokens, certificates, credentials |
355-
| **Versioning / rotation** | No | No | Yes, via `get_effective_at` |
348+
| Criterion | `dictionary` | `key_value` | `secret` |
349+
| ---------------------------- | ------------------------------------- | ----------------------------------------- | ------------------------------------------- |
350+
| **Mutability** | Read-only; set at deployment time | Read-only from application code | Read-only; managed by platform |
351+
| **Value type** | UTF-8 strings only | Arbitrary bytes | Arbitrary bytes |
352+
| **Advanced data structures** | No | Sorted sets, bloom filters, glob scan | No |
353+
| **Confidentiality** | Not encrypted; visible in config | Not encrypted at the application layer | Encrypted at rest; access-controlled |
354+
| **Typical use cases** | Feature flags, routing config, tuning | Caching, counters, state, rate-limit data | API keys, tokens, certificates, credentials |
355+
| **Versioning / rotation** | No | No | Yes, via `get_effective_at` |
356356

357357
Use `dictionary` for simple, non-sensitive string configuration that is known at deployment time. Use `key_value` for larger datasets, binary values, or data that requires advanced query patterns. Use `secret` for any value that must be kept confidential.
358358

‎docs/INDEX.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -4,12 +4,12 @@ Documentation for the `fastedge` crate (v0.3.5) — a Rust SDK for building edge
44

55
## Documents
66

7-
| File | Description |
8-
| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
9-
| [quickstart.md](quickstart.md) | Getting started: project setup, writing a handler, building to WASM (`wasm32-wasip2` for async, `wasm32-wasip1` for basic/CDN) |
10-
| [SDK_API.md](SDK_API.md) | Core API: handler macros (`#[wstd::http_server]`, `#[fastedge::http]`), Body type, outbound HTTP (`send_request`), errors, feature flags |
11-
| [HOST_SERVICES.md](HOST_SERVICES.md) | Host services for HTTP apps: key-value store, secrets, dictionary, diagnostics |
12-
| [CDN_APPS.md](CDN_APPS.md) | CDN apps: proxy-wasm lifecycle, `fastedge::proxywasm::*` API surface, request/response manipulation |
7+
| File | Description |
8+
| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
9+
| [quickstart.md](quickstart.md) | Getting started: project setup, writing a handler, building to WASM (`wasm32-wasip2` for async, `wasm32-wasip1` for basic/CDN) |
10+
| [SDK_API.md](SDK_API.md) | Core API: handler macros (`#[wstd::http_server]`, `#[fastedge::http]`), Body type, outbound HTTP (`send_request`), errors, feature flags |
11+
| [HOST_SERVICES.md](HOST_SERVICES.md) | Host services for HTTP apps: key-value store, secrets, dictionary, diagnostics |
12+
| [CDN_APPS.md](CDN_APPS.md) | CDN apps: proxy-wasm lifecycle, `fastedge::proxywasm::*` API surface, request/response manipulation |
1313

1414
## Suggested Reading Order
1515

‎docs/SDK_API.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -25,8 +25,8 @@ For `#[fastedge::http]` (basic):
2525

2626
```toml
2727
[dependencies]
28-
fastedge = "0.3"
29-
anyhow = "1.0"
28+
fastedge = "0.3.5"
29+
anyhow = "1"
3030

3131
[lib]
3232
crate-type = ["cdylib"]
@@ -410,14 +410,14 @@ Enable non-default features in `Cargo.toml`:
410410

411411
```toml
412412
[dependencies]
413-
fastedge = { version = "0.3", features = ["json"] }
413+
fastedge = { version = "0.3.5", features = ["json"] }
414414
```
415415

416416
Disable the default `proxywasm` feature if you do not need it:
417417

418418
```toml
419419
[dependencies]
420-
fastedge = { version = "0.3", default-features = false }
420+
fastedge = { version = "0.3.5", default-features = false }
421421
```
422422

423423
---

‎fastedge-plugin-source/.generation-config.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -398,7 +398,7 @@ Do NOT document or suggest:
398398
**Known limitation — header removal:** On the FastEdge CDN (nginx-based), removing a header via the proxy-wasm API sets its value to an empty string rather than fully removing it. Keep this in mind when checking for header presence.
399399

400400
**Request Properties:**
401-
CDN apps access request metadata via `self.get_property(vec![...])`. Document ALL available properties on the FastEdge platform:
401+
CDN apps access request metadata via `self.get_property(vec![...])`. **Path format:** Always pass the property identifier as a single dotted string in a one-element vec — e.g., `vec!["request.path"]`, `vec!["response.status"]`, `vec!["request.geo.long"]`. Do **not** split on dots (e.g., `vec!["response", "status"]` is incorrect). Document ALL available properties on the FastEdge platform:
402402

403403
| Property | Encoding | Description |
404404
| ---------------------- | --------------------- | ------------------------------------------------------------------------------- |

0 commit comments

Comments
 (0)