azaion/annotations
1
0
Fork 0
mirror of https://github.com/azaion/annotations.git synced 2026-06-21 09:41:07 +00:00
Code Issues Packages Projects Releases Wiki Activity

[AZ-PENDING-1] [AZ-PENDING-2] Step 4 close-out: verification + docs

Browse Source 
Phase 6 smoke (Docker, _docs/04_refactoring/01-testability-refactoring/
smoke-compose.yml):
  - Annotations app boots clean under ASPNETCORE_ENVIRONMENT=E2ETest.
  - /health 200 OK; /annotations with bearer returns 401 with the
    JWT library's own malformed-token rejection.
  - 0 IDX20108 occurrences in logs (C01 verified).
  - 0 IPAddress.Parse FormatException occurrences; FailsafeProducer
    reaches the broker via Docker DNS (C02 verified).
  - Full smoke report in verification.md.

Phase 7 docs:
  - architecture.md: retire Open Risks §6 (testability blocker
    resolved). Update the constraints block to describe the
    ASPNETCORE_ENVIRONMENT-gated RequireHttps behavior.
  - components/06_platform/description.md: one-liner on JwtExtensions
    JWKS gating.
  - components/02_annotations-realtime-sync/description.md: one-liner
    on FailsafeProducer host resolution accepting literal IP or DNS.
  - tests/test-data.md: refresh the JWKS URL configuration section to
    point at the resolved implementation instead of the open risk.

Task housekeeping:
  - _docs/02_tasks/todo/01_*.md -> done/
  - _docs/02_tasks/todo/02_*.md -> done/
  - _docs/_autodev_state.md: advance to Step 5 (Refactor Backlog Triage).

Tracker IDs remain placeholders pending Atlassian MCP availability —
real IDs to be assigned per
_docs/_process_leftovers/2026-05-14_testability-tracker.md.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Oleksandr Bezdieniezhnykh
2026-05-14 20:38:14 +03:00
parent 90d48cf3c0
commit d7d1c0ed6a
10 changed files with 278 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files
_docs/02_document/architecture.md
+2 -2
View File
@@ -81,7 +81,7 @@ Azaion.Annotations is a single .NET 10 ASP.NET Core service in the Azaion suite
**Key constraints (evidenced in code/config)**:
- `DATABASE_URL` is **required** at startup — `ConfigurationResolver.ResolveRequiredOrThrow` throws if not set. The string is auto-converted from `postgresql://user:pass@host:port/db` URI form to Linq2DB's `Host=…;Username=…` form by `Program.ConvertPostgresUrl`.
- JWT verification is **required** at startup — `JWT_ISSUER`, `JWT_AUDIENCE`, and `JWT_JWKS_URL` are all resolved by `ConfigurationResolver.ResolveRequiredOrThrow`. There is no insecure fallback. The JWKS URL must be HTTPS (`HttpDocumentRetriever { RequireHttps = true }`).
- JWT verification is **required** at startup — `JWT_ISSUER`, `JWT_AUDIENCE`, and `JWT_JWKS_URL` are all resolved by `ConfigurationResolver.ResolveRequiredOrThrow`. There is no insecure fallback. The JWKS URL is fetched with `HttpDocumentRetriever`, whose `RequireHttps` flag is gated on `ASPNETCORE_ENVIRONMENT`: HTTPS is required for any value other than `E2ETest` (Development, Staging, Production, and unset all enforce HTTPS); only `E2ETest` relaxes the flag to support the in-cluster mock issuer documented in `tests/environment.md`. The relaxation is gated in source (`src/Auth/JwtExtensions.cs`), not in config.
- Default directory roots are `/data/{videos,images,labels,results,thumbnails,gps_sat,gps_route}` (migrator `directory_settings` defaults) → operator must mount or override at the DB level via `PUT /settings/directories`.
- CORS is **environment-gated**: `CorsConfigurationValidator.EnsureSafeForEnvironment` refuses to start in `Production` when `CorsConfig:AllowedOrigins` is empty unless `CorsConfig:AllowAnyOrigin=true` is set explicitly. ADR-006 was retired together with the wide-open default.
@@ -374,7 +374,7 @@ These are residual risks that still need attention from later autodev steps (Tes
3. **`UserId` body field vs JWT `NameIdentifier`** drift (suite spec lists `UserId` on `POST /annotations`; code uses JWT subject). Reconcile in the suite spec.
4. **No automated tests**: addressed by autodev Phase A Steps 3–7 (Test Spec → Implement Tests → Run Tests).
5. **`FailsafeProducer.cs:138` swallows `IOException` on image read silently** (`catch { }`). Direct `coderule.mdc` violation. Symptom in product: a missing or unreadable image yields a stream message with `image = null` and no log/metric — the gap is invisible to operators. Track on Refactor Backlog (RB-05).
6. **JWKS HTTPS-only retrieval blocks containerised test harnesses** that would otherwise serve a static JWKS over plain HTTP. Tests must either run a TLS-terminating sidecar in the test compose stack or rely on test-only configuration that relaxes `RequireHttps`. Not a production risk; a Step 4 (Code Testability Revision) item.
6. ~~**JWKS HTTPS-only retrieval blocks containerised test harnesses**~~ — **RESOLVED 2026-05-14** by Step 4 (Code Testability Revision). `JwtExtensions.AddJwtAuth` now gates `HttpDocumentRetriever.RequireHttps` on `ASPNETCORE_ENVIRONMENT == "E2ETest"` (case-insensitive). Production / Staging / Development / unset all retain HTTPS-required behavior; only the `E2ETest` value relaxes the flag. Verified via the smoke harness in `_docs/04_refactoring/01-testability-refactoring/verification.md`. See `_docs/04_refactoring/01-testability-refactoring/testability_changes_summary.md` (item C01) for the full change log.
## Refactor Backlog