Add support for 1xx codes

Author: pimterry

src/endpoints/http-index.ts

@@ -64,3 +64,4 @@ export * from './http/redirect.js';
 export * from './http/bytes.js';
 export * from './http/stream.js';
 export * from './http/stream-bytes.js';
+export * from './http/informational.js';

src/endpoints/http/informational.ts

@@ -0,0 +1,106 @@
+import { STATUS_CODES } from 'http';
+import { StatusError } from '@httptoolkit/util';
+import { HttpEndpoint, HttpHandler, HttpResponse } from '../http-index.js';
+import { httpCustomResponses } from '../groups.js';
+
+const PREFIX = '/info/';
+
+// 101 is reserved for protocol upgrades and isn't meaningful as a standalone
+// informational response, so we exclude it.
+const isSupportedInformationalCode = (code: number): boolean =>
+    code >= 100 && code < 200 && code !== 101;
+
+const parseCode = (path: string): number => {
+    const rest = path.slice(PREFIX.length);
+    const end = rest.indexOf('/');
+    const codeStr = end === -1 ? rest : rest.slice(0, end);
+    return parseInt(codeStr, 10);
+};
+
+const getRemainingPath = (path: string): string | undefined => {
+    const idx = path.indexOf('/', PREFIX.length);
+    return idx !== -1 ? path.slice(idx) : undefined;
+};
+
+const sendInformational = (
+    res: HttpResponse,
+    code: number,
+    headers: Record<string, string | string[]>
+): void => {
+    const writeRaw = (res as { _writeRaw?: (chunk: string, encoding: string) => void })._writeRaw;
+    if (typeof writeRaw === 'function') {
+        let raw = `HTTP/1.1 ${code} ${STATUS_CODES[code] ?? ''}\r\n`;
+        for (const [name, value] of Object.entries(headers)) {
+            for (const v of Array.isArray(value) ? value : [value]) {
+                raw += `${name}: ${v}\r\n`;
+            }
+        }
+        raw += '\r\n';
+        writeRaw.call(res, raw, 'latin1');
+        return;
+    }
+
+    const stream = (res as { stream?: { additionalHeaders?: (h: object) => void } }).stream;
+    if (stream?.additionalHeaders) {
+        stream.additionalHeaders({ ':status': code, ...headers });
+        return;
+    }
+
+    throw new StatusError(500, 'No mechanism available to send informational response');
+};
+
+const handle: HttpHandler = (_req, res, { path, query }) => {
+    const code = parseCode(path);
+
+    const headers: Record<string, string | string[]> = {};
+    const links = query.getAll('link');
+    if (links.length > 0) headers['link'] = links;
+
+    sendInformational(res, code, headers);
+
+    if (getRemainingPath(path)) {
+        return; // Chain continues to the next endpoint as the final response
+    }
+
+    const body = JSON.stringify({
+        sent: { code, headers }
+    }, null, 2);
+    res.writeHead(200, {
+        'content-type': 'application/json',
+        'content-length': Buffer.byteLength(body)
+    });
+    res.end(body);
+};
+
+export const informational: HttpEndpoint = {
+    matchPath: (path) => {
+        if (!path.startsWith(PREFIX)) return false;
+        const code = parseCode(path);
+        if (isNaN(code)) {
+            throw new StatusError(400, `Invalid status code in ${path}`);
+        }
+        if (!isSupportedInformationalCode(code)) {
+            throw new StatusError(400,
+                `${code} is not a 1xx informational status code. ` +
+                `Use any code in 100-199 except 101 (which is reserved for protocol upgrades).`
+            );
+        }
+        return true;
+    },
+    handle,
+    getRemainingPath,
+    meta: {
+        path: '/info/{code}',
+        description:
+            'Sends a 1xx informational response (100, 102, or 103) before the final response. ' +
+            'Supports all codes except 101 which is reserved for protocol upgrades (e.g. websockets). ' +
+            'Use `?link=...` (repeatable) to attach Link headers for testing 103 Early Hints. ' +
+            'Chains with other endpoints: e.g. /info/103/status/404 sends 103 then 404.',
+        examples: [
+            '/info/102',
+            '/info/103?link=%3C/style.css%3E;rel=preload;as=style',
+            '/info/110/info/199/echo'
+        ],
+        group: httpCustomResponses
+    }
+};

