distributor/docs/internal/link.md

# 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.