Relay Runtime Contract

Contract Metadata

{
  "subsystem_id": "relay-runtime",
  "lane": "L7",
  "contract_file": "docs/release-control/v6/internal/subsystems/relay-runtime.md",
  "status_file": "docs/release-control/v6/internal/status.json",
  "registry_file": "docs/release-control/v6/internal/subsystems/registry.json",
  "dependency_subsystem_ids": []
}

Purpose

Own the desktop relay runtime, its persisted client configuration, and the canonical reconnect, encryption, and relay-trust behavior for Pulse instance bridging.

Canonical Files

internal/relay/client.go
internal/config/persistence_relay.go

Shared Boundaries

None.

Extension Points

Add or change desktop relay reconnect, registration, drain, proxy-stream, or encrypted channel behavior through internal/relay/
Add or change persisted relay enablement, server URL, or reconnect-safe default loading through internal/config/persistence_relay.go
Keep desktop relay changes aligned with the governed mobile and server relay surfaces represented by the L7 lane evidence

Forbidden Paths

Reintroducing relay client trust or TLS handling through ad hoc dialer configuration outside the canonical relay client
Letting encrypted DATA frames race ahead of nonce-order guarantees by deferring inbound decrypt work to background goroutines
Treating a missing persisted relay config file as a hard failure instead of falling back to the canonical disabled default

Completion Obligations

Update this contract when new desktop relay runtime or persistence entry points become canonical
Keep relay client changes tied to explicit runtime proof in internal/relay/client_test.go
Keep persisted relay config loading tied to explicit proof in internal/config/persistence_relay_test.go

Current State

The desktop relay client had been carrying real runtime behavior without any explicit subsystem ownership even though L7 already treats relay readiness as a governed release lane. This contract makes that desktop boundary explicit. The canonical relay runtime now includes local CA-bundle trust via SSL_CERT_FILE, so self-hosted relay deployments can use a private CA without forking the dial path or disabling TLS verification globally. Inbound DATA handling is also part of this boundary: encrypted relay frames must be decrypted before they are handed to background stream handlers so the channel nonce guard stays monotonic and relay arrival order cannot trip false replay failures under concurrency. Relay status truthfulness is part of the same contract. If the client is in a governed reconnect or license-pause window, ClientStatus.reconnect_in must reflect that delay instead of silently presenting a disconnected state with no retry timing. The relay HTTP proxy boundary is also part of this owned surface. Relay DATA requests must normalize outer method/path whitespace before building the local Pulse API request so trivial spacing drift does not cause a valid proxied operation to fail at the desktop boundary. The same normalization rule applies to allowlisted proxy header names, so safe headers like Content-Type are not silently stripped just because the upstream frame wrapped them in outer whitespace. Persisted relay config loading is part of the same owned surface. A missing relay.enc file must fall back cleanly to the canonical disabled default so a fresh v6 install or a partially migrated instance does not fail closed just because relay settings have never been saved. That same persistence boundary also owns relay client secrets at rest: relay.enc may only accept plaintext relay config as migration input. Once the runtime can read legacy plaintext relay settings, it must rewrite canonical encrypted storage immediately on load instead of leaving instance_secret or the relay identity private key on disk as a normal runtime path.

3.8 KiB Raw Blame History