requesto

    httpx2's way of writing HTTP calls for MoonBit, on gaato/mttp: verb functions, a client with defaults, responses as values, raise_for_status, streaming, event hooks and a mock transport that runs an mttp server handler.

    http
    client
    requests
    async
    Download zip
    Author
    Version
    0.3.0
    License
    Apache-2.0
    Last updated
    13 hours ago
    Downloads
    142

    #gaato/requesto

    HTTP calls for MoonBit written the way httpx2 (and requests) users write them: verb functions, a client with defaults, responses as values, raise_for_status(), streaming in a scope, event hooks and a mock transport. Underneath it is gaato/mttp, which does the HTTP; requesto only adds the surface and its defaults.

    The name is "request" as Japanese speakers tend to say it: リクエスト, rikuesuto.

    Status: unofficial and experimental. While the version is 0.x, a minor release may contain breaking changes; the changelog lists each one with a migration note.

    #Install

    moon add gaato/requesto

    requesto runs on moonbitlang/core/async, which is experimental: a package that imports it needs options("allow-experimental-packages": ["moonbitlang/core/async"]) in its moon.pkg. Start the event loop with @mttp.run or an async fn main.

    #Usage

    ///|
    #derive(FromJson)
    struct Account {
    id : Int32
    name : String
    }

    ///|
    pub async fn example() -> Unit raise @requesto.HTTPError {
    let client = @requesto.Client::new(
    base_url="https://api.example.com/v1",
    headers=[("Accept", "application/json")],
    auth=Bearer("token"),
    )
    defer client.close()
    let user : Account = client
    .get("users/42", params=[("expand", "teams")])
    .raise_for_status()
    .json_as()
    println("user \{user.id}: \{user.name}")
    client.post("users", json={ "name": user.name }) |> ignore
    }

    A response is a value whatever its status. raise_for_status() raises HTTPStatusError for anything outside 200–299 and otherwise returns the response, so calls chain. Every failure is an HTTPError; its variants are httpx2's exception names (ConnectTimeout, ReadTimeout, ConnectError, TooManyRedirects, HTTPStatusError, …), with is_timeout() and is_transport_error() in place of the class tree, and mttp() returns the @mttp.TransportError underneath.

    #Bodies and auth

    Each call takes one body: content= bytes, text=, data= as a form, json=, or files= with data= as the text fields of a multipart body. auth= takes Basic(user, password), Bearer(token) or Digest(user, password), on the client or on one call. A Digest challenge is answered only for the origin the request was built for, never after a redirect to another.

    ///|
    pub async fn upload(
    client : @requesto.Client,
    ) -> Unit raise @requesto.HTTPError {
    client
    .post(
    "reports",
    data=[("title", "weekly")],
    files=[@requesto.Part::file("file", "week.csv", "text/csv", b"a,b\n")],
    auth=Digest("user", "password"),
    )
    .raise_for_status()
    |> ignore
    }

    #Streaming

    client.stream passes a response whose body is still on the connection to a function, and closes it when the function returns. Read it whole with read(), or piece by piece with each_bytes, each_line or, for server-sent events, each_event:

    ///|
    pub async fn follow(client : @requesto.Client) -> Unit {
    client.stream("GET", "events", async fn(response) {
    response.raise_for_status() |> ignore
    response.each_event(event => println("\{event.event}: \{event.data}"))
    })
    }

    A line longer than 1 MiB or an event longer than 16 MiB raises TooLarge (max_line_bytes=, max_event_bytes= change it).

    #Testing without a network

    MockTransport::new takes a handler of the same type an mttp server serves, so a client can call your app directly, as httpx2's ASGITransport does:

    ///|
    fn hello_app(_ : @mttp.Request) -> @mttp.Response {
    @mttp.Response::new(200, body=Bytes(b"hello"))
    }

    ///|
    async test "the app answers" {
    let client = @requesto.Client::new(
    transport=@requesto.MockTransport::new(req => hello_app(req)),
    )
    defer client.close()
    assert_eq(client.get("https://app.test/").text(), "hello")
    }

    #Coming from httpx2

    httpx2requesto
    httpx2.get(url, params=..., headers=...)@requesto.get(url, params=[...], headers=[...])
    httpx2.Client(base_url=..., auth=...)@requesto.Client::new(base_url=..., auth=Bearer(...))
    content=b"..." / content="..."content=b"..." / text="..."
    r.status_code, r.text, r.json()r.status_code, r.text(), r.json(), or r.json_as() into a type
    with client.stream(...) as r:client.stream(..., async fn(r) { ... })
    r.iter_bytes(), r.iter_lines()r.each_bytes(f), r.each_line(f)
    httpx_sse's iter_sse()r.each_event(f)
    files={"file": ("a.csv", data, "text/csv")}files=[Part::file("file", "a.csv", "text/csv", data)]
    auth=("user", "pw"), DigestAuth("user", "pw")auth=Basic("user", "pw"), auth=Digest("user", "pw")
    Limits(max_connections=100)limits=Limits::new(max_connections=Some(100))
    proxy="http://...", trust_env=Falseproxy="http://...", trust_env=false
    verify=False, verify="ca.pem"trust=Insecure, trust=PemFile("ca.pem")
    Timeout(10.0, connect=5.0)Timeout::new(Some(10_000), connect=Some(5_000)) (milliseconds)
    event_hooks={"request": [...], "response": [...]}event_hooks=EventHooks::new(request=[...], response=[...])
    MockTransport(handler)MockTransport::new(handler)
    except httpx2.HTTPErrorcatch { e => ... } on HTTPError

    HTTPError and status_code keep httpx2's spelling rather than MoonBit's usual HttpError and mttp's status, so names can be guessed from httpx2.

    #Defaults

    The same as httpx2's: redirects are not followed (follow_redirects=true on the client or one call follows up to 20), nothing is retried (retry= takes an @mttp.RetryPolicy), each phase — connect, read, write, pool — has 5 s, the pool holds up to 100 connections and keeps 20 idle for 5 s, the client keeps cookies in a jar of its own (cookie_jar= shares one), proxies come from HTTP_PROXY, HTTPS_PROXY and NO_PROXY, and there is no deadline for the whole call (total_timeout= sets one). On JavaScript the host's fetch handles connections, proxies and TLS itself.

    One difference: a buffered body is limited to 64 MiB after decompression (max_body_bytes=), and a larger one fails with TooLarge instead of filling memory. Read larger bodies with stream.

    Text is decoded as UTF-8, with malformed sequences replaced by U+FFFD; read content for other encodings. Raw content= bytes are sent without a Content-Type, as in httpx2.

    #Using mttp alongside

    Types that need no sugar are mttp's own: @mttp.Request, @mttp.Response, @mttp.Headers, @mttp.RetryPolicy, &@mttp.Backend. client.mttp() returns the mttp client underneath, and build_request gives the @mttp.Request a call would send. Typed endpoints, routers, OpenAPI and servers are mttp's; use it directly for those.

    #License

    Apache-2.0. See LICENSE.

    Part

    A part of a multipart body, for files: Part::file(name, filename,content_type, bytes) or Part::text(name, value).

    SseEvent

    A server-sent event, as StreamResponse::each_event passes it.

    HTTPError

    One suberror for every failure. The variants are httpx2's exception classes that can occur here, and the predicates stand in for its class tree. Transport variants keep the @mttp.TransportError they came from.
    impl Show for HTTPError

    HTTPError::is_network_error

    fn HTTPError::is_network_error(self : HTTPError) -> Bool

    httpx2's NetworkError branch: the connection could not be made or broke.

    HTTPError::is_request_error

    fn HTTPError::is_request_error(self : HTTPError) -> Bool

    httpx2's RequestError branch: every failure except HTTPStatusError.

    HTTPError::is_timeout

    fn HTTPError::is_timeout(self : HTTPError) -> Bool

    Whether a time limit ran out: a phase timeout or total_timeout.

    HTTPError::is_transport_error

    fn HTTPError::is_transport_error(self : HTTPError) -> Bool

    httpx2's TransportError branch: anything that went wrong on the wire.

    HTTPError::mttp

    The mttp error a transport variant came from.

    HTTPError::output

    fn HTTPError::output(self : HTTPError, logger : &Logger) -> Unit

    to_string and output as methods of HTTPError.

    HTTPError::to_string

    fn HTTPError::to_string(self : HTTPError) -> String

    to_string and output as methods of HTTPError.

    Auth

    pub(all) enum Auth {
    Basic(String, String)
    Bearer(String)
    Digest(String, String)
    }

    Credentials for a client's requests, or for one request.

    Client

    pub struct Client {
    // private fields
    }

    An mttp client plus the defaults requesto adds on top.

    Client::build_request

    fn Client::build_request(self : Client, verb : String, url : String, params? : Array[(String, String)], headers? : Array[(String, String)], content? : Bytes, text? : String, data? : Array[(String, String)], files? : Array[
    Part
    ], json? :
    Json
    , auth? : Auth) ->
    Request
    raise HTTPError

    httpx2's build_request: the @mttp.Request a call would send, with the client's base URL, query parameters and auth applied. One body argument is used, in this order: content, text, files (with data as its text fields), data (as a form), json.

    Client::close

    fn Client::close(self : Client) -> Unit

    Closes the client's connections.

    Client::delete

    async fn Client::delete(self : Client, url : String, params? : Array[(String, String)], headers? : Array[(String, String)], auth? : Auth, follow_redirects? : Bool) -> Response raise HTTPError

    A DELETE request; see Client::request.

    Client::get

    async fn Client::get(self : Client, url : String, params? : Array[(String, String)], headers? : Array[(String, String)], auth? : Auth, follow_redirects? : Bool) -> Response raise HTTPError

    A GET request; see Client::request.

    Client::head

    async fn Client::head(self : Client, url : String, params? : Array[(String, String)], headers? : Array[(String, String)], auth? : Auth, follow_redirects? : Bool) -> Response raise HTTPError

    A HEAD request; see Client::request.

    Client::mttp

    The mttp client underneath, for a call requesto does not cover.

    Client::new

    fn Client::new(base_url? : String, headers? : Array[(String, String)], params? : Array[(String, String)], cookies? : Bool, cookie_jar? :
    CookieJar
    , auth? : Auth, timeout? : Timeout, follow_redirects? : Bool, max_redirects? : Int, retry? :
    RetryPolicy
    , max_body_bytes? : Int, total_timeout? : Int, event_hooks? : EventHooks, limits? : Limits, proxy? : String, trust_env? : Bool, trust? :
    Trust
    , transport? : &
    Backend
    , clock? : &
    Clock
    , timer? : &
    Timer
    ) -> Client

    httpx2's defaults: redirects not followed, no retries, 5 s per phase, cookies kept, no deadline for the whole call, proxies from the environment. mttp adds one bound httpx2 lacks: buffered bodies are limited to max_body_bytes (64 MiB).

    • total_timeout (milliseconds) opts in to a deadline for the whole call, redirects and retries included. Without it a stalled connection still fails on its phase timeout; only a slow transfer that keeps making progress runs on, as in httpx2.
    • cookies gives the client a jar of its own; cookie_jar shares one the caller made, with @mttp.CookieJar::new, between clients.
    • retry takes an @mttp.RetryPolicy, such as RetryPolicy::conservative().
    • proxy sends every request through one proxy; otherwise, when trust_env holds, HTTP_PROXY, HTTPS_PROXY and NO_PROXY choose.
    • trust is httpx2's verify: System roots, a PemFile, or Insecure.
    • transport replaces the network, for a MockTransport or any @mttp.Backend; timeout's phases, limits, proxy, trust_env and trust configure only the network backend and are ignored then.
    • clock and timer replace the real ones, for tests on virtual time.

    Client::options

    async fn Client::options(self : Client, url : String, params? : Array[(String, String)], headers? : Array[(String, String)], auth? : Auth, follow_redirects? : Bool) -> Response raise HTTPError

    A OPTIONS request; see Client::request.

    Client::patch

    async fn Client::patch(self : Client, url : String, params? : Array[(String, String)], headers? : Array[(String, String)], content? : Bytes, text? : String, data? : Array[(String, String)], files? : Array[
    Part
    ], json? :
    Json
    , auth? : Auth, follow_redirects? : Bool) -> Response raise HTTPError

    A PATCH request with an optional body; see Client::request.

    Client::post

    async fn Client::post(self : Client, url : String, params? : Array[(String, String)], headers? : Array[(String, String)], content? : Bytes, text? : String, data? : Array[(String, String)], files? : Array[
    Part
    ], json? :
    Json
    , auth? : Auth, follow_redirects? : Bool) -> Response raise HTTPError

    A POST request with an optional body; see Client::request.

    Client::put

    async fn Client::put(self : Client, url : String, params? : Array[(String, String)], headers? : Array[(String, String)], content? : Bytes, text? : String, data? : Array[(String, String)], files? : Array[
    Part
    ], json? :
    Json
    , auth? : Auth, follow_redirects? : Bool) -> Response raise HTTPError

    A PUT request with an optional body; see Client::request.

    Client::request

    async fn Client::request(self : Client, verb : String, url : String, params? : Array[(String, String)], headers? : Array[(String, String)], content? : Bytes, text? : String, data? : Array[(String, String)], files? : Array[
    Part
    ], json? :
    Json
    , auth? : Auth, follow_redirects? : Bool) -> Response raise HTTPError

    Sends one request and reads its whole body, whatever the status. The body arguments are those of build_request.

    Client::send

    async fn Client::send(self : Client, req :
    Request
    , follow_redirects? : Bool) -> Response raise HTTPError

    httpx2's send: sends a built request and reads its whole body.

    Client::stream

    async fn[T] Client::stream(self : Client, verb : String, url : String, f : async (StreamResponse) -> T, params? : Array[(String, String)], headers? : Array[(String, String)], content? : Bytes, text? : String, data? : Array[(String, String)], files? : Array[
    Part
    ], json? :
    Json
    , auth? : Auth, follow_redirects? : Bool) -> T

    httpx2's with client.stream(...) as response:. The response is valid only inside f and is closed when f returns; errors from f come out unchanged. Request hooks run; response hooks do not, since the body is not read.

    EventHooks

    pub struct EventHooks {
    request : Array[(
    Request
    ) -> Unit raise HTTPError]
    response : Array[(Response) -> Unit raise HTTPError]
    }

    httpx2's event_hooks: functions that see each request before it is sent and each response before it is returned. A hook that raises fails the call. Hooks are plain functions, as on httpx2's sync Client, so a lambda can be written without annotations.

    EventHooks::new

    fn EventHooks::new(request? : Array[(
    Request
    ) -> Unit raise HTTPError], response? : Array[(Response) -> Unit raise HTTPError]) -> EventHooks

    Hooks run in order: request before each send, response after it.

    Limits

    pub(all) struct Limits {
    max_connections : Int?
    max_keepalive_connections : Int
    keepalive_expiry : Int
    }

    Connection pool limits, as httpx2's Limits: at most max_connections open (None for no limit), at most max_keepalive_connections idle, each idle one closed after keepalive_expiry milliseconds.

    Limits::new

    fn Limits::new(max_connections? : Int?, max_keepalive_connections? : Int, keepalive_expiry? : Int) -> Limits

    httpx2's defaults: 100 connections, 20 kept alive, for 5 s.

    MockTransport

    pub struct MockTransport {
    // private fields
    }

    httpx2's MockTransport: a transport that calls a handler instead of the network. The handler has the type of an mttp server handler, so an app served with @server.serve can be passed here and called without a socket (what httpx2's ASGITransport does).

    MockTransport::close

    fn MockTransport::close(self : MockTransport) -> Unit

    send and close as methods of MockTransport.

    MockTransport::new

    A transport that answers every request with handler.

    MockTransport::send

    send and close as methods of MockTransport.

    Response

    pub struct Response {
    status_code : Int
    headers :
    Headers

    url : String
    content : Bytes
    request :
    RequestHead

    history : Array[
    RedirectHop
    ]
    elapsed : Int64
    }

    A response with its body read. Every status is an ordinary response; raise_for_status turns the ones outside 200..=299 into an error.

    Response::is_client_error

    fn Response::is_client_error(self : Response) -> Bool

    Whether the status is 400..=499.

    Response::is_error

    fn Response::is_error(self : Response) -> Bool

    Whether the status is 400..=599.

    Response::is_informational

    fn Response::is_informational(self : Response) -> Bool

    Whether the status is 100..=199.

    Response::is_redirect

    fn Response::is_redirect(self : Response) -> Bool

    Whether the status is a redirect (301, 302, 303, 307 or 308) with a Location to follow.

    Response::is_server_error

    fn Response::is_server_error(self : Response) -> Bool

    Whether the status is 500..=599, as in httpx2. raise_for_status also raises for 600..=999, which mttp accepts as server failures.

    Response::is_success

    fn Response::is_success(self : Response) -> Bool

    Whether the status is 200..=299.

    Response::json

    The body parsed as JSON; DecodingError if it is not JSON.

    Response::json_as

    The body decoded from JSON into T; DecodingError if it does not fit.

    Response::raise_for_status

    fn Response::raise_for_status(self : Response) -> Response raise HTTPError

    Raises HTTPStatusError for any status outside 200..=299, as httpx2 does; otherwise returns the response so calls can chain.

    Response::reason_phrase

    fn Response::reason_phrase(self : Response) -> String

    The standard reason phrase for the status, or "" for one without.

    Response::text

    fn Response::text(self : Response) -> String

    The body as UTF-8, malformed sequences replaced with U+FFFD.

    StreamResponse

    pub struct StreamResponse {
    status_code : Int
    headers :
    Headers

    url : String
    request :
    RequestHead

    // private fields
    }

    A response whose body is still on the connection. It is valid only inside the function passed to stream, and is closed when that function returns.

    StreamResponse::each_bytes

    async fn StreamResponse::each_bytes(self : StreamResponse, f : async (Bytes) -> Unit) -> Unit

    httpx2's iter_bytes: calls f with each chunk as it arrives. Errors from f come out unchanged.

    StreamResponse::each_event

    async fn StreamResponse::each_event(self : StreamResponse, f : async (
    SseEvent
    ) -> Unit, max_event_bytes? : Int) -> Unit

    Calls f with each server-sent event as it arrives (what httpx-sse's iter_sse does). An event longer than max_event_bytes (16 MiB by default) closes the body and raises TooLarge.

    StreamResponse::each_line

    async fn StreamResponse::each_line(self : StreamResponse, f : async (String) -> Unit, max_line_bytes? : Int) -> Unit

    httpx2's iter_lines: calls f with each line, without its \n or \r\n, decoded as UTF-8 with malformed sequences replaced. A line longer than max_line_bytes (1 MiB by default) closes the body and raises TooLarge after the lines before it.

    StreamResponse::is_success

    fn StreamResponse::is_success(self : StreamResponse) -> Bool

    Whether the status is 200..=299.

    StreamResponse::raise_for_status

    fn StreamResponse::raise_for_status(self : StreamResponse) -> StreamResponse raise HTTPError

    Raises HTTPStatusError outside 200..=299, carrying the head and an empty body (the body stays unread); otherwise returns the response.

    StreamResponse::read

    async fn StreamResponse::read(self : StreamResponse) -> Bytes raise HTTPError

    Reads the rest of the body, up to the client's max_body_bytes; a longer body raises TooLarge.

    Timeout

    pub(all) struct Timeout {
    connect : Int?
    read : Int?
    write : Int?
    pool : Int?
    }

    Per-phase time limits in milliseconds, as httpx2's Timeout. None means no limit for that phase.

    Timeout::new

    fn Timeout::new(all : Int?, connect? : Int?, read? : Int?, write? : Int?, pool? : Int?) -> Timeout

    Timeout::new(Some(5000)) limits every phase to 5 s; name a phase to set it apart, as in httpx2's Timeout(10.0, connect=5.0).

    delete

    async fn delete(url : String, params? : Array[(String, String)], headers? : Array[(String, String)], auth? : Auth, follow_redirects? : Bool, timeout? : Timeout) -> Response raise HTTPError

    One DELETE request on a client made and closed for this call, as httpx2.delete.

    get

    async fn get(url : String, params? : Array[(String, String)], headers? : Array[(String, String)], auth? : Auth, follow_redirects? : Bool, timeout? : Timeout) -> Response raise HTTPError

    One GET request on a client made and closed for this call, as httpx2.get.
    async fn head(url : String, params? : Array[(String, String)], headers? : Array[(String, String)], auth? : Auth, follow_redirects? : Bool, timeout? : Timeout) -> Response raise HTTPError

    One HEAD request on a client made and closed for this call, as httpx2.head.

    options

    async fn options(url : String, params? : Array[(String, String)], headers? : Array[(String, String)], auth? : Auth, follow_redirects? : Bool, timeout? : Timeout) -> Response raise HTTPError

    One OPTIONS request on a client made and closed for this call, as httpx2.options.

    patch

    async fn patch(url : String, params? : Array[(String, String)], headers? : Array[(String, String)], content? : Bytes, text? : String, data? : Array[(String, String)], files? : Array[
    Part
    ], json? :
    Json
    , auth? : Auth, follow_redirects? : Bool, timeout? : Timeout) -> Response raise HTTPError

    One PATCH request on a client made and closed for this call, as httpx2.patch.

    post

    async fn post(url : String, params? : Array[(String, String)], headers? : Array[(String, String)], content? : Bytes, text? : String, data? : Array[(String, String)], files? : Array[
    Part
    ], json? :
    Json
    , auth? : Auth, follow_redirects? : Bool, timeout? : Timeout) -> Response raise HTTPError

    One POST request on a client made and closed for this call, as httpx2.post.

    put

    async fn put(url : String, params? : Array[(String, String)], headers? : Array[(String, String)], content? : Bytes, text? : String, data? : Array[(String, String)], files? : Array[
    Part
    ], json? :
    Json
    , auth? : Auth, follow_redirects? : Bool, timeout? : Timeout) -> Response raise HTTPError

    One PUT request on a client made and closed for this call, as httpx2.put.

    request

    async fn request(verb : String, url : String, params? : Array[(String, String)], headers? : Array[(String, String)], content? : Bytes, text? : String, data? : Array[(String, String)], files? : Array[
    Part
    ], json? :
    Json
    , auth? : Auth, follow_redirects? : Bool, timeout? : Timeout) -> Response raise HTTPError

    One request on a client made and closed for this call, as httpx2.request.

    stream

    async fn[T] stream(verb : String, url : String, f : async (StreamResponse) -> T, params? : Array[(String, String)], headers? : Array[(String, String)], content? : Bytes, text? : String, data? : Array[(String, String)], files? : Array[
    Part
    ], json? :
    Json
    , auth? : Auth, follow_redirects? : Bool, timeout? : Timeout) -> T

    One streamed request on a client made and closed for this call, as httpx2.stream; see Client::stream.