Сервер

Объект сервера является основным контейнером приложения. Сервер управляет всеми входящими запросами, а также всеми средствами, предоставляемыми фреймворком. Каждый сервер поддерживает одно подключение (например, прослушивает порт 80).

server([options])

Создаёт новый объект сервера, где:

• options - (необязательно) объект конфигурации сервера.

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

const server = Hapi.server({ load: { sampleInterval: 1000 } });

Параметры сервера

Параметры сервера управляют поведением объекта сервера. Обратите внимание, что объект параметров глубоко клонируется (за исключением listener, который копируется поверхностно) и не должен содержать значений, небезопасных для глубокого копирования.

Все параметры необязательны.

server.options.address

Значение по умолчанию: '::' если IPv6 доступен, в противном случае '0.0.0.0' (т.е. все доступные сетевые интерфейсы).

Устанавливает имя хоста или IP-адрес, на котором сервер будет прослушивать. Если не настроен, по умолчанию устанавливается host, если он задан, иначе – все доступные сетевые интерфейсы. Установите значение '127.0.0.1', '::1', или 'localhost' для ограничения сервера только теми подключениями, которые поступают с того же хоста.

server.options.app

Значение по умолчанию: {}.

Предоставляет конфигурацию, специфичную для приложения, к которой можно получить доступ позже через server.settings.app. Фреймворк не взаимодействует с этим объектом. Это просто ссылка, доступная везде, где предоставляется ссылка server.

Обратите внимание на разницу между server.settings.app , используемым для хранения статических значений конфигурации, и server.app, предназначенным для хранения состояния во время выполнения.

server.options.autoListen

Значение по умолчанию: true.

Используется для отключения автоматической инициализации listener. Когда false, указывает, что listener будет запущен вручную вне фреймворка.

Не может быть установлено в false одновременно со значением port.

server.options.cache

Значение по умолчанию: { provider: { constructor: require('@hapi/catbox-memory'), options: { partition: 'hapi-cache' } } }.

Настраивает поставщиков кэширования на стороне сервера. Каждый сервер включает в себя кэш по умолчанию для хранения состояния приложения. По умолчанию создаётся простой кэш на основе памяти, имеющий ограниченную ёмкость и возможности.

hapi использует catbox для реализации кэша, который включает поддержку распространённых решений хранения (например, Redis, MongoDB, Memcached, Riak и др.). Кэширование используется только в том случае, если методы и плагины явно хранят своё состояние в кэше.

Конфигурация кэша сервера определяет только сам контейнер хранения. Конфигурация может быть назначена одному или нескольким (массиву):

• класс или функция прототипа (обычно получаемый вызовом require() к стратегии catbox, например, require('@hapi/catbox-redis')). Внутри будет создан новый клиент catbox клиент с использованием этого конструктора.

• объект конфигурации со следующим:

  • engine - экземпляр объекта движка catbox.

  • name - идентификатор, используемый позже при оснащении или настройке кэширования для методов сервера или плагинов. Каждое имя кэша должно быть уникальным. Один элемент может опустить опцию name, которая определяет кэш по умолчанию. Если каждый кэш включает name, кэш по умолчанию на основе памяти также будет предоставлен.

  • provider - класс, функция-конструктор или объект со следующим:

    • constructor - класс или функция прототипа.

    • options - (необязательно) объект настроек, передаваемый как есть в constructor со следующим:

      • partition - (необязательно) строка, используемая для изоляции кэшированных данных. По умолчанию 'hapi-cache'.
      • другие параметры конструктора, передаваемые в constructor при создании.

  • shared - если true, позволяет нескольким пользователям кэша совместно использовать один и тот же сегмент (например, несколько методов, использующих один и тот же контейнер хранилища кэша). По умолчанию false.

  • Один (и только один) из engine или provider требуется в каждом объекте конфигурации.

server.options.compression

Значение по умолчанию: { minBytes: 1024 }.

Определяет обработку сервером запросов кодирования содержимого. Если false, кодирование содержимого ответа отключено, и сервером не выполняется сжатие.

server.options.compression.minBytes

Значение по умолчанию: '1024'.

Устанавливает минимальный размер полезной нагрузки ответа в байтах, необходимый для сжатия кодирования содержимого. Если размер полезной нагрузки меньше предела, сжатие не выполняется.

server.options.debug

Значение по умолчанию: { request: ['implementation'] }.

Определяет, какие события регистрации отправляются в консоль. Это следует использовать только в целях разработки и не влияет на то, какие события фактически регистрируются внутри и записываются. Установите в false для отключения всех сообщений отладки в консоли, или в объект со:

• log - массив строк тегов журнала сервера, отображаемых в console.error(), когда события регистрируются через server.log(), а также внутренние сгенерированные журналы сервера. По умолчанию не выводится.

• request - массив строк тегов журнала запроса, отображаемых в console.error(), когда события регистрируются через request.log(), а также внутренние сгенерированные журналы запросов. Например, для отображения всех ошибок, установите этот параметр в ['error']. Для отключения всех сообщений отладки в консоли установите в false. Для отображения всех журналов запросов установите в '*'. По умолчанию отображаются необработанные ошибки, сгенерированные внешним кодом (эти ошибки обрабатываются автоматически и приводят к ответу Internal Server Error) или ошибки во время выполнения из-за ошибки разработчика.

Например, для отображения всех ошибок, установите log или request в ['error']. Для отключения всего вывода, установите log или request в false. Для отображения всех журналов сервера, установите log или request в '*'. Для отключения всех данных отладки установите debug в false.

server.options.host

Значение по умолчанию: имя хоста операционной системы, а если он недоступен, то 'localhost'.

Общедоступное имя хоста или IP-адрес. Используется для установки server.info.host и server.info.uri, а также в качестве address, если он не указан.

server.options.info.remote

Значение по умолчанию: false.

Если true, request.info.remoteAddress и request.info.remotePort заполняются при получении запроса, что может потреблять больше ресурсов (но это нормально, если информация нужна, особенно для прерванных запросов). Если false, поля заполняются только по запросу (но будут undefined если доступ к ним осуществляется после прерывания запроса).

server.options.listener

Значение по умолчанию: отсутствует.

Необязательный объект node HTTP (или HTTPS) http.Server (или объект с совместимым интерфейсом).

Если listener необходимо запустить вручную, установите autoListen в false.

Если listener использует TLS, установите tls в true.

server.options.load

Значение по умолчанию: { sampleInterval: 0, maxHeapUsedBytes: 0, maxRssBytes: 0, maxEventLoopDelay: 0, maxEventLoopUtilization: 0 }.

Пределы обработки чрезмерной нагрузки сервера, где:

• sampleInterval - частота выборки в миллисекундах. Если установлено в 0, другие параметры нагрузки игнорируются. По умолчанию 0 (без выборки).

• maxHeapUsedBytes - максимальный размер кучи V8, превышение которого приводит к отклонению входящих запросов с ответом HTTP Server Timeout (503). По умолчанию 0 (без ограничения).

• maxRssBytes - максимальный размер RSS процесса, превышение которого приводит к отклонению входящих запросов с ответом HTTP Server Timeout (503). По умолчанию 0 (без ограничения).

• maxEventLoopDelay - максимальная продолжительность задержки цикла событий в миллисекундах, превышение которой приводит к отклонению входящих запросов с ответом HTTP Server Timeout (503). По умолчанию 0 (без ограничения).

• maxEventLoopUtilization - максимальное значение использования цикла событий, превышение которого приводит к отклонению входящих запросов с ответом HTTP Server Timeout (503). По умолчанию 0 (без ограничения).

server.options.mime

Значение по умолчанию: отсутствует.

Параметры, передаваемые модулю mimos при генерации базы данных MIME, используемой сервером (и доступной через server.mime):

• override - хеш объекта, который объединяется с встроенной информацией MIME, указанной здесь. Каждая пара ключ-значение представляет один объект MIME. Каждое значение замены должно содержать:

  • key - строка типа MIME в нижнем регистре (например, 'application/javascript').

  • value - объект, соответствующий спецификациям, указанным здесь. Дополнительные значения включают:

    • type - указывает значение type для объектов результата, по умолчанию key.

    • predicate - метод с сигнатурой function(mime), когда этот тип MIME найден в базе данных, эта функция будет выполнена для предоставления возможностей кастомизации.

const options = {
    mime: {
        override: {
            'node/module': {
                source: 'iana',
                compressible: true,
                extensions: ['node', 'module', 'npm'],
                type: 'node/module'
            },
            'application/javascript': {
                source: 'iana',
                charset: 'UTF-8',
                compressible: true,
                extensions: ['js', 'javascript'],
                type: 'text/javascript'
            },
            'text/html': {
                predicate: function(mime) {
                    if (someCondition) {
                        mime.foo = 'test';
                    }
                    else {
                        mime.foo = 'bar';
                    }
                    return mime;
                }
            }
        }
    }
};

server.options.operations

Значение по умолчанию: { cleanStop: true }.

Определяет обработку сервером операций сервера:

• cleanStop - если true, сервер отслеживает открытые подключения и должным образом закрывает их при остановке сервера. При нормальной нагрузке это не должно влиять на производительность сервера. Однако при сильной нагрузке мониторинг подключений может потреблять дополнительные ресурсы и усугубить ситуацию. Если сервер никогда не останавливается или если его вынужденно остановить без ожидания закрытия открытых подключений, установка этого значения в false может сохранить ресурсы, которые не используются. По умолчанию true.

server.options.plugins

Значение по умолчанию: {}.

Конфигурация, специфичная для плагина, к которой можно получить доступ позже через server.settings.plugins. plugins — это объект, где каждый ключ — имя плагина, а значение — конфигурация. Обратите внимание на разницу между server.settings.plugins, используемым для хранения статических значений конфигурации, и server.plugins, предназначенным для хранения состояния во время выполнения.

server.options.port

Значение по умолчанию: 0 (эпизодический порт).

Порт TCP, на котором будет прослушивать сервер. По умолчанию сервер выбирает следующий доступный порт при запуске (и присваивается server.info.port).

Если port — строка, содержащая символ '/', она используется в качестве пути к сокету доменной системы UNIX. Если она начинается с '\.\pipe', она используется как имя именованной пайпы Windows.

server.options.query

Значение по умолчанию: {}.

Определяет обработку запросов сервером для компонента запроса пути.

server.options.query.parser

Значение по умолчанию: none.

Устанавливает метод анализа параметров запроса с помощью сигнатуры function(query), где:

• query — объект, содержащий параметры входного request.query.
• метод должен вернуть объект, где каждый ключ — параметр, а соответствующее значение — значение параметра. Если метод вызывает ошибку, ошибка используется в качестве ответа или возвращается при вызове request.setUrl().

const Qs = require('qs');

const options = {
    query: {
        parser: (query) => Qs.parse(query)
    }
};

server.options.router

Значение по умолчанию: { isCaseSensitive: true, stripTrailingSlash: false }.

Управляет тем, как входные URI запросов сопоставляются со справочником маршрутов:

• isCaseSensitive — определяет, считаются ли пути '/example' и '/EXAMPLE' различными ресурсами. По умолчанию true.

• stripTrailingSlash — удаляет завершающие косые черты из входных путей. По умолчанию false.

server.options.routes

Значение по умолчанию: none.

Объект параметров маршрута, используемый в качестве конфигурации по умолчанию для каждого маршрута.

server.options.state

Значение по умолчанию:

{
    strictHeader: true,
    ignoreErrors: false,
    isSecure: true,
    isHttpOnly: true,
    isSameSite: 'Strict',
    encoding: 'none'
}

Устанавливает конфигурацию по умолчанию для каждого состояния (cookie), установленного явно через server.state() или неявно (без определения) с использованием объекта конфигурации состояния.

server.options.tls

Значение по умолчанию: none.

Используется для создания соединения HTTPS. Объект tls передаётся неизменённым серверу node HTTPS как описано в документации node HTTPS.

Устанавливается в true при передаче объекта listener, который был настроен для прямого использования TLS.

server.options.uri

Значение по умолчанию: построено на основе информации о сервере во время выполнения.

Полный общедоступный URI без пути (например, 'http://example.com:8080'). Если он присутствует, используется как информация о сервере, иначе строится из настроек сервера.

Свойства сервера

server.app

Доступ: чтение/запись.

Предоставляет безопасное место для хранения данных приложения сервера во время выполнения без потенциальных конфликтов с внутренними компонентами фреймворка. К данным можно получить доступ, когда сервер доступен. Инициализируется пустым объектом.

const server = Hapi.server();

server.app.key = 'value';

const handler = function (request, h) {

    return request.server.app.key;        // 'value'
};

server.auth.api

Доступ: специфичен для стратегии аутентификации.

Объект, где каждый ключ — имя стратегии аутентификации, а значение — раскрытый API стратегии. Доступен только тогда, когда схема аутентификации раскрывает API, возвращая ключ api в объекте, возвращённом из его функции реализации.

const server = Hapi.server({ port: 80 });

const scheme = function (server, options) {

    return {
        api: {
            settings: {
                x: 5
            }
        },
        authenticate: function (request, h) {

            const authorization = request.headers.authorization;
            if (!authorization) {
                throw Boom.unauthorized(null, 'Custom');
            }

            return h.authenticated({ credentials: { user: 'john' } });
        }
    };
};

server.auth.scheme('custom', scheme);
server.auth.strategy('default', 'custom');

console.log(server.auth.api.default.settings.x);    // 5

server.auth.settings.default

Доступ: только для чтения.

Содержит настройки аутентификации по умолчанию, если стратегия по умолчанию была установлена через server.auth.default().

server.decorations

Доступ: только для чтения.

Предоставляет доступ к уже применённым декорациям к различным интерфейсам фреймворка. Объект нельзя напрямую изменять, а только через server.decorate. Содержит:

• request — декорации объекта запроса.
• response — декорации объекта ответа.
• toolkit — декорации инструментария ответа.
• server — декорации объекта сервера.

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

const success = function () {

    return this.response({ status: 'ok' });
};

server.decorate('toolkit', 'success', success);
console.log(server.decorations.toolkit);            // ['success']

server.events

Доступ: общедоступный интерфейс podium.

Эмиттер событий сервера. Использует podium с поддержкой проверки критериев событий, каналов и фильтров.

Для взаимодействия с server.events используйте следующие методы:

• server.event(events) — регистрация событий приложения.
• server.events.emit(criteria, data) — отправка событий сервера.
• server.events.on(criteria, listener, context) — подписка на все события.
• server.events.once(criteria, listener, context) — подписка на одно событие.

Другие методы включают: server.events.removeListener(name, listener), server.events.removeAllListeners(name), и server.events.hasListeners(name).

'log' Событие

