@e22m4u/js-trie-router-cors

Модуль поддержки CORS для @e22m4u/js-trie-router

Содержание

• Установка
• Использование
• Тесты
• Лицензия

Установка

npm install @e22m4u/js-trie-router-cors

Модуль поддерживает ESM и CommonJS стандарты.

ESM

import {TrieRouterCors} from '@e22m4u/js-trie-router-cors';

CommonJS

const {TrieRouterCors} = require('@e22m4u/js-trie-router-cors');

Использование

Подключение модуля к маршрутизатору выполняется через внедрение зависимости. Сервис регистрируется с передачей объекта настроек.

import {TrieRouter} from '@e22m4u/js-trie-router';
import {TrieRouterCors} from '@e22m4u/js-trie-router-cors';

// создание маршрутизатора
const router = new TrieRouter();

// подключение расширения
router.useService(TrieRouterCors, {
  origin: true, // разрешить запросы с любых источников
  maxAge: 3600, // кэширование preflight запросов на один час
});

Настройки

Модуль позволяет определить объект настроек со следующими свойствами. Каждое свойство отвечает за отдельный аспект работы модуля.

origin

Тип: boolean | string | RegExp | Function | (string | RegExp)[]
По умолчанию: false

Опция управляет проверкой источника. Возможные варианты значений представлены ниже.

• false - отключает отправку CORS заголовков (по умолчанию);
• true - разрешает все источники (отражает источник запроса);
• * - разрешает любые источники запросов (для публичного API);
• http://example.com - указывает точный адрес источника;
• /example\.com$/ регулярное выражение для проверки адреса;
• [...] массив допустимых адресов или регулярных выражений;
• (origin) => true функция для проверки адреса;

Допускается указание конкретных источников через запятую.

router.useService(TrieRouterCors, {
  origin: 'http://foo.com,http://bar.com',
});

Значения * и true разрешают доступ любым адресам. Разница заключается в формировании заголовков ответа сервера.

origin: '*'

При передаче символа звездочки сервер отправляет разрешающий заголовок со значением *. Разрешающий заголовок добавляется ко всем ответам, даже в рамках одного домена. Наличие информации об источнике во входящем запросе не проверяется. Данный режим рекомендуется для публичных API, не использующих авторизацию.

Access-Control-Allow-Origin: *

origin: true

Значение true включает режим отражения. Маршрутизатор читает адрес источника из заголовка Origin и возвращает его точное значение в ответе сервера. Дополнительно устанавливается заголовок Vary. Если входящий запрос не имеет информации об источнике (не кросс-доменный запрос), то установка CORS заголовков пропускается.

Access-Control-Allow-Origin: http://example.com
Vary: Origin

origin: '*' и credentials: true

Наличие флага передачи данных авторизации изменяет поведение символа звездочки. Спецификация запрещает совмещать данный флаг и разрешающий символ *. При таком сочетании маршрутизатор автоматически переключается в режим отражения адреса источника.

Access-Control-Allow-Origin: http://example.com
Access-Control-Allow-Credentials: true

methods

Тип: string | string[]
По умолчанию: GET, HEAD, PUT, PATCH, POST, DELETE

Опция задает разрешенные методы. Значение по умолчанию включает базовые методы протокола. Допускается передача строки или массива.

router.useService(TrieRouterCors, {
  // указание методов в виде массива
  methods: ['GET', 'POST'],
});

allowedHeaders

Тип: string | string[]
По умолчанию: undefined

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

router.useService(TrieRouterCors, {
  // указание заголовков в виде массива
  allowedHeaders: ['Content-Type', 'Authorization'],
});

exposedHeaders

Тип: string | string[]
По умолчанию: undefined

Опция определяет заголовки для чтения на стороне клиента. Значением может быть строка или массив строк.

router.useService(TrieRouterCors, {
  // заголовки доступные для чтения
  exposedHeaders: ['X-Custom-Header'],
});

credentials

Тип: boolean
По умолчанию: false

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

router.useService(TrieRouterCors, {
  // включение передачи данных авторизации
  credentials: true,
});

maxAge

Тип: number
По умолчанию: undefined

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

router.useService(TrieRouterCors, {
  // кэширование ответа на один час
  maxAge: 3600,
});

Тесты

npm run test

Лицензия

MIT