fireweave 2.3.0__tar.gz → 3.0.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- fireweave-3.0.0/PKG-INFO +234 -0
- fireweave-3.0.0/README.md +205 -0
- {fireweave-2.3.0 → fireweave-3.0.0}/pyproject.toml +1 -1
- {fireweave-2.3.0 → fireweave-3.0.0}/src/fireweave/__init__.py +2 -2
- {fireweave-2.3.0 → fireweave-3.0.0}/src/fireweave/application/client.py +23 -48
- {fireweave-2.3.0 → fireweave-3.0.0}/src/fireweave/application/ports.py +6 -6
- {fireweave-2.3.0 → fireweave-3.0.0}/src/fireweave/application/runtime.py +61 -18
- {fireweave-2.3.0 → fireweave-3.0.0}/src/fireweave/domain/decision.py +2 -2
- {fireweave-2.3.0 → fireweave-3.0.0}/src/fireweave/domain/errors.py +51 -15
- {fireweave-2.3.0 → fireweave-3.0.0}/src/fireweave/domain/types.py +3 -3
- {fireweave-2.3.0 → fireweave-3.0.0}/src/fireweave/domain/validation.py +13 -8
- {fireweave-2.3.0 → fireweave-3.0.0}/src/fireweave/infrastructure/adapters/local.py +5 -5
- {fireweave-2.3.0 → fireweave-3.0.0}/src/fireweave/infrastructure/adapters/memory.py +6 -6
- {fireweave-2.3.0 → fireweave-3.0.0}/src/fireweave/infrastructure/adapters/remote.py +42 -13
- fireweave-3.0.0/src/fireweave/start/__init__.py +46 -0
- fireweave-3.0.0/src/fireweave/start/_build_info.py +64 -0
- fireweave-3.0.0/src/fireweave/start/_control_points.py +107 -0
- fireweave-3.0.0/src/fireweave/start/_env.py +43 -0
- fireweave-3.0.0/src/fireweave/start/_facade.py +228 -0
- fireweave-3.0.0/src/fireweave/start/_instance.py +54 -0
- fireweave-3.0.0/src/fireweave/start/_names.py +48 -0
- fireweave-3.0.0/src/fireweave/start/_resolve.py +242 -0
- fireweave-3.0.0/src/fireweave/start/_state.py +624 -0
- fireweave-3.0.0/src/fireweave.egg-info/PKG-INFO +234 -0
- {fireweave-2.3.0 → fireweave-3.0.0}/src/fireweave.egg-info/SOURCES.txt +19 -1
- {fireweave-2.3.0 → fireweave-3.0.0}/tests/test_architecture_layers.py +19 -5
- {fireweave-2.3.0 → fireweave-3.0.0}/tests/test_concurrency.py +2 -2
- {fireweave-2.3.0 → fireweave-3.0.0}/tests/test_control_points.py +3 -23
- {fireweave-2.3.0 → fireweave-3.0.0}/tests/test_control_points_surface.py +5 -5
- {fireweave-2.3.0 → fireweave-3.0.0}/tests/test_errors.py +7 -7
- {fireweave-2.3.0 → fireweave-3.0.0}/tests/test_init_fireweave.py +4 -4
- fireweave-3.0.0/tests/test_input_guards.py +153 -0
- {fireweave-2.3.0 → fireweave-3.0.0}/tests/test_lifecycle.py +1 -1
- {fireweave-2.3.0 → fireweave-3.0.0}/tests/test_local_register_target.py +2 -2
- fireweave-3.0.0/tests/test_redaction_contract.py +57 -0
- {fireweave-2.3.0 → fireweave-3.0.0}/tests/test_remote_adapter.py +10 -10
- fireweave-3.0.0/tests/test_remote_no_redirects.py +128 -0
- {fireweave-2.3.0 → fireweave-3.0.0}/tests/test_runtime_evaluation.py +9 -9
- fireweave-3.0.0/tests/test_start_contracts.py +217 -0
- fireweave-3.0.0/tests/test_start_facade.py +504 -0
- fireweave-3.0.0/tests/test_start_guards.py +182 -0
- fireweave-3.0.0/tests/test_start_remote.py +103 -0
- fireweave-3.0.0/tests/test_start_remote_failures.py +149 -0
- fireweave-3.0.0/tests/test_start_resolve.py +270 -0
- fireweave-2.3.0/PKG-INFO +0 -139
- fireweave-2.3.0/README.md +0 -110
- fireweave-2.3.0/src/fireweave.egg-info/PKG-INFO +0 -139
- {fireweave-2.3.0 → fireweave-3.0.0}/LICENSE +0 -0
- {fireweave-2.3.0 → fireweave-3.0.0}/setup.cfg +0 -0
- {fireweave-2.3.0 → fireweave-3.0.0}/src/fireweave/_version.py +0 -0
- {fireweave-2.3.0 → fireweave-3.0.0}/src/fireweave/application/__init__.py +0 -0
- {fireweave-2.3.0 → fireweave-3.0.0}/src/fireweave/application/mode.py +0 -0
- {fireweave-2.3.0 → fireweave-3.0.0}/src/fireweave/domain/__init__.py +0 -0
- {fireweave-2.3.0 → fireweave-3.0.0}/src/fireweave/domain/context.py +0 -0
- {fireweave-2.3.0 → fireweave-3.0.0}/src/fireweave/domain/target.py +0 -0
- {fireweave-2.3.0 → fireweave-3.0.0}/src/fireweave/infrastructure/__init__.py +0 -0
- {fireweave-2.3.0 → fireweave-3.0.0}/src/fireweave/infrastructure/adapters/__init__.py +0 -0
- {fireweave-2.3.0 → fireweave-3.0.0}/src/fireweave/infrastructure/hosts.py +0 -0
- {fireweave-2.3.0 → fireweave-3.0.0}/src/fireweave/py.typed +0 -0
- {fireweave-2.3.0 → fireweave-3.0.0}/src/fireweave.egg-info/dependency_links.txt +0 -0
- {fireweave-2.3.0 → fireweave-3.0.0}/src/fireweave.egg-info/requires.txt +0 -0
- {fireweave-2.3.0 → fireweave-3.0.0}/src/fireweave.egg-info/top_level.txt +0 -0
- {fireweave-2.3.0 → fireweave-3.0.0}/tests/test_conformance.py +0 -0
- {fireweave-2.3.0 → fireweave-3.0.0}/tests/test_context.py +0 -0
- {fireweave-2.3.0 → fireweave-3.0.0}/tests/test_hosts.py +0 -0
- {fireweave-2.3.0 → fireweave-3.0.0}/tests/test_no_vendor_leak.py +0 -0
- {fireweave-2.3.0 → fireweave-3.0.0}/tests/test_register_target.py +0 -0
fireweave-3.0.0/PKG-INFO
ADDED
|
@@ -0,0 +1,234 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: fireweave
|
|
3
|
+
Version: 3.0.0
|
|
4
|
+
Summary: Fireweave polyglot SDK for Python — server-first control-point evaluation and target registration (spec v0.1.0).
|
|
5
|
+
Author: Fireweave AI, Inc.
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/FireWeave-HQ/fireweave-sdk
|
|
8
|
+
Project-URL: Documentation, https://github.com/FireWeave-HQ/fireweave-sdk/tree/master/docs
|
|
9
|
+
Project-URL: Repository, https://github.com/FireWeave-HQ/fireweave-sdk
|
|
10
|
+
Project-URL: Issues, https://github.com/FireWeave-HQ/fireweave-sdk/issues
|
|
11
|
+
Project-URL: Changelog, https://github.com/FireWeave-HQ/fireweave-sdk/blob/master/CHANGELOG.md
|
|
12
|
+
Project-URL: Source, https://github.com/FireWeave-HQ/fireweave-sdk/tree/master/sdks/python
|
|
13
|
+
Keywords: feature-flags,rollout,release,control-points
|
|
14
|
+
Classifier: Development Status :: 3 - Alpha
|
|
15
|
+
Classifier: Intended Audience :: Developers
|
|
16
|
+
Classifier: Operating System :: OS Independent
|
|
17
|
+
Classifier: Programming Language :: Python :: 3
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
22
|
+
Classifier: Typing :: Typed
|
|
23
|
+
Requires-Python: >=3.10
|
|
24
|
+
Description-Content-Type: text/markdown
|
|
25
|
+
License-File: LICENSE
|
|
26
|
+
Provides-Extra: dev
|
|
27
|
+
Requires-Dist: pytest>=8; extra == "dev"
|
|
28
|
+
Dynamic: license-file
|
|
29
|
+
|
|
30
|
+
# fireweave (Python SDK)
|
|
31
|
+
|
|
32
|
+
Fireweave release-engineering SDK for Python — **control points** and target
|
|
33
|
+
registration, the two v1 capabilities (spec/control-points.md "Scope of v1").
|
|
34
|
+
|
|
35
|
+
- **Zero runtime dependencies.**
|
|
36
|
+
- **The core SDK reads no environment variables** — every option is an explicit
|
|
37
|
+
argument to `init_fireweave` (spec/modes.md). The opt-in start profile,
|
|
38
|
+
`fireweave.start`, is the one documented exception
|
|
39
|
+
([ADR-0012](../../docs/adr/0012-start-profile.md)).
|
|
40
|
+
- **No vendor SDK, key, or hostname in your process.** Applications hold a
|
|
41
|
+
Fireweave project key and talk to fw-server; which backend fw-server
|
|
42
|
+
forwards to is fw-server's concern.
|
|
43
|
+
|
|
44
|
+
## Quick start (one line: the start profile)
|
|
45
|
+
|
|
46
|
+
Most apps need only this ([ADR-0012](../../docs/adr/0012-start-profile.md)). One small module and one call:
|
|
47
|
+
|
|
48
|
+
```python
|
|
49
|
+
# src/fireweave_setup/control_points.py: every control point the app reads, with its local value
|
|
50
|
+
from fireweave.start import define_control_points
|
|
51
|
+
|
|
52
|
+
control_points = define_control_points({
|
|
53
|
+
"new-checkout": {"local": True, "description": "One-page checkout"}, # served only in local mode
|
|
54
|
+
})
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
```python
|
|
58
|
+
# the process entrypoint, FIRST thing: main.py, wsgi.py + asgi.py, create_app(), the Celery app module
|
|
59
|
+
from fireweave.start import start
|
|
60
|
+
from fireweave_setup.control_points import control_points
|
|
61
|
+
|
|
62
|
+
start(control_points=control_points)
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
```python
|
|
66
|
+
# any call site
|
|
67
|
+
from fireweave import EvaluationContext
|
|
68
|
+
from fireweave.start import fw
|
|
69
|
+
|
|
70
|
+
# @fireweave-controlpoint new-checkout
|
|
71
|
+
if fw.control_points.get_boolean_value("new-checkout", False, EvaluationContext(user_id)):
|
|
72
|
+
...
|
|
73
|
+
fw.identify(user_id, {"plan": user.plan}) # at sign-in
|
|
74
|
+
fw.control_points.get_boolean_value("nightly-reindex", False, EvaluationContext(fw.instance_key())) # server as subject
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
Deployed environments set one variable, `FIREWEAVE_KEY` (the project key, `project-api-key_…`).
|
|
78
|
+
Local development needs nothing when `FIREWEAVE_ENV` (or `APP_ENV`) is `development`, `dev`,
|
|
79
|
+
`local` or `test`.
|
|
80
|
+
|
|
81
|
+
`fw.control_points` has exactly the core's nine methods, with the same names and arguments;
|
|
82
|
+
contexts are `EvaluationContext` as everywhere else. Reads are synchronous (one blocking HTTP call
|
|
83
|
+
each in remote mode); in an `async def` handler use
|
|
84
|
+
`await asyncio.to_thread(lambda: fw.control_points.get_boolean_value("new-checkout", False, ctx))`.
|
|
85
|
+
Never pass an unguarded `str(user.id)`: Django's `AnonymousUser.id` is `None`, and `"None"` would
|
|
86
|
+
be one targeting key shared by every anonymous visitor.
|
|
87
|
+
|
|
88
|
+
### Options and overrides
|
|
89
|
+
|
|
90
|
+
Every value resolves as: `start()` keyword option, then env var, then legacy name (warns once),
|
|
91
|
+
then default. Empty and whitespace-only values count as unset.
|
|
92
|
+
|
|
93
|
+
| Option | Env var | Default | What it does |
|
|
94
|
+
| --- | --- | --- | --- |
|
|
95
|
+
| `control_points` | — | `{}` | Local values per control point. Ignored in remote mode. |
|
|
96
|
+
| `mode` | — | inferred | `'remote'` or `'local'`. Overrides inference. `'remote'` without a key is a start error; `'local'` ignores a key, with one warning. |
|
|
97
|
+
| `environment` | `FIREWEAVE_ENV`, `APP_ENV` | — | Environment name used for inference when there is no key and no `mode`. Pass your own, e.g. `environment=settings.DEPLOY_STAGE`. `ENVIRONMENT`, `ENV`, `NODE_ENV` and the retired `FW_ENV` are not read. |
|
|
98
|
+
| `url` | `FIREWEAVE_URL` (legacy `FW_API_URL`, `FW_ATTEST_URL`) | from the installed version | A pre-release or dev release calls `staging-app-server.fireweave.ai`; any other calls `app-server.fireweave.ai`. Staging builds are `X.Y.ZrcN` on PyPI: install one with `pip install fireweave==X.Y.ZrcN` (no extra index; pip skips pre-releases unless pinned). Set it for a self-hosted or local fw-server: https is required except on localhost, and the host allowlist follows it. |
|
|
99
|
+
| `key` | `FIREWEAVE_KEY` (legacy `FW_PROJECT_API_KEY`) | — | Project key. Pass it to read from your own secret store. Browser keys (`fw_public_…`), analytics vendor keys and org or CLI tokens are rejected at start. |
|
|
100
|
+
| `instance_id` | `FIREWEAVE_INSTANCE_ID` | `inst_` + hash of the host name | Value of `fw.instance_key()`. Nothing is written to disk. |
|
|
101
|
+
| `env` | — | `os.environ` | Read values from this mapping instead of the environment (tests). |
|
|
102
|
+
| `log` | — | the `fireweave.start` logger | A callable taking one line, or a `logging.Logger`. Where `[fireweave]` lines go. |
|
|
103
|
+
|
|
104
|
+
`fireweave.start.SDK_VERSION` and `SDK_CHANNEL` show which version and channel are installed.
|
|
105
|
+
|
|
106
|
+
**Mode rule.** `mode` wins. Otherwise: a key means remote. No key and a development environment
|
|
107
|
+
name means local. Anything else (including no environment name at all) raises
|
|
108
|
+
`ConfigurationError` at `start()`, naming `FIREWEAVE_KEY` and where the environment name was
|
|
109
|
+
looked for, so a deploy that forgot its key fails instead of silently serving defaults.
|
|
110
|
+
|
|
111
|
+
**One per process.** `start()` is idempotent: a second call with the same configuration does
|
|
112
|
+
nothing, a different one raises `ConfigurationError`. It does no network I/O and starts no
|
|
113
|
+
thread, so it is ready when it returns. Call it in every process entrypoint; a forked worker
|
|
114
|
+
(gunicorn `--preload`, Celery prefork) rebuilds its client on its own. A read before any `start()`
|
|
115
|
+
starts FireWeave immediately from the environment alone (one warning); the first explicit
|
|
116
|
+
`start()` afterwards replaces that once, with a warning, and shuts the provisional client down
|
|
117
|
+
(reads in flight move to the new one). Processes that never run your entrypoint
|
|
118
|
+
(`manage.py`, spawned children) get the environment-only start, so prefer `FIREWEAVE_*`
|
|
119
|
+
variables to options for anything every process needs.
|
|
120
|
+
|
|
121
|
+
**Reads never raise.** If start fails, reads return your default (`evaluate` and the `*_details`
|
|
122
|
+
forms return an `ERROR` decision with the `Configuration` error) and `fw.identify()` returns
|
|
123
|
+
`ok=False`. In local mode, reading a key that is not in your control points returns the default and
|
|
124
|
+
warns once, naming the file that declared them.
|
|
125
|
+
|
|
126
|
+
**Debugging.** `fw.status()` reports what start decided: `state`, `started_by`, `mode` and
|
|
127
|
+
`mode_source`, `channel`, `sdk_version`, `host`, `endpoint_source`, `key_source`, `environment`,
|
|
128
|
+
`flag_count`, `error` and `last_error_kind`. It never includes the key. When fw-server refuses the
|
|
129
|
+
key (401/403), rate-limits it (429) or cannot be reached (network error, timeout, 5xx or a
|
|
130
|
+
redirect, which is never followed), reads serve their defaults, so a revoked key would otherwise
|
|
131
|
+
look like a rollout at 0%. Each of those kinds logs **one** line per process through your `log`
|
|
132
|
+
sink (default: the `fireweave.start` logger), naming the key's source (`FIREWEAVE_KEY`,
|
|
133
|
+
`start(key=...)`) or the endpoint's, and the host, never the key; `last_error_kind` keeps the
|
|
134
|
+
latest kind (`Authentication`, `Authorization`, `RateLimited`, `Network`, `Timeout`,
|
|
135
|
+
`BackendUnavailable`). `fw.client()` is the core `FireweaveClient` for anything the facade does not
|
|
136
|
+
cover (do not cache it: the first explicit `start()` after a read-triggered one shuts the
|
|
137
|
+
provisional client down); `fw.shutdown()` flushes and closes, and a later `start()` begins fresh.
|
|
138
|
+
Tests call `fireweave.start.reset_for_tests()` between cases.
|
|
139
|
+
|
|
140
|
+
## Quick start (production path)
|
|
141
|
+
|
|
142
|
+
```python
|
|
143
|
+
from fireweave import RegisterTargetOptions, init_fireweave, EvaluationContext
|
|
144
|
+
|
|
145
|
+
# mode is required and never inferred (spec/modes.md); api_key/api_url are
|
|
146
|
+
# explicit options — the SDK reads no environment variables.
|
|
147
|
+
client = init_fireweave(
|
|
148
|
+
mode="remote",
|
|
149
|
+
api_key="project-api-key_...",
|
|
150
|
+
api_url="https://app-server.fireweave.ai",
|
|
151
|
+
)
|
|
152
|
+
|
|
153
|
+
# Once per login: the durable facts your targeting rules match on.
|
|
154
|
+
client.register_target(
|
|
155
|
+
"user_42", RegisterTargetOptions(kind="user", properties={"plan": "pro"})
|
|
156
|
+
)
|
|
157
|
+
|
|
158
|
+
# Per request.
|
|
159
|
+
enabled = client.control_points.get_boolean_value(
|
|
160
|
+
"new-checkout", False, EvaluationContext("user_42")
|
|
161
|
+
)
|
|
162
|
+
|
|
163
|
+
client.shutdown()
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
## Quick start (offline, in-memory)
|
|
167
|
+
|
|
168
|
+
```python
|
|
169
|
+
from fireweave import FireweaveClient, FireweaveRuntime, InMemoryAdapter
|
|
170
|
+
|
|
171
|
+
adapter = InMemoryAdapter({
|
|
172
|
+
"new-checkout": {"enabled": True, "variant": "on", "value": True},
|
|
173
|
+
})
|
|
174
|
+
runtime = FireweaveRuntime(adapter)
|
|
175
|
+
runtime.initialize()
|
|
176
|
+
client = FireweaveClient(runtime)
|
|
177
|
+
|
|
178
|
+
assert client.control_points.get_boolean_value("new-checkout", False) is True
|
|
179
|
+
client.shutdown()
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
## Quick start (local dev — no network, no credentials)
|
|
183
|
+
|
|
184
|
+
```python
|
|
185
|
+
from fireweave import init_fireweave
|
|
186
|
+
|
|
187
|
+
client = init_fireweave(mode="local", local={"control_points": {"new-checkout": True}})
|
|
188
|
+
client.control_points.get_boolean_value("new-checkout", False) # -> True
|
|
189
|
+
client.register_target("user_42") # recorded in-process + traced; nothing sent
|
|
190
|
+
client.shutdown()
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
## The nine methods
|
|
194
|
+
|
|
195
|
+
`get_boolean_value` / `get_string_value` / `get_number_value` /
|
|
196
|
+
`get_object_value`, their `*_details` counterparts (return the whole
|
|
197
|
+
`Decision` — `reason`, `error_kind`, `control_point_metadata`, ... — instead of
|
|
198
|
+
just the value), and the general-form `evaluate`. All nine live under
|
|
199
|
+
`client.control_points`; the `client.flags` alias was removed in 3.0.0
|
|
200
|
+
(ADR-0013).
|
|
201
|
+
|
|
202
|
+
`get_integer_value` is a deprecated alias of `get_number_value` — spec fixes
|
|
203
|
+
the method as **number**, not integer (`Decision.value` is `jsonValue`). It
|
|
204
|
+
still works and delegates straight through; it logs one `DeprecationWarning`
|
|
205
|
+
per process the first time it's called.
|
|
206
|
+
|
|
207
|
+
## Module layout
|
|
208
|
+
|
|
209
|
+
| Module | Responsibility |
|
|
210
|
+
| --- | --- |
|
|
211
|
+
| `domain/` | Pure types + validation: `errors.py`, `types.py`, `context.py`, `decision.py`, `target.py`, `validation.py`. No I/O, no imports from `application/`/`infrastructure/`. |
|
|
212
|
+
| `application/runtime.py` | Lifecycle state machine, context layering, the evaluation pipeline. Evaluation never raises. |
|
|
213
|
+
| `application/client.py` | `FireweaveClient` — `control_points`, `register_target`, `invoke_capability` (degrades; v1 has no supported capabilities). |
|
|
214
|
+
| `application/mode.py` | `init_fireweave` — the single entry point and sanctioned composition root (the only file allowed to import concrete adapters). |
|
|
215
|
+
| `application/ports.py` | The `BackendAdapter` boundary. |
|
|
216
|
+
| `infrastructure/adapters/remote.py` | `FireweaveRemoteAdapter` — the production backend (`POST /v1/control-points/evaluate`, `POST /v1/targets/register`). |
|
|
217
|
+
| `infrastructure/adapters/local.py` | `FireweaveLocalAdapter` — the dev substrate: seeded boolean overrides, no network. `register_target` records in-process and traces the call. |
|
|
218
|
+
| `infrastructure/adapters/memory.py` | Deterministic fixture-driven adapter for tests. |
|
|
219
|
+
| `infrastructure/hosts.py` | SSRF allowlist (on by default; https required off-loopback). |
|
|
220
|
+
| `start/` | The opt-in start profile (`from fireweave.start import start, fw, define_control_points`). Built on the public `fireweave` API only; `start/_env.py` is the one file that reads the environment or the host name. The core never imports it. |
|
|
221
|
+
|
|
222
|
+
## Development
|
|
223
|
+
|
|
224
|
+
```bash
|
|
225
|
+
python -m venv .venv && .venv/bin/pip install -e '.[dev]'
|
|
226
|
+
# or: uv sync
|
|
227
|
+
.venv/bin/pytest # unit tests
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
`conformance/surface/control-points.surface.json` is the parity gate this package satisfies.
|
|
231
|
+
|
|
232
|
+
## License
|
|
233
|
+
|
|
234
|
+
[MIT](./LICENSE).
|
|
@@ -0,0 +1,205 @@
|
|
|
1
|
+
# fireweave (Python SDK)
|
|
2
|
+
|
|
3
|
+
Fireweave release-engineering SDK for Python — **control points** and target
|
|
4
|
+
registration, the two v1 capabilities (spec/control-points.md "Scope of v1").
|
|
5
|
+
|
|
6
|
+
- **Zero runtime dependencies.**
|
|
7
|
+
- **The core SDK reads no environment variables** — every option is an explicit
|
|
8
|
+
argument to `init_fireweave` (spec/modes.md). The opt-in start profile,
|
|
9
|
+
`fireweave.start`, is the one documented exception
|
|
10
|
+
([ADR-0012](../../docs/adr/0012-start-profile.md)).
|
|
11
|
+
- **No vendor SDK, key, or hostname in your process.** Applications hold a
|
|
12
|
+
Fireweave project key and talk to fw-server; which backend fw-server
|
|
13
|
+
forwards to is fw-server's concern.
|
|
14
|
+
|
|
15
|
+
## Quick start (one line: the start profile)
|
|
16
|
+
|
|
17
|
+
Most apps need only this ([ADR-0012](../../docs/adr/0012-start-profile.md)). One small module and one call:
|
|
18
|
+
|
|
19
|
+
```python
|
|
20
|
+
# src/fireweave_setup/control_points.py: every control point the app reads, with its local value
|
|
21
|
+
from fireweave.start import define_control_points
|
|
22
|
+
|
|
23
|
+
control_points = define_control_points({
|
|
24
|
+
"new-checkout": {"local": True, "description": "One-page checkout"}, # served only in local mode
|
|
25
|
+
})
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
```python
|
|
29
|
+
# the process entrypoint, FIRST thing: main.py, wsgi.py + asgi.py, create_app(), the Celery app module
|
|
30
|
+
from fireweave.start import start
|
|
31
|
+
from fireweave_setup.control_points import control_points
|
|
32
|
+
|
|
33
|
+
start(control_points=control_points)
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
```python
|
|
37
|
+
# any call site
|
|
38
|
+
from fireweave import EvaluationContext
|
|
39
|
+
from fireweave.start import fw
|
|
40
|
+
|
|
41
|
+
# @fireweave-controlpoint new-checkout
|
|
42
|
+
if fw.control_points.get_boolean_value("new-checkout", False, EvaluationContext(user_id)):
|
|
43
|
+
...
|
|
44
|
+
fw.identify(user_id, {"plan": user.plan}) # at sign-in
|
|
45
|
+
fw.control_points.get_boolean_value("nightly-reindex", False, EvaluationContext(fw.instance_key())) # server as subject
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
Deployed environments set one variable, `FIREWEAVE_KEY` (the project key, `project-api-key_…`).
|
|
49
|
+
Local development needs nothing when `FIREWEAVE_ENV` (or `APP_ENV`) is `development`, `dev`,
|
|
50
|
+
`local` or `test`.
|
|
51
|
+
|
|
52
|
+
`fw.control_points` has exactly the core's nine methods, with the same names and arguments;
|
|
53
|
+
contexts are `EvaluationContext` as everywhere else. Reads are synchronous (one blocking HTTP call
|
|
54
|
+
each in remote mode); in an `async def` handler use
|
|
55
|
+
`await asyncio.to_thread(lambda: fw.control_points.get_boolean_value("new-checkout", False, ctx))`.
|
|
56
|
+
Never pass an unguarded `str(user.id)`: Django's `AnonymousUser.id` is `None`, and `"None"` would
|
|
57
|
+
be one targeting key shared by every anonymous visitor.
|
|
58
|
+
|
|
59
|
+
### Options and overrides
|
|
60
|
+
|
|
61
|
+
Every value resolves as: `start()` keyword option, then env var, then legacy name (warns once),
|
|
62
|
+
then default. Empty and whitespace-only values count as unset.
|
|
63
|
+
|
|
64
|
+
| Option | Env var | Default | What it does |
|
|
65
|
+
| --- | --- | --- | --- |
|
|
66
|
+
| `control_points` | — | `{}` | Local values per control point. Ignored in remote mode. |
|
|
67
|
+
| `mode` | — | inferred | `'remote'` or `'local'`. Overrides inference. `'remote'` without a key is a start error; `'local'` ignores a key, with one warning. |
|
|
68
|
+
| `environment` | `FIREWEAVE_ENV`, `APP_ENV` | — | Environment name used for inference when there is no key and no `mode`. Pass your own, e.g. `environment=settings.DEPLOY_STAGE`. `ENVIRONMENT`, `ENV`, `NODE_ENV` and the retired `FW_ENV` are not read. |
|
|
69
|
+
| `url` | `FIREWEAVE_URL` (legacy `FW_API_URL`, `FW_ATTEST_URL`) | from the installed version | A pre-release or dev release calls `staging-app-server.fireweave.ai`; any other calls `app-server.fireweave.ai`. Staging builds are `X.Y.ZrcN` on PyPI: install one with `pip install fireweave==X.Y.ZrcN` (no extra index; pip skips pre-releases unless pinned). Set it for a self-hosted or local fw-server: https is required except on localhost, and the host allowlist follows it. |
|
|
70
|
+
| `key` | `FIREWEAVE_KEY` (legacy `FW_PROJECT_API_KEY`) | — | Project key. Pass it to read from your own secret store. Browser keys (`fw_public_…`), analytics vendor keys and org or CLI tokens are rejected at start. |
|
|
71
|
+
| `instance_id` | `FIREWEAVE_INSTANCE_ID` | `inst_` + hash of the host name | Value of `fw.instance_key()`. Nothing is written to disk. |
|
|
72
|
+
| `env` | — | `os.environ` | Read values from this mapping instead of the environment (tests). |
|
|
73
|
+
| `log` | — | the `fireweave.start` logger | A callable taking one line, or a `logging.Logger`. Where `[fireweave]` lines go. |
|
|
74
|
+
|
|
75
|
+
`fireweave.start.SDK_VERSION` and `SDK_CHANNEL` show which version and channel are installed.
|
|
76
|
+
|
|
77
|
+
**Mode rule.** `mode` wins. Otherwise: a key means remote. No key and a development environment
|
|
78
|
+
name means local. Anything else (including no environment name at all) raises
|
|
79
|
+
`ConfigurationError` at `start()`, naming `FIREWEAVE_KEY` and where the environment name was
|
|
80
|
+
looked for, so a deploy that forgot its key fails instead of silently serving defaults.
|
|
81
|
+
|
|
82
|
+
**One per process.** `start()` is idempotent: a second call with the same configuration does
|
|
83
|
+
nothing, a different one raises `ConfigurationError`. It does no network I/O and starts no
|
|
84
|
+
thread, so it is ready when it returns. Call it in every process entrypoint; a forked worker
|
|
85
|
+
(gunicorn `--preload`, Celery prefork) rebuilds its client on its own. A read before any `start()`
|
|
86
|
+
starts FireWeave immediately from the environment alone (one warning); the first explicit
|
|
87
|
+
`start()` afterwards replaces that once, with a warning, and shuts the provisional client down
|
|
88
|
+
(reads in flight move to the new one). Processes that never run your entrypoint
|
|
89
|
+
(`manage.py`, spawned children) get the environment-only start, so prefer `FIREWEAVE_*`
|
|
90
|
+
variables to options for anything every process needs.
|
|
91
|
+
|
|
92
|
+
**Reads never raise.** If start fails, reads return your default (`evaluate` and the `*_details`
|
|
93
|
+
forms return an `ERROR` decision with the `Configuration` error) and `fw.identify()` returns
|
|
94
|
+
`ok=False`. In local mode, reading a key that is not in your control points returns the default and
|
|
95
|
+
warns once, naming the file that declared them.
|
|
96
|
+
|
|
97
|
+
**Debugging.** `fw.status()` reports what start decided: `state`, `started_by`, `mode` and
|
|
98
|
+
`mode_source`, `channel`, `sdk_version`, `host`, `endpoint_source`, `key_source`, `environment`,
|
|
99
|
+
`flag_count`, `error` and `last_error_kind`. It never includes the key. When fw-server refuses the
|
|
100
|
+
key (401/403), rate-limits it (429) or cannot be reached (network error, timeout, 5xx or a
|
|
101
|
+
redirect, which is never followed), reads serve their defaults, so a revoked key would otherwise
|
|
102
|
+
look like a rollout at 0%. Each of those kinds logs **one** line per process through your `log`
|
|
103
|
+
sink (default: the `fireweave.start` logger), naming the key's source (`FIREWEAVE_KEY`,
|
|
104
|
+
`start(key=...)`) or the endpoint's, and the host, never the key; `last_error_kind` keeps the
|
|
105
|
+
latest kind (`Authentication`, `Authorization`, `RateLimited`, `Network`, `Timeout`,
|
|
106
|
+
`BackendUnavailable`). `fw.client()` is the core `FireweaveClient` for anything the facade does not
|
|
107
|
+
cover (do not cache it: the first explicit `start()` after a read-triggered one shuts the
|
|
108
|
+
provisional client down); `fw.shutdown()` flushes and closes, and a later `start()` begins fresh.
|
|
109
|
+
Tests call `fireweave.start.reset_for_tests()` between cases.
|
|
110
|
+
|
|
111
|
+
## Quick start (production path)
|
|
112
|
+
|
|
113
|
+
```python
|
|
114
|
+
from fireweave import RegisterTargetOptions, init_fireweave, EvaluationContext
|
|
115
|
+
|
|
116
|
+
# mode is required and never inferred (spec/modes.md); api_key/api_url are
|
|
117
|
+
# explicit options — the SDK reads no environment variables.
|
|
118
|
+
client = init_fireweave(
|
|
119
|
+
mode="remote",
|
|
120
|
+
api_key="project-api-key_...",
|
|
121
|
+
api_url="https://app-server.fireweave.ai",
|
|
122
|
+
)
|
|
123
|
+
|
|
124
|
+
# Once per login: the durable facts your targeting rules match on.
|
|
125
|
+
client.register_target(
|
|
126
|
+
"user_42", RegisterTargetOptions(kind="user", properties={"plan": "pro"})
|
|
127
|
+
)
|
|
128
|
+
|
|
129
|
+
# Per request.
|
|
130
|
+
enabled = client.control_points.get_boolean_value(
|
|
131
|
+
"new-checkout", False, EvaluationContext("user_42")
|
|
132
|
+
)
|
|
133
|
+
|
|
134
|
+
client.shutdown()
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
## Quick start (offline, in-memory)
|
|
138
|
+
|
|
139
|
+
```python
|
|
140
|
+
from fireweave import FireweaveClient, FireweaveRuntime, InMemoryAdapter
|
|
141
|
+
|
|
142
|
+
adapter = InMemoryAdapter({
|
|
143
|
+
"new-checkout": {"enabled": True, "variant": "on", "value": True},
|
|
144
|
+
})
|
|
145
|
+
runtime = FireweaveRuntime(adapter)
|
|
146
|
+
runtime.initialize()
|
|
147
|
+
client = FireweaveClient(runtime)
|
|
148
|
+
|
|
149
|
+
assert client.control_points.get_boolean_value("new-checkout", False) is True
|
|
150
|
+
client.shutdown()
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
## Quick start (local dev — no network, no credentials)
|
|
154
|
+
|
|
155
|
+
```python
|
|
156
|
+
from fireweave import init_fireweave
|
|
157
|
+
|
|
158
|
+
client = init_fireweave(mode="local", local={"control_points": {"new-checkout": True}})
|
|
159
|
+
client.control_points.get_boolean_value("new-checkout", False) # -> True
|
|
160
|
+
client.register_target("user_42") # recorded in-process + traced; nothing sent
|
|
161
|
+
client.shutdown()
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
## The nine methods
|
|
165
|
+
|
|
166
|
+
`get_boolean_value` / `get_string_value` / `get_number_value` /
|
|
167
|
+
`get_object_value`, their `*_details` counterparts (return the whole
|
|
168
|
+
`Decision` — `reason`, `error_kind`, `control_point_metadata`, ... — instead of
|
|
169
|
+
just the value), and the general-form `evaluate`. All nine live under
|
|
170
|
+
`client.control_points`; the `client.flags` alias was removed in 3.0.0
|
|
171
|
+
(ADR-0013).
|
|
172
|
+
|
|
173
|
+
`get_integer_value` is a deprecated alias of `get_number_value` — spec fixes
|
|
174
|
+
the method as **number**, not integer (`Decision.value` is `jsonValue`). It
|
|
175
|
+
still works and delegates straight through; it logs one `DeprecationWarning`
|
|
176
|
+
per process the first time it's called.
|
|
177
|
+
|
|
178
|
+
## Module layout
|
|
179
|
+
|
|
180
|
+
| Module | Responsibility |
|
|
181
|
+
| --- | --- |
|
|
182
|
+
| `domain/` | Pure types + validation: `errors.py`, `types.py`, `context.py`, `decision.py`, `target.py`, `validation.py`. No I/O, no imports from `application/`/`infrastructure/`. |
|
|
183
|
+
| `application/runtime.py` | Lifecycle state machine, context layering, the evaluation pipeline. Evaluation never raises. |
|
|
184
|
+
| `application/client.py` | `FireweaveClient` — `control_points`, `register_target`, `invoke_capability` (degrades; v1 has no supported capabilities). |
|
|
185
|
+
| `application/mode.py` | `init_fireweave` — the single entry point and sanctioned composition root (the only file allowed to import concrete adapters). |
|
|
186
|
+
| `application/ports.py` | The `BackendAdapter` boundary. |
|
|
187
|
+
| `infrastructure/adapters/remote.py` | `FireweaveRemoteAdapter` — the production backend (`POST /v1/control-points/evaluate`, `POST /v1/targets/register`). |
|
|
188
|
+
| `infrastructure/adapters/local.py` | `FireweaveLocalAdapter` — the dev substrate: seeded boolean overrides, no network. `register_target` records in-process and traces the call. |
|
|
189
|
+
| `infrastructure/adapters/memory.py` | Deterministic fixture-driven adapter for tests. |
|
|
190
|
+
| `infrastructure/hosts.py` | SSRF allowlist (on by default; https required off-loopback). |
|
|
191
|
+
| `start/` | The opt-in start profile (`from fireweave.start import start, fw, define_control_points`). Built on the public `fireweave` API only; `start/_env.py` is the one file that reads the environment or the host name. The core never imports it. |
|
|
192
|
+
|
|
193
|
+
## Development
|
|
194
|
+
|
|
195
|
+
```bash
|
|
196
|
+
python -m venv .venv && .venv/bin/pip install -e '.[dev]'
|
|
197
|
+
# or: uv sync
|
|
198
|
+
.venv/bin/pytest # unit tests
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
`conformance/surface/control-points.surface.json` is the parity gate this package satisfies.
|
|
202
|
+
|
|
203
|
+
## License
|
|
204
|
+
|
|
205
|
+
[MIT](./LICENSE).
|
|
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
|
|
|
4
4
|
|
|
5
5
|
[project]
|
|
6
6
|
name = "fireweave"
|
|
7
|
-
version = "
|
|
7
|
+
version = "3.0.0"
|
|
8
8
|
description = "Fireweave polyglot SDK for Python — server-first control-point evaluation and target registration (spec v0.1.0)."
|
|
9
9
|
readme = "README.md"
|
|
10
10
|
requires-python = ">=3.10"
|
|
@@ -44,7 +44,7 @@ from .domain.errors import (
|
|
|
44
44
|
ConfigurationError,
|
|
45
45
|
ErrorKind,
|
|
46
46
|
FireweaveError,
|
|
47
|
-
|
|
47
|
+
ControlPointNotFoundError,
|
|
48
48
|
InternalError,
|
|
49
49
|
InvalidContextError,
|
|
50
50
|
MalformedResponseError,
|
|
@@ -133,7 +133,7 @@ __all__ = [
|
|
|
133
133
|
"ErrorKind",
|
|
134
134
|
"FireweaveError",
|
|
135
135
|
"NotReadyError",
|
|
136
|
-
"
|
|
136
|
+
"ControlPointNotFoundError",
|
|
137
137
|
"TypeMismatchError",
|
|
138
138
|
"InvalidContextError",
|
|
139
139
|
"TargetingKeyMissingError",
|
|
@@ -42,8 +42,8 @@ def _failure(err: FireweaveError, degraded: bool = False) -> ExtensionResult:
|
|
|
42
42
|
|
|
43
43
|
class _ControlPointsNamespace:
|
|
44
44
|
"""Typed evaluation helpers — the nine methods (spec/control-points.md
|
|
45
|
-
"The nine methods")
|
|
46
|
-
|
|
45
|
+
"The nine methods"), as ``client.control_points``. The ``client.flags``
|
|
46
|
+
alias was removed in 3.0.0 (ADR-0013).
|
|
47
47
|
"""
|
|
48
48
|
|
|
49
49
|
def __init__(self, runtime: FireweaveRuntime) -> None:
|
|
@@ -51,7 +51,7 @@ class _ControlPointsNamespace:
|
|
|
51
51
|
|
|
52
52
|
def evaluate(
|
|
53
53
|
self,
|
|
54
|
-
|
|
54
|
+
control_point_key: str,
|
|
55
55
|
flag_type: FlagType,
|
|
56
56
|
default: Any,
|
|
57
57
|
context: Optional[EvaluationContext] = None,
|
|
@@ -65,50 +65,50 @@ class _ControlPointsNamespace:
|
|
|
65
65
|
``evaluate(key, type, default, context?, options?)`` across every
|
|
66
66
|
language). ``options.include_payload`` (task-10b item 5) is the one
|
|
67
67
|
real field: it attaches the resolved flag's payload, when any, to
|
|
68
|
-
``
|
|
68
|
+
``control_point_metadata['fireweave.payload']`` — a deterministic sorted-key
|
|
69
69
|
JSON string, matching node's ``EvaluateOptions.includePayload``. The
|
|
70
70
|
python control-point surface is synchronous (server SDK — blocking
|
|
71
71
|
I/O like node's ``await`` is fine), so there is no in-flight-call
|
|
72
72
|
`signal` to carry, and v1 reads are side-effect-free by design (no
|
|
73
73
|
per-call exposure opt-in to carry either) — those two remain N/A.
|
|
74
74
|
"""
|
|
75
|
-
return self._runtime.evaluate(
|
|
75
|
+
return self._runtime.evaluate(control_point_key, flag_type, default, context, options)
|
|
76
76
|
|
|
77
|
-
def get_boolean_value(self,
|
|
78
|
-
return self.evaluate(
|
|
77
|
+
def get_boolean_value(self, control_point_key: str, default: bool, context: Optional[EvaluationContext] = None) -> bool:
|
|
78
|
+
return self.evaluate(control_point_key, FlagType.BOOLEAN, default, context).value
|
|
79
79
|
|
|
80
|
-
def get_string_value(self,
|
|
81
|
-
return self.evaluate(
|
|
80
|
+
def get_string_value(self, control_point_key: str, default: str, context: Optional[EvaluationContext] = None) -> str:
|
|
81
|
+
return self.evaluate(control_point_key, FlagType.STRING, default, context).value
|
|
82
82
|
|
|
83
|
-
def get_number_value(self,
|
|
84
|
-
return self.evaluate(
|
|
83
|
+
def get_number_value(self, control_point_key: str, default: Any, context: Optional[EvaluationContext] = None) -> Any:
|
|
84
|
+
return self.evaluate(control_point_key, FlagType.NUMBER, default, context).value
|
|
85
85
|
|
|
86
86
|
def get_object_value(
|
|
87
|
-
self,
|
|
87
|
+
self, control_point_key: str, default: JsonValue, context: Optional[EvaluationContext] = None
|
|
88
88
|
) -> JsonValue:
|
|
89
|
-
return self.evaluate(
|
|
89
|
+
return self.evaluate(control_point_key, FlagType.OBJECT, default, context).value
|
|
90
90
|
|
|
91
91
|
def get_boolean_details(
|
|
92
|
-
self,
|
|
92
|
+
self, control_point_key: str, default: bool, context: Optional[EvaluationContext] = None
|
|
93
93
|
) -> Decision:
|
|
94
|
-
return self.evaluate(
|
|
94
|
+
return self.evaluate(control_point_key, FlagType.BOOLEAN, default, context)
|
|
95
95
|
|
|
96
96
|
def get_string_details(
|
|
97
|
-
self,
|
|
97
|
+
self, control_point_key: str, default: str, context: Optional[EvaluationContext] = None
|
|
98
98
|
) -> Decision:
|
|
99
|
-
return self.evaluate(
|
|
99
|
+
return self.evaluate(control_point_key, FlagType.STRING, default, context)
|
|
100
100
|
|
|
101
101
|
def get_number_details(
|
|
102
|
-
self,
|
|
102
|
+
self, control_point_key: str, default: Any, context: Optional[EvaluationContext] = None
|
|
103
103
|
) -> Decision:
|
|
104
|
-
return self.evaluate(
|
|
104
|
+
return self.evaluate(control_point_key, FlagType.NUMBER, default, context)
|
|
105
105
|
|
|
106
106
|
def get_object_details(
|
|
107
|
-
self,
|
|
107
|
+
self, control_point_key: str, default: JsonValue, context: Optional[EvaluationContext] = None
|
|
108
108
|
) -> Decision:
|
|
109
|
-
return self.evaluate(
|
|
109
|
+
return self.evaluate(control_point_key, FlagType.OBJECT, default, context)
|
|
110
110
|
|
|
111
|
-
def get_integer_value(self,
|
|
111
|
+
def get_integer_value(self, control_point_key: str, default: int, context: Optional[EvaluationContext] = None) -> int:
|
|
112
112
|
"""Deprecated alias of :meth:`get_number_value`.
|
|
113
113
|
|
|
114
114
|
spec/control-points.md fixed the method as **number**, not integer
|
|
@@ -121,7 +121,7 @@ class _ControlPointsNamespace:
|
|
|
121
121
|
warning.
|
|
122
122
|
"""
|
|
123
123
|
_note_deprecated_get_integer_value()
|
|
124
|
-
return self.get_number_value(
|
|
124
|
+
return self.get_number_value(control_point_key, default, context)
|
|
125
125
|
|
|
126
126
|
|
|
127
127
|
# Names invoke_capability will dispatch instead of degrading with
|
|
@@ -136,23 +136,9 @@ SUPPORTED_CAPABILITIES: FrozenSet[str] = frozenset()
|
|
|
136
136
|
# wholesale and then ignored. Unconditional (no env gate): the SDK reads no
|
|
137
137
|
# environment variables (spec/modes.md "The SDK reads no environment
|
|
138
138
|
# variables", unscoped).
|
|
139
|
-
_flags_alias_warned = False
|
|
140
139
|
_get_integer_value_warned = False
|
|
141
140
|
|
|
142
141
|
|
|
143
|
-
def _note_deprecated_flags_alias() -> None:
|
|
144
|
-
global _flags_alias_warned
|
|
145
|
-
if _flags_alias_warned:
|
|
146
|
-
return
|
|
147
|
-
_flags_alias_warned = True
|
|
148
|
-
warnings.warn(
|
|
149
|
-
"client.flags has been renamed to client.control_points. "
|
|
150
|
-
"The old name remains fully supported — no migration is required.",
|
|
151
|
-
DeprecationWarning,
|
|
152
|
-
stacklevel=3,
|
|
153
|
-
)
|
|
154
|
-
|
|
155
|
-
|
|
156
142
|
def _note_deprecated_get_integer_value() -> None:
|
|
157
143
|
global _get_integer_value_warned
|
|
158
144
|
if _get_integer_value_warned:
|
|
@@ -179,17 +165,6 @@ class FireweaveClient:
|
|
|
179
165
|
self._runtime = runtime
|
|
180
166
|
self.control_points = _ControlPointsNamespace(runtime)
|
|
181
167
|
|
|
182
|
-
@property
|
|
183
|
-
def flags(self) -> _ControlPointsNamespace:
|
|
184
|
-
"""Control-point evaluation under its former name.
|
|
185
|
-
|
|
186
|
-
Identical to :attr:`control_points` — ``client.flags is
|
|
187
|
-
client.control_points``. Not scheduled for removal. Logs one notice
|
|
188
|
-
per process the first time this getter is used.
|
|
189
|
-
"""
|
|
190
|
-
_note_deprecated_flags_alias()
|
|
191
|
-
return self.control_points
|
|
192
|
-
|
|
193
168
|
@property
|
|
194
169
|
def runtime(self) -> FireweaveRuntime:
|
|
195
170
|
return self._runtime
|
|
@@ -34,7 +34,7 @@ class EvaluateOptions:
|
|
|
34
34
|
``include_payload`` (task-10b item 5, contracts/evaluation/eval-payload-
|
|
35
35
|
attached.json): when True and the resolved flag carries a payload
|
|
36
36
|
(:attr:`FlagResolution.payload`), it is attached to
|
|
37
|
-
``
|
|
37
|
+
``control_point_metadata['fireweave.payload']`` as a deterministic (sorted-key)
|
|
38
38
|
JSON string — matching node's ``EvaluateOptions.includePayload``. Before
|
|
39
39
|
task-10b this was entirely absent (``evaluate()`` had no ``options``
|
|
40
40
|
concept whatsoever; the parameter existed but was always discarded).
|
|
@@ -80,8 +80,8 @@ class FlagResolution:
|
|
|
80
80
|
:meth:`FireweaveRuntime.evaluate` reads to produce reason ``DEFAULT``
|
|
81
81
|
(spec/modes.md "Behaviour per mode": local mode's unknown-key row).
|
|
82
82
|
Contrast a genuinely-unknown key at a real backend (remote's "key unknown
|
|
83
|
-
to the backend" row), which resolves to reason ``ERROR``/``
|
|
84
|
-
by *raising* :class:`~fireweave.domain.errors.
|
|
83
|
+
to the backend" row), which resolves to reason ``ERROR``/``ControlPointNotFound``
|
|
84
|
+
by *raising* :class:`~fireweave.domain.errors.ControlPointNotFoundError` instead
|
|
85
85
|
of returning ``matched=False`` — see `FireweaveRemoteAdapter.resolve` and
|
|
86
86
|
`FireweaveLocalAdapter.resolve`.
|
|
87
87
|
|
|
@@ -94,7 +94,7 @@ class FlagResolution:
|
|
|
94
94
|
enabled: bool = True
|
|
95
95
|
matched: bool = True
|
|
96
96
|
version: Optional[int] = None
|
|
97
|
-
|
|
97
|
+
vendor_control_point_id: Optional[int] = None
|
|
98
98
|
reason_code: Optional[str] = None
|
|
99
99
|
condition_index: Optional[int] = None
|
|
100
100
|
payload: Optional[JsonValue] = None
|
|
@@ -108,7 +108,7 @@ class BackendAdapter(Protocol):
|
|
|
108
108
|
"""Protocol every Fireweave backend adapter implements.
|
|
109
109
|
|
|
110
110
|
``resolve`` raises a :class:`fireweave.domain.errors.FireweaveError`
|
|
111
|
-
subtype for a genuine backend failure (
|
|
111
|
+
subtype for a genuine backend failure (ControlPointNotFound, Network, Timeout,
|
|
112
112
|
...); the runtime converts those into default-valued decisions —
|
|
113
113
|
evaluation APIs never propagate them to the caller.
|
|
114
114
|
|
|
@@ -122,7 +122,7 @@ class BackendAdapter(Protocol):
|
|
|
122
122
|
def initialize(self) -> None:
|
|
123
123
|
"""Bring the backend up; raise FireweaveError on fatal config."""
|
|
124
124
|
|
|
125
|
-
def resolve(self,
|
|
125
|
+
def resolve(self, control_point_key: str, context: EvaluationContext) -> FlagResolution:
|
|
126
126
|
"""Resolve one flag against a validated, merged context."""
|
|
127
127
|
|
|
128
128
|
def shutdown(self, timeout_ms: int) -> None:
|