Documentation

Server configuration

The HTTP server supports a number of configuration options to customize its behavior. By default, the server will listen on all local network adapters on port 80 and will perform complete request parsing. The following list gives an overview of the most common settings:

port

The port on which the HTTP server shall listen

bindAddresses

A list of all interfaces on which the server shall listen. IPv4 and IPv6 addresses, as well as domain names are supported.

options

Controls optional features of the web server. Certain options can be disabled to increase speed or to decrease memory usage. By default, the following options are enabled: parseURL, parseQueryString, parseFormBody, parseJsonBody, parseMultiPartBody, parseCookies. Enabled options are ORed together.

errorPageHandler

Provides a way to customize error pages. For example:

void errorPage(HTTPServerRequest req,
               HTTPServerResponse res,
               HTTPServerErrorInfo error)
{
	//res.render!("error.dt", req, error); // still affected by a compiler bug
	res.renderCompat!("error.dt",
		HTTPServerRequest, "req",
		HTTPServerErrorInfo, "error")
		(req, error);
}

shared static this()
{
	auto settings = new HTTPServerSettings;
	settings.errorPageHandler = toDelegate(&errorPage);
	// ...
}

Inside of the error.dt template, the variables req, code and msg are available in this example.

sslContext

Lets the server operate as an HTTPS server. You should probably also set the port to 443 in case this field is set.

Routing

The URLRouter class provides a convenient way to let different functions handle different URLs. It supports static path matching, variable placeholders and wild-cards. Any matched variable will be available as an entry in the params dictionary.

In addition to the path, the HTTP method is also used for matching requests. Each HTTP method has a corresponding method in the URLRouter class (e.g. get() or post()). The following example will route all GET requests matching the path scheme "/users/*" to the userInfo handler and serve all other GET requests using the files in the public folder.

import vibe.d;

void userInfo(HTTPServerRequest req, HTTPServerResponse res)
{
	auto username = req.params["user"];
	render!("userinfo.jd", username)(res);
}

void addUser(HTTPServerRequest req, HTTPServerResponse res)
{
	res.redirect("/users/"~req.post["user"]);
}

shared static this()
{
	auto router = new URLRouter;
	router.get("/users/:user", &userInfo);
	router.post("/adduser", &addUser);
	router.get("*", serveStaticFiles("./public/"));

	// To reduce code redundancy, you can also
	// use method chaining:
	router
		.get("/users/:user", &userInfo)
		.post("/adduser", &addUser);
		.get("*", serveStaticFiles("./public/"));

	listenHTTP(new HTTPServerSettings, router);
}

Diet templates

Vibe supports HTML templates with a syntax mostly compatible to jade templates. They provide a concise way to dynamically generate the HTML code of the final web pages. D expressions and statements can be embedded and the full vibe API is available within templates.

Templates should reside somewhere inside the 'views' folder of a project. They are then rendered using the render function, which takes the template file name as the first template argument, followed by a list of variables that should be available to the template. Finally, it takes a HTTPServerResponse to render into.

The following example shows a number of features of the template parser. A full reference of the template syntax is found on the Diet templates page.

!!! 5
html
	head
		title My page: #{pageTitle}
	body
		h1= pageTitle
		p This is the content of this page. The
			| title "#{pageTitle}" is inserted dynamically.
			| We can also use loops and other D statements:
		block placeholder
		p
			- foreach(i, ch; pageTitle)
				| #{i+1}. character: #{ch}
		p.special.small This paragraph has the 'special'
			| and 'small' CSS classes
		p#footer This paragraph has the id 'footer'.
		#somediv
			| I'm a text inside the div ##somediv

Error pages

There are two ways in which an error page is sent back to the client:

• An exception is thrown from the request handler or while parsing the request. By default, a 500 "Internal Server Error" is returned. By throwing a HTTPStatusException , the status code can be customized.
• The request handler does not write a response. In this case the server automatically returns a 404 "Not Found" error.

