🥮 mooncakes.io
    HTTP support for moonbitlang/core/async.

    #Making simple HTTP request

    Simple HTTP request can be made in just one line:

    ///|
    #cfg(any(target="native", target="js"))
    async test {
      let (response, body) = @http.get_text("https://www.moonbitlang.com")
      inspect(response.code, content="200")
      assert_true(body.has_prefix("<!doctype html>"))
    }

    Use @http.get_text() to get a UTF-8-decoded String, @http.get_binary() to get raw Bytes, or @http.get_json() to get Json.

    #Streaming message body

    For HTTP messages with large body, collecting the whole body in memory could be a bad idea. The @http package also provide convenient API for manipulating message body streamingly:

    ///|
    #cfg(any(target="native", target="js"))
    async test {
      let (response, conn) = @http.get("https://www.moonbitlang.com")
      defer conn.close()
      inspect(response.code, content="200")
      let body = conn.text.read_all()
      assert_true(body.has_prefix("<!doctype html>"))
    }

    Here, @http.get(url) performs a GET request to URL, and returns the response header from the server, plus the HTTP connection assigned for this request. The content of response body can be read from the connection through the @io.BinaryReader interface, or through the @io.TextReader interface using the .text view on the connection. The connection must be closed via .close() after finishing the request.

    @http.put and @http.post work similarly, except that the response header will not be returned immediately. @http.put and @http.post only returns the HTTP connection for the request. The caller should first write the content of request body through the @io.BinaryWriter interface on the connection (or through the @io.TextWriter interface via .text). After finishing the request body, .end_request should be invoked on the connection to finish the request and obtain response header from the server. After .end_request, body of response message can be read from the connection as in the @http.get case above.

    #Generic HTTP client

    When performing multiple requests to the same host, sharing and reusing HTTP connection can save a lot of resource. The generic @http.Client type provides connection pool backed HTTP client support. A HTTP client can be created via @http.Client(..) and must be closed via .close(). Users can perform requests through the client via .request(..), .get(..) etc., the semantic of these methods are similar to @http.request(..), @http.get(..) etc., except that they can reuse the client's existing connections to save resource. Multiple requests can be performed on the same client concurrently, the client will automatically create new connection if necessary to fulfill requests.

    note: currently the @http.Client is just a placeholder that create a new connection for every request. Proper connection pool support will be implemented in the near future.

    #JavaScript compatibility

    All HTTP client API, including the toplevel @http.xxx helpers and the generic @http.Client type, has browser-compatible JavaScript backend support using fetch API, Notice that some feature, such as proxy and streaming request body building, are not supported on JavaScript backend due to limitation of fetch API.

    #Writing HTTP servers

    The recommended way to create HTTP servers is @http.Server::run_forever(..). A HTTP server should first get created via @http.Server(..), after that, server.run_forever(f) automatically start and run the server. The callback function f is used to handle HTTP requests. It receives three parameters:

    • the request to process
    • a @http.ServerConnection that can be used to read request body or send response.

    Content of the incoming request body can be read streamingly using @io.BinaryReader interface (or @io.TextReader interface through the builtin .text view) on the @http.ServerConnection directly.

    The procedure to send a response is:
    1. initiate a response and send response header via .send_response()
    2. send response body by using the @http.ServerConnection as @io.BinaryWriter. Text content can be written directly via conn.text through the @io.TextWriter interface as well
    3. (optional) complete the response via .end_response(). If .end_response() is not called, it will be called automatically after f returns normally.

    Here's an example server that returns 404 to every request:

    ///|
    /// A simple HTTP server that return 404 for every request
    #cfg(target="native")
    pub async fn server(listen_addr : @socket.Addr) -> Unit {
      @http.Server(listen_addr).run_forever((request, conn) => {
        conn.send_response(404, "NotFound")
        conn.text.write("`\{request.path}` not found")
      })
    }

    Headers

    source
    type Headers = Map[CaseInsensitiveString, String]

    Type for HTTP headers. The names of headers are case insensitive.

    The RFC requires that multiple header entries with the same name should be semantically equivalent to concatenating values with comma, so a Map with unique keys can be used to represent headers.

    One important exception to the above rule is the Set-Cookie header, which is handled specially via the Cookie type.

    HttpProtocolError

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

    Error raised when an invalid HTTP message is processed

    IncorrectBodyLength

    source

    Error raised when the user is sending a fixed length HTTP message body, but the actual length of the message body is incorrect.

    InvalidMethod

    source
    pub(all) suberror InvalidMethod {
      InvalidMethod(String)
    } derive(
    Debug    , 
    ToJson    )

    Error raised when an invalid extension method (i.e. not valid HTTP method name) is supplied when sending a HTTP request

    ProxyError

    source

    Error raised when the proxy responded with a non-2XX response code

    UriParseError

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

    Error raised when an invalid URI is specified

    CaseInsensitiveString

    source
    pub(all) struct CaseInsensitiveString(String) derive(
    ToJson    )

    String type with case insensitive comparison (in the ASCII sense). This type is implicitly convertible from String & string literal.

    CaseInsensitiveString::to_string

    source
    fn CaseInsensitiveString::to_string(self : CaseInsensitiveString) -> String

    Client

    source
    type Client

    A generic HTTP client

    Client::Client

    source
    fn Client::Client(headers? : Map[CaseInsensitiveString, String]) -> Client

    Create a new HTTP client.

    headers, if present, set common headers for all requests going through this client. The ownership of headers will be transferred to the new client, so headers should not be used by the caller later. The following headers is automatically set, and must not be specified in headers:

    • Host
    • Content-Encoding, Transfer-Encoding

    Client::close

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

    Close a HTTP client, release associated resource

    Client::get

    source
    async fn Client::get(self : Client, url : StringView, extra_headers? : Map[CaseInsensitiveString, String]) -> (ResponseHeader, ClientConnection)

    Perform a GET request on url through a HTTP client. Return the response header and the client connection assigned for the request. Content of response body can be read through the @io.BinaryReader interface (or @io.TextReader interface through the builtin .text view) on the connection. The connection must be closed after the connection become unused.

    See @http.Client::request for more details on the optional parameters.

    Client::get_binary

    source
    async fn Client::get_binary(self : Client, uri : StringView, extra_headers? : Map[CaseInsensitiveString, String]) -> (ResponseHeader, Bytes)

    Perform a HTTP GET request to uri, collect response body as plain binary automatically.

    See @http.Client::request for more details.

    Client::get_json

    source
    async fn Client::get_json(self : Client, uri : StringView, extra_headers? : Map[CaseInsensitiveString, String]) -> (ResponseHeader, 
    Json    )

    Perform a HTTP GET request to uri, collect response body as UTF-8 encoded JSON automatically.

    See @http.Client::request for more details.

    Client::get_text

    source
    async fn Client::get_text(self : Client, uri : StringView, extra_headers? : Map[CaseInsensitiveString, String]) -> (ResponseHeader, String)

    Perform a HTTP GET request to uri, collect response body as UTF-8 encoded text automatically.

    See @http.Client::request for more details.

    Client::post

    source
    async fn Client::post(self : Client, url : StringView, extra_headers? : Map[CaseInsensitiveString, String]) -> ClientConnection

    Perform a POST request on url through a HTTP client. Return the client connection assigned for this request. Request body can be written through the @io.BinaryWriter interface on the connection, or through the @io.TextWriter interface using the builtin .text view on the connection. When the request body is completely written, end_request() should be called on the connection to terminate the request and obtain response header from the server. After receiving the response header, Response body can be read through the @io.BinaryReader interface (or @io.TextReader interface through the builtin .text view) on the connection. The connection must be closed after the connection become unused.

    See @http.Client::request for more details on the optional parameters.

    Client::put

    source
    async fn Client::put(self : Client, url : StringView, extra_headers? : Map[CaseInsensitiveString, String]) -> ClientConnection

    Perform a PUT request on url through a HTTP client. Return the client connection assigned for this request. Request body can be written through the @io.BinaryWriter interface on the connection, or through the @io.TextWriter interface using the builtin .text view on the connection. When the request body is completely written, end_request() should be called on the connection to terminate the request and obtain response header from the server. After receiving the response header, Response body can be read through the @io.BinaryReader interface (or @io.TextReader interface through the builtin .text view) on the connection. The connection must be closed after the connection become unused.

    See @http.Client::request for more details on the optional parameters.

    Client::request

    source
    async fn Client::request(self : Client, meth : RequestMethod, url : StringView, extra_headers? : Map[CaseInsensitiveString, String]) -> ClientConnection

    Make a request using a HTTP client. meth specifies the request method and url specifies the target URL of request. Currently only http and https protocols are supported.

    The client will find or allocate a new network connection to fulfill the request. If the request is sent successfully, that connection will be returned. Subsequent workflow with the returned connection is as follows:
    1. request message body can be written to the connection through @io.BinaryWriter interface (or @io.TextWriter interface through the builtin .text view on the connection)
    2. after finish writing all request body content, .end_request() should be invoked on the connection to finish the request and obtain the response header
    3. after obtaining the response header, content of response body can be read through the @io.BinaryReader interface (or @io.TextReader interface through the builtin .text view) on the connection
    4. after finishing the whole request, .close() must be called on the connection to return it to the client

    In addition to common headers specified on client creation, extra HTTP headers can be passed via extra_headers. In addition to the forbidden headers in @http.Client(..), User-Agent must not be specified in extra_headers: it can only be specified on client creation.

    If Content-Length is present in extra_headers, it should be the total length of the request body. The request body can still be sent incrementally, but if the actual body being sent is shorter and longer than the provided length, an error will be raised.

    ClientConnection

    source
    pub struct ClientConnection {
      text : 
    Utf8TextView
      // private fields
    }

    Simple HTTP client which connect to a remote host via TCP

    ClientConnection::ClientConnection

    source
    #alias(new, deprecated="`new` is deprecated, use `ClientConnection` instead")
    async fn ClientConnection::ClientConnection(uri : String, headers? : Map[CaseInsensitiveString, String], proxy? : ClientConnection, trust? : 
    TrustedRoot    ) -> ClientConnection

    Create a new HTTP client by connecting to a remote host. Host should be specified via protocol://host[:port], where protocol is one of http or https. If protocol is https, a TLS connection will be established, and the certificate of the remote peer will be verified.

    If the protocol is https, trust will determine the trusted root for cert validation. See @tls.TrustedRoot for more details.

    headers can be used to specify persistent headers for the client, i.e. all requests made from this client will share these headers. The ownership of headers will be transferred to the new client, so headers should not be used by the caller later. The following headers is automatically set, and must not be specified in headers:

    • Host
    • Content-Length, Transfer-Encoding

    If proxy is present, it should be another HTTP client in a clean state. The new client will send a CONNECT request via the proxy client and try to establish a tunnel via the proxy client. All subsequent requests made by the new client will go through the proxy tunnel. The ownership of the proxy client is transferred to the new client, so it must not be used nor closed anymore by the caller. Using another HTTP client as proxy allows advanced features such as proxy authentication and https CONNECT proxy.

    ClientConnection::close

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

    Close a HTTP client and release underlying resource. In particular close the underlying TCP connection. This function is idempotent: it is safe to call .close() multiple times, only the first .close() call takes effect.

    ClientConnection::drop_all

    source
    async fn ClientConnection::drop_all(self : ClientConnection) -> Int64

    ClientConnection::drop_exactly

    source
    async fn ClientConnection::drop_exactly(self : ClientConnection, len : Int) -> Unit

    ClientConnection::end_request

    source
    async fn ClientConnection::end_request(self : ClientConnection, on_informational_response? : async (ResponseHeader) -> Unit) -> ResponseHeader

    End the body of the request currently being sent, and obtain response from the server. Should be called immediately after request body is fully sent.

    Only the header of the response will be received and returned, the response body can be read through ClientConnection as an @io.BinaryReader, or through client.text as an @io.TextReader.

    If the body of the last response is still not consumed, it will be discarded.

    1XX response, except for 101 Switching Protocol, will be automatically processed and discarded, and the returned response is always the final response (or 101). on_informational_response, if present, will be invoked for every skipped 1XX informational response.

    ClientConnection::enter_passthrough_mode

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

    Let the client enter "pass through" mode, where the client serve as a TCP tunnel (maybe TLS encrypted) directly. This is useful for the special CONNECT HTTP request and HTTP protocol upgrade.

    In passthrough mode, Read/write the client becomes direct read/write on the underlying connection, and only its @io.BinaryReader and @io.BinaryWriter APIs may be used.

    When entering pass through mode, the client must be in a clean state (i.e. not in the middle of sending a request). Unread data from the body of the last response will be discarded.

    ClientConnection::flush

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

    Flush buffered data in the request body being sent, if any.

    ClientConnection::peek

    source
    async fn ClientConnection::peek(self : ClientConnection) -> BytesView?

    ClientConnection::peek_at_least

    source
    async fn ClientConnection::peek_at_least(self : ClientConnection, min_len : Int) -> BytesView

    ClientConnection::peek_exactly

    source
    async fn ClientConnection::peek_exactly(self : ClientConnection, len : Int) -> BytesView

    ClientConnection::peek_until

    source
    async fn ClientConnection::peek_until(self : ClientConnection, pattern : BytesView, include_delimiter? : Bool) -> BytesView?

    ClientConnection::read

    source
    async fn ClientConnection::read(self : ClientConnection) -> Bytes?

    ClientConnection::read_all

    source
    async fn ClientConnection::read_all(self : ClientConnection) -> Bytes

    ClientConnection::read_at_least

    source
    async fn ClientConnection::read_at_least(self : ClientConnection, min_len : Int) -> Bytes

    ClientConnection::read_exactly

    source
    async fn ClientConnection::read_exactly(self : ClientConnection, len : Int) -> Bytes

    ClientConnection::read_into

    source
    async fn ClientConnection::read_into(self : ClientConnection, dst : FixedArray[Byte], offset? : Int, max_len? : Int) -> Int

    ClientConnection::read_until

    source
    async fn ClientConnection::read_until(self : ClientConnection, pattern : BytesView, include_delimiter? : Bool) -> Bytes?

    ClientConnection::request

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

    Send a HTTP request to the server. Only the header of the request will be sent, the request body can be sent through ClientConnection as an @io.BinaryWriter, or through client.text as an @io.TextWriter. Once request body has been sent, end_request must be called to complete the request and obtain response from the server.

    After performing a request, the next request MUST NOT be made before the request is completed via end_request.

    In addition to headers in ClientConnection::connect, extra HTTP headers can be passed via extra_headers. The following headers is automatically set by request, and must not be specified in extra_headers:

    • Host
    • Transfer-Encoding

    The following headers can only be set globally for each client on initialization, and must not be set on a per-request basis:

    • User-Agent

    If Content-Length is present in extra_headers, it should be the total length of the request body. The request body can still be sent incrementally, but if the actual body being sent is shorter and longer than the provided length, an error will be raised.

    ClientConnection::skip_response_body

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

    Skip the body of the response currently being produced, so that the next request can be made.

    ClientConnection::trailer

    source

    Get the trailer of current response message.

    MUST be called AFTER all content of current message body has been read, and BEFORE reading the next response, otherwise this method will crash immediately.

    If the message is not chunk encoded, an empty header map will be returned.

    ClientConnection::write

    source
    async fn ClientConnection::write(self : ClientConnection, data : BytesView) -> Unit

    ClientConnection::write_reader

    source

    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(
    Debug    , 
    ToJson    )

    A cookie value returned by a HTTP server via the Set-Cookie header

    Cookie::Cookie

    source
    #alias(new, deprecated="`new` is deprecated, use `Cookie` instead")
    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

    Create a new cookie value

    Protocol

    source

    Supported HTTP protocols

    Protocol::default_port

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

    The default port of a HTTP protocol

    RequestHeader

    source
    pub(all) struct RequestHeader {
      meth : RequestMethod
      path : String
      headers : Map[CaseInsensitiveString, String]
    } derive(
    Debug    , 
    ToJson    )

    HTTP request header

    RequestMethod

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

    HTTP request method

    RequestMethod::to_string

    source
    fn RequestMethod::to_string(self : RequestMethod) -> String

    ResponseHeader

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

    HTTP response header

    Server

    source
    pub struct Server {
      addr : 
    Addr
      // private fields
    }

    A HTTP server

    Server::Server

    source
    #alias(new, deprecated="`new` is deprecated, use `Server` instead")
    async fn Server::Server(addr : 
    Addr    , dual_stack? : Bool, reuse_addr? : Bool, headers? : Map[CaseInsensitiveString, String]) -> Server

    Create a new HTTP server listening on addr.

    The meaning of dual_stack and reuse_addr is the same as @socket.TcpServer::new(), see there for more details.

    headers can be used to specify common headers shared by all responses sent by this server.

    Server::accept

    source

    Accept a new connection from a HTTP server. Return the new HTTP connection and the address of peer.

    Server::close

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

    Close a HTTP server, release associated resource

    Server::run_forever

    source
    async fn Server::run_forever(self : Server, f : async (RequestHeader, ServerConnection) -> Unit, allow_failure? : Bool, max_connections? : Int) -> Unit

    Start the main loop of a HTTP server, the server will keep listening for new connections and new requests from existing connections. Requests are handled by the callback function f.

    • header of the request to process
    • a @http.ServerConnection that can be used to read request body or send response.

    Content of the incoming request body can be read streamingly using @io.BinaryReader interface (or @io.TextReader interface through the builtin .text view) on the @http.ServerConnection directly.

    The procedure to send a response is:
    1. initiate a response and send response header via .send_response()
    2. send the response body through @http.ServerConnection as an @io.BinaryWriter, or through .text as an @io.TextWriter
    3. (optional) complete the response via .end_response(). If .end_response() is not called, it will be called automatically after f returns.

    If allow_failure is true (true by default), error raised by f will not crash the whole server. In this case, run_forever will only terminate when cancelled externally. Note that if f fails, the connection used by f will still get aborted.

    If max_connections is present, at most max_connections clients are allowed in parallel. New clients will only get handled after a previous client terminates.

    If f fails without closing the connection, run_forever will close each connection automatically. If f manually closes the connection, the connection will be dropped after f returns. On error or cancellation, the server will be closed automatically.

    ServerConnection

    source
    pub struct ServerConnection {
      text : 
    Utf8TextView
      // private fields
    }

    A single HTTP server connection

    ServerConnection::client_addr

    source

    Get the address of client from a HTTP server connection

    ServerConnection::close

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

    Close the connection, the underlying TCP connection will be closed as well. This function is idempotent: it is safe to call .close() multiple times, only the first .close() call takes effect.

    ServerConnection::drop_all

    source
    async fn ServerConnection::drop_all(self : ServerConnection) -> Int64

    ServerConnection::drop_exactly

    source
    async fn ServerConnection::drop_exactly(self : ServerConnection, len : Int) -> Unit

    ServerConnection::end_response

    source
    async fn ServerConnection::end_response(self : ServerConnection) -> Unit

    End the body of the response currently being sent. Should be called immediately after response body is fully sent.

    ServerConnection::enter_passthrough_mode

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

    Let the server enter "pass through" mode, where the server serve as a TCP tunnel (maybe TLS encrypted) directly. This is useful for handling the special CONNECT HTTP request and HTTP protcol upgrade.

    In passthrough mode, Read/write the server becomes direct read/write on the underlying connection, and only its @io.BinaryReader and @io.BinaryWriter APIs may be used.

    When entering pass through mode, the server must be in a clean state (i.e. not in the middle of sending a response). Unread data from the body of the last request will be discarded.

    ServerConnection::flush

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

    Flush buffered data in the response body being sent, if any.

    ServerConnection::new

    source

    Create a new HTTP server connection from a TCP connection.

    headers can be used to specify persistent headers for the connection, i.e. all response sent by this connection will share these headers. The following headers is automatically set, and must not be specified in headers:

    • Content-Length, Transfer-Encoding

    ServerConnection::peek

    source
    async fn ServerConnection::peek(self : ServerConnection) -> BytesView?

    ServerConnection::peek_at_least

    source
    async fn ServerConnection::peek_at_least(self : ServerConnection, min_len : Int) -> BytesView

    ServerConnection::peek_exactly

    source
    async fn ServerConnection::peek_exactly(self : ServerConnection, len : Int) -> BytesView

    ServerConnection::peek_until

    source
    async fn ServerConnection::peek_until(self : ServerConnection, pattern : BytesView, include_delimiter? : Bool) -> BytesView?

    ServerConnection::read

    source
    async fn ServerConnection::read(self : ServerConnection) -> Bytes?

    ServerConnection::read_all

    source
    async fn ServerConnection::read_all(self : ServerConnection) -> Bytes

    ServerConnection::read_at_least

    source
    async fn ServerConnection::read_at_least(self : ServerConnection, min_len : Int) -> Bytes

    ServerConnection::read_exactly

    source
    async fn ServerConnection::read_exactly(self : ServerConnection, len : Int) -> Bytes

    ServerConnection::read_into

    source
    async fn ServerConnection::read_into(self : ServerConnection, dst : FixedArray[Byte], offset? : Int, max_len? : Int) -> Int

    ServerConnection::read_request

    source
    async fn ServerConnection::read_request(self : ServerConnection) -> RequestHeader

    Read a single request from the connection. If the body of the last request is not consumed yet, it will be discarded.

    After calling read_request, the body of the request can be obtained by using ServerConnection as an @io.BinaryReader, or through .text as an @io.TextReader.

    ServerConnection::read_until

    source
    async fn ServerConnection::read_until(self : ServerConnection, pattern : BytesView, include_delimiter? : Bool) -> Bytes?

    ServerConnection::send_response

    source
    async fn ServerConnection::send_response(self : ServerConnection, code : Int, reason : String, extra_headers? : Map[CaseInsensitiveString, String], cookies? : Array[Cookie]) -> Unit

    Send a response to the peer. The response body can then be sent through ServerConnection as an @io.BinaryWriter, or through .text as an @io.TextWriter. After calling send_response, end_response must be called before sending the next response.

    cookies, if present, specify a list of cookies that the server wish the client to set. They will be transferred to the client via the Set-Cookie HTTP header. Users should always set cookies via cookies instead of filling Set-Cookie header directly.

    If Content-Length is present in extra_headers, it should be the total length of the request body. This useful for, for example, file servers to allow clients to know the progress of download, perform multipart download etc.

    The request body can still be sent incrementally, but if the actual body being sent is shorter and longer than the provided length, an error will be raised.

    ServerConnection::skip_request_body

    source
    async fn ServerConnection::skip_request_body(self : ServerConnection) -> Unit

    Manually discard the body of the request currently being processed.

    ServerConnection::trailer

    source

    Get the trailer of current request message.

    MUST be called AFTER all content of current message body has been read, and BEFORE reading the next request, otherwise this method will crash immediately.

    If the message is not chunk encoded, an empty header map will be returned.

    ServerConnection::write

    source
    async fn ServerConnection::write(self : ServerConnection, data : BytesView) -> Unit

    ServerConnection::write_reader

    source

    ServerConnection::write_string

    source
    async fn ServerConnection::write_string(self : ServerConnection, s : String) -> Unit

    Introduced so that the sugar writer <+ "hello \{world}" can work on ServerConnection. Performance will be improved in the future

    ServerConnection::write_string_interpolation

    source
    async fn[X : Show] ServerConnection::write_string_interpolation(self : ServerConnection, data : X) -> Unit

    Integrate a @http.ServerConnection with string interpolation syntax

    get

    source
    async fn get(uri : StringView, headers? : Map[CaseInsensitiveString, String], proxy? : ClientConnection) -> (ResponseHeader, ClientConnection)

    Performs a GET request to the target URL. Return the response header and the connection assigned for this request. Response body can be obtained by reading from the connection via the @io.BinaryReader interface, or through the @io.TextReader interface using the builtin .text view on the connection. For requests with simple, short response message, @http.get_binary/@http.get_text/@http.get_json can be used to collect the body automatically.

    The returned connection must be manually closed via .close() after the caller no longer need to use it.

    get_binary

    source
    async fn get_binary(uri : StringView, headers? : Map[CaseInsensitiveString, String], proxy? : ClientConnection) -> (ResponseHeader, Bytes)

    Perform a HTTP GET request to uri with binary response. 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.ClientConnection::new for more details. proxy is not supported on JavaScript backend.

    See ClientConnection::request for more details.

    get_json

    source
    async fn get_json(uri : StringView, headers? : Map[CaseInsensitiveString, String], proxy? : ClientConnection) -> (ResponseHeader, 
    Json    )

    Perform a HTTP GET request to uri with UTF-8 encoded JSON response. 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.ClientConnection::new for more details. proxy is not supported on JavaScript backend.

    See ClientConnection::request for more details.

    get_text

    source
    async fn get_text(uri : StringView, headers? : Map[CaseInsensitiveString, String], proxy? : ClientConnection) -> (ResponseHeader, String)

    Perform a HTTP GET request to uri with UTF-8 encoded response. 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.ClientConnection::new for more details. proxy is not supported on JavaScript backend.

    See ClientConnection::request for more details.

    post

    source
    async fn post(uri : StringView, headers? : Map[CaseInsensitiveString, String], proxy? : ClientConnection) -> ClientConnection

    Performs a POST request to the target URL. Return the connection assigned for this request. Request body can be written through the @io.BinaryWriter interface on the connection, or through the @io.TextWriter interface using the builtin .text view on the connection.

    When the request body is completely written, end_request() should be called on the connection to terminate the request and obtain response header from the server. After receiving the response header, response body can be obtained by reading from the connection via the @io.BinaryReader interface, or through the @io.TextReader interface using the builtin .text view on the connection.

    For requests with simple, short message body, @http.post_binary/@http.post_text/@http.post_json can be used to collect the body automatically.

    The returned connection must be manually closed via .close() after the caller no longer need to use it.

    post_binary

    source
    async fn post_binary(uri : StringView, content : BytesView, headers? : Map[CaseInsensitiveString, String], proxy? : ClientConnection) -> (ResponseHeader, Bytes)

    Similar to get_binary, but performs a POST request instead.

    post_json

    source
    async fn post_json(uri : StringView, content : 
    Json    , headers? : Map[CaseInsensitiveString, String], proxy? : ClientConnection) -> (ResponseHeader, 
    Json    )

    Similar to get_json, but performs a POST request instead.

    post_text

    source
    async fn post_text(uri : StringView, content : StringView, headers? : Map[CaseInsensitiveString, String], proxy? : ClientConnection) -> (ResponseHeader, String)

    Similar to get_text, but performs a POST request instead.

    put

    source
    async fn put(uri : StringView, headers? : Map[CaseInsensitiveString, String], proxy? : ClientConnection) -> ClientConnection

    Performs a PUT request to the target URL. Return the connection assigned for this request. Request body can be written through the @io.BinaryWriter interface on the connection, or through the @io.TextWriter interface using the builtin .text view on the connection.

    When the request body is completely written, end_request() should be called on the connection to terminate the request and obtain response header from the server. After receiving the response header, response body can be obtained by reading from the connection via the @io.BinaryReader interface, or through the @io.TextReader interface using the builtin .text view on the connection.

    For requests with simple, short message body, @http.put_binary/@http.put_text/@http.put_json can be used to collect the body automatically.

    The returned connection must be manually closed via .close() after the caller no longer need to use it.

    put_binary

    source
    async fn put_binary(uri : StringView, content : BytesView, headers? : Map[CaseInsensitiveString, String], proxy? : ClientConnection) -> (ResponseHeader, Bytes)

    Similar to get_binary, but performs a PUT request instead.

    put_json

    source
    async fn put_json(uri : StringView, content : 
    Json    , headers? : Map[CaseInsensitiveString, String], proxy? : ClientConnection) -> (ResponseHeader, 
    Json    )

    Similar to get_json, but performs a PUT request instead.

    put_text

    source
    async fn put_text(uri : StringView, content : StringView, headers? : Map[CaseInsensitiveString, String], proxy? : ClientConnection) -> (ResponseHeader, String)

    Similar to get_text, but performs a PUT request instead.

    request

    source
    async fn request(meth : RequestMethod, uri : StringView, headers? : Map[CaseInsensitiveString, String], proxy? : ClientConnection) -> ClientConnection

    Perform a generic HTTP request to uri. Return the connection assigned for this request. The caller should first write request body to the connection through the @io.BinaryWriter interface (or through the @io.TextWriter interface using the builtin .text view), then call .end_request() to finish the request and obtain server response, and finally read response message body through the @io.BinaryReader interface (or through the @io.TextReader interface using the builtin .text view) on the connection.

    The returned connection must be closed after finishing the request.

    For requests with short message body, @http.request_binary/@http.request_text/@http.request_json can be used to automatically collect request/response body.

    For common request methods, @http.get, @http.post etc. can be used instead.

    request_binary

    source
    async fn request_binary(meth : RequestMethod, uri : StringView, body : BytesView, headers? : Map[CaseInsensitiveString, String], proxy? : ClientConnection) -> (ResponseHeader, Bytes)

    Perform a single HTTP request to uri with binary payload/response. 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.ClientConnection(..) for more details. proxy is not supported on JavaScript backend.

    See ClientConnection::request for more details.

    request_json

    source
    async fn request_json(meth : RequestMethod, uri : StringView, body : 
    Json    ?, headers~ : Map[CaseInsensitiveString, String], proxy? : ClientConnection) -> (ResponseHeader, 
    Json    )

    Perform a single HTTP request to uri with UTF-8 encoded JSON payload/response. 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.ClientConnection(..) for more details. proxy is not supported on JavaScript backend.

    See ClientConnection::request for more details.

    request_text

    source
    async fn request_text(meth : RequestMethod, uri : StringView, body : StringView, headers~ : Map[CaseInsensitiveString, String], proxy? : ClientConnection) -> (ResponseHeader, String)

    Perform a single HTTP request to uri with UTF-8 encoded payload/response. 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.ClientConnection(..) for more details. proxy is not supported on JavaScript backend.

    See ClientConnection::request for more details.

    Source Files