@netlify/headers-parser 7.2.0

package/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2021 Netlify <team@netlify.com>
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,3 @@
+# Netlify Headers Parser
+
+Parses headers rules from both `_headers` and `netlify.toml` and normalizes them to an array of objects.

package/lib/all.d.ts

@@ -0,0 +1,9 @@
+export declare const parseAllHeaders: ({ headersFiles, netlifyConfigPath, configHeaders, minimal, }: {
+    headersFiles?: never[] | undefined;
+    netlifyConfigPath: any;
+    configHeaders?: never[] | undefined;
+    minimal?: boolean | undefined;
+}) => Promise<{
+    headers: import("./types.js").Header[];
+    errors: Error[];
+}>;

package/lib/all.js

@@ -0,0 +1,36 @@
+import { parseFileHeaders } from './line_parser.js';
+import { mergeHeaders } from './merge.js';
+import { parseConfigHeaders } from './netlify_config_parser.js';
+import { normalizeHeaders } from './normalize.js';
+import { splitResults, concatResults } from './results.js';
+// Parse all headers from `netlify.toml` and `_headers` file, then normalize
+// and validate those.
+export const parseAllHeaders = async function ({ headersFiles = [], netlifyConfigPath, configHeaders = [], minimal = false, }) {
+    const [{ headers: fileHeaders, errors: fileParseErrors }, { headers: parsedConfigHeaders, errors: configParseErrors },] = await Promise.all([getFileHeaders(headersFiles), getConfigHeaders(netlifyConfigPath)]);
+    const { headers: normalizedFileHeaders, errors: fileNormalizeErrors } = normalizeHeaders(fileHeaders, minimal);
+    const { headers: normalizedConfigParseHeaders, errors: configParseNormalizeErrors } = normalizeHeaders(parsedConfigHeaders, minimal);
+    const { headers: normalizedConfigHeaders, errors: configNormalizeErrors } = normalizeHeaders(configHeaders, minimal);
+    const { headers, errors: mergeErrors } = mergeHeaders({
+        fileHeaders: normalizedFileHeaders,
+        configHeaders: [...normalizedConfigParseHeaders, ...normalizedConfigHeaders],
+    });
+    const errors = [
+        ...fileParseErrors,
+        ...fileNormalizeErrors,
+        ...configParseErrors,
+        ...configParseNormalizeErrors,
+        ...configNormalizeErrors,
+        ...mergeErrors,
+    ];
+    return { headers, errors };
+};
+const getFileHeaders = async function (headersFiles) {
+    const resultsArrays = await Promise.all(headersFiles.map(parseFileHeaders));
+    return concatResults(resultsArrays);
+};
+const getConfigHeaders = async function (netlifyConfigPath) {
+    if (netlifyConfigPath === undefined) {
+        return splitResults([]);
+    }
+    return await parseConfigHeaders(netlifyConfigPath);
+};

package/lib/for_regexp.d.ts

@@ -0,0 +1 @@
+export function getForRegExp(forPath: any): RegExp;

package/lib/for_regexp.js

@@ -0,0 +1,29 @@
+import escapeStringRegExp from 'escape-string-regexp';
+// Retrieve `forRegExp` which is a `RegExp` used to match the `for` path
+export const getForRegExp = function (forPath) {
+    const pattern = forPath.split('/').map(trimString).filter(Boolean).map(getPartRegExp).join('/');
+    return new RegExp(`^/${pattern}/?$`, 'iu');
+};
+const trimString = function (part) {
+    return part.trimEnd();
+};
+const getPartRegExp = function (part) {
+    // Placeholder like `/segment/:placeholder/test`
+    // Matches everything up to a /
+    if (part.startsWith(':')) {
+        return '([^/]+)';
+    }
+    // Standalone catch-all wildcard like `/segment/*`
+    // Unlike `:placeholder`, the whole part is optional
+    if (part === '*') {
+        return '?(.*)';
+    }
+    // Non-standalone catch-all wildcard like `/segment/hello*world/test`
+    if (part.includes('*')) {
+        // @todo use `part.replaceAll('*', ...)` after dropping support for
+        // Node <15.0.0
+        return part.replace(CATCH_ALL_CHAR_REGEXP, '(.*)');
+    }
+    return escapeStringRegExp(part);
+};
+const CATCH_ALL_CHAR_REGEXP = /\*/g;

package/lib/index.d.ts

@@ -0,0 +1 @@
+export { parseAllHeaders } from './all.js';

package/lib/index.js

@@ -0,0 +1 @@
+export { parseAllHeaders } from './all.js';

package/lib/line_parser.d.ts

@@ -0,0 +1,4 @@
+export declare const parseFileHeaders: (headersFile: string) => Promise<{
+    headers: any;
+    errors: any[];
+}>;

package/lib/line_parser.js

