47 lines
1.4 KiB
Markdown
47 lines
1.4 KiB
Markdown
# Link URL Policy
|
|
|
|
Audience: developers and LLM coding agents changing `internal/link`.
|
|
|
|
## Purpose
|
|
|
|
`internal/link` owns shared validation for configured and persisted HTTP link URLs.
|
|
|
|
## Inputs And Outputs
|
|
|
|
Input is a URL string. Output is either nil for an accepted URL or a concise validation error that callers wrap with field context.
|
|
|
|
## Boundaries
|
|
|
|
The package validates URL shape only. It does not construct output URLs, choose primary URLs, infer public URLs from backend configuration, parse config files, or write destination state.
|
|
|
|
## Config Fields Used
|
|
|
|
The package does not read config directly. `internal/config` uses it to validate `links.base_url`; `internal/state` uses it to validate persisted `links.primary_url` and output `url` fields.
|
|
|
|
## Adapters Used
|
|
|
|
None.
|
|
|
|
## State And Manifest Behavior
|
|
|
|
Destination state URL fields and configured link URLs share the same URL validation policy. Source manifests are not involved.
|
|
|
|
## Skip And Resume Behavior
|
|
|
|
None.
|
|
|
|
## Failure Behavior
|
|
|
|
Validation rejects parse failures, non-HTTP(S) schemes, missing hosts, query strings, and fragments.
|
|
|
|
## Tests To Inspect
|
|
|
|
- `internal/link/url_test.go`
|
|
- callers in `internal/config`, `internal/state`, and `internal/publish`
|
|
|
|
## Architectural Invariants
|
|
|
|
- Configured and persisted link URLs use one validation policy.
|
|
- URL construction remains outside `internal/link`.
|
|
- Callers own field-specific error context.
|