Тип события 'log' отправляет внутренние события сервера, сгенерированные фреймворком, а также события приложения, записанные с помощью server.log().

Обработчик события 'log' использует функцию с сигнатурой function(event, tags), где:

• event — объект со следующими свойствами:

  • timestamp — метка времени события.
  • tags — массив тегов, определяющих событие (например, ['error', 'http']).
  • channel — устанавливается в 'internal' для событий, сгенерированных внутри, иначе 'app' для событий, сгенерированных server.log().
  • data — информация, специфичная для события. Доступна, когда данные события были предоставлены и не являются ошибкой. Ошибки передаются через error.
  • error — объект ошибки, связанный с событием, если применимо. Не может появиться вместе с data.

• tags — объект, где каждый event.tag — ключ, а значение — true. Полезно для быстрого идентификации событий.

server.events.on('log', (event, tags) => {

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

Сгенерированные внутри события (идентифицируются по tags):

• load — записывает текущие измерения загрузки сервера, когда сервер отклоняет запрос из-за высокой загрузки. Данные события содержат метрики загрузки процесса.

• connection client error — событие clientError получено от слушателя HTTP или HTTPS. Данные события — объект ошибки, полученный.

'cachePolicy' Событие

Тип события 'cachePolicy' генерируется при создании политики кэша сервера политика кэша через server.cache() или при регистрации server.method() с включённым кэшированием. Обработчик события 'cachePolicy' использует функцию с сигнатурой function(cachePolicy, cache, segment), где:

• cachePolicy — политика кэша catbox.
• cache — имя обеспечения кэша, использованное при создании политики, или undefined если использовался кэш по умолчанию.
• segment — имя сегмента, использованное при создании политики.

server.events.on('cachePolicy', (cachePolicy, cache, segment) => {

    console.log(`New cache policy created using cache: ${cache === undefined ? 'default' : cache} and segment: ${segment}`);
});

'request' Событие

Тип события 'request' отправляет внутренние события запроса, сгенерированные фреймворком, а также события приложения, записанные с помощью request.log().

Обработчик события 'request' использует функцию с сигнатурой function(request, event, tags), где:

• request — объект запроса.

• event — объект со следующими свойствами:

  • timestamp — метка времени события.
  • tags — массив тегов, определяющих событие (например, ['error', 'http']).
  • channel — одно из
    • 'app' — события, сгенерированные request.log().
    • 'error' — генерируется один раз на запрос, если у ответа был код состояния 500.
    • 'internal' — внутренние сгенерированные события.
  • request — идентификатор запроса идентификатор.
  • data — информация, специфичная для события. Доступна, когда данные события были предоставлены и не являются ошибкой. Ошибки передаются через error.
  • error — объект ошибки, связанный с событием, если применимо. Не может появиться вместе с data.

• tags — объект, где каждый event.tag — ключ, а значение — true. Полезно для быстрого идентификации событий.

server.events.on('request', (request, event, tags) => {

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

Чтобы прослушивать только один из каналов, используйте объект критериев событий:

server.events.on({ name: 'request', channels: 'error' }, (request, event, tags) => {

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

Сгенерированные внутри события (идентифицируются по tags):

• accept-encoding error - запрос содержит неверный заголовок Accept-Encoding.
• auth unauthenticated - со схемой аутентификации в запросе не указано.
• auth unauthenticated response {strategy} - выбранная стратегия аутентификации вернула ответ, не являющийся ошибкой (например, переадресация на страницу входа).
• auth unauthenticated error {strategy} - запрос не прошёл проверку выбранной стратегией аутентификации (неверные учетные данные).
• auth unauthenticated missing {strategy} - запрос не прошёл проверку выбранной стратегией аутентификации (учетные данные не найдены).
• auth unauthenticated try {strategy} - запрос не прошёл проверку выбранной стратегией аутентификации в режиме 'try' и будет продолжен.
• auth scope error - запрос прошёл аутентификацию, но не удовлетворяет требованиям к доступу.
• auth entity user error - запрос прошёл аутентификацию, но содержал сущность приложения, когда требовалась сущность пользователя.
• auth entity app error - запрос прошёл аутентификацию, но содержал сущность пользователя, когда требовалась сущность приложения.
• ext error - произошла ошибка обработчика расширения onPostResponse.
• handler error - обработчик маршрута вернул ошибку. Включает продолжительность выполнения и сообщение об ошибке.
• pre error - метод pre был выполнен и вернул ошибку. Включает продолжительность выполнения, ключ назначения и ошибку.
• internal error - запросу был назначен HTTP-ответ со статусом 500.
• internal implementation error - неправильно реализованный метод жизненного цикла.
• request abort error - запрос прерван.
• request closed error - запрос преждевременно закрыт.
• request error - поток запроса выдал ошибку. Включает ошибку.
• request server timeout error - запрос занял слишком много времени на обработку сервером. Включает значение конфигурации таймаута и продолжительность.
• state error - запрос содержал недействительный cookie или cookies. Включает cookies и подробности ошибки.
• state response error - ответ содержал недействительный cookie, что помешало генерации корректного заголовка. Включает ошибку.
• payload error - произошла ошибка обработки тела запроса. Включает ошибку.
• response error - произошла ошибка при записи ответа клиенту. Включает ошибку.
• response error close - произошла ошибка при записи ответа клиенту из-за преждевременного закрытия соединения.
• response error aborted - произошла ошибка при записи ответа клиенту из-за преждевременного прерывания соединения.
• response error cleanup - произошла ошибка при освобождении ресурсов ответа.
• validation error {input} - произошла ошибка валидации входных данных (т.е. тела, запроса, параметров, заголовков). Включает ошибку. Выдаётся только при установленном failAction в значение 'log'.
• validation response error - произошла ошибка валидации ответа. Включает сообщение об ошибке. Выдаётся только при установленном failAction в значение 'log'.

'response' Событие

Тип события 'response' срабатывает после отправки ответа клиенту (или при закрытии соединения с клиентом без отправки ответа, в этом случае request.response равен null). Одно событие генерируется на запрос. Обработчик события 'response' использует сигнатуру функции function(request), где:

• request - объект запроса.

server.events.on('response', (request) => {

    console.log(`Response sent for request: ${request.info.id}`);
});

'route' Событие

Тип события 'route' срабатывает при добавлении маршрута с помощью server.route(). Обработчик события 'route' использует сигнатуру функции function(route), где:

• route - информация о маршруте. Объект route не должен изменяться.

server.events.on('route', (route) => {

    console.log(`New route added: ${route.path}`);
});

'start' Событие

Тип события 'start' срабатывает при запуске сервера с помощью server.start(). Обработчик события 'start' использует сигнатуру функции function().

server.events.on('start', () => {

    console.log('Server started');
});

'closing' Событие

Тип события 'closing' срабатывает при остановке сервера с помощью server.stop(). Оно срабатывает, когда приём входящих запросов больше не производится, но до закрытия всех активных подключений, и, следовательно, до срабатывания события 'stop'. Обработчик события 'closing' использует сигнатуру функции function().

server.events.on('closing', () => {

    console.log('Server is closing');
});

'stop' Событие

Тип события 'stop' срабатывает при остановке сервера с помощью server.stop(). Обработчик события 'stop' использует сигнатуру функции function().

server.events.on('stop', () => {

    console.log('Server stopped');
});

server.info Информация о сервере

Доступ: только для чтения.

Объект, содержащий информацию о сервере, где:

• id - уникальный идентификатор сервера (в формате '{имя_хоста}:{PID}:{текущее_время_base36}').

• created - метка времени создания сервера.

• started - метка времени запуска сервера (0 при остановке).

• port - порт подключения, определённый по следующим правилам:

  • до запуска сервера: значение конфигурации port.
  • после запуска сервера: фактический назначенный порт, если порт не был сконфигурирован или был установлен в 0.

• host - значение конфигурации host.

• address - активный IP-адрес, к которому подключение было привязано после запуска. Устанавливается в undefined до запуска сервера или при использовании порта, отличного от TCP (например, UNIX-доменная сокета).

• protocol - используемый протокол:

  • 'http' - HTTP.
  • 'https' - HTTPS.
  • 'socket' - UNIX-доменная сокета или именованная труба Windows.

• uri - строковое представление подключения (например, 'http://example.com:8080' или 'socket:/unix/domain/socket/path'). Содержит значение uri, если оно задано, в противном случае построено на основе доступных настроек. Если конфигурация port не задана или установлена в 0, компонент порта в uri не будет включён до запуска сервера.

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

console.log(server.info.port);            // 80

server.listener Слушатель сервера

Доступ: только для чтения и публичный интерфейс слушателя.

Объект HTTP-сервера Node.

const Hapi = require('@hapi/hapi');
const SocketIO = require('socket.io');

const server = Hapi.server({ port: 80 });

const io = SocketIO.listen(server.listener);
io.sockets.on('connection', (socket) => {

    socket.emit({ msg: 'welcome' });
});

server.load Загрузка сервера

Доступ: только для чтения.

Объект, содержащий метрики загрузки процесса (когда включён load.sampleInterval):

• eventLoopDelay - задержка цикла событий в миллисекундах.
• eventLoopUtilization - текущее значение использования цикла событий.
• heapUsed - использование памяти кучи V8.
• rss - использование памяти RSS.

const Hapi = require('@hapi/hapi');
const server = Hapi.server({ load: { sampleInterval: 1000 } });

console.log(server.load.rss);

server.methods Методы сервера

Доступ: только для чтения.

Методы сервера — это функции, зарегистрированные на сервере и используемые в приложении в качестве общих утилит. Преимущество в возможности их настройки для использования встроенного кеша и совместного использования между несколькими обработчиками запросов без необходимости создания общего модуля.

sever.methods — это объект, предоставляющий доступ к методам, зарегистрированным с помощью server.method(), где каждое имя метода сервера является свойством объекта.

const Hapi = require('@hapi/hapi');
const server = Hapi.server();

server.method('add', (a, b) => (a + b));
const result = server.methods.add(1, 2);    // 3

server.mime MIME-типы сервера

Доступ: только для чтения и публичный интерфейс mimos.

Предоставляет доступ к базе данных MIME-типов сервера, используемой для задания информации о формате содержимого. Объект не должен изменяться напрямую, а только через настройку сервера mime.

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

const options = {
    mime: {
        override: {
            'node/module': {
                source: 'steve',
                compressible: false,
                extensions: ['node', 'module', 'npm'],
                type: 'node/module'
            }
        }
    }
};

const server = Hapi.server(options);
console.log(server.mime.path('code.js').type)        // 'application/javascript'
console.log(server.mime.path('file.npm').type)        // 'node/module'

server.plugins Плагины сервера

Доступ: чтение/запись.

Объект, содержащий значения, экспонированные каждым зарегистрированным плагином, где каждый ключ — имя плагина, а значения — экспонированные свойства каждого плагина с использованием server.expose(). Плагины могут устанавливать значение объекта server.plugins[name] напрямую или с помощью метода server.expose().

exports.plugin = {
    name: 'example',
    register: function (server, options) {

        server.expose('key', 'value');
        server.plugins.example.other = 'other';

        console.log(server.plugins.example.key);      // 'value'
        console.log(server.plugins.example.other);    // 'other'
    }
};

server.realm Область сервера

Доступ: только для чтения.

Объект области содержит защищённые настройки сервера, специфичные для каждого плагина или стратегии аутентификации. При регистрации плагина или схемы аутентификации предоставляется ссылка на объект server, с новым контейнером server.realm, специфичным для этой регистрации. Это позволяет каждому плагину сохранять свои собственные настройки без утечек и влияния на другие плагины.

Например, плагин может установить путь к файлу по умолчанию для локальных ресурсов без нарушения конфигурированных путей других плагинов. При вызове server.bind(), свойство settings.bind активной области устанавливается и используется маршрутами и расширениями, добавленными на том же уровне (корень сервера или плагин).

Объект server.realm содержит:

• modifiers - когда объект сервера предоставляется в качестве аргумента плагину register() метод, modifiers предоставляет настройки регистрации, переданные методу server.register(), и включает:

  • route - настройки маршрутизации:

    • prefix - префикс пути маршрута, используемый всеми вызовами server.route() со стороны сервера. Обратите внимание, что если используется префикс, и путь маршрута задан как '/', результирующий путь не будет содержать заключительный слеш.
    • vhost - настройки виртуального хоста маршрута, используемые всеми вызовами server.route() со стороны сервера.

• parent - область родительского объекта сервера или null для корневого сервера.

• plugin - имя активного плагина (пустая строка, если на корневом сервере).

• pluginOptions - параметры плагина, переданные при регистрации.

• plugins - состояние, специфичное для плагина, которое должно быть доступно только активным плагинам, работающим в одном состоянии. plugins - это объект, где каждый ключ — имя плагина, а значение — состояние плагина.

• settings - переопределения настроек:

  • files.relativeTo
  • bind

Объект server.realm следует считать только для чтения и его нельзя изменять напрямую, за исключением свойства plugins, которое каждый плагин может непосредственно управлять, устанавливая его свойства внутри plugins[name].

exports.register = function (server, options) {

    console.log(server.realm.modifiers.route.prefix);
};

server.registrations

Доступ: только для чтения.

Объект текущих зарегистрированных плагинов, где каждый ключ — имя зарегистрированного плагина, а значение — объект, содержащий:

• version - версия плагина.
• name - имя плагина.
• options - (необязательно) параметры, переданные плагину при регистрации.

server.settings

Доступ: только для чтения.

Объект конфигурации сервера после применения значений по умолчанию.

const Hapi = require('@hapi/hapi');
const server = Hapi.server({
    app: {
        key: 'value'
    }
});

console.log(server.settings.app);   // { key: 'value' }

server.states

Доступ: только для чтения и statehood общедоступный интерфейс.

Менеджер файлов cookie сервера.

server.states.settings

Доступ: только для чтения.

Настройки менеджера файлов cookie сервера. Настройки основаны на значениях, настроенных в server.options.state.

server.states.cookies

Доступ: только для чтения.

Объект, содержащий конфигурацию каждого файла cookie, добавленного с помощью server.state(), где каждый ключ — имя файла cookie, а значение — объект конфигурации.

server.states.names

Доступ: только для чтения.

Массив, содержащий имена всех настроенных файлов cookie.

server.type

Доступ: только для чтения.

Строка, указывающая тип слушателя, где:

• 'socket' - сокет доменной UNIX-системы или именованная Windows-пайпа.
• 'tcp' - HTTP-слушатель.

server.version

Доступ: только для чтения.

Номер версии модуля hapi.

const Hapi = require('@hapi/hapi');
const server = Hapi.server();

console.log(server.version);        // '17.0.0'

server.auth.default(options)

Устанавливает стратегию по умолчанию, которая применяется ко всем маршрутам, где:

• options - один из:

  • строка с именем стратегии по умолчанию
  • объект конфигурации аутентификации, использующий тот же формат, что и параметры обработчика маршрута auth.

Возвращаемое значение: ничего.

Стратегия по умолчанию не применяется, если маршрут явно указывает auth как false, или имеет настроенную стратегию аутентификации (содержит параметры аутентификации strategy или strategies).

Обратите внимание, что если для маршрута настроена аутентификация, стратегия по умолчанию применяется только при добавлении маршрута, а не во время выполнения. Это означает, что вызов server.auth.default() после добавления маршрута с настройками аутентификации не повлияет на ранее добавленные маршруты. Однако стратегия по умолчанию будет применена к маршрутам, добавленным до вызова server.auth.default() , если эти маршруты не имеют настроек аутентификации.

Настройки стратегии аутентификации по умолчанию можно получить с помощью server.auth.settings.default. Чтобы получить активную конфигурацию аутентификации маршрута, используйте server.auth.lookup(request.route).

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

server.auth.scheme('custom', scheme);
server.auth.strategy('default', 'custom');
server.auth.default('default');

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

        return request.auth.credentials.user;
    }
});

server.auth.scheme(name, scheme)

Регистрирует схему аутентификации, где:

• name - имя схемы.
• scheme - метод, реализующий схему, со сигнатурой function(server, options), где:
  • server - ссылка на объект сервера, к которому добавляется схема. Каждая стратегия аутентификации получает собственную server.realm, родитель которой — область server при вызове server.auth.strategy().
  • options - (необязательно) аргумент схемы options, переданный в server.auth.strategy() при создании стратегии.

Возвращаемое значение: ничего.

Функция scheme должна возвращать объект схемы аутентификации при вызове.

Схема аутентификации

Схема аутентификации — это объект со следующими свойствами:

• api - (необязательно) объект, доступный через объект server.auth.api.

• async authenticate(request, h) - (обязательно) функция метода жизненного цикла, вызываемая для каждого входящего запроса, настроенного со схемой аутентификации. Методу предоставляются два специальных метода инструментария для возврата аутентифицированного или неаутентифицированного результата:

  • h.authenticated() - указывает, что запрос аутентифицирован успешно.
  • h.unauthenticated() - указывает, что запрос не смог пройти аутентификацию.

• async payload(request, h) - (необязательно) метод жизненного цикла для аутентификации полезной нагрузки запроса.

• async response(request, h) - (необязательно) метод жизненного цикла для добавления заголовков аутентификации в ответ перед записью заголовков или полезной нагрузки ответа.

• async verify(auth) - (необязательно) метод для проверки того, что предоставленные учетные данные аутентификации по-прежнему действительны (например, не истекли или не аннулированы после первоначальной аутентификации), где:

  • auth - объект request.auth, содержащий объекты credentials и artifacts, возвращенные методом схемы authenticate().
  • метод генерирует исключение Error, когда предоставленные учетные данные больше не действительны (например, истекли или аннулированы). Обратите внимание, что методу не доступен исходный запрос, только учетные данные и артефакты, созданные методом authenticate().

• options - (необязательно) объект со следующими ключами:

  • payload - если true, требуется валидация полезной нагрузки в качестве части схемы и запрещает маршрутам отключать валидацию полезной нагрузки. По умолчанию false.

Когда метод схемы authenticate() вызывает ошибку или вызывает h.unauthenticated(), конкретика ошибки влияет на то, будут ли предприняты дополнительные стратегии аутентификации (если они настроены для маршрута). Если ошибка содержит сообщение, дополнительные стратегии не будут предприняты. Если ошибка не содержит сообщения, но содержит имя схемы (например, Boom.unauthorized(null, 'Custom')), дополнительные стратегии будут предприняты в порядке приоритета (определенном в конфигурации маршрута). При неудачной аутентификации имена схем будут присутствовать в заголовке «WWW-Authenticate».

Когда метод схемы payload() вызывает ошибку с сообщением, это означает, что валидация полезной нагрузки не прошла из-за некорректной полезной нагрузки. Если ошибка не содержит сообщения, но содержит имя схемы (например, Boom.unauthorized(null, 'Custom') ), аутентификация все еще может быть успешной, если настройка маршрута auth.payload установлена в 'optional'.

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

const scheme = function (server, options) {

    return {
        authenticate: function (request, h) {

            const req = request.raw.req;
            const authorization = req.headers.authorization;
            if (!authorization) {
                throw Boom.unauthorized(null, 'Custom');
            }

            return h.authenticated({ credentials: { user: 'john' } });
        }
    };
};

server.auth.scheme('custom', scheme);

server.auth.strategy(name, scheme, [options])

Регистрирует стратегию аутентификации, где:

• name - имя стратегии.
• scheme - имя схемы (должно быть предварительно зарегистрировано с помощью server.auth.scheme()).
• options - параметры схемы, основанные на требованиях схемы.

Возвращаемое значение: ничего.

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

server.auth.scheme('custom', scheme);
server.auth.strategy('default', 'custom');

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

            return request.auth.credentials.user;
        }
    }
});

