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
¶
-
unsigned short
-
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
std::map
on cppreference.comstd::vector
on cppreference.com
-
class
headers_type
¶ An alias for
std::map< std::string, std::vector< std::string >, show::_less_ignore_case_ASCII >
, whereshow::_less_ignore_case_ASCII
is a case-insensitive compare forstd::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
std::map
on cppreference.comstd::vector
on cppreference.com
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
std::runtime_error
on cppreference.com
-
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.