Add a docs landing page

Author: pimterry

src/docs-page.ts

@@ -0,0 +1,78 @@
+export interface EndpointGroup {
+    id: string;
+    name: string;
+    description?: string;
+    combinedExamples?: string[];
+}
+
+export interface EndpointMeta {
+    path: string;
+    description: string;
+    examples?: string[];
+    group?: EndpointGroup;
+}
+
+// HTTP endpoint groups
+export const httpContentExamples: EndpointGroup = {
+    id: 'content-examples',
+    name: 'Response Content Formats'
+};
+
+export const httpAuthentication: EndpointGroup = {
+    id: 'authentication',
+    name: 'Authentication'
+};
+
+export const httpCookies: EndpointGroup = {
+    id: 'cookies',
+    name: 'Cookies'
+};
+
+export const httpContentEncoding: EndpointGroup = {
+    id: 'content-encoding',
+    name: 'Response Content Encodings'
+};
+
+export const httpErrors: EndpointGroup = {
+    id: 'errors',
+    name: 'Errors'
+};
+
+// WebSocket endpoint groups
+export const wsMessaging: EndpointGroup = {
+    id: 'messaging',
+    name: 'Messaging'
+};
+
+export const wsConnection: EndpointGroup = {
+    id: 'connection',
+    name: 'Connection'
+};
+
+export const wsTiming: EndpointGroup = {
+    id: 'timing',
+    name: 'Timing'
+};
+
+export const wsErrors: EndpointGroup = {
+    id: 'errors',
+    name: 'Errors'
+};
+
+// TLS endpoint groups
+export const tlsCertificateModes: EndpointGroup = {
+    id: 'certificate-modes',
+    name: 'Certificate Modes'
+};
+
+export const tlsProtocolNegotiation: EndpointGroup = {
+    id: 'protocol-negotiation',
+    name: 'Protocol Negotiation',
+    description: 'Endpoints that negotiate specific protocols via ALPN. These can be used together, to simulate a server supporting specific combinations of protocols, in the preference order specified.'
+};
+
+export const tlsVersions: EndpointGroup = {
+    id: 'versions',
+    name: 'TLS Versions',
+    description: 'Endpoints that only accept specific TLS versions. These can be used together, to simulate a server supporting any specific combination of versions.'
+};

src/endpoints/groups.ts

@@ -2,6 +2,9 @@ import { MaybePromise } from '@httptoolkit/util';
 import * as http from 'http';
 import * as http2 from 'http2';
 
+import { EndpointMeta, EndpointGroup } from './groups.js';
+export type { EndpointMeta, EndpointGroup };
+
 export type HttpRequest = http.IncomingMessage | http2.Http2ServerRequest;
 export type HttpResponse = http.ServerResponse | http2.Http2ServerResponse;
 
@@ -19,6 +22,7 @@ export interface HttpEndpoint {
     handle: HttpHandler;
     needsRawData?: boolean;
     getRemainingPath?: (path: string) => string | undefined;
+    meta?: EndpointMeta;
 }
 
 export * from './http/echo.js';

src/endpoints/http-index.ts

@@ -4,4 +4,9 @@ import { buildHttpBinAnythingEndpoint } from '../../httpbin-compat.js';
 export const anything: HttpEndpoint = {
     matchPath: (path) => path === '/anything' || path.startsWith('/anything/'),
     handle: buildHttpBinAnythingEndpoint({}),
+    meta: {
+        path: '/anything',
+        description: 'Returns JSON containing the parsed details of the request, including method, url, headers, args, data, files, form, and origin.',
+        examples: ['/anything', '/anything/subpath']
+    }
 };

src/endpoints/http/anything.ts

@@ -1,5 +1,6 @@
 import { serializeJson } from '../../util.js';
 import { HttpEndpoint, HttpHandler } from '../http-index.js';
+import { httpAuthentication } from '../groups.js';
 
 const matchPath = (path: string) =>
     !!path.match(/^\/basic-auth\/([^\/]+)\/([^\/]+)$/);