await server.auth.test(strategy, request)

Проверяет запрос по стратегии аутентификации, где:

• strategy - имя стратегии, зарегистрированной с помощью server.auth.strategy().
• request - объект запроса.

Возвращаемое значение: объект, содержащий аутентификацию credentials и artifacts , если аутентификация прошла успешно, в противном случае генерируется ошибка.

Обратите внимание, что метод test() не учитывает конфигурацию аутентификации маршрута. Он также не выполняет аутентификацию полезной нагрузки. Он ограничен выполнением основной аутентификации стратегии. Он не включает проверку области, сущности или других свойств маршрута.

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

server.auth.scheme('custom', scheme);
server.auth.strategy('default', 'custom');

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

        try {
            const { credentials, artifacts } = await request.server.auth.test('default', request);
            return { status: true, user: credentials.name };
        }
        catch (err) {
            return { status: false };
        }
    }
});

await server.auth.verify(request)

Проверяет учетные данные аутентификации запроса по стратегии аутентификации, где:

• request - объект запроса.

Возвращаемое значение: ничего, если проверка прошла успешно, в противном случае генерируется ошибка.

Обратите внимание, что метод verify() не учитывает конфигурацию аутентификации маршрута или любую другую информацию из запроса, кроме объекта request.auth. Он также не выполняет аутентификацию полезной нагрузки. Он ограничен проверкой того, что ранее действительные учетные данные по-прежнему действительны (например, не аннулированы или не истекли). Он не включает проверку области, сущности или других свойств.

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

server.auth.scheme('custom', scheme);
server.auth.strategy('default', 'custom');

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

        try {
            const credentials = await request.server.auth.verify(request);
            return { status: true, user: credentials.name };
        }
        catch (err) {
            return { status: false };
        }
    }
});

server.bind(context)

Устанавливает глобальный контекст, используемый в качестве объекта связывания по умолчанию при добавлении маршрута или расширения, где:

• context — объект, используемый для привязки this в методах жизненного цикла, таких как обработчик маршрута и методы расширения. Контекст также доступен как h.context.

Значение возврата: ничего.

При установке контекста внутри плагина, контекст применяется только к методам, настроенным плагином. Обратите внимание, что контекст применяется только к маршрутам и расширениям, добавленным после его установки. Игнорируется, если привязываемый метод является стрелочной функцией.

const handler = function (request, h) {

    return this.message;    // Or h.context.message
};

exports.plugin = {
    name: 'example',
    register: function (server, options) {

        const bind = {
            message: 'hello'
        };

        server.bind(bind);
        server.route({ method: 'GET', path: '/', handler });
    }
};

server.cache(options)

Предоставляет сегмент кэша внутри серверного кэша, где:

• options — конфигурация catbox политики, где:

  • expiresIn — относительный срок истечения, выраженный в миллисекундах с момента сохранения элемента в кэше. Нельзя использовать вместе с expiresAt.

  • expiresAt — время суток, выраженное в 24-часовом формате 'ЧЧ:ММ', в которое все записи кэша истекают. Используется местное время. Нельзя использовать вместе с expiresIn.

  • generateFunc — функция, используемая для генерации нового элемента кэша, если он не найден в кэше при вызове get(). Подпись метода: async function(id, flags), где:

    - `id` - the `id` string or object provided to the `get()` method.
    - `flags` - an object used to pass back additional flags to the cache where:
        - `ttl` - the cache ttl value in milliseconds. Set to `0` to skip storing in the
          cache. Defaults to the cache global policy.
    

  • staleIn — число миллисекунд, чтобы пометить элемент, сохраненный в кэше, как устаревший и попытаться перегенерировать его, когда generateFunc предоставлен. Должно быть меньше expiresIn.

  • staleTimeout — число миллисекунд, через которое проверяется, является ли элемент устаревшим.

  • generateTimeout — число миллисекунд, через которое ожидается возврат ошибки тайм-аута, когда функция generateFunc занимает слишком много времени для возвращения значения. Когда значение, наконец, возвращено, оно хранится в кэше для будущих запросов. Требуется, если generateFunc присутствует. Установлено в false, чтобы отключить тайм-ауты, что может привести к зависанию всех запросов get() на неопределенное время.

  • generateOnReadError — если false, ошибка чтения из upstream кэша остановит метод cache.get() от вызова функции генерации, а вместо этого вернёт ошибку кэша. По умолчанию true.

  • generateIgnoreWriteError — если false, ошибка записи в upstream кэша при вызове cache.get() будет возвращена вместе с сгенерированным значением при вызове. По умолчанию true.

  • dropOnError — если true, ошибка или тайм-аут в generateFunc приводит к удалению устаревшего значения из кэша. По умолчанию true.

  • pendingGenerateTimeout — число миллисекунд, пока вызов generateFunc продолжается для данного идентификатора, прежде чем последующий вызов generateFunc будет разрешен. По умолчанию 0 (нет блокировки одновременных вызовов generateFunc помимо staleTimeout).

  • cache — имя кэша, настроенное в server.cache. По умолчанию — кэш по умолчанию.

  • segment — имя сегмента, используемое для изоляции кэшированных элементов в разделе кэша. При вызове внутри плагина, по умолчанию '!имя', где 'имя' — имя плагина. При вызове внутри серверного метода, по умолчанию '#имя', где 'имя' — имя серверного метода. Требуется при вызове вне плагина.

  • shared — если true, позволяет нескольким кэшам разделять один и тот же сегмент. По умолчанию false.

Значение возврата: объект catbox политики.

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

async function example() {

    const server = Hapi.server({ port: 80 });
    const cache = server.cache({ segment: 'countries', expiresIn: 60 * 60 * 1000 });
    await cache.set('norway', { capital: 'oslo' });
    const value = await cache.get('norway');
}

await server.cache.provision(options)

Предоставляет серверный кэш, как описано в server.cache, где:

• options — такие же, как серверные cache опции конфигурации.

Значение возврата: ничего.

Обратите внимание, что если сервер был инициализирован или запущен, кэш будет автоматически запущен, чтобы соответствовать состоянию любого другого предоставленного серверного кэша.

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

async function example() {

    const server = Hapi.server({ port: 80 });
    await server.initialize();
    await server.cache.provision({ provider: require('@hapi/catbox-memory'), name: 'countries' });

    const cache = server.cache({ cache: 'countries', expiresIn: 60 * 60 * 1000 });
    await cache.set('norway', { capital: 'oslo' });
    const value = await cache.get('norway');
}

server.control(server)

Связывает другой сервер с состоянием инициализации/старта/остановки текущего сервера, вызывая у управляемого сервера методы initialize()/start()/stop() всякий раз, когда вызываются методы текущего сервера, где:

• server — объект сервера hapi, который будет управляется.

server.decoder(encoding, decoder)

Регистрирует пользовательский декомпрессор кодирования для расширения встроенной поддержки 'gzip' и 'deflate', где:

• encoding — строка имени декодера.

• decoder — функция, использующая подпись function(options), где options — опции, специфичные для кодирования, настроенные в маршрутной опции payload.compression, а возвращаемое значение — объект, совместимый с выводом нода zlib.createGunzip().

Значение возврата: ничего.

const Zlib = require('zlib');
const Hapi = require('@hapi/hapi');
const server = Hapi.server({ port: 80, routes: { payload: { compression: { special: { chunkSize: 16 * 1024 } } } } });

server.decoder('special', (options) => Zlib.createGunzip(options));

server.decorate(type, property, method, [options])

Расширяет различные интерфейсы фреймворка пользовательскими методами, где:

• type — декорируемый интерфейс. Поддерживаемые типы:

  • 'handler' — добавляет новый тип обработчика, используемый в обработчиках маршрутов.
  • 'request' — добавляет методы к объекту Запрос.
  • 'response' — добавляет методы к объекту Ответ.
  • 'server' — добавляет методы к объекту Сервер.
  • 'toolkit' — добавляет методы к инструментарию ответа.

• property — имя ключа декорации объекта или символ.

• method — функция расширения или другое значение.

• options — (необязательно) поддерживает следующие необязательные параметры:

  • apply — когда type равно 'request', если true, функция method вызывается с подписью function(request), где request — текущий объект запроса, а возвращаемое значение назначается как декорация.
  • extend — если true, переопределяет существующую декорацию. method должна быть функцией с подписью function(existing), где:
    • existing — предыдущее значение метода декорации.
    • должна возвращать новую функцию или значение декорации.
    • не может быть использована для расширения декораций обработчиков.

Значение возврата: ничего.

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

const success = function () {

    return this.response({ status: 'ok' });
};

server.decorate('toolkit', 'success', success);

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

        return h.success();
    }
});

При регистрации декорации обработчика, method должна быть функцией с подписью function(route, options), где:

• route — информация о маршруте.
• options — объект конфигурации, предоставленный в конфигурации обработчика.

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

async function example() {

    const server = Hapi.server({ host: 'localhost', port: 8000 });

    // Defines new handler for routes on this server

    const handler = function (route, options) {

        return function (request, h) {

            return 'new handler: ' + options.msg;
        }
    };

    server.decorate('handler', 'test', handler);

    server.route({
        method: 'GET',
        path: '/',
        handler: { test: { msg: 'test' } }
    });

    await server.start();
}

Функция method может иметь свойство объекта или функции defaults. Если свойство установлено в объект, этот объект используется в качестве конфигурации по умолчанию для маршрутов, использующих этот обработчик. Если свойство установлено в функцию, функция использует подпись function(method) и возвращает конфигурацию маршрута по умолчанию.

const Hapi = require('@hapi/hapi');
const server = Hapi.server({ host: 'localhost', port: 8000 });

