Add stream & bytes endpoints

Author: pimterry

src/endpoints/http-index.ts

@@ -61,3 +61,6 @@ export * from './http/base64.js';
 export * from './http/cache.js';
 export * from './http/etag.js';
 export * from './http/redirect.js';
+export * from './http/bytes.js';
+export * from './http/stream.js';
+export * from './http/stream-bytes.js';

src/endpoints/http/bytes.ts

@@ -0,0 +1,55 @@
+import * as crypto from 'crypto';
+import { StatusError } from '@httptoolkit/util';
+import { HttpEndpoint } from '../http-index.js';
+import { httpDynamicData } from '../groups.js';
+
+const MAX_BYTES = 102400; // 100KB
+
+const parseN = (path: string): number => {
+    const n = parseInt(path.slice('/bytes/'.length), 10);
+    if (isNaN(n) || n < 0) throw new StatusError(400, `Invalid byte count in ${path}`);
+    if (n > MAX_BYTES) throw new StatusError(400, `Byte count exceeds maximum of ${MAX_BYTES}`);
+    return n;
+};
+
+export const bytesEndpoint: HttpEndpoint = {
+    matchPath: (path) => {
+        if (!path.match(/^\/bytes\/\d+$/)) return false;
+        parseN(path);
+        return true;
+    },
+    handle: (_req, res, { path, query }) => {
+        const n = parseN(path);
+        const seed = query.get('seed');
+
+        let data: Buffer;
+        if (seed !== null) {
+            // Seeded: use seed to generate deterministic bytes via hash chaining
+            const chunks: Buffer[] = [];
+            let remaining = n;
+            let counter = 0;
+            while (remaining > 0) {
+                const hash = crypto.createHash('sha256')
+                    .update(`${seed}:${counter++}`)
+                    .digest();
+                chunks.push(hash.subarray(0, Math.min(remaining, hash.length)));
+                remaining -= hash.length;
+            }
+            data = Buffer.concat(chunks, n);
+        } else {
+            data = crypto.randomBytes(n);
+        }
+
+        res.writeHead(200, {
+            'content-type': 'application/octet-stream',
+            'content-length': n.toString()
+        });
+        res.end(data);
+    },
+    meta: {
+        path: '/bytes/{n}',
+        description: 'Returns n random bytes. Supports an optional "seed" query parameter for deterministic output.',
+        examples: ['/bytes/1024'],
+        group: httpDynamicData
+    }
+};

src/endpoints/http/stream-bytes.ts

@@ -0,0 +1,60 @@
+import * as crypto from 'crypto';
+import { StatusError } from '@httptoolkit/util';
+import { HttpEndpoint } from '../http-index.js';
+import { httpDynamicData } from '../groups.js';
+
+const MAX_BYTES = 102400; // 100KB
+
+const parseN = (path: string): number => {
+    const n = parseInt(path.slice('/stream-bytes/'.length), 10);
+    if (isNaN(n) || n < 0) throw new StatusError(400, `Invalid byte count in ${path}`);
+    if (n > MAX_BYTES) throw new StatusError(400, `Byte count exceeds maximum of ${MAX_BYTES}`);
+    return n;
+};
+
+export const streamBytesEndpoint: HttpEndpoint = {
+    matchPath: (path) => {
+        if (!path.match(/^\/stream-bytes\/\d+$/)) return false;
+        parseN(path);
+        return true;
+    },
+    handle: (_req, res, { path, query }) => {
+        const n = parseN(path);
+        const chunkSize = Math.max(1, parseInt(query.get('chunk_size') || '10240', 10));
+        const seed = query.get('seed');
+
+        res.writeHead(200, { 'content-type': 'application/octet-stream' });
+
+        let remaining = n;
+        let counter = 0;
+        while (remaining > 0) {
+            const size = Math.min(remaining, chunkSize);
+            let chunk: Buffer;
+
+            if (seed !== null) {
+                const parts: Buffer[] = [];
+                let partRemaining = size;
+                while (partRemaining > 0) {
+                    const hash = crypto.createHash('sha256')
+                        .update(`${seed}:${counter++}`)
+                        .digest();
+                    parts.push(hash.subarray(0, Math.min(partRemaining, hash.length)));
+                    partRemaining -= hash.length;
+                }
+                chunk = Buffer.concat(parts, size);
+            } else {
+                chunk = crypto.randomBytes(size);
+            }
+
+            (res as NodeJS.WritableStream).write(chunk);
+            remaining -= size;
+        }
+        res.end();
+    },
+    meta: {
+        path: '/stream-bytes/{n}',
+        description: 'Streams n random bytes in chunks. Supports optional "chunk_size" (default 10240) and "seed" query parameters.',
+        examples: ['/stream-bytes/1024'],
+        group: httpDynamicData
+    }
+};

