Update

Author: PeterCxy

blueprints/per-user-dev-environments.html.md

@@ -16,7 +16,7 @@ This blueprint explains how to use Fly Machines to securely host ephemeral devel
 Your architecture should include:
 
 - **Router app(s)**
-    - A Fly.io app to handle requests to wildcard subdomains (`*.example.com`). Uses `fly-replay` headers to transparently redirect each request to the correct app and machine. If you have clusters of users (or robots) in different geographic regions, you can spin up a router app in multiple regions (you might also want to consider a globally distributed datastore like [Upstash for Redis](https://fly.io/docs/upstash/redis/#what-you-should-know)). 
+    - A Fly.io app to handle requests to wildcard subdomains (`*.example.com`). Uses `fly-replay` headers to transparently redirect each request to the correct app and machine. If you have clusters of users (or robots) in different geographic regions, you can spin up a router app in multiple region to increase reliability and reduce latency (you might also want to consider a globally distributed datastore like [Upstash for Redis](https://fly.io/docs/upstash/redis/#what-you-should-know)). 
 - **User apps (pre-created)**
     - Dedicated per-user (or per-robot) Fly apps, each containing isolated Fly Machines. App and Machine creation is not instantaneous, so we recommend provisioning a pool of these before you need them so you can quickly assign upon request.
 - **Fly Machines (with optional volumes)**
@@ -32,7 +32,7 @@ Your router app handles all incoming wildcard traffic. Its responsibility is sim
 
 - Extract subdomains (like `alice.example.com` → `alice-123`).
 - Look up the correct app (and optionally machine ID) for that user.
-- Issue a `fly-replay` header directing the Fly Proxy to [internally redirect the request](https://fly.io/docs/networking/dynamic-request-routing) (this should add no more than ~10 milliseconds of latency).
+- Issue a `fly-replay` header directing the Fly Proxy to [internally redirect the request](https://fly.io/docs/networking/dynamic-request-routing) (this should add no more than ~10 milliseconds of latency if the router app is deployed close to the user).
 - When appropriate, use [replay caching](https://fly.io/docs/networking/dynamic-request-routing/#replay-caching) to further reduce latency and load on the router app.
 - Make sure you've added [a wildcard domain](https://fly.io/docs/networking/custom-domain/#get-certified) (*.example.com) to your router app (read more about the [certificate management endpoint here](https://fly.io/docs/networking/custom-domain-api/)).
 

networking/dynamic-request-routing.html.markerb

@@ -57,22 +57,23 @@ 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:
+In cases where the replay target does not change often, you can use the `fly-replay-cache` mechanism to relieve the original app of some load. Here's how it works:
 - Issue a `fly-replay` header as usual
 - Set `fly-replay-cache: example.com/some/path/*`
-  - This needs to be a path-matching pattern ending with a wildcard `/*`. This is where the cached replay is applied to.
-  - The domain part should not include ports; i.e. use `example.com`, not `example.com:80` or `example.com:443`.
+  - This needs to be a path-matching pattern ending with a wildcard `/*`. This is where the cached replay is applied.
+  - The domain part should not include ports; use `example.com`, not `example.com:80`.
   - 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 may proactively invalidate the cache by
 - Issuing a `fly-replay` back to the origin
 - 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.
+<div class="note icon">
+**Note**: Replay caching is an optimization, not a guarantee. Your app should _not_ depend on this mechanism to function.
+The app issuing `fly-replay` 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` should still have multiple instances deployed in multiple regions.
+</div>
 
 ## Implementation Details
 
@@ -88,6 +89,7 @@ For large uploads that exceed the 1MB limit, consider:
 
 For `fly-replay-cache`, the following limitations apply:
 - The `state` field cannot be set in the `fly-replay` intended to be cached
+- The TTL needs to be a minimum of 10 seconds
 - 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