Reorganize & clarify endpoint groups

Author: pimterry

src/docs-page.ts

@@ -1,5 +1,8 @@
 import { httpEndpoints, wsEndpoints, tlsEndpoints } from './endpoints/endpoint-index.js';
-import { EndpointMeta, EndpointGroup } from './endpoints/groups.js';
+import {
+    EndpointMeta, EndpointGroup,
+    httpGroupOrder, wsGroupOrder, tlsGroupOrder
+} from './endpoints/groups.js';
 
 interface EndpointWithMeta {
     meta?: EndpointMeta;
@@ -19,7 +22,10 @@ function sortEndpoints(endpoints: EndpointMeta[]): EndpointMeta[] {
     return endpoints.sort((a, b) => a.path.localeCompare(b.path));
 }
 
-function groupEndpoints(endpoints: EndpointWithMeta[]): GroupedEndpoints[] {
+function groupEndpoints(
+    endpoints: EndpointWithMeta[],
+    groupOrder: EndpointGroup[]
+): GroupedEndpoints[] {
     const withMeta = endpoints.filter(e => e.meta).map(e => e.meta!);
     const groups = new Map<string, { group: EndpointGroup; endpoints: EndpointMeta[] }>();
 
@@ -43,10 +49,14 @@ function groupEndpoints(endpoints: EndpointWithMeta[]): GroupedEndpoints[] {
         result.push(ungrouped);
     }
 
-    // Add grouped endpoints alphabetically by name, with sorted endpoints within
+    // Add grouped endpoints in the order defined by the groupOrder array
+    const orderIndex = new Map(groupOrder.map((g, i) => [g.id, i]));
     const sortedEntries = [...groups.entries()]
         .filter(([k]) => k !== '')
-        .sort((a, b) => a[1].group.name.localeCompare(b[1].group.name));
+        .sort((a, b) =>
+            (orderIndex.get(a[1].group.id) ?? Infinity) -
+            (orderIndex.get(b[1].group.id) ?? Infinity)
+        );
 
     for (const [, groupData] of sortedEntries) {
         groupData.endpoints = sortEndpoints(groupData.endpoints);
@@ -480,14 +490,14 @@ export function getDocsHtml(): string {
             id: 'http-endpoints',
             title: 'HTTP Endpoints',
             intro: [],
-            groups: groupEndpoints(httpEndpoints),
+            groups: groupEndpoints(httpEndpoints, httpGroupOrder),
             type: 'http'
         },
         {
             id: 'websocket-endpoints',
             title: 'WebSocket Endpoints',
             intro: ['Connect via <code>wss://{hostname}/ws/...</code>'],
-            groups: groupEndpoints(wsEndpoints),
+            groups: groupEndpoints(wsEndpoints, wsGroupOrder),
             type: 'ws'
         },
         {
@@ -498,7 +508,7 @@ export function getDocsHtml(): string {
                 'Endpoints can be combined using double-dashes, e.g. <code>expired--revoked--http2--tls-v1-2.{domain}</code> will return an expired and revoked certificate, use TLSv1.2, and then negotiate HTTP/2 on the connection.',
                 'These can also be combined with the HTTP or WebSocket handlers above, which can be independently specified in the request path.'
             ],
-            groups: groupEndpoints(tlsEndpoints),
+            groups: groupEndpoints(tlsEndpoints, tlsGroupOrder),
             type: 'tls'
         }
     ];

src/endpoints/groups.ts

@@ -13,9 +13,24 @@ export interface EndpointMeta {
 }
 
 // HTTP endpoint groups
-export const httpContentExamples: EndpointGroup = {
-    id: 'content-examples',
-    name: 'Response Content Formats'
+export const httpRequestInspection: EndpointGroup = {
+    id: 'request-inspection',
+    name: 'Request Inspection'
+};
+
+export const httpCustomResponses: EndpointGroup = {
+    id: 'custom-responses',
+    name: 'Custom Responses'
+};
+
+export const httpRedirects: EndpointGroup = {
+    id: 'redirects',
+    name: 'Redirects'
+};
+
+export const httpCaching: EndpointGroup = {
+    id: 'caching',
+    name: 'Caching'
 };
 
 export const httpAuthentication: EndpointGroup = {
@@ -28,35 +43,44 @@ export const httpCookies: EndpointGroup = {
     name: 'Cookies'
 };
 
-export const httpContentEncoding: EndpointGroup = {
-    id: 'content-encoding',
-    name: 'Response Content Encodings'
+export const httpResponseFormats: EndpointGroup = {
+    id: 'response-formats',
+    name: 'Response Formats'
 };
 
-export const httpErrors: EndpointGroup = {
-    id: 'errors',
-    name: 'Errors'
+export const httpResponseEncoding: EndpointGroup = {
+    id: 'response-encoding',
+    name: 'Response Encoding'
 };
 
-export const httpTlsMetadata: EndpointGroup = {
-    id: 'tls-metadata',
-    name: 'TLS Metadata'
+export const httpDynamicData: EndpointGroup = {
+    id: 'dynamic-data',
+    name: 'Dynamic Data'
 };
 
-export const httpRedirects: EndpointGroup = {
-    id: 'redirects',
-    name: 'Redirects'
+export const httpTlsInspection: EndpointGroup = {
+    id: 'tls-inspection',
+    name: 'TLS Inspection'
 };
 
-export const httpResponseInspection: EndpointGroup = {
-    id: 'response-inspection',
-    name: 'Response Inspection'
+export const httpErrors: EndpointGroup = {
+    id: 'errors',
+    name: 'Errors'
 };
 
-export const httpDynamicData: EndpointGroup = {
-    id: 'dynamic-data',
-    name: 'Dynamic Data'
-};
+export const httpGroupOrder: EndpointGroup[] = [
+    httpRequestInspection,
+    httpCustomResponses,
+    httpRedirects,
+    httpCaching,
+    httpAuthentication,
+    httpCookies,
+    httpResponseFormats,
+    httpResponseEncoding,
+    httpDynamicData,
+    httpTlsInspection,
+    httpErrors
+];
 
 // WebSocket endpoint groups
 export const wsMessaging: EndpointGroup = {
@@ -79,6 +103,13 @@ export const wsErrors: EndpointGroup = {
     name: 'Errors'
 };
 
+export const wsGroupOrder: EndpointGroup[] = [
+    wsMessaging,
+    wsConnection,
+    wsTiming,
+    wsErrors
+];
+
 // TLS endpoint groups
 export const tlsCertificateModes: EndpointGroup = {
     id: 'certificate-modes',
@@ -95,4 +126,10 @@ 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.'
-};
+};
+
+export const tlsGroupOrder: EndpointGroup[] = [
+    tlsCertificateModes,
+    tlsProtocolNegotiation,
+    tlsVersions
+];

src/endpoints/http/anything.ts

@@ -1,4 +1,5 @@
 import { HttpEndpoint } from '../http-index.js';
+import { httpRequestInspection } from '../groups.js';
 import { buildHttpBinAnythingEndpoint } from '../../httpbin-compat.js';
 
 export const anything: HttpEndpoint = {
@@ -7,6 +8,7 @@ export const anything: HttpEndpoint = {
     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']
+        examples: ['/anything', '/anything/subpath'],
+        group: httpRequestInspection
     }
 };

src/endpoints/http/cache.ts

@@ -1,6 +1,6 @@
 import { StatusError } from '@httptoolkit/util';
 import { HttpEndpoint } from '../http-index.js';
-import { httpResponseInspection } from '../groups.js';
+import { httpCaching } from '../groups.js';
 import { buildHttpBinAnythingData } from '../../httpbin-compat.js';
 import { serializeJson } from '../../util.js';
 
@@ -22,7 +22,7 @@ export const cache: HttpEndpoint = {
         path: '/cache',
         description: 'Returns 304 Not Modified if an If-Modified-Since or If-None-Match header is present, otherwise returns the same response as /get.',
         examples: ['/cache'],
-        group: httpResponseInspection
+        group: httpCaching
     }
 };
 
@@ -46,6 +46,6 @@ export const cacheWithAge: HttpEndpoint = {
         path: '/cache/{n}',
         description: 'Sets a Cache-Control header for n seconds, then returns the same response as /get.',
         examples: ['/cache/60'],
-        group: httpResponseInspection
+        group: httpCaching
     }
 };

src/endpoints/http/delay.ts

@@ -1,5 +1,6 @@
 import { delay, StatusError } from '@httptoolkit/util';
 import { HttpEndpoint, HttpHandler } from '../http-index.js';
+import { httpDynamicData } from '../groups.js';
 import { buildHttpBinAnythingEndpoint } from '../../httpbin-compat.js';
 
 const getRemainingPath = (path: string): string | undefined => {
@@ -43,6 +44,7 @@ export const delayEndpoint: HttpEndpoint = {
     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']
+        examples: ['/delay/1', '/delay/5', '/delay/2/status/200'],
+        group: httpDynamicData
     }
 };

src/endpoints/http/deny.ts

@@ -1,5 +1,5 @@
 import { HttpEndpoint } from '../http-index.js';
-import { httpContentExamples } from '../groups.js';
+import { httpResponseFormats } from '../groups.js';
 
 const DENY_TEXT = `
           .-''''''-.
@@ -24,6 +24,6 @@ export const deny: HttpEndpoint = {
         path: '/deny',
         description: 'Returns a page denied by robots.txt.',
         examples: ['/deny'],
-        group: httpContentExamples
+        group: httpResponseFormats
     }
 };

src/endpoints/http/echo.ts

@@ -5,6 +5,7 @@ import {
     HttpRequest,
     HttpResponse
 } from '../http-index.js';
+import { httpRequestInspection } from '../groups.js';
 
 const matchPath = ((path: string) => path === '/echo');
 
@@ -166,6 +167,7 @@ export const echo: HttpEndpoint = {
     meta: {
         path: '/echo',
         description: 'Echoes back the raw HTTP request data. For HTTP/2, returns parsed frame data as JSON lines.',
-        examples: ['/echo']
+        examples: ['/echo'],
+        group: httpRequestInspection
     }
 }

src/endpoints/http/encoding/brotli.ts

@@ -1,7 +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';
+import { httpResponseEncoding } 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
@@ -30,6 +30,6 @@ export const brotli: HttpEndpoint = {
         path: '/encoding/brotli',
         description: 'Returns brotli-encoded JSON data.',
         examples: ['/encoding/brotli'],
-        group: httpContentEncoding
+        group: httpResponseEncoding
     }
 };

src/endpoints/http/encoding/deflate.ts

@@ -1,7 +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';
+import { httpResponseEncoding } 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
@@ -30,6 +30,6 @@ export const deflate: HttpEndpoint = {
         path: '/encoding/deflate',
         description: 'Returns deflate-encoded JSON data.',
         examples: ['/encoding/deflate'],
-        group: httpContentEncoding
+        group: httpResponseEncoding
     }
 };

src/endpoints/http/encoding/gzip.ts

@@ -1,7 +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';
+import { httpResponseEncoding } 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
@@ -30,6 +30,6 @@ export const gzip: HttpEndpoint = {
         path: '/encoding/gzip',
         description: 'Returns gzip-encoded JSON data.',
         examples: ['/encoding/gzip'],
-        group: httpContentEncoding
+        group: httpResponseEncoding
     }
 };