const handler = function (route, options) {

    return function (request, h) {

        return 'new handler: ' + options.msg;
    }
};

// Change the default payload processing for this handler

handler.defaults = {
    payload: {
        output: 'stream',
        parse: false
    }
};

server.decorate('handler', 'test', handler);

server.dependency(dependencies, [after])

Используется в плагине для объявления необходимой зависимости от других плагинов, необходимых для работы текущего плагина (перечисленные плагины должны быть зарегистрированы перед инициализацией или запуском сервера), где:

• dependencies — одно из:

  • строка имени одного плагина.
  • массив строк имён плагинов.
  • объект, где каждый ключ — имя плагина, а соответствующее значение — строка диапазона версии, которая должна соответствовать зарегистрированной версии плагина.

• after — (необязательно) функция, вызываемая после регистрации всех указанных зависимостей и перед запуском сервера. Функция вызывается только при инициализации или запуске сервера. Подпись функции: async function(server), где:

  • server — сервер, на котором был вызван метод dependency().

Значение возврата: ничего.

Метод after идентичен установке точки расширения сервера на 'onPreStart'.

Если обнаружена циклическая зависимость, выводится исключение (например, два плагина имеют функцию after для вызова друг после друга).

const after = function (server) {

    // Additional plugin registration logic
};

exports.plugin = {
    name: 'example',
    register: function (server, options) {

        server.dependency('yar', after);
    }
};

Зависимости также могут быть установлены через свойство плагина dependencies (не поддерживает установку after):

exports.plugin = {
    name: 'test',
    version: '1.0.0',
    dependencies: {
        yar: '1.x.x'
    },
    register: function (server, options) { }
};

Конфигурация dependencies принимает одно из:

• строка имени одного плагина.
• массив строк имён плагинов.
• объект, где каждый ключ — имя плагина, а соответствующее значение — строка диапазона версии, которая должна соответствовать зарегистрированной версии плагина.

server.encoder(encoding, encoder)

Регистрирует пользовательский компрессор кодирования для расширения встроенной поддержки 'gzip' и 'deflate', где:

• encoding — строка имени кодировщика.

• encoder — функция, использующая подпись function(options), где options — опции, специфичные для кодирования, настроенные в опции маршрута compression, а возвращаемое значение — объект, совместимый с выводом нода zlib.createGzip().

Значение возврата: ничего.

const Zlib = require('zlib');
const Hapi = require('@hapi/hapi');
const server = Hapi.server({ port: 80, routes: { compression: { special: { chunkSize: 16 * 1024 } } } });

server.encoder('special', (options) => Zlib.createGzip(options));

server.event(events)

Регистрирует пользовательские события приложения, где:

• events - должно быть одним из следующих:

  • строка имени события.

  • объект опций события со следующими необязательными ключами (если не указано иное):

    • name - строка имени события (обязательно).

    • channels - строка или массив строк, определяющих доступные каналы события. По умолчанию никаких ограничений по каналам (обновления события могут указывать канал или нет).

    • clone - если true, то объект data, переданный в server.events.emit(), клонируется перед передачей слушателям (если не указано иначе каждым слушателем). По умолчанию false (data передаётся как есть).

    • spread - если true, то объект data, переданный в server.event.emit(), должен быть массивом, и метод listener вызывается с каждым элементом массива в качестве отдельного аргумента (если не указано иначе каждым слушателем). Это следует использовать только тогда, когда структура данных, отправляемых на передачу, известна и предсказуема. По умолчанию false (data передаётся как один аргумент независимо от его типа).

    • tags - если true и объект criteria, переданный в server.event.emit(), включает tags, метки отображаются в объект (где каждая строка метки — ключ, а значение — true), который добавляется в список аргументов в конце. Настройка может быть переопределена каждым слушателем. По умолчанию false.

    • shared - если true, то одно и то же событие name может быть зарегистрировано несколько раз, при этом повторная регистрация игнорируется. Обратите внимание, что если конфигурация регистрации изменяется между регистрацией, используется только первая конфигурация. По умолчанию false (повторная регистрация вызовет ошибку).

  • массив, содержащий любой из вышеперечисленных элементов.

Значение возврата: ничего.

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

async function example() {

    const server = Hapi.server({ port: 80 });
    server.event('test');
    server.events.on('test', (update) => console.log(update));
    await server.events.gauge('test', 'hello');
}

server.events.emit(criteria, data)

Отправляет пользовательское событие приложения всем подписанным слушателям, где:

• criteria - критерии обновления события, которые должны быть одним из следующих:

  • строка имени события.
  • объект со следующими необязательными ключами (если не указано иное):
    • name - строка имени события (обязательно).
    • channel - строка имени канала.
    • tags - строка тега или массив строк тегов.

• data - значение, отправляемое подписчикам. Если data является функцией, сигнатура функции — function(), и она вызывается один раз для генерации (возвращаемого значения) фактических данных, отправляемых слушателям. Если слушатели, соответствующие событию, отсутствуют, функция data не вызывается.

Значение возврата: ничего.

Обратите внимание, что события должны быть зарегистрированы перед их отправкой или подпиской на них, вызвав server.event(events). Это делается для обнаружения опечаток в имени события и недопустимых действий с событием.

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

async function example() {

    const server = Hapi.server({ port: 80 });
    server.event('test');
    server.events.on('test', (update) => console.log(update));
    server.events.emit('test', 'hello');
}

server.events.on(criteria, listener, context)

Подписывается на событие, где:

• criteria - критерии подписки, которые должны быть одним из следующих:

  • строка имени события, которая может быть любой из встроенных событий сервера или пользовательского события приложения, зарегистрированного с помощью server.event().

  • объект критериев со следующими необязательными ключами (если не указано иное):

    • name - (обязательно) строка имени события.

    • channels - строка или массив строк, определяющих каналы события для подписки. Если регистрация события указала список разрешенных каналов, массив channels должен соответствовать разрешенным каналам. Если channels указаны, обновления событий без обозначения канала не будут включены в подписку. По умолчанию никаких фильтров по каналам.

    • clone - если true, то объект data, переданный в server.event.emit(), клонируется перед вызовом метода listener. По умолчанию опция регистрации события (которая по умолчанию false).

    • count - целое положительное число, указывающее количество раз, которое listener может быть вызвано, после чего подписка автоматически удаляется. Значение 1 эквивалентно вызову server.events.once(). По умолчанию нет лимита.

    • filter - метки события (если есть) для подписки, которые могут быть одним из следующих:

      • строка метки.

      • массив строк меток.

      • объект со следующим:

        • tags - строка метки или массив строк меток.
        • all - если true, все tags должны быть присутствовать для того, чтобы обновление события соответствовало подписке. По умолчанию false (хотя бы одна совпадающая метка).

    • spread - если true, и объект data, переданный в server.event.emit(), является массивом, метод listener вызывается с каждым элементом массива в качестве отдельного аргумента. Это следует использовать только тогда, когда структура данных, отправляемых на передачу, известна и предсказуема. По умолчанию опция регистрации события (которая по умолчанию false).

    • tags - если true и объект criteria, переданный в server.event.emit(), включает tags, метки отображаются в объект (где каждая строка метки — ключ, а значение — true), который добавляется в список аргументов в конце. По умолчанию опция регистрации события (которая по умолчанию false).

• listener - метод обработчика, настроенный для получения обновлений события. Сигнатура функции зависит от аргумента события, а также от опций spread и tags.

• context - объект, привязанный к обработчику слушателя.

Значение возврата: ничего.

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

async function example() {

    const server = Hapi.server({ port: 80 });
    server.event('test');
    server.events.on('test', (update) => console.log(update));
    server.events.emit('test', 'hello');
}

server.events.once(criteria, listener, context)

То же, что и вызов server.events.on() с опцией count установленной в 1.

Значение возврата: ничего.

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

async function example() {

    const server = Hapi.server({ port: 80 });
    server.event('test');
    server.events.once('test', (update) => console.log(update));
    server.events.emit('test', 'hello');
    server.events.emit('test', 'hello');       // Ignored
}

await server.events.once(criteria)

То же, что и вызов server.events.on() с опцией count установленной в 1.

Значение возврата: промис, который разрешается, когда событие отправляется.

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

async function example() {

    const server = Hapi.server({ port: 80 });
    server.event('test');
    const pending = server.events.once('test');
    server.events.emit('test', 'hello');
    const update = await pending;
}

await server.events.gauge(criteria, data)

Ведёт себя идентично server.events.emit(), но также возвращает массив результатов всех обработчиков событий, которые выполняются. Возвращаемое значение - это результат Promise.allSettled(), где каждый элемент в результирующем массиве - это { status: 'fulfilled', value } в случае успешного обработчика или { status: 'rejected', reason } в случае обработчика, который вызывает ошибку.

Обратите внимание, что системные ошибки, такие как TypeError, не обрабатываются специально, и рекомендуется тщательно проверять любые отклонения с помощью чего-либо вроде bounce.

server.expose(key, value, [options])

Используется внутри плагина для экспонирования свойства через server.plugins[name], где:

• key - назначенный ключ (server.plugins[name][key]).
• value - назначенное значение.
• options - необязательные настройки:
  • scope - управляет тем, как обрабатывать наличие области видимости плагина в имени (например, @hapi/test):
    • false - область видимости удаляется (например, @hapi/test изменяется на test под server.plugins). Это значение по умолчанию.
    • true - область видимости сохраняется как есть (например, @hapi/test используется как server.plugins['@hapi/test']).
    • 'underscore' - область видимости переписывается (например, @hapi/test используется как server.plugins.hapi__test).

Значение возврата: ничего.

exports.plugin =
    name: 'example',
    register: function (server, options) {

        server.expose('util', () => console.log('something'));
    }
};

server.expose(obj)

Объединяет объект в существующее содержимое server.plugins[name], где:

• obj - объект, объединяемый в контейнер экспонированных свойств.

Значение возврата: ничего.

exports.plugin = {
    name: 'example',
    register: function (server, options) {

        server.expose({ util: () => console.log('something') });
    }
};

Обратите внимание, что все свойства obj глубоко клонируются в server.plugins[name], поэтому не используйте этот метод для экспонирования больших объектов, которые могут быть дорогими для клонирования или одиночных объектов, таких как объекты клиента базы данных. Вместо этого отдавайте предпочтение server.expose(key, value), который копирует только ссылку на value.

server.ext(events)

Регистрирует функцию расширения в одном из пунктов расширения цикла жизни запроса , где:

• events - объект или массив объектов со следующими полями:

  • type - (обязательно) имя события точки расширения. Доступные точки расширения включают точки расширения запроса, а также следующие точки расширения сервера:

    • 'onPreStart' - вызывается перед запуском слушателей соединения.
    • 'onPostStart' - вызывается после запуска слушателей соединения.
    • 'onPreStop' - вызывается перед остановкой слушателей соединения.
    • 'onPostStop' - вызывается после остановки слушателей соединения.

  • method - (обязательно) функция или массив функций, которые должны быть выполнены в определённый момент обработки запроса. Требуемая сигнатура функции расширения:

    • точки расширения сервера: async function(server) где:

      • server - объект сервера.
      • this - объект, предоставленный через options.bind или текущий активный контекст, установленный с помощью server.bind().

    • точки расширения запроса: метод жизненного цикла.

  • options - (необязательно) объект со следующими полями:

    • before - строка или массив строк с именами плагинов, которые этот метод должен выполнить перед ним (в том же событии). В противном случае, методы расширения выполняются в порядке добавления.

    • after - строка или массив строк с именами плагинов, которые этот метод должен выполнить после него (в том же событии). В противном случае, методы расширения выполняются в порядке добавления.

    • bind - объект контекста, передаваемый обратно предоставленному методу (через this) при его вызове. Игнорируется, если метод является стрелочной функцией.

    • sandbox - если установлено в 'plugin', при добавлении точек расширения запроса расширение добавляется только к маршрутам, определённым текущим плагином. Не разрешается при конфигурировании расширений на уровне маршрутов или при добавлении расширений сервера. По умолчанию установлено в 'server', что применяется к любому маршруту, добавленному к серверу, к которому добавлено расширение.

    • timeout - количество миллисекунд, ожидаемых для выполнения method, прежде чем вернуть ошибку таймаута. По умолчанию таймаут не используется.

Значение возврата: ничего.

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

async function example() {

    const server = Hapi.server({ port: 80 });

    server.ext({
        type: 'onRequest',
        method: function (request, h) {

            // Change all requests to '/test'

            request.setUrl('/test');
            return h.continue;
        }
    });

    server.route({ method: 'GET', path: '/test', handler: () => 'ok' });
    await server.start();

    // All requests will get routed to '/test'
}

server.ext(event, [method, [options]])

Регистрирует одно событие расширения с использованием тех же свойств, что и в server.ext(events), но передаваемых в качестве аргументов.

Свойство method может быть опущено (если options отсутствует) или передано null, что заставит функцию вернуть промис. Промис разрешается с объектом request при первом вызове точки расширения. Это используется в основном для написания тестов без необходимости писать пользовательские обработчики только для обработки одного события.

Значение возврата: промис, если method опущено, в противном случае undefined.

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

async function example() {

    const server = Hapi.server({ port: 80 });

    server.ext('onRequest', function (request, h) {

        // Change all requests to '/test'

        request.setUrl('/test');
        return h.continue;
    });

    server.route({ method: 'GET', path: '/test', handler: () => 'ok' });
    await server.start();

    // All requests will get routed to '/test'
}

await server.initialize()

Инициализирует сервер (запускает кэши, завершает регистрацию плагинов), но не начинает прослушивание на порту соединения.

Значение возврата: ничего.

Обратите внимание, что если метод завершается с ошибкой и генерирует ошибку, сервер считается в неопределённом состоянии и должен быть остановлен. В большинстве случаев полное восстановление невозможно, так как различные плагины, кэши и другие слушатели событий могут быть сбиты с толку многократными попытками запуска сервера или делать предположения о стабильном состоянии среды. Рекомендуется прервать процесс, если сервер не может запуститься должным образом. Если необходимо попытаться продолжить после ошибки, сначала вызовите server.stop() для сброса состояния сервера.

const Hapi = require('@hapi/hapi');
const Hoek = require('@hapi/hoek');

async function example() {

    const server = Hapi.server({ port: 80 });
    await server.initialize();
}

await server.inject(options)

Вводит запрос на сервер, моделируя входящий HTTP-запрос без реального подключения сокета. Ввод полезен для целей тестирования, а также для вызова логики маршрутизации внутри без избыточности и ограничений стека сети.

Метод использует модуль shot для выполнения ввода с некоторыми дополнительными параметрами и свойствами ответа:

