Add a REST API interface

pimterry · pimterry · commit c6a2dc5aff17 · 2023-06-27T14:25:02.000+01:00
GraphQL will remain supported for now, for backward compat, but should
eventually be phased out. It's been a bit of a pain in lots of ways:
can't easily recognize requests from URL, very inflexible for
forward/backward compat, very hard to support streaming or other
non-trivial flow use cases, painful npm dep trees, etc.
diff --git a/src/api/api-model.ts b/src/api/api-model.ts
@@ -51,7 +51,7 @@ export class ApiModel {
             // convenient to do it up front.
             certificateFingerprint: generateSPKIFingerprint(this.config.https.certContent),
 
-            networkInterfaces: os.networkInterfaces(),
+            networkInterfaces: this.getNetworkInterfaces(),
             systemProxy: await withFallback(() => getSystemProxy(), 2000, undefined),
 
             dnsServers: proxyPort
@@ -70,6 +70,10 @@ export class ApiModel {
         }, 2000, []);
     }
 
+    getNetworkInterfaces() {
+        return os.networkInterfaces();
+    }
+
     getInterceptors(proxyPort?: number) {
         return Promise.all(
             Object.keys(this.interceptors).map((key) => {
@@ -88,7 +92,7 @@ export class ApiModel {
             id: interceptor.id,
             version: interceptor.version,
             metadata: options.metadataType
-                ? this.getInterceptorMetadata(id, options.metadataType)
+                ? await this.getInterceptorMetadata(id, options.metadataType)
                 : undefined,
             isActivable: await withFallback(
                 async () => interceptor.isActivable(),
diff --git a/src/api/api-server.ts b/src/api/api-server.ts
@@ -11,6 +11,7 @@ import { shutdown } from '../shutdown';
 
 import { ApiModel } from './api-model';
 import { exposeGraphQLAPI } from './graphql-api';
+import { exposeRestAPI } from './rest-api';
 
 /**
  * This file contains the core server API, used by the UI to query
@@ -27,6 +28,11 @@ import { exposeGraphQLAPI } from './graphql-api';
  * - Optionally (always set in the HTK app) requires an auth
  *   token with every request, provided by $HTK_SERVER_TOKEN or
  *   --token at startup.
+ *
+ * The API is available in two formats: a simple REST-ish API,
+ * and a GraphQL that exists for backward compatibility. All
+ * future development will happen on the REST API, and the
+ * GraphQL API will eventually be removed.
  */
 
 export class HttpToolkitServerApi extends events.EventEmitter {
@@ -63,10 +69,14 @@ export class HttpToolkitServerApi extends events.EventEmitter {
         }));
 
         this.server.use((req, res, next) => {
-            if (req.method !== 'POST') {
-                // We allow only POST, because that's all we expect for GraphQL queries,
+            if (req.path === '/' && req.method !== 'POST') {
+                // We allow only POST to GQL, because that's all we expect for GraphQL queries,
                 // and this helps derisk some (admittedly unlikely) XSRF possibilities.
                 res.status(405).send('Only POST requests are supported');
+
+                // XSRF is less of a risk elsewhere, as REST GET endpoints don't do dangerous
+                // things. Also we're enforcing Origin headers everywhere so it should be
+                // impossible regardless, but better safe than sorry!
             } else {
                 next();
             }
@@ -99,6 +109,9 @@ export class HttpToolkitServerApi extends events.EventEmitter {
             }
         )
 
+        this.server.use(express.json());
+
+        exposeRestAPI(this.server, apiModel);
         exposeGraphQLAPI(this.server, apiModel);
     }
 
diff --git a/src/api/graphql-api.ts b/src/api/graphql-api.ts
@@ -80,8 +80,7 @@ const buildResolvers = (apiModel: ApiModel) => {
                 'certificateContent',
                 'certificateFingerprint'
             ]),
-            networkInterfaces: async (__: unknown, ___: unknown, context: any) =>
-                (await getConfig(context)).networkInterfaces,
+            networkInterfaces: apiModel.getNetworkInterfaces(),
             systemProxy: async (__: unknown, ___: unknown, context: any) =>
                 (await getConfig(context)).systemProxy,
             dnsServers: async (__: void, { proxyPort }: { proxyPort: number }): Promise<string[]> =>
diff --git a/src/api/rest-api.ts b/src/api/rest-api.ts
@@ -0,0 +1,131 @@
+import type {
+    Application as ExpressApp,
+    NextFunction
+} from 'express';
+import type {
+    Request,
+    Response,
+    RequestHandler,
+    RouteParameters
+} from 'express-serve-static-core';
+import type { ParsedQs } from 'qs';
+
+import { ErrorLike, StatusError } from '../util/error';
+import { ApiModel } from './api-model';
+
+/**
+ * This file exposes the API model via a REST-ish classic HTTP API.
+ * All endpoints take & receive JSON only. Status codes are used
+ * directly to indicate any errors, with any details returned
+ * as JSON in an `error` field.
+ */
+
+export function exposeRestAPI(
+    server: ExpressApp,
+    apiModel: ApiModel
+) {
+    server.get('/version', handleErrors((_req, res) => {
+        res.send({ version: apiModel.getVersion() });
+    }));
+
+    server.post('/update', handleErrors((_req, res) => {
+        apiModel.updateServer();
+        res.send({ success: true });
+    }));
+
+    server.post('/shutdown', handleErrors((_req, res) => {
+        apiModel.shutdownServer();
+        res.send({ success: true });
+    }));
+
+    server.get('/config', handleErrors(async (req, res) => {
+        const proxyPort = getProxyPort(req.query.proxyPort);
+        res.send({ config: await apiModel.getConfig(proxyPort) });
+    }));
+
+    server.get('/config/network-interfaces', handleErrors((_req, res) => {
+        res.send({ networkInterfaces: apiModel.getNetworkInterfaces() });
+    }));
+
+    // Get top-line data on the current interceptor state
+    server.get('/interceptors', handleErrors(async (req, res) => {
+        const proxyPort = getProxyPort(req.query.proxyPort);
+        res.send({ interceptors: await apiModel.getInterceptors(proxyPort) });
+    }));
+
+    // Get full detailed data on a specific interceptor state, i.e. detailed metadata.
+    server.get('/interceptors/:id', handleErrors(async (req, res) => {
+        const interceptorId = req.params.id;
+        const proxyPort = getProxyPort(req.query.proxyPort);
+
+        res.send({
+            interceptors: await apiModel.getInterceptor(interceptorId, {
+                proxyPort: proxyPort,
+                metadataType: 'detailed'
+            })
+        });
+    }));
+
+    server.post('/interceptors/:id/activate/:proxyPort', handleErrors(async (req, res) => {
+        const interceptorId = req.params.id;
+        const proxyPort = parseInt(req.params.proxyPort, 10);
+        if (isNaN(proxyPort)) throw new StatusError(400, `Could not parse required proxy port: ${req.params.proxyPort}`);
+
+        const interceptorOptions = req.body || undefined;
+
+        const result = await apiModel.activateInterceptor(interceptorId, proxyPort, interceptorOptions);
+        res.send({ result });
+    }));
+}
+
+function getProxyPort(stringishInput: any) {
+    // Proxy port is optional everywhere, to make it possible to query data
+    // in parallel (without waiting for Mockttp) for potentially faster setup.
+
+    if (!stringishInput) return undefined;
+
+    const proxyPort = parseInt(stringishInput as string, 10);
+    if (isNaN(proxyPort)) return undefined;
+
+    return proxyPort;
+}
+
+// A wrapper to automatically apply async error handling & responses to an Express handler. Fairly simple logic,
+// very awkward (but not actually very interesting) types.
+function handleErrors<
+    Route extends string,
+    P = RouteParameters<Route>,
+    ResBody = any,
+    ReqBody = any,
+    ReqQuery = ParsedQs,
+    Locals extends Record<string, any> = Record<string, any>,
+>(
+    handler: RequestHandler<P, ResBody, ReqBody, ReqQuery, Locals>
+): RequestHandler<P, ResBody, ReqBody, ReqQuery, Locals> {
+    return (async (req: Request<P, ResBody, ReqBody, ReqQuery, Locals>, res: Response<any, Locals>, next: NextFunction) => {
+        try {
+            return await handler(req, res, next);
+        } catch (e) {
+            const error = e as ErrorLike;
+
+            console.log(`Error handling request to ${req.path}: ${error.message ?? error}`);
+            reportError(error);
+
+            // Use default error handler if response started (kills the connection)
+            if (res.headersSent) return next(error)
+            else {
+                const status = (error.status && error.status >= 400 && error.status < 600)
+                    ? error.status
+                    : 500;
+
+                res.status(status).send({
+                    error: {
+                        code: error.code,
+                        message: error.message,
+                        stack: error.stack
+                    }
+                })
+            }
+        }
+    }) as any;
+}
diff --git a/src/util/error.ts b/src/util/error.ts
@@ -1,8 +1,9 @@
 export type ErrorLike = Partial<Error> & {
     // Various properties we might want to look for on errors:
-    code?: string,
-    cmd?: string,
-    signal?: string
+    code?: string;
+    cmd?: string;
+    signal?: string;
+    status?: number;
 };
 
 // Useful to easily cast and then examine errors that are otherwise 'unknown':
@@ -13,4 +14,25 @@ export function isErrorLike(error: any): error is ErrorLike {
         error.code ||
         error.stack
     )
+}
+
+abstract class CustomErrorBase extends Error {
+    constructor(message?: string) {
+        super(message); // 'Error' breaks prototype chain here
+
+        // This restores the details of the real error subclass:
+        this.name = new.target.name;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+export class StatusError extends CustomErrorBase {
+    constructor(
+        /**
+         * Should be a valid HTTP status code
+         */
+        public readonly status: number,
+        message: string
+    ) {
+        super(message);
+    }
 }
diff --git a/test/integration-test.spec.ts b/test/integration-test.spec.ts
@@ -6,6 +6,7 @@ import * as tmp from 'tmp';
 import decompress from 'decompress';
 import { expect } from 'chai';
 import getGraphQL from 'graphql.js';
+import fetch from 'node-fetch';
 
 import { getRemote } from 'mockttp';
 
@@ -126,7 +127,7 @@ describe('Integration test', function () {
         await mockttp.stop();
     });
 
-    it('exposes the version over HTTP', async () => {
+    it('exposes the version via GraphQL', async () => {
         const graphql = buildGraphql('http://localhost:45457/');
 
         const response = await graphql(`
@@ -138,14 +139,43 @@ describe('Integration test', function () {
         expect(response.version).to.equal(require('../package.json').version);
     });
 
-    it('exposes interceptors over HTTP', async function () {
+    it('exposes the version via REST', async () => {
+        const response = await fetch('http://localhost:45457/version', {
+            headers: { 'origin': 'https://app.httptoolkit.tech' }
+        });
+
+        expect(response.ok).to.equal(true);
+        const responseData = await response.json();
+
+        expect(responseData).to.deep.equal({
+            version: require('../package.json').version
+        });
+    });
+
+    it('exposes the system configuration via REST', async () => {
+        const response = await fetch('http://localhost:45457/config?proxyPort=8000', {
+            headers: { 'origin': 'https://app.httptoolkit.tech' }
+        });
+
+        expect(response.ok).to.equal(true);
+        const responseData = await response.json();
+
+        const { config } = responseData;
+        expect(config.certificatePath).not.to.equal(undefined);
+        expect(config.certificateContent).not.to.equal(undefined);
+        expect(config.certificateFingerprint).not.to.equal(undefined);
+        expect(Object.keys(config.networkInterfaces).length).to.be.greaterThan(0);
+        expect(config.ruleParameterKeys).to.deep.equal([]);
+        expect(config.dnsServers.length).to.equal(1);
+    });
+
+    it('exposes interceptors over GraphQL & REST', async function () {
         // Browser detection on a fresh machine (i.e. in CI) with many browsers
         // installed can take a couple of seconds. Give it one retry.
         this.retries(1);
 
         const graphql = buildGraphql('http://localhost:45457/');
-
-        const response = await graphql(`
+        const gqlResponse = await graphql(`
             query getInterceptors($proxyPort: Int!) {
                 interceptors {
                     id
@@ -156,6 +186,17 @@ describe('Integration test', function () {
             }
         `)({ proxyPort: 8000 });
 
+        const restResponse = await (await fetch('http://localhost:45457/interceptors?proxyPort=8000', {
+            headers: { 'origin': 'https://app.httptoolkit.tech' }
+        })).json();
+
+        // We drop metadata - much harder to assert against.
+        restResponse.interceptors.forEach((interceptor: any) => {
+            delete interceptor.metadata;
+        });
+
+        expect(gqlResponse).to.deep.equal(restResponse);
+
         const activable = (id: string, version = '1.0.0') => ({
             id,
             version,
@@ -170,7 +211,7 @@ describe('Integration test', function () {
             "isActive": false
         });
 
-        expect(response.interceptors).to.deep.equal([
+        expect(restResponse.interceptors).to.deep.equal([
             activable('fresh-chrome'),
             activable('existing-chrome'),
             inactivable('fresh-chrome-beta'),
@@ -193,4 +234,36 @@ describe('Integration test', function () {
             activable('docker-attach')
         ]);
     });
+
+    it("allows activating interceptors via REST API", async () => {
+        const response = await fetch('http://localhost:45457/interceptors/existing-terminal/activate/8000', {
+            method: 'POST',
+            headers: { 'origin': 'https://app.httptoolkit.tech' }
+        });
+
+        expect(response.ok).to.equal(true);
+        const responseData = await response.json();
+        expect(responseData).to.deep.equal({
+            "result": {
+                "metadata": {
+                    "commands": {
+                        "Bash": {
+                            "command": "eval \"$(curl -sS localhost:8001/setup)\"",
+                            "description": "Bash-compatible"
+                        },
+                        "Fish": {
+                            "command": "curl -sS localhost:8001/fish-setup | source",
+                            "description": "Fish"
+                        },
+                        "Powershell": {
+                            "command": "Invoke-Expression (Invoke-WebRequest http://localhost:8001/ps-setup).Content",
+                            "description": "Powershell"
+                        }
+                    },
+                    "port": 8001
+                },
+                "success": true
+            }
+        });
+    });
 });