src/endpoints/http/stream.ts

@@ -0,0 +1,40 @@
+import { StatusError } from '@httptoolkit/util';
+import { HttpEndpoint } from '../http-index.js';
+import { httpDynamicData } from '../groups.js';
+import { buildHttpBinAnythingData } from '../../httpbin-compat.js';
+
+const MAX_LINES = 100;
+
+const parseN = (path: string): number => {
+    const n = parseInt(path.slice('/stream/'.length), 10);
+    if (isNaN(n) || n < 0) throw new StatusError(400, `Invalid stream count in ${path}`);
+    if (n > MAX_LINES) throw new StatusError(400, `Stream count exceeds maximum of ${MAX_LINES}`);
+    return n;
+};
+
+export const streamEndpoint: HttpEndpoint = {
+    matchPath: (path) => {
+        if (!path.match(/^\/stream\/\d+$/)) return false;
+        parseN(path);
+        return true;
+    },
+    handle: async (req, res) => {
+        const n = parseN(req.url!.split('?')[0]);
+        const data = await buildHttpBinAnythingData(req, {
+            fieldFilter: ["url", "args", "headers", "origin"]
+        });
+
+        res.writeHead(200, { 'content-type': 'application/json' });
+
+        for (let i = 0; i < n; i++) {
+            (res as NodeJS.WritableStream).write(JSON.stringify({ id: i, ...data as object }) + '\n');
+        }
+        res.end();
+    },
+    meta: {
+        path: '/stream/{n}',
+        description: 'Streams n newline-delimited JSON objects, each containing request data with an incrementing id.',
+        examples: ['/stream/5'],
+        group: httpDynamicData
+    }
+};

test/bytes.spec.ts

@@ -0,0 +1,58 @@
+import * as net from 'net';
+import { expect } from 'chai';
+import { DestroyableServer, makeDestroyable } from 'destroyable-server';
+
+import { createServer } from '../src/server.js';
+
+describe("Bytes endpoint", () => {
+
+    let server: DestroyableServer;
+    let serverPort: number;
+
+    beforeEach(async () => {
+        server = makeDestroyable(await createServer());
+        await new Promise<void>((resolve) => server.listen(resolve));
+        serverPort = (server.address() as net.AddressInfo).port;
+    });
+
+    afterEach(async () => {
+        await server.destroy();
+    });
+
+    it("returns the specified number of random bytes", async () => {
+        const response = await fetch(`http://localhost:${serverPort}/bytes/256`);
+        expect(response.status).to.equal(200);
+        expect(response.headers.get('content-type')).to.equal('application/octet-stream');
+        expect(response.headers.get('content-length')).to.equal('256');
+        const body = await response.arrayBuffer();
+        expect(body.byteLength).to.equal(256);
+    });
+
+    it("returns zero bytes for /bytes/0", async () => {
+        const response = await fetch(`http://localhost:${serverPort}/bytes/0`);
+        expect(response.status).to.equal(200);
+        const body = await response.arrayBuffer();
+        expect(body.byteLength).to.equal(0);
+    });
+
+    it("returns deterministic output with seed", async () => {
+        const r1 = await fetch(`http://localhost:${serverPort}/bytes/64?seed=42`);
+        const r2 = await fetch(`http://localhost:${serverPort}/bytes/64?seed=42`);
+        const b1 = Buffer.from(await r1.arrayBuffer());
+        const b2 = Buffer.from(await r2.arrayBuffer());
+        expect(b1.equals(b2)).to.be.true;
+    });
+
+    it("returns different output with different seeds", async () => {
+        const r1 = await fetch(`http://localhost:${serverPort}/bytes/64?seed=1`);
+        const r2 = await fetch(`http://localhost:${serverPort}/bytes/64?seed=2`);
+        const b1 = Buffer.from(await r1.arrayBuffer());
+        const b2 = Buffer.from(await r2.arrayBuffer());
+        expect(b1.equals(b2)).to.be.false;
+    });
+
+    it("rejects byte counts over the maximum", async () => {
+        const response = await fetch(`http://localhost:${serverPort}/bytes/200000`);
+        expect(response.status).to.equal(400);
+    });
+});

test/stream-bytes.spec.ts

