From 07eae13cc3d7b1a7fdc090d150f2dfaf0ec5943f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alejandro=20Ferna=CC=81ndez=20Haro?= Date: Wed, 20 Nov 2019 16:25:40 +0000 Subject: [PATCH] API documentation update --- .../kibana-plugin-server.irouter.delete.md | 2 +- .../kibana-plugin-server.irouter.get.md | 2 +- .../server/kibana-plugin-server.irouter.md | 10 ++-- .../kibana-plugin-server.irouter.options.md | 13 +++++ .../kibana-plugin-server.irouter.patch.md | 13 +++++ .../kibana-plugin-server.irouter.post.md | 2 +- .../kibana-plugin-server.irouter.put.md | 2 +- ...kibana-plugin-server.kibanarequestroute.md | 4 +- ...lugin-server.kibanarequestroute.options.md | 2 +- .../core/server/kibana-plugin-server.md | 3 + .../kibana-plugin-server.requesthandler.md | 2 +- .../kibana-plugin-server.routeconfig.md | 2 +- ...a-plugin-server.routeconfigoptions.body.md | 2 +- ...kibana-plugin-server.routeconfigoptions.md | 2 +- ...na-plugin-server.routeconfigoptionsbody.md | 4 +- ...in-server.routeconfigoptionsbody.output.md | 4 +- ...gin-server.routeconfigoptionsbody.parse.md | 2 +- .../kibana-plugin-server.routemethod.md | 2 +- ...ibana-plugin-server.routerroute.handler.md | 11 ++++ .../kibana-plugin-server.routerroute.md | 23 ++++++++ ...kibana-plugin-server.routerroute.method.md | 11 ++++ ...ibana-plugin-server.routerroute.options.md | 11 ++++ .../kibana-plugin-server.routerroute.path.md | 11 ++++ .../kibana-plugin-server.routeschemas.body.md | 11 ++++ .../kibana-plugin-server.routeschemas.md | 22 +++++++ ...ibana-plugin-server.routeschemas.params.md | 11 ++++ ...kibana-plugin-server.routeschemas.query.md | 11 ++++ .../kibana-plugin-server.validbodyoutput.md | 13 +++++ src/core/server/http/index.ts | 3 + src/core/server/http/router/index.ts | 4 +- src/core/server/http/router/router.ts | 7 ++- src/core/server/index.ts | 3 + src/core/server/server.api.md | 57 +++++++++++++------ 33 files changed, 243 insertions(+), 39 deletions(-) create mode 100644 docs/development/core/server/kibana-plugin-server.irouter.options.md create mode 100644 docs/development/core/server/kibana-plugin-server.irouter.patch.md create mode 100644 docs/development/core/server/kibana-plugin-server.routerroute.handler.md create mode 100644 docs/development/core/server/kibana-plugin-server.routerroute.md create mode 100644 docs/development/core/server/kibana-plugin-server.routerroute.method.md create mode 100644 docs/development/core/server/kibana-plugin-server.routerroute.options.md create mode 100644 docs/development/core/server/kibana-plugin-server.routerroute.path.md create mode 100644 docs/development/core/server/kibana-plugin-server.routeschemas.body.md create mode 100644 docs/development/core/server/kibana-plugin-server.routeschemas.md create mode 100644 docs/development/core/server/kibana-plugin-server.routeschemas.params.md create mode 100644 docs/development/core/server/kibana-plugin-server.routeschemas.query.md create mode 100644 docs/development/core/server/kibana-plugin-server.validbodyoutput.md diff --git a/docs/development/core/server/kibana-plugin-server.irouter.delete.md b/docs/development/core/server/kibana-plugin-server.irouter.delete.md index 46b6d9db2efcf45..1b1d2636a0e0f02 100644 --- a/docs/development/core/server/kibana-plugin-server.irouter.delete.md +++ b/docs/development/core/server/kibana-plugin-server.irouter.delete.md @@ -9,5 +9,5 @@ Register a route handler for `DELETE` request. Signature: ```typescript -delete:

(route: RouteConfig, handler: RequestHandler) => void; +delete:

| Type>(route: RouteConfig, handler: RequestHandler) => void; ``` diff --git a/docs/development/core/server/kibana-plugin-server.irouter.get.md b/docs/development/core/server/kibana-plugin-server.irouter.get.md index 5c072bb5d91f9e9..ba700cfa8685dcd 100644 --- a/docs/development/core/server/kibana-plugin-server.irouter.get.md +++ b/docs/development/core/server/kibana-plugin-server.irouter.get.md @@ -9,5 +9,5 @@ Register a route handler for `GET` request. Signature: ```typescript -get:

(route: RouteConfig, handler: RequestHandler) => void; +get:

(route: RouteConfig, handler: RequestHandler) => void; ``` diff --git a/docs/development/core/server/kibana-plugin-server.irouter.md b/docs/development/core/server/kibana-plugin-server.irouter.md index 9f64cc93a0383a5..000f212b22ce4b9 100644 --- a/docs/development/core/server/kibana-plugin-server.irouter.md +++ b/docs/development/core/server/kibana-plugin-server.irouter.md @@ -16,9 +16,11 @@ export interface IRouter | Property | Type | Description | | --- | --- | --- | -| [delete](./kibana-plugin-server.irouter.delete.md) | <P extends ObjectType, Q extends ObjectType, B extends ObjectType>(route: RouteConfig<P, Q, B, 'delete'>, handler: RequestHandler<P, Q, B>) => void | Register a route handler for DELETE request. | -| [get](./kibana-plugin-server.irouter.get.md) | <P extends ObjectType, Q extends ObjectType, B extends ObjectType>(route: RouteConfig<P, Q, B, 'get'>, handler: RequestHandler<P, Q, B>) => void | Register a route handler for GET request. | -| [post](./kibana-plugin-server.irouter.post.md) | <P extends ObjectType, Q extends ObjectType, B extends ObjectType>(route: RouteConfig<P, Q, B, 'post'>, handler: RequestHandler<P, Q, B>) => void | Register a route handler for POST request. | -| [put](./kibana-plugin-server.irouter.put.md) | <P extends ObjectType, Q extends ObjectType, B extends ObjectType>(route: RouteConfig<P, Q, B, 'put'>, handler: RequestHandler<P, Q, B>) => void | Register a route handler for PUT request. | +| [delete](./kibana-plugin-server.irouter.delete.md) | <P extends ObjectType, Q extends ObjectType, B extends ObjectType | Type<Buffer> | Type<Stream>>(route: RouteConfig<P, Q, B, 'delete'>, handler: RequestHandler<P, Q, B>) => void | Register a route handler for DELETE request. | +| [get](./kibana-plugin-server.irouter.get.md) | <P extends ObjectType, Q extends ObjectType, B extends never>(route: RouteConfig<P, Q, B, 'get'>, handler: RequestHandler<P, Q, B>) => void | Register a route handler for GET request. | +| [options](./kibana-plugin-server.irouter.options.md) | <P extends ObjectType, Q extends ObjectType, B extends never>(route: RouteConfig<P, Q, B, 'options'>, handler: RequestHandler<P, Q, B>) => void | Register a route handler for OPTIONS request. | +| [patch](./kibana-plugin-server.irouter.patch.md) | <P extends ObjectType, Q extends ObjectType, B extends ObjectType | Type<Buffer> | Type<Stream>>(route: RouteConfig<P, Q, B, 'patch'>, handler: RequestHandler<P, Q, B>) => void | Register a route handler for PATCH request. | +| [post](./kibana-plugin-server.irouter.post.md) | <P extends ObjectType, Q extends ObjectType, B extends ObjectType | Type<Buffer> | Type<Stream>>(route: RouteConfig<P, Q, B, 'post'>, handler: RequestHandler<P, Q, B>) => void | Register a route handler for POST request. | +| [put](./kibana-plugin-server.irouter.put.md) | <P extends ObjectType, Q extends ObjectType, B extends ObjectType | Type<Buffer> | Type<Stream>>(route: RouteConfig<P, Q, B, 'put'>, handler: RequestHandler<P, Q, B>) => void | Register a route handler for PUT request. | | [routerPath](./kibana-plugin-server.irouter.routerpath.md) | string | Resulted path | diff --git a/docs/development/core/server/kibana-plugin-server.irouter.options.md b/docs/development/core/server/kibana-plugin-server.irouter.options.md new file mode 100644 index 000000000000000..98714024f9a23c5 --- /dev/null +++ b/docs/development/core/server/kibana-plugin-server.irouter.options.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [IRouter](./kibana-plugin-server.irouter.md) > [options](./kibana-plugin-server.irouter.options.md) + +## IRouter.options property + +Register a route handler for `OPTIONS` request. + +Signature: + +```typescript +options:

