Async Http Server. More...

#include <HttpAsyncServer.h>

Public Member Functions
template<typename T , typename = typename TypeTraits::EnableIf<TypeTraits::IsBaseOf<HttpConnection, T>::value>::type>
Result	init (Span< T > clients)
	Initializes the async server with all needed memory buffers.

template<typename T , typename = typename TypeTraits::EnableIf<TypeTraits::IsBaseOf<HttpConnection, T>::value>::type>
Result	resize (Span< T > clients)

Result	close ()
	Closes the server, removing references to the memory buffers passed during init.

Result	start (AsyncEventLoop &loop, StringSpan address, uint16_t port)
	Starts the http server on the given AsyncEventLoop, address and port.

Result	startExternal (AsyncEventLoop &loop)
	Starts the HTTP state machine without creating a native listener.

Result	acceptExternalConnection (HttpConnection &connection, AsyncReadableStream &readable, AsyncWritableStream &writable)
	Activates a specific connection slot for externally accepted plaintext streams.

Result	stop ()
	Stops http server asynchronously pushing cancel and close requests to the event loop.

void	setMaxHeaderSize (uint32_t bytes)
	Sets the maximum accepted request-header size in bytes.

uint32_t	getMaxHeaderSize () const
	Gets the maximum accepted request-header size in bytes.

void	setTransportSetup (Function< Result(HttpAsyncServerTransportSetup &)> &&setup)
	Sets an optional transport setup hook invoked after accepting TCP and before HTTP reads request bytes.

void	setTransportClose (Function< void(HttpConnection &)> &&close)
	Sets an optional transport teardown hook invoked before HTTP destroys the installed transport streams.

void	setTransportReuse (Function< Result(HttpConnection &)> &&reuse)
	Sets an optional hook that reopens an alternate writable transport for the next keep-alive response.

void	setTransportShutdown (Function< Result(HttpConnection &, Function< void(Result)>)> &&shutdown)
	Sets an optional asynchronous hook that drains a terminal response before closing its socket.

void	clearTransportSetup ()
	Clears optional transport setup, reuse, shutdown, and teardown hooks.

bool	isStarted () const
	Returns true if the server has been started.

const HttpConnectionsPool &	getConnections () const

void	setDefaultKeepAlive (bool enabled)
	Set default keep-alive behavior for all connections.

bool	getDefaultKeepAlive () const
	Get the default keep-alive setting.

void	setMaxRequestsPerConnection (uint32_t maxRequests)
	Set maximum requests per keep-alive connection.

uint32_t	getMaxRequestsPerConnection () const
	Get the maximum requests per connection.

Public Attributes
Function< void(HttpConnection &)>	onRequest
	Called after enough data from a newly connected client has arrived, causing all headers to be parsed.

Function< void(Result)>	onError
	Called on accept, parse, protocol, or streaming errors before the affected connection is closed.

Detailed Description

Async Http Server.

This class handles a fully asynchronous http server staying inside 5 fixed memory regions passed during init.

Usage:

Use SC::HttpAsyncServer::onRequest callback to intercept requests from http clients
Write to SC::HttpResponse using the writable stream obtained from HttpConnection::response.getWritableStream()
Alternatively use SC::HttpAsyncFileServer to statically serve files

