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.
Files changed (103) hide show
  1. test_base/__init__.py +20 -0
  2. test_base/adapters/__init__.py +354 -0
  3. test_base/adapters/base.py +263 -0
  4. test_base/adapters/canonical_json.py +1088 -0
  5. test_base/adapters/junit_xml.py +1272 -0
  6. test_base/api/__init__.py +0 -0
  7. test_base/api/app.py +314 -0
  8. test_base/api/deps.py +178 -0
  9. test_base/api/routes/__init__.py +0 -0
  10. test_base/api/routes/failures.py +104 -0
  11. test_base/api/routes/health.py +35 -0
  12. test_base/api/routes/imports.py +143 -0
  13. test_base/api/routes/queries.py +295 -0
  14. test_base/api/routes/retention.py +130 -0
  15. test_base/api/routes/runs.py +147 -0
  16. test_base/api/routes/server.py +65 -0
  17. test_base/api/routes/stream.py +117 -0
  18. test_base/api/schemas.py +390 -0
  19. test_base/api/security.py +183 -0
  20. test_base/cli/__init__.py +125 -0
  21. test_base/cli/commands/__init__.py +0 -0
  22. test_base/cli/commands/db.py +76 -0
  23. test_base/cli/commands/demo.py +103 -0
  24. test_base/cli/commands/formats.py +41 -0
  25. test_base/cli/commands/ingest.py +119 -0
  26. test_base/cli/commands/init.py +738 -0
  27. test_base/cli/commands/prune.py +146 -0
  28. test_base/cli/commands/publish.py +133 -0
  29. test_base/cli/commands/serve.py +118 -0
  30. test_base/cli/commands/token.py +97 -0
  31. test_base/cli/options.py +189 -0
  32. test_base/cli/render.py +223 -0
  33. test_base/config.py +519 -0
  34. test_base/demo/__init__.py +0 -0
  35. test_base/demo/evidence.py +447 -0
  36. test_base/demo/seed.py +628 -0
  37. test_base/domain/__init__.py +61 -0
  38. test_base/domain/events.py +422 -0
  39. test_base/domain/failures.py +327 -0
  40. test_base/domain/identity.py +205 -0
  41. test_base/domain/metrics.py +176 -0
  42. test_base/domain/models.py +947 -0
  43. test_base/domain/status.py +246 -0
  44. test_base/errors.py +136 -0
  45. test_base/logging.py +174 -0
  46. test_base/py.typed +0 -0
  47. test_base/sdk/__init__.py +28 -0
  48. test_base/sdk/client.py +607 -0
  49. test_base/service/__init__.py +0 -0
  50. test_base/service/bus.py +331 -0
  51. test_base/service/coalesce.py +133 -0
  52. test_base/service/imports.py +552 -0
  53. test_base/service/retention.py +640 -0
  54. test_base/service/runs.py +394 -0
  55. test_base/service/runtime.py +123 -0
  56. test_base/storage/__init__.py +41 -0
  57. test_base/storage/artifacts.py +347 -0
  58. test_base/storage/base.py +350 -0
  59. test_base/storage/db.py +595 -0
  60. test_base/storage/failures.py +321 -0
  61. test_base/storage/locks.py +104 -0
  62. test_base/storage/migrations/env.py +108 -0
  63. test_base/storage/migrations/script.py.mako +26 -0
  64. test_base/storage/migrations/versions/0001_initial.py +289 -0
  65. test_base/storage/migrations/versions/0002_retention_indexes.py +38 -0
  66. test_base/storage/migrations/versions/0003_postgresql_bigint.py +74 -0
  67. test_base/storage/migrations/versions/0004_run_shards.py +37 -0
  68. test_base/storage/migrations/versions/0005_failure_groups.py +206 -0
  69. test_base/storage/models.py +560 -0
  70. test_base/storage/repositories.py +2481 -0
  71. test_base/storage/uow.py +138 -0
  72. test_base/version.py +17 -0
  73. test_base/web/assets/css/app.css +3567 -0
  74. test_base/web/assets/favicon.svg +5 -0
  75. test_base/web/assets/js/00-util.js +829 -0
  76. test_base/web/assets/js/05-windows.js +551 -0
  77. test_base/web/assets/js/10-provider.js +396 -0
  78. test_base/web/assets/js/12-live-provider.js +804 -0
  79. test_base/web/assets/js/20-charts.js +715 -0
  80. test_base/web/assets/js/30-store.js +793 -0
  81. test_base/web/assets/js/40-components.js +2141 -0
  82. test_base/web/assets/js/42-timeline.js +629 -0
  83. test_base/web/assets/js/50-view-overview.js +747 -0
  84. test_base/web/assets/js/52-view-analytics.js +842 -0
  85. test_base/web/assets/js/53-view-suites.js +508 -0
  86. test_base/web/assets/js/54-view-metrics.js +438 -0
  87. test_base/web/assets/js/55-view-runs.js +244 -0
  88. test_base/web/assets/js/56-view-evidence.js +703 -0
  89. test_base/web/assets/js/57-view-failures.js +596 -0
  90. test_base/web/assets/js/60-view-run.js +788 -0
  91. test_base/web/assets/js/65-view-test.js +402 -0
  92. test_base/web/assets/js/70-view-settings.js +524 -0
  93. test_base/web/assets/js/75-view-help.js +554 -0
  94. test_base/web/assets/js/80-settings.js +99 -0
  95. test_base/web/assets/js/85-activity.js +727 -0
  96. test_base/web/assets/js/90-app.js +595 -0
  97. test_base/web/assets/manifest.json +70 -0
  98. test_base/web/index.html +210 -0
  99. test_base-0.1.1.dist-info/METADATA +285 -0
  100. test_base-0.1.1.dist-info/RECORD +103 -0
  101. test_base-0.1.1.dist-info/WHEEL +4 -0
  102. test_base-0.1.1.dist-info/entry_points.txt +6 -0
  103. test_base-0.1.1.dist-info/licenses/LICENSE +201 -0
