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
|
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
|
+
)
|