Crate dbs_uhttp

Expand description

Minimal implementation of the HTTP/1.0 and HTTP/1.1 protocols.

HTTP/1.1 has a mandatory header Host, but as this crate is only used for parsing API requests, this header (if present) is ignored.

This HTTP implementation is stateless thus it does not support chunking or compression.

Supported Headers

The dbs_uhttp crate has support for parsing the following Request headers:

Content-Length
Expect
Transfer-Encoding

The Response does not have a public interface for adding headers, but whenever a write to the Body is made, the headers ContentLength and MediaType are automatically updated.

Media Types

The supported media types are:

text/plain
application/json

Supported Methods

The supported HTTP Methods are:

GET
PUT
PATCH

Supported Status Codes

The supported status codes are:

Continue - 100
OK - 200
No Content - 204
Bad Request - 400
Not Found - 404
Internal Server Error - 500
Not Implemented - 501

Example for parsing an HTTP Request from a slice

use dbs_uhttp::{Request, Version};

let request_bytes = b"GET http://localhost/home HTTP/1.0\r\n\r\n";
let http_request = Request::try_from(request_bytes, None).unwrap();
assert_eq!(http_request.http_version(), Version::Http10);
assert_eq!(http_request.uri().get_abs_path(), "/home");

Example for creating an HTTP Response

use dbs_uhttp::{Body, MediaType, Response, StatusCode, Version};

let mut response = Response::new(Version::Http10, StatusCode::OK);
let body = String::from("This is a test");
response.set_body(Body::new(body.clone()));
response.set_content_type(MediaType::PlainText);

assert!(response.status() == StatusCode::OK);
assert_eq!(response.body().unwrap(), Body::new(body));
assert_eq!(response.http_version(), Version::Http10);

let mut response_buf: [u8; 126] = [0; 126];
assert!(response.write_all(&mut response_buf.as_mut()).is_ok());

HttpConnection can be used for automatic data exchange and parsing when handling a client, but it only supports one stream.

For handling multiple clients use HttpServer, which multiplexes HttpConnections and offers an easy to use interface. The server can run in either blocking or non-blocking mode. Non-blocking is achieved by using epoll to make sure requests will never block when called.

Example for using the server

use dbs_uhttp::{HttpServer, Response, StatusCode};

let path_to_socket = "/tmp/example.sock";
std::fs::remove_file(path_to_socket).unwrap_or_default();

// Start the server.
let mut server = HttpServer::new(path_to_socket).unwrap();
server.start_server().unwrap();

// Connect a client to the server so it doesn't block in our example.
let mut socket = std::os::unix::net::UnixStream::connect(path_to_socket).unwrap();

// Server loop processing requests.
loop {
    for request in server.requests().unwrap() {
        let response = request.process(|request| {
            // Your code here.
            Response::new(request.http_version(), StatusCode::NoContent)
        });
        server.respond(response);
    }
    // Break this example loop.
    break;
}

Structs

Body

The Body associated with an HTTP Request or Response.

Encoding

Wrapper over supported AcceptEncoding.

Headers

Wrapper over the list of headers associated with a Request that we need in order to parse the request correctly and be able to respond to it.

HttpConnection

A wrapper over a HTTP Connection.

HttpRoutes

An HTTP routes structure.

HttpServer

HTTP Server implementation using Unix Domain Sockets and EPOLL to handle multiple connections on the same thread.

Request

Wrapper over an HTTP Request.

Response

Wrapper over an HTTP Response.

ResponseHeaders

Wrapper over the list of headers associated with a HTTP Response. When creating a ResponseHeaders object, the content type is initialized to text/plain. The content type can be updated with a call to set_content_type.

ServerRequest

Wrapper over Request which adds an identification token.

ServerResponse

Wrapper over Response which adds an identification token.

SysError

Errors associated with a sys errno