HewDocumentation 0.9.3

Module std.net.http.server

HTTP server for handling web requests.

Provides a blocking HTTP server that listens on a TCP address, accepts incoming requests, and sends responses. Request-body reads time out after 30 seconds by default so slow trickle-feed clients cannot hold the server indefinitely.

Examples

import std.net.http.server as http;

fn main() {
    match http.listen(":8080") {
        .Ok(server) => {
            let req = server.accept().expect("accept request");
            req.respond_text(200, "Hello from Hew!").expect("respond_text succeeds");
            server.close();
        }
        .Err(err) => {
            println(f"{err}");
        }
    }
}

Contents

Functions

Function listen

pub fn listen(addr: string) -> Result<Server, net.NetError>

Create a new HTTP server listening on the given address.

The address format is "host:port" or ":port" to listen on all interfaces.

Returns Err(net.NetError) when the address cannot be bound — the port is already in use, the address is not local, or the string is not a valid endpoint. The returned error carries the failure detail.

Examples

import std.net;
import std.net.http.server as http;

fn main() {
    match http.listen("127.0.0.1:0") {
        .Ok(server) => server.close(),
        .Err(_) => println(f"listen failed"),
    }
}

Types

Struct Server

An HTTP server bound to a TCP address.

Created by calling http.listen(addr), which returns Err when the address cannot be bound. Use accept() to wait for incoming requests in a loop, then call close() before the value goes out of scope.

Methods

fn port(self) -> i64

Return the TCP port selected for this listener.

fn accept(self) -> Request fails net.NetError

Block until a client connects and return the next Request.

fn set_request_timeout(self, timeout: duration) -> () fails net.NetError

Set a positive per-request body read deadline.

Struct Request

An incoming HTTP request.

Obtained from server.accept(). Provides accessors for the request method, path, headers, and body. Must be responded to with one of the respond methods. Requests close automatically at scope exit; call close() to release one early.

Methods

fn method(self) -> string

Return the HTTP method (e.g. "GET", "POST").

fn path(self) -> string

Return the request path (e.g. "/api/users").

fn header(self, name: string) -> Option<string> fails net.NetError

Return the named header, or None when absent.

fn headers(self) -> Vec<(string, string)>

Return all request headers as a list of (name, value) pairs.

The returned vector is owned by the caller; Hew frees it automatically when it goes out of scope. Returns an empty vector if no headers were present or the request is invalid.

fn body(self, encoding: string) -> string fails net.NetError

Return the request body, decoded according to encoding.

Text is decoded as UTF-8. An empty encoding selects UTF-8; other encodings and invalid UTF-8 bytes return errors.

fn respond(consume self, status: i64, content_type: string, body: string) -> Result<(), net.NetError>

Consume this request and send a full HTTP response.

The Content-Length header is derived from body automatically.

fn respond_text(consume self, status: i64, body: string) -> Result<(), net.NetError>

Send a plain-text HTTP response.

Examples
import std.net.http.server as http;

fn main() {
    match http.listen(":8080") {
        .Ok(server) => {
            let req = server.accept().expect("accept request");
            req.respond_text(200, "OK").expect("respond_text succeeds");
            server.close();
        }
        .Err(err) => println(f"{err}"),
    }
}
fn respond_json(consume self, status: i64, json: string) -> Result<(), net.NetError>

Send a JSON HTTP response with Content-Type: application/json.

fn respond_stream(consume self, status: i64, content_type: string) -> Result<Sink<string>, net.NetError>

Consume this request and return a Sink for chunked response output.

Each sink.send(chunk) sends data to the client immediately. Call sink.close() to finish the response.

Examples
import std.net.http.server as http;

fn main() {
    match http.listen(":8080") {
        .Ok(server) => {
            let req = server.accept().expect("accept request");
            let body = req.respond_stream(200, "text/plain").expect("begin response");
            body.send("chunk 1").expect("send");
            body.send("chunk 2").expect("send");
            body.close();
            server.close();
        }
        .Err(err) => println(f"{err}"),
    }
}

Inherent methods

impl Server

fn close(consume self)

Release this server early. Scope exit performs the same release.

impl Request

fn close(consume self)

Release this request early. Scope exit performs the same release.