[HTTP] Versioned router implementation

.github/CODEOWNERS

@@ -284,7 +284,8 @@ packages/core/usage-data/core-usage-data-base-server-internal @elastic/kibana-co
 packages/core/usage-data/core-usage-data-server @elastic/kibana-core
 packages/core/usage-data/core-usage-data-server-internal @elastic/kibana-core
 packages/core/usage-data/core-usage-data-server-mocks @elastic/kibana-core
-packages/core/versioning/core-version-http-server @elastic/kibana-core
+packages/core/versioning/core-versioned-http-server @elastic/kibana-core
+packages/core/versioning/core-versioned-http-server-internal @elastic/kibana-core
 x-pack/plugins/cross_cluster_replication @elastic/platform-deployment-management
 packages/kbn-crypto @elastic/kibana-security
 packages/kbn-crypto-browser @elastic/kibana-core

package.json

@@ -329,7 +329,8 @@
     "@kbn/core-usage-data-base-server-internal": "link:packages/core/usage-data/core-usage-data-base-server-internal",
     "@kbn/core-usage-data-server": "link:packages/core/usage-data/core-usage-data-server",
     "@kbn/core-usage-data-server-internal": "link:packages/core/usage-data/core-usage-data-server-internal",
-    "@kbn/core-version-http-server": "link:packages/core/versioning/core-version-http-server",
+    "@kbn/core-versioned-http-server": "link:packages/core/versioning/core-versioned-http-server",
+    "@kbn/core-versioned-http-server-internal": "link:packages/core/versioning/core-versioned-http-server-internal",
     "@kbn/cross-cluster-replication-plugin": "link:x-pack/plugins/cross_cluster_replication",
     "@kbn/crypto": "link:packages/kbn-crypto",
     "@kbn/crypto-browser": "link:packages/kbn-crypto-browser",

packages/core/http/core-http-router-server-internal/index.ts

@@ -17,3 +17,4 @@ export {
   isKibanaResponse,
   KibanaResponse,
 } from './src/response';
+export { RouteValidator } from './src/validator';

packages/core/http/core-http-router-server-internal/src/request.ts

@@ -120,9 +120,9 @@ export class CoreKibanaRequest<
 
   constructor(
     request: RawRequest,
-    public readonly params: Params,
-    public readonly query: Query,
-    public readonly body: Body,
+    public params: Params,
+    public query: Query,
+    public body: Body,
     // @ts-expect-error we will use this flag as soon as http request proxy is supported in the core
     // until that time we have to expose all the headers
     private readonly withoutSecretHeaders: boolean

packages/core/versioning/core-versioned-http-server-internal/README.md

@@ -0,0 +1,7 @@
+# @kbn/core-versioned-http-server-internal
+
+This package contains the implementation for sever-side HTTP versioning.
+
+## Experimental
+
+See notes in `@kbn/core-versioned-http-server`

packages/core/versioning/core-version-http-server/index.ts → packages/core/versioning/core-versioned-http-server-internal/index.ts

@@ -6,5 +6,4 @@
  * Side Public License, v 1.
  */
 
-// TODO: export once types are ready
-export {};
+export { InternalVersionedRouter } from './src';

packages/core/versioning/core-versioned-http-server-internal/jest.config.js

@@ -0,0 +1,13 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+module.exports = {
+  preset: '@kbn/test/jest_node',
+  rootDir: '../../../..',
+  roots: ['<rootDir>/packages/core/versioning/core-versioned-http-server-internal'],
+};

packages/core/versioning/core-versioned-http-server-internal/kibana.jsonc

@@ -0,0 +1,5 @@
+{
+  "type": "shared-common",
+  "id": "@kbn/core-versioned-http-server-internal",
+  "owner": "@elastic/kibana-core"
+}

packages/core/versioning/core-versioned-http-server-internal/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "@kbn/core-versioned-http-server-internal",
+  "private": true,
+  "version": "1.0.0",
+  "author": "Kibana Core",
+  "license": "SSPL-1.0 OR Elastic License 2.0"
+}

packages/core/versioning/core-versioned-http-server-internal/src/index.ts

@@ -0,0 +1,9 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+export { InternalVersionedRouter } from './internal_versioned_router';

