1.8 KiB
1.8 KiB
ADR-003: Read-only Gitea HTTP boundary
Status: accepted
Date: 2026-08-26
Context
UBGitea needs authenticated access to Gitea 1.23 repository, branch, tag, contents, file, and commit endpoints. URL components may contain spaces, plus signs, hash characters, slashes in refs, and Unicode. Tokens and DTOs must not escape the data boundary, and automated tests must never call production.
Decision
- Use OkHttp for cancellable asynchronous HTTP and
HttpUrlfor one-time path-segment/query encoding. - Inject a suspending bearer-token provider. A blank token fails before network access.
- Keep Gson DTOs private to the data adapter and validate nullable wire fields before constructing immutable domain models.
- Map 401, 403, 404, 429, network, parse, and 5xx outcomes to explicit failures; never catch coroutine cancellation.
- Use the Gitea contents endpoint for directory metadata and Base64 file content. Validate returned file path, type, encoding, declared size, and decoded size.
- Respect server pagination headers on list endpoints. The contents endpoint has no server pagination, so expose deterministic immutable local pages from its returned directory snapshot.
- Use OkHttp MockWebServer only in unit tests to verify the real authorization/header/URL boundary without production traffic. Smaller mapping tests use an in-memory transport for deterministic fixtures.
Consequences
- Owner, repository, ref, and path values are encoded independently and not manually concatenated into query strings.
- The feature remains read-only; the transport adapter exposes no mutation method.
- Directory paging repeats the contents request for later local pages. A future cache may optimize this only under a separate accepted task.
- MockWebServer is a test-only dependency aligned to the production OkHttp version.