See also: SC::HttpAsyncFileServer, SC::HttpConnectionsPool

    constexpr int MAX_CONNECTIONS = 3;        // Max number of concurrent http connections
    constexpr int REQUEST_SLICES  = 2;        // Number of slices of the request buffer for each connection
    constexpr int REQUEST_SIZE    = 1 * 1024; // How many bytes are allocated to stream data for each connection
    constexpr int HEADER_SIZE     = 8 * 1024; // How many bytes are dedicated to hold request and response headers
 
    // The size of the header and request memory, and length of read/write queues are fixed here, but user can
    // set any arbitrary size for such queues doing the same being done in HttpAsyncConnection constructor.
    using HttpConnectionType = HttpAsyncConnection<REQUEST_SLICES, REQUEST_SLICES, HEADER_SIZE, REQUEST_SIZE>;
 
    // 1. Memory to hold all http connections (single array for simplicity).
    // WebServerExample (SCExample) shows how to leverage virtual memory, to handle dynamic number of clients
    HttpConnectionType connections[MAX_CONNECTIONS];
 
    // Initialize and start the http server
    HttpAsyncServer httpServer;
    const uint16_t  serverPort = report.mapPort(6152);
    SC_TEST_EXPECT(httpServer.init(Span<HttpConnectionType>(connections)));
    SC_TEST_EXPECT(httpServer.start(eventLoop, "127.0.0.1", serverPort));
 
    struct ServerContext
    {
        int numRequests;
    } serverContext = {0};
 
    // Handle the request and answer accordingly
    httpServer.onRequest = [this, &serverContext](HttpConnection& client)
    {
        HttpRequest&  request  = client.request;
        HttpResponse& response = client.response;
        if (request.getParser().method != HttpParser::Method::HttpGET)
        {
            SC_TEST_EXPECT(response.startResponse(405));
            SC_TEST_EXPECT(response.addHeader("Allow", "GET"));
            SC_TEST_EXPECT(response.sendHeaders());
            SC_TEST_EXPECT(response.end());
            return;
        }
        if (request.getRequestTarget() != "/index.html" and request.getRequestTarget() != "/")
        {
            SC_TEST_EXPECT(response.startResponse(404));
            SC_TEST_EXPECT(response.sendHeaders());
            SC_TEST_EXPECT(response.end());
            return;
        }
        serverContext.numRequests++;
        SC_TEST_EXPECT(response.startResponse(200));
        SC_TEST_EXPECT(response.addHeader("Connection", "Closed"));
        SC_TEST_EXPECT(response.addHeader("Content-Type", "text/html"));
        SC_TEST_EXPECT(response.addHeader("Server", "SC"));
        SC_TEST_EXPECT(response.addHeader("Date", "Mon, 27 Aug 2023 16:37:00 GMT"));
        SC_TEST_EXPECT(response.addHeader("Last-Modified", "Wed, 27 Aug 2023 16:37:00 GMT"));
        const char sampleHtml[] = "<html>\r\n"
                                  "<body bgcolor=\"#000000\" text=\"#ffffff\">\r\n"
                                  "<h1>This is a title {}!</h1>\r\n"
                                  "We must start from somewhere\r\n"
                                  "</body>\r\n"
                                  "</html>\r\n";
 
        // Create a "user provided" dynamically allocated string, to show this is possible
        String content;
        SC_TEST_EXPECT(StringBuilder::format(content, sampleHtml, serverContext.numRequests));
        SmallString<16> contentLength;
        SC_TEST_EXPECT(StringBuilder::format(contentLength, "{}", content.view().sizeInBytes()));
        SC_TEST_EXPECT(response.addHeader("Content-Length", contentLength.view()));
        SC_TEST_EXPECT(response.sendHeaders());
        // Note that the system takes ownership of the dynamically allocated user provided string
        // through type erasure and it will invoke its destructor after th write operation will finish,
        // freeing user memory as expected.
        // This write operation succeeds because EXTRA_SLICES allocates one more slot buffer exactly
        // to hold this user provided buffer, that is not part of the "re-usable" buffers created
        // at the beginning of this sample.
        SC_TEST_EXPECT(response.getWritableStream().write(move(content)));
        SC_TEST_EXPECT(response.end());
    };
 

Member Function Documentation

◆ acceptExternalConnection()

Result SC::HttpAsyncServer::acceptExternalConnection	(	HttpConnection &	connection,
		AsyncReadableStream &	readable,
		AsyncWritableStream &	writable )

Activates a specific connection slot for externally accepted plaintext streams.

This must be called on the server event-loop thread. Both streams and the connection storage remain caller-owned until Http has destroyed the streams and deactivated the slot.

◆ clearTransportSetup()

void SC::HttpAsyncServer::clearTransportSetup ( )

inline

Clears optional transport setup, reuse, shutdown, and teardown hooks.

◆ close()

Result SC::HttpAsyncServer::close ( )

Closes the server, removing references to the memory buffers passed during init.

Note: This call will wait until all async operations will be finished before returning

◆ getDefaultKeepAlive()

bool SC::HttpAsyncServer::getDefaultKeepAlive ( ) const

inlinenodiscard

Get the default keep-alive setting.

◆ getMaxHeaderSize()

uint32_t SC::HttpAsyncServer::getMaxHeaderSize ( ) const

inlinenodiscard

Gets the maximum accepted request-header size in bytes.

◆ getMaxRequestsPerConnection()

