mirror of
https://github.com/prdlk/dotfiles.git
synced 2026-11-04 19:57:37 +00:00
Prad NukalaandClaude Fable 5
20891f3910
gitconfig: name/email from chezmoi data, gh credential helper by PATH lookup (portable to darwin). claude: no credentials, history, projects, sessions, or plugin caches. ssh config as private_ (0600). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
60 lines
3.6 KiB
Markdown
60 lines
3.6 KiB
Markdown
# Cloudflare Flagship
|
|
|
|
Feature flag service for controlling feature visibility without redeploying code. Define flags with targeting rules and percentage-based rollouts, then evaluate them in Workers via a native binding or from any JavaScript runtime via the OpenFeature SDK.
|
|
|
|
## When to Use
|
|
|
|
| Need | Use Flagship? | Alternative |
|
|
|------|--------------|-------------|
|
|
| Feature toggles (on/off) | Yes | — |
|
|
| Gradual rollouts (percentage-based) | Yes | — |
|
|
| A/B testing with attribute targeting | Yes | — |
|
|
| Multi-variant configuration delivery | Yes | — |
|
|
| Environment-specific config (dev/staging/prod) | Consider | Wrangler environments, secrets |
|
|
| Static config that never changes | No | `wrangler.jsonc` vars |
|
|
| Per-request rate limiting | No | Rate Limiting rules |
|
|
|
|
## Key Concepts
|
|
|
|
- **Apps** — Top-level organizational unit. Maps to a project or service. Each account can have multiple apps.
|
|
- **Flags** — Named feature toggles with a key, variations, targeting rules, and enabled/disabled state.
|
|
- **Variations** — Possible values a flag returns. Types: boolean, string, number, JSON object. All variations on a flag must share the same type.
|
|
- **Targeting rules** — Sequential, priority-ordered conditions that determine which variation to serve. First match wins; no match returns the default.
|
|
- **Evaluation context** — Key-value attributes (`userId`, `country`, `plan`, etc.) passed at evaluation time for rule matching and rollout bucketing.
|
|
- **Percentage rollouts** — Gradually release to a fraction of users. Consistent hashing on a configurable attribute ensures sticky bucketing.
|
|
|
|
## Two Evaluation Paths
|
|
|
|
| Path | Runtime | Package | Latency | Auth |
|
|
|------|---------|---------|---------|------|
|
|
| **Binding** (`env.FLAGS`) | Workers only | `@cloudflare/workers-types` | Lowest (no HTTP) | Automatic via binding |
|
|
| **OpenFeature SDK** | Workers, Node.js, browser | `@cloudflare/flagship` + `@openfeature/server-sdk` or `@openfeature/web-sdk` | HTTP per eval (server) or prefetch (client) | API token or binding passthrough |
|
|
|
|
**Recommendation:** Use the binding inside Workers. Use the SDK when running outside Workers or when you need OpenFeature vendor-neutrality.
|
|
|
|
## Reading Order
|
|
|
|
| Task | Read |
|
|
|------|------|
|
|
| Set up Flagship in a Worker | `configuration.md` → `api.md` |
|
|
| Evaluate flags in code | `configuration.md` → `patterns.md` |
|
|
| Manage flags via REST API | `api.md` → `patterns.md` |
|
|
| Design targeting rules & rollouts | `patterns.md` → `gotchas.md` |
|
|
| Debug flag evaluation issues | `gotchas.md` → `api.md` |
|
|
|
|
REST API note: management endpoints use Cloudflare v4 envelopes (`result`, `result_info`, `errors`) and snake_case fields. The `/evaluate` endpoint is the exception: it is not enveloped and returns OpenFeature-style camelCase.
|
|
|
|
## In This Reference
|
|
|
|
- **[api.md](./api.md)** — REST API endpoints, binding methods, OpenFeature SDK, schemas
|
|
- **[configuration.md](./configuration.md)** — Wrangler binding setup, SDK installation, TypeScript types
|
|
- **[patterns.md](./patterns.md)** — Flag CRUD via API, targeting rules, rollouts, OpenFeature usage
|
|
- **[gotchas.md](./gotchas.md)** — Common errors, limits, anti-patterns, troubleshooting
|
|
|
|
## See Also
|
|
|
|
- **[Flagship API reference](https://developers.cloudflare.com/api/resources/flagship/)** — Source of truth for REST API paths, envelopes, and response fields
|
|
- **[../workers/](../workers/)** — Workers runtime (Flagship runs inside Workers)
|
|
- **[../kv/](../kv/)** — KV storage (Flagship uses KV infrastructure for flag delivery)
|
|
- **[../wrangler/](../wrangler/)** — Wrangler CLI for deployment and config
|