Skip to content

docs: Add hashing algorithm documentation for results cache #1001

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
lukekim merged 3 commits into from
May 19, 2025
+38 −20
Merged

docs: Add hashing algorithm documentation for results cache #1001

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
2aa01c7
docs: Add hashing algorithm documentation for results cache
peasee May 19, 2025
41f7950
Tweaks
lukekim May 19, 2025
ca88dae
Merge branch 'release/1.3.0' into docs/hashing-algorithm
lukekim May 19, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 22 additions & 12 deletions website/docs/features/caching/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,24 +25,34 @@ name: app
runtime:
results_cache:
enabled: true
cache_max_size: 128MiB
item_ttl: 1s
cache_max_size: 1GiB # Default 128 MiB
item_ttl: 1m # Default 1s
```

| Parameter name | Optional | Description |
| ----------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `enabled` | Yes | Defaults to `true`. |
| `cache_max_size` | Yes | Maximum cache size. Defaults to `128MiB`. |
| `eviction_policy` | Yes | Cache replacement policy when the cache reaches `cache_max_size`. Defaults to `lru`, which is currently the only supported value. |
| `item_ttl` | Yes | Cache entry expiration duration (Time to Live). Defaults to 1 second. |
| `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. |
| Parameter name | Optional | Description |
| ------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `enabled` | Yes | Defaults to `true`. |
| `cache_max_size` | Yes | Maximum cache size. Defaults to `128MiB`. |
| `eviction_policy` | Yes | Cache replacement policy when the cache reaches `cache_max_size`. Defaults to `lru`, which is currently the only supported value. |
| `item_ttl` | Yes | Cache entry expiration duration (Time to Live). Defaults to 1 second. |
| `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. |
| `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`. |

### Choosing a `cache_key_type`

- **`plan` (Default):** Uses the query's logical plan as the cache key. Matches semantically equivalent queries but requires query parsing.
- **`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.
- **`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.
- **`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.

Use `sql` for the lowest latency with identical queries that do not include dynamic functions. Use `plan` for greater flexibility.
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.

### Choosing a `hashing_algorithm`

The hashing algorithm determines how cache keys are hashed before being stored, impacting both lookup speed and protection against potential DOS attacks.

- **`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.
- **`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`.

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).

## Cached Responses

Expand Down
24 changes: 16 additions & 8 deletions website/docs/reference/spicepod/runtime.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,13 +22,14 @@ runtime:
item_ttl: 1s
```

| Parameter name | Optional | Description |
| ----------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `enabled` | Yes | Defaults to `true`. |
| `cache_max_size` | Yes | Maximum cache size. Defaults to `128MiB`. |
| `eviction_policy` | Yes | Cache replacement policy when the cache reaches `cache_max_size`. Defaults to `lru`, which is currently the only supported value. |
| `item_ttl` | Yes | Cache entry expiration duration (Time to Live). Defaults to 1 second. |
| `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. |
| Parameter name | Optional | Description |
| ------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `enabled` | Yes | Defaults to `true`. |
| `cache_max_size` | Yes | Maximum cache size. Defaults to `128MiB`. |
| `eviction_policy` | Yes | Cache replacement policy when the cache reaches `cache_max_size`. Defaults to `lru`, which is currently the only supported value. |
| `item_ttl` | Yes | Cache entry expiration duration (Time to Live). Defaults to 1 second. |
| `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. |
| `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`. |

### Choosing a `cache_key_type`

Expand All @@ -37,9 +38,16 @@ runtime:

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

### Choosing a `hashing_algorithm`

- **`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.
- **`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`.

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).

## `runtime.shutdown_timeout`

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.
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.

```yaml
runtime:
Expand Down
Loading