complete-exchange-base-url.rst (2044B)
1 .. ts:op:: completeExchangeBaseUrl 2 3 Try to complete a partial URL into the canonical base URL of an 4 exchange. 5 6 **Request:** 7 8 The request arguments must be a `CompleteBaseUrlRequest` object. 9 10 **Response:** 11 12 On success, the result is a `CompleteBaseUrlResult` object. 13 14 **Side effects:** 15 16 Probes candidate base URLs over the network until one validates as 17 an exchange. 18 19 **Details:** 20 21 The wallet derives candidate base URLs from ``url`` and probes 22 them, returning the first candidate that answers like an exchange. 23 A failure to complete is reported in-band via the ``status`` field 24 of the result, not with an error response: ``bad-syntax`` when the 25 URL is too malformed to be completed, ``bad-network`` when no 26 candidate could be reached and ``bad-exchange`` when the endpoint 27 is reachable but is not an exchange. In the failure case, 28 ``suggestions`` may list base URLs of exchanges known to the wallet 29 that look similar to what was typed. 30 31 .. ts:def:: CompleteBaseUrlRequest 32 33 interface CompleteBaseUrlRequest { 34 url: string; 35 36 // Correlates progress notifications and allows cancellation. 37 progressToken?: string; 38 } 39 40 .. ts:def:: CompleteBaseUrlResult 41 42 type CompleteBaseUrlResult = 43 | { 44 // ok: completion is a proper exchange 45 status: "ok"; 46 47 // Completed exchange base URL, if completion was possible 48 completion: string; 49 } 50 | { 51 // bad-syntax: url is so badly malformed, it can't be completed 52 // bad-network: syntax okay, but exchange can't be reached 53 // bad-exchange: syntax and network okay, but not talking to 54 // an exchange 55 status: "bad-syntax" | "bad-network" | "bad-exchange"; 56 57 // Error details in case status is not "ok" 58 error: TalerErrorDetail; 59 60 // Base URLs of exchanges known to the wallet whose host looks 61 // like what the user meant to type, most likely first. 62 // Absent when the wallet does not know anything similar. 63 suggestions?: string[]; 64 };