🥮 mooncakes.io

    mio

    Best async http library for Moonbit

    network
    async
    http
    Download zip
    Author
    Version
    0.5.4
    License
    Apache-2.0
    Repository
    Last updated
    last month
    Downloads
    555

    Dependencies

    #oboard/mio

    A MoonBit HTTP networking library with native HTTP/1.1, experimental HTTP/2 and HTTP/3 transports, and JavaScript Fetch support.

    Version License

    #Features

    • 🚀 Async support: Request APIs are async on native and JavaScript targets.
    • 🌐 HTTP methods: GET, POST, PUT, DELETE, PATCH, OPTIONS, HEAD, CONNECT, and TRACE are represented by RequestMethod.
    • 📄 Response helpers: Read response bodies as binary, text, or JSON.
    • 🌊 Streaming HTTP/1.1: Native stream APIs expose request/response bodies through @io.Reader and @io.Writer.
    • 📦 Compression: Native responses can decode gzip, deflate, br, and zstd content encodings.
    • 🎯 Multi-backend: Native uses MoonBit transports; JavaScript uses the platform Fetch implementation.
    • 🔧 Builder options: Configure default headers, timeout, protocol mode, proxy, and certificate verification.

    #Installation

    Add to your moon.mod.json:

    moon add oboard/mio

    #Quick Start

    #Basic GET Request

    let response = @mio.get("https://api.github.com") catch {
        Err(e) => println("Error: " + e.to_string())
    }
    println("Response: " + response.text())

    #Request Builder

    ///|
    let client = @mio.RequestClient::builder()
      .default_header("User-Agent", "mio")
      .timeout(10000)
      .build()

    ///|
    let response = client
      .post("https://api.example.com/items")
      .json({ "name": "moonbit" })
      .send()

    #HTTP/2 Prior Knowledge

    ///|
    let client = @mio.RequestClient::builder()
      .http2_prior_knowledge()
      .timeout(10000)
      .build()

    ///|
    let response = client.get("http://localhost:3000/").send()
    println(response.text())

    #HTTP/3 Prior Knowledge

    ///|
    let client = @mio.RequestClient::builder()
      .http3_prior_knowledge()
      .timeout(10000)
      .build()

    ///|
    let response = client.get("https://example.com/").send()
    println(response.text())

    danger_accept_invalid_certs(true) disables certificate and hostname verification. It is intended for local testing only.

    #Protocol Support

    ModeNative statusNotes
    HTTP/1.1SupportedDirect TCP/TLS transport with streaming APIs.
    HTTP/2ExperimentalPrior-knowledge client, HPACK, SETTINGS/HEADERS/DATA, PING, WINDOW_UPDATE, and GOAWAY handling.
    HTTP/3ExperimentalUDP QUIC path with X25519, TLS 1.3 ServerHello, EncryptedExtensions, Finished, QUIC Retry, Handshake ACKs, H3 SETTINGS, request streams, and response decoding.
    JavaScriptRuntime-managedUses Fetch; protocol negotiation is handled by the host runtime.

    HTTP/2 and HTTP/3 are currently single-request transports. They do not yet provide a hyper-style connection task, connection pooling, multiplexed request scheduling, broad retransmission/loss recovery, or full certificate-chain validation.

    #Hyper Comparison

    hyper separates an established connection into a request sender and a connection future that continuously drives protocol state. mio currently keeps HTTP/2 and HTTP/3 as compact single-request loops. The implementation is moving toward the same separation of concerns:

    • request construction is handled by RequestClient and RequestBuilder;
    • protocol-specific transports live in HTTP/2 and HTTP/3 modules;
    • connection state such as QUIC packet number spaces, Retry handling, and TLS transcript state is kept below the request API.

    Unlike hyper, this package includes a MoonBit-native experimental QUIC/TLS 1.3/HTTP/3 path. That path is intentionally conservative and still needs more transport work before it should be treated as production-ready.

    #Contributing

    1. Fork the repository
    2. Create your feature branch (git checkout -b feature/amazing-feature)
    3. Commit your changes (git commit -m 'Add amazing feature')
    4. Push to the branch (git push origin feature/amazing-feature)
    5. Open a Pull Request

    #License

    This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

    HpackError

    source
    pub suberror HpackError {
      HpackBadInteger
      HpackBadString
      HpackBadHuffmanPadding
      HpackHuffmanEOS
      HpackBadIndex(Int)
      HpackBadDynamicTableSize(Int)
    } derive(ToJson, 
    Debug    )

    Http2Error

    source
    pub suberror Http2Error {
      Http2BadFrame
      Http2ConnectionError(String)
      Http2StreamReset(Int)
      Http2MissingStatus
    } derive(ToJson, 
    Debug    )

    HttpProtocolError

    source
    pub suberror HttpProtocolError {
      BadRequest
      HttpVersionNotSupported(String)
      NotImplemented
    } derive(ToJson, 
    Debug    )

    IncorrectBodyLength

    source
    pub suberror IncorrectBodyLength derive(ToJson, 
    Debug    )

    ProxyError

    source
    pub suberror ProxyError {
      ProxyError(Response)
    } derive(ToJson, 
    Debug    )

    impl Show for ProxyError

    RequestError

    source
    pub suberror RequestError {
      UnsupportedHttpVersion(HttpVersion)
    } derive(ToJson, 
    Debug    )

    URIParseError

    source
    pub suberror URIParseError {
      InvalidFormat
      UnsupportedProtocol(String)
    } derive(ToJson, 
    Debug    )

    Client

    source
    pub struct Client {
      // private fields
    }

    impl Reader for Client
    impl Writer for Client

    Client::Client

    source
    async fn Client::Client(uri : String, headers? : Map[String, String], proxy? : Client, verify? : Bool) -> Client

    Client::close

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

    Client::end_request

    source
    async fn Client::end_request(self : Client) -> Response

    Client::enter_passthrough_mode

    source
    async fn Client::enter_passthrough_mode(self : Client) -> Unit

    Client::flush

    source
    async fn Client::flush(self : Client) -> Unit

    Client::get

    source
    async fn Client::get(self : Client, path : String, extra_headers? : Map[String, String], body? : &
    Data    ) -> Response

    Client::new

    source
    async fn Client::new(uri : String, headers? : Map[String, String], proxy? : Client, verify? : Bool) -> Client

    Client::post

    source
    async fn Client::post(self : Client, path : String, body : &
    Data    , extra_headers? : Map[String, String]) -> Response

    Client::put

    source
    async fn Client::put(self : Client, path : String, body : &
    Data    , extra_headers? : Map[String, String]) -> Response

    Client::request

    source
    async fn Client::request(self : Client, meth : RequestMethod, path : String, extra_headers? : Map[String, String]) -> Unit

    Client::skip_response_body

    source
    async fn Client::skip_response_body(self : Client) -> Unit

    ClientBuilder

    source
    pub struct ClientBuilder {
      headers : Map[String, String]
      proxy : Client?
      timeout : Int?
      version : HttpVersion
      verify : Bool
    }

    ClientBuilder::ClientBuilder

    source
    #alias(new)
    fn ClientBuilder::ClientBuilder() -> ClientBuilder

    ClientBuilder::build

    source

    ClientBuilder::danger_accept_invalid_certs

    source
    fn ClientBuilder::danger_accept_invalid_certs(self : ClientBuilder, enabled : Bool) -> ClientBuilder

    ClientBuilder::default_header

    source
    fn ClientBuilder::default_header(self : ClientBuilder, key : String, value : String) -> ClientBuilder

    ClientBuilder::default_headers

    source
    fn ClientBuilder::default_headers(self : ClientBuilder, headers : Map[String, String]) -> ClientBuilder

    ClientBuilder::http1_only

    source
    fn ClientBuilder::http1_only(self : ClientBuilder) -> ClientBuilder

    ClientBuilder::http2_prior_knowledge

    source
    fn ClientBuilder::http2_prior_knowledge(self : ClientBuilder) -> ClientBuilder

    ClientBuilder::http3_prior_knowledge

    source
    fn ClientBuilder::http3_prior_knowledge(self : ClientBuilder) -> ClientBuilder

    ClientBuilder::proxy

    source
    fn ClientBuilder::proxy(self : ClientBuilder, proxy : Client) -> ClientBuilder

    ClientBuilder::timeout

    source
    fn ClientBuilder::timeout(self : ClientBuilder, millis : Int) -> ClientBuilder

    pub struct Cookie {
      name : String
      value : String
      path : String?
      expires_raw : String?
      max_age : Int64?
      domain : String?
      secure : Bool
      http_only : Bool
      extensions : Array[String]
    } derive(ToJson, 
    Debug    )

    Cookie::Cookie

    source
    fn Cookie::Cookie(name : String, value : String, path? : String, expires_raw? : String, max_age? : Int64, domain? : String, secure? : Bool, http_only? : Bool, extensions? : Array[String]) -> Cookie

    Cookie::new

    source
    fn Cookie::new(name : String, value : String, path? : String, expires_raw? : String, max_age? : Int64, domain? : String, secure? : Bool, http_only? : Bool, extensions? : Array[String]) -> Cookie

    HttpVersion

    source
    pub(all) enum HttpVersion {
      Http1
      Http2
      Http3
    } derive(Compare, Eq, Hash, ToJson, 
    Debug    )

    Protocol

    source
    pub(all) enum Protocol {
      Http
      Https
    } derive(Compare, Eq, Hash, ToJson, 
    Debug    )

    impl Show for Protocol

    Protocol::default_port

    source
    fn Protocol::default_port(p : Protocol) -> Int

    RequestBuilder

    source
    pub struct RequestBuilder {
      client : RequestClient
      meth : RequestMethod
      uri : String
      headers : Map[String, String]
      body : &
    Data
    }

    RequestBuilder::body

    source

    RequestBuilder::header

    source
    fn RequestBuilder::header(self : RequestBuilder, key : String, value : String) -> RequestBuilder

    RequestBuilder::headers

    source
    fn RequestBuilder::headers(self : RequestBuilder, headers : Map[String, String]) -> RequestBuilder

    RequestBuilder::json

    source
    fn RequestBuilder::json(self : RequestBuilder, value : Json) -> RequestBuilder

    RequestBuilder::send

    source
    async fn RequestBuilder::send(self : RequestBuilder) -> ResponseBody

    RequestClient

    source
    pub struct RequestClient {
      headers : Map[String, String]
      proxy : Client?
      timeout : Int?
      version : HttpVersion
      verify : Bool
    }

    RequestClient::RequestClient

    source
    #alias(new)
    fn RequestClient::RequestClient() -> RequestClient

    RequestClient::builder

    source
    fn RequestClient::builder() -> ClientBuilder

    RequestClient::delete

    source
    fn RequestClient::delete(self : RequestClient, uri : String) -> RequestBuilder

    RequestClient::get

    source
    fn RequestClient::get(self : RequestClient, uri : String) -> RequestBuilder

    RequestClient::head

    source
    fn RequestClient::head(self : RequestClient, uri : String) -> RequestBuilder

    RequestClient::options

    source
    fn RequestClient::options(self : RequestClient, uri : String) -> RequestBuilder

    RequestClient::patch

    source
    fn RequestClient::patch(self : RequestClient, uri : String) -> RequestBuilder

    RequestClient::post

    source
    fn RequestClient::post(self : RequestClient, uri : String) -> RequestBuilder

    RequestClient::put

    source
    fn RequestClient::put(self : RequestClient, uri : String) -> RequestBuilder

    RequestClient::request

    source
    fn RequestClient::request(self : RequestClient, meth : RequestMethod, uri : String) -> RequestBuilder

    RequestMethod

    source
    pub(all) enum RequestMethod {
      Get
      Head
      Post
      Put
      Delete
      Connect
      Options
      Trace
      Patch
    } derive(Compare, Eq, Hash, ToJson, 
    Debug    )

    Response

    source
    pub(all) struct Response {
      code : Int
      reason : String
      headers : Map[String, String]
      cookies : Array[Cookie]
    } derive(ToJson, 
    Debug    )

    impl Show for Response

    ResponseBody

    source
    pub(all) struct ResponseBody {
      response : Response
      body : &
    Data
    }

    ResponseBody::binary

    source
    fn ResponseBody::binary(self : ResponseBody) -> Bytes

    ResponseBody::json

    source
    fn ResponseBody::json(self : ResponseBody) -> Json raise

    ResponseBody::text

    source
    fn ResponseBody::text(self : ResponseBody) -> String raise

    delete

    source
    async fn delete(uri : String, headers? : Map[String, String], body? : &
    Data    , proxy? : Client) -> ResponseBody

    Similar to get, but performs a DELETE request instead.

    get

    source
    async fn get(uri : String, headers? : Map[String, String], body? : &
    Data    , proxy? : Client) -> ResponseBody

    Perform a HTTP GET request to uri. Supported protocols are http:// and https://. The HTTP response message and the whole response body will be returned.

    proxy, if present, specifies the proxy to use for this request. See @http.Client::new for more details. proxy is not supported on JavaScript backend.

    See Client::request for more details.

    get_stream

    source
    async fn get_stream(uri : String, headers? : Map[String, String], body? : &
    Data    , proxy? : Client) -> (Response, Client)

    Similar to @http.get, but allow reading response body streamingly. A pair (response, client) will be returned, where response is the response header from the server, and client is the HTTP client that performs the request. client can be used to read the content of response body via @io.Reader, see @http.Client for more details.

    Note that the returned client must be manually closed via .close() to close the underlying connection used for the request.
    async fn head(uri : String, headers? : Map[String, String], proxy? : Client) -> ResponseBody

    Similar to get, but performs a HEAD request instead.

    options

    source
    async fn options(uri : String, headers? : Map[String, String], body? : &
    Data    , proxy? : Client) -> ResponseBody

    Similar to get, but performs an OPTIONS request instead.

    patch

    source
    async fn patch(uri : String, content : &
    Data    , headers? : Map[String, String], proxy? : Client) -> ResponseBody

    Similar to get, but performs a PATCH request instead.

    post

    source
    async fn post(uri : String, content : &
    Data    , headers? : Map[String, String], proxy? : Client) -> ResponseBody

    Similar to get, but performs a POST request instead.

    post_stream

    source
    async fn post_stream(uri : String, headers? : Map[String, String], proxy? : Client) -> Client

    Similar to @http.post, but allow writing request body streamingly. The return value client is the HTTP client that performs the request, it can be used to write the content of request body via @io.Writer. Notice that writing to @http.Client is buffered, so if you need to send data to the server immediately, .flush() must be called. After writing all the content, .end_request() must be called to complete the request and obtain response from the server. After that, the response body from the server can be obtained by using client as a @io.Reader. See @http.Client for more details.

    Note that the returned client must be manually closed via .close() to close the underlying connection used for the request.

    put

    source
    async fn put(uri : String, content : &
    Data    , headers? : Map[String, String], proxy? : Client) -> ResponseBody

    Similar to get, but performs a PUT request instead.

    put_stream

    source
    async fn put_stream(uri : String, headers? : Map[String, String], proxy? : Client) -> Client

    Similar to @http.put, but allow writing request body streamingly. The return value client is the HTTP client that performs the request, it can be used to write the content of request body via @io.Writer. Notice that writing to @http.Client is buffered, so if you need to send data to the server immediately, .flush() must be called. After writing all the content, .end_request() must be called to complete the request and obtain response from the server. After that, the response body from the server can be obtained by using client as a @io.Reader. See @http.Client for more details.

    Note that the returned client must be manually closed via .close() to close the underlying connection used for the request.

    Source Files

    Powered by MoonBit

    Site sourceReport issuePackagesBuild queueSkillsStatistics

    © 2026 mooncakes.io