(route: RouteConfig, handler: RequestHandler) => void; +``` diff --git a/docs/development/core/server/kibana-plugin-server.irouter.patch.md b/docs/development/core/server/kibana-plugin-server.irouter.patch.md new file mode 100644 index 000000000000000..0f178b1a3a7a0e9 --- /dev/null +++ b/docs/development/core/server/kibana-plugin-server.irouter.patch.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [IRouter](./kibana-plugin-server.irouter.md) > [patch](./kibana-plugin-server.irouter.patch.md) + +## IRouter.patch property + +Register a route handler for `PATCH` request. + +Signature: + +```typescript +patch:

| Type>(route: RouteConfig, handler: RequestHandler) => void; +``` diff --git a/docs/development/core/server/kibana-plugin-server.irouter.post.md b/docs/development/core/server/kibana-plugin-server.irouter.post.md index f6e71c99fcf15a8..7c34b5e0249ef6f 100644 --- a/docs/development/core/server/kibana-plugin-server.irouter.post.md +++ b/docs/development/core/server/kibana-plugin-server.irouter.post.md @@ -9,5 +9,5 @@ Register a route handler for `POST` request. Signature: ```typescript -post:

(route: RouteConfig, handler: RequestHandler) => void; +post:

| Type>(route: RouteConfig, handler: RequestHandler) => void; ``` diff --git a/docs/development/core/server/kibana-plugin-server.irouter.put.md b/docs/development/core/server/kibana-plugin-server.irouter.put.md index d552983dc687121..47732a24101ab82 100644 --- a/docs/development/core/server/kibana-plugin-server.irouter.put.md +++ b/docs/development/core/server/kibana-plugin-server.irouter.put.md @@ -9,5 +9,5 @@ Register a route handler for `PUT` request. Signature: ```typescript -put:

