Hapi HTTP Server Framework

Hapi allows you to define dynamic segments in your route paths using curly braces {}. These values are accessible via request.params.

Parameter Types:

• Standard Parameter: '/book/{id}/cover' matches '/book/123/cover', where request.params.id is '123'.
• Optional Parameter: Adding a '?' suffix makes a parameter optional. '/book/{id?}' matches '/book/' with request.params.id as an empty string ''.
• Multi-segment Wildcard: Using * allows matching multiple segments.
  • '/person/{name*2}' matches exactly two segments (e.g., '/person/john/doe').
  • '/path/{param*}' matches any number of segments (must be the last segment in the path).

Constraints:

• Parameter names may only contain letters, numbers, and underscores (e.g., /{file_name} is valid; /{file-name} is invalid).
• Each segment can only contain one named parameter.

const Hapi = require('@hapi/hapi');
const server = Hapi.server({ port: 80 });

const getAlbum = function (request, h) {
    return 'You asked for ' + 
           (request.params.song ? request.params.song + ' from ' : '') + 
           request.params.album;
};

server.route({
    path: '/{album}/{song?}',
    method: 'GET',
    handler: getAlbum
});

// Multi-segment example
server.route({
    path: '/person/{name*2}', // Matches '/person/john/doe'
    method: 'GET',
    handler: (request, h) => {
        const nameParts = request.params.name.split('/');
        return { first: nameParts[0], last: nameParts[1] };
    }
});

The server.events object is a podium public interface used to interact with server events. You can subscribe to events using on() or once(), and emit application events using emit().

Key event types include:

'log' Event

Emits internal server events and application events logged via server.log(). The handler signature is function(event, tags).

• event.channel: 'internal' for framework events, 'app' for server.log() events.
• event.tags: An object where each event.tag is a key and the value is true.

'cachePolicy' Event

Emitted when a cache policy is created via server.cache() or a cached server.method(). The handler signature is function(cachePolicy, cache, segment).

'request' Event

Emits internal request events and application events logged via request.log(). The handler signature is function(request, event, tags).

• event.channel: 'app' (from request.log()), 'error' (on 500 status codes), or 'internal' (framework generated).

// Example: Listening for request errors
server.events.on('request', (request, event, tags) => {

if (tags.error) {
        console.log(`Request ${event.request} error: ${event.error ? event.error.message : 'unknown'}`);
    }
});

// Example: Listening to a specific channel
server.events.on({ name: 'request', channels: 'error' }, (request, event, tags) => {

console.log(`Request ${event.request} failed`);
});

Every incoming request in Hapi passes through a strictly ordered sequence of steps. Understanding this order is critical for implementing extensions, authentication, and validation correctly.

The complete lifecycle sequence:

1. onRequest: Always called if extensions exist. Can be used for URL/method rewrites via request.setUrl() and request.setMethod().
2. Route lookup: Based on path and method. Skips to onPreResponse if no route is found.
3. Cookies processing: Based on route state options.
4. onPreAuth: Called regardless of whether authentication is performed.
5. Authentication: Based on route auth options.
6. Payload processing: Based on route payload options.
7. Payload authentication: Based on route auth options.
8. onCredentials: Called only if authentication is performed.
9. Authorization: Based on route auth.access options.
10. onPostAuth: Called regardless of authentication.
11. Headers validation: Based on validate.headers.
12. Path parameters validation: Based on validate.params.
13. Query validation: Based on validate.query.
14. Payload validation: Based on validate.payload.
15. State validation: Based on validate.state.
16. onPreHandler
17. Pre-handler methods: Based on route pre options.
18. Route handler: Executes the route handler.
19. onPostHandler: Allows modifying request.response (but not reassigning it).
20. Response validation: Based on validate.response.
21. onPreResponse: Always called unless the request is aborted. Allows modifying the response.
22. Response transmission: May emit a 'request' event on the 'error' channel.
23. Finalize request: Emits 'response' event.
24. onPostResponse: Executed after response is sent. Note: If performing IO here, defer it to another tick to avoid blocking.

The server.realm object provides sandboxed server settings specific to a plugin or an authentication strategy. When a plugin is registered, it receives a server object with a unique realm container. This ensures that settings (like route prefixes or file paths) applied within a plugin do not leak to the global server or other plugins.

Key components of server.realm:

• modifiers.route: Contains route preferences like prefix and vhost. A prefix applied here will automatically be prepended to any routes added via server.route() within this realm.
• plugin: The name of the active plugin.
• pluginOptions: The options passed during registration.
• settings: Overrides for settings like files.relativeTo or bind.
• plugins: A dictionary of plugin-specific state that can be shared among activities within the same realm.

Note: server.realm is read-only, except for the plugins property, which plugins can manipulate to share state.

exports.register = function (server, options) {
    // Access the route prefix configured for this plugin's realm
    console.log(server.realm.modifiers.route.prefix);
};

Plugins allow you to organize application logic by splitting server functionality into smaller, modular components. Each plugin can interact with the server via the standard server interface. A key feature of plugins is sandboxing: certain properties (like server.realm) are scoped to the plugin, meaning changes made to a sandboxed property in one plugin do not affect other plugins.

To create a plugin, you must provide a register function that accepts the server object and an options object. The server object provided to the plugin includes a plugin-specific server.realm for sandboxing.

const plugin = {
    name: 'test',
    version: '1.0.0',
    register: function (server, options) {

        server.route({
            method: 'GET',
            path: '/test',
            handler: function (request, h) {

                return 'ok';
            }
        });
    }
};

hapi provides built-in TypeScript definitions (.d.ts) and uses two complementary patterns for typing:

1. Module augmentation: Used to declare global types that apply to every route (e.g., UserCredentials, ServerApplicationState).
2. Generic refs: Used to pass per-route type overrides via ServerRoute<Refs>, Request<Refs>, and Lifecycle.Method<Refs>.

You can use both together: module augmentation sets the baseline, while generic refs narrow types for specific routes.

import { server as createServer, ServerRoute, Request, ResponseToolkit } from '@hapi/hapi';

interface AppSpace {
    startedAt: number;
}

// Use generic to type server.app
const server = createServer<AppSpace>({ port: 3000 });
server.app.startedAt = Date.now();

// Use generic to type request.params
const route: ServerRoute<{ Params: { id: string } }> = {
    method: 'GET',
    path: '/users/{id}',
    handler: (request, h) => {
        const id: string = request.params.id;
        return { id };
    }
};

server.route(route);