Extract generic interfaces for API models, separate from OpenAPI

Author: pimterry

src/components/view/http/http-api-card.tsx

@@ -6,7 +6,7 @@ import { styled } from '../../../styles';
 import { Icon } from '../../../icons';
 import { joinAnd } from '../../../util';
 
-import { ApiExchange, Parameter } from '../../../model/api/openapi';
+import { ApiExchange, ApiParameter } from '../../../model/api/api-interfaces';
 
 import {
     CollapsibleCardHeading,
@@ -63,7 +63,7 @@ const UnsetValue = styled.span`
 `;
 
 const ParamMetadata = styled((p: {
-    param: Parameter,
+    param: ApiParameter,
     className?: string
 }) => <div className={p.className}>
         {

src/components/view/http/http-details-pane.tsx

@@ -12,7 +12,7 @@ import { UiStore } from '../../../model/ui-store';
 import { RulesStore } from '../../../model/rules/rules-store';
 import { AccountStore } from '../../../model/account/account-store';
 import { getStatusColor } from '../../../model/events/categorization';
-import { ApiExchange } from '../../../model/api/openapi';
+import { ApiExchange } from '../../../model/api/api-interfaces';
 import { buildRuleFromRequest } from '../../../model/rules/rule-definitions';
 import { WebSocketStream } from '../../../model/websockets/websocket-stream';
 

src/components/view/http/http-response-card.tsx

@@ -6,7 +6,7 @@ import { get } from 'typesafe-get';
 import { HtkResponse, Omit } from '../../../types';
 import { Theme } from '../../../styles';
 
-import { ApiExchange } from '../../../model/api/openapi';
+import { ApiExchange } from '../../../model/api/api-interfaces';
 import { getStatusColor } from '../../../model/events/categorization';
 import { getStatusDocs, getStatusMessage } from '../../../model/http/http-docs';
 

src/model/api/api-interfaces.ts

@@ -0,0 +1,72 @@
+import type * as querystring from 'querystring';
+import type {
+    SchemaObject
+} from 'openapi-directory';
+
+import type {
+    HtkResponse,
+    Html
+} from "../../types";
+import { OpenApiMetadata } from './build-openapi';
+
+export type ApiMetadata =
+    | OpenApiMetadata;
+
+export interface ApiRequestMatcher {
+    pathMatcher: RegExp;
+    queryMatcher: querystring.ParsedUrlQuery;
+}
+
+export interface ApiExchange {
+    readonly service: ApiService;
+    readonly operation: ApiOperation;
+    readonly request: ApiRequest;
+
+    readonly response: ApiResponse | undefined;
+
+    updateWithResponse(response: HtkResponse | 'aborted' | undefined): void;
+
+    matchedOperation(): boolean;
+}
+
+export interface ApiService {
+    readonly name: string;
+    readonly logoUrl?: string;
+    readonly description?: Html;
+    readonly docsUrl?: string;
+}
+
+export interface ApiOperation {
+    readonly name: string;
+    readonly description?: Html;
+    readonly docsUrl?: string;
+
+    readonly warnings: string[];
+}
+
+export interface ApiRequest {
+    parameters: ApiParameter[];
+    bodySchema?: SchemaObject;
+}
+
+export interface ApiParameter {
+    name: string;
+    description?: Html;
+    value?: unknown;
+    defaultValue?: unknown;
+    enum?: unknown[];
+    type?: string;
+    in:
+        | 'cookie'
+        | 'path'
+        | 'header'
+        | 'query';
+    required: boolean;
+    deprecated: boolean;
+    warnings: string[];
+}
+
+export interface ApiResponse {
+    description?: Html;
+    bodySchema?: SchemaObject;
+}

src/model/api/api-store.ts

@@ -10,7 +10,7 @@ import { lazyObservablePromise } from "../../util/observable";
 import { hydrate, persist } from "../../util/mobx-persist/persist";
 
 import { AccountStore } from "../account/account-store";
-import { ApiMetadata } from "./build-openapi";
+import { ApiMetadata } from "./api-interfaces";
 import { buildApiMetadataAsync } from '../../services/ui-worker-api';
 import { findBestMatchingApi } from './openapi';
 import { serializeRegex, serializeMap } from '../serialization';

src/model/api/build-openapi.ts

@@ -4,23 +4,21 @@ import * as querystring from 'querystring';
 import { OpenAPIObject, PathItemObject } from 'openapi-directory';
 import * as Ajv from 'ajv';
 
+import type { ApiRequestMatcher } from './api-interfaces';
 import { openApiSchema } from './openapi-schema';
 import { dereference } from '../../util/json-schema';
 
-interface Path {
-    path: string;
-    pathSpec: PathItemObject;
-}
-
-interface RequestMatcher {
-    pathMatcher: RegExp;
-    queryMatcher: querystring.ParsedUrlQuery;
-}
 
-export interface ApiMetadata {
+export interface OpenApiMetadata {
+    type: 'openapi';
     spec: OpenAPIObject;
     serverMatcher: RegExp;
-    requestMatchers: Map<RequestMatcher, Path>;
+    requestMatchers: Map<ApiRequestMatcher, Path>;
+}
+
+interface Path {
+    path: string;
+    pathSpec: PathItemObject;
 }
 
 const filterSpec = new Ajv({
@@ -40,7 +38,7 @@ function templateStringToRegexString(template: string): string {
 export async function buildApiMetadata(
     spec: OpenAPIObject,
     baseUrlOverrides?: string[]
-): Promise<ApiMetadata> {
+): Promise<OpenApiMetadata> {
     const specId = `${
         spec.info['x-providerName'] || 'unknown'
     }/${
@@ -71,7 +69,7 @@ export async function buildApiMetadata(
     // Build a regex that matches any of these at the start of a URL
     const serverMatcher = new RegExp(`^(${serverUrlRegexSources.join('|')})`, 'i')
 
-    const requestMatchers = new Map<RequestMatcher, Path>();
+    const requestMatchers = new Map<ApiRequestMatcher, Path>();
     _.entries(spec.paths)
         // Sort path & pathspec pairs to ensure that more specific paths are
         // always listed first, so that later on we can always use the first match
@@ -129,6 +127,7 @@ export async function buildApiMetadata(
         });
 
     return {
+        type: 'openapi',
         spec,
         serverMatcher,
         requestMatchers

src/model/api/openapi.ts

@@ -8,8 +8,7 @@ import type {
     ParameterObject,
     ResponseObject,
     RequestBodyObject,
-    SchemaObject,
-    ParameterLocation
+    SchemaObject
 } from 'openapi-directory';
 import * as Ajv from 'ajv';
 
@@ -24,7 +23,15 @@ import { firstMatch, empty, lastHeader } from '../../util';
 import { formatAjvError } from '../../util/json-schema';
 import { reportError } from '../../errors';
 
-import { ApiMetadata } from './build-openapi';
+import {
+    ApiExchange,
+    ApiService,
+    ApiOperation,
+    ApiRequest,
+    ApiResponse,
+    ApiParameter
+} from './api-interfaces';
+import { OpenApiMetadata } from './build-openapi';
 import { fromMarkdown } from '../markdown';
 
 const paramValidator = new Ajv({
@@ -35,7 +42,10 @@ const paramValidator = new Ajv({
 // If we match multiple APIs, build all of them, try to match each one
 // against the request, and return only the matching one. This happens if
 // multiple services have the exact same base request URL (rds.amazonaws.com)
-export function findBestMatchingApi(apis: ApiMetadata[], request: HtkRequest): ApiMetadata | undefined {
+export function findBestMatchingApi(
+    apis: OpenApiMetadata[],
+    request: HtkRequest
+): OpenApiMetadata | undefined {
     const matchingApis = apis.filter((api) => matchOperation(api, request).matched);
 
     // If we've successfully found one matching API, return it
@@ -56,7 +66,7 @@ export function findBestMatchingApi(apis: ApiMetadata[], request: HtkRequest): A
     return _.maxBy(matchingApis, a => a.spec.paths.length)!;
 }
 
-function getPath(api: ApiMetadata, request: HtkRequest): {
+function getPath(api: OpenApiMetadata, request: HtkRequest): {
     pathSpec: PathObject,
     path: string
 } | undefined {
@@ -94,7 +104,7 @@ export function getParameters(
     path: string,
     parameters: ParameterObject[],
     request: HtkRequest
-): Parameter[] {
+): ApiParameter[] {
     if (!parameters) return [];
 
     const query = request.parsedUrl.searchParams;
@@ -270,7 +280,7 @@ export function getBodySchema(
     );
 }
 
-function getDummyPath(api: ApiMetadata, request: HtkRequest): string {
+function getDummyPath(api: OpenApiMetadata, request: HtkRequest): string {
     const { parsedUrl } = request;
     const url = `${parsedUrl.protocol}//${parsedUrl.hostname}${parsedUrl.pathname}`;
     const serverMatch = api.serverMatcher.exec(url);
@@ -292,16 +302,16 @@ function stripTags(input: string | undefined): string | undefined {
     return input.replace(/(<([^>]+)>)/ig, '');
 }
 
-export class ApiExchange {
-    constructor(api: ApiMetadata, exchange: HttpExchange) {
+export class OpenApiExchange implements ApiExchange {
+    constructor(api: OpenApiMetadata, exchange: HttpExchange) {
         const { request } = exchange;
-        this.service = new ApiService(api.spec);
+        this.service = new OpenApiService(api.spec);
 
         this._spec = api.spec;
         this._opSpec = matchOperation(api, request);
 
-        this.operation = new ApiOperation(this._opSpec);
-        this.request = new ApiRequest(api.spec, this._opSpec, request);
+        this.operation = new OpenApiOperation(this._opSpec);
+        this.request = new OpenApiRequest(api.spec, this._opSpec, request);
 
         if (exchange.response) {
             this.updateWithResponse(exchange.response);
@@ -319,22 +329,22 @@ export class ApiExchange {
 
     updateWithResponse(response: HtkResponse | 'aborted' | undefined): void {
         if (response === 'aborted' || response === undefined) return;
-        this.response = new ApiResponse(this._spec, this._opSpec, response);
+        this.response = new OpenApiResponse(this._spec, this._opSpec, response);
     }
 
     matchedOperation() {
         return this._opSpec.matched;
     }
 }
 
-class ApiService {
+class OpenApiService implements ApiService {
     constructor(spec: OpenAPIObject) {
         const { info: service } = spec;
 
         this.name = service.title;
         this.logoUrl = service['x-logo']?.url
         this.description = fromMarkdown(service.description);
-        this.docsUrl = get(spec, 'externalDocs', 'url');
+        this.docsUrl = spec?.externalDocs?.url;
     }
 
     public readonly name: string;
@@ -343,7 +353,7 @@ class ApiService {
     public readonly docsUrl?: string;
 }
 
-function matchOperation(api: ApiMetadata, request: HtkRequest) {
+function matchOperation(api: OpenApiMetadata, request: HtkRequest) {
     const matchingPath = getPath(api, request);
 
     const { pathSpec, path } = matchingPath || {
@@ -368,7 +378,7 @@ function matchOperation(api: ApiMetadata, request: HtkRequest) {
 
 type MatchedOperation = ReturnType<typeof matchOperation>;
 
-class ApiOperation {
+class OpenApiOperation implements ApiOperation {
     constructor(
         op: MatchedOperation
     ) {
@@ -411,7 +421,7 @@ class ApiOperation {
     warnings: string[] = [];
 }
 
-class ApiRequest {
+class OpenApiRequest implements ApiRequest {
     constructor(
         spec: OpenAPIObject,
         op: MatchedOperation,
@@ -430,24 +440,11 @@ class ApiRequest {
         );
     }
 
-    parameters: Parameter[];
+    parameters: ApiParameter[];
     bodySchema?: SchemaObject;
 }
 
-export interface Parameter {
-    name: string;
-    description?: Html;
-    value?: unknown;
-    defaultValue?: unknown;
-    enum?: unknown[];
-    type?: string;
-    in: ParameterLocation;
-    required: boolean;
-    deprecated: boolean;
-    warnings: string[];
-}
-
-class ApiResponse {
+class OpenApiResponse implements ApiResponse {
     constructor(
         spec: OpenAPIObject,
         op: MatchedOperation,

src/model/http/exchange.ts

@@ -31,8 +31,9 @@ import { getContentType } from '../events/content-types';
 import { HTKEventBase } from '../events/event-base';
 
 import { ApiStore } from '../api/api-store';
-import { ApiExchange } from '../api/openapi';
-import { ApiMetadata } from '../api/build-openapi';
+import { ApiExchange } from '../api/api-interfaces';
+import { OpenApiExchange } from '../api/openapi';
+import { ApiMetadata } from '../api/api-interfaces';
 import { decodeBody } from '../../services/ui-worker-api';
 import {
     RequestBreakpoint,
@@ -325,7 +326,7 @@ export class HttpExchange extends HTKEventBase {
 
         if (apiMetadata) {
             try {
-                return new ApiExchange(apiMetadata, this);
+                return new OpenApiExchange(apiMetadata, this);
             } catch (e) {
                 reportError(e);
                 throw e;

src/services/ui-worker-api.ts

@@ -24,7 +24,7 @@ import type {
 import Worker from 'worker-loader!./ui-worker';
 
 import { Omit } from '../types';
-import { ApiMetadata } from '../model/api/build-openapi';
+import { ApiMetadata } from '../model/api/api-interfaces';
 import { WorkerFormatterKey } from './ui-worker-formatters';
 
 const worker = new Worker();

src/services/ui-worker.ts

@@ -13,7 +13,8 @@ import {
     SUPPORTED_ENCODING
 } from 'http-encoding';
 
-import { buildApiMetadata, ApiMetadata } from '../model/api/build-openapi';
+import { ApiMetadata } from '../model/api/api-interfaces';
+import { buildApiMetadata } from '../model/api/build-openapi';
 import { parseCert, ParsedCertificate, validatePKCS12, ValidationResult } from '../model/crypto';
 import { WorkerFormatterKey, formatBuffer } from './ui-worker-formatters';