>;
+```
diff --git a/docs/development/core/server/kibana-plugin-server.md b/docs/development/core/server/kibana-plugin-server.md
index 38c7ad75d1db9..17c5136fdc318 100644
--- a/docs/development/core/server/kibana-plugin-server.md
+++ b/docs/development/core/server/kibana-plugin-server.md
@@ -84,6 +84,8 @@ The plugin integrates with the core system via lifecycle events: `setup`
| [RequestHandlerContext](./kibana-plugin-server.requesthandlercontext.md) | Plugin specific context passed to a route handler.Provides the following clients: - [savedObjects.client](./kibana-plugin-server.savedobjectsclient.md) - Saved Objects client which uses the credentials of the incoming request - [elasticsearch.dataClient](./kibana-plugin-server.scopedclusterclient.md) - Elasticsearch data client which uses the credentials of the incoming request - [elasticsearch.adminClient](./kibana-plugin-server.scopedclusterclient.md) - Elasticsearch admin client which uses the credentials of the incoming request |
| [RouteConfig](./kibana-plugin-server.routeconfig.md) | Route specific configuration. |
| [RouteConfigOptions](./kibana-plugin-server.routeconfigoptions.md) | Additional route options. |
+| [RouteConfigOptionsBody](./kibana-plugin-server.routeconfigoptionsbody.md) | Additional body options for a route |
+| [RouteSchemas](./kibana-plugin-server.routeschemas.md) | RouteSchemas contains the schemas for validating the different parts of a request. |
| [SavedObject](./kibana-plugin-server.savedobject.md) | |
| [SavedObjectAttributes](./kibana-plugin-server.savedobjectattributes.md) | The data for a Saved Object is stored as an object in the attributes property. |
| [SavedObjectReference](./kibana-plugin-server.savedobjectreference.md) | A reference to another saved object. |
@@ -133,6 +135,7 @@ The plugin integrates with the core system via lifecycle events: `setup`
| 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. |
+| [validBodyOutput](./kibana-plugin-server.validbodyoutput.md) | The set of valid body.output |
## Type Aliases
@@ -156,6 +159,7 @@ The plugin integrates with the core system via lifecycle events: `setup`
| [IsAuthenticated](./kibana-plugin-server.isauthenticated.md) | Return authentication status for a request. |
| [ISavedObjectsRepository](./kibana-plugin-server.isavedobjectsrepository.md) | See [SavedObjectsRepository](./kibana-plugin-server.savedobjectsrepository.md) |
| [IScopedClusterClient](./kibana-plugin-server.iscopedclusterclient.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.See [ScopedClusterClient](./kibana-plugin-server.scopedclusterclient.md). |
+| [KibanaRequestRouteOptions](./kibana-plugin-server.kibanarequestrouteoptions.md) | Route options: If 'GET' or 'OPTIONS' method, body options won't be returned. |
| [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. |
| [LifecycleResponseFactory](./kibana-plugin-server.lifecycleresponsefactory.md) | Creates an object containing redirection or error response with error details, HTTP headers, and other data transmitted to the client. |
@@ -176,8 +180,9 @@ The plugin integrates with the core system via lifecycle events: `setup`
| [ResponseError](./kibana-plugin-server.responseerror.md) | Error message and optional data send to the client in case of error. |
| [ResponseErrorAttributes](./kibana-plugin-server.responseerrorattributes.md) | Additional data to provide error details. |
| [ResponseHeaders](./kibana-plugin-server.responseheaders.md) | Http response headers to set. |
+| [RouteContentType](./kibana-plugin-server.routecontenttype.md) | The set of supported parseable Content-Types |
| [RouteMethod](./kibana-plugin-server.routemethod.md) | The set of common HTTP methods supported by Kibana routing. |
-| [RouteRegistrar](./kibana-plugin-server.routeregistrar.md) | Handler to declare a route. |
+| [RouteRegistrar](./kibana-plugin-server.routeregistrar.md) | Route handler common definition |
| [SavedObjectAttribute](./kibana-plugin-server.savedobjectattribute.md) | Type definition for a Saved Object attribute value |
| [SavedObjectAttributeSingle](./kibana-plugin-server.savedobjectattributesingle.md) | Don't use this type, it's simply a helper type for [SavedObjectAttribute](./kibana-plugin-server.savedobjectattribute.md) |
| [SavedObjectsClientContract](./kibana-plugin-server.savedobjectsclientcontract.md) | Saved Objects is Kibana's data persisentence mechanism allowing plugins to use Elasticsearch for storing plugin state.\#\# 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 [SavedObjectsClient](./kibana-plugin-server.savedobjectsclient.md) See [SavedObjectsErrorHelpers](./kibana-plugin-server.savedobjectserrorhelpers.md) |
diff --git a/docs/development/core/server/kibana-plugin-server.requesthandler.md b/docs/development/core/server/kibana-plugin-server.requesthandler.md
index 035d16c9fca3c..79abfd4293e9f 100644
--- a/docs/development/core/server/kibana-plugin-server.requesthandler.md
+++ b/docs/development/core/server/kibana-plugin-server.requesthandler.md
@@ -9,7 +9,7 @@ A function executed when route path matched requested resource path. Request han
Signature:
```typescript
-export declare type RequestHandler = (context: RequestHandlerContext, request: KibanaRequest, TypeOf, TypeOf>, response: KibanaResponseFactory) => IKibanaResponse | Promise>;
+export declare type RequestHandler | Type, Method extends RouteMethod = any> = (context: RequestHandlerContext, request: KibanaRequest, TypeOf, TypeOf, Method>, response: KibanaResponseFactory) => IKibanaResponse | Promise>;
```
## Example
diff --git a/docs/development/core/server/kibana-plugin-server.routeconfig.md b/docs/development/core/server/kibana-plugin-server.routeconfig.md
index 769d0dda42644..1970b23c7ec09 100644
--- a/docs/development/core/server/kibana-plugin-server.routeconfig.md
+++ b/docs/development/core/server/kibana-plugin-server.routeconfig.md
@@ -9,14 +9,14 @@ Route specific configuration.
Signature:
```typescript
-export interface RouteConfig
+export interface RouteConfig
| Type, Method extends RouteMethod>
```
## Properties
| Property | Type | Description |
| --- | --- | --- |
-| [options](./kibana-plugin-server.routeconfig.options.md) | RouteConfigOptions | Additional route options [RouteConfigOptions](./kibana-plugin-server.routeconfigoptions.md). |
+| [options](./kibana-plugin-server.routeconfig.options.md) | RouteConfigOptions<Method> | 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. |
| [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. |
diff --git a/docs/development/core/server/kibana-plugin-server.routeconfig.options.md b/docs/development/core/server/kibana-plugin-server.routeconfig.options.md
index 12ca36da6de7c..90ad294457101 100644
--- a/docs/development/core/server/kibana-plugin-server.routeconfig.options.md
+++ b/docs/development/core/server/kibana-plugin-server.routeconfig.options.md
@@ -9,5 +9,5 @@ Additional route options [RouteConfigOptions](./kibana-plugin-server.routeconfig
Signature:
```typescript
-options?: RouteConfigOptions;
+options?: RouteConfigOptions;
```
diff --git a/docs/development/core/server/kibana-plugin-server.routeconfigoptions.body.md b/docs/development/core/server/kibana-plugin-server.routeconfigoptions.body.md
new file mode 100644
index 0000000000000..fee5528ce3378
--- /dev/null
+++ b/docs/development/core/server/kibana-plugin-server.routeconfigoptions.body.md
@@ -0,0 +1,13 @@
+
+
+[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [RouteConfigOptions](./kibana-plugin-server.routeconfigoptions.md) > [body](./kibana-plugin-server.routeconfigoptions.body.md)
+
+## RouteConfigOptions.body property
+
+Additional body options [RouteConfigOptionsBody](./kibana-plugin-server.routeconfigoptionsbody.md).
+
+Signature:
+
+```typescript
+body?: Method extends 'get' | 'options' ? undefined : RouteConfigOptionsBody;
+```
diff --git a/docs/development/core/server/kibana-plugin-server.routeconfigoptions.md b/docs/development/core/server/kibana-plugin-server.routeconfigoptions.md
index b4d210ac0b711..99339db81065c 100644
--- a/docs/development/core/server/kibana-plugin-server.routeconfigoptions.md
+++ b/docs/development/core/server/kibana-plugin-server.routeconfigoptions.md
@@ -9,7 +9,7 @@ Additional route options.
Signature:
```typescript
-export interface RouteConfigOptions
+export interface RouteConfigOptions
```
## Properties
@@ -17,5 +17,6 @@ export interface RouteConfigOptions
| Property | Type | Description |
| --- | --- | --- |
| [authRequired](./kibana-plugin-server.routeconfigoptions.authrequired.md) | boolean | A flag shows that authentication for a route: enabled when true disabled when falseEnabled by default. |
+| [body](./kibana-plugin-server.routeconfigoptions.body.md) | Method extends 'get' | 'options' ? undefined : RouteConfigOptionsBody | Additional body options [RouteConfigOptionsBody](./kibana-plugin-server.routeconfigoptionsbody.md). |
| [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.routeconfigoptionsbody.accepts.md b/docs/development/core/server/kibana-plugin-server.routeconfigoptionsbody.accepts.md
new file mode 100644
index 0000000000000..f48c9a1d73b11
--- /dev/null
+++ b/docs/development/core/server/kibana-plugin-server.routeconfigoptionsbody.accepts.md
@@ -0,0 +1,15 @@
+
+
+[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [RouteConfigOptionsBody](./kibana-plugin-server.routeconfigoptionsbody.md) > [accepts](./kibana-plugin-server.routeconfigoptionsbody.accepts.md)
+
+## RouteConfigOptionsBody.accepts property
+
+A string or an array of strings with the allowed mime types for the endpoint. Use this settings to limit the set of allowed mime types. Note that allowing additional mime types not listed above will not enable them to be parsed, and if parse is true, the request will result in an error response.
+
+Default value: allows parsing of the following mime types: \* application/json \* application/\*+json \* application/octet-stream \* application/x-www-form-urlencoded \* multipart/form-data \* text/\*
+
+Signature:
+
+```typescript
+accepts?: RouteContentType | RouteContentType[] | string | string[];
+```
diff --git a/docs/development/core/server/kibana-plugin-server.routeconfigoptionsbody.maxbytes.md b/docs/development/core/server/kibana-plugin-server.routeconfigoptionsbody.maxbytes.md
new file mode 100644
index 0000000000000..3d22dc07d5bae
--- /dev/null
+++ b/docs/development/core/server/kibana-plugin-server.routeconfigoptionsbody.maxbytes.md
@@ -0,0 +1,15 @@
+
+
+[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [RouteConfigOptionsBody](./kibana-plugin-server.routeconfigoptionsbody.md) > [maxBytes](./kibana-plugin-server.routeconfigoptionsbody.maxbytes.md)
+
+## RouteConfigOptionsBody.maxBytes property
+
+Limits the size of incoming payloads to the specified byte count. Allowing very large payloads may cause the server to run out of memory.
+
+Default value: The one set in the kibana.yml config file under the parameter `server.maxPayloadBytes`.
+
+Signature:
+
+```typescript
+maxBytes?: number;
+```
diff --git a/docs/development/core/server/kibana-plugin-server.routeconfigoptionsbody.md b/docs/development/core/server/kibana-plugin-server.routeconfigoptionsbody.md
new file mode 100644
index 0000000000000..6ef04de459fcf
--- /dev/null
+++ b/docs/development/core/server/kibana-plugin-server.routeconfigoptionsbody.md
@@ -0,0 +1,23 @@
+
+
+[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [RouteConfigOptionsBody](./kibana-plugin-server.routeconfigoptionsbody.md)
+
+## RouteConfigOptionsBody interface
+
+Additional body options for a route
+
+Signature:
+
+```typescript
+export interface RouteConfigOptionsBody
+```
+
+## Properties
+
+| Property | Type | Description |
+| --- | --- | --- |
+| [accepts](./kibana-plugin-server.routeconfigoptionsbody.accepts.md) | RouteContentType | RouteContentType[] | string | string[] | A string or an array of strings with the allowed mime types for the endpoint. Use this settings to limit the set of allowed mime types. Note that allowing additional mime types not listed above will not enable them to be parsed, and if parse is true, the request will result in an error response.Default value: allows parsing of the following mime types: \* application/json \* application/\*+json \* application/octet-stream \* application/x-www-form-urlencoded \* multipart/form-data \* text/\* |
+| [maxBytes](./kibana-plugin-server.routeconfigoptionsbody.maxbytes.md) | number | Limits the size of incoming payloads to the specified byte count. Allowing very large payloads may cause the server to run out of memory.Default value: The one set in the kibana.yml config file under the parameter server.maxPayloadBytes. |
+| [output](./kibana-plugin-server.routeconfigoptionsbody.output.md) | typeof validBodyOutput[number] | The processed payload format. The value must be one of: \* 'data' - the incoming payload is read fully into memory. If parse is true, the payload is parsed (JSON, form-decoded, multipart) based on the 'Content-Type' header. If parse is false, a raw Buffer is returned. \* 'stream' - the incoming payload is made available via a Stream.Readable interface. If the payload is 'multipart/form-data' and parse is true, field values are presented as text while files are provided as streams. File streams from a 'multipart/form-data' upload will also have a hapi property containing the filename and headers properties. Note that payload streams for multipart payloads are a synthetic interface created on top of the entire multipart content loaded into memory. To avoid loading large multipart payloads into memory, set parse to false and handle the multipart payload in the handler using a streaming parser (e.g. pez).Default value: 'data', unless no validation.body is provided in the route definition. In that case the default is 'stream' to alleviate memory pressure. |
+| [parse](./kibana-plugin-server.routeconfigoptionsbody.parse.md) | boolean | 'gunzip' | Determines if the incoming payload is processed or presented raw. Available values: \* true - if the request 'Content-Type' matches the allowed mime types set by allow (for the whole payload as well as parts), the payload is converted into an object when possible. If the format is unknown, a Bad Request (400) error response is sent. Any known content encoding is decoded. \* false - the raw payload is returned unmodified. \* 'gunzip' - the raw payload is returned unmodified after any known content encoding is decoded.Default value: true, unless no validation.body is provided in the route definition. In that case the default is false to alleviate memory pressure. |
+
diff --git a/docs/development/core/server/kibana-plugin-server.routeconfigoptionsbody.output.md b/docs/development/core/server/kibana-plugin-server.routeconfigoptionsbody.output.md
new file mode 100644
index 0000000000000..b84bc709df3ec
--- /dev/null
+++ b/docs/development/core/server/kibana-plugin-server.routeconfigoptionsbody.output.md
@@ -0,0 +1,15 @@
+
+
+[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [RouteConfigOptionsBody](./kibana-plugin-server.routeconfigoptionsbody.md) > [output](./kibana-plugin-server.routeconfigoptionsbody.output.md)
+
+## RouteConfigOptionsBody.output property
+
+The processed payload format. The value must be one of: \* 'data' - the incoming payload is read fully into memory. If parse is true, the payload is parsed (JSON, form-decoded, multipart) based on the 'Content-Type' header. If parse is false, a raw Buffer is returned. \* 'stream' - the incoming payload is made available via a Stream.Readable interface. If the payload is 'multipart/form-data' and parse is true, field values are presented as text while files are provided as streams. File streams from a 'multipart/form-data' upload will also have a hapi property containing the filename and headers properties. Note that payload streams for multipart payloads are a synthetic interface created on top of the entire multipart content loaded into memory. To avoid loading large multipart payloads into memory, set parse to false and handle the multipart payload in the handler using a streaming parser (e.g. pez).
+
+Default value: 'data', unless no validation.body is provided in the route definition. In that case the default is 'stream' to alleviate memory pressure.
+
+Signature:
+
+```typescript
+output?: typeof validBodyOutput[number];
+```
diff --git a/docs/development/core/server/kibana-plugin-server.routeconfigoptionsbody.parse.md b/docs/development/core/server/kibana-plugin-server.routeconfigoptionsbody.parse.md
new file mode 100644
index 0000000000000..d395f67c69669
--- /dev/null
+++ b/docs/development/core/server/kibana-plugin-server.routeconfigoptionsbody.parse.md
@@ -0,0 +1,15 @@
+
+
+[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [RouteConfigOptionsBody](./kibana-plugin-server.routeconfigoptionsbody.md) > [parse](./kibana-plugin-server.routeconfigoptionsbody.parse.md)
+
+## RouteConfigOptionsBody.parse property
+
+Determines if the incoming payload is processed or presented raw. Available values: \* true - if the request 'Content-Type' matches the allowed mime types set by allow (for the whole payload as well as parts), the payload is converted into an object when possible. If the format is unknown, a Bad Request (400) error response is sent. Any known content encoding is decoded. \* false - the raw payload is returned unmodified. \* 'gunzip' - the raw payload is returned unmodified after any known content encoding is decoded.
+
+Default value: true, unless no validation.body is provided in the route definition. In that case the default is false to alleviate memory pressure.
+
+Signature:
+
+```typescript
+parse?: boolean | 'gunzip';
+```
diff --git a/docs/development/core/server/kibana-plugin-server.routecontenttype.md b/docs/development/core/server/kibana-plugin-server.routecontenttype.md
new file mode 100644
index 0000000000000..010388c7b8f17
--- /dev/null
+++ b/docs/development/core/server/kibana-plugin-server.routecontenttype.md
@@ -0,0 +1,13 @@
+
+
+[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [RouteContentType](./kibana-plugin-server.routecontenttype.md)
+
+## RouteContentType type
+
+The set of supported parseable Content-Types
+
+Signature:
+
+```typescript
+export declare type RouteContentType = 'application/json' | 'application/*+json' | 'application/octet-stream' | 'application/x-www-form-urlencoded' | 'multipart/form-data' | 'text/*';
+```
diff --git a/docs/development/core/server/kibana-plugin-server.routemethod.md b/docs/development/core/server/kibana-plugin-server.routemethod.md
index dd1a050708bb3..4f83344f842b3 100644
--- a/docs/development/core/server/kibana-plugin-server.routemethod.md
+++ b/docs/development/core/server/kibana-plugin-server.routemethod.md
@@ -9,5 +9,5 @@ The set of common HTTP methods supported by Kibana routing.
Signature:
```typescript
-export declare type RouteMethod = 'get' | 'post' | 'put' | 'delete';
+export declare type RouteMethod = 'get' | 'post' | 'put' | 'delete' | 'patch' | 'options';
```
diff --git a/docs/development/core/server/kibana-plugin-server.routeregistrar.md b/docs/development/core/server/kibana-plugin-server.routeregistrar.md
index 535927dc73743..0f5f49636fdd5 100644
--- a/docs/development/core/server/kibana-plugin-server.routeregistrar.md
+++ b/docs/development/core/server/kibana-plugin-server.routeregistrar.md
@@ -4,10 +4,10 @@
## RouteRegistrar type
-Handler to declare a route.
+Route handler common definition
Signature:
```typescript
-export declare type RouteRegistrar = (route: RouteConfig, handler: RequestHandler) => void;
+export declare type RouteRegistrar = | Type>(route: RouteConfig, handler: RequestHandler) => void;
```
diff --git a/docs/development/core/server/kibana-plugin-server.routeschemas.body.md b/docs/development/core/server/kibana-plugin-server.routeschemas.body.md
new file mode 100644
index 0000000000000..78a9d25c25d9d
--- /dev/null
+++ b/docs/development/core/server/kibana-plugin-server.routeschemas.body.md
@@ -0,0 +1,11 @@
+
+
+[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [RouteSchemas](./kibana-plugin-server.routeschemas.md) > [body](./kibana-plugin-server.routeschemas.body.md)
+
+## RouteSchemas.body property
+
+Signature:
+
+```typescript
+body?: B;
+```
diff --git a/docs/development/core/server/kibana-plugin-server.routeschemas.md b/docs/development/core/server/kibana-plugin-server.routeschemas.md
new file mode 100644
index 0000000000000..77b980551a8ff
--- /dev/null
+++ b/docs/development/core/server/kibana-plugin-server.routeschemas.md
@@ -0,0 +1,22 @@
+
+
+[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [RouteSchemas](./kibana-plugin-server.routeschemas.md)
+
+## RouteSchemas interface
+
+RouteSchemas contains the schemas for validating the different parts of a request.
+
+Signature:
+
+```typescript
+export interface RouteSchemas | Type>
+```
+
+## Properties
+
+| Property | Type | Description |
+| --- | --- | --- |
+| [body](./kibana-plugin-server.routeschemas.body.md) | B | |
+| [params](./kibana-plugin-server.routeschemas.params.md) | P | |
+| [query](./kibana-plugin-server.routeschemas.query.md) | Q | |
+
diff --git a/docs/development/core/server/kibana-plugin-server.routeschemas.params.md b/docs/development/core/server/kibana-plugin-server.routeschemas.params.md
new file mode 100644
index 0000000000000..3dbf9fed94dc0
--- /dev/null
+++ b/docs/development/core/server/kibana-plugin-server.routeschemas.params.md
@@ -0,0 +1,11 @@
+
+
+[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [RouteSchemas](./kibana-plugin-server.routeschemas.md) > [params](./kibana-plugin-server.routeschemas.params.md)
+
+## RouteSchemas.params property
+
+Signature:
+
+```typescript
+params?: P;
+```
diff --git a/docs/development/core/server/kibana-plugin-server.routeschemas.query.md b/docs/development/core/server/kibana-plugin-server.routeschemas.query.md
new file mode 100644
index 0000000000000..5be5830cb4bc8
--- /dev/null
+++ b/docs/development/core/server/kibana-plugin-server.routeschemas.query.md
@@ -0,0 +1,11 @@
+
+
+[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [RouteSchemas](./kibana-plugin-server.routeschemas.md) > [query](./kibana-plugin-server.routeschemas.query.md)
+
+## RouteSchemas.query property
+
+Signature:
+
+```typescript
+query?: Q;
+```
diff --git a/docs/development/core/server/kibana-plugin-server.validbodyoutput.md b/docs/development/core/server/kibana-plugin-server.validbodyoutput.md
new file mode 100644
index 0000000000000..ea866abf887fb
--- /dev/null
+++ b/docs/development/core/server/kibana-plugin-server.validbodyoutput.md
@@ -0,0 +1,13 @@
+
+
+[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [validBodyOutput](./kibana-plugin-server.validbodyoutput.md)
+
+## validBodyOutput variable
+
+The set of valid body.output
+
+Signature:
+
+```typescript
+validBodyOutput: readonly ["data", "stream"]
+```
diff --git a/packages/kbn-config-schema/README.md b/packages/kbn-config-schema/README.md
index 8ba2c43b5e1fe..fd62f1b3c03b2 100644
--- a/packages/kbn-config-schema/README.md
+++ b/packages/kbn-config-schema/README.md
@@ -12,6 +12,8 @@ Kibana configuration entries providing developers with a fully typed model of th
- [`schema.number()`](#schemanumber)
- [`schema.boolean()`](#schemaboolean)
- [`schema.literal()`](#schemaliteral)
+ - [`schema.buffer()`](#schemabuffer)
+ - [`schema.stream()`](#schemastream)
- [Composite types](#composite-types)
- [`schema.arrayOf()`](#schemaarrayof)
- [`schema.object()`](#schemaobject)
@@ -173,6 +175,36 @@ const valueSchema = [
];
```
+#### `schema.buffer()`
+
+Validates input data as a NodeJS `Buffer`.
+
+__Output type:__ `Buffer`
+
+__Options:__
+ * `defaultValue: TBuffer | Reference | (() => TBuffer)` - defines a default value, see [Default values](#default-values) section for more details.
+ * `validate: (value: TBuffer) => Buffer | void` - defines a custom validator function, see [Custom validation](#custom-validation) section for more details.
+
+__Usage:__
+```typescript
+const valueSchema = schema.buffer({ defaultValue: Buffer.from('Hi, there!') });
+```
+
+#### `schema.stream()`
+
+Validates input data as a NodeJS `stream`.
+
+__Output type:__ `Stream`, `Readable` or `Writtable`
+
+__Options:__
+ * `defaultValue: TStream | Reference | (() => TStream)` - defines a default value, see [Default values](#default-values) section for more details.
+ * `validate: (value: TStream) => string | void` - defines a custom validator function, see [Custom validation](#custom-validation) section for more details.
+
+__Usage:__
+```typescript
+const valueSchema = schema.stream({ defaultValue: new Stream() });
+```
+
### Composite types
#### `schema.arrayOf()`
diff --git a/packages/kbn-config-schema/src/index.ts b/packages/kbn-config-schema/src/index.ts
index 210b044421e7e..56b3096433c24 100644
--- a/packages/kbn-config-schema/src/index.ts
+++ b/packages/kbn-config-schema/src/index.ts
@@ -18,6 +18,7 @@
*/
import { Duration } from 'moment';
+import { Stream } from 'stream';
import { ByteSizeValue } from './byte_size_value';
import { ContextReference, Reference, SiblingReference } from './references';
@@ -26,6 +27,7 @@ import {
ArrayOptions,
ArrayType,
BooleanType,
+ BufferType,
ByteSizeOptions,
ByteSizeType,
ConditionalType,
@@ -52,6 +54,7 @@ import {
UnionType,
URIOptions,
URIType,
+ StreamType,
} from './types';
export { ObjectType, TypeOf, Type };
@@ -65,6 +68,14 @@ function boolean(options?: TypeOptions): Type {
return new BooleanType(options);
}
+function buffer(options?: TypeOptions): Type {
+ return new BufferType(options);
+}
+
+function stream(options?: TypeOptions): Type {
+ return new StreamType(options);
+}
+
function string(options?: StringOptions): Type {
return new StringType(options);
}
@@ -188,6 +199,7 @@ export const schema = {
any,
arrayOf,
boolean,
+ buffer,
byteSize,
conditional,
contextRef,
@@ -201,6 +213,7 @@ export const schema = {
object,
oneOf,
recordOf,
+ stream,
siblingRef,
string,
uri,
diff --git a/packages/kbn-config-schema/src/internals/index.ts b/packages/kbn-config-schema/src/internals/index.ts
index e5a5b446de4f5..4d5091eaa09b1 100644
--- a/packages/kbn-config-schema/src/internals/index.ts
+++ b/packages/kbn-config-schema/src/internals/index.ts
@@ -29,6 +29,7 @@ import {
} from 'joi';
import { isPlainObject } from 'lodash';
import { isDuration } from 'moment';
+import { Stream } from 'stream';
import { ByteSizeValue, ensureByteSizeValue } from '../byte_size_value';
import { ensureDuration } from '../duration';
@@ -89,6 +90,33 @@ export const internals = Joi.extend([
},
rules: [anyCustomRule],
},
+ {
+ name: 'binary',
+
+ base: Joi.binary(),
+ coerce(value: any, state: State, options: ValidationOptions) {
+ // If value isn't defined, let Joi handle default value if it's defined.
+ if (value !== undefined && !(typeof value === 'object' && Buffer.isBuffer(value))) {
+ return this.createError('binary.base', { value }, state, options);
+ }
+
+ return value;
+ },
+ rules: [anyCustomRule],
+ },
+ {
+ name: 'stream',
+
+ pre(value: any, state: State, options: ValidationOptions) {
+ // If value isn't defined, let Joi handle default value if it's defined.
+ if (value instanceof Stream) {
+ return value as any;
+ }
+
+ return this.createError('stream.base', { value }, state, options);
+ },
+ rules: [anyCustomRule],
+ },
{
name: 'string',
diff --git a/packages/kbn-config-schema/src/types/__snapshots__/buffer_type.test.ts.snap b/packages/kbn-config-schema/src/types/__snapshots__/buffer_type.test.ts.snap
new file mode 100644
index 0000000000000..96a7ab34dac26
--- /dev/null
+++ b/packages/kbn-config-schema/src/types/__snapshots__/buffer_type.test.ts.snap
@@ -0,0 +1,11 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`includes namespace in failure 1`] = `"[foo-namespace]: expected value of type [Buffer] but got [undefined]"`;
+
+exports[`is required by default 1`] = `"expected value of type [Buffer] but got [undefined]"`;
+
+exports[`returns error when not a buffer 1`] = `"expected value of type [Buffer] but got [number]"`;
+
+exports[`returns error when not a buffer 2`] = `"expected value of type [Buffer] but got [Array]"`;
+
+exports[`returns error when not a buffer 3`] = `"expected value of type [Buffer] but got [string]"`;
diff --git a/packages/kbn-config-schema/src/types/__snapshots__/stream_type.test.ts.snap b/packages/kbn-config-schema/src/types/__snapshots__/stream_type.test.ts.snap
new file mode 100644
index 0000000000000..e813b4f68a09e
--- /dev/null
+++ b/packages/kbn-config-schema/src/types/__snapshots__/stream_type.test.ts.snap
@@ -0,0 +1,11 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`includes namespace in failure 1`] = `"[foo-namespace]: expected value of type [Stream] but got [undefined]"`;
+
+exports[`is required by default 1`] = `"expected value of type [Buffer] but got [undefined]"`;
+
+exports[`returns error when not a stream 1`] = `"expected value of type [Stream] but got [number]"`;
+
+exports[`returns error when not a stream 2`] = `"expected value of type [Stream] but got [Array]"`;
+
+exports[`returns error when not a stream 3`] = `"expected value of type [Stream] but got [string]"`;
diff --git a/packages/kbn-config-schema/src/types/buffer_type.test.ts b/packages/kbn-config-schema/src/types/buffer_type.test.ts
new file mode 100644
index 0000000000000..63d59296aec84
--- /dev/null
+++ b/packages/kbn-config-schema/src/types/buffer_type.test.ts
@@ -0,0 +1,57 @@
+/*
+ * Licensed to Elasticsearch B.V. under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch B.V. licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import { schema } from '..';
+
+test('returns value by default', () => {
+ const value = Buffer.from('Hi!');
+ expect(schema.buffer().validate(value)).toStrictEqual(value);
+});
+
+test('is required by default', () => {
+ expect(() => schema.buffer().validate(undefined)).toThrowErrorMatchingSnapshot();
+});
+
+test('includes namespace in failure', () => {
+ expect(() =>
+ schema.buffer().validate(undefined, {}, 'foo-namespace')
+ ).toThrowErrorMatchingSnapshot();
+});
+
+describe('#defaultValue', () => {
+ test('returns default when undefined', () => {
+ const value = Buffer.from('Hi!');
+ expect(schema.buffer({ defaultValue: value }).validate(undefined)).toStrictEqual(value);
+ });
+
+ test('returns value when specified', () => {
+ const value = Buffer.from('Hi!');
+ expect(schema.buffer({ defaultValue: Buffer.from('Bye!') }).validate(value)).toStrictEqual(
+ value
+ );
+ });
+});
+
+test('returns error when not a buffer', () => {
+ expect(() => schema.buffer().validate(123)).toThrowErrorMatchingSnapshot();
+
+ expect(() => schema.buffer().validate([1, 2, 3])).toThrowErrorMatchingSnapshot();
+
+ expect(() => schema.buffer().validate('abc')).toThrowErrorMatchingSnapshot();
+});
diff --git a/packages/kbn-config-schema/src/types/buffer_type.ts b/packages/kbn-config-schema/src/types/buffer_type.ts
new file mode 100644
index 0000000000000..194163e5096f0
--- /dev/null
+++ b/packages/kbn-config-schema/src/types/buffer_type.ts
@@ -0,0 +1,34 @@
+/*
+ * Licensed to Elasticsearch B.V. under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch B.V. licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import typeDetect from 'type-detect';
+import { internals } from '../internals';
+import { Type, TypeOptions } from './type';
+
+export class BufferType extends Type {
+ constructor(options?: TypeOptions) {
+ super(internals.binary(), options);
+ }
+
+ protected handleError(type: string, { value }: Record) {
+ if (type === 'any.required' || type === 'binary.base') {
+ return `expected value of type [Buffer] but got [${typeDetect(value)}]`;
+ }
+ }
+}
diff --git a/packages/kbn-config-schema/src/types/index.ts b/packages/kbn-config-schema/src/types/index.ts
index cfa8cc4b7553d..9db79b8bf9e00 100644
--- a/packages/kbn-config-schema/src/types/index.ts
+++ b/packages/kbn-config-schema/src/types/index.ts
@@ -21,6 +21,7 @@ export { Type, TypeOptions } from './type';
export { AnyType } from './any_type';
export { ArrayOptions, ArrayType } from './array_type';
export { BooleanType } from './boolean_type';
+export { BufferType } from './buffer_type';
export { ByteSizeOptions, ByteSizeType } from './byte_size_type';
export { ConditionalType, ConditionalTypeValue } from './conditional_type';
export { DurationOptions, DurationType } from './duration_type';
@@ -30,6 +31,7 @@ export { MapOfOptions, MapOfType } from './map_type';
export { NumberOptions, NumberType } from './number_type';
export { ObjectType, ObjectTypeOptions, Props, TypeOf } from './object_type';
export { RecordOfOptions, RecordOfType } from './record_type';
+export { StreamType } from './stream_type';
export { StringOptions, StringType } from './string_type';
export { UnionType } from './union_type';
export { URIOptions, URIType } from './uri_type';
diff --git a/packages/kbn-config-schema/src/types/stream_type.test.ts b/packages/kbn-config-schema/src/types/stream_type.test.ts
new file mode 100644
index 0000000000000..011fa6373df33
--- /dev/null
+++ b/packages/kbn-config-schema/src/types/stream_type.test.ts
@@ -0,0 +1,71 @@
+/*
+ * Licensed to Elasticsearch B.V. under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch B.V. licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import { schema } from '..';
+import { Stream, Readable, Writable, PassThrough } from 'stream';
+
+test('returns value by default', () => {
+ const value = new Stream();
+ expect(schema.stream().validate(value)).toStrictEqual(value);
+});
+
+test('Readable is valid', () => {
+ const value = new Readable();
+ expect(schema.stream().validate(value)).toStrictEqual(value);
+});
+
+test('Writable is valid', () => {
+ const value = new Writable();
+ expect(schema.stream().validate(value)).toStrictEqual(value);
+});
+
+test('Passthrough is valid', () => {
+ const value = new PassThrough();
+ expect(schema.stream().validate(value)).toStrictEqual(value);
+});
+
+test('is required by default', () => {
+ expect(() => schema.buffer().validate(undefined)).toThrowErrorMatchingSnapshot();
+});
+
+test('includes namespace in failure', () => {
+ expect(() =>
+ schema.stream().validate(undefined, {}, 'foo-namespace')
+ ).toThrowErrorMatchingSnapshot();
+});
+
+describe('#defaultValue', () => {
+ test('returns default when undefined', () => {
+ const value = new Stream();
+ expect(schema.stream({ defaultValue: value }).validate(undefined)).toStrictEqual(value);
+ });
+
+ test('returns value when specified', () => {
+ const value = new Stream();
+ expect(schema.stream({ defaultValue: new PassThrough() }).validate(value)).toStrictEqual(value);
+ });
+});
+
+test('returns error when not a stream', () => {
+ expect(() => schema.stream().validate(123)).toThrowErrorMatchingSnapshot();
+
+ expect(() => schema.stream().validate([1, 2, 3])).toThrowErrorMatchingSnapshot();
+
+ expect(() => schema.stream().validate('abc')).toThrowErrorMatchingSnapshot();
+});
diff --git a/packages/kbn-config-schema/src/types/stream_type.ts b/packages/kbn-config-schema/src/types/stream_type.ts
new file mode 100644
index 0000000000000..db1559f537490
--- /dev/null
+++ b/packages/kbn-config-schema/src/types/stream_type.ts
@@ -0,0 +1,35 @@
+/*
+ * Licensed to Elasticsearch B.V. under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch B.V. licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import typeDetect from 'type-detect';
+import { Stream } from 'stream';
+import { internals } from '../internals';
+import { Type, TypeOptions } from './type';
+
+export class StreamType extends Type {
+ constructor(options?: TypeOptions) {
+ super(internals.stream(), options);
+ }
+
+ protected handleError(type: string, { value }: Record) {
+ if (type === 'any.required' || type === 'stream.base') {
+ return `expected value of type [Stream] but got [${typeDetect(value)}]`;
+ }
+ }
+}
diff --git a/packages/kbn-config-schema/types/joi.d.ts b/packages/kbn-config-schema/types/joi.d.ts
index 5c7e42d0d6f5f..770314faa8ebd 100644
--- a/packages/kbn-config-schema/types/joi.d.ts
+++ b/packages/kbn-config-schema/types/joi.d.ts
@@ -38,6 +38,7 @@ declare module 'joi' {
duration: () => AnySchema;
map: () => MapSchema;
record: () => RecordSchema;
+ stream: () => AnySchema;
};
interface AnySchema {
diff --git a/src/core/server/http/http_server.mocks.ts b/src/core/server/http/http_server.mocks.ts
index 0ac2f59525c32..8469a1d23a44b 100644
--- a/src/core/server/http/http_server.mocks.ts
+++ b/src/core/server/http/http_server.mocks.ts
@@ -54,7 +54,7 @@ function createKibanaRequestMock({
}: RequestFixtureOptions = {}) {
const queryString = querystring.stringify(query);
return KibanaRequest.from(
- {
+ createRawRequestMock({
headers,
params,
query,
@@ -71,13 +71,13 @@ function createKibanaRequestMock({
raw: {
req: { socket },
},
- } as any,
+ }),
{
params: schema.object({}, { allowUnknowns: true }),
body: schema.object({}, { allowUnknowns: true }),
query: schema.object({}, { allowUnknowns: true }),
}
- );
+ ) as KibanaRequest, Readonly<{}>, Readonly<{}>>;
}
type DeepPartial = T extends any[]
diff --git a/src/core/server/http/http_server.test.ts b/src/core/server/http/http_server.test.ts
index ceecfcfea1449..df47ffdc1176b 100644
--- a/src/core/server/http/http_server.test.ts
+++ b/src/core/server/http/http_server.test.ts
@@ -30,6 +30,7 @@ import { HttpConfig } from './http_config';
import { Router } from './router';
import { loggingServiceMock } from '../logging/logging_service.mock';
import { HttpServer } from './http_server';
+import { Readable } from 'stream';
const cookieOptions = {
name: 'sid',
@@ -577,6 +578,157 @@ test('exposes route details of incoming request to a route handler', async () =>
});
});
+test('exposes route details of incoming request to a route handler (POST + payload options)', async () => {
+ const { registerRouter, server: innerServer } = await server.setup(config);
+
+ const router = new Router('', logger, enhanceWithContext);
+ router.post(
+ {
+ path: '/',
+ validate: { body: schema.object({ test: schema.number() }) },
+ options: { body: { accepts: 'application/json' } },
+ },
+ (context, req, res) => res.ok({ body: req.route })
+ );
+ registerRouter(router);
+
+ await server.start();
+ await supertest(innerServer.listener)
+ .post('/')
+ .send({ test: 1 })
+ .expect(200, {
+ method: 'post',
+ path: '/',
+ options: {
+ authRequired: true,
+ tags: [],
+ body: {
+ parse: true, // hapi populates the default
+ maxBytes: 1024, // hapi populates the default
+ accepts: ['application/json'],
+ output: 'data',
+ },
+ },
+ });
+});
+
+describe('body options', () => {
+ test('should reject the request because the Content-Type in the request is not valid', async () => {
+ const { registerRouter, server: innerServer } = await server.setup(config);
+
+ const router = new Router('', logger, enhanceWithContext);
+ router.post(
+ {
+ path: '/',
+ validate: { body: schema.object({ test: schema.number() }) },
+ options: { body: { accepts: 'multipart/form-data' } }, // supertest sends 'application/json'
+ },
+ (context, req, res) => res.ok({ body: req.route })
+ );
+ registerRouter(router);
+
+ await server.start();
+ await supertest(innerServer.listener)
+ .post('/')
+ .send({ test: 1 })
+ .expect(415, {
+ statusCode: 415,
+ error: 'Unsupported Media Type',
+ message: 'Unsupported Media Type',
+ });
+ });
+
+ test('should reject the request because the payload is too large', async () => {
+ const { registerRouter, server: innerServer } = await server.setup(config);
+
+ const router = new Router('', logger, enhanceWithContext);
+ router.post(
+ {
+ path: '/',
+ validate: { body: schema.object({ test: schema.number() }) },
+ options: { body: { maxBytes: 1 } },
+ },
+ (context, req, res) => res.ok({ body: req.route })
+ );
+ registerRouter(router);
+
+ await server.start();
+ await supertest(innerServer.listener)
+ .post('/')
+ .send({ test: 1 })
+ .expect(413, {
+ statusCode: 413,
+ error: 'Request Entity Too Large',
+ message: 'Payload content length greater than maximum allowed: 1',
+ });
+ });
+
+ test('should not parse the content in the request', async () => {
+ const { registerRouter, server: innerServer } = await server.setup(config);
+
+ const router = new Router('', logger, enhanceWithContext);
+ router.post(
+ {
+ path: '/',
+ validate: { body: schema.buffer() },
+ options: { body: { parse: false } },
+ },
+ (context, req, res) => {
+ try {
+ expect(req.body).toBeInstanceOf(Buffer);
+ expect(req.body.toString()).toBe(JSON.stringify({ test: 1 }));
+ return res.ok({ body: req.route.options.body });
+ } catch (err) {
+ return res.internalError({ body: err.message });
+ }
+ }
+ );
+ registerRouter(router);
+
+ await server.start();
+ await supertest(innerServer.listener)
+ .post('/')
+ .send({ test: 1 })
+ .expect(200, {
+ parse: false,
+ maxBytes: 1024, // hapi populates the default
+ output: 'data',
+ });
+ });
+});
+
+test('should return a stream in the body', async () => {
+ const { registerRouter, server: innerServer } = await server.setup(config);
+
+ const router = new Router('', logger, enhanceWithContext);
+ router.put(
+ {
+ path: '/',
+ validate: { body: schema.stream() },
+ options: { body: { output: 'stream' } },
+ },
+ (context, req, res) => {
+ try {
+ expect(req.body).toBeInstanceOf(Readable);
+ return res.ok({ body: req.route.options.body });
+ } catch (err) {
+ return res.internalError({ body: err.message });
+ }
+ }
+ );
+ registerRouter(router);
+
+ await server.start();
+ await supertest(innerServer.listener)
+ .put('/')
+ .send({ test: 1 })
+ .expect(200, {
+ parse: true,
+ maxBytes: 1024, // hapi populates the default
+ output: 'stream',
+ });
+});
+
describe('setup contract', () => {
describe('#createSessionStorage', () => {
it('creates session storage factory', async () => {
diff --git a/src/core/server/http/http_server.ts b/src/core/server/http/http_server.ts
index da97ab535516c..a587eed1f54ec 100644
--- a/src/core/server/http/http_server.ts
+++ b/src/core/server/http/http_server.ts
@@ -127,21 +127,26 @@ export class HttpServer {
for (const router of this.registeredRouters) {
for (const route of router.getRoutes()) {
this.log.debug(`registering route handler for [${route.path}]`);
- const { authRequired = true, tags } = route.options;
// Hapi does not allow payload validation to be specified for 'head' or 'get' requests
const validate = ['head', 'get'].includes(route.method) ? undefined : { payload: true };
+ const { authRequired = true, tags, body = {} } = route.options;
+ const { accepts: allow, maxBytes, output, parse } = body;
this.server.route({
handler: route.handler,
method: route.method,
path: route.path,
options: {
- auth: authRequired ? undefined : false,
+ // Enforcing the comparison with true because plugins could overwrite the auth strategy by doing `options: { authRequired: authStrategy as any }`
+ auth: authRequired === true ? undefined : false,
tags: tags ? Array.from(tags) : undefined,
// TODO: This 'validate' section can be removed once the legacy platform is completely removed.
// We are telling Hapi that NP routes can accept any payload, so that it can bypass the default
// validation applied in ./http_tools#getServerOptions
// (All NP routes are already required to specify their own validation in order to access the payload)
validate,
+ payload: [allow, maxBytes, output, parse].some(v => typeof v !== 'undefined')
+ ? { allow, maxBytes, output, parse }
+ : undefined,
},
});
}
diff --git a/src/core/server/http/http_service.mock.ts b/src/core/server/http/http_service.mock.ts
index e9a2571382edc..6dab120b20e50 100644
--- a/src/core/server/http/http_service.mock.ts
+++ b/src/core/server/http/http_service.mock.ts
@@ -43,6 +43,7 @@ const createRouterMock = (): jest.Mocked => ({
get: jest.fn(),
post: jest.fn(),
put: jest.fn(),
+ patch: jest.fn(),
delete: jest.fn(),
getRoutes: jest.fn(),
handleLegacyErrors: jest.fn().mockImplementation(handler => handler),
diff --git a/src/core/server/http/index.ts b/src/core/server/http/index.ts
index bed76201bb4f9..f9a3a91ec18ad 100644
--- a/src/core/server/http/index.ts
+++ b/src/core/server/http/index.ts
@@ -30,6 +30,7 @@ export {
ErrorHttpResponseOptions,
KibanaRequest,
KibanaRequestRoute,
+ KibanaRequestRouteOptions,
IKibanaResponse,
KnownHeaders,
LegacyRequest,
@@ -44,8 +45,12 @@ export {
RouteConfig,
IRouter,
RouteMethod,
- RouteConfigOptions,
RouteRegistrar,
+ RouteConfigOptions,
+ RouteSchemas,
+ RouteConfigOptionsBody,
+ RouteContentType,
+ validBodyOutput,
} from './router';
export { BasePathProxyServer } from './base_path_proxy_server';
export { OnPreAuthHandler, OnPreAuthToolkit } from './lifecycle/on_pre_auth';
diff --git a/src/core/server/http/router/error_wrapper.ts b/src/core/server/http/router/error_wrapper.ts
index 706a9fe3b8887..c4b4d3840d1b9 100644
--- a/src/core/server/http/router/error_wrapper.ts
+++ b/src/core/server/http/router/error_wrapper.ts
@@ -23,13 +23,14 @@ import { KibanaRequest } from './request';
import { KibanaResponseFactory } from './response';
import { RequestHandler } from './router';
import { RequestHandlerContext } from '../../../server';
+import { RouteMethod } from './route';
export const wrapErrors = (
- handler: RequestHandler
-): RequestHandler => {
+ handler: RequestHandler
+): RequestHandler => {
return async (
context: RequestHandlerContext,
- request: KibanaRequest, TypeOf, TypeOf>,
+ request: KibanaRequest, TypeOf, TypeOf, RouteMethod>,
response: KibanaResponseFactory
) => {
try {
diff --git a/src/core/server/http/router/index.ts b/src/core/server/http/router/index.ts
index f07ad3cfe85c0..35bfb3ba9c33a 100644
--- a/src/core/server/http/router/index.ts
+++ b/src/core/server/http/router/index.ts
@@ -22,11 +22,20 @@ export { Router, RequestHandler, IRouter, RouteRegistrar } from './router';
export {
KibanaRequest,
KibanaRequestRoute,
+ KibanaRequestRouteOptions,
isRealRequest,
LegacyRequest,
ensureRawRequest,
} from './request';
-export { RouteMethod, RouteConfig, RouteConfigOptions } from './route';
+export {
+ RouteMethod,
+ RouteConfig,
+ RouteConfigOptions,
+ RouteSchemas,
+ RouteContentType,
+ RouteConfigOptionsBody,
+ validBodyOutput,
+} from './route';
export { HapiResponseAdapter } from './response_adapter';
export {
CustomHttpResponseOptions,
diff --git a/src/core/server/http/router/request.ts b/src/core/server/http/router/request.ts
index 5d3b70ba27eee..b132899910569 100644
--- a/src/core/server/http/router/request.ts
+++ b/src/core/server/http/router/request.ts
@@ -20,23 +20,32 @@
import { Url } from 'url';
import { Request } from 'hapi';
-import { ObjectType, TypeOf } from '@kbn/config-schema';
+import { ObjectType, Type, TypeOf } from '@kbn/config-schema';
+import { Stream } from 'stream';
import { deepFreeze, RecursiveReadonly } from '../../../utils';
import { Headers } from './headers';
-import { RouteMethod, RouteSchemas, RouteConfigOptions } from './route';
+import { RouteMethod, RouteSchemas, RouteConfigOptions, validBodyOutput } from './route';
import { KibanaSocket, IKibanaSocket } from './socket';
const requestSymbol = Symbol('request');
+/**
+ * Route options: If 'GET' or 'OPTIONS' method, body options won't be returned.
+ * @public
+ */
+export type KibanaRequestRouteOptions = Method extends 'get' | 'options'
+ ? Required, 'body'>>
+ : Required>;
+
/**
* Request specific route information exposed to a handler.
* @public
* */
-export interface KibanaRequestRoute {
+export interface KibanaRequestRoute {
path: string;
- method: RouteMethod | 'patch' | 'options';
- options: Required;
+ method: Method;
+ options: KibanaRequestRouteOptions;
}
/**
@@ -50,17 +59,22 @@ export interface LegacyRequest extends Request {} // eslint-disable-line @typesc
* Kibana specific abstraction for an incoming request.
* @public
*/
-export class KibanaRequest {
+export class KibanaRequest<
+ Params = unknown,
+ Query = unknown,
+ Body = unknown,
+ Method extends RouteMethod = any
+> {
/**
* Factory for creating requests. Validates the request before creating an
* instance of a KibanaRequest.
* @internal
*/
- public static from(
- req: Request,
- routeSchemas?: RouteSchemas,
- withoutSecretHeaders: boolean = true
- ) {
+ public static from<
+ P extends ObjectType,
+ Q extends ObjectType,
+ B extends ObjectType | Type | Type
+ >(req: Request, routeSchemas?: RouteSchemas, withoutSecretHeaders: boolean = true) {
const requestParts = KibanaRequest.validate(req, routeSchemas);
return new KibanaRequest(
req,
@@ -77,7 +91,11 @@ export class KibanaRequest {
* received in the route handler.
* @internal
*/
- private static validate(
+ private static validate<
+ P extends ObjectType,
+ Q extends ObjectType,
+ B extends ObjectType | Type | Type
+ >(
req: Request,
routeSchemas: RouteSchemas | undefined
): {
@@ -113,7 +131,7 @@ export class KibanaRequest {
/** a WHATWG URL standard object. */
public readonly url: Url;
/** matched route details */
- public readonly route: RecursiveReadonly;
+ public readonly route: RecursiveReadonly>;
/**
* Readonly copy of incoming request headers.
* @remarks
@@ -148,15 +166,28 @@ export class KibanaRequest {
this.socket = new KibanaSocket(request.raw.req.socket);
}
- private getRouteInfo() {
+ private getRouteInfo(): KibanaRequestRoute {
const request = this[requestSymbol];
+ const method = request.method as Method;
+ const { parse, maxBytes, allow, output } = request.route.settings.payload || {};
+
+ const options = ({
+ authRequired: request.route.settings.auth !== false,
+ tags: request.route.settings.tags || [],
+ body: ['get', 'options'].includes(method)
+ ? undefined
+ : {
+ parse,
+ maxBytes,
+ accepts: allow,
+ output: output as typeof validBodyOutput[number], // We do not support all the HAPI-supported outputs and TS complains
+ },
+ } as unknown) as KibanaRequestRouteOptions; // TS does not understand this is OK so I'm enforced to do this enforced casting
+
return {
path: request.path,
- method: request.method,
- options: {
- authRequired: request.route.settings.auth !== false,
- tags: request.route.settings.tags || [],
- },
+ method,
+ options,
};
}
}
diff --git a/src/core/server/http/router/route.ts b/src/core/server/http/router/route.ts
index bffa23551dd52..129cf4c922ffd 100644
--- a/src/core/server/http/router/route.ts
+++ b/src/core/server/http/router/route.ts
@@ -17,18 +17,89 @@
* under the License.
*/
-import { ObjectType } from '@kbn/config-schema';
+import { ObjectType, Type } from '@kbn/config-schema';
+import { Stream } from 'stream';
+
/**
* The set of common HTTP methods supported by Kibana routing.
* @public
*/
-export type RouteMethod = 'get' | 'post' | 'put' | 'delete';
+export type RouteMethod = 'get' | 'post' | 'put' | 'delete' | 'patch' | 'options';
+
+/**
+ * The set of valid body.output
+ * @public
+ */
+export const validBodyOutput = ['data', 'stream'] as const;
+
+/**
+ * The set of supported parseable Content-Types
+ * @public
+ */
+export type RouteContentType =
+ | 'application/json'
+ | 'application/*+json'
+ | 'application/octet-stream'
+ | 'application/x-www-form-urlencoded'
+ | 'multipart/form-data'
+ | 'text/*';
+
+/**
+ * Additional body options for a route
+ * @public
+ */
+export interface RouteConfigOptionsBody {
+ /**
+ * A string or an array of strings with the allowed mime types for the endpoint. Use this settings to limit the set of allowed mime types. Note that allowing additional mime types not listed
+ * above will not enable them to be parsed, and if parse is true, the request will result in an error response.
+ *
+ * Default value: allows parsing of the following mime types:
+ * * application/json
+ * * application/*+json
+ * * application/octet-stream
+ * * application/x-www-form-urlencoded
+ * * multipart/form-data
+ * * text/*
+ */
+ accepts?: RouteContentType | RouteContentType[] | string | string[];
+
+ /**
+ * Limits the size of incoming payloads to the specified byte count. Allowing very large payloads may cause the server to run out of memory.
+ *
+ * Default value: The one set in the kibana.yml config file under the parameter `server.maxPayloadBytes`.
+ */
+ maxBytes?: number;
+
+ /**
+ * The processed payload format. The value must be one of:
+ * * 'data' - the incoming payload is read fully into memory. If parse is true, the payload is parsed (JSON, form-decoded, multipart) based on the 'Content-Type' header. If parse is false, a raw
+ * Buffer is returned.
+ * * 'stream' - the incoming payload is made available via a Stream.Readable interface. If the payload is 'multipart/form-data' and parse is true, field values are presented as text while files
+ * are provided as streams. File streams from a 'multipart/form-data' upload will also have a hapi property containing the filename and headers properties. Note that payload streams for multipart
+ * payloads are a synthetic interface created on top of the entire multipart content loaded into memory. To avoid loading large multipart payloads into memory, set parse to false and handle the
+ * multipart payload in the handler using a streaming parser (e.g. pez).
+ *
+ * Default value: 'data', unless no validation.body is provided in the route definition. In that case the default is 'stream' to alleviate memory pressure.
+ */
+ output?: typeof validBodyOutput[number];
+
+ /**
+ * Determines if the incoming payload is processed or presented raw. Available values:
+ * * true - if the request 'Content-Type' matches the allowed mime types set by allow (for the whole payload as well as parts), the payload is converted into an object when possible. If the
+ * format is unknown, a Bad Request (400) error response is sent. Any known content encoding is decoded.
+ * * false - the raw payload is returned unmodified.
+ * * 'gunzip' - the raw payload is returned unmodified after any known content encoding is decoded.
+ *
+ * Default value: true, unless no validation.body is provided in the route definition. In that case the default is false to alleviate memory pressure.
+ */
+ parse?: boolean | 'gunzip';
+}
/**
* Additional route options.
* @public
*/
-export interface RouteConfigOptions {
+export interface RouteConfigOptions {
/**
* A flag shows that authentication for a route:
* `enabled` when true
@@ -42,13 +113,23 @@ export interface RouteConfigOptions {
* Additional metadata tag strings to attach to the route.
*/
tags?: readonly string[];
+
+ /**
+ * Additional body options {@link RouteConfigOptionsBody}.
+ */
+ body?: Method extends 'get' | 'options' ? undefined : RouteConfigOptionsBody;
}
/**
* Route specific configuration.
* @public
*/
-export interface RouteConfig {
+export interface RouteConfig<
+ P extends ObjectType,
+ Q extends ObjectType,
+ B extends ObjectType | Type | Type,
+ Method extends RouteMethod
+> {
/**
* The endpoint _within_ the router path to register the route.
*
@@ -125,7 +206,7 @@ export interface RouteConfig;
}
/**
@@ -133,7 +214,11 @@ export interface RouteConfig
{
+export interface RouteSchemas<
+ P extends ObjectType,
+ Q extends ObjectType,
+ B extends ObjectType | Type | Type
+> {
params?: P;
query?: Q;
body?: B;
diff --git a/src/core/server/http/router/router.test.ts b/src/core/server/http/router/router.test.ts
index 9fdf7297ed775..f5469a95b5106 100644
--- a/src/core/server/http/router/router.test.ts
+++ b/src/core/server/http/router/router.test.ts
@@ -19,6 +19,7 @@
import { Router } from './router';
import { loggingServiceMock } from '../../logging/logging_service.mock';
+import { schema } from '@kbn/config-schema';
const logger = loggingServiceMock.create().get();
const enhanceWithContext = (fn: (...args: any[]) => any) => fn.bind(null, {});
@@ -45,5 +46,46 @@ describe('Router', () => {
`"Expected a valid schema declared with '@kbn/config-schema' package at key: [params]."`
);
});
+
+ it('throws if options.body.output is not a valid value', () => {
+ const router = new Router('', logger, enhanceWithContext);
+ expect(() =>
+ router.post(
+ // we use 'any' because TS already checks we cannot provide this body.output
+ {
+ path: '/',
+ options: { body: { output: 'file' } } as any, // We explicitly don't support 'file'
+ validate: { body: schema.object({}, { allowUnknowns: true }) },
+ },
+ (context, req, res) => res.ok({})
+ )
+ ).toThrowErrorMatchingInlineSnapshot(
+ `"[options.body.output: 'file'] in route POST / is not valid. Only 'data' or 'stream' are valid."`
+ );
+ });
+
+ it('should default `output: "stream" and parse: false` when no body validation is required but not a GET', () => {
+ const router = new Router('', logger, enhanceWithContext);
+ router.post({ path: '/', validate: {} }, (context, req, res) => res.ok({}));
+ const [route] = router.getRoutes();
+ expect(route.options).toEqual({ body: { output: 'stream', parse: false } });
+ });
+
+ it('should NOT default `output: "stream" and parse: false` when the user has specified body options (he cares about it)', () => {
+ const router = new Router('', logger, enhanceWithContext);
+ router.post(
+ { path: '/', options: { body: { maxBytes: 1 } }, validate: {} },
+ (context, req, res) => res.ok({})
+ );
+ const [route] = router.getRoutes();
+ expect(route.options).toEqual({ body: { maxBytes: 1 } });
+ });
+
+ it('should NOT default `output: "stream" and parse: false` when no body validation is required and GET', () => {
+ const router = new Router('', logger, enhanceWithContext);
+ router.get({ path: '/', validate: {} }, (context, req, res) => res.ok({}));
+ const [route] = router.getRoutes();
+ expect(route.options).toEqual({});
+ });
});
});
diff --git a/src/core/server/http/router/router.ts b/src/core/server/http/router/router.ts
index a13eae51a19a6..3bed8fe4186ac 100644
--- a/src/core/server/http/router/router.ts
+++ b/src/core/server/http/router/router.ts
@@ -21,10 +21,17 @@ import { ObjectType, TypeOf, Type } from '@kbn/config-schema';
import { Request, ResponseObject, ResponseToolkit } from 'hapi';
import Boom from 'boom';
+import { Stream } from 'stream';
import { Logger } from '../../logging';
import { KibanaRequest } from './request';
import { KibanaResponseFactory, kibanaResponseFactory, IKibanaResponse } from './response';
-import { RouteConfig, RouteConfigOptions, RouteMethod, RouteSchemas } from './route';
+import {
+ RouteConfig,
+ RouteConfigOptions,
+ RouteMethod,
+ RouteSchemas,
+ validBodyOutput,
+} from './route';
import { HapiResponseAdapter } from './response_adapter';
import { RequestHandlerContext } from '../../../server';
import { wrapErrors } from './error_wrapper';
@@ -32,17 +39,22 @@ import { wrapErrors } from './error_wrapper';
interface RouterRoute {
method: RouteMethod;
path: string;
- options: RouteConfigOptions;
+ options: RouteConfigOptions;
handler: (req: Request, responseToolkit: ResponseToolkit) => Promise>;
}
/**
- * Handler to declare a route.
+ * Route handler common definition
+ *
* @public
*/
-export type RouteRegistrar = (
- route: RouteConfig,
- handler: RequestHandler
+export type RouteRegistrar = <
+ P extends ObjectType,
+ Q extends ObjectType,
+ B extends ObjectType | Type | Type
+>(
+ route: RouteConfig,
+ handler: RequestHandler
) => void;
/**
@@ -62,28 +74,35 @@ export interface IRouter {
* @param route {@link RouteConfig} - a route configuration.
* @param handler {@link RequestHandler} - a function to call to respond to an incoming request
*/
- get: RouteRegistrar;
+ get: RouteRegistrar<'get'>;
/**
* Register a route handler for `POST` request.
* @param route {@link RouteConfig} - a route configuration.
* @param handler {@link RequestHandler} - a function to call to respond to an incoming request
*/
- post: RouteRegistrar;
+ post: RouteRegistrar<'post'>;
/**
* Register a route handler for `PUT` request.
* @param route {@link RouteConfig} - a route configuration.
* @param handler {@link RequestHandler} - a function to call to respond to an incoming request
*/
- put: RouteRegistrar;
+ put: RouteRegistrar<'put'>;
+
+ /**
+ * Register a route handler for `PATCH` request.
+ * @param route {@link RouteConfig} - a route configuration.
+ * @param handler {@link RequestHandler} - a function to call to respond to an incoming request
+ */
+ patch: RouteRegistrar<'patch'>;
/**
* Register a route handler for `DELETE` request.
* @param route {@link RouteConfig} - a route configuration.
* @param handler {@link RequestHandler} - a function to call to respond to an incoming request
*/
- delete: RouteRegistrar;
+ delete: RouteRegistrar<'delete'>;
/**
* Wrap a router handler to catch and converts legacy boom errors to proper custom errors.
@@ -94,16 +113,19 @@ export interface IRouter {
) => RequestHandler;
/**
- * Returns all routes registered with the this router.
+ * Returns all routes registered with this router.
* @returns List of registered routes.
* @internal
*/
getRoutes: () => RouterRoute[];
}
-export type ContextEnhancer = (
- handler: RequestHandler
-) => RequestHandlerEnhanced;
+export type ContextEnhancer<
+ P extends ObjectType,
+ Q extends ObjectType,
+ B extends ObjectType,
+ Method extends RouteMethod
+> = (handler: RequestHandler) => RequestHandlerEnhanced;
function getRouteFullPath(routerPath: string, routePath: string) {
// If router's path ends with slash and route's path starts with slash,
@@ -121,8 +143,8 @@ function getRouteFullPath(routerPath: string, routePath: string) {
function routeSchemasFromRouteConfig<
P extends ObjectType,
Q extends ObjectType,
- B extends ObjectType
->(route: RouteConfig, routeMethod: RouteMethod) {
+ B extends ObjectType | Type | Type
+>(route: RouteConfig, routeMethod: RouteMethod) {
// The type doesn't allow `validate` to be undefined, but it can still
// happen when it's used from JavaScript.
if (route.validate === undefined) {
@@ -144,6 +166,49 @@ function routeSchemasFromRouteConfig<
return route.validate ? route.validate : undefined;
}
+/**
+ * Create a valid options object with "sensible" defaults + adding some validation to the options fields
+ *
+ * @param method HTTP verb for these options
+ * @param routeConfig The route config definition
+ */
+function validOptions(
+ method: RouteMethod,
+ routeConfig: RouteConfig<
+ ObjectType,
+ ObjectType,
+ ObjectType | Type | Type,
+ typeof method
+ >
+) {
+ const shouldNotHavePayload = ['head', 'get'].includes(method);
+ const { options = {}, validate } = routeConfig;
+ const shouldValidateBody = (validate && !!validate.body) || !!options.body;
+
+ const { output } = options.body || {};
+ if (typeof output === 'string' && !validBodyOutput.includes(output)) {
+ throw new Error(
+ `[options.body.output: '${output}'] in route ${method.toUpperCase()} ${
+ routeConfig.path
+ } is not valid. Only '${validBodyOutput.join("' or '")}' are valid.`
+ );
+ }
+
+ const body = shouldNotHavePayload
+ ? undefined
+ : {
+ // If it's not a GET (requires payload) but no body validation is required (or no body options are specified),
+ // We assume the route does not care about the body => use the memory-cheapest approach (stream and no parsing)
+ output: !shouldValidateBody ? ('stream' as const) : undefined,
+ parse: !shouldValidateBody ? false : undefined,
+
+ // User's settings should overwrite any of the "desired" values
+ ...options.body,
+ };
+
+ return { ...options, body };
+}
+
/**
* @internal
*/
@@ -153,21 +218,21 @@ export class Router implements IRouter {
public post: IRouter['post'];
public delete: IRouter['delete'];
public put: IRouter['put'];
+ public patch: IRouter['patch'];
constructor(
public readonly routerPath: string,
private readonly log: Logger,
- private readonly enhanceWithContext: ContextEnhancer
+ private readonly enhanceWithContext: ContextEnhancer
) {
- const buildMethod = (method: RouteMethod) => <
+ const buildMethod = (method: Method) => <
P extends ObjectType,
Q extends ObjectType,
- B extends ObjectType
+ B extends ObjectType | Type | Type
>(
- route: RouteConfig,
- handler: RequestHandler
+ route: RouteConfig,
+ handler: RequestHandler
) => {
- const { path, options = {} } = route;
const routeSchemas = routeSchemasFromRouteConfig(route, method);
this.routes.push({
@@ -179,8 +244,8 @@ export class Router implements IRouter {
handler: this.enhanceWithContext(handler),
}),
method,
- path: getRouteFullPath(this.routerPath, path),
- options,
+ path: getRouteFullPath(this.routerPath, route.path),
+ options: validOptions(method, route),
});
};
@@ -188,6 +253,7 @@ export class Router implements IRouter {
this.post = buildMethod('post');
this.delete = buildMethod('delete');
this.put = buildMethod('put');
+ this.patch = buildMethod('patch');
}
public getRoutes() {
@@ -200,7 +266,11 @@ export class Router implements IRouter {
return wrapErrors(handler);
}
- private async handle({
+ private async handle<
+ P extends ObjectType,
+ Q extends ObjectType,
+ B extends ObjectType | Type | Type
+ >({
routeSchemas,
request,
responseToolkit,
@@ -208,10 +278,10 @@ export class Router implements IRouter {
}: {
request: Request;
responseToolkit: ResponseToolkit;
- handler: RequestHandlerEnhanced;
+ handler: RequestHandlerEnhanced;
routeSchemas?: RouteSchemas;
}) {
- let kibanaRequest: KibanaRequest, TypeOf, TypeOf>;
+ let kibanaRequest: KibanaRequest, TypeOf, TypeOf, typeof request.method>;
const hapiResponseAdapter = new HapiResponseAdapter(responseToolkit);
try {
kibanaRequest = KibanaRequest.from(request, routeSchemas);
@@ -236,8 +306,9 @@ type WithoutHeadArgument = T extends (first: any, ...rest: infer Params) => i
type RequestHandlerEnhanced<
P extends ObjectType,
Q extends ObjectType,
- B extends ObjectType
-> = WithoutHeadArgument>;
+ B extends ObjectType | Type | Type,
+ Method extends RouteMethod
+> = WithoutHeadArgument>;
/**
* A function executed when route path matched requested resource path.
@@ -272,8 +343,13 @@ type RequestHandlerEnhanced<
* ```
* @public
*/
-export type RequestHandler = (
+export type RequestHandler<
+ P extends ObjectType,
+ Q extends ObjectType,
+ B extends ObjectType | Type | Type,
+ Method extends RouteMethod = any
+> = (
context: RequestHandlerContext,
- request: KibanaRequest, TypeOf, TypeOf>,
+ request: KibanaRequest, TypeOf, TypeOf, Method>,
response: KibanaResponseFactory
) => IKibanaResponse | Promise>;
diff --git a/src/core/server/index.ts b/src/core/server/index.ts
index f792f6e604c15..a54ada233bbc9 100644
--- a/src/core/server/index.ts
+++ b/src/core/server/index.ts
@@ -94,6 +94,7 @@ export {
IsAuthenticated,
KibanaRequest,
KibanaRequestRoute,
+ KibanaRequestRouteOptions,
IKibanaResponse,
LifecycleResponseFactory,
KnownHeaders,
@@ -113,9 +114,13 @@ export {
KibanaResponseFactory,
RouteConfig,
IRouter,
+ RouteRegistrar,
RouteMethod,
RouteConfigOptions,
- RouteRegistrar,
+ RouteSchemas,
+ RouteConfigOptionsBody,
+ RouteContentType,
+ validBodyOutput,
SessionStorage,
SessionStorageCookieOptions,
SessionCookieValidationResult,
diff --git a/src/core/server/server.api.md b/src/core/server/server.api.md
index 411e5636069c1..25ca8ade77aca 100644
--- a/src/core/server/server.api.md
+++ b/src/core/server/server.api.md
@@ -449,11 +449,11 @@ export interface AuthToolkit {
export class BasePath {
// @internal
constructor(serverBasePath?: string);
- get: (request: KibanaRequest | LegacyRequest) => string;
+ get: (request: KibanaRequest | LegacyRequest) => string;
prepend: (path: string) => string;
remove: (path: string) => string;
readonly serverBasePath: string;
- set: (request: KibanaRequest | LegacyRequest, requestSpecificBasePath: string) => void;
+ set: (request: KibanaRequest | LegacyRequest, requestSpecificBasePath: string) => void;
}
// Warning: (ae-forgotten-export) The symbol "BootstrapArgs" needs to be exported by the entry point index.d.ts
@@ -718,15 +718,16 @@ export interface IndexSettingsDeprecationInfo {
// @public
export interface IRouter {
- delete: RouteRegistrar;
- get: RouteRegistrar;
+ delete: RouteRegistrar<'delete'>;
+ get: RouteRegistrar<'get'>;
// Warning: (ae-forgotten-export) The symbol "RouterRoute" needs to be exported by the entry point index.d.ts
//
// @internal
getRoutes: () => RouterRoute[];
handleLegacyErrors: (handler: RequestHandler) => RequestHandler;
- post: RouteRegistrar;
- put: RouteRegistrar;
+ patch: RouteRegistrar<'patch'>;
+ post: RouteRegistrar<'post'>;
+ put: RouteRegistrar<'put'>;
routerPath: string;
}
@@ -753,37 +754,38 @@ export interface IUiSettingsClient {
}
// @public
-export class KibanaRequest {
+export class KibanaRequest {
// @internal (undocumented)
protected readonly [requestSymbol]: Request;
constructor(request: Request, params: Params, query: Query, body: Body, withoutSecretHeaders: boolean);
// (undocumented)
readonly body: Body;
- // Warning: (ae-forgotten-export) The symbol "RouteSchemas" needs to be exported by the entry point index.d.ts
- //
// @internal
- static from(req: Request, routeSchemas?: RouteSchemas, withoutSecretHeaders?: boolean): KibanaRequest;
+ static from | Type>(req: Request, routeSchemas?: RouteSchemas, withoutSecretHeaders?: boolean): KibanaRequest;
readonly headers: Headers;
// (undocumented)
readonly params: Params;
// (undocumented)
readonly query: Query;
- readonly route: RecursiveReadonly;
+ readonly route: RecursiveReadonly>;
// (undocumented)
readonly socket: IKibanaSocket;
readonly url: Url;
}
// @public
-export interface KibanaRequestRoute {
+export interface KibanaRequestRoute {
// (undocumented)
- method: RouteMethod | 'patch' | 'options';
+ method: Method;
// (undocumented)
- options: Required;
+ options: KibanaRequestRouteOptions;
// (undocumented)
path: string;
}
+// @public
+export type KibanaRequestRouteOptions = Method extends 'get' | 'options' ? Required, 'body'>> : Required>;
+
// @public
export type KibanaResponseFactory = typeof kibanaResponseFactory;
@@ -1050,7 +1052,7 @@ export type RedirectResponseOptions = HttpResponseOptions & {
};
// @public
-export type RequestHandler = (context: RequestHandlerContext, request: KibanaRequest, TypeOf, TypeOf>, response: KibanaResponseFactory) => IKibanaResponse | Promise>;
+export type RequestHandler | Type, Method extends RouteMethod = any> = (context: RequestHandlerContext, request: KibanaRequest, TypeOf, TypeOf, Method>, response: KibanaResponseFactory) => IKibanaResponse | Promise>;
// @public
export interface RequestHandlerContext {
@@ -1092,23 +1094,45 @@ export type ResponseHeaders = {
};
// @public
-export interface RouteConfig {
- options?: RouteConfigOptions;
+export interface RouteConfig
| Type, Method extends RouteMethod> {
+ options?: RouteConfigOptions;
path: string;
validate: RouteSchemas | false;
}
// @public
-export interface RouteConfigOptions {
+export interface RouteConfigOptions {
authRequired?: boolean;
+ body?: Method extends 'get' | 'options' ? undefined : RouteConfigOptionsBody;
tags?: readonly string[];
}
// @public
-export type RouteMethod = 'get' | 'post' | 'put' | 'delete';
+export interface RouteConfigOptionsBody {
+ accepts?: RouteContentType | RouteContentType[] | string | string[];
+ maxBytes?: number;
+ output?: typeof validBodyOutput[number];
+ parse?: boolean | 'gunzip';
+}
+
+// @public
+export type RouteContentType = 'application/json' | 'application/*+json' | 'application/octet-stream' | 'application/x-www-form-urlencoded' | 'multipart/form-data' | 'text/*';
+
+// @public
+export type RouteMethod = 'get' | 'post' | 'put' | 'delete' | 'patch' | 'options';
// @public
-export type RouteRegistrar = (route: RouteConfig, handler: RequestHandler) => void;
+export type RouteRegistrar = | Type>(route: RouteConfig, handler: RequestHandler) => void;
+
+// @public
+export interface RouteSchemas | Type> {
+ // (undocumented)
+ body?: B;
+ // (undocumented)
+ params?: P;
+ // (undocumented)
+ query?: Q;
+}
// @public (undocumented)
export interface SavedObject {
@@ -1696,6 +1720,9 @@ export interface UserProvidedValues {
userValue?: T;
}
+// @public
+export const validBodyOutput: readonly ["data", "stream"];
+
// Warnings were encountered during analysis:
//
diff --git a/x-pack/legacy/plugins/apm/server/routes/create_api/index.ts b/x-pack/legacy/plugins/apm/server/routes/create_api/index.ts
index 2e97b01d0d108..2bbd8b6ddfb62 100644
--- a/x-pack/legacy/plugins/apm/server/routes/create_api/index.ts
+++ b/x-pack/legacy/plugins/apm/server/routes/create_api/index.ts
@@ -9,7 +9,7 @@ import { schema } from '@kbn/config-schema';
import * as t from 'io-ts';
import { PathReporter } from 'io-ts/lib/PathReporter';
import { isLeft } from 'fp-ts/lib/Either';
-import { KibanaResponseFactory } from 'src/core/server';
+import { KibanaResponseFactory, RouteRegistrar } from 'src/core/server';
import { APMConfig } from '../../../../../../plugins/apm/server';
import {
ServerAPI,
@@ -65,7 +65,7 @@ export function createApi() {
body: bodyRt && 'props' in bodyRt ? t.exact(bodyRt) : fallbackBodyRt
};
- router[routerMethod](
+ (router[routerMethod] as RouteRegistrar)(
{
path,
options,
diff --git a/x-pack/plugins/security/server/routes/authentication/saml.test.ts b/x-pack/plugins/security/server/routes/authentication/saml.test.ts
index cdef1826ddaa8..c8735f9f87f4a 100644
--- a/x-pack/plugins/security/server/routes/authentication/saml.test.ts
+++ b/x-pack/plugins/security/server/routes/authentication/saml.test.ts
@@ -41,8 +41,8 @@ describe('SAML authentication routes', () => {
});
describe('Assertion consumer service endpoint', () => {
- let routeHandler: RequestHandler;
- let routeConfig: RouteConfig;
+ let routeHandler: RequestHandler;
+ let routeConfig: RouteConfig;
beforeEach(() => {
const [acsRouteConfig, acsRouteHandler] = router.post.mock.calls.find(
([{ path }]) => path === '/api/security/saml/callback'