feat: add Playground RFC#35
Open
rhamzeh wants to merge 1 commit into
Open
Conversation
rhamzeh
force-pushed
the
feat/add-playground-rfc
branch
from
0da2839 to
7ec6001
Compare
There was a problem hiding this comment.
Pull request overview
Adds a new draft RFC proposing an open-source OpenFGA Playground architecture, covering deployment surfaces, backend adapter design, fga serve proxy concepts, shared config, and alternatives.
Changes:
- Introduces a full Playground RFC document.
- Defines proposed packages, adapters, proxy endpoints, security layers, drawbacks, alternatives, and unresolved questions.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| ### Architecture overview | ||
|
|
||
| The playground shell talks to the OpenFGA API through a pluggable `BackendAdapter` interface. Three adapters ship with the project, each suited to a different deployment mode. In all three cases, the shell is identical and only the adapter changes. |
|
|
||
| 1. **Localhost binding**. The proxy binds to `localhost` by default; remote network access is impossible without an explicit `--host` flag. | ||
| 2. **Origin validation**. Browser requests from any `Origin` other than `localhost`, `127.0.0.1`, or `::1` are rejected, preventing malicious pages from making cross-origin requests to the local server. | ||
| 3. **Session token authentication**. By default, `fga serve` generates a random session token at startup and prints it. All requests (except `/healthz`) must include the token via the `X-Serve-Token` header or `?token=` query parameter. The playground reads the token from the URL on first load, persists it in `sessionStorage`, and includes it in every subsequent request. A user-supplied token can be set with `--token <value>`, or token auth can be disabled entirely with `--no-token` (not recommended). This protects against other local processes (including malicious browser tabs not protected by the Origin check) using the configured server credentials. |
|
|
||
| **`WASMBackendAdapter`**: Calls into a WebAssembly build of OpenFGA running in a Web Worker. The "server" lives entirely in the browser with no network calls. This adapter enables a fully hosted, shareable playground (e.g., `play.openfga.dev`) and an offline-capable experience. Deferred to a future iteration; gated on a WASM build of OpenFGA being available. | ||
|
|
||
| **`ProxyBackendAdapter`**: Calls `fga serve`, a local HTTP proxy that manages server profiles, stores secrets in `~/.config/fga/servers.yaml`, and forwards requests to upstream OpenFGA servers (local, Auth0 FGA, or any other). This enables local development with authenticated servers: it lets the user manage multiple server connections with their credentials in one place and avoids CORS issues by forwarding all requests server-side. It also avoids the issue with the DDirectBackend adapter of storing credentials in the browser. When `fga serve` has session token auth enabled (the default), the playground prompts the user for the token on first connection. |
|
|
||
| - **Framework lock-in for consumers.** VS Code extension webviews are plain HTML/JavaScript contexts. React components cannot be used natively in them without bundling React into the webview's script. The same is true for any non-React documentation framework. | ||
| - **No native Web Component output.** React components are not Web Components. Embedding a React-based model editor in a Vue docs site or a plain HTML page requires wrapping it in an adapter, adding complexity for every consumer. | ||
| - **Version coupling.** Consumers of `@openfga/playground-components` would be forced to use a compatible React version. For Docusaurus that power our documentation site, it is usually tied to the React version Docusaurus needs, which would have the downstream effect of deciding what React version the Playground can support if we want to reuse it's components in the documentation. OpenFGA tooling should outlive individual React major versions; Lit's commitment to the browser standard avoids this problem. |
|
|
||
| - This would make the playground unavailable to users who do not use VS Code. | ||
| - The Web Component approach delivers the same Monaco editor experience in any browser context. | ||
| - A VS Code extension is still a valid future consumer of the Web Components. It would embed `<openfga-model-editor>` in its webview, but building the components first gives us both possibiliities. |
| - Import from and export to the store yaml file. | ||
| - Be able to connect to and switch between multiple stores. | ||
|
|
||
| While we have been pushing folks to use VSCode with the OpenFGA extension in combination with the CLI, the demand for a Playground has not subsided. Users have cited the model graph in particular as an asset when learning the OpenFGA authorization model or explaining the model to coworkers. |
|
|
||
| #### Deployment and self-hosting gaps | ||
|
|
||
| - [openfga/openfga#2503](https://github.com/openfga/openfga/issues/2503): Request for a flag to serve custom static playground content instead of assets bundled in the binary, enabling lightweight Docker images. (Implicitly addressed by this RFC: the playground is a standalone web app, hosted it however one likes, pointing at the API.) |
|
|
||
| #### Sample store browser | ||
|
|
||
| A dropdown lists all sample stores from the `openfga/sample-stores` GitHub repository. Selecting a sample fetches its `.fga.yaml` file and loads the model, tuples, and assertions into the playground. Samples are fetched at runtime so the playground always reflects the latest samples without a rebuild. These should be view only, but are importable into a new store/exportable into yaml. They cannot do any queries on them before importing, though that may be possible in the future once we have the WasmBackend. |
| - **Binary size.** Compiling the OpenFGA server to WASM produces a binary of 10–20 MB+. This is not acceptable for an initial page load, even with compression and lazy loading. | ||
| - **Implementation complexity.** OpenFGA uses a persistence layer (database) that must also be replaced with an in-memory WASM-compatible implementation. This is significant engineering work that goes beyond this RFC's scope. | ||
| - **Reduced need at v1.** A main part of the target audience (developers who want to manage OpenFGA stores, in prod or dev) already have a server. The `fga serve` approach serves them well today. | ||
| - **Architecture readiness.** The `BackendAdapter` interface is explicitly designed to accommodate a WASM adapter in the future. When a WASM build of OpenFGA is available, it can be wrapped as a `WasmBackendAdapter` and plugged in without changing any component or core code. |
|
|
||
| - **Framework lock-in for consumers.** VS Code extension webviews are plain HTML/JavaScript contexts. React components cannot be used natively in them without bundling React into the webview's script. The same is true for any non-React documentation framework. | ||
| - **No native Web Component output.** React components are not Web Components. Embedding a React-based model editor in a Vue docs site or a plain HTML page requires wrapping it in an adapter, adding complexity for every consumer. | ||
| - **Version coupling.** Consumers of `@openfga/playground-components` would be forced to use a compatible React version. For Docusaurus that power our documentation site, it is usually tied to the React version Docusaurus needs, which would have the downstream effect of deciding what React version the Playground can support if we want to reuse it's components in the documentation. OpenFGA tooling should outlive individual React major versions; Lit's commitment to the browser standard avoids this problem. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
This RFC proposes a new, fully open-source OpenFGA Playground that replaces the current hosted iframe experience with a locally run, modular app. It introduces a pluggable architecture (direct,future proxy, and future WASM backends), reusable Web Components, and a richer feature set for modeling, testing, visualization, and debugging. The goal is to eliminate recurring user friction due to CORS or it being in an iframe or remotely hosted, improve maintainability, and make the playground embeddable across docs and developer tooling while keeping the core UX familiar for existing users.
What problem is being solved?
How is it being solved?
What changes are made to solve it?
References
Review Checklist
main