@@ -0,0 +1,84 @@
+import { promises as fs } from 'fs';
+import { pathExists } from 'path-exists';
+import { splitResults } from './results.js';
+// Parse `_headers` file to an array of objects following the same syntax as
+// the `headers` property in `netlify.toml`
+export const parseFileHeaders = async function (headersFile) {
+    const results = await parseHeaders(headersFile);
+    const { headers, errors: parseErrors } = splitResults(results);
+    const { headers: reducedHeaders, errors: reducedErrors } = headers.reduce(reduceLine, { headers: [], errors: [] });
+    const errors = [...parseErrors, ...reducedErrors];
+    return { headers: reducedHeaders, errors };
+};
+const parseHeaders = async function (headersFile) {
+    if (!(await pathExists(headersFile))) {
+        return [];
+    }
+    const text = await readHeadersFile(headersFile);
+    if (typeof text !== 'string') {
+        return [text];
+    }
+    return text.split('\n').map(normalizeLine).filter(hasHeader).map(parseLine).filter(Boolean);
+};
+const readHeadersFile = async function (headersFile) {
+    try {
+        return await fs.readFile(headersFile, 'utf-8');
+    }
+    catch {
+        return new Error(`Could not read headers file: ${headersFile}`);
+    }
+};
+const normalizeLine = function (line, index) {
+    return { line: line.trim(), index };
+};
+const hasHeader = function ({ line }) {
+    return line !== '' && !line.startsWith('#');
+};
+const parseLine = function ({ line, index }) {
+    try {
+        return parseHeaderLine(line);
+    }
+    catch (error) {
+        return new Error(`Could not parse header line ${index + 1}:
+  ${line}
+${error.message}`);
+    }
+};
+// Parse a single header line
+const parseHeaderLine = function (line) {
+    if (isPathLine(line)) {
+        return { path: line };
+    }
+    if (!line.includes(HEADER_SEPARATOR)) {
+        return;
+    }
+    const [rawName, ...rawValue] = line.split(HEADER_SEPARATOR);
+    const name = rawName.trim();
+    if (name === '') {
+        throw new Error(`Missing header name`);
+    }
+    const value = rawValue.join(HEADER_SEPARATOR).trim();
+    if (value === '') {
+        throw new Error(`Missing header value`);
+    }
+    return { name, value };
+};
+const isPathLine = function (line) {
+    return line.startsWith('/');
+};
+const HEADER_SEPARATOR = ':';
+const reduceLine = function ({ headers, errors }, { path, name, value }) {
+    if (path !== undefined) {
+        return { headers: [...headers, { for: path, values: {} }], errors };
+    }
+    if (headers.length === 0) {
+        const error = new Error(`Path should come before header "${name}"`);
+        return { headers, errors: [...errors, error] };
+    }
+    const previousHeaders = headers.slice(0, -1);
+    const currentHeader = headers[headers.length - 1];
+    const { values } = currentHeader;
+    const newValue = values[name] === undefined ? value : `${values[name]}, ${value}`;
+    const newHeaders = [...previousHeaders, { ...currentHeader, values: { ...values, [name]: newValue } }];
+    return { headers: newHeaders, errors };
+};

package/lib/merge.d.ts

@@ -0,0 +1,8 @@
+import type { Header } from './types.js';
+export declare const mergeHeaders: ({ fileHeaders, configHeaders, }: {
+    fileHeaders: (Error | Header)[];
+    configHeaders: (Error | Header)[];
+}) => {
+    headers: Header[];
+    errors: Error[];
+};

package/lib/merge.js

@@ -0,0 +1,50 @@
+import stringify from 'fast-safe-stringify';
+import { splitResults } from './results.js';
+// Merge headers from `_headers` with the ones from `netlify.toml`.
+// When:
+//  - Both `netlify.toml` headers and `_headers` are specified, paths are
+//    merged. If the same path is specified in both, their headers are merged.
+//    If the same path and header is specified both in `netlify.toml` and
+//    `_headers`, the one in `netlify.toml` is used (i.e. overrides, does not
+//    concatenate).
+//  - The same path is specified twice in `netlify.toml` headers, their headers
+//    are merged. If the same header is specified twice in different places for
+//    the same path, the later one overrides (does not concatenate) any earlier
+//    ones. If the same header is specified twice in the same place for the same
+//    path, it is concatenated as a comma-separated list string.
+//  - The same path is specified twice in `_headers`, the behavior is the same
+//    as `netlify.toml` headers.
+export const mergeHeaders = function ({ fileHeaders, configHeaders, }) {
+    const results = [...fileHeaders, ...configHeaders];
+    const { headers, errors } = splitResults(results);
+    const mergedHeaders = removeDuplicates(headers);
+    return { headers: mergedHeaders, errors };
+};
+// Remove duplicates. This is especially likely considering `fileHeaders` might
+// have been previously merged to `configHeaders`, which happens when
+// `netlifyConfig.headers` is modified by plugins.
+// The latest duplicate value is the one kept, hence why we need to iterate the
+// array backwards and reverse it at the end
+const removeDuplicates = function (headers) {
+    const uniqueHeaders = new Set();
+    const result = [];
+    for (let i = headers.length - 1; i >= 0; i--) {
+        const h = headers[i];
+        const key = generateHeaderKey(h);
+        if (uniqueHeaders.has(key))
+            continue;
+        uniqueHeaders.add(key);
+        result.push(h);
+    }
+    return result.reverse();
+};
+// We generate a unique header key based on JSON stringify. However, because some
+// properties can be regexes, we need to replace those by their toString representation
+// given the default will be and empty object
+const generateHeaderKey = function (header) {
+    return stringify.default.stableStringify(header, (_, value) => {
+        if (value instanceof RegExp)
+            return value.toString();
+        return value;
+    });
+};

