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
File without changes
test_base/api/app.py ADDED
@@ -0,0 +1,314 @@
1
+ """The FastAPI application: wiring, security headers, error mapping, static assets.
2
+
3
+ Three things happen here that are worth reading before changing anything.
4
+
5
+ **Errors are mapped once.** Every route raises
6
+ :class:`~test_base.errors.TestBaseError` subclasses and never builds an HTTP
7
+ response by hand, so the JSON shape of a failure — ``{error, message, detail}`` —
8
+ is guaranteed identical across the API and matches what the CLI prints.
9
+
10
+ **Security headers are applied to everything**, including the static dashboard and
11
+ the OpenAPI docs. The CSP is restrictive by default (``default-src 'none'``),
12
+ which is only possible because the frontend ships no inline scripts, no inline
13
+ styles and no remote origins — see ADR-0001 D7. If you ever find yourself
14
+ loosening the CSP to make a feature work, the feature is wrong, not the policy.
15
+
16
+ **The dashboard is served from the wheel.** ``test_base/web`` is packaged, mounted
17
+ read-only, and served with an ETag; there is no separate web server to run and no
18
+ build step to forget.
19
+ """
20
+
21
+ from __future__ import annotations
22
+
23
+ import contextlib
24
+ from collections.abc import AsyncIterator, Sequence
25
+ from importlib.resources import files
26
+ from pathlib import Path
27
+ from typing import Any
28
+
29
+ from fastapi import FastAPI, Request
30
+ from fastapi.exceptions import RequestValidationError
31
+ from fastapi.responses import FileResponse, JSONResponse, Response
32
+ from fastapi.staticfiles import StaticFiles
33
+ from sqlalchemy import exc as sa_exc
34
+ from starlette.middleware.cors import CORSMiddleware
35
+ from starlette.middleware.trustedhost import TrustedHostMiddleware
36
+
37
+ from test_base.api.routes import (
38
+ failures,
39
+ health,
40
+ imports,
41
+ queries,
42
+ retention,
43
+ runs,
44
+ server,
45
+ stream,
46
+ )
47
+ from test_base.api.security import TokenVerifier
48
+ from test_base.config import Settings, get_settings
49
+ from test_base.errors import StorageBusyError, TestBaseError
50
+ from test_base.logging import configure_logging, get_logger
51
+ from test_base.service.runtime import AppContext, create_context
52
+ from test_base.storage.db import is_contention
53
+ from test_base.version import __version__
54
+
55
+ __all__ = ["create_app", "web_root"]
56
+
57
+ logger = get_logger(__name__)
58
+
59
+ API_PREFIX = "/api/v1"
60
+
61
+ DESCRIPTION = """
62
+ One live dashboard for every test run — any team, any framework, any CI.
63
+
64
+ Test Base accepts test results from any language and any framework over plain
65
+ HTTP. There is no required client library: `curl` is a first-class publisher.
66
+
67
+ * **Import a report file** — `POST /api/v1/imports` with a JUnit XML or Test Base
68
+ canonical JSON file and the metadata that describes the run.
69
+ * **Publish live** — `POST /api/v1/runs` to open a run, then stream
70
+ `POST /api/v1/runs/{run_id}/events` as tests finish, then
71
+ `POST /api/v1/runs/{run_id}/finish`.
72
+ * **Watch** — `GET /api/v1/events/stream` is Server-Sent Events with heartbeats
73
+ and `Last-Event-ID` replay.
74
+
75
+ Every write is idempotent. Reposting an event, a batch or a whole report never
76
+ duplicates a test or moves a count.
77
+ """
78
+
79
+
80
+ def web_root() -> Path:
81
+ """Where the packaged dashboard lives.
82
+
83
+ Uses ``importlib.resources`` so it resolves correctly from an installed
84
+ wheel, a zipapp or a source checkout, rather than assuming a path relative
85
+ to this file.
86
+ """
87
+ return Path(str(files("test_base").joinpath("web")))
88
+
89
+
90
+ class _SecurityHeadersMiddleware:
91
+ """Adds the headers that make an XSS in stored test output non-exploitable,
92
+ and the one that stops a browser running last release's dashboard.
93
+
94
+ Written as raw ASGI rather than ``BaseHTTPMiddleware`` because the latter
95
+ buffers responses, which would defeat the whole point of the SSE endpoint.
96
+
97
+ **The cache header is not a performance tweak.** ``StaticFiles`` sends an
98
+ ``ETag`` and a ``Last-Modified`` but no ``Cache-Control``, and a response
99
+ with a validator and no freshness directive is one a browser may cache
100
+ *heuristically* — commonly a tenth of the file's age — serving it for hours
101
+ without ever asking whether it changed. The dashboard is a dozen plain
102
+ ``.js`` files at stable paths, so the symptom of that is an upgraded Test Base
103
+ running the previous version's JavaScript against the current version's
104
+ markup: no error, no console message, just a feature that silently is not
105
+ there. ``no-cache`` does not mean "do not store" — it means "revalidate
106
+ first", so the browser still gets a 304 and the bytes still come from disk
107
+ cache. The cost is one conditional request per asset per load; the thing it
108
+ buys is that shipping a fix actually ships it.
109
+ """
110
+
111
+ def __init__(self, app: Any, settings: Settings) -> None:
112
+ self.app = app
113
+ self.headers: list[tuple[bytes, bytes]] = [
114
+ (b"x-content-type-options", b"nosniff"),
115
+ (b"x-frame-options", b"DENY"),
116
+ (b"referrer-policy", b"no-referrer"),
117
+ (b"cross-origin-opener-policy", b"same-origin"),
118
+ (b"permissions-policy", b"camera=(), microphone=(), geolocation=(), payment=()"),
119
+ ]
120
+ #: Sent for the dashboard only. The API sets its own caching where it
121
+ #: wants any, and SSE must never be cached at all.
122
+ self.revalidate: tuple[bytes, bytes] = (b"cache-control", b"no-cache")
123
+ if settings.csp:
124
+ self.headers.append((b"content-security-policy", settings.csp.encode("latin-1")))
125
+
126
+ async def __call__(self, scope: Any, receive: Any, send: Any) -> None:
127
+ if scope["type"] != "http":
128
+ await self.app(scope, receive, send)
129
+ return
130
+
131
+ path = scope.get("path", "")
132
+ is_dashboard = path == "/" or path.startswith("/assets/")
133
+
134
+ async def send_with_headers(message: Any) -> None:
135
+ if message["type"] == "http.response.start":
136
+ existing = {key.lower() for key, _ in message.get("headers", [])}
137
+ message.setdefault("headers", [])
138
+ for key, value in self.headers:
139
+ if key not in existing:
140
+ message["headers"].append((key, value))
141
+ if is_dashboard and self.revalidate[0] not in existing:
142
+ message["headers"].append(self.revalidate)
143
+ await send(message)
144
+
145
+ await self.app(scope, receive, send_with_headers)
146
+
147
+
148
+ def _install_error_handlers(app: FastAPI) -> None:
149
+ """One place where an exception becomes an HTTP response."""
150
+
151
+ @app.exception_handler(TestBaseError)
152
+ async def _test_base_error(_: Request, exc: TestBaseError) -> JSONResponse:
153
+ if isinstance(exc, StorageBusyError):
154
+ # Expected under a burst of publishers, and answered with a retry.
155
+ logger.warning("%s: %s", exc.code, exc.message)
156
+ elif exc.http_status >= 500:
157
+ logger.error("%s: %s", exc.code, exc.message)
158
+ else:
159
+ logger.debug("%s: %s", exc.code, exc.message)
160
+ headers: dict[str, str] = {}
161
+ if exc.http_status == 401:
162
+ headers["WWW-Authenticate"] = "Bearer"
163
+ if isinstance(exc, StorageBusyError):
164
+ headers["Retry-After"] = str(exc.retry_after)
165
+ return JSONResponse(exc.to_dict(), status_code=exc.http_status, headers=headers or None)
166
+
167
+ @app.exception_handler(sa_exc.OperationalError)
168
+ async def _database_error(_: Request, exc: sa_exc.OperationalError) -> JSONResponse:
169
+ # Contention that SQLite reported itself — the writer queue in
170
+ # storage/db.py keeps one process's writers in line, but a second
171
+ # process (a `test-base ingest` beside the server) can still hold the
172
+ # lock. Either way nothing was written and a retry succeeds; a
173
+ # traceback and a dropped connection told the publisher neither.
174
+ if is_contention(exc):
175
+ busy = StorageBusyError("The database is busy with other writes. Retry shortly.")
176
+ logger.warning("%s: %s", busy.code, exc.orig)
177
+ return JSONResponse(
178
+ busy.to_dict(),
179
+ status_code=busy.http_status,
180
+ headers={"Retry-After": str(busy.retry_after)},
181
+ )
182
+ logger.error("database error: %s", exc.orig)
183
+ return JSONResponse(
184
+ {"error": "storage_error", "message": "The database could not complete the request."},
185
+ status_code=500,
186
+ )
187
+
188
+ @app.exception_handler(RequestValidationError)
189
+ async def _validation_error(_: Request, exc: RequestValidationError) -> JSONResponse:
190
+ # FastAPI's default shape is `{"detail": [...]}`; ours is the same shape
191
+ # as every other error so a client needs exactly one error parser.
192
+ return JSONResponse(
193
+ {
194
+ "error": "validation_error",
195
+ "message": "the request body did not match the expected schema",
196
+ "detail": {"errors": _jsonable_errors(exc.errors())},
197
+ },
198
+ status_code=422,
199
+ )
200
+
201
+
202
+ def _jsonable_errors(errors: Sequence[Any]) -> list[dict[str, Any]]:
203
+ """Strip the non-serializable ``ctx`` Pydantic sometimes attaches."""
204
+ cleaned: list[dict[str, Any]] = []
205
+ for error in errors:
206
+ item = {key: value for key, value in error.items() if key != "ctx"}
207
+ item["loc"] = [str(part) for part in item.get("loc", ())]
208
+ cleaned.append(item)
209
+ return cleaned
210
+
211
+
212
+ def create_app(
213
+ settings: Settings | None = None,
214
+ *,
215
+ context: AppContext | None = None,
216
+ ) -> FastAPI:
217
+ """Build the application.
218
+
219
+ Pass ``context`` to reuse an already-built one — that is how the CLI avoids
220
+ opening the database twice, and how tests bind the app to a temporary
221
+ directory.
222
+ """
223
+ settings = settings or (context.settings if context else get_settings())
224
+ configure_logging(settings)
225
+
226
+ owns_context = context is None
227
+
228
+ @contextlib.asynccontextmanager
229
+ async def lifespan(app: FastAPI) -> AsyncIterator[None]:
230
+ app.state.context = context or create_context(settings)
231
+ # Writes happen on worker threads; the bus needs this loop to publish onto.
232
+ app.state.context.bus.bind_loop()
233
+ app.state.verifier = TokenVerifier.from_settings(settings)
234
+ app.state.admin_verifier = TokenVerifier.admin_from_settings(settings)
235
+ app.state.settings = settings
236
+ for warning in settings.check_bind_safety():
237
+ logger.warning(warning)
238
+ logger.info("Test Base %s ready — data in %s", __version__, settings.data_dir)
239
+ try:
240
+ yield
241
+ finally:
242
+ if owns_context:
243
+ app.state.context.close()
244
+
245
+ app = FastAPI(
246
+ title="Test Base",
247
+ version=__version__,
248
+ description=DESCRIPTION,
249
+ summary="One live dashboard for every test run — any team, any framework, any CI.",
250
+ license_info={"name": "Apache-2.0", "identifier": "Apache-2.0"},
251
+ lifespan=lifespan,
252
+ root_path=settings.root_path,
253
+ docs_url="/api/docs",
254
+ redoc_url="/api/redoc",
255
+ openapi_url="/api/openapi.json",
256
+ )
257
+
258
+ _install_error_handlers(app)
259
+
260
+ app.include_router(health.router)
261
+ app.include_router(imports.router, prefix=API_PREFIX)
262
+ app.include_router(runs.router, prefix=API_PREFIX)
263
+ app.include_router(queries.router, prefix=API_PREFIX)
264
+ app.include_router(failures.router, prefix=API_PREFIX)
265
+ app.include_router(stream.router, prefix=API_PREFIX)
266
+ app.include_router(retention.router, prefix=API_PREFIX)
267
+ app.include_router(server.router, prefix=API_PREFIX)
268
+
269
+ if settings.cors_allow_origins:
270
+ app.add_middleware(
271
+ CORSMiddleware,
272
+ allow_origins=settings.cors_allow_origins,
273
+ allow_credentials=False,
274
+ allow_methods=["GET", "POST", "OPTIONS"],
275
+ allow_headers=["authorization", "content-type", "x-api-key", "x-idempotency-key"],
276
+ )
277
+ if settings.trusted_hosts:
278
+ app.add_middleware(TrustedHostMiddleware, allowed_hosts=settings.trusted_hosts)
279
+ app.add_middleware(_SecurityHeadersMiddleware, settings=settings)
280
+
281
+ _mount_dashboard(app)
282
+ return app
283
+
284
+
285
+ def _mount_dashboard(app: FastAPI) -> None:
286
+ """Serve the packaged dashboard at ``/``.
287
+
288
+ Mounted last so it cannot shadow an API route, and served through an
289
+ explicit index handler so that ``/`` and any client-side route both resolve
290
+ to the same file.
291
+ """
292
+ root = web_root()
293
+ if not root.is_dir(): # pragma: no cover - only in a broken install
294
+ logger.warning("dashboard assets are missing from %s; serving the API only", root)
295
+ return
296
+
297
+ assets = root / "assets"
298
+ if assets.is_dir():
299
+ app.mount("/assets", StaticFiles(directory=assets), name="assets")
300
+
301
+ index = root / "index.html"
302
+
303
+ @app.get("/", include_in_schema=False)
304
+ async def dashboard() -> Response:
305
+ if not index.is_file(): # pragma: no cover
306
+ return JSONResponse({"error": "not_found", "message": "dashboard not installed"}, 404)
307
+ return FileResponse(index, media_type="text/html")
308
+
309
+ @app.get("/favicon.ico", include_in_schema=False)
310
+ async def favicon() -> Response:
311
+ icon = root / "assets" / "favicon.svg"
312
+ if icon.is_file():
313
+ return FileResponse(icon, media_type="image/svg+xml")
314
+ return Response(status_code=204)
test_base/api/deps.py ADDED
@@ -0,0 +1,178 @@
1
+ """FastAPI dependencies — the bridge from the app's state to the service layer.
2
+
3
+ The :class:`~test_base.service.runtime.AppContext` is created once in the
4
+ lifespan handler and hung off ``app.state``. Everything else reaches it through
5
+ these dependencies, which keeps the routes free of any knowledge about how the
6
+ context was built and lets a test swap the whole thing for a temporary one.
7
+
8
+ Repository work is synchronous (SQLAlchemy, SQLite), so every route that touches
9
+ the database is declared ``def`` rather than ``async def``. FastAPI then runs it
10
+ in a worker thread and the event loop — which is also serving SSE streams — is
11
+ never blocked by a slow query. Getting this backwards is the classic way to make
12
+ a live dashboard stutter whenever somebody imports a large report.
13
+ """
14
+
15
+ from __future__ import annotations
16
+
17
+ from collections.abc import Iterator
18
+ from typing import Annotated
19
+
20
+ from fastapi import Depends, Header, Request
21
+
22
+ from test_base.api.security import TokenVerifier, parse_authorization
23
+ from test_base.errors import AuthenticationError, AuthorizationError
24
+ from test_base.service.imports import ImportService
25
+ from test_base.service.runs import RunService
26
+ from test_base.service.runtime import AppContext
27
+
28
+ __all__ = [
29
+ "Context",
30
+ "Imports",
31
+ "Runs",
32
+ "get_context",
33
+ "get_import_service",
34
+ "get_run_service",
35
+ "is_admin",
36
+ "require_admin",
37
+ "require_read",
38
+ "require_write",
39
+ ]
40
+
41
+
42
+ def get_context(request: Request) -> AppContext:
43
+ """The application context for this request."""
44
+ return request.app.state.context # type: ignore[no-any-return]
45
+
46
+
47
+ def get_verifier(request: Request) -> TokenVerifier:
48
+ return request.app.state.verifier # type: ignore[no-any-return]
49
+
50
+
51
+ def get_admin_verifier(request: Request) -> TokenVerifier:
52
+ return request.app.state.admin_verifier # type: ignore[no-any-return]
53
+
54
+
55
+ Context = Annotated[AppContext, Depends(get_context)]
56
+
57
+
58
+ def require_write(
59
+ request: Request,
60
+ authorization: Annotated[str | None, Header()] = None,
61
+ x_api_key: Annotated[str | None, Header()] = None,
62
+ ) -> None:
63
+ """Guard every mutating endpoint.
64
+
65
+ ``X-API-Key`` is accepted alongside ``Authorization: Bearer`` because a
66
+ surprising number of CI systems make it hard to set an Authorization header
67
+ on a generic HTTP step. It is the same token and the same check.
68
+ """
69
+ verifier = get_verifier(request)
70
+ if not verifier.enabled:
71
+ return
72
+ if authorization:
73
+ verifier.require(authorization)
74
+ return
75
+ if x_api_key and verifier.verify(x_api_key.strip()):
76
+ return
77
+ raise AuthenticationError(
78
+ "a valid bearer token is required; send it as `Authorization: Bearer <token>` "
79
+ "or `X-API-Key: <token>`"
80
+ )
81
+
82
+
83
+ def require_read(
84
+ request: Request,
85
+ authorization: Annotated[str | None, Header()] = None,
86
+ x_api_key: Annotated[str | None, Header()] = None,
87
+ ) -> None:
88
+ """Guard read endpoints — only when the operator asked for that.
89
+
90
+ Reads are open by default even with auth on, because the common deployment
91
+ is "anyone in the team may look, only CI may write". Set
92
+ ``TEST_BASE_REQUIRE_AUTH_FOR_READS=true`` to close them too.
93
+ """
94
+ context = get_context(request)
95
+ if not context.settings.require_auth_for_reads:
96
+ return
97
+ require_write(request, authorization, x_api_key)
98
+
99
+
100
+ def require_triage(
101
+ request: Request,
102
+ authorization: Annotated[str | None, Header()] = None,
103
+ x_api_key: Annotated[str | None, Header()] = None,
104
+ ) -> None:
105
+ """Guard triage: a write, unless the operator opened it to every reader.
106
+
107
+ Triage annotates failures and never changes a result, which is why an
108
+ operator may choose ``TEST_BASE_OPEN_TRIAGE=true`` — the people triaging
109
+ are the team reading the dashboard, not the CI that holds the token.
110
+ Without that choice it is guarded like every other write.
111
+ """
112
+ if get_context(request).settings.open_triage:
113
+ return
114
+ require_write(request, authorization, x_api_key)
115
+
116
+
117
+ def is_admin(
118
+ request: Request,
119
+ authorization: str | None = None,
120
+ x_api_key: str | None = None,
121
+ ) -> bool:
122
+ """Whether this caller may run destructive maintenance.
123
+
124
+ Two ways in, and no third:
125
+
126
+ **An admin token.** A separate list from the write tokens, because the write
127
+ token is the one that lives in every repository's CI settings — a credential
128
+ that can post a test result must not also be able to delete a year of them
129
+ (ADR-0002 D8).
130
+
131
+ **An unauthenticated loopback instance.** The laptop case: the port is
132
+ reachable only from this machine, and anyone who can reach it can already
133
+ run ``test-base prune`` in a terminal, so refusing here would protect nothing
134
+ and only make the dashboard lie about what it can do.
135
+
136
+ Note what is *not* on that list: an instance bound to a public interface with
137
+ ``--insecure-no-auth``. Writes are open there by the operator's explicit
138
+ choice, but "anyone on the network may add data" and "anyone on the network
139
+ may destroy it" are different enough that the second needs saying out loud —
140
+ with an admin token.
141
+ """
142
+ admin = get_admin_verifier(request)
143
+ presented = parse_authorization(authorization) or (x_api_key or "").strip() or None
144
+ if presented and admin.hashes and admin.verify(presented):
145
+ return True
146
+ settings = get_context(request).settings
147
+ return not settings.auth_enabled and settings.is_loopback
148
+
149
+
150
+ def require_admin(
151
+ request: Request,
152
+ authorization: Annotated[str | None, Header()] = None,
153
+ x_api_key: Annotated[str | None, Header()] = None,
154
+ ) -> None:
155
+ """Guard destructive maintenance. See :func:`is_admin` for the rules."""
156
+ if is_admin(request, authorization, x_api_key):
157
+ return
158
+ raise AuthorizationError(
159
+ "this endpoint needs an administrator token. Create one with "
160
+ "`test-base token create --admin` and set TEST_BASE_ADMIN_TOKEN_HASHES, "
161
+ "or run `test-base prune` on the host."
162
+ )
163
+
164
+
165
+ def get_import_service(context: Context) -> ImportService:
166
+ return ImportService(context)
167
+
168
+
169
+ def get_run_service(context: Context) -> RunService:
170
+ return RunService(context)
171
+
172
+
173
+ def iter_context(request: Request) -> Iterator[AppContext]: # pragma: no cover - convenience
174
+ yield get_context(request)
175
+
176
+
177
+ Imports = Annotated[ImportService, Depends(get_import_service)]
178
+ Runs = Annotated[RunService, Depends(get_run_service)]
File without changes
@@ -0,0 +1,104 @@
1
+ """Failure groups — the distinct ways tests fail, and what people decided about them.
2
+
3
+ ``GET /failures`` lists the groups that failed inside the window and filters
4
+ the rest of the dashboard uses, with their counts read from those runs.
5
+ ``GET /failures/{fingerprint}`` is one group in full. ``PATCH`` records triage:
6
+ a status, an owner, an issue link, a note. Triage is a note on the failure,
7
+ never a change to the results — an ignored failure still fails its run.
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ from typing import Annotated, Literal
13
+
14
+ from fastapi import APIRouter, Depends, Query
15
+
16
+ from test_base.api.deps import Context, require_read, require_triage
17
+ from test_base.api.routes.queries import Filter
18
+ from test_base.api.schemas import TriageRequest
19
+ from test_base.domain.failures import TriageStatus
20
+ from test_base.domain.models import FailureGroupDetail, FailureGroupList, FailureGroupSummary
21
+ from test_base.errors import NotFoundError, ValidationError
22
+ from test_base.storage.failures import REGRESSED
23
+
24
+ router = APIRouter(tags=["failures"])
25
+
26
+ #: What `triage=` accepts: every stored status, plus `regressed`.
27
+ _TRIAGE_FILTERS = frozenset({*(status.value for status in TriageStatus), REGRESSED})
28
+
29
+
30
+ def _triage_filter(values: list[str] | None) -> list[str]:
31
+ wanted: list[str] = []
32
+ for value in values or []:
33
+ wanted.extend(part.strip() for part in value.split(",") if part.strip())
34
+ unknown = sorted(set(wanted) - _TRIAGE_FILTERS)
35
+ if unknown:
36
+ raise ValidationError(
37
+ f"unknown triage filter {', '.join(unknown)}; use any of "
38
+ f"{', '.join(sorted(_TRIAGE_FILTERS))}",
39
+ detail={"triage": unknown},
40
+ )
41
+ return wanted
42
+
43
+
44
+ @router.get(
45
+ "/failures",
46
+ response_model=FailureGroupList,
47
+ summary="Failure groups in the window",
48
+ dependencies=[Depends(require_read)],
49
+ )
50
+ def list_failures(
51
+ context: Context,
52
+ run_filter: Filter,
53
+ triage: Annotated[
54
+ list[str] | None,
55
+ Query(
56
+ description="Triage statuses to include — untriaged, investigating, known, fixed, "
57
+ "ignored, or regressed (fixed, and failing again). Repeat or comma-separate."
58
+ ),
59
+ ] = None,
60
+ q: Annotated[
61
+ str | None, Query(max_length=200, description="Search titles, owners and issue links.")
62
+ ] = None,
63
+ sort: Annotated[
64
+ Literal["recent", "occurrences"],
65
+ Query(description="recent: last seen first. occurrences: most failures first."),
66
+ ] = "recent",
67
+ ) -> FailureGroupList:
68
+ wanted = _triage_filter(triage)
69
+ with context.uow_factory(read_only=True) as uow:
70
+ return uow.failures.list_groups(run_filter, triage=wanted, search=q, sort=sort)
71
+
72
+
73
+ @router.get(
74
+ "/failures/{fingerprint}",
75
+ response_model=FailureGroupDetail,
76
+ summary="One failure group, with its tests and recent occurrences",
77
+ dependencies=[Depends(require_read)],
78
+ responses={404: {"description": "No such failure group."}},
79
+ )
80
+ def get_failure(context: Context, fingerprint: str, run_filter: Filter) -> FailureGroupDetail:
81
+ with context.uow_factory(read_only=True) as uow:
82
+ detail = uow.failures.get_group(fingerprint, run_filter)
83
+ if detail is None:
84
+ raise NotFoundError(f"failure group {fingerprint} does not exist")
85
+ return detail
86
+
87
+
88
+ @router.patch(
89
+ "/failures/{fingerprint}",
90
+ response_model=FailureGroupSummary,
91
+ summary="Triage a failure group",
92
+ dependencies=[Depends(require_triage)],
93
+ responses={404: {"description": "No such failure group."}},
94
+ )
95
+ def triage_failure(context: Context, fingerprint: str, body: TriageRequest) -> FailureGroupSummary:
96
+ changes = {field: getattr(body, field) for field in body.model_fields_set}
97
+ if not changes:
98
+ raise ValidationError("nothing to change: send status, owner, issue_url or note")
99
+ with context.uow_factory() as uow:
100
+ group = uow.failures.triage(fingerprint, context.workspace_id, changes)
101
+ if group is None:
102
+ raise NotFoundError(f"failure group {fingerprint} does not exist")
103
+ uow.commit()
104
+ return group
@@ -0,0 +1,35 @@
1
+ """Liveness and readiness.
2
+
3
+ ``/healthz`` is deliberately outside ``/api/v1``: it is infrastructure, not part
4
+ of the versioned contract, and a container healthcheck should not have to be
5
+ updated when the API version moves. It touches the database — a Test Base that
6
+ cannot read its own store is not healthy, however well it serves HTTP.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ from fastapi import APIRouter
12
+
13
+ from test_base.api.deps import Context
14
+ from test_base.api.schemas import HealthResponse
15
+ from test_base.logging import get_logger
16
+
17
+ router = APIRouter(tags=["health"])
18
+ logger = get_logger(__name__)
19
+
20
+
21
+ @router.get("/healthz", response_model=HealthResponse, summary="Liveness and readiness")
22
+ def healthz(context: Context) -> HealthResponse:
23
+ database = "ok"
24
+ try:
25
+ with context.uow_factory(read_only=True) as uow:
26
+ uow.runs.get_workspace(context.workspace_id)
27
+ except Exception as exc: # a healthcheck must report, never raise
28
+ logger.error("health check failed to reach the database: %s", exc)
29
+ database = "error"
30
+ return HealthResponse(
31
+ status="ok" if database == "ok" else "degraded",
32
+ database=database,
33
+ workspace_id=context.workspace_id,
34
+ live_subscribers=context.bus.subscriber_count,
35
+ )