"authenticated" | auth interceptor successfully authenticated a user |
+| unauthenticated | "unauthenticated" | auth interceptor failed user authentication |
+| unknown | "unknown" | auth interceptor has not been registered |
+
diff --git a/docs/development/core/server/kibana-plugin-server.customhttpresponseoptions.md b/docs/development/core/server/kibana-plugin-server.customhttpresponseoptions.md
new file mode 100644
index 00000000000000..cabee8a47e5ca0
--- /dev/null
+++ b/docs/development/core/server/kibana-plugin-server.customhttpresponseoptions.md
@@ -0,0 +1,20 @@
+
+
+[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [CustomHttpResponseOptions](./kibana-plugin-server.customhttpresponseoptions.md)
+
+## CustomHttpResponseOptions interface
+
+HTTP response parameters for a response with adjustable status code.
+
+Signature:
+
+```typescript
+export interface CustomHttpResponseOptions extends HttpResponseOptions
+```
+
+## Properties
+
+| Property | Type | Description |
+| --- | --- | --- |
+| [statusCode](./kibana-plugin-server.customhttpresponseoptions.statuscode.md) | number | |
+
diff --git a/docs/development/core/server/kibana-plugin-server.customhttpresponseoptions.statuscode.md b/docs/development/core/server/kibana-plugin-server.customhttpresponseoptions.statuscode.md
new file mode 100644
index 00000000000000..5444ccd2ebb554
--- /dev/null
+++ b/docs/development/core/server/kibana-plugin-server.customhttpresponseoptions.statuscode.md
@@ -0,0 +1,11 @@
+
+
+[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [CustomHttpResponseOptions](./kibana-plugin-server.customhttpresponseoptions.md) > [statusCode](./kibana-plugin-server.customhttpresponseoptions.statuscode.md)
+
+## CustomHttpResponseOptions.statusCode property
+
+Signature:
+
+```typescript
+statusCode: number;
+```
diff --git a/docs/development/core/server/kibana-plugin-server.getauthheaders.md b/docs/development/core/server/kibana-plugin-server.getauthheaders.md
index ee7572615fe1a9..fba8b8ca8ee3a4 100644
--- a/docs/development/core/server/kibana-plugin-server.getauthheaders.md
+++ b/docs/development/core/server/kibana-plugin-server.getauthheaders.md
@@ -9,5 +9,5 @@ Get headers to authenticate a user against Elasticsearch.
Signature:
```typescript
-export declare type GetAuthHeaders = (request: KibanaRequest | Request) => AuthHeaders | undefined;
+export declare type GetAuthHeaders = (request: KibanaRequest | LegacyRequest) => AuthHeaders | undefined;
```
diff --git a/docs/development/core/server/kibana-plugin-server.getauthstate.md b/docs/development/core/server/kibana-plugin-server.getauthstate.md
new file mode 100644
index 00000000000000..47fc38c28f5e0a
--- /dev/null
+++ b/docs/development/core/server/kibana-plugin-server.getauthstate.md
@@ -0,0 +1,16 @@
+
+
+[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [GetAuthState](./kibana-plugin-server.getauthstate.md)
+
+## GetAuthState type
+
+Get authentication state for a request. Returned by `auth` interceptor.
+
+Signature:
+
+```typescript
+export declare type GetAuthState = (request: KibanaRequest | LegacyRequest) => {
+ status: AuthStatus;
+ state: unknown;
+};
+```
diff --git a/docs/development/core/server/kibana-plugin-server.headers.md b/docs/development/core/server/kibana-plugin-server.headers.md
index 83259efe8b79d5..cd73d4de43b9db 100644
--- a/docs/development/core/server/kibana-plugin-server.headers.md
+++ b/docs/development/core/server/kibana-plugin-server.headers.md
@@ -4,9 +4,14 @@
## Headers type
+Http request headers to read.
Signature:
```typescript
-export declare type Headers = RecordResponseHeaders | HTTP Headers with additional information about response |
+
diff --git a/docs/development/core/server/kibana-plugin-server.httpresponsepayload.md b/docs/development/core/server/kibana-plugin-server.httpresponsepayload.md
new file mode 100644
index 00000000000000..3dc4e2c7956f75
--- /dev/null
+++ b/docs/development/core/server/kibana-plugin-server.httpresponsepayload.md
@@ -0,0 +1,13 @@
+
+
+[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [HttpResponsePayload](./kibana-plugin-server.httpresponsepayload.md)
+
+## HttpResponsePayload type
+
+Data send to the client as a response payload.
+
+Signature:
+
+```typescript
+export declare type HttpResponsePayload = undefined | string | Record{ get: GetAuthState; isAuthenticated: IsAuthenticated; getAuthHeaders: GetAuthHeaders; } | |
+| [basePath](./kibana-plugin-server.httpserversetup.basepath.md) | { get: (request: KibanaRequest | LegacyRequest) => string; set: (request: KibanaRequest | LegacyRequest, basePath: string) => void; prepend: (url: string) => string; remove: (url: string) => string; } | |
+| [createCookieSessionStorageFactory](./kibana-plugin-server.httpserversetup.createcookiesessionstoragefactory.md) | <T>(cookieOptions: SessionStorageCookieOptions<T>) => Promise<SessionStorageFactory<T>> | Creates cookie based session storage factory [SessionStorageFactory](./kibana-plugin-server.sessionstoragefactory.md) |
+| [isTlsEnabled](./kibana-plugin-server.httpserversetup.istlsenabled.md) | boolean | Flag showing whether a server was configured to use TLS connection. |
+| [registerAuth](./kibana-plugin-server.httpserversetup.registerauth.md) | (handler: AuthenticationHandler) => void | 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) | (handler: OnPostAuthHandler) => void | 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) | (handler: OnPreAuthHandler) => void | 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) | (router: Router) => void | Add all the routes registered with router to HTTP server request listeners. |
+| [server](./kibana-plugin-server.httpserversetup.server.md) | Server | |
+
+## 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'
+ }
+ });
+});
+
+```
+
diff --git a/docs/development/core/server/kibana-plugin-server.httpserversetup.registerauth.md b/docs/development/core/server/kibana-plugin-server.httpserversetup.registerauth.md
new file mode 100644
index 00000000000000..6e63e0996a63a9
--- /dev/null
+++ b/docs/development/core/server/kibana-plugin-server.httpserversetup.registerauth.md
@@ -0,0 +1,13 @@
+
+
+[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [HttpServerSetup](./kibana-plugin-server.httpserversetup.md) > [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.
+
+Signature:
+
+```typescript
+registerAuth: (handler: AuthenticationHandler) => void;
+```
diff --git a/docs/development/core/server/kibana-plugin-server.httpserversetup.registeronpostauth.md b/docs/development/core/server/kibana-plugin-server.httpserversetup.registeronpostauth.md
new file mode 100644
index 00000000000000..c74a67da350ecc
--- /dev/null
+++ b/docs/development/core/server/kibana-plugin-server.httpserversetup.registeronpostauth.md
@@ -0,0 +1,13 @@
+
+
+[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [HttpServerSetup](./kibana-plugin-server.httpserversetup.md) > [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).
+
+Signature:
+
+```typescript
+registerOnPostAuth: (handler: OnPostAuthHandler) => void;
+```
diff --git a/docs/development/core/server/kibana-plugin-server.httpserversetup.registeronpreauth.md b/docs/development/core/server/kibana-plugin-server.httpserversetup.registeronpreauth.md
new file mode 100644
index 00000000000000..f6efa1c1dd73c4
--- /dev/null
+++ b/docs/development/core/server/kibana-plugin-server.httpserversetup.registeronpreauth.md
@@ -0,0 +1,13 @@
+
+
+[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [HttpServerSetup](./kibana-plugin-server.httpserversetup.md) > [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).
+
+Signature:
+
+```typescript
+registerOnPreAuth: (handler: OnPreAuthHandler) => void;
+```
diff --git a/docs/development/core/server/kibana-plugin-server.httpserversetup.registerrouter.md b/docs/development/core/server/kibana-plugin-server.httpserversetup.registerrouter.md
new file mode 100644
index 00000000000000..4c2a9ae3274068
--- /dev/null
+++ b/docs/development/core/server/kibana-plugin-server.httpserversetup.registerrouter.md
@@ -0,0 +1,13 @@
+
+
+[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [HttpServerSetup](./kibana-plugin-server.httpserversetup.md) > [registerRouter](./kibana-plugin-server.httpserversetup.registerrouter.md)
+
+## HttpServerSetup.registerRouter property
+
+Add all the routes registered with `router` to HTTP server request listeners.
+
+Signature:
+
+```typescript
+registerRouter: (router: Router) => void;
+```
diff --git a/docs/development/core/server/kibana-plugin-server.httpserversetup.server.md b/docs/development/core/server/kibana-plugin-server.httpserversetup.server.md
new file mode 100644
index 00000000000000..a137eba7c8a5a7
--- /dev/null
+++ b/docs/development/core/server/kibana-plugin-server.httpserversetup.server.md
@@ -0,0 +1,11 @@
+
+
+[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [HttpServerSetup](./kibana-plugin-server.httpserversetup.md) > [server](./kibana-plugin-server.httpserversetup.server.md)
+
+## HttpServerSetup.server property
+
+Signature:
+
+```typescript
+server: Server;
+```
diff --git a/docs/development/core/server/kibana-plugin-server.isauthenticated.md b/docs/development/core/server/kibana-plugin-server.isauthenticated.md
new file mode 100644
index 00000000000000..15f412710412a2
--- /dev/null
+++ b/docs/development/core/server/kibana-plugin-server.isauthenticated.md
@@ -0,0 +1,13 @@
+
+
+[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [IsAuthenticated](./kibana-plugin-server.isauthenticated.md)
+
+## IsAuthenticated type
+
+Return authentication status for a request.
+
+Signature:
+
+```typescript
+export declare type IsAuthenticated = (request: KibanaRequest | LegacyRequest) => boolean;
+```
diff --git a/docs/development/core/server/kibana-plugin-server.kibanarequest.md b/docs/development/core/server/kibana-plugin-server.kibanarequest.md
index a9622e4319d573..19167f2f640418 100644
--- a/docs/development/core/server/kibana-plugin-server.kibanarequest.md
+++ b/docs/development/core/server/kibana-plugin-server.kibanarequest.md
@@ -26,6 +26,6 @@ export declare class KibanaRequestParams | |
| [query](./kibana-plugin-server.kibanarequest.query.md) | | Query | |
-| [route](./kibana-plugin-server.kibanarequest.route.md) | | RecursiveReadonly<KibanaRequestRoute> | |
-| [url](./kibana-plugin-server.kibanarequest.url.md) | | Url | |
+| [route](./kibana-plugin-server.kibanarequest.route.md) | | RecursiveReadonly<KibanaRequestRoute> | matched route details |
+| [url](./kibana-plugin-server.kibanarequest.url.md) | | Url | a WHATWG URL standard object. |
diff --git a/docs/development/core/server/kibana-plugin-server.kibanarequest.route.md b/docs/development/core/server/kibana-plugin-server.kibanarequest.route.md
index 301eeef1b6bb58..88954eedf4cfb5 100644
--- a/docs/development/core/server/kibana-plugin-server.kibanarequest.route.md
+++ b/docs/development/core/server/kibana-plugin-server.kibanarequest.route.md
@@ -4,6 +4,8 @@
## KibanaRequest.route property
+matched route details
+
Signature:
```typescript
diff --git a/docs/development/core/server/kibana-plugin-server.kibanarequest.url.md b/docs/development/core/server/kibana-plugin-server.kibanarequest.url.md
index b8bd46199763ee..62d1f971594764 100644
--- a/docs/development/core/server/kibana-plugin-server.kibanarequest.url.md
+++ b/docs/development/core/server/kibana-plugin-server.kibanarequest.url.md
@@ -4,6 +4,8 @@
## KibanaRequest.url property
+a WHATWG URL standard object.
+
Signature:
```typescript
diff --git a/docs/development/core/server/kibana-plugin-server.kibanaresponsefactory.md b/docs/development/core/server/kibana-plugin-server.kibanaresponsefactory.md
new file mode 100644
index 00000000000000..82832ee9334a53
--- /dev/null
+++ b/docs/development/core/server/kibana-plugin-server.kibanaresponsefactory.md
@@ -0,0 +1,13 @@
+
+
+[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [KibanaResponseFactory](./kibana-plugin-server.kibanaresponsefactory.md)
+
+## KibanaResponseFactory type
+
+Creates an object containing request response payload, HTTP headers, error details, and other data transmitted to the client.
+
+Signature:
+
+```typescript
+export declare type KibanaResponseFactory = typeof kibanaResponseFactory;
+```
diff --git a/docs/development/core/server/kibana-plugin-server.knownheaders.md b/docs/development/core/server/kibana-plugin-server.knownheaders.md
new file mode 100644
index 00000000000000..986794f3aaa61d
--- /dev/null
+++ b/docs/development/core/server/kibana-plugin-server.knownheaders.md
@@ -0,0 +1,13 @@
+
+
+[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [KnownHeaders](./kibana-plugin-server.knownheaders.md)
+
+## KnownHeaders type
+
+Set of well-known HTTP headers.
+
+Signature:
+
+```typescript
+export declare type KnownHeaders = KnownKeysasScoped(...)). |
| [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 body.error.header[WWW-Authenticate] |
| [KibanaRequest](./kibana-plugin-server.kibanarequest.md) | Kibana specific abstraction for an incoming request. |
-| [Router](./kibana-plugin-server.router.md) | |
+| [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) | |
| [ScopedClusterClient](./kibana-plugin-server.scopedclusterclient.md) | Serves the same purpose as "normal" ClusterClient but exposes additional callAsCurrentUser method that doesn't use credentials of the Kibana internal user (as callAsInternalUser does) to request Elasticsearch API, but rather passes HTTP headers extracted from the current user request to the API |
+## Enumerations
+
+| Enumeration | Description |
+| --- | --- |
+| [AuthStatus](./kibana-plugin-server.authstatus.md) | Status indicating an outcome of the authentication. |
+
## Interfaces
| Interface | Description |
@@ -32,13 +38,17 @@ The plugin integrates with the core system via lifecycle events: `setup`
| [CallAPIOptions](./kibana-plugin-server.callapioptions.md) | The set of options that defines how API call should be made and result be processed. |
| [CoreSetup](./kibana-plugin-server.coresetup.md) | Context passed to the plugins setup method. |
| [CoreStart](./kibana-plugin-server.corestart.md) | Context passed to the plugins start method. |
+| [CustomHttpResponseOptions](./kibana-plugin-server.customhttpresponseoptions.md) | HTTP response parameters for a response with adjustable status code. |
| [DiscoveredPlugin](./kibana-plugin-server.discoveredplugin.md) | Small container object used to expose information about discovered plugins that may or may not have been started. |
| [ElasticsearchError](./kibana-plugin-server.elasticsearcherror.md) | |
| [ElasticsearchServiceSetup](./kibana-plugin-server.elasticsearchservicesetup.md) | |
| [FakeRequest](./kibana-plugin-server.fakerequest.md) | Fake request object created manually by Kibana plugins. |
+| [HttpResponseOptions](./kibana-plugin-server.httpresponseoptions.md) | HTTP response parameters |
+| [HttpServerSetup](./kibana-plugin-server.httpserversetup.md) | 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. |
| [HttpServiceStart](./kibana-plugin-server.httpservicestart.md) | |
| [InternalCoreStart](./kibana-plugin-server.internalcorestart.md) | |
| [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. |
| [LoggerFactory](./kibana-plugin-server.loggerfactory.md) | The single purpose of LoggerFactory interface is to define a way to retrieve a context-based logger instance. |
| [LogMeta](./kibana-plugin-server.logmeta.md) | Contextual metadata |
@@ -49,7 +59,8 @@ The plugin integrates with the core system via lifecycle events: `setup`
| [PluginsServiceSetup](./kibana-plugin-server.pluginsservicesetup.md) | |
| [PluginsServiceStart](./kibana-plugin-server.pluginsservicestart.md) | |
| [ResponseErrorMeta](./kibana-plugin-server.responseerrormeta.md) | Additional metadata to enhance error output or provide error details. |
-| [RouteConfigOptions](./kibana-plugin-server.routeconfigoptions.md) | Route specific configuration. |
+| [RouteConfig](./kibana-plugin-server.routeconfig.md) | Route specific configuration. |
+| [RouteConfigOptions](./kibana-plugin-server.routeconfigoptions.md) | Additional route options. |
| [SavedObject](./kibana-plugin-server.savedobject.md) | |
| [SavedObjectAttributes](./kibana-plugin-server.savedobjectattributes.md) | |
| [SavedObjectReference](./kibana-plugin-server.savedobjectreference.md) | A reference to another saved object. |
@@ -78,8 +89,15 @@ The plugin integrates with the core system via lifecycle events: `setup`
| [SavedObjectsUpdateOptions](./kibana-plugin-server.savedobjectsupdateoptions.md) | |
| [SavedObjectsUpdateResponse](./kibana-plugin-server.savedobjectsupdateresponse.md) | |
| [SessionStorage](./kibana-plugin-server.sessionstorage.md) | Provides an interface to store and retrieve data across requests. |
+| [SessionStorageCookieOptions](./kibana-plugin-server.sessionstoragecookieoptions.md) | Configuration used to create HTTP session storage based on top of cookie mechanism. |
| [SessionStorageFactory](./kibana-plugin-server.sessionstoragefactory.md) | SessionStorage factory to bind one to an incoming request |
+## Variables
+
+| Variable | Description |
+| --- | --- |
+| [kibanaResponseFactory](./kibana-plugin-server.kibanaresponsefactory.md) | Set of helpers used to create KibanaResponse to form HTTP response on an incoming request. Should be returned as a result of [RequestHandler](./kibana-plugin-server.requesthandler.md) execution. |
+
## Type Aliases
| Type Alias | Description |
@@ -89,14 +107,20 @@ The plugin integrates with the core system via lifecycle events: `setup`
| [AuthHeaders](./kibana-plugin-server.authheaders.md) | Auth Headers map |
| [ElasticsearchClientConfig](./kibana-plugin-server.elasticsearchclientconfig.md) | |
| [GetAuthHeaders](./kibana-plugin-server.getauthheaders.md) | Get headers to authenticate a user against Elasticsearch. |
-| [Headers](./kibana-plugin-server.headers.md) | |
+| [GetAuthState](./kibana-plugin-server.getauthstate.md) | Get authentication state for a request. Returned by auth interceptor. |
+| [Headers](./kibana-plugin-server.headers.md) | Http request headers to read. |
+| [HttpResponsePayload](./kibana-plugin-server.httpresponsepayload.md) | Data send to the client as a response payload. |
| [HttpServiceSetup](./kibana-plugin-server.httpservicesetup.md) | |
-| [LegacyRequest](./kibana-plugin-server.legacyrequest.md) | Support Legacy platform request for the period of migration. |
+| [IsAuthenticated](./kibana-plugin-server.isauthenticated.md) | Return authentication status for a request. |
+| [KibanaResponseFactory](./kibana-plugin-server.kibanaresponsefactory.md) | Creates an object containing request response payload, HTTP headers, error details, and other data transmitted to the client. |
+| [KnownHeaders](./kibana-plugin-server.knownheaders.md) | Set of well-known HTTP headers. |
| [OnPostAuthHandler](./kibana-plugin-server.onpostauthhandler.md) | |
| [OnPreAuthHandler](./kibana-plugin-server.onpreauthhandler.md) | |
| [PluginInitializer](./kibana-plugin-server.plugininitializer.md) | The plugin export at the root of a plugin's server directory should conform to this interface. |
| [PluginName](./kibana-plugin-server.pluginname.md) | Dedicated type for plugin name/id that is supposed to make Map/Set/Arrays that use it as a key or value more obvious. |
| [RecursiveReadonly](./kibana-plugin-server.recursivereadonly.md) | |
+| [RedirectResponseOptions](./kibana-plugin-server.redirectresponseoptions.md) | HTTP response parameters for redirection response |
+| [RequestHandler](./kibana-plugin-server.requesthandler.md) | A function executed when route path matched requested resource path. Request handler is expected to return a result of one of [KibanaResponseFactory](./kibana-plugin-server.kibanaresponsefactory.md) functions. |
| [ResponseError](./kibana-plugin-server.responseerror.md) | Error message and optional data send to the client in case of error. |
| [RouteMethod](./kibana-plugin-server.routemethod.md) | The set of common HTTP methods supported by Kibana routing. |
| [SavedObjectsClientContract](./kibana-plugin-server.savedobjectsclientcontract.md) | \#\# SavedObjectsClient errorsSince the SavedObjectsClient has its hands in everything we are a little paranoid about the way we present errors back to to application code. Ideally, all errors will be either:1. Caused by bad implementation (ie. undefined is not a function) and as such unpredictable 2. An error that has been classified and decorated appropriately by the decorators in [SavedObjectsErrorHelpers](./kibana-plugin-server.savedobjectserrorhelpers.md)Type 1 errors are inevitable, but since all expected/handle-able errors should be Type 2 the isXYZError() helpers exposed at SavedObjectsErrorHelpers should be used to understand and manage error responses from the SavedObjectsClient.Type 2 errors are decorated versions of the source error, so if the elasticsearch client threw an error it will be decorated based on its type. That means that rather than looking for error.body.error.type or doing substring checks on error.body.error.reason, just use the helpers to understand the meaning of the error:\`\`\`js if (SavedObjectsErrorHelpers.isNotFoundError(error)) { // handle 404 }if (SavedObjectsErrorHelpers.isNotAuthorizedError(error)) { // 401 handling should be automatic, but in case you wanted to know }// always rethrow the error unless you handle it throw error; \`\`\`\#\#\# 404s from missing indexFrom the perspective of application code and APIs the SavedObjectsClient is a black box that persists objects. One of the internal details that users have no control over is that we use an elasticsearch index for persistance and that index might be missing.At the time of writing we are in the process of transitioning away from the operating assumption that the SavedObjects index is always available. Part of this transition is handling errors resulting from an index missing. These used to trigger a 500 error in most cases, and in others cause 404s with different error messages.From my (Spencer) perspective, a 404 from the SavedObjectsApi is a 404; The object the request/call was targeting could not be found. This is why \#14141 takes special care to ensure that 404 errors are generic and don't distinguish between index missing or document missing.\#\#\# 503s from missing indexUnlike all other methods, create requests are supposed to succeed even when the Kibana index does not exist because it will be automatically created by elasticsearch. When that is not the case it is because Elasticsearch's action.auto_create_index setting prevents it from being created automatically so we throw a special 503 with the intention of informing the user that their Elasticsearch settings need to be updated.See [SavedObjectsErrorHelpers](./kibana-plugin-server.savedobjectserrorhelpers.md) |
diff --git a/docs/development/core/server/kibana-plugin-server.redirectresponseoptions.md b/docs/development/core/server/kibana-plugin-server.redirectresponseoptions.md
new file mode 100644
index 00000000000000..6fb0a5add2fb65
--- /dev/null
+++ b/docs/development/core/server/kibana-plugin-server.redirectresponseoptions.md
@@ -0,0 +1,17 @@
+
+
+[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [RedirectResponseOptions](./kibana-plugin-server.redirectresponseoptions.md)
+
+## RedirectResponseOptions type
+
+HTTP response parameters for redirection response
+
+Signature:
+
+```typescript
+export declare type RedirectResponseOptions = HttpResponseOptions & {
+ headers: {
+ location: string;
+ };
+};
+```
diff --git a/docs/development/core/server/kibana-plugin-server.requesthandler.md b/docs/development/core/server/kibana-plugin-server.requesthandler.md
new file mode 100644
index 00000000000000..b7e593c30f2f3c
--- /dev/null
+++ b/docs/development/core/server/kibana-plugin-server.requesthandler.md
@@ -0,0 +1,42 @@
+
+
+[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [RequestHandler](./kibana-plugin-server.requesthandler.md)
+
+## RequestHandler type
+
+A function executed when route path matched requested resource path. Request handler is expected to return a result of one of [KibanaResponseFactory](./kibana-plugin-server.kibanaresponsefactory.md) functions.
+
+Signature:
+
+```typescript
+export declare type RequestHandler = (request: KibanaRequest
+```
+
+## Properties
+
+| Property | Type | Description |
+| --- | --- | --- |
+| [options](./kibana-plugin-server.routeconfig.options.md) | (
req: Request,
@@ -68,6 +74,7 @@ export class KibanaRequest (
req: Request,
@@ -102,8 +109,9 @@ export class KibanaRequest {
/**
* The endpoint _within_ the router path to register the route. E.g. if the
* router is registered at `/elasticsearch` and the route path is `/search`,
* the full path for the route is `/elasticsearch/search`.
+ * Supports:
+ * - named path segments `path/{name}`.
+ * - optional path segments `path/{position?}`.
+ * - multi-segments `path/{coordinates*2}`.
+ * Segments are accessible within a handler function as `params` property of {@link KibanaRequest} object.
+ * To have read access to `params` you *must* specify validation schema with {@link RouteConfig.validate}.
*/
path: string;
/**
* A schema created with `@kbn/config-schema` that every request will be validated against.
- *
+ * You *must* specify a validation schema to be able to read:
+ * - url path segments
+ * - request query
+ * - request body
* To opt out of validating the request, specify `false`.
+ * @example
+ * ```ts
+ * import { schema } from '@kbn/config-schema';
+ * router.get({
+ * path: 'path/{id}'
+ * validate: {
+ * params: schema.object({
+ * id: schema.string(),
+ * }),
+ * query: schema.object({...}),
+ * body: schema.object({...}),
+ * },
+ * })
+ * ```
*/
validate: RouteSchemas {
params?: P;
diff --git a/src/core/server/http/router/router.ts b/src/core/server/http/router/router.ts
index b801aa41754faa..a4d4b62e40203b 100644
--- a/src/core/server/http/router/router.ts
+++ b/src/core/server/http/router/router.ts
@@ -22,25 +22,41 @@ import { Request, ResponseObject, ResponseToolkit } from 'hapi';
import { Logger } from '../../logging';
import { KibanaRequest } from './request';
-import { KibanaResponse, ResponseFactory, responseFactory } from './response';
+import { KibanaResponse, KibanaResponseFactory, kibanaResponseFactory } from './response';
import { RouteConfig, RouteConfigOptions, RouteMethod, RouteSchemas } from './route';
import { HapiResponseAdapter } from './response_adapter';
-export interface RouterRoute {
+interface RouterRoute {
method: RouteMethod;
path: string;
options: RouteConfigOptions;
handler: (req: Request, responseToolkit: ResponseToolkit, log: Logger) => Promise (
route: RouteConfig (
route: RouteConfig (
route: RouteConfig (
route: RouteConfig = (
request: KibanaRequest = (request: KibanaRequest {
+ options?: RouteConfigOptions;
+ path: string;
+ validate: RouteSchemas (route: RouteConfig (route: RouteConfig, TypeOf>, response: KibanaResponseFactory) => KibanaResponse
RouteConfigOptions | Additional route options [RouteConfigOptions](./kibana-plugin-server.routeconfigoptions.md). |
+| [path](./kibana-plugin-server.routeconfig.path.md) | string | The endpoint \_within\_ the router path to register the route. E.g. if the router is registered at /elasticsearch and the route path is /search, the full path for the route is /elasticsearch/search. Supports: - named path segments path/{name}. - optional path segments path/{position?}. - multi-segments path/{coordinates*2}. Segments are accessible within a handler function as params property of [KibanaRequest](./kibana-plugin-server.kibanarequest.md) object. To have read access to params you \*must\* specify validation schema with [RouteConfig.validate](./kibana-plugin-server.routeconfig.validate.md). |
+| [validate](./kibana-plugin-server.routeconfig.validate.md) | RouteSchemas<P, Q, B> | false | A schema created with @kbn/config-schema that every request will be validated against. You \*must\* specify a validation schema to be able to read: - url path segments - request query - request body To opt out of validating the request, specify false. |
+
diff --git a/docs/development/core/server/kibana-plugin-server.routeconfig.options.md b/docs/development/core/server/kibana-plugin-server.routeconfig.options.md
new file mode 100644
index 00000000000000..12ca36da6de7cb
--- /dev/null
+++ b/docs/development/core/server/kibana-plugin-server.routeconfig.options.md
@@ -0,0 +1,13 @@
+
+
+[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [RouteConfig](./kibana-plugin-server.routeconfig.md) > [options](./kibana-plugin-server.routeconfig.options.md)
+
+## RouteConfig.options property
+
+Additional route options [RouteConfigOptions](./kibana-plugin-server.routeconfigoptions.md).
+
+Signature:
+
+```typescript
+options?: RouteConfigOptions;
+```
diff --git a/docs/development/core/server/kibana-plugin-server.routeconfig.path.md b/docs/development/core/server/kibana-plugin-server.routeconfig.path.md
new file mode 100644
index 00000000000000..3437f0e0fe0640
--- /dev/null
+++ b/docs/development/core/server/kibana-plugin-server.routeconfig.path.md
@@ -0,0 +1,13 @@
+
+
+[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [RouteConfig](./kibana-plugin-server.routeconfig.md) > [path](./kibana-plugin-server.routeconfig.path.md)
+
+## RouteConfig.path property
+
+The endpoint \_within\_ the router path to register the route. E.g. if the router is registered at `/elasticsearch` and the route path is `/search`, the full path for the route is `/elasticsearch/search`. Supports: - named path segments `path/{name}`. - optional path segments `path/{position?}`. - multi-segments `path/{coordinates*2}`. Segments are accessible within a handler function as `params` property of [KibanaRequest](./kibana-plugin-server.kibanarequest.md) object. To have read access to `params` you \*must\* specify validation schema with [RouteConfig.validate](./kibana-plugin-server.routeconfig.validate.md).
+
+Signature:
+
+```typescript
+path: string;
+```
diff --git a/docs/development/core/server/kibana-plugin-server.routeconfig.validate.md b/docs/development/core/server/kibana-plugin-server.routeconfig.validate.md
new file mode 100644
index 00000000000000..f7177485f5fb60
--- /dev/null
+++ b/docs/development/core/server/kibana-plugin-server.routeconfig.validate.md
@@ -0,0 +1,32 @@
+
+
+[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [RouteConfig](./kibana-plugin-server.routeconfig.md) > [validate](./kibana-plugin-server.routeconfig.validate.md)
+
+## RouteConfig.validate property
+
+A schema created with `@kbn/config-schema` that every request will be validated against. You \*must\* specify a validation schema to be able to read: - url path segments - request query - request body To opt out of validating the request, specify `false`.
+
+Signature:
+
+```typescript
+validate: RouteSchemasboolean | A flag shows that authentication for a route: enabled when true disabled when falseEnabled by default. |
+| [authRequired](./kibana-plugin-server.routeconfigoptions.authrequired.md) | boolean | A flag shows that authentication for a route: enabled when true disabled when falseEnabled by default. |
| [tags](./kibana-plugin-server.routeconfigoptions.tags.md) | readonly string[] | Additional metadata tag strings to attach to the route. |
diff --git a/docs/development/core/server/kibana-plugin-server.router.(constructor).md b/docs/development/core/server/kibana-plugin-server.router.(constructor).md
index 5f8e1e5e293ab7..26048a603c9f6b 100644
--- a/docs/development/core/server/kibana-plugin-server.router.(constructor).md
+++ b/docs/development/core/server/kibana-plugin-server.router.(constructor).md
@@ -16,5 +16,5 @@ constructor(path: string);
| Parameter | Type | Description |
| --- | --- | --- |
-| path | string | |
+| path | string | a router path, set as the very first path segment for all registered routes. |
diff --git a/docs/development/core/server/kibana-plugin-server.router.delete.md b/docs/development/core/server/kibana-plugin-server.router.delete.md
index cd49f80baaf70d..565dc10ce76e83 100644
--- a/docs/development/core/server/kibana-plugin-server.router.delete.md
+++ b/docs/development/core/server/kibana-plugin-server.router.delete.md
@@ -4,7 +4,7 @@
## Router.delete() method
-Register a `DELETE` request with the router
+Register a route handler for `DELETE` request.
Signature:
diff --git a/docs/development/core/server/kibana-plugin-server.router.get.md b/docs/development/core/server/kibana-plugin-server.router.get.md
index ab8e7c8c5a65d2..a3899eaa678f7c 100644
--- a/docs/development/core/server/kibana-plugin-server.router.get.md
+++ b/docs/development/core/server/kibana-plugin-server.router.get.md
@@ -4,7 +4,7 @@
## Router.get() method
-Register a `GET` request with the router
+Register a route handler for `GET` request.
Signature:
diff --git a/docs/development/core/server/kibana-plugin-server.router.getroutes.md b/docs/development/core/server/kibana-plugin-server.router.getroutes.md
deleted file mode 100644
index 3e4785a3a7c6ca..00000000000000
--- a/docs/development/core/server/kibana-plugin-server.router.getroutes.md
+++ /dev/null
@@ -1,19 +0,0 @@
-
-
-[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [Router](./kibana-plugin-server.router.md) > [getRoutes](./kibana-plugin-server.router.getroutes.md)
-
-## Router.getRoutes() method
-
-Returns all routes registered with the this router.
-
-Signature:
-
-```typescript
-getRoutes(): ReadonlyDELETE request with the router |
-| [get(route, handler)](./kibana-plugin-server.router.get.md) | | Register a GET request with the router |
-| [getRoutes()](./kibana-plugin-server.router.getroutes.md) | | Returns all routes registered with the this router. |
-| [post(route, handler)](./kibana-plugin-server.router.post.md) | | Register a POST request with the router |
-| [put(route, handler)](./kibana-plugin-server.router.put.md) | | Register a PUT request with the router |
+| [delete(route, handler)](./kibana-plugin-server.router.delete.md) | | Register a route handler for DELETE request. |
+| [get(route, handler)](./kibana-plugin-server.router.get.md) | | Register a route handler for GET request. |
+| [post(route, handler)](./kibana-plugin-server.router.post.md) | | Register a route handler for POST request. |
+| [put(route, handler)](./kibana-plugin-server.router.put.md) | | Register a route handler for PUT request. |
+
+## Example
+
+
+```ts
+const router = new Router('my-app');
+// handler is called when 'my-app/path' resource is requested with `GET` method
+router.get({ path: '/path', validate: false }, (req, res) => res.ok({ content: 'ok' }));
+
+```
diff --git a/docs/development/core/server/kibana-plugin-server.router.post.md b/docs/development/core/server/kibana-plugin-server.router.post.md
index a499a46b1ee79a..7aca35466d643a 100644
--- a/docs/development/core/server/kibana-plugin-server.router.post.md
+++ b/docs/development/core/server/kibana-plugin-server.router.post.md
@@ -4,7 +4,7 @@
## Router.post() method
-Register a `POST` request with the router
+Register a route handler for `POST` request.
Signature:
diff --git a/docs/development/core/server/kibana-plugin-server.router.put.md b/docs/development/core/server/kibana-plugin-server.router.put.md
index 7b1337279cca9a..760ccf9ef88e8d 100644
--- a/docs/development/core/server/kibana-plugin-server.router.put.md
+++ b/docs/development/core/server/kibana-plugin-server.router.put.md
@@ -4,7 +4,7 @@
## Router.put() method
-Register a `PUT` request with the router
+Register a route handler for `PUT` request.
Signature:
diff --git a/docs/development/core/server/kibana-plugin-server.scopedclusterclient.(constructor).md b/docs/development/core/server/kibana-plugin-server.scopedclusterclient.(constructor).md
index 94b49e43a113c8..0fea07320b2f9f 100644
--- a/docs/development/core/server/kibana-plugin-server.scopedclusterclient.(constructor).md
+++ b/docs/development/core/server/kibana-plugin-server.scopedclusterclient.(constructor).md
@@ -9,7 +9,7 @@ Constructs a new instance of the `ScopedClusterClient` class
Signature:
```typescript
-constructor(internalAPICaller: APICaller, scopedAPICaller: APICaller, headers?: RecordAPICaller | |
| scopedAPICaller | APICaller | |
-| headers | Record<string, string | string[] | undefined> | undefined | |
+| headers | Headers | undefined | |
diff --git a/docs/development/core/server/kibana-plugin-server.sessionstoragecookieoptions.encryptionkey.md b/docs/development/core/server/kibana-plugin-server.sessionstoragecookieoptions.encryptionkey.md
new file mode 100644
index 00000000000000..167ab03d7567f5
--- /dev/null
+++ b/docs/development/core/server/kibana-plugin-server.sessionstoragecookieoptions.encryptionkey.md
@@ -0,0 +1,13 @@
+
+
+[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [SessionStorageCookieOptions](./kibana-plugin-server.sessionstoragecookieoptions.md) > [encryptionKey](./kibana-plugin-server.sessionstoragecookieoptions.encryptionkey.md)
+
+## SessionStorageCookieOptions.encryptionKey property
+
+A key used to encrypt a cookie value. Should be at least 32 characters long.
+
+Signature:
+
+```typescript
+encryptionKey: string;
+```
diff --git a/docs/development/core/server/kibana-plugin-server.sessionstoragecookieoptions.issecure.md b/docs/development/core/server/kibana-plugin-server.sessionstoragecookieoptions.issecure.md
new file mode 100644
index 00000000000000..824fc9d136a3ff
--- /dev/null
+++ b/docs/development/core/server/kibana-plugin-server.sessionstoragecookieoptions.issecure.md
@@ -0,0 +1,13 @@
+
+
+[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [SessionStorageCookieOptions](./kibana-plugin-server.sessionstoragecookieoptions.md) > [isSecure](./kibana-plugin-server.sessionstoragecookieoptions.issecure.md)
+
+## SessionStorageCookieOptions.isSecure property
+
+Flag indicating whether the cookie should be sent only via a secure connection.
+
+Signature:
+
+```typescript
+isSecure: boolean;
+```
diff --git a/docs/development/core/server/kibana-plugin-server.sessionstoragecookieoptions.md b/docs/development/core/server/kibana-plugin-server.sessionstoragecookieoptions.md
new file mode 100644
index 00000000000000..de412818142f25
--- /dev/null
+++ b/docs/development/core/server/kibana-plugin-server.sessionstoragecookieoptions.md
@@ -0,0 +1,23 @@
+
+
+[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [SessionStorageCookieOptions](./kibana-plugin-server.sessionstoragecookieoptions.md)
+
+## SessionStorageCookieOptions interface
+
+Configuration used to create HTTP session storage based on top of cookie mechanism.
+
+Signature:
+
+```typescript
+export interface SessionStorageCookieOptionsstring | A key used to encrypt a cookie value. Should be at least 32 characters long. |
+| [isSecure](./kibana-plugin-server.sessionstoragecookieoptions.issecure.md) | boolean | Flag indicating whether the cookie should be sent only via a secure connection. |
+| [name](./kibana-plugin-server.sessionstoragecookieoptions.name.md) | string | Name of the session cookie. |
+| [validate](./kibana-plugin-server.sessionstoragecookieoptions.validate.md) | (sessionValue: T) => boolean | Promise<boolean> | Function called to validate a cookie content. |
+
diff --git a/docs/development/core/server/kibana-plugin-server.sessionstoragecookieoptions.name.md b/docs/development/core/server/kibana-plugin-server.sessionstoragecookieoptions.name.md
new file mode 100644
index 00000000000000..e6bc7ea3fe00f1
--- /dev/null
+++ b/docs/development/core/server/kibana-plugin-server.sessionstoragecookieoptions.name.md
@@ -0,0 +1,13 @@
+
+
+[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [SessionStorageCookieOptions](./kibana-plugin-server.sessionstoragecookieoptions.md) > [name](./kibana-plugin-server.sessionstoragecookieoptions.name.md)
+
+## SessionStorageCookieOptions.name property
+
+Name of the session cookie.
+
+Signature:
+
+```typescript
+name: string;
+```
diff --git a/docs/development/core/server/kibana-plugin-server.sessionstoragecookieoptions.validate.md b/docs/development/core/server/kibana-plugin-server.sessionstoragecookieoptions.validate.md
new file mode 100644
index 00000000000000..f3cbfc0d84e18e
--- /dev/null
+++ b/docs/development/core/server/kibana-plugin-server.sessionstoragecookieoptions.validate.md
@@ -0,0 +1,13 @@
+
+
+[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [SessionStorageCookieOptions](./kibana-plugin-server.sessionstoragecookieoptions.md) > [validate](./kibana-plugin-server.sessionstoragecookieoptions.validate.md)
+
+## SessionStorageCookieOptions.validate property
+
+Function called to validate a cookie content.
+
+Signature:
+
+```typescript
+validate: (sessionValue: T) => boolean | Promise, TypeOf>,
- createResponse: ResponseFactory
+ response: KibanaResponseFactory
) => KibanaResponse
, TypeOf>, response: KibanaResponseFactory) => KibanaResponse