diff --git a/docs/concepts/cache-warmer.mdx b/docs/concepts/cache-warmer.mdx
index a35bdb08..cebbdf20 100644
--- a/docs/concepts/cache-warmer.mdx
+++ b/docs/concepts/cache-warmer.mdx
@@ -69,3 +69,68 @@ Users can manually recompute slow queries from the Cosmo Studio. Currently, reco
+
+## In-Memory Fallback Cache Warming
+
+The in-memory fallback cache warming feature preserves the planner cache across hot config reloads and schema changes, allowing it to be rewarmed automatically and reducing latency spikes during restarts.
+
+### How It Works
+
+After the router has started, the router can be reloaded for two reasons: either a config change or a schema change. Due to the structure of the router internals, we have two slight variations on how we handle the in-memory switchover cache warming:
+
+1. **Before Reload**: In case of config changes (from hot config reloading), the router extracts all queries from the current plan cache, preserving the queries that were in the planner cache before the cache is cleared for reloading.
+
+2. **During Reload**: The router with the updated config receives the queries from the previous plan cache that existed before reloading, and uses them to warm up its current plan cache before serving traffic.
+
+3. **Result**: The updated router reloads with a fully warmed cache, eliminating latency spikes that would normally occur during cold starts.
+
+When using the in-memory fallback, the first start will still experience a cold start, as there is no prior populated planner cache. *Only subsequent reloads* will benefit from the in-memory fallback.
+
+### When to Use the In-Memory Fallback
+
+The in-memory fallback can be used either as a fallback method or as a primary method for cache warming. This depends on the router configuration; the defaults provided by the router enable it as a fallback to the Cosmo Cloud CDN cache warmer, which is a feature that needs to be enabled explicitly in Cosmo. However, it can also be used as the primary method of rewarming the plan cache.
+
+When the in-memory fallback is used with the Cosmo Cloud CDN cache warmer, the fallback is triggered when either:
+* Getting the list of operations from the CDN fails
+* The request to the CDN succeeds but does not return a list of operations (either no operations are cached or the manifest has not been created yet)
+
+In these cases, the router will use the fallback and load the list of operations from the in-memory fallback (if any operations exist).
+
+
+ The in-memory fallback cannot be used as a fallback for sources other than the Cosmo Cloud CDN cache warmer.
+
+
+### Configuration
+
+The in-memory fallback can be enabled as a fallback for the CDN cache warmer. To do this, ensure:
+
+* Cache warming is enabled in the router configuration (`cache_warmup.enabled: true`)
+* `source.cdn.enabled` is set to `true` (this is true by default and does not need to be explicitly specified)
+* `in_memory_fallback` is set to `true` (default)
+
+```yaml
+cache_warmup:
+ enabled: true
+ in_memory_fallback: true # Enabled by default
+
+ # This is implicitly enabled by default, you do not need to explicitly specify the following
+ source:
+ cdn:
+ enabled: true
+```
+
+To use the in-memory fallback as the primary source, ensure:
+
+* Cache warming is enabled in the router configuration (`cache_warmup.enabled: true`)
+* `source.cdn.enabled` is set to `false` (this needs to be specified explicitly, as the default is true)
+* `in_memory_fallback` is set to `true` (default)
+
+```yaml
+cache_warmup:
+ enabled: true
+ in_memory_fallback: true # Enabled by default
+
+ source:
+ cdn:
+ enabled: false
+```
diff --git a/docs/router/configuration.mdx b/docs/router/configuration.mdx
index 72cef7eb..a766beca 100644
--- a/docs/router/configuration.mdx
+++ b/docs/router/configuration.mdx
@@ -2173,13 +2173,14 @@ apollo_router_compatibility_flags:
## Cache warmer
-| Environment Variable | YAML | Required | Description | Default Value |
-| -------------------- | ---------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
-| | enabled | | Enable the cache warmer. | false |
-| | workers | | The number of workers for the cache warmup to run in parallel. Higher numbers decrease the time to warm up the cache but increase the load on the system. | 8 |
-| | items_per_second | | The number of cache warmup items to process per second. Higher numbers decrease the time to warm up the cache but increase the load on the system. | 50 |
-| | timeout | | The timeout for warming up the cache. This can be used to limit the amount of time cache warming will block deploying a new config. The period is specified as a string with a number and a unit, e.g. 10ms, 1s, 1m, 1h. The supported units are 'ms', 's', 'm', 'h'. | 30s |
-| | source | | The source of the cache warmup items. Only one can be specified. If empty, the cache warmup source is the Cosmo CDN and it requires a graph to be set. | |
+| Environment Variable | YAML | Required | Description | Default Value |
+| --------------------------------------------------- | ------------------------------ | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
+| CACHE_WARMUP_ENABLED | enabled | | Enable the cache warmer. | false |
+| CACHE_WARMUP_ITEMS_PER_SECOND | items_per_second | | The number of cache warmup items to process per second. Higher numbers decrease the time to warm up the cache but increase the load on the system. | 50 |
+| CACHE_WARMUP_TIMEOUT | timeout | | The timeout for warming up the cache. This can be used to limit the amount of time cache warming will block deploying a new config. The period is specified as a string with a number and a unit, e.g. 10ms, 1s, 1m, 1h. The supported units are 'ms', 's', 'm', 'h'. | 30s |
+| CACHE_WARMUP_WORKERS | workers | | The number of workers for the cache warmup to run in parallel. Higher numbers decrease the time to warm up the cache but increase the load on the system. | 8 |
+| | source | | The source of the cache warmup items. Only one can be specified. If empty, the cache warmup source is the Cosmo CDN and it requires a graph to be set. | |
+| CACHE_WARMUP_IN_MEMORY_FALLBACK | in_memory_fallback | | Enable in-memory switchover that persists the plan cache across router restarts. When enabled, the router will use queries from the previous instance's plan cache to warm up the new cache on restart. Can be used as a fallback or as the primary source for cache warming. | true |
### Example YAML config:
@@ -2191,15 +2192,17 @@ cache_warmup:
workers: 8
items_per_second: 50
timeout: 30s
+ in_memory_fallback: true
```
### Source
The source of the cache warmup items. Only one can be specified. If empty, the cache warmup source is the Cosmo CDN and it requires a graph to be set.
-| Environment Variable | YAML | Required | Description | Default Value |
-| -------------------- | ---- | ---------------------- | ------------------------------------------------------------ | ------------- |
-| | path | | The path to the directory containing the cache warmup items. | |
+| Environment Variable | YAML | Required | Description | Default Value |
+| -------------------- | -------------- | ---------------------- | ------------------------------------------------------------ | ------------- |
+| | filesystem.path | | The path to the directory containing the cache warmup items. | |
+| | cdn.enabled | | Whether the CDN is the source for warming the cache. | true |
### Example YAML config:
@@ -2211,6 +2214,10 @@ cache_warmup:
workers: 8
items_per_second: 50
timeout: 30s
+ in_memory_fallback: true
source:
- path: "./cache-warmer/operations"
+ cdn:
+ enabled: true
+ filesystem:
+ path: "./cache-warmer/operations"
```
diff --git a/docs/router/deployment/config-hot-reload.mdx b/docs/router/deployment/config-hot-reload.mdx
index daa467a3..439b878e 100644
--- a/docs/router/deployment/config-hot-reload.mdx
+++ b/docs/router/deployment/config-hot-reload.mdx
@@ -38,6 +38,8 @@ This will behave similarly to the CDN polling with regard to router lifecycle.
WebSocket or SSE (Server-Sent Events) connections are long-lived and will be closed immediately after the active graph instance is shut down. Clients must reconnect to restore the connection.
-### Latency Implications
+### Latency Implications and Cache Warming
-When the configuration is swapped, a new graph is created internally. This implies that the planner cache is invalidated, as a plan is coupled to a specific graph. In high-traffic scenarios, this can increase latency. We are currently working on a solution to mitigate this by warming up the cache with the latest top 100 operations during the initial router start and configuration changes.
+When the configuration is swapped, a new graph is created internally. This implies that the planner cache is invalidated, as a plan is coupled to a specific graph. In high-traffic scenarios, this can increase latency.
+
+To mitigate this issue, the router supports **cache warming**. For more details on cache warming, see the [Cache Warmer documentation](/concepts/cache-warmer).