Skip to content

Add documentation for cross-org fly-replay #2325

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
Dec 18, 2025
Merged

Add documentation for cross-org fly-replay #2325

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
45 changes: 40 additions & 5 deletions networking/dynamic-request-routing.html.markerb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@
|`region` | The region(s) to route the request to. Accepts comma-separated list of [region codes](/docs/reference/regions/) |
|`instance` | The ID of a specific Machine to route to |
|`prefer_instance` | The ID of a specific Machine to route to, if possible |
|`app` | The name of another app (in same organization) to route to |
|`app` | The name of another app to route to |
|`state` | Optional string included in `fly-replay-src` header on replay |
|`elsewhere` | If `true`, excludes responding Machine from next load-balance |

Expand Down Expand Up @@ -58,12 +58,16 @@

Route to another app:
```
fly-replay: app=app-in-same-org
fly-replay: app=target-app
```

<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).
</div>

You can combine multiple fields:
```
fly-replay: region="sjc,any";app=app-in-same-org
fly-replay: region="sjc,any";app=target-app
```

<div class="note icon">
Expand All @@ -86,7 +90,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 93 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": 93, "column": 104}}}, "severity": "INFO"}

### JSON Structure

Expand All @@ -97,7 +101,7 @@
|`region` | The region(s) to route the request to. Accepts comma-separated list of [region codes](/docs/reference/regions/) |
|`instance` | The ID of a specific Machine to route to |
|`prefer_instance` | The ID of a specific Machine to route to, if possible |
|`app` | The name of another app (in same organization) to route to |
|`app` | The name of another app to route to |
|`state` | Optional string included in `fly-replay-src` header on replay |
|`elsewhere` | If `true`, excludes responding Machine from next load-balance |
|`transform.path` | Rewrite the path and query parameters of the request |
Expand Down Expand Up @@ -134,7 +138,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 141 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": 141, "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 @@ -192,8 +196,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 199 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": 199, "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 200 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": 200, "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 @@ -383,4 +387,35 @@
fly-replay: app=customer-function-app
```

This allows you to build router apps that can dynamically route requests to other apps in your organization.
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).

### Cross-Organization Routing

By default, `fly-replay` with `app=` only works for apps within the same organization. To allow replay requests from apps in other organizations, you must configure an allowlist on the target organization.

#### Configuring Allowed Replay Sources

Only organization admins can manage the replay sources allowlist, and must also have read permissions or higher on the source organization being added. You can configure replay sources via the dashboard or CLI.

**Dashboard:**

Go to your organization's settings page and find the **Routing** section. Under **Cross-Organization Routing**, you can add or remove organizations that are allowed to send replay requests to apps in your organization.

**CLI:**

List organizations currently allowed to send replays:
```cmd
fly orgs replay-sources list --org <target-org>
```

Add organizations to the allowlist interactively:
```cmd
fly orgs replay-sources add --org <target-org>
```

Remove organizations from the allowlist interactively:
```cmd
fly orgs replay-sources remove --org <target-org>
```
Loading