Skip to content

Commit 069ce75

Browse files
peaseelukekim
peasee
and
lukekim
authored
docs: Add hashing algorithm documentation for results cache (#1001)
* docs: Add hashing algorithm documentation for results cache * Tweaks --------- Co-authored-by: Luke Kim <80174+lukekim@users.noreply.github.com>
1 parent c2008b0 commit 069ce75

2 files changed

Lines changed: 38 additions & 20 deletions

File tree

‎website/docs/features/caching/index.md‎

Lines changed: 22 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -25,24 +25,34 @@ name: app
2525
runtime:
2626
results_cache:
2727
enabled: true
28-
cache_max_size: 128MiB
29-
item_ttl: 1s
28+
cache_max_size: 1GiB # Default 128 MiB
29+
item_ttl: 1m # Default 1s
3030
```
3131
32-
| Parameter name | Optional | Description |
33-
| ----------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
34-
| `enabled` | Yes | Defaults to `true`. |
35-
| `cache_max_size` | Yes | Maximum cache size. Defaults to `128MiB`. |
36-
| `eviction_policy` | Yes | Cache replacement policy when the cache reaches `cache_max_size`. Defaults to `lru`, which is currently the only supported value. |
37-
| `item_ttl` | Yes | Cache entry expiration duration (Time to Live). Defaults to 1 second. |
38-
| `cache_key_type` | Yes | Determines how cache keys are generated. Defaults to `plan`. `plan` uses the query's logical plan, while `sql` uses the raw SQL query string. |
32+
| Parameter name | Optional | Description |
33+
| ------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
34+
| `enabled` | Yes | Defaults to `true`. |
35+
| `cache_max_size` | Yes | Maximum cache size. Defaults to `128MiB`. |
36+
| `eviction_policy` | Yes | Cache replacement policy when the cache reaches `cache_max_size`. Defaults to `lru`, which is currently the only supported value. |
37+
| `item_ttl` | Yes | Cache entry expiration duration (Time to Live). Defaults to 1 second. |
38+
| `cache_key_type` | Yes | Determines how cache keys are generated. Defaults to `plan`. `plan` uses the query's logical plan, while `sql` uses the raw SQL query string. |
39+
| `hashing_algorithm` | Yes | Selects which hashing algorithm is used to hash the cache keys when storing the results. Defaults to `siphash`. Supports `siphash` or `ahash`. |
3940

4041
### Choosing a `cache_key_type`
4142

42-
- **`plan` (Default):** Uses the query's logical plan as the cache key. Matches semantically equivalent queries but requires query parsing.
43-
- **`sql`:** Uses the raw SQL string as the cache key. Provides faster lookups but requires exact string matches. Queries with dynamic functions, such as `NOW()`, may produce unexpected results. Use `sql` only when results are predictable.
43+
- **`plan` (Default):** Uses the query's logical plan as the cache key. This approach matches semantically equivalent queries, even if their SQL syntax differs. However, it requires query parsing, which introduces some overhead.
44+
- **`sql`:** Uses the raw SQL string as the cache key. This method provides faster lookups but requires exact string matches. Queries with dynamic functions, such as `NOW()`, may produce unexpected results because the cache key changes with each execution. Use `sql` only when query results are predictable and consistent.
4445

45-
Use `sql` for the lowest latency with identical queries that do not include dynamic functions. Use `plan` for greater flexibility.
46+
Use `sql` for the lowest latency with identical queries that do not include dynamic functions. Use `plan` for greater flexibility and semantic matching of queries.
47+
48+
### Choosing a `hashing_algorithm`
49+
50+
The hashing algorithm determines how cache keys are hashed before being stored, impacting both lookup speed and protection against potential DOS attacks.
51+
52+
- **`siphash` (Default):** Uses the SipHash1-3 algorithm for hashing the cache keys, the [default hashing algorithm of Rust](https://github.com/rust-lang/rust/commit/db1b1919baba8be48d997d9f70a6a5df7e31612a). This hashing algorithm is a secure algorithm that implements verified protections against ["hash flooding"](https://v8.dev/blog/hash-flooding) denial of service (DoS) attacks. Reasonably performant, and provides a high level of security.
53+
- **`ahash`:** Uses the [AHash](https://github.com/tkaitchuck/ahash) algorithm for hashing the cache keys. The AHash algorithm is a [high quality](https://github.com/tkaitchuck/aHash/blob/master/compare/readme.md#Quality) hashing algorithm, and has claimed resistance against hashing DoS attacks. AHash has higher performance than SipHash1-3, especially when used with `cache_key_type: plan`.
54+
55+
Consider using `ahash` if maximum performance is most important, or where hashing DoS attacks are unlikely or a low risk. More information on the security mechanisms of AHash are available [in the AHash documentation](https://github.com/tkaitchuck/aHash/wiki/How-aHash-is-resists-DOS-attacks).
4656

4757
## Cached Responses
4858

‎website/docs/reference/spicepod/runtime.md‎

Lines changed: 16 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -22,13 +22,14 @@ runtime:
2222
item_ttl: 1s
2323
```
2424
25-
| Parameter name | Optional | Description |
26-
| ----------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
27-
| `enabled` | Yes | Defaults to `true`. |
28-
| `cache_max_size` | Yes | Maximum cache size. Defaults to `128MiB`. |
29-
| `eviction_policy` | Yes | Cache replacement policy when the cache reaches `cache_max_size`. Defaults to `lru`, which is currently the only supported value. |
30-
| `item_ttl` | Yes | Cache entry expiration duration (Time to Live). Defaults to 1 second. |
31-
| `cache_key_type` | Yes | Determines how cache keys are generated. Defaults to `plan`. `plan` uses the query's logical plan, while `sql` uses the raw SQL query string. |
25+
| Parameter name | Optional | Description |
26+
| ------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
27+
| `enabled` | Yes | Defaults to `true`. |
28+
| `cache_max_size` | Yes | Maximum cache size. Defaults to `128MiB`. |
29+
| `eviction_policy` | Yes | Cache replacement policy when the cache reaches `cache_max_size`. Defaults to `lru`, which is currently the only supported value. |
30+
| `item_ttl` | Yes | Cache entry expiration duration (Time to Live). Defaults to 1 second. |
31+
| `cache_key_type` | Yes | Determines how cache keys are generated. Defaults to `plan`. `plan` uses the query's logical plan, while `sql` uses the raw SQL query string. |
32+
| `hashing_algorithm` | Yes | Selects which hashing algorithm is used to hash the cache keys when storing the results. Defaults to `siphash`. Supports `siphash` or `ahash`. |
3233

3334
### Choosing a `cache_key_type`
3435

@@ -37,9 +38,16 @@ runtime:
3738

3839
Use `sql` for the lowest latency with identical queries that do not include dynamic functions. Use `plan` for greater flexibility.
3940

41+
### Choosing a `hashing_algorithm`
42+
43+
- **`siphash` (Default):** Uses the SipHash1-3 algorithm for hashing the cache keys, the [default hashing algorithm of Rust](https://github.com/rust-lang/rust/commit/db1b1919baba8be48d997d9f70a6a5df7e31612a). This hashing algorithm is a secure algorithm that implements verified protections against ["hash flooding"](https://v8.dev/blog/hash-flooding) denial of service (DoS) attacks. Reasonably performant, and provides a high level of security.
44+
- **`ahash`:** Uses the [AHash](https://github.com/tkaitchuck/ahash) algorithm for hashing the cache keys. The AHash algorithm is a [high quality](https://github.com/tkaitchuck/aHash/blob/master/compare/readme.md#Quality) hashing algorithm, and has claimed resistance against hashing DoS attacks. AHash has higher performance than SipHash1-3, especially when used with a `plan` `cache_key_type`.
45+
46+
Consider using `ahash` if maximum performance is most important, or where hashing DoS attacks are unlikely or a low risk. More information on the security mechanisms of AHash are available [in the AHash documentation](https://github.com/tkaitchuck/aHash/wiki/How-aHash-is-resists-DOS-attacks).
47+
4048
## `runtime.shutdown_timeout`
4149

42-
Controls how long Spice waits for connections to be gracefully drained and for components to shut down cleanly during runtime termination. Defaults to 30 seconds.
50+
Controls how long Spice waits for connections to be gracefully drained and for components to shut down cleanly during runtime termination. Defaults to 30 seconds.
4351

4452
```yaml
4553
runtime:

0 commit comments

Comments
 (0)