• options - может быть присвоен строка с запрошенным URI или объект со следующими полями:

  • method - (необязательно) HTTP-метод запроса (например, 'POST'). По умолчанию 'GET'.

  • url - (обязательно) URL запроса. Если URI включает авторизацию (например, 'example.com:8080'), она используется для автоматической установки заголовка HTTP 'Host', если он не был указан в headers.

  • authority - (необязательно) строка, определяющая значение заголовка HTTP 'Host'. Используется только в том случае, если 'Host' не указан в headers и url не содержит компонента авторизации. Значение по умолчанию определяется по информации сервера во время выполнения.

  • headers - (необязательно) объект с необязательными заголовками запроса, где каждый ключ - имя заголовка, а значение - содержимое заголовка. По умолчанию дополнений к стандартным заголовкам shot нет.

  • payload - (необязательно) строка, буфер или объект, содержащий содержимое запроса. В случае объекта он будет преобразован в строку. По умолчанию содержимое отсутствует. Обратите внимание, что обработка содержимого по умолчанию установлена в 'application/json', если заголовок 'Content-Type' не предоставлен.

  • auth - (необязательно) объект, содержащий обработанные учетные данные аутентификации, где:

    • strategy - (обязательно) имя стратегии аутентификации, соответствующее предоставленным учетным данным.

    • credentials - (обязательно) объект учетных данных, содержащий информацию об аутентификации. credentials используются для обхода стандартных стратегий аутентификации и проверяются напрямую, как если бы они были получены через схему аутентификации.

    • artifacts - (необязательно) объект артефактов, содержащий информацию об артефактах аутентификации. artifacts используются для обхода стандартных стратегий аутентификации и проверяются напрямую, как если бы они были получены через схему аутентификации. По умолчанию артефакты отсутствуют.

    • payload - (необязательно) отключает аутентификацию содержимого при установке в false. Необходимо только тогда, когда стратегия аутентификации требует аутентификации содержимого. По умолчанию true.

  • app - (необязательно) задаёт начальное значение request.app, по умолчанию {}.

  • plugins - (необязательно) задаёт начальное значение request.plugins, по умолчанию {}.

  • allowInternals - (необязательно) позволяет доступ к маршрутам с options.isInternal установленным в true. По умолчанию false.

  • remoteAddress - (необязательно) устанавливает удалённый адрес для входящего соединения.

  • simulate - (необязательно) объект с параметрами, используемыми для моделирования условий потока клиентских запросов для тестирования:

    • error - если true, генерирует событие 'error' после передачи содержимого (если таковое есть). По умолчанию false.

    • close - если true, генерирует событие 'close' после передачи содержимого (если таковое есть). По умолчанию false.

    • end - если false, не завершает поток. По умолчанию true.

    • split - указывает, будет ли содержимое запроса разбиваться на части. По умолчанию undefined, т.е. содержимое не разбивается на части.

  • validate - (необязательно) если false, options вводы не валидируются. Это рекомендуется для использования inject() во время выполнения, чтобы сделать его быстрее, так как проверка ввода может быть проверена отдельно.

Значение возврата: объект ответа со следующими свойствами:

• statusCode - код HTTP-статуса.

• headers - объект, содержащий установленные заголовки.

• payload - строка содержимого ответа.

• rawPayload - буфер исходного содержимого ответа.

• raw - объект с объектами запроса и ответа ввода:

  • req - симулированный объект запроса node.
  • res - симулированный объект ответа node.

• result - исходный ответ обработчика (например, когда это не поток или представление) перед сериализацией для передачи. Если недоступен, значение устанавливается в payload. Полезно для проверки и повторного использования возвращаемых внутренних объектов (вместо анализа строки ответа).

• request - объект запроса.

Выбрасывает ошибку Boom, если обработка запроса завершается с ошибкой. Частичный объект ответа доступен в свойстве data.

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

async function example() {

    const server = Hapi.server({ port: 80 });
    server.route({ method: 'GET', path: '/', handler: () => 'Success!' });

    const res = await server.inject('/');
    console.log(res.result);                // 'Success!'
}

server.log(tags, [data, [timestamp]])

Регистрирует события сервера, которые нельзя связать с конкретным запросом. При вызове сервер генерирует событие 'log', которое может использоваться другими слушателями или плагинами

• tags - (обязательно) строка или массив строк (например, ['error', 'database', 'read']) для идентификации события. Теги используются вместо уровней регистрации и предоставляют гораздо более выразительный механизм для описания и фильтрации событий. Любые логи, генерируемые сервером внутри, включают тег 'hapi' вместе со специфической для события информацией.

• data - (необязательно) строка сообщения или объект с данными приложения, которые регистрируются. Если data функция, её сигнатура function(), и она вызывается один раз для генерации (значения возврата) фактических данных, передаваемых слушателям. Если нет слушателей, соответствующих событию, функция data не вызывается.

• timestamp - (необязательно) временная метка в миллисекундах. По умолчанию Date.now() (текущее время).

Значение возврата: ничего.

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

server.events.on('log', (event, tags) => {

    if (tags.error) {
        console.log(event);
    }
});

server.log(['test', 'error'], 'Test event');

server.lookup(id)

Ищет конфигурацию маршрута, где:

• id - идентификатор маршрута .

Значение возврата: информация о маршруте в запросе, если найдена, в противном случае null.

const Hapi = require('@hapi/hapi');
const server = Hapi.server();
server.route({
    method: 'GET',
    path: '/',
    options: {
        id: 'root',
        handler: () => 'ok'
    }
});

const route = server.lookup('root');

server.match(method, path, [host])

Ищет конфигурацию маршрута, где:

• method - метод HTTP (например, 'GET', 'POST').
• path - запрашиваемый путь (должен начинаться с '/').
• host - (необязательно) имя хоста (для сопоставления с маршрутами с vhost).

Возвращаемое значение: информация о маршруте, если найден, в противном случае null.

const Hapi = require('@hapi/hapi');
const server = Hapi.server();
server.route({
    method: 'GET',
    path: '/',
    options: {
        id: 'root',
        handler: () => 'ok'
    }
});

const route = server.match('get', '/');

server.method(name, method, [options])

Регистрирует метод сервера, где:

• name - уникальное имя метода, используемое для вызова метода через server.methods[name].

• method - функция метода со структурой async function(...args, [flags]), где:

  • ...args - аргументы функции метода (может быть любое количество аргументов или ни одного).
  • flags - при включенном кэшировании, объект, используемый для установки необязательных флагов результата метода. Этот параметр предоставляется автоматически и может быть доступен/изменён только внутри функции метода. Его нельзя передавать в качестве аргумента.
    • ttl - 0 если результат действителен, но не может быть кэширован. По умолчанию используется политика кэширования.

• options - (необязательно) объект конфигурации:

  • bind - объект контекста, передаваемый обратно функции метода (через this) при вызове. По умолчанию используется активный контекст (устанавливается через server.bind() при регистрации метода). Игнорируется, если метод является стрелочной функцией.

  • cache - та же конфигурация кэширования, что и в server.cache(). Опция generateTimeout обязательна, и опция generateFunc запрещена.

  • generateKey - функция, используемая для генерации уникального ключа (для кэширования) из аргументов, переданных в функцию метода (аргумент flags не передаётся как вход). Сервер автоматически сгенерирует уникальный ключ, если все аргументы функции являются типов 'string', 'number', или 'boolean'. Однако, если метод использует другие типы аргументов, необходимо предоставить функцию генерации ключа, которая принимает те же аргументы, что и функция, и возвращает уникальную строку (или null если ключ сгенерировать нельзя).

Возвращаемое значение: ничего.

Имена методов могут быть вложенными (например, utils.users.get), что автоматически создаст полный путь в server.methods (например, доступ к которому осуществляется через server.methods.utils.users.get).

При конфигурации с включенным кэшированием server.methods[name].cache назначается объект со следующими свойствами и методами: - await drop(...args) - функция, которая может быть использована для очистки кэша для данного ключа. - stats - объект со статистикой кэша, см. catbox для документации по статистике.

Пример с простыми аргументами:

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

async function example() {

    const server = Hapi.server({ port: 80 });

    const add = (a, b) => (a + b);
    server.method('sum', add, { cache: { expiresIn: 2000, generateTimeout: 100 } });

    console.log(await server.methods.sum(4, 5));          // 9
}

Пример с аргументом-объектом:

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

async function example() {

    const server = Hapi.server({ port: 80 });

    const addArray = function (array) {

        let sum = 0;
        array.forEach((item) => {

            sum += item;
        });

        return sum;
    };

    const options = {
        cache: { expiresIn: 2000, generateTimeout: 100 },
        generateKey: (array) => array.join(',')
    };

    server.method('sumObj', addArray, options);

    console.log(await server.methods.sumObj([5, 6]));     // 11
}

server.method(methods)

Регистрирует функцию метода сервера, как описано в server.method(), используя объект конфигурации, где:

• methods - объект или массив объектов, где каждый содержит:

  • name - имя метода.
  • method - функция метода.
  • options - (необязательно) настройки.

Возвращаемое значение: ничего.

const add = function (a, b) {

    return a + b;
};

server.method({
    name: 'sum',
    method: add,
    options: {
        cache: {
            expiresIn: 2000,
            generateTimeout: 100
        }
    }
});

server.path(relativeTo)

Устанавливает префикс пути, используемый для поиска статических ресурсов (файлов и шаблонов представления) при использовании относительных путей, где:

• relativeTo - префикс пути, добавляемый к любому относительному пути к файлу, начинающемуся с '.'.

Возвращаемое значение: ничего.

Обратите внимание, что установка пути в плагине применяется только к ресурсам, к которым обращаются методы плагина. Если путь не задан, используется значение по умолчанию сервера конфигурация маршрутов files.relativeTo настроек. Путь применяется только к маршрутам, добавленным после его установки.

exports.plugin = {
    name: 'example',
    register: function (server, options) {

        // Assuming the Inert plugin was registered previously

        server.path(__dirname + '../static');
        server.route({ path: '/file', method: 'GET', handler: { file: './test.html' } });
    }
};

await server.register(plugins, [options])

Регистрирует плагин, где:

• plugins - один или массив:

  • объект плагина.

  • объект со следующим:

    • plugin - объект плагина.
    • options - (необязательно) параметры, передаваемые плагину во время регистрации.
    • once, routes - (необязательно) параметры регистрации, специфичные для плагина, как определено ниже.

• options - (необязательно) параметры регистрации (отличаются от параметров, переданных функции регистрации):

  • once - если true, последующие регистрации того же плагина пропускаются без ошибки. Не может быть использовано с опциями плагина. По умолчанию false. Если не установлено значение true, при повторной регистрации плагина на сервере будет выброшено исключение.

  • routes - модификаторы, применяемые к каждому маршруту, добавленному плагином:

    • prefix - строка, добавленная в качестве префикса к любому пути маршрута (должна начинаться с '/'). Если плагин регистрирует дочерний плагин, prefix передаётся дочернему плагину или добавляется перед префиксом, специфичным для дочернего плагина.
    • vhost - строка виртуального хоста (или массив строк), применяемая к каждому маршруту. Внешний vhost переопределяет все вложенные настройки.

Возвращаемое значение: ссылка на server.

async function example() {

    await server.register({ plugin: require('plugin_name'), options: { message: 'hello' } });
}

server.route(route)

Добавляет маршрут, где:

• route - объект конфигурации маршрута или массив объектов конфигурации, где каждый объект содержит:

  • path - (обязательно) абсолютный путь, используемый для сопоставления входящих запросов (должен начинаться с '/'). Входящие запросы сравниваются с настроенными путями на основе конфигурации сервера router. Путь может включать именованные параметры, заключенные в {}, которые будут сопоставлены с литеральными значениями в запросе, как описано в Параметрах пути.

  • method - (обязательно) метод HTTP. Обычно один из 'GET', 'POST', 'PUT', 'PATCH', 'DELETE' или 'OPTIONS'. Разрешены все методы HTTP, кроме 'HEAD'. Используйте '*' для сопоставления с любым методом HTTP (только когда точное совпадение не найдено, и любое совпадение с конкретным методом будет иметь более высокий приоритет по сравнению с сопоставлением по шаблону). Может быть назначен массив методов, что имеет тот же результат, что и добавление одного и того же маршрута с разными методами вручную.

  • vhost - (необязательно) строка домена или массив строк домена для ограничения маршрута только запросами с соответствующим заголовком хоста. Сопоставление выполняется только с частью имени хоста заголовка (исключая порт). По умолчанию все хосты.

  • handler - (обязательно, если handler не задано) функция обработчика маршрута, вызываемая для генерации ответа после успешной проверки подлинности и валидации.

  • options - дополнительные параметры маршрута. Значение options может быть объектом или функцией, возвращающей объект с сигнатурой function(server), где server — сервер, к которому добавляется маршрут, и this привязана к текущему области параметру bind.

  • rules - объект пользовательских правил маршрута. Объект передаётся каждому процессору правил, зарегистрированному с помощью server.rules(). Не может быть использовано, если route.options.rules определён.

Возвращаемое значение: ничего.

Обратите внимание, что объект options глубоко клонируется (за исключением bind, который копируется поверхностно) и не может содержать никаких значений, небезопасных для глубокого копирования.

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

// Handler in top level

server.route({ method: 'GET', path: '/status', handler: () => 'ok' });

// Handler in config

const user = {
    cache: { expiresIn: 5000 },
    handler: function (request, h) {

        return { name: 'John' };
    }
};

server.route({ method: 'GET', path: '/user', options: user });

// An array of routes

server.route([
    { method: 'GET', path: '/1', handler: function (request, h) { return 'ok'; } },
    { method: 'GET', path: '/2', handler: function (request, h) { return 'ok'; } }
]);

Параметры пути

Параметризованные пути обрабатываются путём сопоставления именованных параметров с содержимым пути входящего запроса в этом сегменте пути. Например, '/book/{id}/cover' будет соответствовать '/book/123/cover', и request.params.id будет установлено на значение '123'. Каждый сегмент пути (всё между открывающим '/' и закрывающим '/' сегментом, за исключением конца пути) может содержать только один именованный параметр. Параметр может охватывать весь сегмент ('/{param}') или часть сегмента (%%%CODE_BLOCK_986%%). Имя параметра может содержать только буквы, цифры и символы нижнего подчёркивания, например, '/{file-name}' недопустимо, а '/{file_name}' — допустимо.

Необязательный суффикс '?' после имени параметра указывает на необязательный параметр (разрешено только если параметр находится в конце пути или охватывает только часть сегмента, как в '/a{param?}/b'). Например, маршрут '/book/{id?}' соответствует '/book/', а значение request.params.id установлено на пустую строку ''.

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
});

