DD 69: Exchange Base URL Completion

11.69. DD 69: Exchange Base URL Completion#

11.69.1. Summary#

Define the request, which turns user-provided input (like exchange.example.com or just example.com) into a canonical, validated HTTPS exchange base URL. Validation requires that GET <base>/keys returns a valid ExchangeKeysResponse object.

11.69.2. Motivation#

Users may provide incomplete or ambiguous input when configuring an exchange. For example, they may type just example.com instead of the full https://exchange.example.com/. The system must normalize, complete, and validate such inputs to ensure that only valid exchanges are accepted. This improves robustness and user experience while preventing misconfiguration.

11.69.3. Requirements#

  • Accepts a single string from the user (host or URL).

  • Supports inputs like exchange.example.com, example.com, or https://exchange.example.com/.

  • Always enforces HTTPS.

  • Base URL must end with a single / and omit ports.

  • Must validate by requesting GET <base>/keys and checking for a valid ExchangeKeysResponse object.

  • Must support a local list of trusted exchanges for resolution of ambiguous inputs or typos (70% Levenshtein similarity).

11.69.4. Proposed Solution#

Process:

  1. Clean up locally

    • Trim spaces and lowercase scheme/host.

    • Default scheme to https:// if missing.

    • Reject non-HTTPS schemes.

    • Remove explicit port and strip query/fragment.

    • Ensure a trailing slash.

  2. Candidate base URLs

    • If input host starts with exchange., use directly.

    • If input is a bare domain, construct https://exchange.<domain>/ as a second candidate.

  3. Network check (keys)

    • For each candidate, perform GET <base>/keys.

    • Follow HTTPS redirects within limits.

    • Accept if the final response is a valid ExchangeKeysResponse.

    • Otherwise, treat as protocol failure.

  4. List of trusted exchanges

    • Check the input against a local list of trusted exchanges.

    • Match by exact part match of hostname and fuzzy match (≥70% Levenshtein).

    • Return bad-protocol and if trusted entry(ies) is(are) found, return it(them) back in object(sugestions: array).

11.69.4.1. Outcome values#

  • ok — Keys validated; return canonical base.

  • bad-syntax — Input invalid (e.g., non-HTTPS scheme).

  • bad-network — Network failure (DNS/connect/TLS/timeout).

  • bad-protocol — Response received but not a valid exchange.

11.69.4.2. Canonicalization of output#

  • Always return in the form https://<lowercased-host>/.

  • No ports, queries, or fragments.

11.69.4.3. Examples#

  • exchange.example.com -> ok, returns https://exchange.example.com/.

  • example.com -> try https://example.com/keys first. If not valid, then try https://exchange.example.com/keys. If that works → ok, returns https://exchange.example.com/.

  • https://exchange.example.com/ with /keys returning something other than a valid ExchangeKeysResponse object -> bad-protocol.

  • http://exchange.example.com -> bad-syntax (HTTPS required).

  • example.com where /keys redirects to https://api.example.com/keys and returns valid data -> ok, returns https://api.example.com/.

  • DNS failure -> bad-network.

11.69.5. Definition of Done#

  • Request implemented and documented.

  • Unit tests cover: - valid inputs, - redirects, - trusted exchange fallback, - failure cases (syntax, network, protocol).

  • Feature is enabled by default once tests pass.

11.69.6. Alternatives#

11.69.7. Drawbacks#

  • Requires maintaining a local list of trusted exchanges and fuzzy matching.

  • Adds network overhead (GET /keys probes).

  • Possible user confusion if multiple trusted exchanges are suggested as fuzzy matches.

11.69.8. Discussion / Q&A#

(To be filled in with results from discussions on mailing lists / personal communication.)