hapi — How to Use Server Labels

Using hapi as the framework of choice for building web apps or APIs brings a lot built-in functionality to leverage from. In the end of August 2015 we published a post describing how to run separate frontend and backend servers within one project using hapi.

The mentioned post in the previous sentence shows you how to define and use different hapi server connections to separate the plugins and routes of front- and backend.

This article shows you how to use hapi’s server labels to select specific connections for further manipulation.

hapi Series Overview

What are Server Labels

Labels within hapi’s server object is a string or an array of strings representing the server. The labels option defaults to an empty array []. Labels are similar to tags and are used to categorize servers. Use the labels property in combination with the server.select() method to pick matching connections.

How to Use Labels

Let’s directly start with an example to illustrate the definition of labels for different server connections. We create three different connections and label each connection with a proper name representing its purpose.

var hapi = require('hapi');  

// Create hapi server instance
var server = new hapi.Server();

// add connection parameters
    host: 'localhost',
    port: 3000,
    labels: ['frontend']

    host: 'localhost',
    port: 3001,
    labels: ['admin']

    host: 'localhost',
    port: 8000,
    labels: ['api']

As you can see within the code snippet, we create a new hapi server instance and define three connections. Hapi will listen on all defined connections for incoming requests to handle. However, the important parts are the labels definition. The first connection is labeled as frontend since this connection represents our web frontend. The second connection has the admin label assigned. The third connection is the api and has the appropriate label attached.

Internally, hapi does a deep clone of the options object passed to the server.connection method. You can now use the server.select() method to request a specific connection for further operations.

Select Connections by Label

Hapi’s server object offers the server.select method to pick a single or multiple connections based on labels. The server.select method returns an array of connections. The code below shows the connection selection using the previously introduced server configuration with their labels.

var api = server.select('api');

// api.connections.length === 1

As you expect, only the one connection labeled as api was selected from the pool of three connections.

Combine Multiple Labels to Select Connections

We’re now deriving another example from the previously introduced hapi server configuration with three connections and their labels. We assume the frontend and admin connections are accessible via web browser. Therefore, both connections require view rendering support. We now want to select both connections via an OR statement and pass an array of labels to select the frontend and admin connections.

// all servers with a label of frontend OR admin
var frontends = server.select(['frontend', 'admin']);  
// frontends.connections.length === 2

// servers with a label of api AND admin
var apiOrAdmin = server.select('api').select('admin');  
// apiOrAdmin.connections.length === 0

You can also simulate an AND selection by chaining the select methods and passing the specific labels as parameters. The example above tries to select a connection with label api AND admin which is obviously not available and results in an empty return (length === 0).

Register Plugins for Server(s) Selected by Labels

A common use case for labels is the separate installation of plugins for different connections. Within our exemplary server setup with three connections, only the frontend and admin connection need template rendering support. We have two options to register the vision plugin for rendering support only to those two connections: we could either use the server.register method or select the two connections first and register the plugins for them. The example below uses the server object and specifies the connection selection as a parameter.

    register: require('vision')
  }, {
    select: ['frontend', 'admin']
  }, function (err) {
    // handle error
    // do further stuff like view configuration, etc.

The snippet above shows you how to register a plugin only for selected connections. The api connection doesn’t require any view support and there’s no need to add the vision plugin to the api as well.

We hope you’ve learned a lot about hapi’s server labels throughout this guide! Maybe you’ve already use cases in mind for your projects using hapi as the framework.

Please use the comments below or shout out to @futurestud_io for further questions!

Additional Resources

Explore the Library

Find interesting tutorials and solutions for your problems.