Web types are the browser package (
@fireweaveai/web-sdk). Server packages use the non-Web names. Go’s runtime type is fireweave.Runtime; its OpenFeature constructor is openfeature.NewProvider(client).
Older SDK architecture sketches show
phc_ keys, exposurePolicy.defaultSend: true, and adapter("posthog") construction. Those are stale. Production credentials are a FireWeave project key (project-api-key_…). sendExposure defaults false. Construct a concrete adapter class; do not pass a string adapter name.Adapters
Remote adapters authenticate with
Authorization: Bearer <key>. Node, Python, and Go remote adapters read FW_API_URL and FW_PROJECT_API_KEY when options are omitted. Java takes FireweaveConfig.host / projectApiKey only — no System.getenv. Web requires constructor apiUrl and apiKey — no environment.
https is required off-loopback; http is loopback-only. Host allowlists differ: Node/Web default to FireWeave hosts + loopback (plus the configured hostname); Python/Go/Java defaults include PostHog hosts + loopback (Java in particular will reject an unknown fw-server host unless you set allowedHosts).
Never send PostHog phc_ / phs_ / phx_ keys on the FireWeave remote path. The web adapter rejects those shapes.
Evaluation path
- The OpenFeature client or
FireweaveClientsuppliesflagKey, expected type, default, and context (targetingKey+ attributes). - The provider (if used) maps OF context to the canonical evaluation context. Reserved
fireweave.*keys other thanfireweave.groups/fireweave.groupPropertiesyieldInvalidContext. - The runtime checks lifecycle. Not ready or already closed → default +
NotReady/AlreadyClosed. - The adapter evaluates (
evaluateFlags/ language equivalent). Remote:POST /v1/flags/evaluate(side-effect-free). - The runtime coerces the typed value or returns
TypeMismatch+ default. - A Decision is built (
flagKey,value,variant,reason, error fields, metadata). - OpenFeature maps that to
ResolutionDetails. Native callers get the Decision (or a typed getter that readsvalue). - Exposure emission runs only when
sendExposureis true (default false) or you callexposures.record.
evaluateSync). initialize / identify / setContext prefetch asynchronously. A prefetch that exceeds DEFAULT_FLAGS_READY_TIMEOUT_MS (5000) leaves the runtime STALE.
Lifecycle states
Verified states:UNINITIALIZED | INITIALIZING | READY | STALE | ERROR | FATAL | SHUTDOWN.
OpenFeature status mapping used by the SDKs: UNINITIALIZED / INITIALIZING / SHUTDOWN → NOT_READY; READY → READY; STALE → STALE; ERROR → ERROR; FATAL → FATAL.
Default shutdown timeout is 10_000 ms. Node, Python, and Web client shutdown flush exposures first. Java close() and runtime.shutdown() do not.
Wire protocol
Spec version0.1.0. Paths implemented by remote adapters:
Auth on the wire:
Authorization: Bearer <FireWeave project/runtime key>. The spec also accepts x-api-key; do not document that header as universally sent by every adapter.
Evaluate request fields include targetingKey, attributes, groups, groupProperties, flagKeys. Register body: targetingKey, kind, environment, properties. Response shape: { "ok": true, "targetingKey": "…" }.
Production hostnames such as
app-server.fireweave.ai appear on the Node/Web allowlist. Whether they are the customer-facing fw-server URL is not verified from the SDK repo. Configure FW_API_URL / apiUrl / Java host from your project, and add that hostname to Java allowedHosts if it is not already listed.OpenFeature boundary
FireWeave ships a provider in all five packages (OF spec floor v0.8.0, ADR-0003). Pins:
Tracking (OpenFeature spec §6) is not implemented. Releases, exposures, signals, targets, and capabilities live on
FireweaveClient.
Packages
See Compatibility for the type and adapter matrix, and Package index for publish state.