HTTP
The host capability Http sends HTTP/1.1 requests (spec/24, edition 0.2).
-
Operations. One per method, so
uses @http: Http[get]can never post:get(url: Text, headers: List[Header], key_name: Option[Text]) -> internal Response;post(url: Text, headers: List[Header], body: Text, key_name: Option[Text]) -> internal Response;put, with the parameters ofpost;delete, with the parameters ofget.
Each fails with
HttpErrorand acceptsinternal.Headerhasname: Textandvalue: internal Text, andResponsehasstatus: Int,headers: List[Header]andbody: Text. -
Statuses are not failures. A 404 is a
Response.HttpErroris for requests that got no response:Denied,BadUrl,BadRequest,Unreachable,TimedOut,TooLarge,TlsorProtocol. -
Grants.
http:<origin>orhttp:<origin>:<methods>, by defaultget:http:https://api.example.com:get,post. A request outside them fails withDenied, before any connection. Plainhttponly where a grant says so. -
Credentials.
key_name: Some("name")sends the keynameof the run'skeys:grant asAuthorization: Bearer <key>, to that origin only. The program never sees it, and no trace shows it. An API that wants its token in another header, asX-Api-Token, takes it as a header value: asecrettoken needs a policy tointernalfirst (§9). -
Labels. Arguments accept
internaldata: asecretURL, body or header value needs a policy first. Responses areinternal, so a function that returns what it read declares aninternalresult, and itsOptionorResulttoo, since which one it returns depends on the response. -
Failures are
internal. The server receives the URL, the headers with their values and the body, and may decide whether the request fails by them, so the failure of every request isinternal, as its response is (S-15). Handle it withattemptand return a labeled value:if error passorif error failis U4002. -
Header values. A header value with a control character other than a tab, such as a newline, aborts the run with U6004, since the value is
internal. Remove them from values built from data first:value.replace(pattern: "\n", by: ""). -
Limits.
--max-response <MiB>(default 16) and--http-timeout <seconds>(default 30, the total time of a request). Tests giveHttpa handler, since examples cannot use it. As any handler, it implements every operation of the capability, all four (U3011), asfixed_answerbelow.
module weather
--- The temperature of a city, from a JSON API, or `None` when the request or its answer fails.
--- The token is the key `weather` of the run's `keys:` grant; the program never sees it.
pub temperature(city: Text) -> internal Option[internal Int]
uses @http: Http[get]
=
let accept = Header(name: "Accept", value: "application/json")
let r = attempt @http.get("https://api.example.com/v1/now?city={city}", headers: [accept], key_name: Some("weather"))
when r
is Ok(response) -> if response.status == 200 then degrees(response.body) else None
is Err(e) -> None
--- The `degrees` field of a JSON object, when it is an integer.
degrees(body: internal Text) -> internal Option[internal Int]
=
let doc = body.parse_json()
if error use Null
when doc
is Object(fields) ->
let value = fields.get(key: "degrees")
if none use Null
when value
is Number(n) -> Some(n)
else -> None
else -> NoneA test of a function that uses Http installs a stand-in with given. Its parameter is named answer, not body, since an operation's parameter of the same name would clash with it (U1002):
module stand_in
--- The status of a GET, or `None` when the request gets no response.
pub status_of(url: Text) -> internal Option[internal Int]
uses @http: Http[get]
=
let r = attempt @http.get(url, headers: [], key_name: None)
when r
is Ok(response) -> Some(response.status)
is Err(e) -> None
--- A stand-in for an API: every GET answers 200 with `answer`, and the other methods 405.
pub handler fixed_answer(answer: Text) for Http
op get(url, headers, key_name) = Response(status: 200, headers: [], body: answer)
op post(url, headers, body, key_name) = Response(status: 405, headers: [], body: "")
op put(url, headers, body, key_name) = Response(status: 405, headers: [], body: "")
op delete(url, headers, key_name) = Response(status: 405, headers: [], body: "")
example "the stand-in answers every GET"
given @http = fixed_answer(answer: "ok")
do status_of("https://api.example.com/v1/now")
expect result == Some(200)