- Http Handler
- Asynchronous HTTP programming
- REST description
- API Reference
Most of the components provided by
Pistache live in the
Net namespace. It is thus
recommended to directly import this namespace with a
Requests that are received by
Pistache are handled by a special class called
This class declares a bunch of virtual methods that can be overriden to handle special events
that occur on the socket and/or connection.
onRequest() function must be overriden. This function is called whenever
received data and correctly parsed it as an http request.
The first argument is an object of type
Http::Request representing the request itself.
It contains a bunch of informations including:
- The resource associated to the request
- The query parameters
- The headers
- The body of the request
Request object gives a
read-only access to these informations. You can access them
through a couple of getters but can not modify them. An http request is immutable.
Sending a response
ResponseWriter is an object from which the final http response is sent to the client.
onRequest() function does not return anything (
void). Instead, the response is
sent through the
ResponseWriter class. This class provides a bunch of
overloads to send the response:
You can use this overload to send a response with an empty body and a given
HTTP Code (e.g
This overload can be used to send a response with static, fixed-size content (body).
A MIME type can also be specified, which will be sent through the
This version can also be used to send a fixed-size response with a body except that it does not need to construct a string (no memory is allocated). The size of the content is directly deduced by the compiler. This version only works with raw string literals.
These functions are
asynchronous, meaning that they do not return a plain old
value indicating the number of bytes being sent, but instead a
Promise that will be
fulfilled later on. See the next section for more details on asynchronous programming with
Sometimes, content that is to be sent back to the user can not be known in advance, thus the length
can not be determined in advance.
For that matter, the HTTP specification defines a special data-transfer mechanism called
chunked encoding where data is sent in a series
of chunks. This mechanism uses the
Transfer-Encoding HTTP header in place of the
To stream content, Pistache provides a special
ResponseStream class. To get a ResponseStream from
a ResponseWriter, call the
stream() member function:
To initate a stream, you have to pass the HTTP status code to the stream function (here
The ResponseStream class provides an
iostream like interface that overloads the
The first line will write a chunk of size 2 with the content PO to the stream’s buffer. The second line will write a second
chunk of size 2 with the content “NG”. To end the stream and flush the content, use the special
end marker will write the last chunk of size 0 and send the final data over the network. To simply flush the stream’s buffer
without ending the stream, you can use the
After starting a stream, headers become immutable. They must be written to the response before creating a ResponseStream:
Static file serving
In addition to text content serving, Pistache provides a way to serve static files through the
serveFile also returns a Promise representing the total number of bytes being sent to the wire
Sometimes, you might require to timeout after a certain amount of time. For example, if you are designing an HTTP API
with soft real-time constraints, you will have a time constraint to send a response back to the client.
That is why Pistache provides the ability to control the timeout on a per-request basis. To arm a timeout on a response,
you can use the
timeoufterAfter() member function directly on the
This will trigger a timeout if a response has not been sent within 500 milliseconds.
timeoutAfter accepts any kind
When a timeout triggers, the
onTimeout() function from your handler will be called. By default, this method does nothing. If you
want to handle your timeout properly, you should then override this function inside your own handler:
Request object that is passed to the onTimeout is the exact same request that triggered the timeout. The
ResponseWriter is a
complete new writer object.
Since the ResponseWriter object is a complete new object, state is not preserved with the ResponseWriter from the onRequest() callback, which means that you will have to write the complete response again, including headers and cookies.
Asynchronous HTTP programming
Interfaces provided by
non-blocking. Asynchronous programming allows for code
to continue executing even if the result of a given call is not available yet. Calls that provide an asynchronous
interface are referred to
An example of such a call is the
send() function provided by the
This function returns the number of bytes written to the socket file descriptor associated to the connection.
However, instead of returning directly the value to the caller and thus blocking the caller, it wraps
the value into a component called a
Promise is the Pistache’s implementation of the
asynchronous call, a
Promise separates the launch of an asynchronous operation from the retrieval of its result.
While the asynchronous might still be running, a
Promise<T> is directly returned to the caller to retrieve the final
result when it becomes available. A so called
continuation can be attach to a Promise to execute a callback when
the result becomes available (when the Promise has been resolved or fulfilled).
then() member is used to attach a callback to the Promise. The first argument is a
callable that will be called
when the Promise has been succesfully resolved. If, for some reason, an error occurs during the asynchronous operation,
a Promise can be rejected and will then fail. In this case, the second callable will be called.
a special callback that will call
std::terminate() if the promise failed. This is the equivalent of the
Other generic callbacks can also be used in this case:
Async::IgnoreExceptionwill simply ignore the exception and let the program continue
Async::Throwwill “rethrow” the exception up to an eventual promise call-chain. This has the same effect than the
throwkeyword, except that it is suitable for promises.
Exceptions in promises callbacks are propagated through an
Promises can also be chained together to create a whole asynchronous pipeline:
Line 5 will propagate the exception if
fetchDatabase() failed and rejected the promise.
Inspired by the Rust eco-system and Hyper, HTTP headers are represented
type-safe plain objects. Instead of representing headers as a pair of
(key: string, value: value), the choice has
been made to represent them as plain objects. This greatly reduces the risk of typo errors that can not catched by the
compiler with plain old strings.
Instead, objects give the compiler the ability to catch errors directly at compile-time, as the user can not add or request a header through its name: it has to use the whole type. Types being enforced at compile-time, it helps reducing common typo errors.
Pistache, each HTTP Header is a
class that inherits from the
Http::Header base class and use the
to define the name of the header. List of all headers inside an HTTP request or response are stored inside an internal
std::unordered_map, wrapped in an
Header::Collection class. Invidual headers can be retrieved or added to this object
through the whole type of the header:
get<H> will return a
H: Header (H inherits from Header). If the header does not exist,
will throw an exception.
tryGet<H> provides a non-throwing alternative that, instead, returns a null pointer.
Headers provided by Pistache live in the Http::Header namespace
Defining your own header
Common headers defined by the HTTP RFC (RFC2616) are already implemented and available.
However, some APIs might define extra headers that do not exist in
Pistache. To support your own header types, you can define
and register your own HTTP Header by first declaring a class that inherits the
Since every header has a name, the
NAME() macro must be used to name the header properly:
Http::Header base class provides two virtual methods that you must override in your own implementation:
This function is used to parse the header from the string representation. Alternatively, to avoid allocating memory for the string representation, a raw version can be used:
str will directly point to the header buffer from the raw http stream. The
len parameter is the total length of the header’s value.
When writing the response back to the client, the
write function is used to serialize the header into the network buffer.
Let’s combine these functions together to finalize the implementation of our previously declared header:
And that’s it. Now all we have to do is registering the header to the registry system:
You should always provide a default constructor for your header so that it can be instantiated by the registry system
XProtocolVersion can be retrieved and added like any other header in the
Headers that are not known to the registry system are stored as a raw pair of strings in the Collection class. getRaw() can be used to retrieve a raw header:
MIME Types (or Media Type) are also fully typed. Such types are for example
used in an HTTP request or response to describe the data contained in the body of the message (
Content-Type header, …)
and are composed of a type, subtype, and optional suffix and parameters.
MIME Types are represented by the
Mime::MediaType class, implemented in the
mime.h header. A MIME type can be directly
constructed from a string:
However, to enforce type-safety, common types are all represented as enumerations:
To avoid such a typing pain, a
MIME macro is also provided:
For suffix MIMEs, use the special
If you like typing, you can also use the long form:
toString() function can be used to get the string representation of a given MIME type:
HTTP routing consists of binding an HTTP route to a C++ callback. A special component called an HTTP router will be in charge of dispatching HTTP requests to the right C++ callback. A route is composed of an HTTP verb associated to a resource:
GET is the verb and
/users/1 is the associated resource.
A bunch of HTTP methods (verbs) are supported by Pistache:
- GET: The
GETmethod is used by the client (e.g
browser) to retrieve a ressource identified by an URI. For example, to retrieve an user identified by an id, a client will issue a
- POST: the
POSTmethod is used to post or send new information to a certain ressource. The server will then read and store the data associated to the request. POST is a common way of transmitting data from an HTML form. POST can also be used to create a new resource or update information of an existing resource. For example, to create a new user, a client will issue a
/userspath with the data of the user to create in its body.
PUTis very similar to
PUTis idempotent, meaning that two requests to the same Request-URI with the same identical content should have the same effect and should produce the same result.
- DELETE: the
DELETEmethod is used to delete a resource associated to a given Request-URI. For example, to remove an user, a client might issue a
DELETEcall to the
To sum up,
PUT are used to Create and/or Update,
GET is used to Read and
DELETE is used to Delete
Static routes are the simplest ones as they do rely on dynamic parts of the Request-URI.
/users/all is a static route that will exactly match the
However, it is often useful to define routes that have dynamic parts. For example, to retrieve a specific user
by its id, the id is needed to query the storage. Dynamic routes thus have parameters that are then matched
one by one by the HTTP router. In a dynamic route, parameters are identified by a column
:id is a dynamic parameter. When a request comes in, the router will try to match the
:id parameter to
the corresponding part of the request. For example, if the server receives a request to
/users/13, the router will
13 value to the
Some parameters, like
:id are named. However,
Pistache also allows splat (wildcard) parameters, identified by a star
To define your routes, you first have to instantiate an HTTP router:
Then, use the
Routes::<Method>() functions to add some routes:
Routes::bind is a special function that will generate a corresponding C++ callback that will then
be called by the router if a given route matches the Request-URI.
A C++ callback associated to a route must have the following signature:
A callback can either be a non-static free or member function. For member functions, a pointer to the
corresponding instance must be passed to the
Routes::bind function so that the router knows on which
instance to invoke the member function.
The first parameter of the callback is
Rest::Request and not an
Http::Request will additional functions. Named and splat parameters are for example retrieved through
As you can see, parameters are also typed. To cast a parameter to the appropriate type, use the
as<T> member template.
An exception will be thrown if the parameter can not be casted to the right type
Installing the handler
Once the routes have been defined, the final
Http::Handler must be set to the HTTP Endpoint. To retrieve the handler,
just call the
handler() member function on the router object:
Documentation writing for this part is still in progress, please refer to the rest_description example