The HTTPServerSettings can be used to provide a custom error page handler. If one is provided, it is called for any of the two conditions and must render an error page to the response object. If no handler is given, a simple plain-text error page is generated.

import vibe.d
void error(HTTPServerRequest req, HTTPServerResponse res, HTTPServerErrorInfo error)
{
	res.renderCompat!("error.dl",
		HTTPServerRequest, "req",
		HTTPServerErrorInfo, "error")
		(req, error);
}

shared static this()
{
	auto settings = new HTTPServerSettings;
	settings.errorPageHandler = toDelegate(&error);

	auto router = new URLRouter;
	// ...

	listenHTTP(settings, router);
}

Authentication

Currently, the only built-in authentication method is HTTP-Basic-Auth. HTTP-Digest-Auth will follow later and higher level mechanisms such as OAuth will be provided using extension libraries.

The recommended practice for plugging authentication into a web application is to use the fall-through feature of the URLRouter. If the user is properly authenticated, the performBasicAuth function will not do anything and the URLRouter will continue to match the request to all following routes. If, however, there is no authentication or if the username/password pair is not valid, it will throw a HTTPStatusException exception which generates a 403 error page so that the user is prompted with a password dialog on the browser side. The routing stops in this case.

import vibe.d;

bool checkPassword(string user, string password)
{
	return user == "admin" && password == "secret";
}

shared static this()
{
	auto router = new URLRouter;
	// the following routes are accessible without authentication:
	router.get("/", staticTemplate!"index.dl");
	router.get("/about", staticTemplate!"about.dl");
   
	// now any request is matched and checked for authentication:
	router.any("*", performBasicAuth("Site Realm", toDelegate(&checkPassword)));

	// the following routes can only be reached if authenticated:
	router.get("/profile", staticTemplate!"profile.dl");
	router.get("/internal", staticTemplate!"internal.dl");

	// ...
}

Sessions

Cookie based HTTP sessions are supported directly by the HTTP server. To be able to use them, you first have to set a SessionStore in the HTTPServerSettings . Sessions are then established by calling HTTPServerResponse.startSession and stopped using HTTPServerResponse.terminateSession . The returned Session object behaves as a key value store taking strings as keys and values.

import vibe.d;

void login(HTTPServerRequest req, HTTPServerResponse res)
{
	// todo: verify user/password here

	auto session = res.startSession();
	session["username"] = req.form["username"];
	session["password"] = req.form["password"];
	res.redirect("/home");
}

void logout(HTTPServerRequest req, HTTPServerResponse res)
{
	res.terminateSession();
	res.redirect("/");
}

void checkLogin(HTTPServerRequest req, HTTPServerResponse res)
{
	// force a redirect to / for unauthenticated users
	if( req.session is null )
		res.redirect("/");
}

shared static this()
{
	auto router = new URLRouter;
	router.get("/", staticTemplate!"index.dl");
	router.post("/login", &login);
	router.post("/logout", &logout);
	// restrict all following routes to authenticated users:
	router.any("*", &checkLogin);
	router.get("/home", staticTemplate!"home.dl");

	auto settings = new HTTPServerSettings;
	settings.sessionStore = new MemorySessionStore;
	// ...
}

Client requests

Client request are done using the requestHTTP() function.

import vibe.vibe

void main()
{
	auto res = requestHTTP("http://google.com",
			(scope req) {
				/* could e.g. add headers here before sending*/
			},
			(scope res) {
				logInfo("Response: %s", res.bodyReader.readAllUTF8());
			}
		);
}

A connection pool is used internally in conjunction with persistent HTTP connection to reduce the number of connection establishments.

MongoDB

A native MongoDB driver is part of the distribution supporting the standard set of database operations. Data is exchanged using the Bson struct.

For an comprehensive documentation of MongoDB's operations see the MongoDB manual . The API reference contains the documentation for the driver.

import vibe.d;

MongoClient client;