(route: RouteConfig, handler: RequestHandler) => void; +put:

| Type>(route: RouteConfig, handler: RequestHandler) => void; ``` diff --git a/docs/development/core/server/kibana-plugin-server.kibanarequestroute.md b/docs/development/core/server/kibana-plugin-server.kibanarequestroute.md index 6b4bbb7255cb46a..679a8c20bcf648e 100644 --- a/docs/development/core/server/kibana-plugin-server.kibanarequestroute.md +++ b/docs/development/core/server/kibana-plugin-server.kibanarequestroute.md @@ -9,7 +9,7 @@ Request specific route information exposed to a handler. Signature: ```typescript -export interface KibanaRequestRoute +export interface KibanaRequestRoute ``` ## Properties @@ -17,6 +17,6 @@ export interface KibanaRequestRouteMethod | | -| [options](./kibana-plugin-server.kibanarequestroute.options.md) | Method extends 'get' ? Required<Pick<RouteConfigOptions<Method>, 'authRequired' | 'tags'>> : Required<RouteConfigOptions> | | +| [options](./kibana-plugin-server.kibanarequestroute.options.md) | Method extends 'get' ? Required<Omit<RouteConfigOptions<Method>, 'body'>> : Required<RouteConfigOptions> | | | [path](./kibana-plugin-server.kibanarequestroute.path.md) | string | | diff --git a/docs/development/core/server/kibana-plugin-server.kibanarequestroute.options.md b/docs/development/core/server/kibana-plugin-server.kibanarequestroute.options.md index f67ece968f6d943..0fdf321ba51f73b 100644 --- a/docs/development/core/server/kibana-plugin-server.kibanarequestroute.options.md +++ b/docs/development/core/server/kibana-plugin-server.kibanarequestroute.options.md @@ -7,5 +7,5 @@ Signature: ```typescript -options: Method extends 'get' ? Required, 'authRequired' | 'tags'>> : Required; +options: Method extends 'get' ? Required, 'body'>> : Required; ``` diff --git a/docs/development/core/server/kibana-plugin-server.md b/docs/development/core/server/kibana-plugin-server.md index 5255cd7870231ad..4356f9a2f415a9f 100644 --- a/docs/development/core/server/kibana-plugin-server.md +++ b/docs/development/core/server/kibana-plugin-server.md @@ -83,6 +83,8 @@ The plugin integrates with the core system via lifecycle events: `setup` | [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 | +| [RouterRoute](./kibana-plugin-server.routerroute.md) | Definition of 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. | @@ -127,6 +129,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 diff --git a/docs/development/core/server/kibana-plugin-server.requesthandler.md b/docs/development/core/server/kibana-plugin-server.requesthandler.md index 035d16c9fca3c02..d6b525b805a4163 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> = (context: RequestHandlerContext, request: KibanaRequest, TypeOf, TypeOf>, 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 cb0b7ae9f435b53..1970b23c7ec099c 100644 --- a/docs/development/core/server/kibana-plugin-server.routeconfig.md +++ b/docs/development/core/server/kibana-plugin-server.routeconfig.md @@ -9,7 +9,7 @@ Route specific configuration. Signature: ```typescript -export interface RouteConfig

