Expose createRouter from HttpService, prepare handlers for context in…

…troduction (elastic#42686)

* expose createRouter, prepare route handler for context introduction.

* fix tests

* update examples in docs

* update tests

* re-genereated docs

* remove registerRouter from http service contract

createRouter registers a router under the hood. that reduces API surface
for consumers

* address comments

* update docs

docs/development/core/server/kibana-plugin-server.coresetup.http.md

@@ -14,5 +14,6 @@ http: {
         registerOnPostAuth: HttpServiceSetup['registerOnPostAuth'];
         basePath: HttpServiceSetup['basePath'];
         isTlsEnabled: HttpServiceSetup['isTlsEnabled'];
+        createRouter: () => IRouter;
     };
 ```

docs/development/core/server/kibana-plugin-server.coresetup.md

@@ -18,5 +18,5 @@ export interface CoreSetup
 |  --- | --- | --- |
 |  [context](./kibana-plugin-server.coresetup.context.md) | <code>{</code><br/><code>        createContextContainer: ContextSetup['createContextContainer'];</code><br/><code>    }</code> |  |
 |  [elasticsearch](./kibana-plugin-server.coresetup.elasticsearch.md) | <code>{</code><br/><code>        adminClient$: Observable&lt;ClusterClient&gt;;</code><br/><code>        dataClient$: Observable&lt;ClusterClient&gt;;</code><br/><code>        createClient: (type: string, clientConfig?: Partial&lt;ElasticsearchClientConfig&gt;) =&gt; ClusterClient;</code><br/><code>    }</code> |  |
-|  [http](./kibana-plugin-server.coresetup.http.md) | <code>{</code><br/><code>        createCookieSessionStorageFactory: HttpServiceSetup['createCookieSessionStorageFactory'];</code><br/><code>        registerOnPreAuth: HttpServiceSetup['registerOnPreAuth'];</code><br/><code>        registerAuth: HttpServiceSetup['registerAuth'];</code><br/><code>        registerOnPostAuth: HttpServiceSetup['registerOnPostAuth'];</code><br/><code>        basePath: HttpServiceSetup['basePath'];</code><br/><code>        isTlsEnabled: HttpServiceSetup['isTlsEnabled'];</code><br/><code>    }</code> |  |
+|  [http](./kibana-plugin-server.coresetup.http.md) | <code>{</code><br/><code>        createCookieSessionStorageFactory: HttpServiceSetup['createCookieSessionStorageFactory'];</code><br/><code>        registerOnPreAuth: HttpServiceSetup['registerOnPreAuth'];</code><br/><code>        registerAuth: HttpServiceSetup['registerAuth'];</code><br/><code>        registerOnPostAuth: HttpServiceSetup['registerOnPostAuth'];</code><br/><code>        basePath: HttpServiceSetup['basePath'];</code><br/><code>        isTlsEnabled: HttpServiceSetup['isTlsEnabled'];</code><br/><code>        createRouter: () =&gt; IRouter;</code><br/><code>    }</code> |  |
 

docs/development/core/server/kibana-plugin-server.httpserversetup.md

@@ -23,16 +23,15 @@ export interface HttpServerSetup
 |  [registerAuth](./kibana-plugin-server.httpserversetup.registerauth.md) | <code>(handler: AuthenticationHandler) =&gt; void</code> | To define custom authentication and/or authorization mechanism for incoming requests. A handler should return a state to associate with the incoming request. The state can be retrieved later via http.auth.get(..) Only one AuthenticationHandler can be registered. |
 |  [registerOnPostAuth](./kibana-plugin-server.httpserversetup.registeronpostauth.md) | <code>(handler: OnPostAuthHandler) =&gt; void</code> | To define custom logic to perform for incoming requests. Runs the handler after Auth interceptor did make sure a user has access to the requested resource. The auth state is available at stage via http.auth.get(..) Can register any number of registerOnPreAuth, which are called in sequence (from the first registered to the last). |
 |  [registerOnPreAuth](./kibana-plugin-server.httpserversetup.registeronpreauth.md) | <code>(handler: OnPreAuthHandler) =&gt; void</code> | To define custom logic to perform for incoming requests. Runs the handler before Auth interceptor performs a check that user has access to requested resources, so it's the only place when you can forward a request to another URL right on the server. Can register any number of registerOnPostAuth, which are called in sequence (from the first registered to the last). |
-|  [registerRouter](./kibana-plugin-server.httpserversetup.registerrouter.md) | <code>(router: Router) =&gt; void</code> | Add all the routes registered with <code>router</code> to HTTP server request listeners. |
+|  [registerRouter](./kibana-plugin-server.httpserversetup.registerrouter.md) | <code>(router: IRouter) =&gt; void</code> | Add all the routes registered with <code>router</code> to HTTP server request listeners. |
 |  [server](./kibana-plugin-server.httpserversetup.server.md) | <code>Server</code> |  |
 
 ## Example
 
-To handle an incoming request in your plugin you should: - Create a `Router` instance. Use `plugin-id` as a prefix path segment for your routes.
+To handle an incoming request in your plugin you should: - Create a `Router` instance. Router is already configured to use `plugin-id` to prefix path segment for your routes.
 
 ```ts
-import { Router } from 'src/core/server';
-const router = new Router('my-app');
+const router = httpSetup.createRouter();
 
 ```
 - Use `@kbn/config-schema` package to create a schema to validate the request `params`<!-- -->, `query`<!-- -->, and `body`<!-- -->. Every incoming request will be validated against the created schema. If validation failed, the request is rejected with `400` status and `Bad request` error without calling the route's handler. To opt out of validating the request, specify `false`<!-- -->.
@@ -66,8 +65,7 @@ const handler = async (request: KibanaRequest, response: ResponseFactory) => {
 
 ```ts
 import { schema, TypeOf } from '@kbn/config-schema';
-import { Router } from 'src/core/server';
-const router = new Router('my-app');
+const router = httpSetup.createRouter();
 
 const validate = {
   params: schema.object({
@@ -79,7 +77,7 @@ router.get({
   path: 'path/{id}',
   validate
 },
-async (request, response) => {
+async (context, request, response) => {
   const data = await findObject(request.params.id);
   if (!data) return response.notFound();
   return response.ok(data, {

docs/development/core/server/kibana-plugin-server.httpserversetup.registerrouter.md

@@ -9,5 +9,5 @@ Add all the routes registered with `router` to HTTP server request listeners.
 <b>Signature:</b>
 
 ```typescript
-registerRouter: (router: Router) => void;
+registerRouter: (router: IRouter) => void;
 ```

docs/development/core/server/kibana-plugin-server.httpservicesetup.md

@@ -8,5 +8,7 @@
 <b>Signature:</b>
 
 ```typescript
-export declare type HttpServiceSetup = HttpServerSetup;
+export declare type HttpServiceSetup = Omit<HttpServerSetup, 'registerRouter'> & {
+    createRouter: (path: string) => IRouter;
+};
 ```

docs/development/core/server/kibana-plugin-server.irouter.delete.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-server](./kibana-plugin-server.md) &gt; [IRouter](./kibana-plugin-server.irouter.md) &gt; [delete](./kibana-plugin-server.irouter.delete.md)
+
+## IRouter.delete property
+
+Register a route handler for `DELETE` request.
+
+<b>Signature:</b>
+
+```typescript
+delete: <P extends ObjectType, Q extends ObjectType, B extends ObjectType>(route: RouteConfig<P, Q, B>, handler: RequestHandler<P, Q, B>) => void;
+```

docs/development/core/server/kibana-plugin-server.irouter.get.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-server](./kibana-plugin-server.md) &gt; [IRouter](./kibana-plugin-server.irouter.md) &gt; [get](./kibana-plugin-server.irouter.get.md)
+
+## IRouter.get property
+
+Register a route handler for `GET` request.
+
+<b>Signature:</b>
+
+```typescript
+get: <P extends ObjectType, Q extends ObjectType, B extends ObjectType>(route: RouteConfig<P, Q, B>, handler: RequestHandler<P, Q, B>) => void;
+```

docs/development/core/server/kibana-plugin-server.irouter.md

@@ -0,0 +1,24 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-server](./kibana-plugin-server.md) &gt; [IRouter](./kibana-plugin-server.irouter.md)
+
+## IRouter interface
+
+Registers route handlers for specified resource path and method.
+
+<b>Signature:</b>
+
+```typescript
+export interface IRouter 
+```
+
+## Properties
+
+|  Property | Type | Description |
+|  --- | --- | --- |
+|  [delete](./kibana-plugin-server.irouter.delete.md) | <code>&lt;P extends ObjectType, Q extends ObjectType, B extends ObjectType&gt;(route: RouteConfig&lt;P, Q, B&gt;, handler: RequestHandler&lt;P, Q, B&gt;) =&gt; void</code> | Register a route handler for <code>DELETE</code> request. |
+|  [get](./kibana-plugin-server.irouter.get.md) | <code>&lt;P extends ObjectType, Q extends ObjectType, B extends ObjectType&gt;(route: RouteConfig&lt;P, Q, B&gt;, handler: RequestHandler&lt;P, Q, B&gt;) =&gt; void</code> | Register a route handler for <code>GET</code> request. |
+|  [post](./kibana-plugin-server.irouter.post.md) | <code>&lt;P extends ObjectType, Q extends ObjectType, B extends ObjectType&gt;(route: RouteConfig&lt;P, Q, B&gt;, handler: RequestHandler&lt;P, Q, B&gt;) =&gt; void</code> | Register a route handler for <code>POST</code> request. |
+|  [put](./kibana-plugin-server.irouter.put.md) | <code>&lt;P extends ObjectType, Q extends ObjectType, B extends ObjectType&gt;(route: RouteConfig&lt;P, Q, B&gt;, handler: RequestHandler&lt;P, Q, B&gt;) =&gt; void</code> | Register a route handler for <code>PUT</code> request. |
+|  [routerPath](./kibana-plugin-server.irouter.routerpath.md) | <code>string</code> | Resulted path |
+

docs/development/core/server/kibana-plugin-server.irouter.post.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-server](./kibana-plugin-server.md) &gt; [IRouter](./kibana-plugin-server.irouter.md) &gt; [post](./kibana-plugin-server.irouter.post.md)
+
+## IRouter.post property
+
+Register a route handler for `POST` request.
+
+<b>Signature:</b>
+
+```typescript
+post: <P extends ObjectType, Q extends ObjectType, B extends ObjectType>(route: RouteConfig<P, Q, B>, handler: RequestHandler<P, Q, B>) => void;
+```

docs/development/core/server/kibana-plugin-server.irouter.put.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-server](./kibana-plugin-server.md) &gt; [IRouter](./kibana-plugin-server.irouter.md) &gt; [put](./kibana-plugin-server.irouter.put.md)
+
+## IRouter.put property
+
+Register a route handler for `PUT` request.
+
+<b>Signature:</b>
+
+```typescript
+put: <P extends ObjectType, Q extends ObjectType, B extends ObjectType>(route: RouteConfig<P, Q, B>, handler: RequestHandler<P, Q, B>) => void;
+```

docs/development/core/server/kibana-plugin-server.irouter.routerpath.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-server](./kibana-plugin-server.md) &gt; [IRouter](./kibana-plugin-server.irouter.md) &gt; [routerPath](./kibana-plugin-server.irouter.routerpath.md)
+
+## IRouter.routerPath property
+
+Resulted path
+
+<b>Signature:</b>
+
+```typescript
+routerPath: string;
+```

docs/development/core/server/kibana-plugin-server.md

@@ -19,7 +19,6 @@ The plugin integrates with the core system via lifecycle events: `setup`<!-- -->
 |  [ClusterClient](./kibana-plugin-server.clusterclient.md) | Represents an Elasticsearch cluster API client and allows to call API on behalf of the internal Kibana user and the actual user that is derived from the request headers (via <code>asScoped(...)</code>). |
 |  [ElasticsearchErrorHelpers](./kibana-plugin-server.elasticsearcherrorhelpers.md) | Helpers for working with errors returned from the Elasticsearch service.Since the internal data of errors are subject to change, consumers of the Elasticsearch service should always use these helpers to classify errors instead of checking error internals such as <code>body.error.header[WWW-Authenticate]</code> |
 |  [KibanaRequest](./kibana-plugin-server.kibanarequest.md) | Kibana specific abstraction for an incoming request. |
-|  [Router](./kibana-plugin-server.router.md) | Provides ability to declare a handler function for a particular path and HTTP request method. Each route can have only one handler functions, which is executed when the route is matched. |
 |  [SavedObjectsErrorHelpers](./kibana-plugin-server.savedobjectserrorhelpers.md) |  |
 |  [SavedObjectsSchema](./kibana-plugin-server.savedobjectsschema.md) |  |
 |  [SavedObjectsSerializer](./kibana-plugin-server.savedobjectsserializer.md) |  |
@@ -51,6 +50,7 @@ The plugin integrates with the core system via lifecycle events: `setup`<!-- -->
 |  [HttpServiceStart](./kibana-plugin-server.httpservicestart.md) |  |
 |  [IKibanaSocket](./kibana-plugin-server.ikibanasocket.md) | A tiny abstraction for TCP socket. |
 |  [InternalCoreStart](./kibana-plugin-server.internalcorestart.md) |  |
+|  [IRouter](./kibana-plugin-server.irouter.md) | Registers route handlers for specified resource path and method. |
 |  [KibanaRequestRoute](./kibana-plugin-server.kibanarequestroute.md) | Request specific route information exposed to a handler. |
 |  [LegacyRequest](./kibana-plugin-server.legacyrequest.md) |  |
 |  [Logger](./kibana-plugin-server.logger.md) | Logger exposes all the necessary methods to log any type of information and this is the interface used by the logging consumers including plugins. |

docs/development/core/server/kibana-plugin-server.requesthandler.md

@@ -9,14 +9,14 @@ A function executed when route path matched requested resource path. Request han
 <b>Signature:</b>
 
 ```typescript
-export declare type RequestHandler<P extends ObjectType, Q extends ObjectType, B extends ObjectType> = (request: KibanaRequest<TypeOf<P>, TypeOf<Q>, TypeOf<B>>, response: KibanaResponseFactory) => KibanaResponse<any> | Promise<KibanaResponse<any>>;
+export declare type RequestHandler<P extends ObjectType, Q extends ObjectType, B extends ObjectType> = (context: {}, request: KibanaRequest<TypeOf<P>, TypeOf<Q>, TypeOf<B>>, response: KibanaResponseFactory) => KibanaResponse<any> | Promise<KibanaResponse<any>>;
 ```
 
 ## Example
 
 
 ```ts
-const router = new Router('my-app');
+const router = httpSetup.createRouter();
 // creates a route handler for GET request on 'my-app/path/{id}' path
 router.get(
   {
@@ -29,8 +29,8 @@ router.get(
     },
   },
   // function to execute to create a responses
-  async (request, response) => {
-    const data = await findObject(request.params.id);
+  async (context, request, response) => {
+    const data = await context.findObject(request.params.id);
     // creates a command to respond with 'not found' error
     if (!data) return response.notFound();
     // creates a command to send found data to the client