void test()
{
	auto coll = client.getCollection("test.collection");
	foreach (doc; coll.find(["name": "Peter"]))
		logInfo("Found entry: %s", cast(Json)doc);
}

shared static this()
{
	client = connectMongoDB("127.0.0.1");
}

Redis

A rudimentary client for the structured storage server Redis is included in Vibe. Commands and operations on Redis data types are implemented as instance methods of the client. The methods are named after their corresponding Redis command documented in the command reference .

Server

Listening for TCP connections is done using the listenTCP function. An implementation of a very simple echo server could look like this:

import vibe.d;

shared static this()
{
	listenTCP(7, (conn){ conn.write(conn) });
}

Calling listenTCP like this will listen on all local network devices. To listen only on a specific device, the bind address can be given as an additional parameter:

import vibe.d;

shared static this()
{
	listenTCP(7, conn => conn.write(conn), "127.0.0.1");
}

The address can be given as an IP address string (IPv4 or IPv6 format), as an uint for numeric IPv4 addresses or as a in6_addr for numeric IPv6 addresses.

Client

Connecting to a TCP server is done with the connectTCP function. The following example gets the current time using the Daytime Protocol .

import vibe.d;

shared static this()
{
	auto conn = connectTCP("time-b.timefreq.bldrdoc.gov", 13);
	logInfo("The time is: %s", cast(string)conn.readAll());
}

Publishing on the DUB registry

The DUB registry contains packages that use the same package management as vibe.d. Many of them extend and supplement vibe.d's functionality. The packages are automatically downloaded if the corresponding entry in the "dependencies" section of the project's package.json file is present.

If you have written an extension library yourself, you can register it in the DUB registry so others can easily make use of it. For this to work, you will first have to write a proper package.json, which has to lie in the root directory of your project (the project should adhere to the structure mentioned in the first steps). The project currently also has to be hosted on github. See http://registry.vibed.org/publish for more information.

{
	"name": "vibelog",
	"description": "A light-weight embeddable blog implementation",
	"homepage": "https://github.com/rejectedsoftware/vibelog",
	"authors": [
		"Sönke Ludwig"
	],
	"dependencies": {
	}
}

You can then register your project on registry.vibed.org and as soon as you then add a new git tag with the name matching the current version prefixed with "v" ("v0.0.1" for the example here), it should appear there. Note that the update can take up to 30 minutes. Anyone can then add an entry similar to the following to their project to make use of the library:

{
	...
	"dependencies": {
		"vibelog": ">=0.0.1"
	}
}

Custom main function

When writing a client application, maybe something like wget, it may not be desirable to start an explicit event loop, but instead exit right after the work is done. Some applications might also need more control of how vibe is initialized or when the event loop is started. To support such usage scenarios, you can implement your own main() function. To be able to do this, you just have to import "vibe.vibe" instead of "vibe.d" add "VibeCustomMain" to the "versions" field in your package.json file. This will tell the compiler to not use the main() function that vibe.d provides.

import vibe.vibe;

int main(string[] args)
{
	processCommandLineArgs(args);
	return runEventLoop();
}

import vibe.vibe;

void main()
{
	auto f = openFile("test.html", FileMode.CreateTrunc);
	f.write(download("http://google.com/"));
}

Privilege lowering

For server applications it may be desirable to start the application as root so that it can listen on privileged ports or open system log files for writing. After these setup tasks, such applications impose a security risk because a hole in the application that allows to somehow execute commands on the server will give the attacker full access to the system. For this reason vibe supports privilege lowering, where the user id and group id of the process are changed to an unprivileged user after the setup process, right before the event loop is started.

Privilege lowering can be configured in the configuration file /etc/vibe/vibe.conf (on Windows vibe.conf must be in the application's root directory instead). The two fields "user" and "group" have to be set to the the name or numeric ID of the unprivileged user/group.

{
	"user": "www-data",
	"group": "www-data"
}