2. Tutorials
  3. hapi — How to Use Server Labels

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

  1. Get Your Server Up and Running
  2. v17 Upgrade Guide (Your Move to async/await)
  3. Become a Better Developer in 2018
  4. Become a Better Developer in 2017
  1. What You’ll Build
  2. Prepare Your Project: Stack & Structure
  3. Environment Variables and Storing Secrets
  4. Set Up MongoDB and Connect With Mongoose
  5. Sending Emails in Node.js
  6. Load the User’s Profile Picture From Gravatar Using Virtuals in Mongoose
  7. Implement a User Profile Editing Screen
  8. Generate a Username in Mongoose Middleware
  9. Displaying Seasons and Episodes for TV Shows with Mongoose Relationship Population
  10. Implementing Pagination for Movies
  11. Implement a Watchlist
  12. Create a Full Text Search with MongoDB
  1. Create a REST API with JSON Endpoints
  2. Update Mongoose Models for JSON Responses
  3. API Pagination for TV Shows
  4. Customize API Endpoints with Query Parameters
  5. Always Throw and Handle API Validation Errors
  6. Advanced API Validation With Custom Errors
  7. Create an API Documentation with Swagger
  8. Customize Your Swagger API Documentation URL
  9. Describe Endpoint Details in Your Swagger API Documentation
  10. 10 Tips on API Testing With Postman
  11. JWT Authentication in Swagger API Documentation
  12. API Versioning with Request Headers
  1. IP-Based Rate Limits (Part 1 of 7)
  2. Rate Limits for Routes (Part 2 of 7)
  3. Dynamic Rate Limits (Part 3 of 7)
  4. Render a “Rate Limit Exceeded” View (Part 4 of 7)
  5. Show “Rate Limit Exceeded” Error on Login (Part 5 of 7)
  6. Disable Rate Limiting (Part 6 of 7)
  7. Rate Limiter Refactoring & Cleanup (Part 7 of 7)
  1. API Login With Username and Password to Generate a JWT
  2. JWT Authentication and Private API Endpoints
  3. Refresh Tokens With JWT Authentication
  4. Create a JWT Utility
  5. JWT Refresh Token for Multiple Devices
  6. Check Refresh Token in Authentication Strategy
  7. Rate Limit Your Refresh Token API Endpoint
  8. How to Revoke a JWT
  9. Invalidate JWTs With Blacklists
  10. JWT Logout (Part 1/2)
  11. JWT “Immediate” Logout (Part 2/2)
  12. A Better Place to Invalidate Tokens
  13. How to Switch the JWT Signing Algorithm
  14. Roll Your Own Refresh Token Authentication Scheme
  15. JWT Claims 101
  16. Use JWT With Asymmetric Signatures (RS256 & Co.)
  17. Encrypt the JWT Payload (The Simple Way)
  18. Increase JWT Security Beyond the Signature
  19. Unsigned JSON Web Tokens (Unsecured JWS)
  20. JWK and JWKS Overview
  21. Provide a JWKS API Endpoint
  22. Create a JWK from a Shared Secret
  23. JWT Verification via JWKS API Endpoint
  24. What is JOSE in JWT
  25. Encrypt a JWT (the JWE Way)
  26. Authenticate Encrypted JWTs (JWE)
  27. Encrypted and Signed JWT (Nested JWT)
  28. Bringing Back JWT Decoding and Authentication
  29. Bringing Back JWT Claims in the JWT Payload
  1. Basic Authentication With Username and Password
  2. Authentication and Remember Me Using Cookies
  3. How to Set a Default Authentication Strategy
  4. Define Multiple Authentication Strategies for a Route
  5. Restrict User Access With Scopes
  6. Show „Insufficient Scope“ View for Routes With Restricted Access
  7. Access Restriction With Dynamic and Advanced Scopes
  8. hapi - How to Fix „unknown authentication strategy“
  9. Authenticate with GitHub And Remember the Login
  10. Authenticate with GitLab And Remember the User
  11. How to Combine Bell With Another Authentication Strategy
  12. Custom OAuth Bell Strategy to Connect With any Server
  13. Redirect to Previous Page After Login
  14. How to Implement a Complete Sign Up Flow With Email and Password
  15. How to Implement a Complete Login Flow
  16. Implement a Password-Reset Flow
  1. Views in hapi 9 (and above)
  2. How to Render and Reply Views
  3. How to Reply and Render Pug Views (Using Pug 2.0)
  4. How to Create a Dynamic Handlebars Layout Template
  5. Create and Use Handlebars Partial Views
  6. Create and Use Custom Handlebars Helpers
  7. Specify a Different Handlebars Layout for a Specific View
  8. How to Create Jade-Like Layout Blocks in Handlebars
  9. Use Vue.js Mustache Tags in Handlebars Templates
  10. How to Use Multiple Handlebars Layouts
  1. Extend Your Server Functionality With Plugins
  2. Create Your Own Custom Plugin
  3. How to Register Plugins for a Selected Server Instance
  4. hapi Plugin for Client Geo Location (by Future Studio 🚀)
  5. Increase Development Speed With Errors in the Browser or as JSON Response
  1. Route Handling and Drive Traffic to Your Server
  2. How to Serve Static Files (Images, JS, CSS, etc.)
  3. How to Use Query Parameters
  4. Optional Path Parameters
  5. Multi-Segment/Wildcard Path Parameters
  6. Ignore Trailing Slashes on Route Paths
  7. How to Fix “Unsupported Media Type”
  1. How to Access and Handle Request Payload
  2. Access Request Headers
  3. How to Manage Cookies and HTTP States Across Requests
  4. Detect and Get the Client IP Address
  5. How to Upload Files
  6. Quick Access to Logged In User in Route Handlers
  7. How to Fix “handler method did not return a value, a promise, or throw an error”
  8. How to Fix “X must return an error, a takeover response, or a continue signal”
  1. How to Reply a JSON Response
  2. How to Set Response Status Code
  3. How to Handle 404 Responses for Missing Routes
  1. Query Parameter Validation With Joi
  2. Path Parameter Validation With Joi
  3. Request Payload Validation With Joi
  4. Validate Query and Path Parameters, Payload and Headers All at Once on Your Routes
  5. Validate Request Headers With Joi
  6. Reply Custom View for Failed Validations
  7. Handle Failed Validations and Show Errors Details at Inputs
  8. How to Fix AssertionError, Cannot validate HEAD or GET requests
  1. Add CSRF Protection on Forms and API Endpoints
  1. Report Errors to Sentry
  2. Don’t Report Errors to Sentry in Development Mode
  3. Logging Fundamentals
  4. Log to Console With Good
  5. Log to File With Good
  1. Getting Started With Testing Using Lab and Code
  2. Run Tests with Assertions using Code
  3. Test Route Handlers by Injecting Requests
  4. Inject Request Payload, Headers and Parameters While Testing Route Handlers
  1. Zero-Downtime Deployments Using PM2

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
server.connection({  
    host: 'localhost',
    port: 3000,
    labels: ['frontend']
});

server.connection({  
    host: 'localhost',
    port: 3001,
    labels: ['admin']
});

server.connection({  
    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.

server.register({  
    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

Marcus Pöhls

Marcus is a fullstack JS developer. He’s passionate about the hapi framework for Node.js and loves to build web apps and APIs. Creator of Futureflix and the “learn hapi” learning path.

Explore the Library

Find interesting tutorials and solutions for your problems.

Android

Node.js

Server

Miscellaneous