package/lib/netlify_config_parser.d.ts

@@ -0,0 +1,4 @@
+export declare const parseConfigHeaders: (netlifyConfigPath: string) => Promise<{
+    headers: any[];
+    errors: Error[];
+}>;

package/lib/netlify_config_parser.js

@@ -0,0 +1,30 @@
+import { promises as fs } from 'fs';
+import { parse as loadToml } from '@iarna/toml';
+import { pathExists } from 'path-exists';
+import { splitResults } from './results.js';
+// Parse `headers` field in "netlify.toml" to an array of objects.
+// This field is already an array of objects, so it only validates and
+// normalizes it.
+export const parseConfigHeaders = async function (netlifyConfigPath) {
+    if (!(await pathExists(netlifyConfigPath))) {
+        return splitResults([]);
+    }
+    const headers = await parseConfig(netlifyConfigPath);
+    return splitResults(headers);
+};
+// Load the configuration file and parse it (TOML)
+const parseConfig = async function (configPath) {
+    try {
+        const configString = await fs.readFile(configPath, 'utf8');
+        const config = loadToml(configString);
+        // Convert `null` prototype objects to normal plain objects
+        const { headers = [] } = JSON.parse(JSON.stringify(config));
+        if (!Array.isArray(headers)) {
+            throw new TypeError(`"headers" must be an array`);
+        }
+        return headers;
+    }
+    catch (error) {
+        return [new Error(`Could not parse configuration file: ${error}`)];
+    }
+};

package/lib/normalize.d.ts

@@ -0,0 +1,8 @@
+import type { Header } from './types.js';
+export declare const normalizeHeaders: (headers: any, minimal: boolean) => {
+    headers: Header[];
+    errors: Error[];
+} | {
+    headers: TypeError[];
+    errors: Error[];
+};

package/lib/normalize.js

