Document HTTP service (elastic#42331) (elastic#42558)

* improving naming, add TSDoc

* re-genereate docs

* use response name in migration guide

* Apply suggestions from code review

Co-Authored-By: Josh Dover <me@joshdover.com>

* place docs near the related code

* re-generate docs

* mark code as example to reduce noise in http-service.md

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

@@ -0,0 +1,22 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-server](./kibana-plugin-server.md) &gt; [AuthStatus](./kibana-plugin-server.authstatus.md)
+
+## AuthStatus enum
+
+Status indicating an outcome of the authentication.
+
+<b>Signature:</b>
+
+```typescript
+export declare enum AuthStatus 
+```
+
+## Enumeration Members
+
+|  Member | Value | Description |
+|  --- | --- | --- |
+|  authenticated | <code>&quot;authenticated&quot;</code> | <code>auth</code> interceptor successfully authenticated a user |
+|  unauthenticated | <code>&quot;unauthenticated&quot;</code> | <code>auth</code> interceptor failed user authentication |
+|  unknown | <code>&quot;unknown&quot;</code> | <code>auth</code> interceptor has not been registered |
+

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

@@ -0,0 +1,20 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-server](./kibana-plugin-server.md) &gt; [CustomHttpResponseOptions](./kibana-plugin-server.customhttpresponseoptions.md)
+
+## CustomHttpResponseOptions interface
+
+HTTP response parameters for a response with adjustable status code.
+
+<b>Signature:</b>
+
+```typescript
+export interface CustomHttpResponseOptions extends HttpResponseOptions 
+```
+
+## Properties
+
+|  Property | Type | Description |
+|  --- | --- | --- |
+|  [statusCode](./kibana-plugin-server.customhttpresponseoptions.statuscode.md) | <code>number</code> |  |
+

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

@@ -0,0 +1,11 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-server](./kibana-plugin-server.md) &gt; [CustomHttpResponseOptions](./kibana-plugin-server.customhttpresponseoptions.md) &gt; [statusCode](./kibana-plugin-server.customhttpresponseoptions.statuscode.md)
+
+## CustomHttpResponseOptions.statusCode property
+
+<b>Signature:</b>
+
+```typescript
+statusCode: number;
+```

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

@@ -9,5 +9,5 @@ Get headers to authenticate a user against Elasticsearch.
 <b>Signature:</b>
 
 ```typescript
-export declare type GetAuthHeaders = (request: KibanaRequest | Request) => AuthHeaders | undefined;
+export declare type GetAuthHeaders = (request: KibanaRequest | LegacyRequest) => AuthHeaders | undefined;
 ```

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

@@ -0,0 +1,16 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-server](./kibana-plugin-server.md) &gt; [GetAuthState](./kibana-plugin-server.getauthstate.md)
+
+## GetAuthState type
+
+Get authentication state for a request. Returned by `auth` interceptor.
+
+<b>Signature:</b>
+
+```typescript
+export declare type GetAuthState = (request: KibanaRequest | LegacyRequest) => {
+    status: AuthStatus;
+    state: unknown;
+};
+```

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

@@ -4,9 +4,14 @@
 
 ## Headers type
 
+Http request headers to read.
 
 <b>Signature:</b>
 
 ```typescript
-export declare type Headers = Record<string, string | string[] | undefined>;
+export declare type Headers = {
+    [header in KnownHeaders]?: string | string[] | undefined;
+} & {
+    [header: string]: string | string[] | undefined;
+};
 ```

docs/development/core/server/kibana-plugin-server.httpresponseoptions.headers.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; [HttpResponseOptions](./kibana-plugin-server.httpresponseoptions.md) &gt; [headers](./kibana-plugin-server.httpresponseoptions.headers.md)
+
+## HttpResponseOptions.headers property
+
+HTTP Headers with additional information about response
+
+<b>Signature:</b>
+
+```typescript
+headers?: ResponseHeaders;
+```

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

@@ -0,0 +1,20 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-server](./kibana-plugin-server.md) &gt; [HttpResponseOptions](./kibana-plugin-server.httpresponseoptions.md)
+
+## HttpResponseOptions interface
+
+HTTP response parameters
+
+<b>Signature:</b>
+
+```typescript
+export interface HttpResponseOptions 
+```
+
+## Properties
+
+|  Property | Type | Description |
+|  --- | --- | --- |
+|  [headers](./kibana-plugin-server.httpresponseoptions.headers.md) | <code>ResponseHeaders</code> | HTTP Headers with additional information about response |
+

docs/development/core/server/kibana-plugin-server.httpresponsepayload.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; [HttpResponsePayload](./kibana-plugin-server.httpresponsepayload.md)
+
+## HttpResponsePayload type
+
+Data send to the client as a response payload.
+
+<b>Signature:</b>
+
+```typescript
+export declare type HttpResponsePayload = undefined | string | Record<string, any> | Buffer | Stream;
+```

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