В дополнение к необязательному суффиксу ?, имя параметра также может указывать количество совпадающих сегментов, используя суффикс *, за которым следует число, большее 1. Если число ожидаемых частей может быть любым, то используйте * без числа (сопоставление с любым количеством сегментов может быть использовано только в последнем сегменте пути).

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

const getPerson = function (request, h) {

    const nameParts = request.params.name.split('/');
    return { first: nameParts[0], last: nameParts[1] };
};

server.route({
    path: '/person/{name*2}',   // Matches '/person/john/doe'
    method: 'GET',
    handler: getPerson
});

Порядок сопоставления путей

Маршрутизатор итерируется по таблице маршрутизации при каждом входящем запросе и выполняет первый (и только первый) соответствующий маршрут. Сопоставление маршрутов выполняется на основе сочетания пути запроса и HTTP-глагола (например, 'GET', 'POST'). Запрос исключается из логики маршрутизации. Запросы сопоставляются в детерминированном порядке, где порядок добавления маршрутов не имеет значения.

Маршруты сопоставляются в зависимости от специфичности маршрута, которая оценивается в каждом сегменте входящего пути запроса. Каждый путь запроса разбивается на сегменты (части, разделённые '/'). Сегменты сравниваются с таблицей маршрутизации один за другим и сопоставляются с самым специфичным путём до тех пор, пока не будет найдено совпадение. Если совпадение не найдено, пробуется следующее совпадение.

При сопоставлении маршрутов литералы строк (без параметров пути) имеют наивысший приоритет, за которыми следуют смешанные параметры ('/a{p}b'), параметры ('/{p}') и затем шаблонные (/{p*}).

Обратите внимание, что смешанные параметры медленнее сравниваются, так как они не могут быть хешированы и требуют итерации по массиву всех регулярных выражений, представляющих различные смешанные параметры в каждом узле таблицы маршрутизации.

Маршрут по умолчанию

Если приложению нужно переопределить стандартный ответ об ошибке «Не найдено» (404), оно может добавить маршрут по умолчанию для определенного метода или всех методов. Только один такой маршрут может быть определён.

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

const handler = function (request, h) {

    return h.response('The page was not found').code(404);
};

server.route({ method: '*', path: '/{p*}', handler });

server.rules(processor, [options])

Определяет обработчик правил маршрутизации для преобразования объекта правил маршрутизации в конфигурацию маршрута, где:

• processor - функция с сигнатурой function(rules, info), где:

  • rules - пользовательский объект, определённый в вашей конфигурации маршрутов для использования его значений.
  • info - объект со следующими свойствами:
    • method - метод маршрута.
    • path - путь маршрута.
    • vhost - виртуальный хост маршрута (если он определён).
  • возвращает объект конфигурации маршрута.

• options - необязательные настройки:

  • validate - валидация объекта правил:
    • schema - схема joi.
    • options - необязательные параметры валидации joi. По умолчанию %%%CODE_BLOCK_1017%%.

Обратите внимание, что корневой сервер и каждый экземпляр сервера плагина могут зарегистрировать только один обработчик правил. Если маршрут добавляется после настройки правил, он не будет включать конфигурацию правил. Маршруты, добавленные плагинами, применяют правила к правилам каждого родительского домена от корня до домена маршрута. Это означает, что обработчик, определённый плагином, переопределяет конфигурацию, сгенерированную обработчиком корня, если они перекрываются. Аналогично, собственная конфигурация маршрута переопределяет конфигурацию, созданную обработчиками правил.

const validateSchema = {
    auth: Joi.string(),
    myCustomPre: Joi.array().min(2).items(Joi.string()),
    payload: Joi.object()
};

const myPreHelper = (name) => {

    return {
        method: (request, h) => {

            return `hello ${name || 'world'}!`;
        },
        assign: 'myPreHelper'
    };
};

const processor = (rules, info) => {

    if (!rules) {
        return null;
    }

    const options = {};

    if (rules.auth) {
        options.auth = {
            strategy: rules.auth,
            validate: {
                entity: 'user'
            }
        };
    }

    if (rules.myCustomPre) {
        options.pre = [
            myPreHelper(...rules.myCustomPre)
        ];
    }

    if (rules.payload) {
        options.validate = { payload: Joi.object(rules.payload) };
    }

    return options;
};

server.rules(processor, {
    validate: { schema: validateSchema }
});

server.route({
    method: 'GET',
    path: '/',
    rules: {
        auth: 'jwt',
        myCustomPre: ['arg1', 'arg2'],
        payload: { a: Joi.boolean(), b: Joi.string() }
    },
    options: {
        id: 'my-route'
    }
});

Запуск сервера

Запускает сервер, прослушивая входящие запросы на указанном порту (если подключение не было настроено с autoListen установленным в false).

Значение возврата: ничего.

Обратите внимание, что если метод завершается ошибкой и выбрасывает исключение, сервер считается в неопределённом состоянии и должен быть остановлен. В большинстве случаев полное восстановление невозможно, поскольку различные плагины, кэши и другие обработчики событий будут сбиты с толку многократными попытками запуска сервера или сделают предположения о здоровом состоянии среды. Рекомендуется прервать процесс, если сервер не может запуститься должным образом. Если вы должны попытаться возобновить работу после ошибки, сначала вызовите server.stop() для сброса состояния сервера.

Если запущенный сервер запускается снова, второй вызов server.start() игнорируется. События не будут генерироваться, и никакие расширения не будут вызываться.

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

async function example() {

    const server = Hapi.server({ port: 80 });
    await server.start();
    console.log('Server started at: ' + server.info.uri);
}

Настройка состояния сервера

Управление состоянием HTTP использует файлы cookie клиента для сохранения состояния между несколькими запросами. Регистрирует определения файлов cookie, где:

• name - строка имени файла cookie.

• options - необязательные параметры файлов cookie:

  • ttl - время жизни в миллисекундах. По умолчанию null (время жизни сессии — файлы cookie удаляются при закрытии браузера).

  • isSecure - устанавливает флаг «Secure». По умолчанию true.

  • isHttpOnly - устанавливает флаг «HttpOnly». По умолчанию true.

  • isSameSite - устанавливает флаг 'SameSite'. Значение должно быть одним из:

    • false - нет флага.
    • 'Strict' - устанавливает значение в 'Strict' (это значение по умолчанию).
    • 'Lax' - устанавливает значение в 'Lax'.
    • 'None' - устанавливает значение в 'None'.

  • path - область действия пути. По умолчанию null (без пути).

  • domain - область действия домена. По умолчанию null (без домена).

  • autoValue - если присутствует и файл cookie не получен от клиента или не установлен обработчиком маршрута, файл cookie автоматически добавляется в ответ со значениями. Значение может быть функцией с сигнатурой async function(request), где:

    • request - объект запроса.

  • encoding - кодирование выполняется над предоставленным значением перед сериализацией. Варианты:

    • 'none' - без кодирования. В этом случае значение файла cookie должно быть строкой. Это значение по умолчанию.
    • 'base64' - строковое значение закодировано с помощью Base64.
    • 'base64json' - значение объекта JSON-строкируется, а затем кодируется с помощью Base64.
    • 'form' - значение объекта закодировано с помощью метода x-www-form-urlencoded.
    • 'iron' - шифрует и подписывает значение с помощью iron.

  • sign - объект, используемый для вычисления HMAC для проверки целостности файлов cookie. Это не обеспечивает конфиденциальность, а только средство проверки того, что значение файла cookie было сгенерировано сервером. Избыточно при использовании кодирования 'iron'. Варианты:

    • integrity - параметры алгоритма. По умолчанию require('iron').defaults.integrity.
    • password - пароль, используемый для генерации ключа HMAC (должен быть длиной не менее 32 символов).

  • password - пароль, используемый для кодирования 'iron' (должен быть длиной не менее 32 символов).

  • iron - параметры кодирования 'iron'. По умолчанию require('iron').defaults.

  • ignoreErrors - если true, ошибки игнорируются и обрабатываются как отсутствующие файлы cookie.

  • clearInvalid - если true, автоматически указывает клиенту на удаление некорректных файлов cookie. По умолчанию false.

  • strictHeader - если false, разрешает любое значение файла cookie, включая значения, нарушающие RFC 6265. По умолчанию true.

  • passThrough - используется плагинами прокси (например, h2o2).

  • contextualize - функция с сигнатурой async function(definition, request), используемая для переопределения параметров файлов cookie, специфичных для запроса, где:

    • definition - копия options для форматирования файла cookie, которую функция может изменить для настройки заголовка файла cookie запроса. Обратите внимание, что изменение свойства definition.contextualize будет проигнорировано.
    • request - текущий объект запроса.

Значение возврата: ничего.

Значения по умолчанию для состояния можно изменить с помощью параметра конфигурации server.options.state.

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

// Set cookie definition

server.state('session', {
    ttl: 24 * 60 * 60 * 1000,     // One day
    isSecure: true,
    path: '/',
    encoding: 'base64json'
});

// Set state in route handler

const handler = function (request, h) {

    let session = request.state.session;
    if (!session) {
        session = { user: 'joe' };
    }

    session.last = Date.now();

    return h.response('Success').state('session', session);
};

Зарегистрированные файлы cookie автоматически анализируются при получении. Правила анализа зависят от конфигурации маршрута state.parse. Если анализ входящего зарегистрированного файла cookie завершается ошибкой, он не включается в request.state, независимо от параметра state.failAction. Когда state.failAction установлен на 'log', а значение некорректного файла cookie получено, сервер выпустит событие 'request'. Чтобы перехватить эти ошибки, подпишитесь на событие 'request' на канале 'internal' и отфильтруйте по тегам 'error' и 'state':

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

server.events.on({ name: 'request', channels: 'internal' }, (request, event, tags) => {

    if (tags.error && tags.state) {
        console.error(event);
    }
});

server.states.add(name, [options])

Доступ: только для чтения.

То же самое, что и вызов server.state().

Форматирование файлов cookie

Форматирует заголовок HTTP 'Set-Cookie' на основе server.options.state, где:

• cookies - один объект или массив объектов, каждый из которых содержит:
  • name - имя файла cookie.
  • value - значение файла cookie.
  • options - конфигурация файла cookie для переопределения настроек сервера.

Значение возврата: строка заголовка.

Обратите внимание, что эта утилита использует конфигурацию сервера, но не изменяет состояние сервера. Она предназначена для ручного форматирования файлов cookie (например, при ручном задании заголовков).

Анализ заголовка

Анализирует заголовок HTTP 'Cookies' на основе server.options.state, где:

• header - заголовок HTTP.

Значение возврата: объект, где каждый ключ — имя файла cookie, а значение — проанализированный файл cookie.

Обратите внимание, что эта утилита использует конфигурацию сервера, но не изменяет состояние сервера. Она предназначена для ручного анализа файлов cookie (например, при отключении анализа сервером).

Остановка сервера

Останавливает прослушиватель сервера, отказываясь принимать новые подключения или запросы (существующие подключения будут продолжены до закрытия или истечения времени ожидания), где:

• options - (необязательно) объект с:

  • timeout - устанавливает время ожидания в миллисекундах до принудительного завершения любых открытых подключений, появившихся до остановки сервера на приём новых подключений. Время ожидания применяется только к ожиданию закрытия существующих подключений, а не к любым расширениям сервера 'onPreStop' или 'onPostStop', которые могут задерживать или блокировать операцию остановки неопределённо. Игнорируется, если server.options.operations.cleanStop — false. Обратите внимание, что если сервер настроен как контроллер группы группы, время ожидания относится к каждому контролируемому серверу и самому контролирующему серверу. По умолчанию 5000 (5 секунд).

Значение возврата: ничего.

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

async function example() {

    const server = Hapi.server({ port: 80 });
    await server.start();
    await server.stop({ timeout: 60 * 1000 });
    console.log('Server stopped');
}

Таблица маршрутизации

Возвращает копию таблицы маршрутизации, где:

• host - (необязательно) хост для фильтрации маршрутов, соответствующих определённому виртуальному хосту. По умолчанию все виртуальные хосты.

Значение возврата: массив маршрутов, где каждый маршрут содержит:

• settings - конфигурация маршрута с применёнными значениями по умолчанию.
• method - метод HTTP в нижнем регистре.
• path - путь маршрута.

const Hapi = require('@hapi/hapi');
const server = Hapi.server({ port: 80 });
server.route({ method: 'GET', path: '/example', handler: () => 'ok' });

const table = server.table();

server.validator(validator)

Регистрирует модуль валидации сервера, используемый для компиляции исходных правил валидации в схемы валидации для всех маршрутов, где:

• validator — модуль валидации (например, joi).

Возвращаемое значение: ничего.

Примечание: валидатор используется только тогда, когда правила валидации не являются предварительно скомпилированными схемами. Когда правило валидации является функцией или объектом схемы, правило используется как есть, и валидатор не используется. При установке валидатора внутри плагина, валидатор применяется только к маршрутам, настроенным этим плагином, и плагинам, зарегистрированным им.

const Hapi = require('@hapi/hapi');
const Joi = require('joi');

async function example() {

    const server = Hapi.server({ port: 80 });
    server.validator(Joi);
}

Параметры маршрута

Каждый маршрут можно настроить для изменения стандартного поведения жизненного цикла запроса.

route.options.app

Состояние конфигурации маршрута, специфичное для приложения. Не должно использоваться плагинами, которые должны использовать options.plugins[name] вместо этого.

route.options.auth

Конфигурация аутентификации маршрута. Значение может быть:

• false для отключения аутентификации, если установлена стратегия по умолчанию.

• строка с именем стратегии аутентификации, зарегистрированной с помощью server.auth.strategy(). Стратегия будет установлена в режим 'required'.

• объект конфигурации аутентификации.

route.options.auth.access

Значение по умолчанию: ничего.

Объект или массив объектов, определяющих правила доступа к маршруту. Каждое правило оценивается относительно входящего запроса, и доступ предоставляется, если хотя бы одно из правил соответствует. Каждый объект правила должен включать как минимум одно из scope или entity.

route.options.auth.access.scope

Значение по умолчанию: false (нет требований к области).

Требуемая область приложения для доступа к маршруту. Значение может быть строкой области или массивом строк областей. При аутентификации объект учетных данных scope должен содержать как минимум одну из определенных для доступа к маршруту областей.

Если строка области начинается с символа +, эта область обязательна. Если строка области начинается с символа !, эта область запрещена. Например, область ['!a', '+b', 'c', 'd'] означает, что учетные данные входящего запроса scope не должны содержать 'a', должны содержать 'b' и должны содержать одну из 'c' или 'd'.

Вы также можете получить доступ к свойствам объекта запроса (query, params, payload, и credentials) для заполнения динамической области, используя символы '{' и '}' вокруг имени свойства, например 'user-{params.id}'.