packages/core/versioning/core-versioned-http-server-internal/src/internal_versioned_route.test.ts

@@ -0,0 +1,117 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+import { schema } from '@kbn/config-schema';
+import type { IRouter, RequestHandler } from '@kbn/core-http-server';
+import { httpServiceMock } from '@kbn/core-http-server-mocks';
+import { VERSION_HEADER } from './internal_versioned_route';
+import { InternalVersionedRouter } from '.';
+import { kibanaResponseFactory } from '@kbn/core-http-router-server-internal';
+
+describe('Versioned route', () => {
+  let router: IRouter;
+  const handlerFn: RequestHandler = async (ctx, req, res) => res.ok({ body: { foo: 1 } });
+  beforeEach(() => {
+    router = httpServiceMock.createRouter();
+  });
+
+  it('can register multiple handlers', () => {
+    const versionedRouter = InternalVersionedRouter.from({ router });
+    versionedRouter
+      .get({ path: '/test/{id}', access: 'internal' })
+      .addVersion({ version: '1', validate: false }, handlerFn)
+      .addVersion({ version: '2', validate: false }, handlerFn)
+      .addVersion({ version: '3', validate: false }, handlerFn);
+    const routes = versionedRouter.getRoutes();
+    expect(routes).toHaveLength(1);
+    const [route] = routes;
+    expect(route.handlers).toHaveLength(3);
+    // We only register one route with the underlying router
+    expect(router.get).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not allow specifying a handler for the same version more than once', () => {
+    const versionedRouter = InternalVersionedRouter.from({ router });
+    expect(() =>
+      versionedRouter
+        .get({ path: '/test/{id}', access: 'internal' })
+        .addVersion({ version: '1', validate: false }, handlerFn)
+        .addVersion({ version: '1', validate: false }, handlerFn)
+        .addVersion({ version: '3', validate: false }, handlerFn)
+    ).toThrowError(`Version 1 handler has already been registered for the route "get /test/{id}"`);
+  });
+
+  it('runs input validations', async () => {
+    let handler: RequestHandler;
+
+    let validatedBody = false;
+    let validatedParams = false;
+    let validatedQuery = false;
+    let validatedOutputBody = false;
+
+    (router.post as jest.Mock).mockImplementation((opts: unknown, fn) => (handler = fn));
+    const versionedRouter = InternalVersionedRouter.from({ router });
+    versionedRouter.post({ path: '/test/{id}', access: 'internal' }).addVersion(
+      {
+        version: '1',
+        validate: {
+          request: {
+            body: schema.object({
+              foo: schema.number({
+                validate: () => {
+                  validatedBody = true;
+                },
+              }),
+            }),
+            params: schema.object({
+              foo: schema.number({
+                validate: () => {
+                  validatedParams = true;
+                },
+              }),
+            }),
+            query: schema.object({
+              foo: schema.number({
+                validate: () => {
+                  validatedQuery = true;
+                },
+              }),
+            }),
+          },
+          response: {
+            body: schema.object({
+              foo: schema.number({
+                validate: () => {
+                  validatedOutputBody = true;
+                },
+              }),
+            }),
+          },
+        },
+      },
+      handlerFn
+    );
+
+    const kibanaResponse = await handler!(
+      {} as any,
+      {
+        headers: { [VERSION_HEADER]: '1' },
+        body: { foo: 1 },
+        params: { foo: 1 },
+        query: { foo: 1 },
+      } as any,
+      kibanaResponseFactory
+    );
+
+    expect(kibanaResponse.status).toBe(200);
+    expect(validatedBody).toBe(true);
+    expect(validatedParams).toBe(true);
+    expect(validatedQuery).toBe(true);
+    expect(validatedOutputBody).toBe(true);
+  });
+});

packages/core/versioning/core-versioned-http-server-internal/src/internal_versioned_route.ts