@@ -0,0 +1,112 @@
+import isPlainObj from 'is-plain-obj';
+import mapObj from 'map-obj';
+import { getForRegExp } from './for_regexp.js';
+import { splitResults } from './results.js';
+// Validate and normalize an array of `headers` objects.
+// This step is performed after `headers` have been parsed from either
+// `netlify.toml` or `_headers`.
+export const normalizeHeaders = function (headers, minimal) {
+    if (!Array.isArray(headers)) {
+        const error = new TypeError(`Headers must be an array not: ${headers}`);
+        return splitResults([error]);
+    }
+    const results = headers
+        .map((header, index) => parseHeader(header, index, minimal))
+        .filter(Boolean);
+    return splitResults(results);
+};
+const parseHeader = function (header, index, minimal) {
+    if (!isPlainObj(header)) {
+        return new TypeError(`Header must be an object not: ${header}`);
+    }
+    try {
+        return parseHeaderObject(header, minimal);
+    }
+    catch (error) {
+        return new Error(`Could not parse header number ${index + 1}:
+  ${JSON.stringify(header)}
+${error.message}`);
+    }
+};
+// Parse a single `headers` object
+const parseHeaderObject = function ({ for: rawPath, values: rawValues }, minimal) {
+    const forPath = normalizePath(rawPath);
+    if (rawValues === undefined) {
+        return;
+    }
+    const values = normalizeValues(rawValues);
+    if (Object.keys(values).length === 0) {
+        return;
+    }
+    const header = {
+        for: forPath,
+        values,
+    };
+    if (!minimal) {
+        header.forRegExp = getForRegExp(forPath);
+    }
+    return header;
+};
+// Normalize and validate the `for` field
+const normalizePath = function (rawPath) {
+    if (rawPath === undefined) {
+        throw new TypeError('Missing "for" field');
+    }
+    if (typeof rawPath !== 'string') {
+        throw new TypeError(`"for" must be a string not: ${rawPath}`);
+    }
+    return rawPath.trim();
+};
+// Normalize and validate the `values` field
+const normalizeValues = function (rawValues) {
+    if (!isPlainObj(rawValues)) {
+        throw new TypeError(`"values" must be an object not: ${rawValues}`);
+    }
+    return mapObj(rawValues, normalizeValue);
+};
+// Normalize and validate each header `values`
+const normalizeValue = function (rawKey, rawValue) {
+    const key = rawKey.trim();
+    if (key === '' || key === 'undefined') {
+        throw new Error('Empty header name');
+    }
+    const value = normalizeRawValue(key, rawValue);
+    return [key, value];
+};
+const normalizeRawValue = function (key, rawValue) {
+    if (typeof rawValue === 'string') {
+        return normalizeMultipleValues(normalizeStringValue(rawValue));
+    }
+    if (Array.isArray(rawValue)) {
+        return rawValue.map((singleValue, index) => normalizeArrayItemValue(`${key}[${index}]`, singleValue)).join(', ');
+    }
+    throw new TypeError(`Header "${key}" value must be a string not: ${rawValue}`);
+};
+// Multiple values can be specified by using whitespaces and commas.
+// For example:
+//   [[headers]]
+//   for = "/*"
+//     [headers.values]
+// 	   cache-control = '''
+// 	   max-age=0,
+// 	   no-cache,
+// 	   no-store,
+// 	   must-revalidate'''
+// Is normalized to:
+//   [[headers]]
+//   for = "/*"
+//     [headers.values]
+// 	   cache-control = "max-age=0, no-cache, no-store, must-revalidate"
+const normalizeMultipleValues = function (value) {
+    return value.split(MULTIPLE_VALUES_REGEXP).join(', ');
+};
+const MULTIPLE_VALUES_REGEXP = /\s*,\s*/g;
+const normalizeArrayItemValue = function (key, singleValue) {
+    if (typeof singleValue !== 'string') {
+        throw new TypeError(`Header "${key}" value must be a string not: ${singleValue}`);
+    }
+    return normalizeStringValue(singleValue);
+};
+const normalizeStringValue = function (stringValue) {
+    return stringValue.trim();
+};

package/lib/results.d.ts

@@ -0,0 +1,12 @@
+import type { Header } from './types.js';
+export declare function splitResults<Type>(results: (Error | Type)[]): {
+    headers: Type[];
+    errors: Error[];
+};
+export declare const concatResults: (resultsArrays: {
+    headers: Header[];
+    errors: Error[];
+}[]) => {
+    headers: Header[];
+    errors: Error[];
+};

package/lib/results.js

@@ -0,0 +1,15 @@
+// If one header fails to parse, we still try to return the other ones
+export function splitResults(results) {
+    const headers = results.filter((result) => !isError(result));
+    const errors = results.filter(isError);
+    return { headers, errors };
+}
+const isError = function (result) {
+    return result instanceof Error;
+};
+// Concatenate an array of `{ headers, errors }`
+export const concatResults = function (resultsArrays) {
+    const headers = resultsArrays.flatMap(({ headers }) => headers);
+    const errors = resultsArrays.flatMap(({ errors }) => errors);
+    return { headers, errors };
+};

package/lib/types.d.ts

@@ -0,0 +1,7 @@
+export type Header = {
+    for: string;
+    forRegExp?: RegExp;
+    values: {
+        [key: string]: string;
+    };
+};

package/lib/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@netlify/headers-parser",
+  "version": "7.2.0",
+  "description": "Parses Netlify headers into a JavaScript object representation",
+  "type": "module",
+  "exports": "./lib/index.js",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.js",
+  "files": [
+    "lib/**/*"
+  ],
+  "scripts": {
+    "prebuild": "rm -rf lib",
+    "build": "tsc",
+    "test": "vitest run",
+    "test:bench": "vitest bench",
+    "test:dev": "vitest",
+    "test:ci": "vitest run --reporter=default && vitest bench --run --passWithNoTests"
+  },
+  "keywords": [
+    "netlify"
+  ],
+  "engines": {
+    "node": "^14.16.0 || >=16.0.0"
+  },
+  "author": "Netlify",
+  "license": "MIT",
+  "dependencies": {
+    "@iarna/toml": "^2.2.5",
+    "escape-string-regexp": "^5.0.0",
+    "fast-safe-stringify": "^2.0.7",
+    "is-plain-obj": "^4.0.0",
+    "map-obj": "^5.0.0",
+    "path-exists": "^5.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^14.18.53",
+    "typescript": "^5.0.0",
+    "vitest": "^0.34.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/netlify/build.git",
+    "directory": "packages/headers-parser"
+  },
+  "bugs": {
+    "url": "https://github.com/netlify/build/issues"
+  },
+  "homepage": "https://github.com/netlify/build#readme",
+  "gitHead": "131a644bfde5205f730f3369b778d8914c7c0382"
+}