route.options.auth.access.entity

Значение по умолчанию: 'any'.

Требуемый тип аутентифицированного сущности. Если установлено, должно соответствовать значению entity аутентифицированных учетных данных запроса. Доступные значения:

• 'any' — аутентификация может быть от имени пользователя или приложения.
• 'user' — аутентификация должна быть от имени пользователя, который идентифицируется по наличию атрибута 'user' в объекте credentials, возвращенном стратегией аутентификации.
• 'app' — аутентификация должна быть от имени приложения, которое идентифицируется по отсутствию атрибута user в объекте credentials, возвращенном стратегией аутентификации.

route.options.auth.mode

Значение по умолчанию: 'required'.

Режим аутентификации. Доступные значения:

• 'required' — аутентификация обязательна.
• 'optional' — аутентификация необязательна — запрос должен содержать действительные учетные данные или вообще не содержать учетных данных.
• 'try' — аналогично 'optional', любые учетные данные запроса пытаются пройти аутентификацию, но если учетные данные недействительны, запрос продолжает выполняться независимо от ошибки аутентификации.

route.options.auth.payload

Значение по умолчанию: false, если схема не требует аутентификации содержимого.

Если установлено, содержимое входящего запроса аутентифицируется после обработки. Требуется стратегия с поддержкой аутентификации содержимого (например, Hawk). Не может быть установлено в значение, отличное от 'required', если схема устанавливает режим аутентификации options.payload в true.

Доступные значения:

• false — аутентификация содержимого отсутствует.
• 'required' — аутентификация содержимого требуется.
• 'optional' — аутентификация содержимого выполняется только когда клиент предоставляет информацию об аутентификации содержимого (например, атрибут hash в Hawk).

route.options.auth.strategies

Значение по умолчанию: стратегия по умолчанию, установленная с помощью server.auth.default().

Массив имён стратегий, в порядке, в котором они должны быть проверены. Не может использоваться вместе с strategy.

route.options.auth.strategy

Значение по умолчанию: стратегия по умолчанию, установленная с помощью server.auth.default().

Имя стратегии. Не может использоваться вместе с strategies.

route.options.bind

Значение по умолчанию: null.

Объект, возвращаемый предоставленной handler (через this) при вызове. Игнорируется, если метод является стрелочной функцией.

route.options.cache

Значение по умолчанию: { privacy: 'default', statuses: [200], otherwise: 'no-cache' }.

Если метод маршрута 'GET', маршрут можно настроить для включения директив кэширования HTTP в ответе. Кэширование можно настроить с помощью объекта со следующими параметрами:

• privacy — определяет флаг приватности, включенный в кэширование на стороне клиента с помощью заголовка 'Cache-Control'. Значения:

  • 'default' — нет флага приватности.
  • 'public' — отметить ответ как подходящий для публичного кэширования.
  • 'private' — отметить ответ как подходящий только для приватного кэширования.

• expiresIn — относительное время истечения срока действия, выраженное в миллисекундах с момента сохранения элемента в кэше. Не может использоваться вместе с expiresAt.

• expiresAt — время суток в формате 'HH:MM' 24-часового формата, к которому все записи кэша для маршрута истекают. Не может использоваться вместе с expiresIn.

• statuses — массив номеров кодов HTTP-статусов (например, 200), которые разрешается включать в действительную директиву кэширования.

• otherwise — строка со значением заголовка 'Cache-Control' при отключенном кэшировании.

Заголовок по умолчанию Cache-Control: no-cache может быть отключен, установив cache в false.

route.options.compression

Объект, где каждый ключ — имя кодировки содержимого, а каждое значение — объект с желаемыми настройками кодировщика. Обратите внимание, что настройки декодера устанавливаются в compression.

route.options.cors

Значение по умолчанию: false (нет заголовков CORS).

Протокол Cross-Origin Resource Sharing позволяет браузерам выполнять кросс-доменные вызовы API. CORS требуется веб-приложениям, работающим внутри браузера, которые загружаются с другого домена, чем сервер API. Чтобы включить, установите cors в true, или в объект со следующими параметрами:

• origin — массив строк разрешенных серверов источников ('Access-Control-Allow-Origin'). Массив может содержать любое сочетание полных квалифицированных источников наряду со строками источников, содержащими символ подстановки '*', или единственную строку источника '*'. Если установлено в 'ignore', любой входящий заголовок Origin игнорируется (есть или нет) и заголовок 'Access-Control-Allow-Origin' устанавливается в '*'. По умолчанию — любой источник ['*'].

• maxAge — количество секунд, в течение которых браузер должен кэшировать ответ CORS ('Access-Control-Max-Age'). Чем больше значение, тем дольше потребуется браузеру для проверки изменений в политике. По умолчанию 86400 (один день).

• headers — массив строк разрешенных заголовков ('Access-Control-Allow-Headers'). По умолчанию ['Accept', 'Authorization', 'Content-Type', 'If-None-Match'].

• additionalHeaders — массив дополнительных заголовков для headers. Используйте это для сохранения стандартных заголовков.

• exposedHeaders — массив строк выставляемых заголовков ('Access-Control-Expose-Headers'). По умолчанию ['WWW-Authenticate', 'Server-Authorization'].

• additionalExposedHeaders — массив дополнительных заголовков для exposedHeaders. Используйте это для сохранения стандартных заголовков.

• credentials — если true, разрешает отправку учетных данных пользователя ('Access-Control-Allow-Credentials'). По умолчанию false.

• preflightStatusCode — код состояния, используемый для ответов CORS на предварительные запросы, либо 200 или 204. По умолчанию 200.

route.options.description

Значение по умолчанию: ничего.

Описание маршрута, используемое для генерации документации (строка).

Этот параметр недоступен при установке параметров сервера маршрутов с помощью server.options.routes.

route.options.ext

Значение по умолчанию: ничего.

Точки расширения запроса уровня маршрута, установив параметр в объект с ключом для каждой из желаемых точек расширения ('onRequest' не разрешается), и значение такое же, как аргумент server.ext(events) event.

route.options.files

Значение по умолчанию: { relativeTo: '.' }.

Определяет поведение доступа к файлам:

• relativeTo — определяет, относительно каких каталогов будут разрешаться пути.

route.options.handler

Значение по умолчанию: ничего.

Функция обработчика маршрута выполняет основную бизнес-логику маршрута и устанавливает ответ. handler может быть назначено:

• методом жизненного цикла.

• объектом с единственным свойством, используя имя типа обработчика, зарегистрированного с помощью метода server.decorate(). Соответствующее значение свойства передается как параметры зарегистрированному генератору обработчика.

const handler = function (request, h) {

    return 'success';
};

Примечание: обработчики, использующие стрелочную функцию со стилем «толстая стрелка», не могут быть привязаны к свойству bind. Вместо этого привязанный контекст доступен по адресу h.context.

route.options.id

Значение по умолчанию: none.

Необязательный уникальный идентификатор, используемый для поиска маршрута с помощью server.lookup(). Не может быть назначен маршрутам, добавленным с массивом методов.

route.options.isInternal

Значение по умолчанию: false.

Если true, доступ к маршруту нельзя получить через HTTP-прослушиватель, только через интерфейс server.inject() с параметром allowInternals установленным в true. Используется для внутренних маршрутов, которые не должны быть доступны внешнему миру.

route.options.json

Значение по умолчанию: none.

Необязательные аргументы, передаваемые в JSON.stringify(), при преобразовании объекта или ответа об ошибке в строковый полезный груз или экранировании его после строкового представления. Поддерживает следующие:

• replacer — функция или массив замены. По умолчанию без действий.

• space — количество пробелов для отступа ключей вложенных объектов. По умолчанию без отступа.

• suffix — строковый суффикс, добавляемый после преобразования в строку JSON. По умолчанию без суффикса.

• escape — вызывает Hoek.jsonEscape() после преобразования в строку JSON. По умолчанию false.

route.options.log

Значение по умолчанию: { collect: false }.

Параметры ведения журнала запросов:

• collect — если true, журналы уровня запроса (как внутренние, так и приложения) собираются и доступны через request.logs.

route.options.notes

Значение по умолчанию: none.

Примечания к маршруту, используемые для генерации документации (строка или массив строк).

Этот параметр недоступен при установке параметров маршрута сервера с помощью server.options.routes.

route.options.payload

Определяет, как обрабатывается полезная нагрузка запроса.

route.options.payload.allow

Значение по умолчанию: разрешает парсинг следующих типов MIME:

