test-base 0.1.1__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.
- test_base/__init__.py +20 -0
- test_base/adapters/__init__.py +354 -0
- test_base/adapters/base.py +263 -0
- test_base/adapters/canonical_json.py +1088 -0
- test_base/adapters/junit_xml.py +1272 -0
- test_base/api/__init__.py +0 -0
- test_base/api/app.py +314 -0
- test_base/api/deps.py +178 -0
- test_base/api/routes/__init__.py +0 -0
- test_base/api/routes/failures.py +104 -0
- test_base/api/routes/health.py +35 -0
- test_base/api/routes/imports.py +143 -0
- test_base/api/routes/queries.py +295 -0
- test_base/api/routes/retention.py +130 -0
- test_base/api/routes/runs.py +147 -0
- test_base/api/routes/server.py +65 -0
- test_base/api/routes/stream.py +117 -0
- test_base/api/schemas.py +390 -0
- test_base/api/security.py +183 -0
- test_base/cli/__init__.py +125 -0
- test_base/cli/commands/__init__.py +0 -0
- test_base/cli/commands/db.py +76 -0
- test_base/cli/commands/demo.py +103 -0
- test_base/cli/commands/formats.py +41 -0
- test_base/cli/commands/ingest.py +119 -0
- test_base/cli/commands/init.py +738 -0
- test_base/cli/commands/prune.py +146 -0
- test_base/cli/commands/publish.py +133 -0
- test_base/cli/commands/serve.py +118 -0
- test_base/cli/commands/token.py +97 -0
- test_base/cli/options.py +189 -0
- test_base/cli/render.py +223 -0
- test_base/config.py +519 -0
- test_base/demo/__init__.py +0 -0
- test_base/demo/evidence.py +447 -0
- test_base/demo/seed.py +628 -0
- test_base/domain/__init__.py +61 -0
- test_base/domain/events.py +422 -0
- test_base/domain/failures.py +327 -0
- test_base/domain/identity.py +205 -0
- test_base/domain/metrics.py +176 -0
- test_base/domain/models.py +947 -0
- test_base/domain/status.py +246 -0
- test_base/errors.py +136 -0
- test_base/logging.py +174 -0
- test_base/py.typed +0 -0
- test_base/sdk/__init__.py +28 -0
- test_base/sdk/client.py +607 -0
- test_base/service/__init__.py +0 -0
- test_base/service/bus.py +331 -0
- test_base/service/coalesce.py +133 -0
- test_base/service/imports.py +552 -0
- test_base/service/retention.py +640 -0
- test_base/service/runs.py +394 -0
- test_base/service/runtime.py +123 -0
- test_base/storage/__init__.py +41 -0
- test_base/storage/artifacts.py +347 -0
- test_base/storage/base.py +350 -0
- test_base/storage/db.py +595 -0
- test_base/storage/failures.py +321 -0
- test_base/storage/locks.py +104 -0
- test_base/storage/migrations/env.py +108 -0
- test_base/storage/migrations/script.py.mako +26 -0
- test_base/storage/migrations/versions/0001_initial.py +289 -0
- test_base/storage/migrations/versions/0002_retention_indexes.py +38 -0
- test_base/storage/migrations/versions/0003_postgresql_bigint.py +74 -0
- test_base/storage/migrations/versions/0004_run_shards.py +37 -0
- test_base/storage/migrations/versions/0005_failure_groups.py +206 -0
- test_base/storage/models.py +560 -0
- test_base/storage/repositories.py +2481 -0
- test_base/storage/uow.py +138 -0
- test_base/version.py +17 -0
- test_base/web/assets/css/app.css +3567 -0
- test_base/web/assets/favicon.svg +5 -0
- test_base/web/assets/js/00-util.js +829 -0
- test_base/web/assets/js/05-windows.js +551 -0
- test_base/web/assets/js/10-provider.js +396 -0
- test_base/web/assets/js/12-live-provider.js +804 -0
- test_base/web/assets/js/20-charts.js +715 -0
- test_base/web/assets/js/30-store.js +793 -0
- test_base/web/assets/js/40-components.js +2141 -0
- test_base/web/assets/js/42-timeline.js +629 -0
- test_base/web/assets/js/50-view-overview.js +747 -0
- test_base/web/assets/js/52-view-analytics.js +842 -0
- test_base/web/assets/js/53-view-suites.js +508 -0
- test_base/web/assets/js/54-view-metrics.js +438 -0
- test_base/web/assets/js/55-view-runs.js +244 -0
- test_base/web/assets/js/56-view-evidence.js +703 -0
- test_base/web/assets/js/57-view-failures.js +596 -0
- test_base/web/assets/js/60-view-run.js +788 -0
- test_base/web/assets/js/65-view-test.js +402 -0
- test_base/web/assets/js/70-view-settings.js +524 -0
- test_base/web/assets/js/75-view-help.js +554 -0
- test_base/web/assets/js/80-settings.js +99 -0
- test_base/web/assets/js/85-activity.js +727 -0
- test_base/web/assets/js/90-app.js +595 -0
- test_base/web/assets/manifest.json +70 -0
- test_base/web/index.html +210 -0
- test_base-0.1.1.dist-info/METADATA +285 -0
- test_base-0.1.1.dist-info/RECORD +103 -0
- test_base-0.1.1.dist-info/WHEEL +4 -0
- test_base-0.1.1.dist-info/entry_points.txt +6 -0
- test_base-0.1.1.dist-info/licenses/LICENSE +201 -0
test_base/api/schemas.py
ADDED
|
@@ -0,0 +1,390 @@
|
|
|
1
|
+
"""Request and response bodies for ``/api/v1``.
|
|
2
|
+
|
|
3
|
+
These are the *public* contract — separate from the canonical domain models they
|
|
4
|
+
wrap, and separate again from the ORM (ADR-0001 D3). Responses mostly re-export
|
|
5
|
+
domain models unchanged; requests are their own thing, because what a publisher
|
|
6
|
+
is allowed to *send* is a much smaller surface than what Test Base *stores*. You
|
|
7
|
+
cannot, for instance, post a run's counts: they are derived, and accepting them
|
|
8
|
+
would create two sources of truth for the number on the front page.
|
|
9
|
+
|
|
10
|
+
Every model forbids unknown fields. A publisher with a typo in a field name gets
|
|
11
|
+
a 422 naming the field rather than a silently ignored value and a wrong dashboard.
|
|
12
|
+
"""
|
|
13
|
+
|
|
14
|
+
from __future__ import annotations
|
|
15
|
+
|
|
16
|
+
import uuid
|
|
17
|
+
from typing import Annotated, Any
|
|
18
|
+
|
|
19
|
+
from pydantic import AwareDatetime, BaseModel, ConfigDict, Field, field_validator
|
|
20
|
+
|
|
21
|
+
from test_base.domain.events import DomainEvent
|
|
22
|
+
from test_base.domain.failures import TriageStatus
|
|
23
|
+
from test_base.domain.models import (
|
|
24
|
+
Artifact,
|
|
25
|
+
ArtifactKind,
|
|
26
|
+
ImportResult,
|
|
27
|
+
Project,
|
|
28
|
+
RunContext,
|
|
29
|
+
RunCounts,
|
|
30
|
+
RunSummary,
|
|
31
|
+
ShardRef,
|
|
32
|
+
TestRun,
|
|
33
|
+
TestType,
|
|
34
|
+
TriggerType,
|
|
35
|
+
utcnow,
|
|
36
|
+
)
|
|
37
|
+
from test_base.domain.status import RunStatus
|
|
38
|
+
from test_base.version import SCHEMA_VERSION, __version__
|
|
39
|
+
|
|
40
|
+
__all__ = [
|
|
41
|
+
"ArtifactResponse",
|
|
42
|
+
"CreateRunRequest",
|
|
43
|
+
"ErrorResponse",
|
|
44
|
+
"EventsRequest",
|
|
45
|
+
"EventsResponse",
|
|
46
|
+
"FinishRunRequest",
|
|
47
|
+
"HealthResponse",
|
|
48
|
+
"ImportResponse",
|
|
49
|
+
"ProjectListResponse",
|
|
50
|
+
"PruneRequest",
|
|
51
|
+
"PruneResponse",
|
|
52
|
+
"RetentionSettingsResponse",
|
|
53
|
+
"RunListResponse",
|
|
54
|
+
"ServerDatabase",
|
|
55
|
+
"ServerInfoResponse",
|
|
56
|
+
]
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
class _Request(BaseModel):
|
|
60
|
+
model_config = ConfigDict(extra="forbid", str_strip_whitespace=True, populate_by_name=True)
|
|
61
|
+
|
|
62
|
+
|
|
63
|
+
class _Response(BaseModel):
|
|
64
|
+
model_config = ConfigDict(extra="forbid")
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
# ------------------------------------------------------------------ requests
|
|
68
|
+
|
|
69
|
+
|
|
70
|
+
class CreateRunRequest(_Request):
|
|
71
|
+
"""``POST /api/v1/runs``.
|
|
72
|
+
|
|
73
|
+
``run_id`` is optional and, when supplied, makes the call idempotent: a CI
|
|
74
|
+
step that is retried announces the same run rather than creating a second.
|
|
75
|
+
Publishers that can generate a UUID should always send one.
|
|
76
|
+
"""
|
|
77
|
+
|
|
78
|
+
project_key: Annotated[str, Field(min_length=1, max_length=120)]
|
|
79
|
+
run_id: uuid.UUID | None = None
|
|
80
|
+
name: str | None = None
|
|
81
|
+
team: str | None = None
|
|
82
|
+
component: str | None = None
|
|
83
|
+
test_type: TestType = TestType.OTHER
|
|
84
|
+
trigger: TriggerType = TriggerType.UNKNOWN
|
|
85
|
+
context: RunContext = Field(default_factory=RunContext)
|
|
86
|
+
tags: list[str] = Field(default_factory=list, max_length=64)
|
|
87
|
+
metadata: dict[str, Any] = Field(default_factory=dict)
|
|
88
|
+
expected_tests: int | None = Field(
|
|
89
|
+
default=None, ge=0, description="Collected test count, if known before execution."
|
|
90
|
+
)
|
|
91
|
+
started: bool = Field(
|
|
92
|
+
default=True, description="False to open the run as queued rather than running."
|
|
93
|
+
)
|
|
94
|
+
run_key: str | None = Field(
|
|
95
|
+
default=None,
|
|
96
|
+
max_length=512,
|
|
97
|
+
description="Name of the CI run, e.g. $GITHUB_RUN_ID, instead of run_id: every "
|
|
98
|
+
"publisher sending the same key and project opens the same run.",
|
|
99
|
+
)
|
|
100
|
+
shard: ShardRef | None = Field(
|
|
101
|
+
default=None,
|
|
102
|
+
description="Which slice of a sharded run this publisher is; the run then stays open "
|
|
103
|
+
"until every shard has finished.",
|
|
104
|
+
)
|
|
105
|
+
|
|
106
|
+
|
|
107
|
+
class EventsRequest(_Request):
|
|
108
|
+
"""``POST /api/v1/runs/{run_id}/events``.
|
|
109
|
+
|
|
110
|
+
Send ``sequence: 0`` on every event to have the server allocate a contiguous
|
|
111
|
+
block; send your own monotonic numbers if you want gap detection, which you
|
|
112
|
+
probably do for a long-running suite.
|
|
113
|
+
"""
|
|
114
|
+
|
|
115
|
+
events: Annotated[list[DomainEvent], Field(min_length=1, max_length=5000)]
|
|
116
|
+
|
|
117
|
+
|
|
118
|
+
class FinishRunRequest(_Request):
|
|
119
|
+
"""``POST /api/v1/runs/{run_id}/finish``.
|
|
120
|
+
|
|
121
|
+
``status`` is advisory and only honoured for ``cancelled``; every other
|
|
122
|
+
outcome is folded from the results that were actually reported.
|
|
123
|
+
"""
|
|
124
|
+
|
|
125
|
+
finished_at: AwareDatetime | None = None
|
|
126
|
+
status: RunStatus | None = None
|
|
127
|
+
duration_ms: int | None = Field(default=None, ge=0)
|
|
128
|
+
metadata: dict[str, Any] = Field(default_factory=dict)
|
|
129
|
+
shard: ShardRef | None = Field(
|
|
130
|
+
default=None,
|
|
131
|
+
description="Finish one shard rather than the run. Without it the whole run closes, "
|
|
132
|
+
"including shards that never reported.",
|
|
133
|
+
)
|
|
134
|
+
|
|
135
|
+
|
|
136
|
+
# ----------------------------------------------------------------- responses
|
|
137
|
+
|
|
138
|
+
|
|
139
|
+
class ImportResponse(_Response):
|
|
140
|
+
"""``POST /api/v1/imports``.
|
|
141
|
+
|
|
142
|
+
Deliberately verbose: which adapter was chosen and how confident detection
|
|
143
|
+
was are the first two questions asked when an import produces a surprise.
|
|
144
|
+
"""
|
|
145
|
+
|
|
146
|
+
result: ImportResult
|
|
147
|
+
|
|
148
|
+
|
|
149
|
+
class RunListResponse(_Response):
|
|
150
|
+
runs: list[RunSummary]
|
|
151
|
+
total: int
|
|
152
|
+
limit: int
|
|
153
|
+
offset: int
|
|
154
|
+
|
|
155
|
+
|
|
156
|
+
class ProjectListResponse(_Response):
|
|
157
|
+
projects: list[Project]
|
|
158
|
+
|
|
159
|
+
|
|
160
|
+
class EventsResponse(_Response):
|
|
161
|
+
"""What applying a batch did.
|
|
162
|
+
|
|
163
|
+
``ignored`` is how a publisher confirms idempotency worked: repost a batch
|
|
164
|
+
and every event comes back ignored, with the counts unchanged.
|
|
165
|
+
"""
|
|
166
|
+
|
|
167
|
+
run_id: uuid.UUID
|
|
168
|
+
applied: int
|
|
169
|
+
ignored: int
|
|
170
|
+
created_run: bool
|
|
171
|
+
counts: RunCounts
|
|
172
|
+
status: RunStatus
|
|
173
|
+
|
|
174
|
+
|
|
175
|
+
class ArtifactResponse(_Response):
|
|
176
|
+
artifact: Artifact
|
|
177
|
+
deduplicated: bool = Field(
|
|
178
|
+
default=False, description="True when identical content was already stored."
|
|
179
|
+
)
|
|
180
|
+
|
|
181
|
+
|
|
182
|
+
class RunResponse(_Response):
|
|
183
|
+
run: TestRun
|
|
184
|
+
|
|
185
|
+
|
|
186
|
+
class ArtifactListResponse(_Response):
|
|
187
|
+
artifacts: list[Artifact]
|
|
188
|
+
|
|
189
|
+
|
|
190
|
+
class ErrorResponse(_Response):
|
|
191
|
+
"""The single error shape every failing endpoint returns."""
|
|
192
|
+
|
|
193
|
+
error: str = Field(description="Stable machine-readable code, e.g. `unknown_format`.")
|
|
194
|
+
message: str
|
|
195
|
+
detail: dict[str, Any] = Field(default_factory=dict)
|
|
196
|
+
|
|
197
|
+
|
|
198
|
+
class AdapterInfo(_Response):
|
|
199
|
+
"""One row of ``GET /api/v1/adapters``.
|
|
200
|
+
|
|
201
|
+
Extra keys from an adapter's ``describe()`` are ignored rather than rejected:
|
|
202
|
+
a third-party adapter is entitled to describe itself with fields this build
|
|
203
|
+
has never heard of, and refusing the whole listing over one of them would
|
|
204
|
+
make an unrelated plugin able to break the endpoint.
|
|
205
|
+
"""
|
|
206
|
+
|
|
207
|
+
model_config = ConfigDict(extra="ignore")
|
|
208
|
+
|
|
209
|
+
name: str
|
|
210
|
+
display_name: str = ""
|
|
211
|
+
description: str = ""
|
|
212
|
+
priority: int = 0
|
|
213
|
+
extensions: list[str] = Field(default_factory=list)
|
|
214
|
+
content_types: list[str] = Field(default_factory=list)
|
|
215
|
+
|
|
216
|
+
|
|
217
|
+
class AdapterListResponse(_Response):
|
|
218
|
+
adapters: list[AdapterInfo]
|
|
219
|
+
|
|
220
|
+
|
|
221
|
+
class HealthResponse(_Response):
|
|
222
|
+
"""``GET /healthz`` — cheap enough for a container healthcheck every 10s."""
|
|
223
|
+
|
|
224
|
+
status: str = "ok"
|
|
225
|
+
version: str = __version__
|
|
226
|
+
schema_version: int = SCHEMA_VERSION
|
|
227
|
+
database: str = "ok"
|
|
228
|
+
workspace_id: uuid.UUID | None = None
|
|
229
|
+
live_subscribers: int = 0
|
|
230
|
+
time: AwareDatetime = Field(default_factory=utcnow)
|
|
231
|
+
|
|
232
|
+
|
|
233
|
+
class ServerDatabase(_Response):
|
|
234
|
+
"""The database this server writes to."""
|
|
235
|
+
|
|
236
|
+
backend: str = Field(description="`sqlite` or `postgresql`.")
|
|
237
|
+
label: str = Field(description="`SQLite` or `PostgreSQL`, for display.")
|
|
238
|
+
server: str | None = Field(
|
|
239
|
+
default=None,
|
|
240
|
+
description="Engine and version, such as `PostgreSQL 16.4`. Administrators only.",
|
|
241
|
+
)
|
|
242
|
+
location: str | None = Field(
|
|
243
|
+
default=None,
|
|
244
|
+
description="The SQLite file, or the PostgreSQL URL without driver or password. "
|
|
245
|
+
"Administrators only.",
|
|
246
|
+
)
|
|
247
|
+
|
|
248
|
+
|
|
249
|
+
class ServerInfoResponse(_Response):
|
|
250
|
+
"""``GET /api/v1/server`` — what this server runs on, for Settings and Help.
|
|
251
|
+
|
|
252
|
+
Which kind of database is no secret; where it lives is. A host name, a
|
|
253
|
+
database user and a home directory in a path are a small map of the
|
|
254
|
+
infrastructure, so those fields are filled for administrators only
|
|
255
|
+
(:func:`test_base.api.deps.is_admin`) and are ``null`` for everyone else.
|
|
256
|
+
"""
|
|
257
|
+
|
|
258
|
+
admin: bool = Field(description="Whether this caller may see the details.")
|
|
259
|
+
auth_enabled: bool = Field(
|
|
260
|
+
description="Whether publishing needs a token. No secret: an unauthenticated POST "
|
|
261
|
+
"answers the same question with a 401."
|
|
262
|
+
)
|
|
263
|
+
version: str = Field(default=__version__, description="The Test Base version.")
|
|
264
|
+
database: ServerDatabase
|
|
265
|
+
artifacts_dir: str | None = Field(default=None, description="Administrators only.")
|
|
266
|
+
settings_file: str | None = Field(
|
|
267
|
+
default=None,
|
|
268
|
+
description="The settings file `test-base init` saved, when there is one. "
|
|
269
|
+
"Administrators only.",
|
|
270
|
+
)
|
|
271
|
+
|
|
272
|
+
|
|
273
|
+
ARTIFACT_KINDS = [kind.value for kind in ArtifactKind]
|
|
274
|
+
|
|
275
|
+
|
|
276
|
+
# ----------------------------------------------------------------- retention
|
|
277
|
+
|
|
278
|
+
|
|
279
|
+
class RetentionSettingsResponse(_Response):
|
|
280
|
+
"""What the dashboard needs to draw the retention panel.
|
|
281
|
+
|
|
282
|
+
``admin`` is about *this caller*, not about the server: it answers "may the
|
|
283
|
+
person holding this page delete anything", which is the only question the UI
|
|
284
|
+
can act on. A dashboard that drew a delete button and then got a 403 would be
|
|
285
|
+
worse than one that never drew it.
|
|
286
|
+
"""
|
|
287
|
+
|
|
288
|
+
admin: bool = Field(description="Whether this caller may run a prune.")
|
|
289
|
+
retention_days: int | None = Field(
|
|
290
|
+
default=None, description="The configured default cutoff, if any."
|
|
291
|
+
)
|
|
292
|
+
min_runs: int = Field(description="Runs always kept per project.")
|
|
293
|
+
grace_hours: float = Field(description="How long a new artifact blob is protected.")
|
|
294
|
+
units: dict[str, int] = Field(description="The duration grammar, in hours per unit.")
|
|
295
|
+
|
|
296
|
+
|
|
297
|
+
class PruneRequest(_Request):
|
|
298
|
+
"""A cutoff, expressed the way the caller prefers.
|
|
299
|
+
|
|
300
|
+
Exactly one of ``older_than`` and ``before``. ``confirm`` is required for the
|
|
301
|
+
destructive endpoint and ignored by the preview: an API that deletes a year
|
|
302
|
+
of history on a request a client sent by accident is an API with one field
|
|
303
|
+
missing.
|
|
304
|
+
"""
|
|
305
|
+
|
|
306
|
+
older_than: str | None = Field(
|
|
307
|
+
default=None,
|
|
308
|
+
description="A duration: 90d, 6m, 2w, 1y, 12h, or a bare number of days.",
|
|
309
|
+
)
|
|
310
|
+
before: AwareDatetime | None = Field(
|
|
311
|
+
default=None, description="An absolute cutoff. Runs at or before it are removed."
|
|
312
|
+
)
|
|
313
|
+
keep_min: int | None = Field(
|
|
314
|
+
default=None, ge=0, description="Runs kept per project. Defaults to the server setting."
|
|
315
|
+
)
|
|
316
|
+
project_keys: list[str] = Field(default_factory=list, description="Restrict to these projects.")
|
|
317
|
+
by_import_date: bool = Field(
|
|
318
|
+
default=False, description="Cut on when the run was imported, not when it ran."
|
|
319
|
+
)
|
|
320
|
+
include_unfinished: bool = Field(
|
|
321
|
+
default=False, description="Also remove queued and running runs past the cutoff."
|
|
322
|
+
)
|
|
323
|
+
confirm: bool = Field(default=False, description="Required by the destructive endpoint.")
|
|
324
|
+
|
|
325
|
+
|
|
326
|
+
class PruneResponse(_Response):
|
|
327
|
+
"""What a prune did, or — when ``dry_run`` — what it would do."""
|
|
328
|
+
|
|
329
|
+
dry_run: bool
|
|
330
|
+
cutoff: AwareDatetime
|
|
331
|
+
runs: int
|
|
332
|
+
rows: int
|
|
333
|
+
deleted: dict[str, int]
|
|
334
|
+
blobs_unlinked: int
|
|
335
|
+
blobs_retained: int
|
|
336
|
+
bytes_freed: int
|
|
337
|
+
skipped_live: int
|
|
338
|
+
protected: int
|
|
339
|
+
batches: int
|
|
340
|
+
vacuumed: bool = Field(
|
|
341
|
+
default=False,
|
|
342
|
+
description=(
|
|
343
|
+
"Always false over HTTP. VACUUM rewrites the whole database behind an "
|
|
344
|
+
"exclusive lock, which is not something a web request should start; run "
|
|
345
|
+
"`test-base prune --vacuum` on the host to reclaim the file space."
|
|
346
|
+
),
|
|
347
|
+
)
|
|
348
|
+
by_project: dict[str, int]
|
|
349
|
+
oldest: AwareDatetime | None = None
|
|
350
|
+
newest: AwareDatetime | None = None
|
|
351
|
+
|
|
352
|
+
|
|
353
|
+
# ------------------------------------------------------------------ triage
|
|
354
|
+
|
|
355
|
+
|
|
356
|
+
class TriageRequest(_Request):
|
|
357
|
+
"""``PATCH /api/v1/failures/{fingerprint}``.
|
|
358
|
+
|
|
359
|
+
Only the fields present change. ``null`` or an empty string clears
|
|
360
|
+
``owner``, ``issue_url`` and ``note``; ``status`` cannot be cleared, only
|
|
361
|
+
set — ``untriaged`` is how to take a verdict back.
|
|
362
|
+
"""
|
|
363
|
+
|
|
364
|
+
status: TriageStatus | None = None
|
|
365
|
+
owner: Annotated[str, Field(max_length=120)] | None = None
|
|
366
|
+
issue_url: Annotated[str, Field(max_length=2048)] | None = None
|
|
367
|
+
note: Annotated[str, Field(max_length=4000)] | None = None
|
|
368
|
+
|
|
369
|
+
@field_validator("status", mode="before")
|
|
370
|
+
@classmethod
|
|
371
|
+
def _settable(cls, value: object) -> object:
|
|
372
|
+
# Sent as null, it would be a verdict that changes nothing yet still
|
|
373
|
+
# stamps the group as triaged just now.
|
|
374
|
+
if value is None:
|
|
375
|
+
raise ValueError("status cannot be cleared; set it to untriaged instead")
|
|
376
|
+
return value
|
|
377
|
+
|
|
378
|
+
@field_validator("owner", "issue_url", "note", mode="before")
|
|
379
|
+
@classmethod
|
|
380
|
+
def _strip(cls, value: object) -> object:
|
|
381
|
+
return value.strip() if isinstance(value, str) else value
|
|
382
|
+
|
|
383
|
+
@field_validator("issue_url")
|
|
384
|
+
@classmethod
|
|
385
|
+
def _web_link(cls, value: str | None) -> str | None:
|
|
386
|
+
# A link the dashboard renders as an <a href>: only http(s), so a
|
|
387
|
+
# `javascript:` URL can never become one.
|
|
388
|
+
if value and not value.lower().startswith(("http://", "https://")):
|
|
389
|
+
raise ValueError("issue_url must be an http:// or https:// link")
|
|
390
|
+
return value or None
|
|
@@ -0,0 +1,183 @@
|
|
|
1
|
+
"""Bearer-token authentication, and the token hashing behind it.
|
|
2
|
+
|
|
3
|
+
Test Base stores **only hashes**. A stolen database gives an attacker a list of
|
|
4
|
+
PBKDF2 digests, not a list of working tokens. The plaintext exists exactly once,
|
|
5
|
+
in the terminal output of ``test-base token create``, and it is the operator's job
|
|
6
|
+
to put it somewhere safe from there.
|
|
7
|
+
|
|
8
|
+
Why PBKDF2 rather than a bare SHA-256 of a random token: the tokens *we* generate
|
|
9
|
+
carry 256 bits of entropy and a bare hash would be fine for them, but nothing
|
|
10
|
+
stops an operator setting ``TEST_BASE_API_TOKENS=letmein``. PBKDF2 makes that
|
|
11
|
+
mistake expensive to exploit instead of free. To keep the per-request cost off
|
|
12
|
+
the hot path, a successful verification is memoized for the life of the process,
|
|
13
|
+
keyed on a SHA-256 of the presented token — so the KDF runs once per distinct
|
|
14
|
+
token, not once per request.
|
|
15
|
+
|
|
16
|
+
Everything here is timing-safe: :func:`hmac.compare_digest` for the comparison,
|
|
17
|
+
and a uniform "invalid token" response whether the token was unknown, malformed
|
|
18
|
+
or simply absent.
|
|
19
|
+
"""
|
|
20
|
+
|
|
21
|
+
from __future__ import annotations
|
|
22
|
+
|
|
23
|
+
import hashlib
|
|
24
|
+
import hmac
|
|
25
|
+
import secrets
|
|
26
|
+
from dataclasses import dataclass, field
|
|
27
|
+
|
|
28
|
+
from test_base.errors import AuthenticationError, ConfigurationError
|
|
29
|
+
|
|
30
|
+
__all__ = [
|
|
31
|
+
"PBKDF2_ITERATIONS",
|
|
32
|
+
"TokenVerifier",
|
|
33
|
+
"generate_token",
|
|
34
|
+
"hash_token",
|
|
35
|
+
"parse_authorization",
|
|
36
|
+
"verify_token_hash",
|
|
37
|
+
]
|
|
38
|
+
|
|
39
|
+
PBKDF2_ITERATIONS = 120_000
|
|
40
|
+
_ALGORITHM = "sha256"
|
|
41
|
+
_SALT_BYTES = 16
|
|
42
|
+
_TOKEN_BYTES = 32
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
def generate_token() -> str:
|
|
46
|
+
"""A fresh API token: 256 bits, URL-safe, prefixed so it is greppable.
|
|
47
|
+
|
|
48
|
+
The ``ths_`` prefix means a leaked token can be found by secret scanners and
|
|
49
|
+
recognised in a log by a human, which is worth more than the four characters
|
|
50
|
+
it costs.
|
|
51
|
+
"""
|
|
52
|
+
return f"ths_{secrets.token_urlsafe(_TOKEN_BYTES)}"
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
def hash_token(
|
|
56
|
+
token: str, *, salt: bytes | None = None, iterations: int = PBKDF2_ITERATIONS
|
|
57
|
+
) -> str:
|
|
58
|
+
"""Hash a token into the storable ``pbkdf2_sha256$iterations$salt$hash`` form."""
|
|
59
|
+
if not token:
|
|
60
|
+
raise ConfigurationError("refusing to hash an empty token")
|
|
61
|
+
salt = salt or secrets.token_bytes(_SALT_BYTES)
|
|
62
|
+
digest = hashlib.pbkdf2_hmac(_ALGORITHM, token.encode("utf-8"), salt, iterations)
|
|
63
|
+
return f"pbkdf2_{_ALGORITHM}${iterations}${salt.hex()}${digest.hex()}"
|
|
64
|
+
|
|
65
|
+
|
|
66
|
+
def verify_token_hash(token: str, stored: str) -> bool:
|
|
67
|
+
"""Constant-time check of ``token`` against one stored hash.
|
|
68
|
+
|
|
69
|
+
Accepts the legacy ``sha256$salt$hash`` form as well, so an operator who
|
|
70
|
+
generated hashes with an older build is not locked out by an upgrade.
|
|
71
|
+
"""
|
|
72
|
+
if not token or not stored:
|
|
73
|
+
return False
|
|
74
|
+
parts = stored.split("$")
|
|
75
|
+
try:
|
|
76
|
+
if len(parts) == 4 and parts[0] == f"pbkdf2_{_ALGORITHM}":
|
|
77
|
+
iterations = int(parts[1])
|
|
78
|
+
salt = bytes.fromhex(parts[2])
|
|
79
|
+
expected = bytes.fromhex(parts[3])
|
|
80
|
+
actual = hashlib.pbkdf2_hmac(_ALGORITHM, token.encode("utf-8"), salt, iterations)
|
|
81
|
+
elif len(parts) == 3 and parts[0] == _ALGORITHM:
|
|
82
|
+
salt = bytes.fromhex(parts[1])
|
|
83
|
+
expected = bytes.fromhex(parts[2])
|
|
84
|
+
actual = hashlib.sha256(salt + token.encode("utf-8")).digest()
|
|
85
|
+
else:
|
|
86
|
+
return False
|
|
87
|
+
except (ValueError, TypeError):
|
|
88
|
+
return False
|
|
89
|
+
return hmac.compare_digest(actual, expected)
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
def parse_authorization(header: str | None) -> str | None:
|
|
93
|
+
"""Extract the token from an ``Authorization: Bearer …`` header.
|
|
94
|
+
|
|
95
|
+
Returns ``None`` for anything else — including ``Basic`` — rather than
|
|
96
|
+
raising, so the caller decides whether a missing credential is an error.
|
|
97
|
+
"""
|
|
98
|
+
if not header:
|
|
99
|
+
return None
|
|
100
|
+
scheme, _, value = header.partition(" ")
|
|
101
|
+
if scheme.lower() != "bearer":
|
|
102
|
+
return None
|
|
103
|
+
token = value.strip()
|
|
104
|
+
return token or None
|
|
105
|
+
|
|
106
|
+
|
|
107
|
+
@dataclass
|
|
108
|
+
class TokenVerifier:
|
|
109
|
+
"""Checks presented tokens against the configured hashes.
|
|
110
|
+
|
|
111
|
+
Built once at startup from :class:`~test_base.config.Settings`. Plaintext
|
|
112
|
+
tokens from configuration are hashed immediately and the plaintext is not
|
|
113
|
+
retained anywhere on the instance.
|
|
114
|
+
"""
|
|
115
|
+
|
|
116
|
+
hashes: list[str] = field(default_factory=list)
|
|
117
|
+
enabled: bool = True
|
|
118
|
+
_accepted: set[str] = field(default_factory=set, repr=False)
|
|
119
|
+
_rejected: set[str] = field(default_factory=set, repr=False)
|
|
120
|
+
|
|
121
|
+
@classmethod
|
|
122
|
+
def from_settings(cls, settings: object) -> TokenVerifier:
|
|
123
|
+
hashes = list(getattr(settings, "api_token_hashes", []) or [])
|
|
124
|
+
for plaintext in getattr(settings, "api_tokens", []) or []:
|
|
125
|
+
hashes.append(hash_token(plaintext))
|
|
126
|
+
return cls(hashes=hashes, enabled=bool(getattr(settings, "auth_enabled", False)))
|
|
127
|
+
|
|
128
|
+
@classmethod
|
|
129
|
+
def admin_from_settings(cls, settings: object) -> TokenVerifier:
|
|
130
|
+
"""The verifier for destructive maintenance.
|
|
131
|
+
|
|
132
|
+
Always ``enabled``, whatever ``auth_enabled`` says, and deliberately so:
|
|
133
|
+
this verifier answers "is this caller an administrator", which is not the
|
|
134
|
+
same question as "is authentication switched on". An instance with no
|
|
135
|
+
admin tokens configured therefore accepts no admin token at all, and
|
|
136
|
+
:func:`test_base.api.deps.require_admin` is the only thing that decides
|
|
137
|
+
whether an unauthenticated loopback caller may proceed without one.
|
|
138
|
+
"""
|
|
139
|
+
hashes = list(getattr(settings, "admin_token_hashes", []) or [])
|
|
140
|
+
for plaintext in getattr(settings, "admin_tokens", []) or []:
|
|
141
|
+
hashes.append(hash_token(plaintext))
|
|
142
|
+
return cls(hashes=hashes, enabled=True)
|
|
143
|
+
|
|
144
|
+
def __bool__(self) -> bool:
|
|
145
|
+
return bool(self.hashes)
|
|
146
|
+
|
|
147
|
+
def verify(self, token: str | None) -> bool:
|
|
148
|
+
"""True when ``token`` matches one configured hash."""
|
|
149
|
+
if not self.enabled:
|
|
150
|
+
return True
|
|
151
|
+
if not token:
|
|
152
|
+
return False
|
|
153
|
+
fingerprint = hashlib.sha256(token.encode("utf-8")).hexdigest()
|
|
154
|
+
if fingerprint in self._accepted:
|
|
155
|
+
return True
|
|
156
|
+
if fingerprint in self._rejected:
|
|
157
|
+
return False
|
|
158
|
+
for stored in self.hashes:
|
|
159
|
+
if verify_token_hash(token, stored):
|
|
160
|
+
self._accepted.add(fingerprint)
|
|
161
|
+
return True
|
|
162
|
+
# Bounded, so a flood of bad tokens cannot grow the process without limit.
|
|
163
|
+
if len(self._rejected) < 4096:
|
|
164
|
+
self._rejected.add(fingerprint)
|
|
165
|
+
return False
|
|
166
|
+
|
|
167
|
+
def require(self, header: str | None) -> None:
|
|
168
|
+
"""Raise :class:`AuthenticationError` unless the header carries a valid token.
|
|
169
|
+
|
|
170
|
+
The message is identical for a missing, malformed and wrong token: telling
|
|
171
|
+
a caller *which* of those it was is free information for an attacker.
|
|
172
|
+
"""
|
|
173
|
+
if not self.enabled:
|
|
174
|
+
return
|
|
175
|
+
if not self.hashes:
|
|
176
|
+
raise ConfigurationError(
|
|
177
|
+
"authentication is enabled but no tokens are configured; "
|
|
178
|
+
"create one with `test-base token create`"
|
|
179
|
+
)
|
|
180
|
+
if not self.verify(parse_authorization(header)):
|
|
181
|
+
raise AuthenticationError(
|
|
182
|
+
"a valid bearer token is required; send it as `Authorization: Bearer <token>`"
|
|
183
|
+
)
|
|
@@ -0,0 +1,125 @@
|
|
|
1
|
+
"""The ``test-base`` command line.
|
|
2
|
+
|
|
3
|
+
Each command is a thin wrapper over the service layer — nothing here contains
|
|
4
|
+
business logic::
|
|
5
|
+
|
|
6
|
+
test-base init choose SQLite or PostgreSQL, check it, and save the choice
|
|
7
|
+
test-base serve start the API and the dashboard
|
|
8
|
+
test-base ingest import a report into the local store
|
|
9
|
+
test-base publish send a report to a remote Test Base
|
|
10
|
+
test-base demo fill the store with realistic sample data
|
|
11
|
+
test-base prune delete runs older than a retention cutoff
|
|
12
|
+
test-base db check the configured database and migrate it
|
|
13
|
+
test-base token create and hash API tokens
|
|
14
|
+
test-base formats list the installed report adapters
|
|
15
|
+
|
|
16
|
+
Everything here is also reachable over HTTP and from Python, with one deliberate
|
|
17
|
+
exception: ``prune`` is the terminal only. Authentication has two scopes, and the
|
|
18
|
+
write one is what every CI publisher token holds, so a prune endpoint behind it
|
|
19
|
+
would let a token that lives in a repository's CI settings delete a year of
|
|
20
|
+
history (ADR-0002 D8).
|
|
21
|
+
|
|
22
|
+
One rule shows up everywhere: **tokens are never taken as arguments.** A token on
|
|
23
|
+
a command line lands in shell history, in ``ps`` output for every user on the
|
|
24
|
+
box, and in the CI log if the step is echoed. ``--token-env`` and ``--token-file``
|
|
25
|
+
are the supported ways in.
|
|
26
|
+
"""
|
|
27
|
+
|
|
28
|
+
from __future__ import annotations
|
|
29
|
+
|
|
30
|
+
import sys
|
|
31
|
+
from typing import Annotated
|
|
32
|
+
|
|
33
|
+
import typer
|
|
34
|
+
|
|
35
|
+
from test_base.errors import TestBaseError
|
|
36
|
+
from test_base.version import SCHEMA_VERSION, __version__
|
|
37
|
+
|
|
38
|
+
__all__ = ["app", "main"]
|
|
39
|
+
|
|
40
|
+
app = typer.Typer(
|
|
41
|
+
name="test-base",
|
|
42
|
+
help="One live dashboard for every test run — any team, any framework, any CI.",
|
|
43
|
+
no_args_is_help=True,
|
|
44
|
+
add_completion=True,
|
|
45
|
+
rich_markup_mode="rich",
|
|
46
|
+
context_settings={"help_option_names": ["-h", "--help"]},
|
|
47
|
+
)
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
def _version_callback(value: bool) -> None:
|
|
51
|
+
if value:
|
|
52
|
+
typer.echo(f"test-base {__version__} (canonical schema v{SCHEMA_VERSION})")
|
|
53
|
+
raise typer.Exit
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
@app.callback()
|
|
57
|
+
def _root(
|
|
58
|
+
version: Annotated[
|
|
59
|
+
bool,
|
|
60
|
+
typer.Option(
|
|
61
|
+
"--version",
|
|
62
|
+
"-V",
|
|
63
|
+
callback=_version_callback,
|
|
64
|
+
is_eager=True,
|
|
65
|
+
help="Show the version and exit.",
|
|
66
|
+
),
|
|
67
|
+
] = False,
|
|
68
|
+
) -> None:
|
|
69
|
+
"""Test Base."""
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
def _register() -> None:
|
|
73
|
+
"""Attach the sub-commands.
|
|
74
|
+
|
|
75
|
+
Imported lazily and inside a function so that ``test-base --help`` does not
|
|
76
|
+
pay for importing FastAPI, SQLAlchemy and every adapter. On a cold cache that
|
|
77
|
+
is the difference between a command that feels instant and one that does not.
|
|
78
|
+
"""
|
|
79
|
+
from test_base.cli.commands import (
|
|
80
|
+
db,
|
|
81
|
+
demo,
|
|
82
|
+
formats,
|
|
83
|
+
ingest,
|
|
84
|
+
prune,
|
|
85
|
+
publish,
|
|
86
|
+
serve,
|
|
87
|
+
token,
|
|
88
|
+
)
|
|
89
|
+
from test_base.cli.commands import init as setup
|
|
90
|
+
|
|
91
|
+
app.command(
|
|
92
|
+
"init", help="Set up Test Base: choose SQLite or PostgreSQL, check it, save the choice."
|
|
93
|
+
)(setup.init)
|
|
94
|
+
app.command("serve", help="Start the API and serve the dashboard.")(serve.serve)
|
|
95
|
+
app.command("ingest", help="Import a report file into the local store.")(ingest.ingest)
|
|
96
|
+
app.command("publish", help="Send a report to a remote Test Base server.")(publish.publish)
|
|
97
|
+
app.command("demo", help="Populate the store with realistic sample data.")(demo.demo)
|
|
98
|
+
app.command("prune", help="Delete runs older than a retention cutoff.")(prune.prune)
|
|
99
|
+
app.command("formats", help="List the installed report adapters.")(formats.formats)
|
|
100
|
+
app.add_typer(token.app, name="token", help="Create and hash API tokens.")
|
|
101
|
+
app.add_typer(db.app, name="db", help="Check the configured database and migrate it.")
|
|
102
|
+
|
|
103
|
+
|
|
104
|
+
def main() -> None:
|
|
105
|
+
"""Console-script entry point.
|
|
106
|
+
|
|
107
|
+
Catches :class:`~test_base.errors.TestBaseError` and turns it into a clean
|
|
108
|
+
message plus that error's own exit code, so a CI step can branch on *why* it
|
|
109
|
+
failed rather than only on the fact that it did.
|
|
110
|
+
"""
|
|
111
|
+
_register()
|
|
112
|
+
try:
|
|
113
|
+
app()
|
|
114
|
+
except TestBaseError as exc:
|
|
115
|
+
typer.secho(f"error: {exc.message}", fg=typer.colors.RED, err=True)
|
|
116
|
+
for key, value in exc.detail.items():
|
|
117
|
+
typer.secho(f" {key}: {value}", fg=typer.colors.BRIGHT_BLACK, err=True)
|
|
118
|
+
raise SystemExit(exc.exit_code) from exc
|
|
119
|
+
except KeyboardInterrupt: # pragma: no cover - interactive
|
|
120
|
+
typer.secho("interrupted", fg=typer.colors.YELLOW, err=True)
|
|
121
|
+
raise SystemExit(130) from None
|
|
122
|
+
|
|
123
|
+
|
|
124
|
+
if __name__ == "__main__": # pragma: no cover
|
|
125
|
+
sys.exit(main()) # type: ignore[func-returns-value]
|
|
File without changes
|