@@ -0,0 +1,15 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-server](./kibana-plugin-server.md) &gt; [HttpServerSetup](./kibana-plugin-server.httpserversetup.md) &gt; [auth](./kibana-plugin-server.httpserversetup.auth.md)
+
+## HttpServerSetup.auth property
+
+<b>Signature:</b>
+
+```typescript
+auth: {
+        get: GetAuthState;
+        isAuthenticated: IsAuthenticated;
+        getAuthHeaders: GetAuthHeaders;
+    };
+```

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

@@ -0,0 +1,16 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-server](./kibana-plugin-server.md) &gt; [HttpServerSetup](./kibana-plugin-server.httpserversetup.md) &gt; [basePath](./kibana-plugin-server.httpserversetup.basepath.md)
+
+## HttpServerSetup.basePath property
+
+<b>Signature:</b>
+
+```typescript
+basePath: {
+        get: (request: KibanaRequest | LegacyRequest) => string;
+        set: (request: KibanaRequest | LegacyRequest, basePath: string) => void;
+        prepend: (url: string) => string;
+        remove: (url: string) => string;
+    };
+```

docs/development/core/server/kibana-plugin-server.httpserversetup.createcookiesessionstoragefactory.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; [HttpServerSetup](./kibana-plugin-server.httpserversetup.md) &gt; [createCookieSessionStorageFactory](./kibana-plugin-server.httpserversetup.createcookiesessionstoragefactory.md)
+
+## HttpServerSetup.createCookieSessionStorageFactory property
+
+Creates cookie based session storage factory [SessionStorageFactory](./kibana-plugin-server.sessionstoragefactory.md)
+
+<b>Signature:</b>
+
+```typescript
+createCookieSessionStorageFactory: <T>(cookieOptions: SessionStorageCookieOptions<T>) => Promise<SessionStorageFactory<T>>;
+```

docs/development/core/server/kibana-plugin-server.httpserversetup.istlsenabled.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; [HttpServerSetup](./kibana-plugin-server.httpserversetup.md) &gt; [isTlsEnabled](./kibana-plugin-server.httpserversetup.istlsenabled.md)
+
+## HttpServerSetup.isTlsEnabled property
+
+Flag showing whether a server was configured to use TLS connection.
+
+<b>Signature:</b>
+
+```typescript
+isTlsEnabled: boolean;
+```

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