+export interface RouteConfig

| Type, Method extends RouteMethod> ``` ## Properties diff --git a/docs/development/core/server/kibana-plugin-server.routeconfigoptions.body.md b/docs/development/core/server/kibana-plugin-server.routeconfigoptions.body.md index ed195ca4696cf59..0937456c6df360a 100644 --- a/docs/development/core/server/kibana-plugin-server.routeconfigoptions.body.md +++ b/docs/development/core/server/kibana-plugin-server.routeconfigoptions.body.md @@ -9,5 +9,5 @@ Additional body options [RouteConfigOptionsBody](./kibana-plugin-server.routecon Signature: ```typescript -body?: Method extends 'get' ? never : RouteConfigOptionsBody; +body?: Method extends 'get' | 'options' ? never : RouteConfigOptionsBody; ``` diff --git a/docs/development/core/server/kibana-plugin-server.routeconfigoptions.md b/docs/development/core/server/kibana-plugin-server.routeconfigoptions.md index dc9a738c367a14e..b16d79c969868c1 100644 --- a/docs/development/core/server/kibana-plugin-server.routeconfigoptions.md +++ b/docs/development/core/server/kibana-plugin-server.routeconfigoptions.md @@ -17,6 +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' ? never : RouteConfigOptionsBody | Additional body options [RouteConfigOptionsBody](./kibana-plugin-server.routeconfigoptionsbody.md). | +| [body](./kibana-plugin-server.routeconfigoptions.body.md) | Method extends 'get' | 'options' ? never : 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.md b/docs/development/core/server/kibana-plugin-server.routeconfigoptionsbody.md index 77d0442f7f05f52..6ef04de459fcf25 100644 --- a/docs/development/core/server/kibana-plugin-server.routeconfigoptionsbody.md +++ b/docs/development/core/server/kibana-plugin-server.routeconfigoptionsbody.md @@ -18,6 +18,6 @@ export interface RouteConfigOptionsBody | --- | --- | --- | | [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) | 'data' | 'stream' | 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'. | -| [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. | +| [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 index 57e497e3c6ee621..b84bc709df3eca5 100644 --- a/docs/development/core/server/kibana-plugin-server.routeconfigoptionsbody.output.md +++ b/docs/development/core/server/kibana-plugin-server.routeconfigoptionsbody.output.md @@ -6,10 +6,10 @@ 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'. +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?: 'data' | 'stream'; +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 index cb4c5defd053eeb..d395f67c6966908 100644 --- a/docs/development/core/server/kibana-plugin-server.routeconfigoptionsbody.parse.md +++ b/docs/development/core/server/kibana-plugin-server.routeconfigoptionsbody.parse.md @@ -6,7 +6,7 @@ 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. +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: diff --git a/docs/development/core/server/kibana-plugin-server.routemethod.md b/docs/development/core/server/kibana-plugin-server.routemethod.md index dd1a050708bb352..4f83344f842b3cb 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.routerroute.handler.md b/docs/development/core/server/kibana-plugin-server.routerroute.handler.md new file mode 100644 index 000000000000000..0d4e492744a713e --- /dev/null +++ b/docs/development/core/server/kibana-plugin-server.routerroute.handler.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [RouterRoute](./kibana-plugin-server.routerroute.md) > [handler](./kibana-plugin-server.routerroute.handler.md) + +## RouterRoute.handler property + +Signature: + +```typescript +handler: (req: Request, responseToolkit: ResponseToolkit) => Promise>; +``` diff --git a/docs/development/core/server/kibana-plugin-server.routerroute.md b/docs/development/core/server/kibana-plugin-server.routerroute.md new file mode 100644 index 000000000000000..034a3d6de36e947 --- /dev/null +++ b/docs/development/core/server/kibana-plugin-server.routerroute.md @@ -0,0 +1,23 @@ + + +[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [RouterRoute](./kibana-plugin-server.routerroute.md) + +## RouterRoute interface + +Definition of a route + +Signature: + +```typescript +export interface RouterRoute +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [handler](./kibana-plugin-server.routerroute.handler.md) | (req: Request, responseToolkit: ResponseToolkit) => Promise<ResponseObject | Boom<any>> | | +| [method](./kibana-plugin-server.routerroute.method.md) | RouteMethod | | +| [options](./kibana-plugin-server.routerroute.options.md) | RouteConfigOptions | | +| [path](./kibana-plugin-server.routerroute.path.md) | string | | + diff --git a/docs/development/core/server/kibana-plugin-server.routerroute.method.md b/docs/development/core/server/kibana-plugin-server.routerroute.method.md new file mode 100644 index 000000000000000..9a2382c068a0faa --- /dev/null +++ b/docs/development/core/server/kibana-plugin-server.routerroute.method.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [RouterRoute](./kibana-plugin-server.routerroute.md) > [method](./kibana-plugin-server.routerroute.method.md) + +## RouterRoute.method property + +Signature: + +```typescript +method: RouteMethod; +``` diff --git a/docs/development/core/server/kibana-plugin-server.routerroute.options.md b/docs/development/core/server/kibana-plugin-server.routerroute.options.md new file mode 100644 index 000000000000000..c0a4c6561528b88 --- /dev/null +++ b/docs/development/core/server/kibana-plugin-server.routerroute.options.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [RouterRoute](./kibana-plugin-server.routerroute.md) > [options](./kibana-plugin-server.routerroute.options.md) + +## RouterRoute.options property + +Signature: + +```typescript +options: RouteConfigOptions; +``` diff --git a/docs/development/core/server/kibana-plugin-server.routerroute.path.md b/docs/development/core/server/kibana-plugin-server.routerroute.path.md new file mode 100644 index 000000000000000..3e8b449931520e0 --- /dev/null +++ b/docs/development/core/server/kibana-plugin-server.routerroute.path.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [RouterRoute](./kibana-plugin-server.routerroute.md) > [path](./kibana-plugin-server.routerroute.path.md) + +## RouterRoute.path property + +Signature: + +```typescript +path: string; +``` 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 000000000000000..78a9d25c25d9d62 --- /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 000000000000000..77b980551a8ffe4 --- /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 000000000000000..3dbf9fed94dc092 --- /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 000000000000000..5be5830cb4bc87f --- /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 000000000000000..ea866abf887fb83 --- /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/src/core/server/http/index.ts b/src/core/server/http/index.ts index 22f7e88f4a0c83f..63fb2ebbc600478 100644 --- a/src/core/server/http/index.ts +++ b/src/core/server/http/index.ts @@ -43,10 +43,13 @@ export { KibanaResponseFactory, RouteConfig, IRouter, + RouterRoute, RouteMethod, 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/index.ts b/src/core/server/http/router/index.ts index 9ecc046acd6b65e..36bbc2fd4c65f19 100644 --- a/src/core/server/http/router/index.ts +++ b/src/core/server/http/router/index.ts @@ -18,7 +18,7 @@ */ export { Headers, filterHeaders, ResponseHeaders, KnownHeaders } from './headers'; -export { Router, RequestHandler, IRouter } from './router'; +export { Router, RequestHandler, IRouter, RouterRoute } from './router'; export { KibanaRequest, KibanaRequestRoute, @@ -30,8 +30,10 @@ export { RouteMethod, RouteConfig, RouteConfigOptions, + RouteSchemas, RouteContentType, RouteConfigOptionsBody, + validBodyOutput, } from './route'; export { HapiResponseAdapter } from './response_adapter'; export { diff --git a/src/core/server/http/router/router.ts b/src/core/server/http/router/router.ts index 212a5c9c5bbc835..f3ea2099311e63b 100644 --- a/src/core/server/http/router/router.ts +++ b/src/core/server/http/router/router.ts @@ -35,7 +35,12 @@ import { import { HapiResponseAdapter } from './response_adapter'; import { RequestHandlerContext } from '../../../server'; -interface RouterRoute { +/** + * Definition of a route + * + * @public + */ +export interface RouterRoute { method: RouteMethod; path: string; options: RouteConfigOptions; diff --git a/src/core/server/index.ts b/src/core/server/index.ts index a02e2a9a7042d8b..86121e2eda7192e 100644 --- a/src/core/server/index.ts +++ b/src/core/server/index.ts @@ -112,10 +112,13 @@ export { KibanaResponseFactory, RouteConfig, IRouter, + RouterRoute, RouteMethod, RouteConfigOptions, + RouteSchemas, RouteConfigOptionsBody, RouteContentType, + validBodyOutput, SessionStorage, SessionStorageCookieOptions, SessionStorageFactory, diff --git a/src/core/server/server.api.md b/src/core/server/server.api.md index 3143c18a3485359..bc30f4eff6179b8 100644 --- a/src/core/server/server.api.md +++ b/src/core/server/server.api.md @@ -714,14 +714,14 @@ export interface IndexSettingsDeprecationInfo { // @public export interface IRouter { - delete:

