Types

Main Types

The public interfaces to the main SHOW classes are documented on the following pages:

Support Types

enum http_protocol

Symbolizes the HTTP protocols understood by SHOW. The enum members are:

HTTP_1_0 HTTP/1.0
HTTP_1_1 HTTP/1.1
NONE The request did not specify a protocol version
UNKOWN The protocol specified by the request wasn’t recognized

There is no HTTP_2 as SHOW is not intended to handle HTTP/2 requests. These are much better handled by a reverse proxy such as NGINX, which will convert them into HTTP/1.0 or HTTP/1.1 requests for SHOW.

class response_code

A simple utility struct that encapsulates the numerical code and description for an HTTP status code. An object of this type can easily be statically initialized like so:

show::response_code rc = { 404, "Not Found" };

See the list of HTTP status codes on Wikipedia for an easy reference for the standard code & description values.

The two fields are defined as:

unsigned short code
std::string description
class query_args_type

An alias for std::map< std::string, std::vector< std::string > >, and can be statically initialized like one:

show::query_args_type args{
    { "tag", { "foo", "bar" } },
    { "page", { "3" } }
};

This creates a variable args which represents the query string ?tag=foo&tag=bar&page=3.

See also

class headers_type

An alias for std::map< std::string, std::vector< std::string >, show::_less_ignore_case_ASCII >, where show::_less_ignore_case_ASCII is a case-insensitive compare for std::map.

While HTTP header names are typically given in Dashed-Title-Case, they are technically case-insensitive. Additionally, in general a given header name may appear more than once in a request or response. This type satisfies both these constraints.

Headers can be statically initialized:

show::headers_type headers{
    { "Content-Type", { "text/plain" } },
    { "Set-Cookie", {
        "cookie1=foobar",
        "cookie2=SGVsbG8gV29ybGQh"
    } }
};

See also

Throwables

Not all of these strictly represent an error state when throw; some signal common situations that should be treated very much in the same way as exceptions. SHOW’s throwables are broken into two categories — connection interruptions and exceptions.

Connection interruptions

class connection_interrupted

A common base class for both types of connection interruptions. Note that this does not inherit from std::exception.

class connection_timeout : public connection_interrupted

An object of this type will be thrown in two general situations:

  • A server object timed out waiting for a new connection
  • A connection, request, or response timed out reading from or sending to a client

In the first situation, generally the application will simply loop and start waiting again. In the second case, the application may want to close the connection or continue waiting with either the same timoute or some kind of falloff. Either way the action will be application-specific.

class client_disconnected : public connection_interrupted

This is thrown when SHOW detects that a client has broken connection with the server and no further communication can occur.

Exceptions

See also

class socket_error : public std::runtime_error

An unrecoverable, low-level error occurred inside SHOW. If thrown while handling a connection, the connection will no longer be valid but the server should be fine. If thrown while creating or working with a server, the server object itself is in an unrecoverable state and can no longer serve.

The nature of this error when thrown by a server typically implies trying again will not work. If the application is designed to serve on a single IP/port, you will most likely want to exit the program with an error.

class request_parse_error : public std::runtime_error

Thrown when creating a request object from a connection and SHOW encounters something it can’t manage to interpret into a request.

As parsing the offending request almost certainly failed midway, garbage data will likely in the connection’s buffer. Currently, the only safe way to handle this exception is to close the connection.

class response_marshall_error : public std::runtime_error

Thrown by response’s constructor when the response arguments cannot be marshalled into a valid HTTP response:

  • One of the header names is an empty string
  • One of the header names contains a character other than A-Z, a-z, 0-9, or -
  • Any header value is an empty string
class url_decode_error : public std::runtime_error

Thrown by url_decode() when the input is not a valid URL- or percent-encoded string.

Note

url_encode() shouldn’t throw an exception, as any string can be converted to percent-encoding.