h2o2 Proxy Handler

When using the uri option, you can inject values from the incoming request using the following template variables:

• {protocol}
• {host}
• {port}
• {path}
• {query}

You can also capture request.params and query values by using a similar replacement strategy. Note that the default variables listed above take precedence; avoid using them as names for your own request.params.

// Example using default template values
server.route({
    method: 'GET',
    path: '/foo',
    handler: {
        proxy: {
            uri: '{protocol}://{host}:{port}/go/to/{path}'
        }
    }
});

// Example using request.params
server.route({
    method: 'GET',
    path: '/foo/{bar}',
    handler: {
        proxy: {
            uri: 'https://some.upstream.service.com/some/path/to/{bar}{query}'
        }
    }
});

To add proxying functionality to your hapi server, register the @hapi/h2o2 plugin. This allows you to use the proxy handler in your route configurations.

const Hapi = require('@hapi/hapi');
const H2o2 = require('@hapi/h2o2');

const start = async function() {

  const server = Hapi.server();

  await server.register(H2o2);
  await server.start();

  console.log(`Server started at:  ${server.info.uri}`);
};

start();

When defining the uri option, you can use placeholders that h2o2 will automatically replace using the current request's information:

• {protocol}: The current server's protocol.
• {host}: The current server's host.
• {port}: The current server's port.
• {path}: The current request's path.
• {query}: The current request's query string.
• {key}: Any parameter defined in the route (e.g., {id}).

Example: uri: 'https://api.example.com/{path}' will map /users to https://api.example.com/users.

// If the route is /user/{id}
// And the request is GET /user/123?name=foo
// The following uri will map to: https://upstream.com/api/123?name=foo
h.proxy({
    uri: 'https://upstream.com/api/{id}{query}'
});

By default, h2o2 uses wreck. You can provide a custom client by passing an object to the httpClient option. The client must implement the wreck interface, specifically the request() and parseCacheControl() methods.

server.route({
    method: 'GET',
    path: '/',
    handler: {
        proxy: {
            httpClient: {
                request(method, uri, options) {
                    return axios({
                        method,
                        url: 'https://some.upstream.service.com/'
                    })
                }
            }
        }
    }
});

Use the uri option to send requests to a specific absolute URI. This overrides the incoming host, port, protocol, path, and query. This configuration cannot be used simultaneously with host, port, protocol, or mapUri.

server.route({
    method: 'GET',
    path: '/',
    handler: {
        proxy: {
            uri: 'https://some.upstream.service.com/that/has?what=you&want=todo'
        }
    }
});

You can direct requests to a specific upstream service by providing the host, port, and protocol (either 'http' or 'https'). The request will be sent to the upstream service using the same path as the original client request. This configuration cannot be used simultaneously with uri or mapUri.

server.route({
    method: 'GET',
    path: '/',
    handler: {
        proxy: {
            host: '10.33.33.1',
            port: '443',
            protocol: 'https'
        }
    }
});

You can proxy a request to an upstream endpoint within a route handler using h.proxy(options). The options object accepts the same keys as the route configuration proxy handler. Note that response flow control rules do not apply when using this method.

const handler = function (request, h) {

    return h.proxy({ host: 'example.com', port: 80, protocol: 'http' });
};

You can provide an onResponse callback in your proxy options to intercept the upstream response. This is useful for custom error handling or transforming the response before it is sent to the downstream client.

The callback receives: (err, res, request, h, settings, ttl).

• err: The error object if the request failed.
• res: The upstream response object.
• request: The downstream request object.
• h: The hapi toolkit.
• settings: The effective proxy settings.
• ttl: The calculated TTL (if ttl: 'upstream' was used).

h.proxy({
    uri: 'https://api.example.com',
    onResponse: (err, res, request, h, settings, ttl) => {
        if (err) {
            return h.response({ error: 'Upstream unavailable' }).code(502);
        }
        // Custom logic for successful responses
        return h.response(res).ttl(ttl);
    }
});