@@ -34,5 +35,11 @@ const handle: HttpHandler = (req, res, { path }) => {
 
 export const basicAuth: HttpEndpoint = {
     matchPath,
-    handle
+    handle,
+    meta: {
+        path: '/basic-auth/{username}/{password}',
+        description: 'Challenges with HTTP Basic Auth, expecting the username & password from the URL. Returns 200 with user info on success, 401 if unauthenticated, 403 if wrong credentials.',
+        examples: ['/basic-auth/admin/secret'],
+        group: httpAuthentication
+    }
 };

src/endpoints/http/basic-auth.ts

@@ -2,13 +2,20 @@ import * as Cookie from 'cookie';
 
 import { HttpEndpoint } from '../http-index.js';
 import { serializeJson } from '../../util.js';
+import { httpCookies } from '../groups.js';
 
 export const getCookies: HttpEndpoint = {
     matchPath: (path) => path === '/cookies',
     handle: (req, res) => {
         const cookies = Cookie.parse(req.headers.cookie || '');
         res.writeHead(200, { 'Content-Type': 'application/json' });
         res.end(serializeJson({ cookies }));
+    },
+    meta: {
+        path: '/cookies',
+        description: 'Returns the cookies sent with the request.',
+        examples: ['/cookies'],
+        group: httpCookies
     }
 }
 
@@ -43,6 +50,12 @@ export const setCookies: HttpEndpoint = {
                 ];
             })).flat()
         ] as any).end(); // Any because H2 types don't include string array
+    },
+    meta: {
+        path: '/cookies/set',
+        description: 'Sets cookies via query parameters or path segments, then redirects to /cookies.',
+        examples: ['/cookies/set?name=value', '/cookies/set/name/value'],
+        group: httpCookies
     }
 }
 
@@ -58,5 +71,11 @@ export const deleteCookies: HttpEndpoint = {
                 `${key}=; Expires=Thu, 01-Jan-1970 00:00:00 GMT; Max-Age=0; Path=/`
             ]).flat()
         ] as any).end(); // Any because H2 types don't include string array
+    },
+    meta: {
+        path: '/cookies/delete',
+        description: 'Deletes cookies specified in query parameters, then redirects to /cookies.',
+        examples: ['/cookies/delete?name'],
+        group: httpCookies
     }
 }

src/endpoints/http/cookies.ts

@@ -39,5 +39,10 @@ export const delayEndpoint: HttpEndpoint = {
         return true;
     },
     handle,
-    getRemainingPath
+    getRemainingPath,
+    meta: {
+        path: '/delay/{seconds}',
+        description: 'Delays the response by the specified number of seconds (max 10). Can be chained with other endpoints.',
+        examples: ['/delay/1', '/delay/5', '/delay/2/status/200']
+    }
 };

src/endpoints/http/delay.ts

@@ -162,5 +162,10 @@ async function handle(req: HttpRequest, res: HttpResponse) {
 export const echo: HttpEndpoint = {
     matchPath,
     handle,
-    needsRawData: true
+    needsRawData: true,
+    meta: {
+        path: '/echo',
+        description: 'Echoes back the raw HTTP request data. For HTTP/2, returns parsed frame data as JSON lines.',
+        examples: ['/echo']
+    }
 }

src/endpoints/http/echo.ts

@@ -1,6 +1,7 @@
 import * as zlib from 'node:zlib';
 import { serializeJson } from '../../../util.js';
 import { HttpEndpoint, HttpHandler } from '../../http-index.js';
+import { httpContentEncoding } from '../../groups.js';
 
 // We pre-decode the data. Note that this differs from HTTPBin which returns
 // dynamic data here - for this reason, we use a subdirectory. Dynamic encoding
@@ -24,5 +25,11 @@ const handle: HttpHandler = (req, res) => {
 
 export const brotli: HttpEndpoint = {
     matchPath,
-    handle
+    handle,
+    meta: {
+        path: '/encoding/brotli',
+        description: 'Returns brotli-encoded JSON data.',
+        examples: ['/encoding/brotli'],
+        group: httpContentEncoding
+    }
 };

src/endpoints/http/encoding/brotli.ts

@@ -1,6 +1,7 @@
 import * as zlib from 'node:zlib';
 import { serializeJson } from '../../../util.js';
 import { HttpEndpoint, HttpHandler } from '../../http-index.js';
+import { httpContentEncoding } from '../../groups.js';
 
 // We pre-decode the data. Note that this differs from HTTPBin which returns
 // dynamic data here - for this reason, we use a subdirectory. Dynamic encoding
@@ -24,5 +25,11 @@ const handle: HttpHandler = (req, res) => {
 
 export const deflate: HttpEndpoint = {
     matchPath,
-    handle
+    handle,
+    meta: {
+        path: '/encoding/deflate',
+        description: 'Returns deflate-encoded JSON data.',
+        examples: ['/encoding/deflate'],
+        group: httpContentEncoding
+    }
 };