@@ -0,0 +1,164 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+import { schema } from '@kbn/config-schema';
+import type {
+  RequestHandler,
+  IRouter,
+  RequestHandlerContextBase,
+  KibanaRequest,
+  KibanaResponseFactory,
+} from '@kbn/core-http-server';
+import type {
+  Version,
+  AddVersionOpts,
+  VersionedRoute,
+  VersionedRouteConfig,
+} from '@kbn/core-versioned-http-server';
+import type { CoreKibanaRequest } from '@kbn/core-http-router-server-internal';
+import type { Method } from './types';
+
+import { validate } from './validate';
+
+type Options = AddVersionOpts<unknown, unknown, unknown, unknown>;
+
+export const VERSION_HEADER = 'TBD';
+
+// This validation is a pass-through so that we can apply our version-specific validation later
+const passThroughValidation = { body: schema.any(), params: schema.any(), query: schema.any() };
+
+export class InternalVersionedRoute implements VersionedRoute {
+  private readonly handlers = new Map<
+    Version,
+    {
+      fn: RequestHandler;
+      options: Options;
+    }
+  >();
+
+  public static from({
+    router,
+    method,
+    path,
+    options,
+  }: {
+    router: IRouter;
+    method: Method;
+    path: string;
+    options: VersionedRouteConfig<Method>;
+  }) {
+    return new InternalVersionedRoute(router, method, path, options);
+  }
+
+  private constructor(
+    private readonly router: IRouter,
+    public readonly method: Method,
+    public readonly path: string,
+    public readonly options: VersionedRouteConfig<Method>,
+    // TODO: Make "true" dev-only
+    private readonly validateResponses: boolean = true
+  ) {}
+
+  /** This is where we must implement the versioned spec once it is available */
+  private requestHandler = async (
+    ctx: RequestHandlerContextBase,
+    req: KibanaRequest,
+    res: KibanaResponseFactory
+  ) => {
+    const version = req.headers[VERSION_HEADER] as undefined | Version;
+    if (!version) {
+      return res.custom({
+        statusCode: 406,
+        body: `Version expected at [${this.method}] [${this.path}]. Please specify a version in the ${VERSION_HEADER} header.`,
+      });
+    }
+
+    const handler = this.handlers.get(version);
+    if (!handler) {
+      return res.custom({
+        statusCode: 406,
+        body: `No ${version} available for ${this.method} ${this.path}. Available versions are: ${[
+          this.handlers.keys(),
+        ].join(',')}`,
+      });
+    }
+
+    const coreKibanaRequest = req as CoreKibanaRequest;
+    if (handler.options.validate && handler.options.validate.request) {
+      try {
+        const { body, params, query } = validate(
+          req,
+          handler.options.validate.request,
+          handler.options.version
+        );
+        coreKibanaRequest.body = body;
+        coreKibanaRequest.params = params;
+        coreKibanaRequest.query = query;
+      } catch (e) {
+        return res.custom({
+          statusCode: 400,
+          body: e.message,
+        });
+      }
+    } else {
+      // Preserve behavior of not passing through unvalidated data
+      coreKibanaRequest.body = {};
+      coreKibanaRequest.params = {};
+      coreKibanaRequest.query = {};
+    }
+
+    const result = await handler.fn(ctx, req, res);
+
+    if (this.validateResponses && handler.options.validate && handler.options.validate.response) {
+      const { response } = handler.options.validate;
+      try {
+        validate(
+          req,
+          { body: response.body, unsafe: { body: response.unsafe } },
+          handler.options.version
+        );
+      } catch (e) {
+        return res.custom({
+          statusCode: 500,
+          body: `Failed output validation: ${e.message}`,
+        });
+      }
+    }
+
+    return result;
+  };
+
+  public addVersion(options: Options, handler: RequestHandler<any, any, any, any>): VersionedRoute {
+    if (this.handlers.has(options.version)) {
+      throw new Error(
+        `Version ${
+          options.version
+        } handler has already been registered for the route "${this.method.toLowerCase()} ${
+          this.path
+        }"`
+      );
+    }
+
+    this.handlers.set(options.version, { fn: handler, options });
+    if (this.handlers.size === 1) {
+      this.router[this.method](
+        {
+          path: this.path,
+          validate: passThroughValidation,
+          options: this.options,
+        },
+        this.requestHandler
+      );
+    }
+    return this;
+  }
+
+  public getHandlers(): Array<{ fn: RequestHandler; options: Options }> {
+    return [...this.handlers.values()];
+  }
+}