uint32_t SC::HttpAsyncServer::getMaxRequestsPerConnection ( ) const

inlinenodiscard

Get the maximum requests per connection.

◆ init()

template<typename T , typename = typename TypeTraits::EnableIf<TypeTraits::IsBaseOf<HttpConnection, T>::value>::type>

Result SC::HttpAsyncServer::init ( Span< T > clients )

inline

Initializes the async server with all needed memory buffers.

◆ isStarted()

bool SC::HttpAsyncServer::isStarted ( ) const

inlinenodiscard

Returns true if the server has been started.

◆ setDefaultKeepAlive()

void SC::HttpAsyncServer::setDefaultKeepAlive ( bool enabled )

inline

Set default keep-alive behavior for all connections.

Parameters

enabled true to keep connections alive by default (HTTP/1.1 default)

Note: Can be overridden per-response via HttpResponse::setKeepAlive()

◆ setMaxHeaderSize()

void SC::HttpAsyncServer::setMaxHeaderSize ( uint32_t bytes )

inline

Sets the maximum accepted request-header size in bytes.

The limit must fit inside the per-connection header storage passed to init().

◆ setMaxRequestsPerConnection()

void SC::HttpAsyncServer::setMaxRequestsPerConnection ( uint32_t maxRequests )

inline

Set maximum requests per keep-alive connection.

Parameters

maxRequests Maximum requests before closing connection (0 = unlimited)

◆ setTransportClose()

void SC::HttpAsyncServer::setTransportClose ( Function< void(HttpConnection &)> && close )

inline

Sets an optional transport teardown hook invoked before HTTP destroys the installed transport streams.

The hook may start asynchronous stream destruction but must not reset the connection's transport streams.

◆ setTransportReuse()

void SC::HttpAsyncServer::setTransportReuse ( Function< Result(HttpConnection &)> && reuse )

inline

Sets an optional hook that reopens an alternate writable transport for the next keep-alive response.

◆ setTransportSetup()

void SC::HttpAsyncServer::setTransportSetup ( Function< Result(HttpAsyncServerTransportSetup &)> && setup )

inline

Sets an optional transport setup hook invoked after accepting TCP and before HTTP reads request bytes.

◆ setTransportShutdown()

void SC::HttpAsyncServer::setTransportShutdown ( Function< Result(HttpConnection &, Function< void(Result)>)> && shutdown )

inline

Sets an optional asynchronous hook that drains a terminal response before closing its socket.

◆ start()

Result SC::HttpAsyncServer::start	(	AsyncEventLoop &	loop,
		StringSpan	address,
		uint16_t	port )

Starts the http server on the given AsyncEventLoop, address and port.

Parameters

loop	The event loop to be used, where to add the listening socket
address	The address of local interface where to listen to
port	The local port where to start listening to

Returns: Valid Result if http listening has been started successfully

◆ startExternal()

Result SC::HttpAsyncServer::startExternal ( AsyncEventLoop & loop )

Starts the HTTP state machine without creating a native listener.

An external listener must inject accepted plaintext streams with acceptExternalConnection().

◆ stop()

Result SC::HttpAsyncServer::stop ( )

Stops http server asynchronously pushing cancel and close requests to the event loop.

Warning: Consider calling HttpAsyncServer::close before reclaiming memory used by this class

Member Data Documentation

◆ onError

Function<void(Result)> SC::HttpAsyncServer::onError

Called on accept, parse, protocol, or streaming errors before the affected connection is closed.

◆ onRequest

Function<void(HttpConnection&)> SC::HttpAsyncServer::onRequest

Called after enough data from a newly connected client has arrived, causing all headers to be parsed.

The documentation for this struct was generated from the following file:

HttpAsyncServer.h

Public Member Functions

Public Attributes

Detailed Description

Member Function Documentation

◆ acceptExternalConnection()

◆ clearTransportSetup()

◆ close()

◆ getDefaultKeepAlive()

◆ getMaxHeaderSize()

◆ getMaxRequestsPerConnection()

◆ init()

◆ isStarted()

◆ setDefaultKeepAlive()

◆ setMaxHeaderSize()

◆ setMaxRequestsPerConnection()

◆ setTransportClose()

◆ setTransportReuse()

◆ setTransportSetup()

◆ setTransportShutdown()

◆ start()

◆ startExternal()

◆ stop()

Member Data Documentation

◆ onError

◆ onRequest