• application/json
• application/*+json
• application/octet-stream
• application/x-www-form-urlencoded
• multipart/form-data
• text/*

Строка или массив строк с разрешенными типами MIME для конечной точки. Используйте этот параметр для ограничения набора разрешенных типов MIME. Обратите внимание, что разрешение дополнительных типов MIME, не перечисленных выше, не позволит их парсить, и если parse true, запрос приведет к ответу об ошибке.

route.options.payload.compression

Значение по умолчанию: none.

Объект, где каждый ключ — имя кодирования содержимого, а каждое значение — объект с желаемыми настройками декодера. Обратите внимание, что настройки кодировщика устанавливаются в compression.

route.options.payload.defaultContentType

Значение по умолчанию: 'application/json'.

Тип содержимого по умолчанию, если заголовок 'Content-Type' запроса отсутствует.

route.options.payload.failAction

Значение по умолчанию: 'error' (возвращает ошибку Bad Request (400)).

Значение failAction, определяющее, как обрабатывать ошибки при разборе полезной нагрузки.

route.options.payload.maxBytes

Значение по умолчанию: 1048576 (1 МБ).

Ограничивает размер входящей полезной нагрузки заданным количеством байтов. Разрешение очень больших полезных нагрузок может привести к нехватке памяти на сервере.

route.options.payload.maxParts

Значение по умолчанию: 1000.

Ограничивает количество частей, разрешенных в полезной нагрузке типа multipart.

route.options.payload.multipart

Значение по умолчанию: false.

Переопределяет обработку полезной нагрузки для запросов multipart. Значение может быть одним из:

• false — отключение обработки multipart (это значение по умолчанию).

• true — включение обработки multipart с использованием значения output.

• объект со следующими обязательными параметрами:

  • output — аналогично параметру output с дополнительным параметром value:

    • annotated — оборачивает каждую часть multipart в объект со следующими ключами:

      • headers — заголовки части.
      • filename — имя файла части.
      • payload — обработанная полезная нагрузка части.

route.options.payload.output

Значение по умолчанию: 'data'.

Формат обработанной полезной нагрузки. Значение должно быть одним из:

• 'data' — входящая полезная нагрузка полностью считывается в память. Если parse true, полезная нагрузка анализируется (JSON, декодирование формы, multipart) на основе заголовка 'Content-Type'. Если parse false, возвращается сырой Buffer.

• 'stream' — входящая полезная нагрузка доступна через интерфейс Stream.Readable . Если полезная нагрузка 'multipart/form-data' и parse true, значения полей представлены как текст, а файлы — как потоки. Потоки файлов из загрузки 'multipart/form-data' также будут иметь свойство hapi, содержащее свойства filename и headers. Обратите внимание, что потоки полезной нагрузки для multipart-полезных нагрузок — это синтетический интерфейс, созданный поверх всего содержимого multipart, загруженного в память. Чтобы избежать загрузки больших multipart-полезных нагрузок в память, установите parse false и обработайте multipart-полезную нагрузку в обработчике с помощью потокового анализатора (например, pez).

• 'file' — входящая полезная нагрузка записывается во временный файл в каталоге, указанном в параметрах uploads. Если полезная нагрузка 'multipart/form-data' и parse true, значения полей представлены как текст, а файлы сохраняются на диск. Обратите внимание, что приложение несет полную ответственность за очистку файлов, созданных фреймворком. Это можно сделать, отслеживая используемые файлы (например, используя объект request.app) и прослушивая событие сервера 'response' для выполнения очистки.

route.options.payload.override

Значение по умолчанию: none.

Строка типа MIME, переопределяющая значение заголовка 'Content-Type', полученного из запроса.

route.options.payload.parse

Значение по умолчанию: true.

Определяет, обрабатывается ли входящая полезная нагрузка или представлена в сыром виде. Доступные значения:

• true — если тип содержимого запроса 'Content-Type' соответствует разрешенным типам MIME, заданным в allow (для всей полезной нагрузки и частей), полезная нагрузка преобразуется в объект, когда это возможно. Если формат неизвестен, отправляется ответ об ошибке Bad Request (400). Любая известная кодировка содержимого декодируется.

• false — сырая полезная нагрузка возвращается без изменений.

• 'gunzip' — сырая полезная нагрузка возвращается без изменений после декодирования любой известной кодировки содержимого.

route.options.payload.protoAction

Значение по умолчанию: 'error'.

Устанавливает обработку входящей полезной нагрузки, которая может содержать атаку с отравлением прототипа. Доступные значения:

• 'error' — возвращает ошибку 400 bad request, если полезная нагрузка содержит прототип.

• 'remove' — очищает полезную нагрузку, удаляя прототип.

• 'ignore' — отключает защиту и позволяет полезной нагрузке пройти как полученную. Используйте этот параметр только в том случае, если вы уверены, что такие входящие данные не могут представлять никакой угрозы для вашего приложения.

route.options.payload.timeout

Значение по умолчанию: до 10000 (10 секунд).

Таймаут приема полезной нагрузки в миллисекундах. Устанавливает максимальное время, разрешенное для клиента для передачи полезной нагрузки запроса (тела), прежде чем отказаться и ответить с ошибкой Request Timeout (408).

Установите значение false для отключения.

route.options.payload.uploads

Значение по умолчанию: os.tmpdir().

Каталог, используемый для записи загрузок файлов.

route.options.plugins

Значение по умолчанию: {}.

Настройки, специфичные для плагинов. plugins — это объект, где каждый ключ — имя плагина, а значение — настройка плагина.

route.options.pre

Значение по умолчанию: none.

Параметр pre позволяет определять методы для выполнения действий перед вызовом обработчика. Эти методы позволяют разбить логику обработчика на более мелкие, повторно используемые компоненты, которые можно совместно использовать в разных маршрутах, а также обеспечить более чистую обработку ошибок предварительных операций (например, загрузка необходимых справочных данных из базы данных).

pre назначается упорядоченный массив методов, которые вызываются последовательно в порядке. Если массив pre содержит другой массив методов как один из своих элементов, эти методы вызываются параллельно. Обратите внимание, что во время параллельного выполнения, если любой из методов завершится ошибкой, вернет ответ takeover или сигнал прерывания, другие параллельные методы продолжат выполнение, но будут проигнорированы по завершении.

pre может быть назначен смешанный массив:

• массив, содержащий элементы, перечисленные ниже, которые выполняются параллельно.

• объект с:

  • method — метод жизненного цикла.
  • assign — имя ключа, используемого для назначения ответа метода в request.pre и request.preResponses.
  • failAction — значение failAction, определяющее, что делать, когда метод предварительного обработчика вызывает ошибку. Если assign указан и настройка failAction не равна 'error', ошибка будет назначена.

• функция метода — то же самое, что и включение объекта с единственным ключом method.

Обратите внимание, что методы предобработчика ведут себя не так, как другие методы жизненного цикла, когда возвращается значение. Вместо того, чтобы возвращаемое значение становилось новым полезным нагрузом ответа, значение используется для назначения соответствующих request.pre и request.preResponses свойств. В остальных случаях обработка ошибок, ответ захвата или сигнал прерывания ведут себя так же, как и другие методы жизненного цикла.

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

const pre1 = function (request, h) {

    return 'Hello';
};

const pre2 = function (request, h) {

    return 'World';
};

const pre3 = function (request, h) {

    return request.pre.m1 + ' ' + request.pre.m2;
};

server.route({
    method: 'GET',
    path: '/',
    options: {
        pre: [
            [
                // m1 and m2 executed in parallel
                { method: pre1, assign: 'm1' },
                { method: pre2, assign: 'm2' }
            ],
            { method: pre3, assign: 'm3' },
        ],
        handler: function (request, h) {

            return request.pre.m3 + '!\n';
        }
    }
});

route.options.response

Правила обработки исходящего ответа.

route.options.response.disconnectStatusCode

Значение по умолчанию: 499.

Код состояния HTTP по умолчанию, используемый для установки ошибки ответа, когда запрос закрыт или прерван до полного передачи ответа. Значение может быть любым целым числом, большим или равным 400. Значение по умолчанию 499 основано на нестандартной ошибке nginx "CLIENT CLOSED REQUEST". Это значение используется только для ведения журнала, так как запрос уже завершен.

route.options.response.emptyStatusCode

Значение по умолчанию: 204.

Код состояния HTTP по умолчанию, когда полезная нагрузка считается пустой. Значение может быть 200 или 204. Обратите внимание, что код состояния 200 преобразуется в 204 только во время передачи ответа (код состояния ответа останется 200 на протяжении всего жизненного цикла запроса, если не задано вручную).

route.options.response.failAction

Значение по умолчанию: 'error' (возвратить ошибку Internal Server Error (500)).

Значение failAction, определяющее, что делать, когда проверка полезной нагрузки ответа завершается с ошибкой.

route.options.response.modify

Значение по умолчанию: false.

Если true, применяет изменения правил проверки к полезной нагрузке ответа.

route.options.response.options

Значение по умолчанию: none.

joi объект опций, передаваемый в функцию валидации. Полезно для установки глобальных параметров, таких как stripUnknown или abortEarly. Если пользовательская функция валидации определена с помощью schema или status, тогда options может быть произвольным объектом, который будет передан в эту функцию в качестве второго аргумента.

route.options.response.ranges

Значение по умолчанию: true.

Если false, поддержка диапазонов полезной нагрузки range отключена.

route.options.response.sample

Значение по умолчанию: 100 (все ответы).

Процент полезных нагрузок ответов, подвергнутых проверке (0 - 100). Установите значение 0 для отключения всей проверки.

route.options.response.schema

Значение по умолчанию: true (без проверки).

Правила проверки полезной нагрузки ответа по умолчанию (для всех ответов, не являющихся ошибками), выраженные как один из:

• true - любая полезная нагрузка разрешена (без проверки).

• false - полезная нагрузка не разрешена.

• объект валидации joi. options вместе с контекстом запроса ({ headers, params, query, payload, state, app, auth }) передаются в функцию проверки.

• функция проверки с сигнатурой async function(value, options), где:

  • value - ожидаемая полезная нагрузка ответа.

  • options - options вместе с контекстом запроса ({ headers, params, query, payload, state, app, auth }).

  • если функция возвращает значение и modify равно true, то значение используется как новый ответ. Если исходный ответ является ошибкой, возвращаемое значение используется для переопределения исходной ошибки output.payload. Если возникает ошибка, ошибка обрабатывается в соответствии с failAction.

route.options.response.status

Значение по умолчанию: none.

Схемы валидации для определённых кодов состояния HTTP. Ответы (исключая ошибки), не соответствующие указанным кодам состояния, проверяются с использованием по умолчанию schema.

status устанавливается в объект, где каждый ключ — 3-значный код состояния HTTP, а значение имеет такое же определение, как schema.

route.options.rules

Значение по умолчанию: none.

Пользовательский объект правил, передаваемый каждому обработчику правил, зарегистрированному в server.rules().

route.options.security

Значение по умолчанию: false (заголовки безопасности отключены).

Устанавливает общие заголовки безопасности. Чтобы включить, установите security в true или в объект со следующими параметрами:

• hsts — управляет заголовком 'Strict-Transport-Security', где:

  • true — заголовок будет установлен в max-age=15768000. Это значение по умолчанию.

  • число — параметр maxAge будет установлен в указанное значение.

  • объект со следующими полями:

    • maxAge — часть max-age заголовка, как число. Значение по умолчанию 15768000.
    • includeSubDomains — логическое значение, указывающее, нужно ли добавить флаг includeSubDomains в заголовок.
    • preload — логическое значение, указывающее, нужно ли добавить флаг 'preload' (используется для добавления доменов в предварительно загруженный список HSTS Chrome) в заголовок.

• xframe — управляет заголовком 'X-Frame-Options', где:

  • true — заголовок будет установлен в 'DENY'. Это значение по умолчанию.

  • 'deny' — заголовки будут установлены в 'DENY'.

  • 'sameorigin' — заголовки будут установлены в 'SAMEORIGIN'.

  • объект для указания правила 'allow-from', где:

    • rule — одно из:
      • 'deny'
      • 'sameorigin'
      • 'allow-from'
    • source — когда rule равно 'allow-from', это используется для формирования остальной части заголовка, в противном случае это поле игнорируется. Если rule равно 'allow-from', но source не задано, правило будет автоматически изменено на 'sameorigin'.

• xss — управляет заголовком 'X-XSS-Protection', где:

  • 'disabled' — заголовок будет установлен в '0'. Это значение по умолчанию.
  • 'enabled' — заголовок будет установлен в '1; mode=block'.
  • false — заголовок будет опущен.

  Примечание: при включении это значение может создать уязвимости в версиях Internet Explorer ниже 8, неисправленных версиях IE8 и браузерах, использующих фильтр/аудитор XSS. Подробнее см. здесь, здесь и здесь.

• noOpen — логическое значение, управляющее заголовком 'X-Download-Options' для Internet Explorer, предотвращая выполнение загрузок в вашем контексте. По умолчанию устанавливает заголовок в 'noopen'.

• noSniff — логическое значение, управляющее заголовком 'X-Content-Type-Options'. По умолчанию устанавливает заголовок в его единственное и значение по умолчанию 'nosniff'.

• referrer — управляет заголовком 'Referrer-Policy', который имеет следующие возможные значения.

  • false — заголовок 'Referrer-Policy' не будет отправлен клиентам с ответами. Это значение по умолчанию.
  • '' — сообщает клиентам, что Referrer-Policy будет определён где-то ещё, например, в теге meta HTML.
  • 'no-referrer' — сообщает клиентам, что заголовок referer никогда не включается при выполнении запросов.
  • 'no-referrer-when-downgrade' — сообщает клиентам, что заголовок referer никогда не включается при переходе с HTTPS на HTTP.
  • 'same-origin' — сообщает клиентам, что заголовок referer включается только для текущего сайта.
  • 'origin' — аналогично 'origin', но сообщает клиентам, что заголовок referer пропускается при переходе с HTTPS на HTTP.
  • 'origin-when-cross-origin' — сообщает клиентам, что полный путь включен в заголовок referer для запросов того же сайта, а компоненты происхождения URL включены для запросов с разных сайтов.
  • 'strict-origin-when-cross-origin' — аналогично 'origin-when-cross-origin', но клиент получает инструкцию пропускать заголовок referer при переходе с HTTPS на HTTP.
  • 'unsafe-url' — сообщает клиенту всегда включать заголовок referer с полным URL.

route.options.state

Значение по умолчанию: { parse: true, failAction: 'error' }.

Управление состоянием HTTP (куки) позволяет серверу хранить информацию на стороне клиента, которая отправляется обратно на сервер с каждым запросом (как определено в RFC 6265). state поддерживает следующие параметры:

• parse — определяет, будут ли анализироваться заголовки 'Cookie' и храниться в объекте request.state.

• failAction — значение failAction, определяющее, как обрабатывать ошибки парсинга куки. По умолчанию 'error' (возвратить ошибку Bad Request (400)).

route.options.tags

Значение по умолчанию: none.

Теги маршрута, используемые для генерации документации (массив строк).

Это значение недоступно при установке параметров маршрутов сервера с помощью server.options.routes.

route.options.timeout

Значение по умолчанию: { server: false }.

Таймауты для обработки продолжительности.

route.options.timeout.server

Значение по умолчанию: false.

Тайм-аут ответа в миллисекундах. Устанавливает максимальное время, разрешённое для ответа сервера на входящий запрос перед отказом и отправкой ответа с ошибкой Service Unavailable (503).

route.options.timeout.socket

Значение по умолчанию: none (используется узел по умолчанию 2 минуты).

По умолчанию, сокеты узла автоматически отключаются после 2 минут. Используйте этот параметр, чтобы переопределить это поведение. Установите в false для отключения таймаутов сокета.

route.options.validate

Значение по умолчанию: { headers: true, params: true, query: true, payload: true, state: true, failAction: 'error' }.

Правила валидации входных данных запроса для различных компонентов запроса.

route.options.validate.errorFields

Значение по умолчанию: none.

Необязательный объект с полями ошибок, копируемыми в каждый ответ об ошибке валидации.

route.options.validate.failAction

Значение по умолчанию: 'error' (возвращает ошибку Bad Request (400)).

Значение failAction, которое определяет, как обрабатывать ошибки валидации. Если установлено значение функции, аргумент err включает тип ошибки валидации в err.output.payload.validation.source. Доступ к стандартной ошибке, которая в противном случае была бы записана в журнал или возвращена, можно получить в err.data.defaultError.

route.options.validate.headers

Значение по умолчанию: true (без валидации).

Правила валидации для входящих заголовков запроса:

• true - любые разрешенные заголовки (валидация не выполняется).

• объект валидации joi.

• функция валидации, использующая подпись async function(value, options) , где:

  • value - объект request.headers, содержащий заголовки запроса.
  • options - options.
  • если возвращается значение, значение используется в качестве нового значения request.headers, а исходное значение сохраняется в request.orig.headers. В противном случае заголовки остаются неизменными. Если возникает ошибка, ошибка обрабатывается в соответствии с failAction.

Обратите внимание, что все имена полей заголовков должны быть в нижнем регистре для соответствия нормализованным заголовкам, используемым узлом.

route.options.validate.options

Значение по умолчанию: none.

Объект параметров, передаваемый правилам joi или пользовательским методам валидации. Используется для установки глобальных параметров, таких как stripUnknown или abortEarly.

Если определена пользовательская функция валидации (см. headers, params, query, или payload выше), то options может быть произвольным объектом, который будет передан этой функции в качестве второго параметра.

Значения других входных данных (т. е. headers, query, params, payload, state, app, и auth ) добавляются в объект options в разделе валидации %%%CODE_BLOCK_1507%% (доступно в правилах как Joi.ref('$query.key')).

Обратите внимание, что валидация выполняется в порядке (т. е. заголовки, параметры, запросы и данные загрузки), и если используется преобразование типов (например, преобразование строки в число), значение входных данных, которые ещё не прошли валидацию, будет отражать необработанные, невалидированные и неизменённые значения.

Если правила валидации для headers, params, query, и payload определены как на уровне сервера routes, так и на уровне маршрута, индивидуальные настройки маршрута переопределяют настройки по умолчанию маршрутов (правила не объединяются).

route.options.validate.params

Значение по умолчанию: true (без валидации).

Правила валидации для входящих параметров пути запроса после сопоставления пути с маршрутом, извлечения параметров и сохранения их в request.params, где:

• true - любые значения параметров пути разрешены (валидация не выполняется).

• объект валидации joi.

• функция валидации, использующая подпись async function(value, options) , где:

  • value - объект request.params, содержащий параметры пути запроса.
  • options - options.
  • если возвращается значение, значение используется в качестве нового значения request.params, а исходное значение сохраняется в request.orig.params. В противном случае параметры пути остаются неизменными. Если возникает ошибка, ошибка обрабатывается в соответствии с failAction.

Обратите внимание, что отсутствие соответствия правил валидации определению параметров пути маршрута приведёт к отказу всех запросов.

route.options.validate.payload

Значение по умолчанию: true (без валидации).

Правила валидации для входящей загрузки (тела запроса), где:

• true - любая загрузка разрешена (валидация не выполняется).

• false - любая загрузка запрещена.

• объект валидации joi.

  • Обратите внимание, что пустые загрузки представлены значением null. Если предоставлена схема валидации и разрешены пустые загрузки, схема должна быть явно определена, установив правило в схему joi с разрешенными пустыми значениями (например, null).

• функция валидации, использующая подпись async function(value, options) , где:

  • value - объект request.payload, содержащий загрузку запроса.
  • options - options.
  • если возвращается значение, значение используется в качестве нового значения request.payload, а исходное значение сохраняется в request.orig.payload. В противном случае загрузка остаётся неизменной. Если возникает ошибка, ошибка обрабатывается в соответствии с failAction.

Обратите внимание, что валидация больших загрузок и их модификация приведут к дублированию памяти загрузки (так как исходная сохраняется), а также к значительным затратам на производительность при валидации больших объёмов данных.

route.options.validate.query

Значение по умолчанию: true (без валидации).

Правила валидации для входящей компоненты URI запроса (ключевое значение части URI между '?' и '#'). Запрос анализируется на отдельные пары ключ-значение, декодируется и сохраняется в request.query перед валидацией. Где:

• true - любые значения параметров запроса разрешены (валидация не выполняется).

• false - никакие значения параметров запроса не разрешены.

• объект валидации joi.

• функция валидации, использующая подпись async function(value, options) , где:

  • value - объект request.query, содержащий параметры запроса.
  • options - options.
  • если возвращается значение, значение используется в качестве нового значения request.query, а исходное значение сохраняется в request.orig.query. В противном случае параметры запроса остаются неизменными. Если возникает ошибка, ошибка обрабатывается в соответствии с failAction.