taler-docs

Documentation for GNU Taler components, APIs and protocols
Log | Files | Refs | README | LICENSE

069-exchange-base-url-completion.rst (4320B)

      1 DD 69: Exchange Base URL Completion
      2 ###################################
      3 
      4 Summary
      5 =======
      6 
      7 Define the request, which turns user-provided input (like ``exchange.example.com`` or just ``example.com``) into a canonical,
      8 validated **HTTPS** exchange base URL. Validation requires that ``GET <base>/config`` returns a valid
      9 `ExchangeVersionResponse <https://docs.taler.net/core/api-exchange.html#get--config>`__ object.
     10 
     11 Motivation
     12 ==========
     13 
     14 Users may provide incomplete or ambiguous input when configuring an exchange. For example, they may type just
     15 ``example.com`` instead of the full ``https://exchange.example.com/``.
     16 The system must normalize, complete, and validate such inputs to ensure that only valid exchanges are accepted.
     17 This improves robustness and user experience while preventing misconfiguration.
     18 
     19 Requirements
     20 ============
     21 
     22 * Accepts a single string from the user (host or URL).
     23 * Supports inputs like ``exchange.example.com``, ``example.com``,
     24   or ``https://exchange.example.com/``.
     25 * Always enforces HTTPS.
     26 * Base URL must end with a single ``/`` and omit ports.
     27 * Must validate by requesting ``GET <base>/config`` and checking for a valid
     28   `ExchangeVersionResponse <https://docs.taler.net/core/api-exchange.html#get--config>`__ object.
     29 * Must support a local list of trusted exchanges for resolution of ambiguous
     30   inputs or typos (70% Levenshtein similarity).
     31 
     32 Proposed Solution
     33 =================
     34 
     35 Process:
     36 
     37 1. **Clean up locally**
     38 
     39    * Trim spaces and lowercase scheme/host.
     40    * Default scheme to ``https://`` if missing.
     41    * Reject non-HTTPS schemes.
     42    * Remove explicit port and strip query/fragment.
     43    * Ensure a trailing slash.
     44 
     45 2. **Candidate base URLs**
     46 
     47    * If input host starts with ``exchange.``, use directly.
     48    * If input is a bare domain, construct
     49      ``https://exchange.<domain>/`` as a second candidate.
     50 
     51 3. **Network check (keys)**
     52 
     53    * For each candidate, perform ``GET <base>/config``.
     54    * Follow HTTPS redirects within limits.
     55    * Accept if the final response is a valid
     56      `ExchangeVersionResponse <https://docs.taler.net/core/api-exchange.html#get--config>`__.
     57    * Otherwise, treat as protocol failure.
     58 
     59 4. **List of trusted exchanges**
     60 
     61    * Check the input against a local list of trusted exchanges.
     62    * Match by exact part match of hostname and fuzzy match (≥70% Levenshtein).
     63    * Return ``bad-protocol`` and if trusted entry(ies) is(are) found, return it(them) back in object(``sugestions: array``).
     64 
     65 Outcome values
     66 --------------
     67 
     68 * **ok** — Keys validated; return canonical base.
     69 * **bad-syntax** — Input invalid (e.g., non-HTTPS scheme).
     70 * **bad-network** — Network failure (DNS/connect/TLS/timeout).
     71 * **bad-protocol** — Response received but not a valid exchange.
     72 
     73 Canonicalization of output
     74 --------------------------
     75 
     76 * Always return in the form ``https://<lowercased-host>/``.
     77 * No ports, queries, or fragments.
     78 
     79 Examples
     80 --------
     81 
     82 * ``exchange.example.com`` -> **ok**, returns ``https://exchange.example.com/``.
     83 * ``example.com`` -> try ``https://example.com/config`` first.
     84   If not valid, then try ``https://exchange.example.com/config``.
     85   If that works → **ok**, returns ``https://exchange.example.com/``.
     86 * ``https://exchange.example.com/`` with ``/config`` returning something other
     87   than a valid `ExchangeVersionResponse <https://docs.taler.net/core/api-exchange.html#get--config>`__ object -> **bad-protocol**.
     88 * ``http://exchange.example.com`` -> **bad-syntax** (HTTPS required).
     89 * ``example.com`` where ``/config`` redirects to
     90   ``https://api.example.com/config`` and returns valid data -> **ok**, returns
     91   ``https://api.example.com/``.
     92 * DNS failure -> **bad-network**.
     93 
     94 
     95 Definition of Done
     96 ==================
     97 
     98 * Request implemented and documented.
     99 * Unit tests cover:
    100   - valid inputs,
    101   - redirects,
    102   - trusted exchange fallback,
    103   - failure cases (syntax, network, protocol).
    104 * Feature is enabled by default once tests pass.
    105 
    106 Alternatives
    107 ============
    108 
    109 Drawbacks
    110 =========
    111 
    112 * Requires maintaining a local list of trusted exchanges and fuzzy matching.
    113 * Adds network overhead (``GET /config`` probes).
    114 * Possible user confusion if multiple trusted exchanges are suggested
    115   as fuzzy matches.
    116 
    117 Discussion / Q&A
    118 ================
    119 
    120 (To be filled in with results from discussions on mailing lists / personal communication.)