@@ -0,0 +1,93 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-server](./kibana-plugin-server.md) &gt; [HttpServerSetup](./kibana-plugin-server.httpserversetup.md)
+
+## HttpServerSetup interface
+
+Kibana HTTP Service provides own abstraction for work with HTTP stack. Plugins don't have direct access to `hapi` server and its primitives anymore. Moreover, plugins shouldn't rely on the fact that HTTP Service uses one or another library under the hood. This gives the platform flexibility to upgrade or changing our internal HTTP stack without breaking plugins. If the HTTP Service lacks functionality you need, we are happy to discuss and support your needs.
+
+<b>Signature:</b>
+
+```typescript
+export interface HttpServerSetup 
+```
+
+## Properties
+
+|  Property | Type | Description |
+|  --- | --- | --- |
+|  [auth](./kibana-plugin-server.httpserversetup.auth.md) | <code>{</code><br/><code>        get: GetAuthState;</code><br/><code>        isAuthenticated: IsAuthenticated;</code><br/><code>        getAuthHeaders: GetAuthHeaders;</code><br/><code>    }</code> |  |
+|  [basePath](./kibana-plugin-server.httpserversetup.basepath.md) | <code>{</code><br/><code>        get: (request: KibanaRequest &#124; LegacyRequest) =&gt; string;</code><br/><code>        set: (request: KibanaRequest &#124; LegacyRequest, basePath: string) =&gt; void;</code><br/><code>        prepend: (url: string) =&gt; string;</code><br/><code>        remove: (url: string) =&gt; string;</code><br/><code>    }</code> |  |
+|  [createCookieSessionStorageFactory](./kibana-plugin-server.httpserversetup.createcookiesessionstoragefactory.md) | <code>&lt;T&gt;(cookieOptions: SessionStorageCookieOptions&lt;T&gt;) =&gt; Promise&lt;SessionStorageFactory&lt;T&gt;&gt;</code> | Creates cookie based session storage factory [SessionStorageFactory](./kibana-plugin-server.sessionstoragefactory.md) |
+|  [isTlsEnabled](./kibana-plugin-server.httpserversetup.istlsenabled.md) | <code>boolean</code> | Flag showing whether a server was configured to use TLS connection. |
+|  [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. |
+|  [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.
+
+```ts
+import { Router } from 'src/core/server';
+const router = new Router('my-app');
+
+```
+- 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`<!-- -->.
+
+```ts
+import { schema, TypeOf } from '@kbn/config-schema';
+const validate = {
+  params: schema.object({
+    id: schema.string(),
+  }),
+};
+
+```
+- Declare a function to respond to incoming request. The function will receive `request` object containing request details: url, headers, matched route, as well as validated `params`<!-- -->, `query`<!-- -->, `body`<!-- -->. And `response` object instructing HTTP server to create HTTP response with information sent back to the client as the response body, headers, and HTTP status. Unlike, `hapi` route handler in the Legacy platform, any exception raised during the handler call will generate `500 Server error` response and log error details for further investigation. See below for returning custom error responses.
+
+```ts
+const handler = async (request: KibanaRequest, response: ResponseFactory) => {
+  const data = await 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 and set response headers
+  return response.ok(data, {
+    headers: {
+      'content-type': 'application/json'
+    }
+  });
+}
+
+```
+- Register route handler for GET request to 'my-app/path/<!-- -->{<!-- -->id<!-- -->}<!-- -->' path
+
+```ts
+import { schema, TypeOf } from '@kbn/config-schema';
+import { Router } from 'src/core/server';
+const router = new Router('my-app');
+
+const validate = {
+  params: schema.object({
+    id: schema.string(),
+  }),
+};
+
+router.get({
+  path: 'path/{id}',
+  validate
+},
+async (request, response) => {
+  const data = await findObject(request.params.id);
+  if (!data) return response.notFound();
+  return response.ok(data, {
+    headers: {
+      'content-type': 'application/json'
+    }
+  });
+});
+
+```
+

docs/development/core/server/kibana-plugin-server.httpserversetup.registerauth.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; [HttpServerSetup](./kibana-plugin-server.httpserversetup.md) &gt; [registerAuth](./kibana-plugin-server.httpserversetup.registerauth.md)
+
+## HttpServerSetup.registerAuth property
+
+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.
+
+<b>Signature:</b>
+
+```typescript
+registerAuth: (handler: AuthenticationHandler) => void;
+```

docs/development/core/server/kibana-plugin-server.httpserversetup.registeronpostauth.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; [HttpServerSetup](./kibana-plugin-server.httpserversetup.md) &gt; [registerOnPostAuth](./kibana-plugin-server.httpserversetup.registeronpostauth.md)
+
+## HttpServerSetup.registerOnPostAuth property
+
+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).
+
+<b>Signature:</b>
+
+```typescript
+registerOnPostAuth: (handler: OnPostAuthHandler) => void;
+```

docs/development/core/server/kibana-plugin-server.httpserversetup.registeronpreauth.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; [HttpServerSetup](./kibana-plugin-server.httpserversetup.md) &gt; [registerOnPreAuth](./kibana-plugin-server.httpserversetup.registeronpreauth.md)
+
+## HttpServerSetup.registerOnPreAuth property
+
+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).
+
+<b>Signature:</b>
+
+```typescript
+registerOnPreAuth: (handler: OnPreAuthHandler) => void;
+```

docs/development/core/server/kibana-plugin-server.httpserversetup.registerrouter.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; [HttpServerSetup](./kibana-plugin-server.httpserversetup.md) &gt; [registerRouter](./kibana-plugin-server.httpserversetup.registerrouter.md)
+
+## HttpServerSetup.registerRouter property
+
+Add all the routes registered with `router` to HTTP server request listeners.
+
+<b>Signature:</b>
+
+```typescript
+registerRouter: (router: Router) => void;
+```

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

@@ -0,0 +1,11 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-server](./kibana-plugin-server.md) &gt; [HttpServerSetup](./kibana-plugin-server.httpserversetup.md) &gt; [server](./kibana-plugin-server.httpserversetup.server.md)
+
+## HttpServerSetup.server property
+
+<b>Signature:</b>
+
+```typescript
+server: Server;
+```

docs/development/core/server/kibana-plugin-server.isauthenticated.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; [IsAuthenticated](./kibana-plugin-server.isauthenticated.md)
+
+## IsAuthenticated type
+
+Return authentication status for a request.
+
+<b>Signature:</b>
+
+```typescript
+export declare type IsAuthenticated = (request: KibanaRequest | LegacyRequest) => boolean;
+```

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

@@ -26,6 +26,6 @@ export declare class KibanaRequest<Params = unknown, Query = unknown, Body = unk
 |  [headers](./kibana-plugin-server.kibanarequest.headers.md) |  | <code>Headers</code> | Readonly copy of incoming request headers. |
 |  [params](./kibana-plugin-server.kibanarequest.params.md) |  | <code>Params</code> |  |
 |  [query](./kibana-plugin-server.kibanarequest.query.md) |  | <code>Query</code> |  |
-|  [route](./kibana-plugin-server.kibanarequest.route.md) |  | <code>RecursiveReadonly&lt;KibanaRequestRoute&gt;</code> |  |
-|  [url](./kibana-plugin-server.kibanarequest.url.md) |  | <code>Url</code> |  |
+|  [route](./kibana-plugin-server.kibanarequest.route.md) |  | <code>RecursiveReadonly&lt;KibanaRequestRoute&gt;</code> | matched route details |
+|  [url](./kibana-plugin-server.kibanarequest.url.md) |  | <code>Url</code> | a WHATWG URL standard object. |
 

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

@@ -4,6 +4,8 @@
 
 ## KibanaRequest.route property
 
+matched route details
+
 <b>Signature:</b>
 
 ```typescript