diff --git a/website/docs/features/caching/index.md b/website/docs/features/caching/index.md index c17f1f49f..76880058e 100644 --- a/website/docs/features/caching/index.md +++ b/website/docs/features/caching/index.md @@ -50,7 +50,7 @@ Every cache type (`sql_results`, `search_results`, `embeddings`) supports the fo | `max_size` | Yes | `128MiB` | Maximum cache size. Defaults to `128MiB`. | | `eviction_policy` | Yes | `lru` | Cache replacement policy when the cache reaches `max_size`. Defaults to `lru`. Supports `lru` (Least Recently Used), `lfu` (Least Frequently Used), and `tiny_lfu` (Window TinyLFU, higher hit rate for skewed access patterns). See [Choosing an `eviction_policy`](#choosing-an-eviction_policy). | | `item_ttl` | Yes | `1s` | Cache entry expiration duration (Time to Live). Defaults to 1 second. | -| `hashing_algorithm` | Yes | `xxh3` | Selects which hashing algorithm is used to hash the cache keys when storing the results. Defaults to `xxh3`. Supports `xxh3`, `ahash`, `siphash`, `blake3`, `xxh32`, `xxh64`, or `xxh128`. | +| `hashing_algorithm` | Yes | `xxh3` | Selects which hashing algorithm is used to hash the cache keys when storing the results. Defaults to `xxh3`. Supports `xxh3`, `ahash`, `siphash`, `blake3`, `xxh64`, or `xxh128`. `xxh32` is deprecated. | | `engine` | Yes | - | Ignored. Accepted so existing spicepods still load. See [The `engine` parameter](#the-engine-parameter). | ### Choosing an `eviction_policy` @@ -121,7 +121,8 @@ The hashing algorithm determines how cache keys are hashed before being stored, - **`siphash`:** 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#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`. - **`blake3`:** Uses the [BLAKE3](https://github.com/BLAKE3-team/BLAKE3) cryptographic hash function. BLAKE3 is a fast, parallelizable hash function that provides cryptographic security while maintaining high performance. It is suitable for scenarios requiring both speed and cryptographic guarantees. -- **`xxh32`, `xxh64`, `xxh128`:** Variants of the XXH hashing algorithm with different output sizes. These algorithms offer a balance between speed and collision resistance, with larger hash sizes providing better collision resistance at the cost of performance. +- **`xxh64`, `xxh128`:** Variants of the XXH hashing algorithm with different output sizes. These algorithms offer a balance between speed and collision resistance, with larger hash sizes providing better collision resistance at the cost of performance. +- **`xxh32`:** Deprecated, and will be removed in a future release. A runtime that sets it logs a warning at startup. Use `xxh3` instead. Use `xxh3` (the default) for its superior speed in most scenarios. Use `ahash`, `xxh64` or `xxh128` for reduced collision probability when caching a large number of queries. Use `blake3` when cryptographic security is required. Use `siphash` when protection against hash flooding attacks is a priority. diff --git a/website/docs/reference/spicepod/runtime.md b/website/docs/reference/spicepod/runtime.md index 527baf3c7..4062102da 100644 --- a/website/docs/reference/spicepod/runtime.md +++ b/website/docs/reference/spicepod/runtime.md @@ -77,7 +77,7 @@ Runtime caches support common configuration parameters: | `max_size` | Yes | `128MiB` | Maximum cache size. Defaults to `128MiB`. | | `eviction_policy` | Yes | `lru` | Cache replacement policy when the cache reaches `max_size`. Defaults to `lru`. Supports `lru` (Least Recently Used), `lfu` (Least Frequently Used), and `tiny_lfu` (Window TinyLFU, higher hit rate for skewed access patterns). | | `item_ttl` | Yes | `1s` | Cache entry expiration duration (Time to Live). Defaults to 1 second. | -| `hashing_algorithm` | Yes | `xxh3` | Selects which hashing algorithm is used to hash the cache keys when storing the results. Defaults to `xxh3`. Supports `xxh3`, `ahash`, `siphash`, `blake3`, `xxh32`, `xxh64`, or `xxh128`. | +| `hashing_algorithm` | Yes | `xxh3` | Selects which hashing algorithm is used to hash the cache keys when storing the results. Defaults to `xxh3`. Supports `xxh3`, `ahash`, `siphash`, `blake3`, `xxh64`, or `xxh128`. `xxh32` is deprecated. | | `engine` | Yes | - | Ignored. Accepted so existing spicepods still load; `engine: pingora` logs a one-time warning. [Learn more](../../features/caching#the-engine-parameter). | ### `runtime.caching.search_results` @@ -151,7 +151,8 @@ Use `sql` for the lowest latency with identical queries that do not include dyna - **`siphash`:** 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#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`. - **`blake3`:** Uses the [BLAKE3](https://github.com/BLAKE3-team/BLAKE3) cryptographic hash function. BLAKE3 is a fast, parallelizable hash function that provides cryptographic security while maintaining high performance. It is suitable for scenarios requiring both speed and cryptographic guarantees. -- **`xxh32`, `xxh64`, `xxh128`:** Variants of the XXH hashing algorithm with different output sizes. These algorithms offer a balance between speed and collision resistance, with larger hash sizes providing better collision resistance at the cost of performance. +- **`xxh64`, `xxh128`:** Variants of the XXH hashing algorithm with different output sizes. These algorithms offer a balance between speed and collision resistance, with larger hash sizes providing better collision resistance at the cost of performance. +- **`xxh32`:** Deprecated, and will be removed in a future release. A runtime that sets it logs a warning at startup. Use `xxh3` instead. Use `xxh3` (the default) for its superior speed in most scenarios. Use `ahash`, `xxh64` or `xxh128` for reduced collision probability when caching a large number of queries. Use `blake3` when cryptographic security is required. Use `siphash` when protection against hash flooding attacks is a priority.