@@ -0,0 +1,143 @@
1
+ """``POST /api/v1/imports`` — upload a report file.
2
+
3
+ The endpoint every CI system can use without a client library:
4
+
5
+ .. code-block:: shell
6
+
7
+ curl -X POST http://localhost:8000/api/v1/imports \\
8
+ -H "Authorization: Bearer $TEST_BASE_TOKEN" \\
9
+ -F "file=@results.xml" \\
10
+ -F "project=payments-api" \\
11
+ -F "team=payments" \\
12
+ -F "type=component"
13
+
14
+ Repeat ``file`` to send several reports into one run in one request — all of
15
+ them land, or none do. ``shard=2/4`` marks the upload as one slice of a sharded
16
+ run, and ``run_key`` names the CI run so every shard arrives at the same run id
17
+ without being handed one::
18
+
19
+ curl … -F "file=@unit.xml" -F "file=@integration.xml" \\
20
+ -F "project=payments-api" -F "run_key=$GITHUB_RUN_ID" -F "shard=2/4"
21
+
22
+ Multipart rather than a JSON body because that is what ``curl -F``, ``requests``,
23
+ ``HttpClient`` and every CI plugin already know how to send, and because it lets
24
+ the file stream instead of being base64'd into a JSON string.
25
+ """
26
+
27
+ from __future__ import annotations
28
+
29
+ import uuid
30
+ from typing import Annotated
31
+
32
+ from fastapi import APIRouter, Depends, File, Form, Header, UploadFile
33
+
34
+ from test_base.api.deps import Imports, require_write
35
+ from test_base.api.schemas import AdapterInfo, AdapterListResponse
36
+ from test_base.domain.models import ImportResult, RunContext, ShardRef, TestType, TriggerType
37
+ from test_base.errors import ValidationError
38
+ from test_base.service.imports import ImportRequest, ImportUpload
39
+
40
+ router = APIRouter(tags=["ingestion"])
41
+
42
+
43
+ @router.post(
44
+ "/imports",
45
+ response_model=ImportResult,
46
+ status_code=201,
47
+ summary="Import a test report file",
48
+ dependencies=[Depends(require_write)],
49
+ responses={
50
+ 413: {
51
+ "description": "A file is larger than TEST_BASE_MAX_REPORT_BYTES, or there are more "
52
+ "than TEST_BASE_MAX_IMPORT_FILES files."
53
+ },
54
+ 415: {"description": "No installed adapter recognised the format."},
55
+ 422: {"description": "The format was recognised but the file could not be parsed."},
56
+ },
57
+ )
58
+ def create_import(
59
+ service: Imports,
60
+ file: Annotated[
61
+ list[UploadFile],
62
+ File(description="The report file. Repeat the field to import several into one run."),
63
+ ],
64
+ project: Annotated[str, Form(description="Project key, e.g. payments-api.")],
65
+ team: Annotated[str | None, Form()] = None,
66
+ component: Annotated[str | None, Form()] = None,
67
+ type: Annotated[TestType, Form(description="Test type.")] = TestType.OTHER,
68
+ trigger: Annotated[TriggerType, Form()] = TriggerType.UNKNOWN,
69
+ name: Annotated[str | None, Form()] = None,
70
+ environment: Annotated[str | None, Form()] = None,
71
+ branch: Annotated[str | None, Form()] = None,
72
+ commit: Annotated[str | None, Form()] = None,
73
+ framework: Annotated[str | None, Form()] = None,
74
+ language: Annotated[str | None, Form()] = None,
75
+ pipeline_id: Annotated[str | None, Form()] = None,
76
+ pipeline_url: Annotated[str | None, Form()] = None,
77
+ ci_provider: Annotated[str | None, Form()] = None,
78
+ tags: Annotated[str | None, Form(description="Comma-separated tags.")] = None,
79
+ run_id: Annotated[uuid.UUID | None, Form(description="Reuse an existing run id.")] = None,
80
+ run_key: Annotated[
81
+ str | None,
82
+ Form(
83
+ description="Name of the CI run, e.g. $GITHUB_RUN_ID, instead of run_id: every "
84
+ "upload with the same key and project lands in the same run."
85
+ ),
86
+ ] = None,
87
+ shard: Annotated[
88
+ str | None,
89
+ Form(description="This upload's slice of a sharded run, as INDEX/TOTAL, e.g. 2/4."),
90
+ ] = None,
91
+ format: Annotated[str | None, Form(description="Force an adapter by name.")] = None,
92
+ x_idempotency_key: Annotated[str | None, Header()] = None,
93
+ ) -> ImportResult:
94
+ try:
95
+ shard_ref = ShardRef.parse(shard) if shard else None
96
+ except ValueError as exc:
97
+ raise ValidationError(str(exc), detail={"shard": shard}) from exc
98
+ request = ImportRequest(
99
+ project_key=project,
100
+ run_id=run_id,
101
+ name=name,
102
+ team=team,
103
+ component=component,
104
+ test_type=type,
105
+ trigger=trigger,
106
+ context=RunContext(
107
+ environment=environment,
108
+ branch=branch,
109
+ commit_sha=commit,
110
+ framework=framework,
111
+ language=language,
112
+ pipeline_id=pipeline_id,
113
+ pipeline_url=pipeline_url,
114
+ ci_provider=ci_provider,
115
+ ),
116
+ tags=[tag.strip() for tag in (tags or "").split(",") if tag.strip()],
117
+ explicit_format=format,
118
+ source="urn:test-base:api-import",
119
+ idempotency_key=x_idempotency_key,
120
+ run_key=run_key,
121
+ shard=shard_ref,
122
+ )
123
+ uploads = [
124
+ ImportUpload(item.file, filename=item.filename, content_type=item.content_type)
125
+ for item in file
126
+ ]
127
+ return service.import_files(uploads, request)
128
+
129
+
130
+ @router.get(
131
+ "/adapters",
132
+ response_model=AdapterListResponse,
133
+ summary="List the installed report adapters",
134
+ )
135
+ def list_adapters() -> AdapterListResponse:
136
+ """What this server can parse.
137
+
138
+ Worth calling before an import fails: the same list appears in the body of a
139
+ 415, but a publisher can check it up front.
140
+ """
141
+ from test_base.adapters import get_registry
142
+
143
+ return AdapterListResponse(adapters=[AdapterInfo(**row) for row in get_registry().describe()])
@@ -0,0 +1,295 @@
1
+ """Read endpoints — what the dashboard, and anyone with `curl`, asks for.
2
+
3
+ Two altitudes, kept apart on purpose (it is a product requirement, not an
4
+ implementation detail): ``/overview`` answers "how is the portfolio doing" and is
5
+ cheap enough to poll, while ``/runs/{id}`` and ``/tests/{id}`` are the
6
+ engineering drill-down and are allowed to return a lot.
7
+
8
+ Filters are shared across ``/overview`` and ``/runs`` and mean the same thing in
9
+ both, so a dashboard can carry the user's filter selection from one view to the
10
+ other without translating it.
11
+ """
12
+
13
+ from __future__ import annotations
14
+
15
+ import uuid
16
+ from datetime import UTC, timedelta
17
+ from typing import Annotated
18
+
19
+ from fastapi import APIRouter, Depends, Query
20
+ from fastapi.responses import Response, StreamingResponse
21
+ from pydantic import AwareDatetime
22
+
23
+ from test_base.api.deps import Context, require_read
24
+ from test_base.api.schemas import ArtifactListResponse, ProjectListResponse, RunListResponse
25
+ from test_base.domain.models import OverviewSnapshot, RunDetail, TestDetail, utcnow
26
+ from test_base.domain.status import RunStatus
27
+ from test_base.errors import NotFoundError, ValidationError
28
+ from test_base.storage.base import OverviewWindow, RunFilter
29
+
30
+ router = APIRouter(tags=["query"], dependencies=[Depends(require_read)])
31
+
32
+ # Every handler below opens its unit of work with ``read_only=True``. On SQLite
33
+ # that is the difference between a query queueing behind a publisher and running
34
+ # alongside it: a writing transaction takes the write lock up front (see
35
+ # storage/db.py), and a dashboard polling the overview would otherwise contend
36
+ # with every import.
37
+
38
+ _CSV = "Repeat the parameter or pass a comma-separated list."
39
+
40
+
41
+ def _split(values: list[str] | None) -> list[str]:
42
+ """Accept both ``?team=a&team=b`` and ``?team=a,b``."""
43
+ out: list[str] = []
44
+ for value in values or []:
45
+ out.extend(part.strip() for part in value.split(",") if part.strip())
46
+ return out
47
+
48
+
49
+ def build_filter(
50
+ context: Context,
51
+ project: Annotated[list[str] | None, Query(description=_CSV)] = None,
52
+ team: Annotated[list[str] | None, Query(description=_CSV)] = None,
53
+ component: Annotated[list[str] | None, Query(description=_CSV)] = None,
54
+ test_type: Annotated[list[str] | None, Query(alias="type", description=_CSV)] = None,
55
+ environment: Annotated[list[str] | None, Query(description=_CSV)] = None,
56
+ branch: Annotated[list[str] | None, Query(description=_CSV)] = None,
57
+ status: Annotated[list[RunStatus] | None, Query(description=_CSV)] = None,
58
+ tag: Annotated[list[str] | None, Query(description=_CSV)] = None,
59
+ search: Annotated[str | None, Query(max_length=200)] = None,
60
+ live: Annotated[bool, Query(description="Only runs that are queued or running.")] = False,
61
+ # Aware only: a timestamp with no offset would be read as UTC, and a caller
62
+ # writing local time would get a window hours away from the one they meant
63
+ # without any sign of it. A 422 that says so is the kinder answer.
64
+ since: Annotated[
65
+ AwareDatetime | None,
66
+ Query(description="Runs that started at or after this instant. ISO 8601 with an offset."),
67
+ ] = None,
68
+ until: Annotated[
69
+ AwareDatetime | None,
70
+ Query(description="Runs that started at or before this instant. ISO 8601 with an offset."),
71
+ ] = None,
72
+ limit: Annotated[int, Query(ge=1, le=500)] = 50,
73
+ offset: Annotated[int, Query(ge=0)] = 0,
74
+ ) -> RunFilter:
75
+ """Every facet the dashboard exposes, in one dependency."""
76
+ return RunFilter(
77
+ workspace_id=context.workspace_id,
78
+ project_keys=_split(project),
79
+ teams=_split(team),
80
+ components=_split(component),
81
+ test_types=_split(test_type),
82
+ environments=_split(environment),
83
+ branches=_split(branch),
84
+ statuses=tuple(status or ()),
85
+ tags=_split(tag),
86
+ search=search,
87
+ since=since,
88
+ until=until,
89
+ live_only=live,
90
+ limit=limit,
91
+ offset=offset,
92
+ )
93
+
94
+
95
+ Filter = Annotated[RunFilter, Depends(build_filter)]
96
+
97
+
98
+ #: The longest window an overview answers for, however it is asked for. The
99
+ #: trend's buckets widen rather than multiply, but every run in the window is
100
+ #: still read to fold its counts, and this endpoint has to stay cheap to poll.
101
+ MAX_OVERVIEW_WINDOW = timedelta(days=366)
102
+
103
+ _WINDOW_DAYS = "The window's length in days, ending now: 1 to 365. The default is 30."
104
+ _WINDOW_HOURS = (
105
+ "The window's length in hours, ending now — for windows shorter than a day, or not a "
106
+ "whole number of days. One of `window_days` and `window_hours`, not both."
107
+ )
108
+ _SINCE = (
109
+ "Where a fixed window starts. ISO 8601 with an offset. Without `until`, the window "
110
+ "runs to now and keeps growing; it cannot also have a length."
111
+ )
112
+ _UNTIL = (
113
+ "Where the window ends. ISO 8601 with an offset. With `since`, a fixed range; alone, "
114
+ "the `window_days` or `window_hours` before it."
115
+ )
116
+
117
+
118
+ def overview_window(
119
+ window_days: int | None,
120
+ window_hours: int | None,
121
+ since: AwareDatetime | None,
122
+ until: AwareDatetime | None,
123
+ ) -> OverviewWindow:
124
+ """The window a request asked for, or a 422 that says why it cannot be one."""
125
+ if window_days is not None and window_hours is not None:
126
+ raise ValidationError("pass window_days or window_hours, not both")
127
+ if since is not None and (window_days is not None or window_hours is not None):
128
+ raise ValidationError(
129
+ "since fixes where the window starts, so it cannot also have a length: pass "
130
+ "since and until for a fixed range, or a length on its own"
131
+ )
132
+ if window_hours is not None:
133
+ length = timedelta(hours=window_hours)
134
+ else:
135
+ length = timedelta(days=window_days if window_days is not None else 30)
136
+ start = since.astimezone(UTC) if since is not None else None
137
+ end = until.astimezone(UTC) if until is not None else None
138
+ if start is not None:
139
+ if start >= (end if end is not None else utcnow()):
140
+ raise ValidationError(
141
+ "since must be before until" if end is not None else "since is in the future"
142
+ )
143
+ if (end if end is not None else utcnow()) - start > MAX_OVERVIEW_WINDOW:
144
+ raise ValidationError("an overview window can be at most 366 days long")
145
+ if length > MAX_OVERVIEW_WINDOW:
146
+ raise ValidationError("an overview window can be at most 366 days long")
147
+ return OverviewWindow(length=length, since=start, until=end)
148
+
149
+
150
+ @router.get("/overview", response_model=OverviewSnapshot, summary="Portfolio overview")
151
+ def get_overview(
152
+ context: Context,
153
+ window_days: Annotated[int | None, Query(ge=1, le=365, description=_WINDOW_DAYS)] = None,
154
+ window_hours: Annotated[int | None, Query(ge=1, le=8784, description=_WINDOW_HOURS)] = None,
155
+ since: Annotated[AwareDatetime | None, Query(description=_SINCE)] = None,
156
+ until: Annotated[AwareDatetime | None, Query(description=_UNTIL)] = None,
157
+ after: Annotated[
158
+ int | None,
159
+ Query(
160
+ ge=0,
161
+ description="The cursor (SSE `id:`) of the newest change the caller has seen. The "
162
+ "answer includes it and every change before it — and may be shared with other "
163
+ "callers asking for the same. Without it, the answer is as new as the request.",
164
+ ),
165
+ ] = None,
166
+ ) -> OverviewSnapshot:
167
+ """Totals, trends, project health, live runs and the worst offenders."""
168
+ window = overview_window(window_days, window_hours, since, until)
169
+
170
+ def compute() -> OverviewSnapshot:
171
+ with context.uow_factory(read_only=True) as uow:
172
+ return uow.runs.overview(context.workspace_id, window=window)
173
+
174
+ # Every open dashboard asks for this the moment a result lands. Computed
175
+ # per request, a burst of results piled requests up faster than they
176
+ # finished until no worker thread or connection was free; shared, it is
177
+ # one computation per change however many dashboards are watching.
178
+ current = context.bus.latest_cursor(context.workspace_id)
179
+ return context.overviews.get(
180
+ window,
181
+ need=current if after is None else after,
182
+ current=current,
183
+ compute=compute,
184
+ # Only a caller on the event stream says `after`, and only such a
185
+ # caller is told — and asks again — when a newer answer exists.
186
+ reuse_finished=after is not None,
187
+ )
188
+
189
+
190
+ @router.get("/projects", response_model=ProjectListResponse, summary="List projects")
191
+ def list_projects(context: Context) -> ProjectListResponse:
192
+ with context.uow_factory(read_only=True) as uow:
193
+ return ProjectListResponse(projects=uow.runs.list_projects(context.workspace_id))
194
+
195
+
196
+ @router.get("/facets", summary="Distinct values available for each filter")
197
+ def get_facets(context: Context) -> dict[str, list[str]]:
198
+ """What is worth offering in a filter dropdown, for this workspace."""
199
+ with context.uow_factory(read_only=True) as uow:
200
+ return uow.runs.facets(context.workspace_id)
201
+
202
+
203
+ @router.get("/runs", response_model=RunListResponse, summary="List runs")
204
+ def list_runs(context: Context, run_filter: Filter) -> RunListResponse:
205
+ with context.uow_factory(read_only=True) as uow:
206
+ runs = uow.runs.list_runs(run_filter)
207
+ total = uow.runs.count_runs(run_filter)
208
+ return RunListResponse(runs=runs, total=total, limit=run_filter.limit, offset=run_filter.offset)
209
+
210
+
211
+ @router.get(
212
+ "/runs/{run_id}",
213
+ response_model=RunDetail,
214
+ summary="One run, with its suites, tests, attempts and comparison",
215
+ responses={404: {"description": "No such run."}},
216
+ )
217
+ def get_run(
218
+ context: Context,
219
+ run_id: uuid.UUID,
220
+ compare: Annotated[bool, Query(description="Include the previous-run comparison.")] = True,
221
+ ) -> RunDetail:
222
+ with context.uow_factory(read_only=True) as uow:
223
+ detail = uow.runs.get_run_detail(run_id, comparison=compare)
224
+ if detail is None:
225
+ raise NotFoundError(f"run {run_id} does not exist")
226
+ return detail
227
+
228
+
229
+ @router.get(
230
+ "/tests/{test_id}",
231
+ response_model=TestDetail,
232
+ summary="One test identity, with its history across runs",
233
+ responses={404: {"description": "No such test."}},
234
+ )
235
+ def get_test(
236
+ context: Context,
237
+ test_id: uuid.UUID,
238
+ history: Annotated[int, Query(ge=1, le=200)] = 30,
239
+ ) -> TestDetail:
240
+ with context.uow_factory(read_only=True) as uow:
241
+ detail = uow.runs.get_test_detail(
242
+ test_id, workspace_id=context.workspace_id, history=history
243
+ )
244
+ if detail is None:
245
+ raise NotFoundError(f"test {test_id} has no recorded results")
246
+ return detail
247
+
248
+
249
+ @router.get(
250
+ "/runs/{run_id}/artifacts",
251
+ response_model=ArtifactListResponse,
252
+ summary="Files attached to a run",
253
+ )
254
+ def list_artifacts(context: Context, run_id: uuid.UUID) -> ArtifactListResponse:
255
+ with context.uow_factory(read_only=True) as uow:
256
+ return ArtifactListResponse(artifacts=uow.artifacts.list_for_run(run_id))
257
+
258
+
259
+ @router.get(
260
+ "/artifacts/{artifact_id}",
261
+ summary="Download one artifact",
262
+ response_class=Response,
263
+ responses={404: {"description": "No such artifact."}},
264
+ )
265
+ def download_artifact(context: Context, artifact_id: uuid.UUID) -> StreamingResponse:
266
+ """Stream an artifact back.
267
+
268
+ Always ``Content-Disposition: attachment`` and always the stored content
269
+ type — never a type sniffed from the bytes. An artifact is attacker-supplied
270
+ content on our origin; serving it inline would hand an uploader a stored XSS
271
+ on the dashboard's own domain.
272
+ """
273
+ with context.uow_factory(read_only=True) as uow:
274
+ artifact = uow.artifacts.get(artifact_id)
275
+ if artifact is None:
276
+ raise NotFoundError(f"artifact {artifact_id} does not exist")
277
+ handle = uow.artifacts.open(artifact.sha256)
278
+
279
+ def stream() -> object:
280
+ try:
281
+ while chunk := handle.read(64 * 1024):
282
+ yield chunk
283
+ finally:
284
+ handle.close()
285
+
286
+ quoted = artifact.name.replace('"', "")
287
+ return StreamingResponse(
288
+ stream(), # type: ignore[arg-type]
289
+ media_type=artifact.content_type,
290
+ headers={
291
+ "content-disposition": f'attachment; filename="{quoted}"',
292
+ "content-length": str(artifact.size_bytes),
293
+ "x-content-type-options": "nosniff",
294
+ },
295
+ )
@@ -0,0 +1,130 @@
1
+ """Retention — reading the policy, previewing a prune, and running one.
2
+
3
+ This is the one destructive surface in the API, and the only one behind a third
4
+ scope. The reasoning, in short: authentication has a read scope and a write
5
+ scope, and the write token is the one that lives in every repository's CI
6
+ settings, gets copied between projects and is the most likely to leak. A prune
7
+ behind ``require_write`` would mean any credential that can post a test result
8
+ can also delete a year of them, so retention gets its own token
9
+ (:func:`test_base.api.deps.require_admin`, ADR-0002 D8).
10
+
11
+ An unauthenticated *loopback* instance is admin by default, because anyone who
12
+ can reach that port can already run ``test-base prune`` in a terminal and
13
+ pretending otherwise would only make the dashboard lie about what it can do. An
14
+ instance bound to a public interface with ``--insecure-no-auth`` is not: open
15
+ writes are a choice an operator makes knowingly, and open *deletes* deserve to be
16
+ a second, separate one.
17
+
18
+ Both endpoints run the same :class:`~test_base.service.retention.RetentionService`
19
+ the CLI runs, so there is one implementation of what a prune means. They are
20
+ ``def`` rather than ``async def`` — the prune is synchronous SQLite work in
21
+ committed batches, and running it on the event loop would freeze every SSE
22
+ stream the dashboard is holding open.
23
+ """
24
+
25
+ from __future__ import annotations
26
+
27
+ from typing import Annotated
28
+
29
+ from fastapi import APIRouter, Depends, Header, Request
30
+
31
+ from test_base.api.deps import Context, is_admin, require_admin, require_read
32
+ from test_base.api.schemas import PruneRequest, PruneResponse, RetentionSettingsResponse
33
+ from test_base.errors import ConfigurationError, ValidationError
34
+ from test_base.service.retention import (
35
+ UNIT_HOURS,
36
+ PruneResult,
37
+ RetentionPolicy,
38
+ RetentionService,
39
+ resolve_cutoff,
40
+ )
41
+
42
+ router = APIRouter(tags=["retention"])
43
+
44
+
45
+ @router.get(
46
+ "/retention",
47
+ response_model=RetentionSettingsResponse,
48
+ summary="Read the retention policy",
49
+ dependencies=[Depends(require_read)],
50
+ )
51
+ def read_retention(
52
+ request: Request,
53
+ context: Context,
54
+ authorization: Annotated[str | None, Header()] = None,
55
+ x_api_key: Annotated[str | None, Header()] = None,
56
+ ) -> RetentionSettingsResponse:
57
+ settings = context.settings
58
+ return RetentionSettingsResponse(
59
+ admin=is_admin(request, authorization, x_api_key),
60
+ retention_days=settings.retention_days,
61
+ min_runs=settings.retention_min_runs,
62
+ grace_hours=settings.artifact_gc_grace_hours,
63
+ units=dict(UNIT_HOURS),
64
+ )
65
+
66
+
67
+ def _policy(context: Context, body: PruneRequest) -> RetentionPolicy:
68
+ settings = context.settings
69
+ try:
70
+ cutoff = resolve_cutoff(
71
+ older_than=body.older_than,
72
+ before=body.before,
73
+ default_days=settings.retention_days,
74
+ )
75
+ except ConfigurationError as exc:
76
+ # `resolve_cutoff` is shared with the CLI, where an unreadable duration
77
+ # really is a configuration error and 78/EX_CONFIG is the right exit
78
+ # code. Over HTTP the same string came from a client, so it is a 422 —
79
+ # answering 500 would blame the server for the caller's typo and tell
80
+ # every monitor that Test Base is broken.
81
+ raise ValidationError(exc.message, detail=exc.detail) from exc
82
+ return RetentionPolicy(
83
+ cutoff=cutoff,
84
+ keep_min=settings.retention_min_runs if body.keep_min is None else body.keep_min,
85
+ project_keys=tuple(body.project_keys),
86
+ by_import_date=body.by_import_date,
87
+ include_unfinished=body.include_unfinished,
88
+ grace_seconds=settings.artifact_gc_grace_hours * 3600.0,
89
+ )
90
+
91
+
92
+ def _response(result: PruneResult) -> PruneResponse:
93
+ return PruneResponse.model_validate(result.as_dict())
94
+
95
+
96
+ @router.post(
97
+ "/retention/preview",
98
+ response_model=PruneResponse,
99
+ summary="Count what a prune would remove",
100
+ dependencies=[Depends(require_admin)],
101
+ responses={403: {"description": "An administrator token is required."}},
102
+ )
103
+ def preview_prune(context: Context, body: PruneRequest) -> PruneResponse:
104
+ """Read-only. Opens a deferred transaction, so it does not queue in front of
105
+ a publisher the way a write would."""
106
+ return _response(RetentionService(context).plan(_policy(context, body)))
107
+
108
+
109
+ @router.post(
110
+ "/retention/prune",
111
+ response_model=PruneResponse,
112
+ summary="Delete runs older than a cutoff",
113
+ dependencies=[Depends(require_admin)],
114
+ responses={
115
+ 403: {"description": "An administrator token is required."},
116
+ 422: {"description": "The request did not confirm, or the cutoff was unreadable."},
117
+ },
118
+ )
119
+ def run_prune(context: Context, body: PruneRequest) -> PruneResponse:
120
+ """Irreversible. Deletes the runs, everything under them, and the artifact
121
+ blobs left unreferenced."""
122
+ if not body.confirm:
123
+ # Cheap, and it costs a caller one field. An API that destroys a year of
124
+ # history on a request somebody sent by accident is missing this check.
125
+ raise ValidationError(
126
+ "refusing to prune without confirmation; send `confirm: true` once you have "
127
+ "previewed the result at POST /retention/preview",
128
+ detail={"field": "confirm"},
129
+ )
130
+ return _response(RetentionService(context).prune(_policy(context, body)))