fivefold 0.1.0__py3-none-any.whl
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.
- fivefold/__init__.py +4 -0
- fivefold/_data/db/bootstrap.sql +26 -0
- fivefold/_data/db/migrations/0001_schemas.sql +67 -0
- fivefold/_data/db/migrations/0002_gateway.sql +224 -0
- fivefold/_data/db/migrations/0003_gateway_record_0010.sql +91 -0
- fivefold/_data/db/migrations/0004_harness.sql +141 -0
- fivefold/_data/db/migrations/0005_sim.sql +679 -0
- fivefold/_data/db/migrations/0006_gateway_reads.sql +66 -0
- fivefold/_data/db/migrations/0007_eval.sql +33 -0
- fivefold/_data/db/migrations/0008_run_stop.sql +18 -0
- fivefold/_data/db/migrations/0009_message_copies.sql +69 -0
- fivefold/_data/db/migrations/0010_gateway_g1_check.sql +14 -0
- fivefold/_data/db/migrations/0011_model_calls.sql +37 -0
- fivefold/_data/db/migrations/0012_recovery_latency.sql +23 -0
- fivefold/_data/db/migrations/0013_split_topology.sql +33 -0
- fivefold/_data/db/migrations/0014_tool_call_args.sql +20 -0
- fivefold/_data/db/registry/0001_registry.sql +31 -0
- fivefold/_data/faults/expected.yaml +406 -0
- fivefold/_data/scenarios/dev/dev-001-single-po.yaml +45 -0
- fivefold/_data/scenarios/dev/dev-002-human-approval.yaml +47 -0
- fivefold/agents/__init__.py +7 -0
- fivefold/agents/branch.py +187 -0
- fivefold/agents/checkpoint.py +77 -0
- fivefold/agents/connection.py +153 -0
- fivefold/agents/live.py +492 -0
- fivefold/agents/policy.py +426 -0
- fivefold/agents/remote.py +333 -0
- fivefold/agents/replay.py +170 -0
- fivefold/agents/scripted.py +122 -0
- fivefold/agents/tools.py +229 -0
- fivefold/agents/worker.py +164 -0
- fivefold/domain/__init__.py +5 -0
- fivefold/domain/api.py +517 -0
- fivefold/domain/authority.py +149 -0
- fivefold/domain/contracts.py +80 -0
- fivefold/domain/identity.py +113 -0
- fivefold/domain/prices.py +178 -0
- fivefold/domain/report.py +92 -0
- fivefold/domain/rules.py +346 -0
- fivefold/domain/scenario.py +524 -0
- fivefold/evaluator/__init__.py +155 -0
- fivefold/evaluator/__main__.py +127 -0
- fivefold/evaluator/authorization.py +146 -0
- fivefold/evaluator/checks.py +331 -0
- fivefold/evaluator/evaluate.py +109 -0
- fivefold/evaluator/evidence.py +392 -0
- fivefold/evaluator/freshness.py +136 -0
- fivefold/evaluator/liveness.py +236 -0
- fivefold/evaluator/load.py +354 -0
- fivefold/evaluator/metrics.py +95 -0
- fivefold/evaluator/records.py +452 -0
- fivefold/evaluator/recovery.py +209 -0
- fivefold/evaluator/report.py +1096 -0
- fivefold/evaluator/result.py +344 -0
- fivefold/evaluator/store.py +83 -0
- fivefold/faults/__init__.py +5 -0
- fivefold/faults/catalog.py +278 -0
- fivefold/faults/plan.py +538 -0
- fivefold/gateway/__init__.py +6 -0
- fivefold/gateway/admin.py +179 -0
- fivefold/gateway/admin_api.py +398 -0
- fivefold/gateway/codec.py +372 -0
- fivefold/gateway/destination.py +64 -0
- fivefold/gateway/dispatcher.py +379 -0
- fivefold/gateway/freshness.py +83 -0
- fivefold/gateway/invariants.py +761 -0
- fivefold/gateway/memory.py +277 -0
- fivefold/gateway/pg_store.py +657 -0
- fivefold/gateway/records.py +592 -0
- fivefold/gateway/server.py +102 -0
- fivefold/gateway/sim_client.py +295 -0
- fivefold/gateway/state_machine.py +376 -0
- fivefold/gateway/steps.py +897 -0
- fivefold/gateway/store.py +635 -0
- fivefold/gateway/tools.py +424 -0
- fivefold/gateway/twin.py +199 -0
- fivefold/gateway/wire.py +138 -0
- fivefold/harness/__init__.py +6 -0
- fivefold/harness/actors.py +230 -0
- fivefold/harness/cells.py +303 -0
- fivefold/harness/clock.py +209 -0
- fivefold/harness/demo.py +397 -0
- fivefold/harness/fault_effects.py +122 -0
- fivefold/harness/live_options.py +159 -0
- fivefold/harness/log.py +540 -0
- fivefold/harness/mcp_link.py +409 -0
- fivefold/harness/migrations.py +520 -0
- fivefold/harness/models.py +368 -0
- fivefold/harness/registry.py +105 -0
- fivefold/harness/reports.py +100 -0
- fivefold/harness/rng.py +57 -0
- fivefold/harness/run.py +881 -0
- fivefold/harness/scheduler.py +441 -0
- fivefold/harness/sim_points.py +215 -0
- fivefold/harness/split/__init__.py +34 -0
- fivefold/harness/split/__main__.py +275 -0
- fivefold/harness/split/credentials.py +74 -0
- fivefold/harness/split/faults.py +75 -0
- fivefold/harness/split/gateway.py +769 -0
- fivefold/harness/split/hops.py +291 -0
- fivefold/harness/split/lifecycle.py +322 -0
- fivefold/harness/split/rundir.py +152 -0
- fivefold/harness/split/service.py +157 -0
- fivefold/harness/split/simulator.py +432 -0
- fivefold/harness/study.py +643 -0
- fivefold/harness/transport.py +533 -0
- fivefold/paths.py +24 -0
- fivefold/py.typed +0 -0
- fivefold/recorder/__init__.py +18 -0
- fivefold/recorder/__main__.py +308 -0
- fivefold/recorder/cassette.py +322 -0
- fivefold/recorder/playback.py +316 -0
- fivefold/recorder/recording.py +133 -0
- fivefold/sim/__init__.py +37 -0
- fivefold/sim/config.py +52 -0
- fivefold/sim/endpoint.py +176 -0
- fivefold/sim/ledger.py +583 -0
- fivefold/sim/service.py +834 -0
- fivefold/viewer/__init__.py +14 -0
- fivefold/viewer/__main__.py +75 -0
- fivefold/viewer/app.py +122 -0
- fivefold/viewer/records.py +108 -0
- fivefold/viewer/source.py +196 -0
- fivefold/viewer/timeline.py +61 -0
- fivefold-0.1.0.dist-info/METADATA +169 -0
- fivefold-0.1.0.dist-info/RECORD +128 -0
- fivefold-0.1.0.dist-info/WHEEL +4 -0
- fivefold-0.1.0.dist-info/licenses/LICENSE +202 -0
|
@@ -0,0 +1,179 @@
|
|
|
1
|
+
"""The gateway's admin path, in process: open escalations and their resolution (0003).
|
|
2
|
+
|
|
3
|
+
Escalation hands an action whose outcome is unknown to a human: after the `escalated`
|
|
4
|
+
note, only an attestation moves the action (0010, reading 7). A human resolves an
|
|
5
|
+
escalation through the admin API by attesting that the action committed, naming the
|
|
6
|
+
effect, or that it did not (0003, escalation). `GatewayAdmin` is the core of that API,
|
|
7
|
+
in the gateway's process. In-process runs call it directly, as the scripted resolver
|
|
8
|
+
does; `admin_api.py` serves it over HTTP, with the gateway's records, for a gateway
|
|
9
|
+
served over HTTP. It reads time only from the run's virtual clock (0009), and it never
|
|
10
|
+
contacts the simulator: the human checks the world out of band, and the gateway records
|
|
11
|
+
what the human attests.
|
|
12
|
+
|
|
13
|
+
- `open_escalations` lists the escalations no one has resolved yet, in escalation-id
|
|
14
|
+
order, with what a human needs to check each one: the action, the approval its
|
|
15
|
+
attempts cite, when the escalation opened, when the action was last sent, and from
|
|
16
|
+
when "not committed" can be attested.
|
|
17
|
+
- `resolve` attests one escalation through the store's `attest`: T11 or T12, with reason
|
|
18
|
+
`human_attested`. The store refuses "not committed" before S past the action's latest
|
|
19
|
+
send, and accepts an attestation that names an effect at any time (0010, reading 8).
|
|
20
|
+
Every wait on the action then ends at once, as it does after a step of its driver. A
|
|
21
|
+
refusal is named after the store refused: `EscalationResolved` for an escalation
|
|
22
|
+
resolved already, `BeforeSettleTime` for "not committed" too early. Both are
|
|
23
|
+
`StepRefused`, and the store's rules decide either way.
|
|
24
|
+
"""
|
|
25
|
+
|
|
26
|
+
from __future__ import annotations
|
|
27
|
+
|
|
28
|
+
from collections.abc import Mapping
|
|
29
|
+
from dataclasses import dataclass
|
|
30
|
+
|
|
31
|
+
from fivefold.gateway import steps
|
|
32
|
+
from fivefold.gateway.dispatcher import Dispatcher
|
|
33
|
+
from fivefold.gateway.records import ActionResult, Escalation, Resolution, check_text
|
|
34
|
+
from fivefold.gateway.steps import StepRefused
|
|
35
|
+
from fivefold.gateway.store import ActionStore, in_action_order, view_of
|
|
36
|
+
from fivefold.harness.scheduler import Scheduler
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
class UnknownEscalation(LookupError):
|
|
40
|
+
"""No action of the run has an escalation with this id."""
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
class EscalationResolved(StepRefused):
|
|
44
|
+
"""The escalation is resolved already: each one is resolved once (0003, escalation).
|
|
45
|
+
|
|
46
|
+
`escalation` is the escalation as it was resolved: when, how and by whom.
|
|
47
|
+
"""
|
|
48
|
+
|
|
49
|
+
def __init__(self, message: str, escalation: Escalation) -> None:
|
|
50
|
+
super().__init__(message)
|
|
51
|
+
self.escalation = escalation
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
class BeforeSettleTime(StepRefused):
|
|
55
|
+
"""An attestation of "not committed" before S past the latest send (0010, reading 8).
|
|
56
|
+
|
|
57
|
+
`not_committed_from_vt` is the first virtual time at which it can be made.
|
|
58
|
+
"""
|
|
59
|
+
|
|
60
|
+
def __init__(self, message: str, not_committed_from_vt: int) -> None:
|
|
61
|
+
super().__init__(message)
|
|
62
|
+
self.not_committed_from_vt = not_committed_from_vt
|
|
63
|
+
|
|
64
|
+
|
|
65
|
+
@dataclass(frozen=True)
|
|
66
|
+
class OpenEscalation:
|
|
67
|
+
"""An escalation no one has resolved yet, as the admin path lists it (0003)."""
|
|
68
|
+
|
|
69
|
+
escalation_id: str
|
|
70
|
+
action_id: str
|
|
71
|
+
intent_id: str
|
|
72
|
+
operation: str
|
|
73
|
+
target: str
|
|
74
|
+
args: Mapping[str, str | int]
|
|
75
|
+
approval_id: str
|
|
76
|
+
"""The approval the action's grant names. Every attempt of the action cites it, and
|
|
77
|
+
no attempt of another action does (0002, rules 12 and 13)."""
|
|
78
|
+
opened_vt: int
|
|
79
|
+
last_sent_vt: int
|
|
80
|
+
"""When the action's latest attempt was sent. "Not committed" can be attested only
|
|
81
|
+
at or after S past it (0010, reading 8)."""
|
|
82
|
+
not_committed_from_vt: int
|
|
83
|
+
"""`last_sent_vt` plus S: from then on, every request of the action has committed or
|
|
84
|
+
never will (0005), and "not committed" can be attested."""
|
|
85
|
+
|
|
86
|
+
|
|
87
|
+
class GatewayAdmin:
|
|
88
|
+
"""The admin path of one gateway: its open escalations, and their resolution."""
|
|
89
|
+
|
|
90
|
+
def __init__(self, scheduler: Scheduler, store: ActionStore, dispatcher: Dispatcher) -> None:
|
|
91
|
+
self._scheduler = scheduler
|
|
92
|
+
self._store = store
|
|
93
|
+
self._dispatcher = dispatcher
|
|
94
|
+
|
|
95
|
+
def open_escalations(self) -> tuple[OpenEscalation, ...]:
|
|
96
|
+
"""Every escalation no one has resolved yet, in escalation-id order."""
|
|
97
|
+
snapshot = self._store.snapshot()
|
|
98
|
+
escalated = [e.action_id for e in snapshot.escalations.values() if e.resolved_vt is None]
|
|
99
|
+
settle_ms = self._store.settings.settle_ms
|
|
100
|
+
found: list[OpenEscalation] = []
|
|
101
|
+
for action_id in in_action_order(escalated):
|
|
102
|
+
view = view_of(snapshot, action_id)
|
|
103
|
+
escalation, grant = view.escalation, view.grant
|
|
104
|
+
if escalation is None or grant is None or not view.attempts:
|
|
105
|
+
raise AssertionError(f"{action_id} is escalated with no grant or no send")
|
|
106
|
+
action = view.action
|
|
107
|
+
last_sent_vt = max(attempt.sent_vt for attempt in view.attempts)
|
|
108
|
+
found.append(
|
|
109
|
+
OpenEscalation(
|
|
110
|
+
escalation_id=escalation.escalation_id,
|
|
111
|
+
action_id=action_id,
|
|
112
|
+
intent_id=action.intent_id,
|
|
113
|
+
operation=action.operation,
|
|
114
|
+
target=action.target,
|
|
115
|
+
args=action.args,
|
|
116
|
+
approval_id=grant.approval_id,
|
|
117
|
+
opened_vt=escalation.opened_vt,
|
|
118
|
+
last_sent_vt=last_sent_vt,
|
|
119
|
+
not_committed_from_vt=last_sent_vt + settle_ms,
|
|
120
|
+
)
|
|
121
|
+
)
|
|
122
|
+
return tuple(found)
|
|
123
|
+
|
|
124
|
+
def resolve(
|
|
125
|
+
self,
|
|
126
|
+
escalation_id: str,
|
|
127
|
+
resolution: Resolution,
|
|
128
|
+
effect_id: str | None = None,
|
|
129
|
+
*,
|
|
130
|
+
actor: str,
|
|
131
|
+
) -> ActionResult:
|
|
132
|
+
"""Attest an escalated action's outcome now: T11 or T12, `human_attested` (0003).
|
|
133
|
+
|
|
134
|
+
`effect_id` names the effect for `committed` and is None for `not_committed`.
|
|
135
|
+
`actor` names the human, as the escalation records it. Returns the action's
|
|
136
|
+
result after the attestation.
|
|
137
|
+
|
|
138
|
+
Raises `UnknownEscalation` for an id no action has; `EscalationResolved` for an
|
|
139
|
+
escalation already resolved; `BeforeSettleTime` for "not committed" before S past
|
|
140
|
+
the action's latest send; and `ValueError` for an effect id that does not fit the
|
|
141
|
+
resolution. The two refusals are `StepRefused`, raised once the store refused.
|
|
142
|
+
"""
|
|
143
|
+
if not actor:
|
|
144
|
+
raise ValueError("an attestation names the human who made it")
|
|
145
|
+
check_text(actor, "the actor")
|
|
146
|
+
if effect_id is not None:
|
|
147
|
+
check_text(effect_id, "the effect id")
|
|
148
|
+
escalation = self._store.snapshot().escalations.get(escalation_id)
|
|
149
|
+
if escalation is None:
|
|
150
|
+
raise UnknownEscalation(escalation_id)
|
|
151
|
+
action_id = escalation.action_id
|
|
152
|
+
try:
|
|
153
|
+
self._store.attest(action_id, resolution, effect_id, actor, self._scheduler.now)
|
|
154
|
+
except StepRefused as refused:
|
|
155
|
+
named = self._named(action_id, resolution, refused)
|
|
156
|
+
if named is None:
|
|
157
|
+
raise
|
|
158
|
+
raise named from refused
|
|
159
|
+
self._dispatcher.wake(action_id)
|
|
160
|
+
return steps.result_for(self._store.view(action_id))
|
|
161
|
+
|
|
162
|
+
def _named(
|
|
163
|
+
self, action_id: str, resolution: Resolution, refused: StepRefused
|
|
164
|
+
) -> StepRefused | None:
|
|
165
|
+
"""Why the store refused an attestation, read from the records after it did."""
|
|
166
|
+
view = self._store.view(action_id)
|
|
167
|
+
escalation = view.escalation
|
|
168
|
+
if escalation is not None and escalation.resolved_vt is not None:
|
|
169
|
+
message = (
|
|
170
|
+
f"{escalation.escalation_id} is resolved already: {escalation.resolution},"
|
|
171
|
+
f" attested by {escalation.actor} at vt {escalation.resolved_vt}"
|
|
172
|
+
)
|
|
173
|
+
return EscalationResolved(message, escalation)
|
|
174
|
+
if resolution is Resolution.NOT_COMMITTED and view.attempts:
|
|
175
|
+
last_sent_vt = max(attempt.sent_vt for attempt in view.attempts)
|
|
176
|
+
due = last_sent_vt + self._store.settings.settle_ms
|
|
177
|
+
if self._scheduler.now < due:
|
|
178
|
+
return BeforeSettleTime(str(refused), due)
|
|
179
|
+
return None
|
|
@@ -0,0 +1,398 @@
|
|
|
1
|
+
"""The gateway's admin API over HTTP, built with FastAPI (0002 rule 22, 0003, 0010).
|
|
2
|
+
|
|
3
|
+
`admin_app` serves one gateway's admin path as JSON. It lists the gateway's actions,
|
|
4
|
+
grants and action events and its open escalations, and it resolves an escalation when a
|
|
5
|
+
human attests what happened: committed, naming the effect, or not committed (0003,
|
|
6
|
+
escalation). It never issues or revokes approvals; that happens in the approvals service
|
|
7
|
+
(0002, rule 22). In-process runs and the demos call `GatewayAdmin` directly, as the
|
|
8
|
+
scripted resolver does. This app is for a gateway served over HTTP, which mounts it, for
|
|
9
|
+
example under `/admin`. Paths below are relative to that mount.
|
|
10
|
+
|
|
11
|
+
- `GET /actions`: `actions`, every action in action-id order, with its state, intent,
|
|
12
|
+
operation, target, arguments, grant, the approval its grant names and its effect id.
|
|
13
|
+
- `GET /actions/{action_id}`: the `action`, its `escalation` (or null) and its
|
|
14
|
+
`events`, in seq order.
|
|
15
|
+
- `GET /grants`: `grants`, every grant in action-id order.
|
|
16
|
+
- `GET /events?from_seq=N`: `events`, the run's action events with seq N or more, in
|
|
17
|
+
seq order. N defaults to 0, which gives all of them.
|
|
18
|
+
- `GET /escalations`: `escalations`, the open ones, as `GatewayAdmin.open_escalations`
|
|
19
|
+
lists them, each with `not_committed_from_vt`.
|
|
20
|
+
- `POST /escalations/{escalation_id}/resolve`: the action's result after the
|
|
21
|
+
attestation, in the shape the agent sees (0003).
|
|
22
|
+
|
|
23
|
+
The resolve request is `{"resolution": "committed", "effect_id": "PO-0001", "actor":
|
|
24
|
+
"ops-1"}`, or `not_committed` with no effect id. It goes through `GatewayAdmin.resolve`,
|
|
25
|
+
so the store's rules and the dispatcher's wake apply unchanged: T11 or T12, with reason
|
|
26
|
+
`human_attested`, and every wait on the action ends at once.
|
|
27
|
+
|
|
28
|
+
Every error answers `{"reason": ..., "message": ...}`:
|
|
29
|
+
|
|
30
|
+
- 401 without the bearer token: `missing_token`, `wrong_scheme` or `invalid_token`;
|
|
31
|
+
- 404 for an unknown action, escalation or path: `unknown_action`, `unknown_escalation`
|
|
32
|
+
or `not_found` (405 `method_not_allowed` for a known path with another method);
|
|
33
|
+
- 409 for a step the store refused: `escalation_resolved`, with the `escalation` as it
|
|
34
|
+
was resolved, or `before_settle_time`, with `not_committed_from_vt`, when "not
|
|
35
|
+
committed" comes before S past the action's latest send (0010, reading 8), or
|
|
36
|
+
`step_refused` for any other refusal, with the store's message;
|
|
37
|
+
- 422 `invalid_request` for input that does not parse;
|
|
38
|
+
- 500 `internal_error` for anything else.
|
|
39
|
+
|
|
40
|
+
Authentication: every HTTP request needs `Authorization: Bearer TOKEN` (RFC 6750), with
|
|
41
|
+
the token the app was built with, before routing, so an unknown path needs it too. A
|
|
42
|
+
deployment reads the token from `FIVEFOLD_ADMIN_API_TOKEN` (`token_from_environment`).
|
|
43
|
+
The app compares SHA-256 digests of the two tokens in constant time, so how long a
|
|
44
|
+
refusal takes says nothing about the token, not even its length. The app refuses to be
|
|
45
|
+
built with an empty token, because the admin API attests outcomes, or with a token that
|
|
46
|
+
RFC 6750 does not allow.
|
|
47
|
+
|
|
48
|
+
Time and reach: the app reads time only through `GatewayAdmin`, from the gateway's
|
|
49
|
+
scheduler (0009). It never contacts the simulator, and holds no simulator client and no
|
|
50
|
+
credential: it reads the gateway's records and calls the admin path. FastAPI's own
|
|
51
|
+
telemetry is off, so a request reads no wall clock, and no environment variable can make
|
|
52
|
+
the app export anything.
|
|
53
|
+
|
|
54
|
+
Every handler is a coroutine, so FastAPI runs it on the event loop that serves the app,
|
|
55
|
+
never in a worker thread. Serve the app on the gateway's own event loop: the handlers
|
|
56
|
+
call the store and the dispatcher directly, a store is used from one thread at a time,
|
|
57
|
+
and the dispatcher's wake sets the loop's events. Under the deterministic scheduler, a
|
|
58
|
+
request made in a scheduler event, such as one through httpx's ASGI transport, waits on
|
|
59
|
+
no timer and on no real wait, so `settle` lets it finish before the next event fires:
|
|
60
|
+
it acts at that event's virtual time, as a call to `GatewayAdmin` there would.
|
|
61
|
+
|
|
62
|
+
FastAPI and Starlette APIs used, checked in the installed source (fastapi 0.162.7,
|
|
63
|
+
starlette 1.10.0): `FastAPI(openapi_url=, docs_url=, redoc_url=, telemetry=)`,
|
|
64
|
+
`FastAPI.get`, `FastAPI.post`, `FastAPI.exception_handler`, `FastAPI.add_middleware`,
|
|
65
|
+
`fastapi.Query`, `fastapi.exceptions.RequestValidationError.errors`,
|
|
66
|
+
`fastapi.responses.JSONResponse`, `starlette.exceptions.HTTPException`,
|
|
67
|
+
`starlette.datastructures.Headers(scope=)` and the types in `starlette.types`.
|
|
68
|
+
"""
|
|
69
|
+
|
|
70
|
+
from __future__ import annotations
|
|
71
|
+
|
|
72
|
+
import hashlib
|
|
73
|
+
import hmac
|
|
74
|
+
import os
|
|
75
|
+
import re
|
|
76
|
+
from collections.abc import Mapping
|
|
77
|
+
from typing import Annotated, Protocol
|
|
78
|
+
|
|
79
|
+
from fastapi import FastAPI, Query, Request
|
|
80
|
+
from fastapi.exceptions import RequestValidationError
|
|
81
|
+
from fastapi.responses import JSONResponse
|
|
82
|
+
from pydantic import BaseModel, ConfigDict, StringConstraints, model_validator
|
|
83
|
+
from starlette.datastructures import Headers
|
|
84
|
+
from starlette.exceptions import HTTPException as StarletteHTTPException
|
|
85
|
+
from starlette.types import ASGIApp, Receive, Scope, Send
|
|
86
|
+
|
|
87
|
+
from fivefold.domain.api import Id
|
|
88
|
+
from fivefold.gateway import wire
|
|
89
|
+
from fivefold.gateway.admin import (
|
|
90
|
+
BeforeSettleTime,
|
|
91
|
+
EscalationResolved,
|
|
92
|
+
GatewayAdmin,
|
|
93
|
+
OpenEscalation,
|
|
94
|
+
UnknownEscalation,
|
|
95
|
+
)
|
|
96
|
+
from fivefold.gateway.codec import to_json
|
|
97
|
+
from fivefold.gateway.records import Action, ActionEvent, Escalation, Grant, Resolution, Snapshot
|
|
98
|
+
from fivefold.gateway.steps import StepRefused, action_number
|
|
99
|
+
from fivefold.gateway.store import UnknownAction, view_of
|
|
100
|
+
|
|
101
|
+
TOKEN_VARIABLE = "FIVEFOLD_ADMIN_API_TOKEN"
|
|
102
|
+
"""The environment variable a deployment reads the admin API's bearer token from."""
|
|
103
|
+
|
|
104
|
+
REALM = "fivefold-admin"
|
|
105
|
+
"""The realm a 401 answer names in its `WWW-Authenticate` header (RFC 6750)."""
|
|
106
|
+
|
|
107
|
+
_TOKEN = re.compile(r"[A-Za-z0-9\-._~+/]+=*")
|
|
108
|
+
"""RFC 6750's `b64token`: what a bearer token may hold."""
|
|
109
|
+
|
|
110
|
+
Json = dict[str, object]
|
|
111
|
+
|
|
112
|
+
Actor = Annotated[str, StringConstraints(pattern=r"^[^\x00-\x1f\x7f]{1,200}$")]
|
|
113
|
+
"""The human who attests: 1 to 200 characters, no control characters."""
|
|
114
|
+
|
|
115
|
+
|
|
116
|
+
class GatewayRecords(Protocol):
|
|
117
|
+
"""The admin API's read path: the gateway's records as one consistent snapshot.
|
|
118
|
+
|
|
119
|
+
Every `ActionStore` is one. A gateway may pass the store its admin path uses, or a
|
|
120
|
+
further store of the same run on its own connection.
|
|
121
|
+
"""
|
|
122
|
+
|
|
123
|
+
def snapshot(self) -> Snapshot:
|
|
124
|
+
"""Every gateway record of the run, as one read sees them."""
|
|
125
|
+
...
|
|
126
|
+
|
|
127
|
+
def events_from(self, seq: int) -> tuple[ActionEvent, ...]:
|
|
128
|
+
"""The run's action events with seq `seq` or more, in seq order. `GET /events`
|
|
129
|
+
reads only these, so polling it never reads the rest of the run."""
|
|
130
|
+
...
|
|
131
|
+
|
|
132
|
+
|
|
133
|
+
class Attestation(BaseModel):
|
|
134
|
+
"""What a human attests about an escalated action (0003, escalation)."""
|
|
135
|
+
|
|
136
|
+
model_config = ConfigDict(extra="forbid", frozen=True)
|
|
137
|
+
|
|
138
|
+
resolution: Resolution
|
|
139
|
+
effect_id: Id | None = None
|
|
140
|
+
actor: Actor
|
|
141
|
+
|
|
142
|
+
@model_validator(mode="after")
|
|
143
|
+
def _effect_fits(self) -> Attestation:
|
|
144
|
+
if (self.resolution is Resolution.COMMITTED) != (self.effect_id is not None):
|
|
145
|
+
raise ValueError("effect_id names the effect for committed, and only for committed")
|
|
146
|
+
return self
|
|
147
|
+
|
|
148
|
+
|
|
149
|
+
def token_from_environment(environ: Mapping[str, str] | None = None) -> str:
|
|
150
|
+
"""The admin API's bearer token, from `FIVEFOLD_ADMIN_API_TOKEN`.
|
|
151
|
+
|
|
152
|
+
Raises `ValueError` when the variable is missing or empty. `environ` defaults to the
|
|
153
|
+
process's environment.
|
|
154
|
+
"""
|
|
155
|
+
token = (os.environ if environ is None else environ).get(TOKEN_VARIABLE, "")
|
|
156
|
+
if not token:
|
|
157
|
+
raise ValueError(f"set {TOKEN_VARIABLE} to the admin API's bearer token")
|
|
158
|
+
return token
|
|
159
|
+
|
|
160
|
+
|
|
161
|
+
def admin_app(admin: GatewayAdmin, records: GatewayRecords, *, token: str) -> FastAPI:
|
|
162
|
+
"""The admin API of one gateway, as an ASGI app; see the module docstring.
|
|
163
|
+
|
|
164
|
+
`admin` is the gateway's admin path, `records` its read path and `token` the bearer
|
|
165
|
+
token every request must carry. Raises `ValueError` for an empty token, or one with a
|
|
166
|
+
character RFC 6750 does not allow.
|
|
167
|
+
"""
|
|
168
|
+
if not token:
|
|
169
|
+
raise ValueError("the admin API needs a bearer token: it attests outcomes")
|
|
170
|
+
if not _TOKEN.fullmatch(token):
|
|
171
|
+
raise ValueError(
|
|
172
|
+
"a bearer token holds letters, digits and -._~+/, then any number of = (RFC 6750)"
|
|
173
|
+
)
|
|
174
|
+
app = FastAPI(
|
|
175
|
+
title="FiveFold gateway admin API",
|
|
176
|
+
openapi_url=None,
|
|
177
|
+
docs_url=None,
|
|
178
|
+
redoc_url=None,
|
|
179
|
+
telemetry={"tracing": False, "metrics": False, "logs": False, "auto_configure": False},
|
|
180
|
+
)
|
|
181
|
+
app.add_middleware(BearerToken, digest=_digest(token))
|
|
182
|
+
|
|
183
|
+
@app.exception_handler(StarletteHTTPException)
|
|
184
|
+
async def http_error(request: Request, error: StarletteHTTPException) -> JSONResponse:
|
|
185
|
+
reasons = {404: "not_found", 405: "method_not_allowed"}
|
|
186
|
+
reason = reasons.get(error.status_code, "http_error")
|
|
187
|
+
return _error(error.status_code, reason, str(error.detail), headers=error.headers)
|
|
188
|
+
|
|
189
|
+
@app.exception_handler(RequestValidationError)
|
|
190
|
+
async def invalid_request(request: Request, error: RequestValidationError) -> JSONResponse:
|
|
191
|
+
return _error(422, "invalid_request", _problems(error))
|
|
192
|
+
|
|
193
|
+
@app.exception_handler(Exception)
|
|
194
|
+
async def internal_error(request: Request, error: Exception) -> JSONResponse:
|
|
195
|
+
return _error(500, "internal_error", "the gateway could not serve this request")
|
|
196
|
+
|
|
197
|
+
@app.get("/actions")
|
|
198
|
+
async def list_actions() -> JSONResponse:
|
|
199
|
+
snapshot = records.snapshot()
|
|
200
|
+
actions = sorted(snapshot.actions.values(), key=lambda a: action_number(a.action_id))
|
|
201
|
+
return JSONResponse({"actions": [_action(a, _grant_of(snapshot, a)) for a in actions]})
|
|
202
|
+
|
|
203
|
+
@app.get("/actions/{action_id}")
|
|
204
|
+
async def get_action(action_id: str) -> JSONResponse:
|
|
205
|
+
try:
|
|
206
|
+
view = view_of(records.snapshot(), action_id)
|
|
207
|
+
except UnknownAction:
|
|
208
|
+
return _error(404, "unknown_action", f"no action {action_id}")
|
|
209
|
+
escalation = view.escalation
|
|
210
|
+
return JSONResponse(
|
|
211
|
+
{
|
|
212
|
+
"action": _action(view.action, view.grant),
|
|
213
|
+
"escalation": None if escalation is None else _escalation(escalation),
|
|
214
|
+
"events": [_event(event) for event in view.events],
|
|
215
|
+
}
|
|
216
|
+
)
|
|
217
|
+
|
|
218
|
+
@app.get("/grants")
|
|
219
|
+
async def list_grants() -> JSONResponse:
|
|
220
|
+
grants = sorted(
|
|
221
|
+
records.snapshot().grants.values(), key=lambda g: action_number(g.action_id)
|
|
222
|
+
)
|
|
223
|
+
return JSONResponse({"grants": [_grant(grant) for grant in grants]})
|
|
224
|
+
|
|
225
|
+
@app.get("/events")
|
|
226
|
+
async def list_events(from_seq: Annotated[int, Query(ge=0)] = 0) -> JSONResponse:
|
|
227
|
+
events = [_event(e) for e in records.events_from(from_seq)]
|
|
228
|
+
return JSONResponse({"events": events})
|
|
229
|
+
|
|
230
|
+
@app.get("/escalations")
|
|
231
|
+
async def list_escalations() -> JSONResponse:
|
|
232
|
+
escalations = [_open_escalation(e) for e in admin.open_escalations()]
|
|
233
|
+
return JSONResponse({"escalations": escalations})
|
|
234
|
+
|
|
235
|
+
@app.post("/escalations/{escalation_id}/resolve")
|
|
236
|
+
async def resolve(escalation_id: str, attestation: Attestation) -> JSONResponse:
|
|
237
|
+
try:
|
|
238
|
+
result = admin.resolve(
|
|
239
|
+
escalation_id,
|
|
240
|
+
attestation.resolution,
|
|
241
|
+
attestation.effect_id,
|
|
242
|
+
actor=attestation.actor,
|
|
243
|
+
)
|
|
244
|
+
except UnknownEscalation:
|
|
245
|
+
return _error(404, "unknown_escalation", f"no escalation {escalation_id}")
|
|
246
|
+
except EscalationResolved as refused:
|
|
247
|
+
resolved = _escalation(refused.escalation)
|
|
248
|
+
return _error(409, "escalation_resolved", str(refused), escalation=resolved)
|
|
249
|
+
except BeforeSettleTime as refused:
|
|
250
|
+
due = refused.not_committed_from_vt
|
|
251
|
+
return _error(409, "before_settle_time", str(refused), not_committed_from_vt=due)
|
|
252
|
+
except StepRefused as refused:
|
|
253
|
+
return _error(409, "step_refused", str(refused))
|
|
254
|
+
except ValueError as invalid:
|
|
255
|
+
return _error(422, "invalid_request", str(invalid))
|
|
256
|
+
return JSONResponse(wire.action(result))
|
|
257
|
+
|
|
258
|
+
return app
|
|
259
|
+
|
|
260
|
+
|
|
261
|
+
class BearerToken:
|
|
262
|
+
"""ASGI middleware that refuses every HTTP request without the app's bearer token.
|
|
263
|
+
|
|
264
|
+
It runs before routing, so every path needs the token. `digest` is the SHA-256 of
|
|
265
|
+
the token. Other scopes pass through: the lifespan, and WebSockets, which no route
|
|
266
|
+
serves, so the router closes them.
|
|
267
|
+
"""
|
|
268
|
+
|
|
269
|
+
def __init__(self, app: ASGIApp, digest: bytes) -> None:
|
|
270
|
+
self._app = app
|
|
271
|
+
self._digest = digest
|
|
272
|
+
|
|
273
|
+
async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
|
|
274
|
+
if scope["type"] == "http":
|
|
275
|
+
refusal = self._refusal(Headers(scope=scope).get("authorization"))
|
|
276
|
+
if refusal is not None:
|
|
277
|
+
await refusal(scope, receive, send)
|
|
278
|
+
return
|
|
279
|
+
await self._app(scope, receive, send)
|
|
280
|
+
|
|
281
|
+
def _refusal(self, header: str | None) -> JSONResponse | None:
|
|
282
|
+
"""The 401 answer for this Authorization header, or None when the token is right."""
|
|
283
|
+
if header is None:
|
|
284
|
+
return _unauthorized("missing_token", "send Authorization: Bearer TOKEN")
|
|
285
|
+
scheme, _, credentials = header.partition(" ")
|
|
286
|
+
if scheme.lower() != "bearer":
|
|
287
|
+
return _unauthorized("wrong_scheme", "the admin API takes a bearer token")
|
|
288
|
+
if not hmac.compare_digest(_digest(credentials.strip()), self._digest):
|
|
289
|
+
return _unauthorized("invalid_token", "this is not the gateway's admin token")
|
|
290
|
+
return None
|
|
291
|
+
|
|
292
|
+
|
|
293
|
+
def _digest(token: str) -> bytes:
|
|
294
|
+
return hashlib.sha256(token.encode("utf-8")).digest()
|
|
295
|
+
|
|
296
|
+
|
|
297
|
+
def _unauthorized(reason: str, message: str) -> JSONResponse:
|
|
298
|
+
challenge = f'Bearer realm="{REALM}"'
|
|
299
|
+
if reason == "invalid_token":
|
|
300
|
+
challenge += ', error="invalid_token"'
|
|
301
|
+
return _error(401, reason, message, headers={"WWW-Authenticate": challenge})
|
|
302
|
+
|
|
303
|
+
|
|
304
|
+
def _error(
|
|
305
|
+
status: int,
|
|
306
|
+
reason: str,
|
|
307
|
+
message: str,
|
|
308
|
+
*,
|
|
309
|
+
headers: Mapping[str, str] | None = None,
|
|
310
|
+
**extra: object,
|
|
311
|
+
) -> JSONResponse:
|
|
312
|
+
body: Json = {"reason": reason, "message": message, **extra}
|
|
313
|
+
return JSONResponse(body, status_code=status, headers=headers)
|
|
314
|
+
|
|
315
|
+
|
|
316
|
+
def _problems(error: RequestValidationError) -> str:
|
|
317
|
+
"""One clause per problem, naming where it is: `body.resolution: Input should be ...`."""
|
|
318
|
+
lines = []
|
|
319
|
+
for problem in error.errors():
|
|
320
|
+
where = ".".join(str(part) for part in problem.get("loc", ()))
|
|
321
|
+
message = str(problem.get("msg", "invalid"))
|
|
322
|
+
lines.append(f"{where}: {message}" if where else message)
|
|
323
|
+
return "; ".join(lines)
|
|
324
|
+
|
|
325
|
+
|
|
326
|
+
# Records as JSON ---------------------------------------------------------------------------
|
|
327
|
+
|
|
328
|
+
|
|
329
|
+
def _grant_of(snapshot: Snapshot, action: Action) -> Grant | None:
|
|
330
|
+
return None if action.grant_id is None else snapshot.grants.get(action.grant_id)
|
|
331
|
+
|
|
332
|
+
|
|
333
|
+
def _action(action: Action, grant: Grant | None) -> Json:
|
|
334
|
+
return {
|
|
335
|
+
"action_id": action.action_id,
|
|
336
|
+
"intent_id": action.intent_id,
|
|
337
|
+
"operation": action.operation,
|
|
338
|
+
"target": action.target,
|
|
339
|
+
"args": dict(action.args),
|
|
340
|
+
"state": str(action.state),
|
|
341
|
+
"contract": str(action.contract),
|
|
342
|
+
"grant_id": action.grant_id,
|
|
343
|
+
"approval_id": None if grant is None else grant.approval_id,
|
|
344
|
+
"effect_id": action.effect_id,
|
|
345
|
+
"created_vt": action.created_vt,
|
|
346
|
+
"updated_vt": action.updated_vt,
|
|
347
|
+
}
|
|
348
|
+
|
|
349
|
+
|
|
350
|
+
def _grant(grant: Grant) -> Json:
|
|
351
|
+
return {
|
|
352
|
+
"grant_id": grant.grant_id,
|
|
353
|
+
"action_id": grant.action_id,
|
|
354
|
+
"approval_id": grant.approval_id,
|
|
355
|
+
"state": str(grant.state),
|
|
356
|
+
"requested_vt": grant.requested_vt,
|
|
357
|
+
"consumed_vt": grant.consumed_vt,
|
|
358
|
+
}
|
|
359
|
+
|
|
360
|
+
|
|
361
|
+
def _event(event: ActionEvent) -> Json:
|
|
362
|
+
return {
|
|
363
|
+
"seq": event.seq,
|
|
364
|
+
"action_id": event.action_id,
|
|
365
|
+
"kind": str(event.kind),
|
|
366
|
+
"from_state": None if event.from_state is None else str(event.from_state),
|
|
367
|
+
"to_state": str(event.to_state),
|
|
368
|
+
"reason": str(event.reason),
|
|
369
|
+
"details": to_json(event.details),
|
|
370
|
+
"vt": event.vt,
|
|
371
|
+
}
|
|
372
|
+
|
|
373
|
+
|
|
374
|
+
def _escalation(escalation: Escalation) -> Json:
|
|
375
|
+
return {
|
|
376
|
+
"escalation_id": escalation.escalation_id,
|
|
377
|
+
"action_id": escalation.action_id,
|
|
378
|
+
"opened_vt": escalation.opened_vt,
|
|
379
|
+
"resolved_vt": escalation.resolved_vt,
|
|
380
|
+
"resolution": None if escalation.resolution is None else str(escalation.resolution),
|
|
381
|
+
"effect_id": escalation.effect_id,
|
|
382
|
+
"actor": escalation.actor,
|
|
383
|
+
}
|
|
384
|
+
|
|
385
|
+
|
|
386
|
+
def _open_escalation(escalation: OpenEscalation) -> Json:
|
|
387
|
+
return {
|
|
388
|
+
"escalation_id": escalation.escalation_id,
|
|
389
|
+
"action_id": escalation.action_id,
|
|
390
|
+
"intent_id": escalation.intent_id,
|
|
391
|
+
"operation": escalation.operation,
|
|
392
|
+
"target": escalation.target,
|
|
393
|
+
"args": dict(escalation.args),
|
|
394
|
+
"approval_id": escalation.approval_id,
|
|
395
|
+
"opened_vt": escalation.opened_vt,
|
|
396
|
+
"last_sent_vt": escalation.last_sent_vt,
|
|
397
|
+
"not_committed_from_vt": escalation.not_committed_from_vt,
|
|
398
|
+
}
|