src/endpoints/http/status.ts

@@ -19,6 +19,12 @@ export const status: HttpEndpoint = {
         if (isNaN(statusCode)) {
             throw new StatusError(400, `Invalid status code in ${path}`);
         }
+        if (statusCode >= 100 && statusCode < 200) {
+            throw new StatusError(400,
+                `1xx codes are informational and cannot be used as a final response. ` +
+                `Use /info/${statusCode} instead.`
+            );
+        }
         return true;
     },
     handle,

test/informational.spec.ts

@@ -0,0 +1,222 @@
+import * as net from 'net';
+import * as http from 'http';
+import * as http2 from 'http2';
+import * as streamConsumers from 'stream/consumers';
+
+import { expect } from 'chai';
+import { DestroyableServer, makeDestroyable } from 'destroyable-server';
+
+import { createTestServer } from './test-helpers.js';
+
+interface Informational {
+    statusCode: number;
+    headers: http.IncomingHttpHeaders;
+}
+
+async function h1Request(port: number, path: string): Promise<{
+    informationals: Informational[];
+    finalStatusCode: number;
+    body: string;
+}> {
+    return new Promise((resolve, reject) => {
+        const informationals: Informational[] = [];
+
+        const req = http.request({ port, path, method: 'GET' }, (res) => {
+            const chunks: Buffer[] = [];
+            res.on('data', (c) => chunks.push(c));
+            res.on('end', () => {
+                resolve({
+                    informationals,
+                    finalStatusCode: res.statusCode!,
+                    body: Buffer.concat(chunks).toString('utf8')
+                });
+            });
+            res.on('error', reject);
+        });
+
+        req.on('information', (info) => {
+            informationals.push({ statusCode: info.statusCode, headers: info.headers });
+        });
+        req.on('error', reject);
+        req.end();
+    });
+}
+
+describe("Informational endpoint", () => {
+
+    let server: DestroyableServer;
+    let serverPort: number;
+
+    beforeEach(async () => {
+        server = makeDestroyable(await createTestServer());
+        await new Promise<void>((resolve) => server.listen(resolve));
+        serverPort = (server.address() as net.AddressInfo).port;
+    });
+
+    afterEach(async () => {
+        await server.destroy();
+    });
+
+    it("sends a 103 Early Hints with a link header, then a 200", async () => {
+        const result = await h1Request(serverPort,
+            '/info/103?link=%3C/style.css%3E%3Brel%3Dpreload%3Bas%3Dstyle'
+        );
+
+        expect(result.informationals).to.have.length(1);
+        expect(result.informationals[0].statusCode).to.equal(103);
+        expect(result.informationals[0].headers['link']).to.equal(
+            '</style.css>;rel=preload;as=style'
+        );
+
+        expect(result.finalStatusCode).to.equal(200);
+        const body = JSON.parse(result.body);
+        expect(body.sent.code).to.equal(103);
+    });
+
+    it("sends multiple link headers in a single 103", async () => {
+        const result = await h1Request(serverPort,
+            '/info/103?link=%3C/a.css%3E&link=%3C/b.js%3E'
+        );
+
+        // Node folds repeated Link headers into a comma-separated string.
+        expect(result.informationals[0].headers['link']).to.equal(
+            '</a.css>, </b.js>'
+        );
+    });
+
+    it("supports non-standard 1xx codes such as 199", async () => {
+        const result = await h1Request(serverPort, '/info/199');
+        expect(result.informationals.map(i => i.statusCode)).to.deep.equal([199]);
+        expect(result.finalStatusCode).to.equal(200);
+    });
+
+    it("chains multiple /info hops to send multiple informationals", async () => {
+        const result = await h1Request(serverPort, '/info/103/info/103/info/100/anything');
+        expect(result.informationals.map(i => i.statusCode)).to.deep.equal([103, 103, 100]);
+        expect(result.finalStatusCode).to.equal(200);
+    });
+
+    it("chains: /info/103/anything sends 103 then runs /anything", async () => {
+        const result = await h1Request(serverPort, '/info/103/anything');
+        expect(result.informationals.map(i => i.statusCode)).to.deep.equal([103]);
+        expect(result.finalStatusCode).to.equal(200);
+        const body = JSON.parse(result.body);
+        expect(body.url).to.match(/\/anything$/);
+    });
+
+    it("chains: /info/103/status/418 sends 103 then a 418", async () => {
+        const result = await h1Request(serverPort, '/info/103/status/418');
+        expect(result.informationals.map(i => i.statusCode)).to.deep.equal([103]);
+        expect(result.finalStatusCode).to.equal(418);
+    });
+
+    it("rejects 101 with a 400 (reserved for upgrades)", async () => {
+        const response = await fetch(`http://localhost:${serverPort}/info/101`);
+        expect(response.status).to.equal(400);
+    });
+
+    it("rejects non-1xx codes with a 400", async () => {
+        const response = await fetch(`http://localhost:${serverPort}/info/200`);
+        expect(response.status).to.equal(400);
+    });
+
+    it("rejects non-numeric codes with a 400", async () => {
+        const response = await fetch(`http://localhost:${serverPort}/info/abc`);
+        expect(response.status).to.equal(400);
+    });
+
+});
+
+describe("Status endpoint with 1xx codes", () => {
+
+    let server: DestroyableServer;
+    let serverPort: number;
+
+    beforeEach(async () => {
+        server = makeDestroyable(await createTestServer());
+        await new Promise<void>((resolve) => server.listen(resolve));
+        serverPort = (server.address() as net.AddressInfo).port;
+    });
+
+    afterEach(async () => {
+        await server.destroy();
+    });
+
+    it("rejects /status/100 with a 400 pointing to /info", async () => {
+        const response = await fetch(`http://localhost:${serverPort}/status/100`);
+        expect(response.status).to.equal(400);
+        const body = await response.text();
+        expect(body).to.include('/info/100');
+    });
+
+});
+
+describe("Informational endpoint over HTTP/2", () => {
+
+    let server: DestroyableServer;
+    let serverPort: number;
+
+    beforeEach(async () => {
+        server = makeDestroyable(await createTestServer());
+        await new Promise<void>((resolve) => server.listen(resolve));
+        serverPort = (server.address() as net.AddressInfo).port;
+    });
+
+    afterEach(async () => {
+        await server.destroy();
+    });
+
+    async function h2Request(path: string): Promise<{
+        informationals: Array<{ statusCode: number; headers: http2.IncomingHttpHeaders }>;
+        finalStatusCode: number;
+        body: string;
+    }> {
+        const client = http2.connect(`http://localhost:${serverPort}`);
+        try {
+            const request = client.request({ ':path': path, ':method': 'GET' });
+            const informationals: Array<{ statusCode: number; headers: http2.IncomingHttpHeaders }> = [];
+            let finalHeaders: http2.IncomingHttpHeaders & http2.IncomingHttpStatusHeader | undefined;
+
+            await new Promise<void>((resolve, reject) => {
+                request.on('headers', (headers) => {
+                    informationals.push({
+                        statusCode: headers[':status'] as number,
+                        headers
+                    });
+                });
+                request.on('response', (headers) => {
+                    finalHeaders = headers;
+                    resolve();
+                });
+                request.on('error', reject);
+            });
+
+            const body = await streamConsumers.text(request);
+            return {
+                informationals,
+                finalStatusCode: finalHeaders![':status']!,
+                body
+            };
+        } finally {
+            client.close();
+        }
+    }
+
+    it("sends a 103 with a Link header before the final response", async () => {
+        const result = await h2Request('/info/103?link=%3C/style.css%3E');
+
+        expect(result.informationals.map(i => i.statusCode)).to.deep.equal([103]);
+        expect(result.informationals[0].headers['link']).to.equal('</style.css>');
+        expect(result.finalStatusCode).to.equal(200);
+    });
+
+    it("chains 1xx with /anything as the final response", async () => {
+        const result = await h2Request('/info/103/anything');
+
+        expect(result.informationals.map(i => i.statusCode)).to.deep.equal([103]);
+        expect(result.finalStatusCode).to.equal(200);
+        const body = JSON.parse(result.body);
+        expect(body.url).to.match(/\/anything$/);
+    });
+
+});