QHttpServerRouterRule Class

Detailed Description

QHttpServerRouterRule expresses the connection between a request path, an HTTP request method, and the respective handler callback. The QHttpServerRouter is a collection of such rules from which the handlers are called if the path and request method match the request. The handler callback must provide the response to the request.

Path and Patterns

Every QHttpServerRouterRule contains a path or path pattern which defines the paths for which it can provide a response through its handler. The path can contain placeholders that are forwarded to the rule's handler. The following examples of path patterns are shown with the QHttpServer::route convenience method, but can also be provided to the QHttpServerRouterRule constructor.

In the simplest case the path is a string with a leading "/":

 QHttpServer server;
 server.route("/user", [] () { return "hello user"; } );

This path pattern creates a rule that forwards all requests with "/user" to the provided hanlder, which in this case is a simple lambda (Note that the handler syntax would look different when using QHttpServerRouterRule directly, see below).

The path pattern can further contain a trailing "/" to create a rule that addresses a collection of paths with arguments after the trailing "/". The argument will be forwarded to the Rule as a QRegularExpressionMatch. Using the QHttpServer::route convenience method the argument is directly forwarded to the lambda:

 server.route("/user/", [] ( qint64 id ) { return "hello user"; } );

This would match the request urls "/user/1", "/user/2" and so on.

The argument can be posititioned freely with the path pattern by using the "<arg>" placeholder. This keyword further allows multiple placeholder.

 server.route("/user/<arg>/history", [] (qint64 id){ return "hello user"; } );
 server.route("/user/<arg>/history/", [] (qint64 id, qint64 page){ return "hello user"; } );

This would, for example, match the request url "/user/1/history/2". All types which are registered in QHttpServerRouter::converters() can be used in the callback and the respective placeholder.

Request Method

Request method is simply one of QHttpServerRequest::Method. If no method is provided to any overload of the Rule construction, the rule will match any request method.

Handler Signature

The handler is a callback with the signature

 void (*)(const QRegularExpressionMatch &, const QHttpServerRequest &, QHttpServerResponder &);

The handler callback receives any matched placeholders as its first argument. The second argument contains details about the request and the response has to be written on the last argument by the handler.

The following code example shows how new rules with the respective handler can be created and added to a QHttpServerRouter:

 template<typename ViewHandler>
 void route(const char *path, const QHttpServerRequest::Methods methods, ViewHandler &&viewHandler)
 {
     auto rule = std::make_unique<QHttpServerRouterRule>(
             path, methods, [this, viewHandler = std::forward<ViewHandler>(viewHandler)]
                                             (QRegularExpressionMatch &match,
                                              const QHttpServerRequest &request,
                                              QHttpServerResponder &responder) mutable {
         auto boundViewHandler = QHttpServerRouterRule::bindCaptured<ViewHandler>(
                 this, std::move(viewHandler), match);
         // call viewHandler
         boundViewHandler();
     });

 // QHttpServerRouter
 router.addRule<ViewHandler>(std::move(rule));
 }

 // Valid:
 route("/user/", [] (qint64 id) { } );                            // "/user/1"
                                                                  // "/user/3"
                                                                  //
 route("/user/<arg>/history", [] (qint64 id) { } );               // "/user/1/history"
                                                                  // "/user/2/history"
                                                                  //
 route("/user/<arg>/history/", [] (qint64 id, qint64 page) { } ); // "/user/1/history/1"
                                                                  // "/user/2/history/2"