Skip to content

Add Cross-Network Routing section to replay documentation #2396

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
bglw merged 1 commit into from
May 1, 2026
Merged

Add Cross-Network Routing section to replay documentation #2396

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
37 changes: 35 additions & 2 deletions networking/dynamic-request-routing.html.markerb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,7 @@
```

<div class="note icon">
By default, cross-app routing works within the same organization. To route to apps in other organizations, see [Cross-Organization Routing](#cross-organization-routing).
By default, cross-app routing works within the same organization and network. To route across networks, see [Cross-Network Routing](#cross-network-routing). To route to apps in other organizations, see [Cross-Organization Routing](#cross-organization-routing).
</div>

You can combine multiple fields:
Expand Down Expand Up @@ -114,7 +114,7 @@
## Replay JSON Format

Your app can set the response content-type to `application/vnd.fly.replay+json` and include replay instructions in the response body.
For a complex replay the JSON body is easier to compose than the header format, and also supports more functionality.

Check warning on line 117 in networking/dynamic-request-routing.html.markerb

View workflow job for this annotation

GitHub Actions / Vale linter 

[vale] reported by reviewdog 🐶
[Fly.WordList] Consider using 'capability' or 'feature' instead of 'functionality'.

Raw Output:
{"message": "[Fly.WordList] Consider using 'capability' or 'feature' instead of 'functionality'.", "location": {"path": "networking/dynamic-request-routing.html.markerb", "range": {"start": {"line": 117, "column": 104}}}, "severity": "INFO"}

### JSON Structure

Expand Down Expand Up @@ -174,7 +174,7 @@
- **Session-based**: Cache replays for specific cookie or header values

<div class="note icon">
**Note**: Replay caching is an optimization, not a guarantee. Your app should _not_ depend on this mechanism to function.

Check warning on line 177 in networking/dynamic-request-routing.html.markerb

View workflow job for this annotation

GitHub Actions / Vale linter 

[vale] reported by reviewdog 🐶
[Fly.Spelling] Is '_not_' a typo?

Raw Output:
{"message": "[Fly.Spelling] Is '_not_' a typo?", "location": {"path": "networking/dynamic-request-routing.html.markerb", "range": {"start": {"line": 177, "column": 80}}}, "severity": "INFO"}
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>
Expand Down Expand Up @@ -232,8 +232,8 @@
```

In this example:
- Replays for requests to `/` (and its subpaths) are cached for 5 minutes based on the `session_id` cookie value

Check warning on line 235 in networking/dynamic-request-routing.html.markerb

View workflow job for this annotation

GitHub Actions / Vale linter 

[vale] reported by reviewdog 🐶
[Fly.Spelling] Is 'subpaths' a typo?

Raw Output:
{"message": "[Fly.Spelling] Is 'subpaths' a typo?", "location": {"path": "networking/dynamic-request-routing.html.markerb", "range": {"start": {"line": 235, "column": 40}}}, "severity": "INFO"}
- Replays for requests to `/api` (and its subpaths) are cached for 10 minutes based on the `Authorization` header value

Check warning on line 236 in networking/dynamic-request-routing.html.markerb

View workflow job for this annotation

GitHub Actions / Vale linter 

[vale] reported by reviewdog 🐶
[Fly.Spelling] Is 'subpaths' a typo?

Raw Output:
{"message": "[Fly.Spelling] Is 'subpaths' a typo?", "location": {"path": "networking/dynamic-request-routing.html.markerb", "range": {"start": {"line": 236, "column": 43}}}, "severity": "INFO"}
- When multiple rules match, the longest matching path takes precedence

If your app accepts requests for multiple hostnames, you can narrow the configuration by specifying a hostname in `path_prefix`:
Expand Down Expand Up @@ -446,7 +446,40 @@

This allows you to build router apps that can dynamically route requests to other apps.

By default, cross-app routing works within the same organization. To route to apps in other organizations, see [Cross-Organization Routing](#cross-organization-routing).
By default, cross-app routing works within the same organization and the same [private network](/docs/networking/private-networking/).

### Cross-Network Routing

By default, `fly-replay` with `app=` only routes to apps within the same private network. If you have multiple networks within your organization and need to replay requests across them, you can enable cross-network replays for your organization.

<div class="note icon">
**Note**: Cross-network replay restrictions only apply to same-org replays. Cross-organization replays (via the [allowlist](#cross-organization-routing)) are not affected by this setting.
</div>

#### Enabling Cross-Network Replays

Only organization admins can manage this setting. You can enable cross-network replays via the dashboard or CLI.

**Dashboard:**

Go to your organization's settings page and find the **Routing** section. Use the **Cross-Network Replay** toggle to enable or disable cross-network replays.

**CLI:**

Check the current status:
```cmd
fly orgs cross-network-replays status --org <your-org>
```

Enable cross-network replays:
```cmd
fly orgs cross-network-replays enable --org <your-org>
```

Disable cross-network replays:
```cmd
fly orgs cross-network-replays disable --org <your-org>
```

### Cross-Organization Routing

Expand Down
Loading