Struct dbs_uhttp::HttpServer

pub struct HttpServer { /* private fields */ }

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

The function that handles incoming connections, parses incoming requests and sends responses for awaiting requests is requests. It can be called in a loop, which will render the thread that the server runs on incapable of performing other operations, or it can be used in another EPOLL structure, as it provides its epoll, which is a wrapper over the file descriptor of the epoll structure used within the server, and it can be added to another one using the EPOLLIN flag. Whenever there is a notification on that fd, requests should be called once.

Example

Starting and running 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;
}

Implementations

impl HttpServer

pub fn new<P: AsRef<Path>>(path_to_socket: P) -> Result<Self, ServerError>

Constructor for HttpServer.

Returns the newly formed HttpServer.

Errors

Returns an IOError when binding or epoll::create fails.

pub fn new_from_fd(socket_fd: RawFd) -> Result<Self, ServerError>

Constructor for HttpServer.

Note that this function requires the socket_fd to be solely owned and not be associated with another File in the caller as it uses the unsafe UnixListener::from_raw_fd method.

Returns the newly formed HttpServer.

Errors

Returns an IOError when epoll::create fails.

pub fn set_payload_max_size(&mut self, request_payload_max_size: usize)

This function sets the limit for PUT/PATCH requests. It overwrites the default limit of 0.05MiB with the one allowed by server.

pub fn start_server(&mut self) -> Result<(), ServerError>

Starts the HTTP Server.

pub fn requests(&mut self) -> Result<Vec<ServerRequest>, ServerError>

This function is responsible for the data exchange with the clients and should be called when we are either notified through epoll that we need to exchange data with at least a client or when we don’t need to perform any other operations on this thread and we can afford to call it in a loop.

Note that this function will block the current thread if there are no notifications to be handled by the server.

Returns a collection of complete and valid requests to be processed by the user of the server. Once processed, responses should be sent using enqueue_responses().

Errors

IOError is returned when read, write or epoll::ctl operations fail. ServerFull is returned when a client is trying to connect to the server, but full capacity has already been reached. InvalidWrite is returned when the server attempted to perform a write operation on a connection on which it is not possible.

pub fn flush_outgoing_writes(&mut self)

This function is responsible with flushing any remaining outgoing requests on the server.

Note that this function can block the thread on write, since the operation is blocking.

pub fn epoll(&self) -> &Poll

The file descriptor of the epoll structure can enable the server to become a non-blocking structure in an application.

Returns a reference to the instance of the server’s internal epoll structure.

Example

Non-blocking server

use std::os::unix::io::AsRawFd;

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

// Create our epoll manager.
let epoll = epoll::Epoll::new().unwrap();

let path_to_socket = "/tmp/epoll_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();

// Add our server to the `epoll` manager.
epoll.ctl(
    epoll::ControlOperation::Add,
    server.epoll().as_raw_fd(),
    epoll::EpollEvent::new(epoll::EventSet::IN, 1234u64),
)
.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();

// Control loop of the application.
let mut events = Vec::with_capacity(10);
loop {
    let num_ev = epoll.wait(-1, events.as_mut_slice());
    for event in events {
        match event.data() {
            // The server notification.
            1234 => {
                let request = server.requests();
                // Process...
            }
            // Other `epoll` notifications.
            _ => {
                // Do other computation.
            }
        }
    }
    // Break this example loop.
    break;
}

pub fn enqueue_responses(
    &mut self,
    responses: Vec<ServerResponse>
) -> Result<(), ServerError>

Enqueues the provided responses in the outgoing connection.

Errors

IOError is returned when an epoll::ctl operation fails.

pub fn respond(&mut self, response: ServerResponse) -> Result<(), ServerError>

Adds the provided response to the outgoing buffer in the corresponding connection.

Errors

IOError is returned when an epoll::ctl operation fails. Underflow is returned when enqueue_response fails.