Add docs for fly-replay-cache

Author: PeterCxy

networking/dynamic-request-routing.html.markerb

@@ -55,6 +55,25 @@ You can combine multiple fields:
 fly-replay: region=sjc;app=app-in-same-org
 ```
 
+## Replay Caching
+
+In cases where the replay target does not change often under some path, you may use the `fly-replay-cache` mechanism to relieve the original app of some unnecessary load. Here's how it works:
+- Issue a `fly-replay` header as usual
+- Set `fly-replay-cache: example.com/some/path/*`
+  - This is a globbing pattern for the path under which the replay will be cached and used for subsequent requests.
+  - The domain part should not include ports; i.e. use `example.com`, not `example.com:80` or `example.com:443`.
+  - The pattern must also match the current path of the request.
+- Set `fly-replay-cache-ttl-secs: number_of_seconds`
+  - This is simply a TTL attached to the replay cache. It needs to be at least 10 seconds.
+
+If the replay target does eventually change, the replay target machine / app may proactively invalidate the cache by
+- Issuing a `fly-replay` back to the original app / machine
+- Setting `fly-replay-cache: invalidate`
+
+It is also worth noting that replay caching is an optimization, not a guarantee. Your app should _not_ depend on this mechanism to function.
+The app issuing `fly-replay`s still serves as the ultimate source of truth, and we may decide to consult that app at any moment even if a replay cache has previously been set.
+To ensure reliable operation, the app issuing `fly-replay`s should still have multiple instances deployed in multiple regions.
+
 ## Implementation Details
 
 ### Requirements and Limitations
@@ -67,6 +86,11 @@ For large uploads that exceed the 1MB limit, consider:
 - Using direct-to-storage uploads where possible
 - Using the [fly-prefer-region](#the-fly-prefer-region-request-header) header instead
 
+For `fly-replay-cache`, the following limitations apply:
+- The `state` field cannot be set in the `fly-replay` intended to be cached
+- Only one step of lookup is performed in the cache; as such, if the target app issues another `fly-replay-cache`, the caching behavior in this case is undefined
+- The `fly-replay-src` header (described below) will _not_ be set for requests replayed through the cache
+
 ### The fly-replay-src Header
 
 When a request is replayed, Fly Proxy adds a `fly-replay-src` header containing metadata about the original request:
@@ -80,6 +104,8 @@ When a request is replayed, Fly Proxy adds a `fly-replay-src` header containing
 
 This header is useful for tracking request paths and implementing consistency patterns. See the [official Ruby client](https://github.com/superfly/fly-ruby/blob/main/lib/fly-ruby/regional_database.rb#L74-L76+external) for an example of using these fields to prevent read-your-write inconsistency.
 
+This header is not set when the request is replayed through a cached `fly-replay` entry.
+
 ## Alternative Routing Headers
 
 For cases where `fly-replay` isn't suitable, Fly.io provides two alternative request headers: