🥮 mooncakes.io

mio

Best async http library for Moonbit

network
async
http
moon add oboard/mio@0.5.2
Download zip
Author
Version
0.5.2
License
Apache-2.0
Repository
Last updated
3 months ago
Downloads
459

Dependencies

README

#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:

{
  "deps": {
    "oboard/mio": "0.5.0"
  }
}

#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
}
async fn Client::Client(uri : String, headers? : Map[String, String], proxy? : Client, verify? : Bool) -> Client

impl Reader for Client
impl Writer for 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::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::new

source

#
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)
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::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::new

source

#
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