Setup a listening virtual host

The HPC provides virtual hosting capabilities and can distinguish virtual host thanks to either (i) the listening IP and port, or (ii) the Host/authority header. Each virtual host is defined by a name (e.g., vh1), a set of listening endpoints and a pattern. The pattern is a regular expression that is used to match the Host header of incoming requests. The endpoints are the ports that the HPC will listen to. The following code snippet shows how to setup a virtual host that listens to the ports 80 and 443.

The pattern must be ".*" if you want to match any request, including those without a Host header, such as http://192.168.1.1/

config.vhosts["vh1"] = {
      .endpoints = {endpoint(HTTP , 80), endpoint(HTTPS , 443)},
      .pattern = ".*"
};

The endpoint directive supports restriction to a specific IP address:

• endpoint(HTTP, 80) listen to all IP addresses on port 80
• endpoint(HTTP, 80, "192.168.1.1") listen to the IP address 192.168.1.1 on port 80

The name of the vhost will be used when altering other properties, and will also appear in logs, metrics, and other reporting.

Route registration

Each virtual host processes requests according to a set of rules named routes. The routes match the method, and the URL with a regex (excluding any query parameters).

Routes are added to the vhost using the following syntax with a handler as described in the rest of this document:

config.vhosts["vh1"] << route(GET | HEAD , "/other/.*", ... handler ...);

In addition to those routes, it is possible to override the default handler triggered when no route nor vhost match.

config.default_route = ... handler ...;

To simplify configuration, it is possible to take aliases to vhost to refer to them later using auto& x = config.vhost["vh1"];

auto& v1 = config.vhost["vh1"]
v1 << route(GET | HEAD , "/local/.*", ... handler ...);
v1 << route(GET | HEAD , "/other/.*", ... handler ...);
v1.set_ebpf_locality(true);

Simple text responses

In its simplest form, a handler will set some headers and provide a response (body). This handler is defined with the following syntax: two object references to access request and reply properties. The response is sent with a status 200 OK. To be able to control the status, use the set_error directive.

config.vhosts["vh1"] << route(GET | HEAD, "/local/.*", [](
    client_request& req, client_reply& rpy){
      rpy.set_header("X-Served-By", "HPC");
      co_await rpy.set_accept(req, "Hello World !");
});

This capability is helpful in cache servers for responding to OPTIONS queries or to provide heartbeat monitoring endpoints.

Errors

The set_error directive allows the user to control the status code and provide an explanatory error message. The error message is optional so that it will be empty.

config.vhosts["vh1"] << route(GET | HEAD , "/local/.*", [](
    client_request& req, client_reply& rpy){
      rpy.set_header("Some-Header", "value");
      co_await rpy.set_error(req , 451, "This content is not licensed for your region.");
});

Redirects

The set_redirect directive allows redirecting the client to an alternate location using a 307 redirect status code.

config.vhosts["vh1"] << route(GET | HEAD , "/local/.*", [](
    client_request& req, client_reply& rpy){
      rpy.set_header("Some-Header", "value");
      co_await rpy.set_redirect(req , "/xxxxx");
});

config.vhosts["vh1"] << route(GET | HEAD , "/remote/.*", [](
    client_request& req, client_reply& rpy){
      rpy.set_header("Some-Header", "value");
      co_await rpy.set_redirect(req , "http://xxxx/");
});

Files

An ultimate way to provide content available locally on the server is to serve files or directory using the set_file and set_directory directives.

The latter ensures that the served files do not belong to any parent directory to prevent accidentally evading the folder through symbolic links or '..'

config.vhosts["vh1"] << route(GET | HEAD , "/info", [](
    client_request&req, client_reply& rpy){
      co_await rpy.set_file(req , "/var/www/data/info.html");
});

config.vhosts["vh1"] << route(GET | HEAD , "/content /.*", [](
    client_request& req, client_reply& rpy){
      rpy.set_header("Some -Header", "value");
      co_await rpy.set_directory(req , "/var/www/data/content_folder");
});