distributor/docs/internal/link.md

Link URL Policy

Purpose

internal/link defines 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.

Validation behavior

Accepted URLs must parse successfully, use http or https, include a host, and omit query strings and fragments.

Boundaries

This package validates URL shape only. It does not construct destination output URLs, choose primary URLs, infer public URLs from backend configuration, or read configuration files.

Tests

Before changing link URL policy, inspect tests under internal/link and callers in internal/config, internal/state, and internal/publish.

Invariants

• Configured links.base_url, persisted links.primary_url, persisted output url, and publish link planning use the same URL policy.
• Callers own field-specific error context.
• URL path construction remains in internal/publish.