@@ -0,0 +1,60 @@
+import * as net from 'net';
+import { expect } from 'chai';
+import { DestroyableServer, makeDestroyable } from 'destroyable-server';
+
+import { createServer } from '../src/server.js';
+
+describe("Stream-bytes endpoint", () => {
+
+    let server: DestroyableServer;
+    let serverPort: number;
+
+    beforeEach(async () => {
+        server = makeDestroyable(await createServer());
+        await new Promise<void>((resolve) => server.listen(resolve));
+        serverPort = (server.address() as net.AddressInfo).port;
+    });
+
+    afterEach(async () => {
+        await server.destroy();
+    });
+
+    it("streams the specified number of bytes", async () => {
+        const response = await fetch(`http://localhost:${serverPort}/stream-bytes/512`);
+        expect(response.status).to.equal(200);
+        expect(response.headers.get('content-type')).to.equal('application/octet-stream');
+        const body = await response.arrayBuffer();
+        expect(body.byteLength).to.equal(512);
+    });
+
+    it("returns zero bytes for /stream-bytes/0", async () => {
+        const response = await fetch(`http://localhost:${serverPort}/stream-bytes/0`);
+        expect(response.status).to.equal(200);
+        const body = await response.arrayBuffer();
+        expect(body.byteLength).to.equal(0);
+    });
+
+    it("returns deterministic output with seed", async () => {
+        const r1 = await fetch(`http://localhost:${serverPort}/stream-bytes/128?seed=abc`);
+        const r2 = await fetch(`http://localhost:${serverPort}/stream-bytes/128?seed=abc`);
+        const b1 = Buffer.from(await r1.arrayBuffer());
+        const b2 = Buffer.from(await r2.arrayBuffer());
+        expect(b1.equals(b2)).to.be.true;
+    });
+
+    it("respects custom chunk_size", async () => {
+        // Just verify it works — we can't easily inspect chunking from fetch,
+        // but we can confirm the total byte count is correct
+        const response = await fetch(
+            `http://localhost:${serverPort}/stream-bytes/100?chunk_size=10`
+        );
+        expect(response.status).to.equal(200);
+        const body = await response.arrayBuffer();
+        expect(body.byteLength).to.equal(100);
+    });
+
+    it("rejects byte counts over the maximum", async () => {
+        const response = await fetch(`http://localhost:${serverPort}/stream-bytes/200000`);
+        expect(response.status).to.equal(400);
+    });
+});

test/stream.spec.ts

@@ -0,0 +1,59 @@
+import * as net from 'net';
+import { expect } from 'chai';
+import { DestroyableServer, makeDestroyable } from 'destroyable-server';
+
+import { createServer } from '../src/server.js';
+
+describe("Stream endpoint", () => {
+
+    let server: DestroyableServer;
+    let serverPort: number;
+
+    beforeEach(async () => {
+        server = makeDestroyable(await createServer());
+        await new Promise<void>((resolve) => server.listen(resolve));
+        serverPort = (server.address() as net.AddressInfo).port;
+    });
+
+    afterEach(async () => {
+        await server.destroy();
+    });
+
+    it("streams n JSON lines", async () => {
+        const response = await fetch(`http://localhost:${serverPort}/stream/3`);
+        expect(response.status).to.equal(200);
+        expect(response.headers.get('content-type')).to.equal('application/json');
+
+        const body = await response.text();
+        const lines = body.trim().split('\n');
+        expect(lines).to.have.length(3);
+
+        const parsed = lines.map(l => JSON.parse(l));
+        expect(parsed[0].id).to.equal(0);
+        expect(parsed[1].id).to.equal(1);
+        expect(parsed[2].id).to.equal(2);
+    });
+
+    it("includes request data fields in each line", async () => {
+        const response = await fetch(`http://localhost:${serverPort}/stream/1`);
+        const body = await response.text();
+        const obj = JSON.parse(body.trim());
+
+        expect(obj).to.have.property('id', 0);
+        expect(obj).to.have.property('url');
+        expect(obj).to.have.property('headers');
+        expect(obj).to.have.property('origin');
+    });
+
+    it("returns empty body for n=0", async () => {
+        const response = await fetch(`http://localhost:${serverPort}/stream/0`);
+        expect(response.status).to.equal(200);
+        const body = await response.text();
+        expect(body).to.equal('');
+    });
+
+    it("rejects n over maximum", async () => {
+        const response = await fetch(`http://localhost:${serverPort}/stream/200`);
+        expect(response.status).to.equal(400);
+    });
+});