(route: RouteConfig, handler: RequestHandler) => void; - get:

(route: RouteConfig, handler: RequestHandler) => void; - // Warning: (ae-forgotten-export) The symbol "RouterRoute" needs to be exported by the entry point index.d.ts - // + delete:

| Type>(route: RouteConfig, handler: RequestHandler) => void; + get:

(route: RouteConfig, handler: RequestHandler) => void; // @internal getRoutes: () => RouterRoute[]; - post:

(route: RouteConfig, handler: RequestHandler) => void; - put:

(route: RouteConfig, handler: RequestHandler) => void; + options:

(route: RouteConfig, handler: RequestHandler) => void; + patch:

| Type>(route: RouteConfig, handler: RequestHandler) => void; + post:

| Type>(route: RouteConfig, handler: RequestHandler) => void; + put:

| Type>(route: RouteConfig, handler: RequestHandler) => void; routerPath: string; } @@ -751,10 +751,8 @@ export class KibanaRequest { 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; @@ -767,11 +765,11 @@ export class KibanaRequest { } // @public -export interface KibanaRequestRoute { +export interface KibanaRequestRoute { // (undocumented) method: Method; // (undocumented) - options: Method extends 'get' ? Required, 'authRequired' | 'tags'>> : Required; + options: Method extends 'get' ? Required, 'body'>> : Required; // (undocumented) path: string; } @@ -1030,7 +1028,7 @@ export type RedirectResponseOptions = HttpResponseOptions & { }; // @public -export type RequestHandler

= (context: RequestHandlerContext, request: KibanaRequest, TypeOf, TypeOf>, response: KibanaResponseFactory) => IKibanaResponse | Promise>; +export type RequestHandler

| Type> = (context: RequestHandlerContext, request: KibanaRequest, TypeOf, TypeOf>, response: KibanaResponseFactory) => IKibanaResponse | Promise>; // @public export interface RequestHandlerContext { @@ -1072,7 +1070,7 @@ export type ResponseHeaders = { }; // @public -export interface RouteConfig

{ +export interface RouteConfig

| Type, Method extends RouteMethod> { options?: RouteConfigOptions; path: string; validate: RouteSchemas | false; @@ -1081,7 +1079,7 @@ export interface RouteConfig

{ authRequired?: boolean; - body?: Method extends 'get' ? never : RouteConfigOptionsBody; + body?: Method extends 'get' | 'options' ? never : RouteConfigOptionsBody; tags?: readonly string[]; } @@ -1089,7 +1087,7 @@ export interface RouteConfigOptions { export interface RouteConfigOptionsBody { accepts?: RouteContentType | RouteContentType[] | string | string[]; maxBytes?: number; - output?: 'data' | 'stream'; + output?: typeof validBodyOutput[number]; parse?: boolean | 'gunzip'; } @@ -1097,7 +1095,29 @@ export interface RouteConfigOptionsBody { 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'; +export type RouteMethod = 'get' | 'post' | 'put' | 'delete' | 'patch' | 'options'; + +// @public +export interface RouterRoute { + // (undocumented) + handler: (req: Request, responseToolkit: ResponseToolkit) => Promise>; + // (undocumented) + method: RouteMethod; + // (undocumented) + options: RouteConfigOptions; + // (undocumented) + path: string; +} + +// @public +export interface RouteSchemas

| Type> { + // (undocumented) + body?: B; + // (undocumented) + params?: P; + // (undocumented) + query?: Q; +} // @public (undocumented) export interface SavedObject { @@ -1623,6 +1643,11 @@ export interface UserProvidedValues { userValue?: T; } +// Warning: (ae-missing-release-tag) "validBodyOutput" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) +// +// @public +export const validBodyOutput: readonly ["data", "stream"]; + // Warnings were encountered during analysis: //