mirror of
https://github.com/elastic/kibana.git
synced 2025-04-23 17:28:26 -04:00
* improving naming, add TSDoc * re-genereate docs * use response name in migration guide * Apply suggestions from code review Co-Authored-By: Josh Dover <me@joshdover.com> * place docs near the related code * re-generate docs * mark code as example to reduce noise in http-service.md
This commit is contained in:
parent
ee3b21f698
commit
c2aafcff93
65 changed files with 1259 additions and 152 deletions
|
@ -0,0 +1,22 @@
|
|||
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
|
||||
|
||||
[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [AuthStatus](./kibana-plugin-server.authstatus.md)
|
||||
|
||||
## AuthStatus enum
|
||||
|
||||
Status indicating an outcome of the authentication.
|
||||
|
||||
<b>Signature:</b>
|
||||
|
||||
```typescript
|
||||
export declare enum AuthStatus
|
||||
```
|
||||
|
||||
## Enumeration Members
|
||||
|
||||
| Member | Value | Description |
|
||||
| --- | --- | --- |
|
||||
| authenticated | <code>"authenticated"</code> | <code>auth</code> interceptor successfully authenticated a user |
|
||||
| unauthenticated | <code>"unauthenticated"</code> | <code>auth</code> interceptor failed user authentication |
|
||||
| unknown | <code>"unknown"</code> | <code>auth</code> interceptor has not been registered |
|
||||
|
|
@ -0,0 +1,20 @@
|
|||
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
|
||||
|
||||
[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [CustomHttpResponseOptions](./kibana-plugin-server.customhttpresponseoptions.md)
|
||||
|
||||
## CustomHttpResponseOptions interface
|
||||
|
||||
HTTP response parameters for a response with adjustable status code.
|
||||
|
||||
<b>Signature:</b>
|
||||
|
||||
```typescript
|
||||
export interface CustomHttpResponseOptions extends HttpResponseOptions
|
||||
```
|
||||
|
||||
## Properties
|
||||
|
||||
| Property | Type | Description |
|
||||
| --- | --- | --- |
|
||||
| [statusCode](./kibana-plugin-server.customhttpresponseoptions.statuscode.md) | <code>number</code> | |
|
||||
|
|
@ -0,0 +1,11 @@
|
|||
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
|
||||
|
||||
[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [CustomHttpResponseOptions](./kibana-plugin-server.customhttpresponseoptions.md) > [statusCode](./kibana-plugin-server.customhttpresponseoptions.statuscode.md)
|
||||
|
||||
## CustomHttpResponseOptions.statusCode property
|
||||
|
||||
<b>Signature:</b>
|
||||
|
||||
```typescript
|
||||
statusCode: number;
|
||||
```
|
|
@ -9,5 +9,5 @@ Get headers to authenticate a user against Elasticsearch.
|
|||
<b>Signature:</b>
|
||||
|
||||
```typescript
|
||||
export declare type GetAuthHeaders = (request: KibanaRequest | Request) => AuthHeaders | undefined;
|
||||
export declare type GetAuthHeaders = (request: KibanaRequest | LegacyRequest) => AuthHeaders | undefined;
|
||||
```
|
||||
|
|
|
@ -0,0 +1,16 @@
|
|||
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
|
||||
|
||||
[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [GetAuthState](./kibana-plugin-server.getauthstate.md)
|
||||
|
||||
## GetAuthState type
|
||||
|
||||
Get authentication state for a request. Returned by `auth` interceptor.
|
||||
|
||||
<b>Signature:</b>
|
||||
|
||||
```typescript
|
||||
export declare type GetAuthState = (request: KibanaRequest | LegacyRequest) => {
|
||||
status: AuthStatus;
|
||||
state: unknown;
|
||||
};
|
||||
```
|
|
@ -4,9 +4,14 @@
|
|||
|
||||
## Headers type
|
||||
|
||||
Http request headers to read.
|
||||
|
||||
<b>Signature:</b>
|
||||
|
||||
```typescript
|
||||
export declare type Headers = Record<string, string | string[] | undefined>;
|
||||
export declare type Headers = {
|
||||
[header in KnownHeaders]?: string | string[] | undefined;
|
||||
} & {
|
||||
[header: string]: string | string[] | undefined;
|
||||
};
|
||||
```
|
||||
|
|
|
@ -0,0 +1,13 @@
|
|||
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
|
||||
|
||||
[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [HttpResponseOptions](./kibana-plugin-server.httpresponseoptions.md) > [headers](./kibana-plugin-server.httpresponseoptions.headers.md)
|
||||
|
||||
## HttpResponseOptions.headers property
|
||||
|
||||
HTTP Headers with additional information about response
|
||||
|
||||
<b>Signature:</b>
|
||||
|
||||
```typescript
|
||||
headers?: ResponseHeaders;
|
||||
```
|
|
@ -0,0 +1,20 @@
|
|||
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
|
||||
|
||||
[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [HttpResponseOptions](./kibana-plugin-server.httpresponseoptions.md)
|
||||
|
||||
## HttpResponseOptions interface
|
||||
|
||||
HTTP response parameters
|
||||
|
||||
<b>Signature:</b>
|
||||
|
||||
```typescript
|
||||
export interface HttpResponseOptions
|
||||
```
|
||||
|
||||
## Properties
|
||||
|
||||
| Property | Type | Description |
|
||||
| --- | --- | --- |
|
||||
| [headers](./kibana-plugin-server.httpresponseoptions.headers.md) | <code>ResponseHeaders</code> | HTTP Headers with additional information about response |
|
||||
|
|
@ -0,0 +1,13 @@
|
|||
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
|
||||
|
||||
[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [HttpResponsePayload](./kibana-plugin-server.httpresponsepayload.md)
|
||||
|
||||
## HttpResponsePayload type
|
||||
|
||||
Data send to the client as a response payload.
|
||||
|
||||
<b>Signature:</b>
|
||||
|
||||
```typescript
|
||||
export declare type HttpResponsePayload = undefined | string | Record<string, any> | Buffer | Stream;
|
||||
```
|
|
@ -0,0 +1,15 @@
|
|||
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
|
||||
|
||||
[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [HttpServerSetup](./kibana-plugin-server.httpserversetup.md) > [auth](./kibana-plugin-server.httpserversetup.auth.md)
|
||||
|
||||
## HttpServerSetup.auth property
|
||||
|
||||
<b>Signature:</b>
|
||||
|
||||
```typescript
|
||||
auth: {
|
||||
get: GetAuthState;
|
||||
isAuthenticated: IsAuthenticated;
|
||||
getAuthHeaders: GetAuthHeaders;
|
||||
};
|
||||
```
|
|
@ -0,0 +1,16 @@
|
|||
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
|
||||
|
||||
[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [HttpServerSetup](./kibana-plugin-server.httpserversetup.md) > [basePath](./kibana-plugin-server.httpserversetup.basepath.md)
|
||||
|
||||
## HttpServerSetup.basePath property
|
||||
|
||||
<b>Signature:</b>
|
||||
|
||||
```typescript
|
||||
basePath: {
|
||||
get: (request: KibanaRequest | LegacyRequest) => string;
|
||||
set: (request: KibanaRequest | LegacyRequest, basePath: string) => void;
|
||||
prepend: (url: string) => string;
|
||||
remove: (url: string) => string;
|
||||
};
|
||||
```
|
|
@ -0,0 +1,13 @@
|
|||
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
|
||||
|
||||
[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [HttpServerSetup](./kibana-plugin-server.httpserversetup.md) > [createCookieSessionStorageFactory](./kibana-plugin-server.httpserversetup.createcookiesessionstoragefactory.md)
|
||||
|
||||
## HttpServerSetup.createCookieSessionStorageFactory property
|
||||
|
||||
Creates cookie based session storage factory [SessionStorageFactory](./kibana-plugin-server.sessionstoragefactory.md)
|
||||
|
||||
<b>Signature:</b>
|
||||
|
||||
```typescript
|
||||
createCookieSessionStorageFactory: <T>(cookieOptions: SessionStorageCookieOptions<T>) => Promise<SessionStorageFactory<T>>;
|
||||
```
|
|
@ -0,0 +1,13 @@
|
|||
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
|
||||
|
||||
[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [HttpServerSetup](./kibana-plugin-server.httpserversetup.md) > [isTlsEnabled](./kibana-plugin-server.httpserversetup.istlsenabled.md)
|
||||
|
||||
## HttpServerSetup.isTlsEnabled property
|
||||
|
||||
Flag showing whether a server was configured to use TLS connection.
|
||||
|
||||
<b>Signature:</b>
|
||||
|
||||
```typescript
|
||||
isTlsEnabled: boolean;
|
||||
```
|
|
@ -0,0 +1,93 @@
|
|||
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
|
||||
|
||||
[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [HttpServerSetup](./kibana-plugin-server.httpserversetup.md)
|
||||
|
||||
## HttpServerSetup interface
|
||||
|
||||
Kibana HTTP Service provides own abstraction for work with HTTP stack. Plugins don't have direct access to `hapi` server and its primitives anymore. Moreover, plugins shouldn't rely on the fact that HTTP Service uses one or another library under the hood. This gives the platform flexibility to upgrade or changing our internal HTTP stack without breaking plugins. If the HTTP Service lacks functionality you need, we are happy to discuss and support your needs.
|
||||
|
||||
<b>Signature:</b>
|
||||
|
||||
```typescript
|
||||
export interface HttpServerSetup
|
||||
```
|
||||
|
||||
## Properties
|
||||
|
||||
| Property | Type | Description |
|
||||
| --- | --- | --- |
|
||||
| [auth](./kibana-plugin-server.httpserversetup.auth.md) | <code>{</code><br/><code> get: GetAuthState;</code><br/><code> isAuthenticated: IsAuthenticated;</code><br/><code> getAuthHeaders: GetAuthHeaders;</code><br/><code> }</code> | |
|
||||
| [basePath](./kibana-plugin-server.httpserversetup.basepath.md) | <code>{</code><br/><code> get: (request: KibanaRequest | LegacyRequest) => string;</code><br/><code> set: (request: KibanaRequest | LegacyRequest, basePath: string) => void;</code><br/><code> prepend: (url: string) => string;</code><br/><code> remove: (url: string) => string;</code><br/><code> }</code> | |
|
||||
| [createCookieSessionStorageFactory](./kibana-plugin-server.httpserversetup.createcookiesessionstoragefactory.md) | <code><T>(cookieOptions: SessionStorageCookieOptions<T>) => Promise<SessionStorageFactory<T>></code> | Creates cookie based session storage factory [SessionStorageFactory](./kibana-plugin-server.sessionstoragefactory.md) |
|
||||
| [isTlsEnabled](./kibana-plugin-server.httpserversetup.istlsenabled.md) | <code>boolean</code> | Flag showing whether a server was configured to use TLS connection. |
|
||||
| [registerAuth](./kibana-plugin-server.httpserversetup.registerauth.md) | <code>(handler: AuthenticationHandler) => void</code> | To define custom authentication and/or authorization mechanism for incoming requests. A handler should return a state to associate with the incoming request. The state can be retrieved later via http.auth.get(..) Only one AuthenticationHandler can be registered. |
|
||||
| [registerOnPostAuth](./kibana-plugin-server.httpserversetup.registeronpostauth.md) | <code>(handler: OnPostAuthHandler) => void</code> | To define custom logic to perform for incoming requests. Runs the handler after Auth interceptor did make sure a user has access to the requested resource. The auth state is available at stage via http.auth.get(..) Can register any number of registerOnPreAuth, which are called in sequence (from the first registered to the last). |
|
||||
| [registerOnPreAuth](./kibana-plugin-server.httpserversetup.registeronpreauth.md) | <code>(handler: OnPreAuthHandler) => void</code> | To define custom logic to perform for incoming requests. Runs the handler before Auth interceptor performs a check that user has access to requested resources, so it's the only place when you can forward a request to another URL right on the server. Can register any number of registerOnPostAuth, which are called in sequence (from the first registered to the last). |
|
||||
| [registerRouter](./kibana-plugin-server.httpserversetup.registerrouter.md) | <code>(router: Router) => void</code> | Add all the routes registered with <code>router</code> to HTTP server request listeners. |
|
||||
| [server](./kibana-plugin-server.httpserversetup.server.md) | <code>Server</code> | |
|
||||
|
||||
## Example
|
||||
|
||||
To handle an incoming request in your plugin you should: - Create a `Router` instance. Use `plugin-id` as a prefix path segment for your routes.
|
||||
|
||||
```ts
|
||||
import { Router } from 'src/core/server';
|
||||
const router = new Router('my-app');
|
||||
|
||||
```
|
||||
- Use `@kbn/config-schema` package to create a schema to validate the request `params`<!-- -->, `query`<!-- -->, and `body`<!-- -->. Every incoming request will be validated against the created schema. If validation failed, the request is rejected with `400` status and `Bad request` error without calling the route's handler. To opt out of validating the request, specify `false`<!-- -->.
|
||||
|
||||
```ts
|
||||
import { schema, TypeOf } from '@kbn/config-schema';
|
||||
const validate = {
|
||||
params: schema.object({
|
||||
id: schema.string(),
|
||||
}),
|
||||
};
|
||||
|
||||
```
|
||||
- Declare a function to respond to incoming request. The function will receive `request` object containing request details: url, headers, matched route, as well as validated `params`<!-- -->, `query`<!-- -->, `body`<!-- -->. And `response` object instructing HTTP server to create HTTP response with information sent back to the client as the response body, headers, and HTTP status. Unlike, `hapi` route handler in the Legacy platform, any exception raised during the handler call will generate `500 Server error` response and log error details for further investigation. See below for returning custom error responses.
|
||||
|
||||
```ts
|
||||
const handler = async (request: KibanaRequest, response: ResponseFactory) => {
|
||||
const data = await findObject(request.params.id);
|
||||
// creates a command to respond with 'not found' error
|
||||
if (!data) return response.notFound();
|
||||
// creates a command to send found data to the client and set response headers
|
||||
return response.ok(data, {
|
||||
headers: {
|
||||
'content-type': 'application/json'
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
```
|
||||
- Register route handler for GET request to 'my-app/path/<!-- -->{<!-- -->id<!-- -->}<!-- -->' path
|
||||
|
||||
```ts
|
||||
import { schema, TypeOf } from '@kbn/config-schema';
|
||||
import { Router } from 'src/core/server';
|
||||
const router = new Router('my-app');
|
||||
|
||||
const validate = {
|
||||
params: schema.object({
|
||||
id: schema.string(),
|
||||
}),
|
||||
};
|
||||
|
||||
router.get({
|
||||
path: 'path/{id}',
|
||||
validate
|
||||
},
|
||||
async (request, response) => {
|
||||
const data = await findObject(request.params.id);
|
||||
if (!data) return response.notFound();
|
||||
return response.ok(data, {
|
||||
headers: {
|
||||
'content-type': 'application/json'
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
```
|
||||
|
|
@ -0,0 +1,13 @@
|
|||
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
|
||||
|
||||
[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [HttpServerSetup](./kibana-plugin-server.httpserversetup.md) > [registerAuth](./kibana-plugin-server.httpserversetup.registerauth.md)
|
||||
|
||||
## HttpServerSetup.registerAuth property
|
||||
|
||||
To define custom authentication and/or authorization mechanism for incoming requests. A handler should return a state to associate with the incoming request. The state can be retrieved later via http.auth.get(..) Only one AuthenticationHandler can be registered.
|
||||
|
||||
<b>Signature:</b>
|
||||
|
||||
```typescript
|
||||
registerAuth: (handler: AuthenticationHandler) => void;
|
||||
```
|
|
@ -0,0 +1,13 @@
|
|||
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
|
||||
|
||||
[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [HttpServerSetup](./kibana-plugin-server.httpserversetup.md) > [registerOnPostAuth](./kibana-plugin-server.httpserversetup.registeronpostauth.md)
|
||||
|
||||
## HttpServerSetup.registerOnPostAuth property
|
||||
|
||||
To define custom logic to perform for incoming requests. Runs the handler after Auth interceptor did make sure a user has access to the requested resource. The auth state is available at stage via http.auth.get(..) Can register any number of registerOnPreAuth, which are called in sequence (from the first registered to the last).
|
||||
|
||||
<b>Signature:</b>
|
||||
|
||||
```typescript
|
||||
registerOnPostAuth: (handler: OnPostAuthHandler) => void;
|
||||
```
|
|
@ -0,0 +1,13 @@
|
|||
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
|
||||
|
||||
[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [HttpServerSetup](./kibana-plugin-server.httpserversetup.md) > [registerOnPreAuth](./kibana-plugin-server.httpserversetup.registeronpreauth.md)
|
||||
|
||||
## HttpServerSetup.registerOnPreAuth property
|
||||
|
||||
To define custom logic to perform for incoming requests. Runs the handler before Auth interceptor performs a check that user has access to requested resources, so it's the only place when you can forward a request to another URL right on the server. Can register any number of registerOnPostAuth, which are called in sequence (from the first registered to the last).
|
||||
|
||||
<b>Signature:</b>
|
||||
|
||||
```typescript
|
||||
registerOnPreAuth: (handler: OnPreAuthHandler) => void;
|
||||
```
|
|
@ -0,0 +1,13 @@
|
|||
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
|
||||
|
||||
[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [HttpServerSetup](./kibana-plugin-server.httpserversetup.md) > [registerRouter](./kibana-plugin-server.httpserversetup.registerrouter.md)
|
||||
|
||||
## HttpServerSetup.registerRouter property
|
||||
|
||||
Add all the routes registered with `router` to HTTP server request listeners.
|
||||
|
||||
<b>Signature:</b>
|
||||
|
||||
```typescript
|
||||
registerRouter: (router: Router) => void;
|
||||
```
|
|
@ -0,0 +1,11 @@
|
|||
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
|
||||
|
||||
[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [HttpServerSetup](./kibana-plugin-server.httpserversetup.md) > [server](./kibana-plugin-server.httpserversetup.server.md)
|
||||
|
||||
## HttpServerSetup.server property
|
||||
|
||||
<b>Signature:</b>
|
||||
|
||||
```typescript
|
||||
server: Server;
|
||||
```
|
|
@ -0,0 +1,13 @@
|
|||
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
|
||||
|
||||
[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [IsAuthenticated](./kibana-plugin-server.isauthenticated.md)
|
||||
|
||||
## IsAuthenticated type
|
||||
|
||||
Return authentication status for a request.
|
||||
|
||||
<b>Signature:</b>
|
||||
|
||||
```typescript
|
||||
export declare type IsAuthenticated = (request: KibanaRequest | LegacyRequest) => boolean;
|
||||
```
|
|
@ -26,6 +26,6 @@ export declare class KibanaRequest<Params = unknown, Query = unknown, Body = unk
|
|||
| [headers](./kibana-plugin-server.kibanarequest.headers.md) | | <code>Headers</code> | Readonly copy of incoming request headers. |
|
||||
| [params](./kibana-plugin-server.kibanarequest.params.md) | | <code>Params</code> | |
|
||||
| [query](./kibana-plugin-server.kibanarequest.query.md) | | <code>Query</code> | |
|
||||
| [route](./kibana-plugin-server.kibanarequest.route.md) | | <code>RecursiveReadonly<KibanaRequestRoute></code> | |
|
||||
| [url](./kibana-plugin-server.kibanarequest.url.md) | | <code>Url</code> | |
|
||||
| [route](./kibana-plugin-server.kibanarequest.route.md) | | <code>RecursiveReadonly<KibanaRequestRoute></code> | matched route details |
|
||||
| [url](./kibana-plugin-server.kibanarequest.url.md) | | <code>Url</code> | a WHATWG URL standard object. |
|
||||
|
||||
|
|
|
@ -4,6 +4,8 @@
|
|||
|
||||
## KibanaRequest.route property
|
||||
|
||||
matched route details
|
||||
|
||||
<b>Signature:</b>
|
||||
|
||||
```typescript
|
||||
|
|
|
@ -4,6 +4,8 @@
|
|||
|
||||
## KibanaRequest.url property
|
||||
|
||||
a WHATWG URL standard object.
|
||||
|
||||
<b>Signature:</b>
|
||||
|
||||
```typescript
|
||||
|
|
|
@ -0,0 +1,13 @@
|
|||
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
|
||||
|
||||
[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [KibanaResponseFactory](./kibana-plugin-server.kibanaresponsefactory.md)
|
||||
|
||||
## KibanaResponseFactory type
|
||||
|
||||
Creates an object containing request response payload, HTTP headers, error details, and other data transmitted to the client.
|
||||
|
||||
<b>Signature:</b>
|
||||
|
||||
```typescript
|
||||
export declare type KibanaResponseFactory = typeof kibanaResponseFactory;
|
||||
```
|
|
@ -0,0 +1,13 @@
|
|||
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
|
||||
|
||||
[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [KnownHeaders](./kibana-plugin-server.knownheaders.md)
|
||||
|
||||
## KnownHeaders type
|
||||
|
||||
Set of well-known HTTP headers.
|
||||
|
||||
<b>Signature:</b>
|
||||
|
||||
```typescript
|
||||
export declare type KnownHeaders = KnownKeys<IncomingHttpHeaders>;
|
||||
```
|
|
@ -2,12 +2,15 @@
|
|||
|
||||
[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [LegacyRequest](./kibana-plugin-server.legacyrequest.md)
|
||||
|
||||
## LegacyRequest type
|
||||
## LegacyRequest interface
|
||||
|
||||
Support Legacy platform request for the period of migration.
|
||||
> Warning: This API is now obsolete.
|
||||
>
|
||||
> `hapi` request object, supported during migration process only for backward compatibility.
|
||||
>
|
||||
|
||||
<b>Signature:</b>
|
||||
|
||||
```typescript
|
||||
export declare type LegacyRequest = Request;
|
||||
export interface LegacyRequest extends Request
|
||||
```
|
||||
|
|
|
@ -17,12 +17,18 @@ The plugin integrates with the core system via lifecycle events: `setup`<!-- -->
|
|||
| [ClusterClient](./kibana-plugin-server.clusterclient.md) | Represents an Elasticsearch cluster API client and allows to call API on behalf of the internal Kibana user and the actual user that is derived from the request headers (via <code>asScoped(...)</code>). |
|
||||
| [ElasticsearchErrorHelpers](./kibana-plugin-server.elasticsearcherrorhelpers.md) | Helpers for working with errors returned from the Elasticsearch service.Since the internal data of errors are subject to change, consumers of the Elasticsearch service should always use these helpers to classify errors instead of checking error internals such as <code>body.error.header[WWW-Authenticate]</code> |
|
||||
| [KibanaRequest](./kibana-plugin-server.kibanarequest.md) | Kibana specific abstraction for an incoming request. |
|
||||
| [Router](./kibana-plugin-server.router.md) | |
|
||||
| [Router](./kibana-plugin-server.router.md) | Provides ability to declare a handler function for a particular path and HTTP request method. Each route can have only one handler functions, which is executed when the route is matched. |
|
||||
| [SavedObjectsErrorHelpers](./kibana-plugin-server.savedobjectserrorhelpers.md) | |
|
||||
| [SavedObjectsSchema](./kibana-plugin-server.savedobjectsschema.md) | |
|
||||
| [SavedObjectsSerializer](./kibana-plugin-server.savedobjectsserializer.md) | |
|
||||
| [ScopedClusterClient](./kibana-plugin-server.scopedclusterclient.md) | Serves the same purpose as "normal" <code>ClusterClient</code> but exposes additional <code>callAsCurrentUser</code> method that doesn't use credentials of the Kibana internal user (as <code>callAsInternalUser</code> does) to request Elasticsearch API, but rather passes HTTP headers extracted from the current user request to the API |
|
||||
|
||||
## Enumerations
|
||||
|
||||
| Enumeration | Description |
|
||||
| --- | --- |
|
||||
| [AuthStatus](./kibana-plugin-server.authstatus.md) | Status indicating an outcome of the authentication. |
|
||||
|
||||
## Interfaces
|
||||
|
||||
| Interface | Description |
|
||||
|
@ -32,13 +38,17 @@ The plugin integrates with the core system via lifecycle events: `setup`<!-- -->
|
|||
| [CallAPIOptions](./kibana-plugin-server.callapioptions.md) | The set of options that defines how API call should be made and result be processed. |
|
||||
| [CoreSetup](./kibana-plugin-server.coresetup.md) | Context passed to the plugins <code>setup</code> method. |
|
||||
| [CoreStart](./kibana-plugin-server.corestart.md) | Context passed to the plugins <code>start</code> method. |
|
||||
| [CustomHttpResponseOptions](./kibana-plugin-server.customhttpresponseoptions.md) | HTTP response parameters for a response with adjustable status code. |
|
||||
| [DiscoveredPlugin](./kibana-plugin-server.discoveredplugin.md) | Small container object used to expose information about discovered plugins that may or may not have been started. |
|
||||
| [ElasticsearchError](./kibana-plugin-server.elasticsearcherror.md) | |
|
||||
| [ElasticsearchServiceSetup](./kibana-plugin-server.elasticsearchservicesetup.md) | |
|
||||
| [FakeRequest](./kibana-plugin-server.fakerequest.md) | Fake request object created manually by Kibana plugins. |
|
||||
| [HttpResponseOptions](./kibana-plugin-server.httpresponseoptions.md) | HTTP response parameters |
|
||||
| [HttpServerSetup](./kibana-plugin-server.httpserversetup.md) | Kibana HTTP Service provides own abstraction for work with HTTP stack. Plugins don't have direct access to <code>hapi</code> server and its primitives anymore. Moreover, plugins shouldn't rely on the fact that HTTP Service uses one or another library under the hood. This gives the platform flexibility to upgrade or changing our internal HTTP stack without breaking plugins. If the HTTP Service lacks functionality you need, we are happy to discuss and support your needs. |
|
||||
| [HttpServiceStart](./kibana-plugin-server.httpservicestart.md) | |
|
||||
| [InternalCoreStart](./kibana-plugin-server.internalcorestart.md) | |
|
||||
| [KibanaRequestRoute](./kibana-plugin-server.kibanarequestroute.md) | Request specific route information exposed to a handler. |
|
||||
| [LegacyRequest](./kibana-plugin-server.legacyrequest.md) | |
|
||||
| [Logger](./kibana-plugin-server.logger.md) | Logger exposes all the necessary methods to log any type of information and this is the interface used by the logging consumers including plugins. |
|
||||
| [LoggerFactory](./kibana-plugin-server.loggerfactory.md) | The single purpose of <code>LoggerFactory</code> interface is to define a way to retrieve a context-based logger instance. |
|
||||
| [LogMeta](./kibana-plugin-server.logmeta.md) | Contextual metadata |
|
||||
|
@ -49,7 +59,8 @@ The plugin integrates with the core system via lifecycle events: `setup`<!-- -->
|
|||
| [PluginsServiceSetup](./kibana-plugin-server.pluginsservicesetup.md) | |
|
||||
| [PluginsServiceStart](./kibana-plugin-server.pluginsservicestart.md) | |
|
||||
| [ResponseErrorMeta](./kibana-plugin-server.responseerrormeta.md) | Additional metadata to enhance error output or provide error details. |
|
||||
| [RouteConfigOptions](./kibana-plugin-server.routeconfigoptions.md) | Route specific configuration. |
|
||||
| [RouteConfig](./kibana-plugin-server.routeconfig.md) | Route specific configuration. |
|
||||
| [RouteConfigOptions](./kibana-plugin-server.routeconfigoptions.md) | Additional route options. |
|
||||
| [SavedObject](./kibana-plugin-server.savedobject.md) | |
|
||||
| [SavedObjectAttributes](./kibana-plugin-server.savedobjectattributes.md) | |
|
||||
| [SavedObjectReference](./kibana-plugin-server.savedobjectreference.md) | A reference to another saved object. |
|
||||
|
@ -78,8 +89,15 @@ The plugin integrates with the core system via lifecycle events: `setup`<!-- -->
|
|||
| [SavedObjectsUpdateOptions](./kibana-plugin-server.savedobjectsupdateoptions.md) | |
|
||||
| [SavedObjectsUpdateResponse](./kibana-plugin-server.savedobjectsupdateresponse.md) | |
|
||||
| [SessionStorage](./kibana-plugin-server.sessionstorage.md) | Provides an interface to store and retrieve data across requests. |
|
||||
| [SessionStorageCookieOptions](./kibana-plugin-server.sessionstoragecookieoptions.md) | Configuration used to create HTTP session storage based on top of cookie mechanism. |
|
||||
| [SessionStorageFactory](./kibana-plugin-server.sessionstoragefactory.md) | SessionStorage factory to bind one to an incoming request |
|
||||
|
||||
## Variables
|
||||
|
||||
| Variable | Description |
|
||||
| --- | --- |
|
||||
| [kibanaResponseFactory](./kibana-plugin-server.kibanaresponsefactory.md) | Set of helpers used to create <code>KibanaResponse</code> to form HTTP response on an incoming request. Should be returned as a result of [RequestHandler](./kibana-plugin-server.requesthandler.md) execution. |
|
||||
|
||||
## Type Aliases
|
||||
|
||||
| Type Alias | Description |
|
||||
|
@ -89,14 +107,20 @@ The plugin integrates with the core system via lifecycle events: `setup`<!-- -->
|
|||
| [AuthHeaders](./kibana-plugin-server.authheaders.md) | Auth Headers map |
|
||||
| [ElasticsearchClientConfig](./kibana-plugin-server.elasticsearchclientconfig.md) | |
|
||||
| [GetAuthHeaders](./kibana-plugin-server.getauthheaders.md) | Get headers to authenticate a user against Elasticsearch. |
|
||||
| [Headers](./kibana-plugin-server.headers.md) | |
|
||||
| [GetAuthState](./kibana-plugin-server.getauthstate.md) | Get authentication state for a request. Returned by <code>auth</code> interceptor. |
|
||||
| [Headers](./kibana-plugin-server.headers.md) | Http request headers to read. |
|
||||
| [HttpResponsePayload](./kibana-plugin-server.httpresponsepayload.md) | Data send to the client as a response payload. |
|
||||
| [HttpServiceSetup](./kibana-plugin-server.httpservicesetup.md) | |
|
||||
| [LegacyRequest](./kibana-plugin-server.legacyrequest.md) | Support Legacy platform request for the period of migration. |
|
||||
| [IsAuthenticated](./kibana-plugin-server.isauthenticated.md) | Return authentication status for a request. |
|
||||
| [KibanaResponseFactory](./kibana-plugin-server.kibanaresponsefactory.md) | Creates an object containing request response payload, HTTP headers, error details, and other data transmitted to the client. |
|
||||
| [KnownHeaders](./kibana-plugin-server.knownheaders.md) | Set of well-known HTTP headers. |
|
||||
| [OnPostAuthHandler](./kibana-plugin-server.onpostauthhandler.md) | |
|
||||
| [OnPreAuthHandler](./kibana-plugin-server.onpreauthhandler.md) | |
|
||||
| [PluginInitializer](./kibana-plugin-server.plugininitializer.md) | The <code>plugin</code> export at the root of a plugin's <code>server</code> directory should conform to this interface. |
|
||||
| [PluginName](./kibana-plugin-server.pluginname.md) | Dedicated type for plugin name/id that is supposed to make Map/Set/Arrays that use it as a key or value more obvious. |
|
||||
| [RecursiveReadonly](./kibana-plugin-server.recursivereadonly.md) | |
|
||||
| [RedirectResponseOptions](./kibana-plugin-server.redirectresponseoptions.md) | HTTP response parameters for redirection response |
|
||||
| [RequestHandler](./kibana-plugin-server.requesthandler.md) | A function executed when route path matched requested resource path. Request handler is expected to return a result of one of [KibanaResponseFactory](./kibana-plugin-server.kibanaresponsefactory.md) functions. |
|
||||
| [ResponseError](./kibana-plugin-server.responseerror.md) | Error message and optional data send to the client in case of error. |
|
||||
| [RouteMethod](./kibana-plugin-server.routemethod.md) | The set of common HTTP methods supported by Kibana routing. |
|
||||
| [SavedObjectsClientContract](./kibana-plugin-server.savedobjectsclientcontract.md) | \#\# SavedObjectsClient errors<!-- -->Since 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 <code>isXYZError()</code> helpers exposed at <code>SavedObjectsErrorHelpers</code> should be used to understand and manage error responses from the <code>SavedObjectsClient</code>.<!-- -->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 <code>error.body.error.type</code> or doing substring checks on <code>error.body.error.reason</code>, 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 index<!-- -->From 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 index<!-- -->Unlike 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 <code>action.auto_create_index</code> setting prevents it from being created automatically so we throw a special 503 with the intention of informing the user that their Elasticsearch settings need to be updated.<!-- -->See [SavedObjectsErrorHelpers](./kibana-plugin-server.savedobjectserrorhelpers.md) |
|
||||
|
|
|
@ -0,0 +1,17 @@
|
|||
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
|
||||
|
||||
[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [RedirectResponseOptions](./kibana-plugin-server.redirectresponseoptions.md)
|
||||
|
||||
## RedirectResponseOptions type
|
||||
|
||||
HTTP response parameters for redirection response
|
||||
|
||||
<b>Signature:</b>
|
||||
|
||||
```typescript
|
||||
export declare type RedirectResponseOptions = HttpResponseOptions & {
|
||||
headers: {
|
||||
location: string;
|
||||
};
|
||||
};
|
||||
```
|
|
@ -0,0 +1,42 @@
|
|||
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
|
||||
|
||||
[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [RequestHandler](./kibana-plugin-server.requesthandler.md)
|
||||
|
||||
## RequestHandler type
|
||||
|
||||
A function executed when route path matched requested resource path. Request handler is expected to return a result of one of [KibanaResponseFactory](./kibana-plugin-server.kibanaresponsefactory.md) functions.
|
||||
|
||||
<b>Signature:</b>
|
||||
|
||||
```typescript
|
||||
export declare type RequestHandler<P extends ObjectType, Q extends ObjectType, B extends ObjectType> = (request: KibanaRequest<TypeOf<P>, TypeOf<Q>, TypeOf<B>>, response: KibanaResponseFactory) => KibanaResponse<any> | Promise<KibanaResponse<any>>;
|
||||
```
|
||||
|
||||
## Example
|
||||
|
||||
|
||||
```ts
|
||||
const router = new Router('my-app');
|
||||
// creates a route handler for GET request on 'my-app/path/{id}' path
|
||||
router.get(
|
||||
{
|
||||
path: 'path/{id}',
|
||||
// defines a validation schema for a named segment of the route path
|
||||
validate: {
|
||||
params: schema.object({
|
||||
id: schema.string(),
|
||||
}),
|
||||
},
|
||||
},
|
||||
// function to execute to create a responses
|
||||
async (request, response) => {
|
||||
const data = await findObject(request.params.id);
|
||||
// creates a command to respond with 'not found' error
|
||||
if (!data) return response.notFound();
|
||||
// creates a command to send found data to the client
|
||||
return response.ok(data);
|
||||
}
|
||||
);
|
||||
|
||||
```
|
||||
|
|
@ -0,0 +1,22 @@
|
|||
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
|
||||
|
||||
[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [RouteConfig](./kibana-plugin-server.routeconfig.md)
|
||||
|
||||
## RouteConfig interface
|
||||
|
||||
Route specific configuration.
|
||||
|
||||
<b>Signature:</b>
|
||||
|
||||
```typescript
|
||||
export interface RouteConfig<P extends ObjectType, Q extends ObjectType, B extends ObjectType>
|
||||
```
|
||||
|
||||
## Properties
|
||||
|
||||
| Property | Type | Description |
|
||||
| --- | --- | --- |
|
||||
| [options](./kibana-plugin-server.routeconfig.options.md) | <code>RouteConfigOptions</code> | Additional route options [RouteConfigOptions](./kibana-plugin-server.routeconfigoptions.md)<!-- -->. |
|
||||
| [path](./kibana-plugin-server.routeconfig.path.md) | <code>string</code> | The endpoint \_within\_ the router path to register the route. E.g. if the router is registered at <code>/elasticsearch</code> and the route path is <code>/search</code>, the full path for the route is <code>/elasticsearch/search</code>. Supports: - named path segments <code>path/{name}</code>. - optional path segments <code>path/{position?}</code>. - multi-segments <code>path/{coordinates*2}</code>. Segments are accessible within a handler function as <code>params</code> property of [KibanaRequest](./kibana-plugin-server.kibanarequest.md) object. To have read access to <code>params</code> you \*must\* specify validation schema with [RouteConfig.validate](./kibana-plugin-server.routeconfig.validate.md)<!-- -->. |
|
||||
| [validate](./kibana-plugin-server.routeconfig.validate.md) | <code>RouteSchemas<P, Q, B> | false</code> | A schema created with <code>@kbn/config-schema</code> that every request will be validated against. You \*must\* specify a validation schema to be able to read: - url path segments - request query - request body To opt out of validating the request, specify <code>false</code>. |
|
||||
|
|
@ -0,0 +1,13 @@
|
|||
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
|
||||
|
||||
[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [RouteConfig](./kibana-plugin-server.routeconfig.md) > [options](./kibana-plugin-server.routeconfig.options.md)
|
||||
|
||||
## RouteConfig.options property
|
||||
|
||||
Additional route options [RouteConfigOptions](./kibana-plugin-server.routeconfigoptions.md)<!-- -->.
|
||||
|
||||
<b>Signature:</b>
|
||||
|
||||
```typescript
|
||||
options?: RouteConfigOptions;
|
||||
```
|
|
@ -0,0 +1,13 @@
|
|||
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
|
||||
|
||||
[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [RouteConfig](./kibana-plugin-server.routeconfig.md) > [path](./kibana-plugin-server.routeconfig.path.md)
|
||||
|
||||
## RouteConfig.path property
|
||||
|
||||
The endpoint \_within\_ the router path to register the route. E.g. if the router is registered at `/elasticsearch` and the route path is `/search`<!-- -->, the full path for the route is `/elasticsearch/search`<!-- -->. Supports: - named path segments `path/{name}`<!-- -->. - optional path segments `path/{position?}`<!-- -->. - multi-segments `path/{coordinates*2}`<!-- -->. Segments are accessible within a handler function as `params` property of [KibanaRequest](./kibana-plugin-server.kibanarequest.md) object. To have read access to `params` you \*must\* specify validation schema with [RouteConfig.validate](./kibana-plugin-server.routeconfig.validate.md)<!-- -->.
|
||||
|
||||
<b>Signature:</b>
|
||||
|
||||
```typescript
|
||||
path: string;
|
||||
```
|
|
@ -0,0 +1,32 @@
|
|||
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
|
||||
|
||||
[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [RouteConfig](./kibana-plugin-server.routeconfig.md) > [validate](./kibana-plugin-server.routeconfig.validate.md)
|
||||
|
||||
## RouteConfig.validate property
|
||||
|
||||
A schema created with `@kbn/config-schema` that every request will be validated against. You \*must\* specify a validation schema to be able to read: - url path segments - request query - request body To opt out of validating the request, specify `false`<!-- -->.
|
||||
|
||||
<b>Signature:</b>
|
||||
|
||||
```typescript
|
||||
validate: RouteSchemas<P, Q, B> | false;
|
||||
```
|
||||
|
||||
## Example
|
||||
|
||||
|
||||
```ts
|
||||
import { schema } from '@kbn/config-schema';
|
||||
router.get({
|
||||
path: 'path/{id}'
|
||||
validate: {
|
||||
params: schema.object({
|
||||
id: schema.string(),
|
||||
}),
|
||||
query: schema.object({...}),
|
||||
body: schema.object({...}),
|
||||
},
|
||||
})
|
||||
|
||||
```
|
||||
|
|
@ -4,7 +4,7 @@
|
|||
|
||||
## RouteConfigOptions.authRequired property
|
||||
|
||||
A flag shows that authentication for a route: enabled when true disabled when false
|
||||
A flag shows that authentication for a route: `enabled` when true `disabled` when false
|
||||
|
||||
Enabled by default.
|
||||
|
||||
|
|
|
@ -4,7 +4,7 @@
|
|||
|
||||
## RouteConfigOptions interface
|
||||
|
||||
Route specific configuration.
|
||||
Additional route options.
|
||||
|
||||
<b>Signature:</b>
|
||||
|
||||
|
@ -16,6 +16,6 @@ export interface RouteConfigOptions
|
|||
|
||||
| Property | Type | Description |
|
||||
| --- | --- | --- |
|
||||
| [authRequired](./kibana-plugin-server.routeconfigoptions.authrequired.md) | <code>boolean</code> | A flag shows that authentication for a route: enabled when true disabled when false<!-- -->Enabled by default. |
|
||||
| [authRequired](./kibana-plugin-server.routeconfigoptions.authrequired.md) | <code>boolean</code> | A flag shows that authentication for a route: <code>enabled</code> when true <code>disabled</code> when false<!-- -->Enabled by default. |
|
||||
| [tags](./kibana-plugin-server.routeconfigoptions.tags.md) | <code>readonly string[]</code> | Additional metadata tag strings to attach to the route. |
|
||||
|
||||
|
|
|
@ -16,5 +16,5 @@ constructor(path: string);
|
|||
|
||||
| Parameter | Type | Description |
|
||||
| --- | --- | --- |
|
||||
| path | <code>string</code> | |
|
||||
| path | <code>string</code> | a router path, set as the very first path segment for all registered routes. |
|
||||
|
||||
|
|
|
@ -4,7 +4,7 @@
|
|||
|
||||
## Router.delete() method
|
||||
|
||||
Register a `DELETE` request with the router
|
||||
Register a route handler for `DELETE` request.
|
||||
|
||||
<b>Signature:</b>
|
||||
|
||||
|
|
|
@ -4,7 +4,7 @@
|
|||
|
||||
## Router.get() method
|
||||
|
||||
Register a `GET` request with the router
|
||||
Register a route handler for `GET` request.
|
||||
|
||||
<b>Signature:</b>
|
||||
|
||||
|
|
|
@ -1,19 +0,0 @@
|
|||
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
|
||||
|
||||
[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [Router](./kibana-plugin-server.router.md) > [getRoutes](./kibana-plugin-server.router.getroutes.md)
|
||||
|
||||
## Router.getRoutes() method
|
||||
|
||||
Returns all routes registered with the this router.
|
||||
|
||||
<b>Signature:</b>
|
||||
|
||||
```typescript
|
||||
getRoutes(): Readonly<RouterRoute>[];
|
||||
```
|
||||
<b>Returns:</b>
|
||||
|
||||
`Readonly<RouterRoute>[]`
|
||||
|
||||
List of registered routes.
|
||||
|
|
@ -4,6 +4,7 @@
|
|||
|
||||
## Router class
|
||||
|
||||
Provides ability to declare a handler function for a particular path and HTTP request method. Each route can have only one handler functions, which is executed when the route is matched.
|
||||
|
||||
<b>Signature:</b>
|
||||
|
||||
|
@ -28,9 +29,18 @@ export declare class Router
|
|||
|
||||
| Method | Modifiers | Description |
|
||||
| --- | --- | --- |
|
||||
| [delete(route, handler)](./kibana-plugin-server.router.delete.md) | | Register a <code>DELETE</code> request with the router |
|
||||
| [get(route, handler)](./kibana-plugin-server.router.get.md) | | Register a <code>GET</code> request with the router |
|
||||
| [getRoutes()](./kibana-plugin-server.router.getroutes.md) | | Returns all routes registered with the this router. |
|
||||
| [post(route, handler)](./kibana-plugin-server.router.post.md) | | Register a <code>POST</code> request with the router |
|
||||
| [put(route, handler)](./kibana-plugin-server.router.put.md) | | Register a <code>PUT</code> request with the router |
|
||||
| [delete(route, handler)](./kibana-plugin-server.router.delete.md) | | Register a route handler for <code>DELETE</code> request. |
|
||||
| [get(route, handler)](./kibana-plugin-server.router.get.md) | | Register a route handler for <code>GET</code> request. |
|
||||
| [post(route, handler)](./kibana-plugin-server.router.post.md) | | Register a route handler for <code>POST</code> request. |
|
||||
| [put(route, handler)](./kibana-plugin-server.router.put.md) | | Register a route handler for <code>PUT</code> request. |
|
||||
|
||||
## Example
|
||||
|
||||
|
||||
```ts
|
||||
const router = new Router('my-app');
|
||||
// handler is called when 'my-app/path' resource is requested with `GET` method
|
||||
router.get({ path: '/path', validate: false }, (req, res) => res.ok({ content: 'ok' }));
|
||||
|
||||
```
|
||||
|
||||
|
|
|
@ -4,7 +4,7 @@
|
|||
|
||||
## Router.post() method
|
||||
|
||||
Register a `POST` request with the router
|
||||
Register a route handler for `POST` request.
|
||||
|
||||
<b>Signature:</b>
|
||||
|
||||
|
|
|
@ -4,7 +4,7 @@
|
|||
|
||||
## Router.put() method
|
||||
|
||||
Register a `PUT` request with the router
|
||||
Register a route handler for `PUT` request.
|
||||
|
||||
<b>Signature:</b>
|
||||
|
||||
|
|
|
@ -9,7 +9,7 @@ Constructs a new instance of the `ScopedClusterClient` class
|
|||
<b>Signature:</b>
|
||||
|
||||
```typescript
|
||||
constructor(internalAPICaller: APICaller, scopedAPICaller: APICaller, headers?: Record<string, string | string[] | undefined> | undefined);
|
||||
constructor(internalAPICaller: APICaller, scopedAPICaller: APICaller, headers?: Headers | undefined);
|
||||
```
|
||||
|
||||
## Parameters
|
||||
|
@ -18,5 +18,5 @@ constructor(internalAPICaller: APICaller, scopedAPICaller: APICaller, headers?:
|
|||
| --- | --- | --- |
|
||||
| internalAPICaller | <code>APICaller</code> | |
|
||||
| scopedAPICaller | <code>APICaller</code> | |
|
||||
| headers | <code>Record<string, string | string[] | undefined> | undefined</code> | |
|
||||
| headers | <code>Headers | undefined</code> | |
|
||||
|
||||
|
|
|
@ -0,0 +1,13 @@
|
|||
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
|
||||
|
||||
[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [SessionStorageCookieOptions](./kibana-plugin-server.sessionstoragecookieoptions.md) > [encryptionKey](./kibana-plugin-server.sessionstoragecookieoptions.encryptionkey.md)
|
||||
|
||||
## SessionStorageCookieOptions.encryptionKey property
|
||||
|
||||
A key used to encrypt a cookie value. Should be at least 32 characters long.
|
||||
|
||||
<b>Signature:</b>
|
||||
|
||||
```typescript
|
||||
encryptionKey: string;
|
||||
```
|
|
@ -0,0 +1,13 @@
|
|||
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
|
||||
|
||||
[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [SessionStorageCookieOptions](./kibana-plugin-server.sessionstoragecookieoptions.md) > [isSecure](./kibana-plugin-server.sessionstoragecookieoptions.issecure.md)
|
||||
|
||||
## SessionStorageCookieOptions.isSecure property
|
||||
|
||||
Flag indicating whether the cookie should be sent only via a secure connection.
|
||||
|
||||
<b>Signature:</b>
|
||||
|
||||
```typescript
|
||||
isSecure: boolean;
|
||||
```
|
|
@ -0,0 +1,23 @@
|
|||
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
|
||||
|
||||
[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [SessionStorageCookieOptions](./kibana-plugin-server.sessionstoragecookieoptions.md)
|
||||
|
||||
## SessionStorageCookieOptions interface
|
||||
|
||||
Configuration used to create HTTP session storage based on top of cookie mechanism.
|
||||
|
||||
<b>Signature:</b>
|
||||
|
||||
```typescript
|
||||
export interface SessionStorageCookieOptions<T>
|
||||
```
|
||||
|
||||
## Properties
|
||||
|
||||
| Property | Type | Description |
|
||||
| --- | --- | --- |
|
||||
| [encryptionKey](./kibana-plugin-server.sessionstoragecookieoptions.encryptionkey.md) | <code>string</code> | A key used to encrypt a cookie value. Should be at least 32 characters long. |
|
||||
| [isSecure](./kibana-plugin-server.sessionstoragecookieoptions.issecure.md) | <code>boolean</code> | Flag indicating whether the cookie should be sent only via a secure connection. |
|
||||
| [name](./kibana-plugin-server.sessionstoragecookieoptions.name.md) | <code>string</code> | Name of the session cookie. |
|
||||
| [validate](./kibana-plugin-server.sessionstoragecookieoptions.validate.md) | <code>(sessionValue: T) => boolean | Promise<boolean></code> | Function called to validate a cookie content. |
|
||||
|
|
@ -0,0 +1,13 @@
|
|||
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
|
||||
|
||||
[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [SessionStorageCookieOptions](./kibana-plugin-server.sessionstoragecookieoptions.md) > [name](./kibana-plugin-server.sessionstoragecookieoptions.name.md)
|
||||
|
||||
## SessionStorageCookieOptions.name property
|
||||
|
||||
Name of the session cookie.
|
||||
|
||||
<b>Signature:</b>
|
||||
|
||||
```typescript
|
||||
name: string;
|
||||
```
|
|
@ -0,0 +1,13 @@
|
|||
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
|
||||
|
||||
[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [SessionStorageCookieOptions](./kibana-plugin-server.sessionstoragecookieoptions.md) > [validate](./kibana-plugin-server.sessionstoragecookieoptions.validate.md)
|
||||
|
||||
## SessionStorageCookieOptions.validate property
|
||||
|
||||
Function called to validate a cookie content.
|
||||
|
||||
<b>Signature:</b>
|
||||
|
||||
```typescript
|
||||
validate: (sessionValue: T) => boolean | Promise<boolean>;
|
||||
```
|
|
@ -18,10 +18,9 @@
|
|||
*/
|
||||
import { Client } from 'elasticsearch';
|
||||
import { get } from 'lodash';
|
||||
import { Request } from 'hapi';
|
||||
|
||||
import { ElasticsearchErrorHelpers } from './errors';
|
||||
import { GetAuthHeaders, isRealRequest } from '../http';
|
||||
import { GetAuthHeaders, isRealRequest, LegacyRequest } from '../http';
|
||||
import { filterHeaders, Headers, KibanaRequest, ensureRawRequest } from '../http/router';
|
||||
import { Logger } from '../logging';
|
||||
import {
|
||||
|
@ -36,8 +35,6 @@ import { ScopedClusterClient } from './scoped_cluster_client';
|
|||
* @public
|
||||
*/
|
||||
|
||||
export type LegacyRequest = Request;
|
||||
|
||||
const noop = () => undefined;
|
||||
/**
|
||||
* The set of options that defines how API call should be made and result be
|
||||
|
|
|
@ -18,7 +18,7 @@
|
|||
*/
|
||||
|
||||
export { ElasticsearchServiceSetup, ElasticsearchService } from './elasticsearch_service';
|
||||
export { CallAPIOptions, ClusterClient, FakeRequest, LegacyRequest } from './cluster_client';
|
||||
export { CallAPIOptions, ClusterClient, FakeRequest } from './cluster_client';
|
||||
export { ScopedClusterClient, Headers, APICaller } from './scoped_cluster_client';
|
||||
export { ElasticsearchClientConfig } from './elasticsearch_client_config';
|
||||
export { config } from './elasticsearch_config';
|
||||
|
|
|
@ -16,19 +16,21 @@
|
|||
* specific language governing permissions and limitations
|
||||
* under the License.
|
||||
*/
|
||||
import { Request } from 'hapi';
|
||||
import { KibanaRequest, ensureRawRequest } from './router';
|
||||
import { KibanaRequest, ensureRawRequest, LegacyRequest } from './router';
|
||||
import { AuthHeaders } from './lifecycle/auth';
|
||||
|
||||
/**
|
||||
* Get headers to authenticate a user against Elasticsearch.
|
||||
* @param request {@link KibanaRequest} - an incoming request.
|
||||
* @return authentication headers {@link AuthHeaders} for - an incoming request.
|
||||
* @public
|
||||
* */
|
||||
export type GetAuthHeaders = (request: KibanaRequest | Request) => AuthHeaders | undefined;
|
||||
export type GetAuthHeaders = (request: KibanaRequest | LegacyRequest) => AuthHeaders | undefined;
|
||||
|
||||
/** @internal */
|
||||
export class AuthHeadersStorage {
|
||||
private authHeadersCache = new WeakMap<Request, AuthHeaders>();
|
||||
public set = (request: KibanaRequest | Request, headers: AuthHeaders) => {
|
||||
private authHeadersCache = new WeakMap<LegacyRequest, AuthHeaders>();
|
||||
public set = (request: KibanaRequest | LegacyRequest, headers: AuthHeaders) => {
|
||||
this.authHeadersCache.set(ensureRawRequest(request), headers);
|
||||
};
|
||||
public get: GetAuthHeaders = request => {
|
||||
|
|
|
@ -16,22 +16,51 @@
|
|||
* specific language governing permissions and limitations
|
||||
* under the License.
|
||||
*/
|
||||
import { Request } from 'hapi';
|
||||
import { KibanaRequest, ensureRawRequest } from './router';
|
||||
import { ensureRawRequest, KibanaRequest, LegacyRequest } from './router';
|
||||
|
||||
/**
|
||||
* Status indicating an outcome of the authentication.
|
||||
* @public
|
||||
*/
|
||||
export enum AuthStatus {
|
||||
/**
|
||||
* `auth` interceptor successfully authenticated a user
|
||||
*/
|
||||
authenticated = 'authenticated',
|
||||
/**
|
||||
* `auth` interceptor failed user authentication
|
||||
*/
|
||||
unauthenticated = 'unauthenticated',
|
||||
/**
|
||||
* `auth` interceptor has not been registered
|
||||
*/
|
||||
unknown = 'unknown',
|
||||
}
|
||||
|
||||
/**
|
||||
* Get authentication state for a request. Returned by `auth` interceptor.
|
||||
* @param request {@link KibanaRequest} - an incoming request.
|
||||
* @public
|
||||
*/
|
||||
export type GetAuthState = (
|
||||
request: KibanaRequest | LegacyRequest
|
||||
) => { status: AuthStatus; state: unknown };
|
||||
|
||||
/**
|
||||
* Return authentication status for a request.
|
||||
* @param request {@link KibanaRequest} - an incoming request.
|
||||
* @public
|
||||
*/
|
||||
export type IsAuthenticated = (request: KibanaRequest | LegacyRequest) => boolean;
|
||||
|
||||
/** @internal */
|
||||
export class AuthStateStorage {
|
||||
private readonly storage = new WeakMap<Request, unknown>();
|
||||
private readonly storage = new WeakMap<LegacyRequest, unknown>();
|
||||
constructor(private readonly canBeAuthenticated: () => boolean) {}
|
||||
public set = (request: KibanaRequest | Request, state: unknown) => {
|
||||
public set = (request: KibanaRequest | LegacyRequest, state: unknown) => {
|
||||
this.storage.set(ensureRawRequest(request), state);
|
||||
};
|
||||
public get = (request: KibanaRequest | Request) => {
|
||||
public get: GetAuthState = request => {
|
||||
const key = ensureRawRequest(request);
|
||||
const state = this.storage.get(key);
|
||||
const status: AuthStatus = this.storage.has(key)
|
||||
|
@ -42,7 +71,7 @@ export class AuthStateStorage {
|
|||
|
||||
return { status, state };
|
||||
};
|
||||
public isAuthenticated = (request: KibanaRequest | Request) => {
|
||||
public isAuthenticated: IsAuthenticated = request => {
|
||||
return this.get(request).status === AuthStatus.authenticated;
|
||||
};
|
||||
}
|
||||
|
|
|
@ -16,24 +16,23 @@
|
|||
* specific language governing permissions and limitations
|
||||
* under the License.
|
||||
*/
|
||||
import { Request } from 'hapi';
|
||||
import { KibanaRequest, ensureRawRequest } from './router';
|
||||
import { ensureRawRequest, KibanaRequest, LegacyRequest } from './router';
|
||||
|
||||
import { modifyUrl } from '../../utils';
|
||||
|
||||
export class BasePath {
|
||||
private readonly basePathCache = new WeakMap<Request, string>();
|
||||
private readonly basePathCache = new WeakMap<LegacyRequest, string>();
|
||||
|
||||
constructor(private readonly serverBasePath?: string) {}
|
||||
|
||||
public get = (request: KibanaRequest | Request) => {
|
||||
public get = (request: KibanaRequest | LegacyRequest) => {
|
||||
const requestScopePath = this.basePathCache.get(ensureRawRequest(request)) || '';
|
||||
const serverBasePath = this.serverBasePath || '';
|
||||
return `${serverBasePath}${requestScopePath}`;
|
||||
};
|
||||
|
||||
// should work only for KibanaRequest as soon as spaces migrate to NP
|
||||
public set = (request: KibanaRequest | Request, requestSpecificBasePath: string) => {
|
||||
public set = (request: KibanaRequest | LegacyRequest, requestSpecificBasePath: string) => {
|
||||
const rawRequest = ensureRawRequest(request);
|
||||
|
||||
if (this.basePathCache.has(rawRequest)) {
|
||||
|
|
|
@ -24,10 +24,26 @@ import { KibanaRequest, ensureRawRequest } from './router';
|
|||
import { SessionStorageFactory, SessionStorage } from './session_storage';
|
||||
import { Logger } from '..';
|
||||
|
||||
/**
|
||||
* Configuration used to create HTTP session storage based on top of cookie mechanism.
|
||||
* @public
|
||||
*/
|
||||
export interface SessionStorageCookieOptions<T> {
|
||||
/**
|
||||
* Name of the session cookie.
|
||||
*/
|
||||
name: string;
|
||||
/**
|
||||
* A key used to encrypt a cookie value. Should be at least 32 characters long.
|
||||
*/
|
||||
encryptionKey: string;
|
||||
/**
|
||||
* Function called to validate a cookie content.
|
||||
*/
|
||||
validate: (sessionValue: T) => boolean | Promise<boolean>;
|
||||
/**
|
||||
* Flag indicating whether the cookie should be sent only via a secure connection.
|
||||
*/
|
||||
isSecure: boolean;
|
||||
}
|
||||
|
||||
|
|
|
@ -25,21 +25,98 @@ import { createServer, getListenerOptions, getServerOptions } from './http_tools
|
|||
import { adoptToHapiAuthFormat, AuthenticationHandler } from './lifecycle/auth';
|
||||
import { adoptToHapiOnPostAuthFormat, OnPostAuthHandler } from './lifecycle/on_post_auth';
|
||||
import { adoptToHapiOnPreAuthFormat, OnPreAuthHandler } from './lifecycle/on_pre_auth';
|
||||
import { Router, KibanaRequest, ResponseHeaders } from './router';
|
||||
import { KibanaRequest, LegacyRequest, ResponseHeaders, Router } from './router';
|
||||
import {
|
||||
SessionStorageCookieOptions,
|
||||
createCookieSessionStorageFactory,
|
||||
} from './cookie_session_storage';
|
||||
import { SessionStorageFactory } from './session_storage';
|
||||
import { AuthStateStorage } from './auth_state_storage';
|
||||
import { AuthHeadersStorage } from './auth_headers_storage';
|
||||
import { AuthStateStorage, GetAuthState, IsAuthenticated } from './auth_state_storage';
|
||||
import { AuthHeadersStorage, GetAuthHeaders } from './auth_headers_storage';
|
||||
import { BasePath } from './base_path_service';
|
||||
|
||||
/**
|
||||
* Kibana HTTP Service provides own abstraction for work with HTTP stack.
|
||||
* Plugins don't have direct access to `hapi` server and its primitives anymore. Moreover,
|
||||
* plugins shouldn't rely on the fact that HTTP Service uses one or another library under the hood.
|
||||
* This gives the platform flexibility to upgrade or changing our internal HTTP stack without breaking plugins.
|
||||
* If the HTTP Service lacks functionality you need, we are happy to discuss and support your needs.
|
||||
*
|
||||
* @example
|
||||
* To handle an incoming request in your plugin you should:
|
||||
* - Create a `Router` instance. Use `plugin-id` as a prefix path segment for your routes.
|
||||
* ```ts
|
||||
* import { Router } from 'src/core/server';
|
||||
* const router = new Router('my-app');
|
||||
* ```
|
||||
*
|
||||
* - Use `@kbn/config-schema` package to create a schema to validate the request `params`, `query`, and `body`. Every incoming request will be validated against the created schema. If validation failed, the request is rejected with `400` status and `Bad request` error without calling the route's handler.
|
||||
* To opt out of validating the request, specify `false`.
|
||||
* ```ts
|
||||
* import { schema, TypeOf } from '@kbn/config-schema';
|
||||
* const validate = {
|
||||
* params: schema.object({
|
||||
* id: schema.string(),
|
||||
* }),
|
||||
* };
|
||||
* ```
|
||||
*
|
||||
* - Declare a function to respond to incoming request.
|
||||
* The function will receive `request` object containing request details: url, headers, matched route, as well as validated `params`, `query`, `body`.
|
||||
* And `response` object instructing HTTP server to create HTTP response with information sent back to the client as the response body, headers, and HTTP status.
|
||||
* Unlike, `hapi` route handler in the Legacy platform, any exception raised during the handler call will generate `500 Server error` response and log error details for further investigation. See below for returning custom error responses.
|
||||
* ```ts
|
||||
* const handler = async (request: KibanaRequest, response: ResponseFactory) => {
|
||||
* const data = await findObject(request.params.id);
|
||||
* // creates a command to respond with 'not found' error
|
||||
* if (!data) return response.notFound();
|
||||
* // creates a command to send found data to the client and set response headers
|
||||
* return response.ok(data, {
|
||||
* headers: {
|
||||
* 'content-type': 'application/json'
|
||||
* }
|
||||
* });
|
||||
* }
|
||||
* ```
|
||||
*
|
||||
* - Register route handler for GET request to 'my-app/path/{id}' path
|
||||
* ```ts
|
||||
* import { schema, TypeOf } from '@kbn/config-schema';
|
||||
* import { Router } from 'src/core/server';
|
||||
* const router = new Router('my-app');
|
||||
*
|
||||
* const validate = {
|
||||
* params: schema.object({
|
||||
* id: schema.string(),
|
||||
* }),
|
||||
* };
|
||||
*
|
||||
* router.get({
|
||||
* path: 'path/{id}',
|
||||
* validate
|
||||
* },
|
||||
* async (request, response) => {
|
||||
* const data = await findObject(request.params.id);
|
||||
* if (!data) return response.notFound();
|
||||
* return response.ok(data, {
|
||||
* headers: {
|
||||
* 'content-type': 'application/json'
|
||||
* }
|
||||
* });
|
||||
* });
|
||||
* ```
|
||||
* @public
|
||||
*/
|
||||
export interface HttpServerSetup {
|
||||
server: Server;
|
||||
/**
|
||||
* Add all the routes registered with `router` to HTTP server request listeners.
|
||||
* @param router {@link Router} - a router with registered route handlers.
|
||||
*/
|
||||
registerRouter: (router: Router) => void;
|
||||
/**
|
||||
* Creates cookie based session storage factory {@link SessionStorageFactory}
|
||||
* @param cookieOptions {@link SessionStorageCookieOptions} - options to configure created cookie session storage.
|
||||
*/
|
||||
createCookieSessionStorageFactory: <T>(
|
||||
cookieOptions: SessionStorageCookieOptions<T>
|
||||
|
@ -49,35 +126,53 @@ export interface HttpServerSetup {
|
|||
* A handler should return a state to associate with the incoming request.
|
||||
* The state can be retrieved later via http.auth.get(..)
|
||||
* Only one AuthenticationHandler can be registered.
|
||||
* @param handler {@link AuthenticationHandler} - function to perform authentication.
|
||||
*/
|
||||
registerAuth: (handler: AuthenticationHandler) => void;
|
||||
/**
|
||||
* To define custom logic to perform for incoming requests. Runs the handler before Auth
|
||||
* hook performs a check that user has access to requested resources, so it's the only
|
||||
* interceptor performs a check that user has access to requested resources, so it's the only
|
||||
* place when you can forward a request to another URL right on the server.
|
||||
* Can register any number of registerOnPostAuth, which are called in sequence
|
||||
* (from the first registered to the last).
|
||||
* @param handler {@link OnPreAuthHandler} - function to call.
|
||||
*/
|
||||
registerOnPreAuth: (handler: OnPreAuthHandler) => void;
|
||||
/**
|
||||
* To define custom logic to perform for incoming requests. Runs the handler after Auth hook
|
||||
* To define custom logic to perform for incoming requests. Runs the handler after Auth interceptor
|
||||
* did make sure a user has access to the requested resource.
|
||||
* The auth state is available at stage via http.auth.get(..)
|
||||
* Can register any number of registerOnPreAuth, which are called in sequence
|
||||
* (from the first registered to the last).
|
||||
* @param handler {@link OnPostAuthHandler} - function to call.
|
||||
*/
|
||||
registerOnPostAuth: (handler: OnPostAuthHandler) => void;
|
||||
basePath: {
|
||||
get: (request: KibanaRequest | Request) => string;
|
||||
set: (request: KibanaRequest | Request, basePath: string) => void;
|
||||
/**
|
||||
* returns `basePath` value, specific for an incoming request.
|
||||
*/
|
||||
get: (request: KibanaRequest | LegacyRequest) => string;
|
||||
/**
|
||||
* sets `basePath` value, specific for an incoming request.
|
||||
*/
|
||||
set: (request: KibanaRequest | LegacyRequest, basePath: string) => void;
|
||||
/**
|
||||
* returns a new `basePath` value, prefixed with passed `url`.
|
||||
*/
|
||||
prepend: (url: string) => string;
|
||||
/**
|
||||
* returns a new `basePath` value, cleaned up from passed `url`.
|
||||
*/
|
||||
remove: (url: string) => string;
|
||||
};
|
||||
auth: {
|
||||
get: AuthStateStorage['get'];
|
||||
isAuthenticated: AuthStateStorage['isAuthenticated'];
|
||||
getAuthHeaders: AuthHeadersStorage['get'];
|
||||
get: GetAuthState;
|
||||
isAuthenticated: IsAuthenticated;
|
||||
getAuthHeaders: GetAuthHeaders;
|
||||
};
|
||||
/**
|
||||
* Flag showing whether a server was configured to use TLS connection.
|
||||
*/
|
||||
isTlsEnabled: boolean;
|
||||
}
|
||||
|
||||
|
|
|
@ -135,7 +135,7 @@ export class HttpService implements CoreService<HttpServiceSetup, HttpServiceSta
|
|||
const httpServer = new HttpServer(this.logger, 'NotReady');
|
||||
const { server } = await httpServer.setup(config);
|
||||
this.notReadyServer = server;
|
||||
// use hapi server while Kibana ResponseFactory doesn't allow specifying custom headers
|
||||
// use hapi server while KibanaResponseFactory doesn't allow specifying custom headers
|
||||
// https://github.com/elastic/kibana/issues/33779
|
||||
this.notReadyServer.route({
|
||||
path: '/{p*}',
|
||||
|
|
|
@ -19,13 +19,25 @@
|
|||
|
||||
export { config, HttpConfig, HttpConfigType } from './http_config';
|
||||
export { HttpService, HttpServiceSetup, HttpServiceStart } from './http_service';
|
||||
export { HttpServerSetup } from './http_server';
|
||||
export { GetAuthHeaders } from './auth_headers_storage';
|
||||
export { AuthStatus, GetAuthState, IsAuthenticated } from './auth_state_storage';
|
||||
export {
|
||||
CustomHttpResponseOptions,
|
||||
isRealRequest,
|
||||
HttpResponseOptions,
|
||||
HttpResponsePayload,
|
||||
KibanaRequest,
|
||||
KibanaRequestRoute,
|
||||
KnownHeaders,
|
||||
LegacyRequest,
|
||||
RedirectResponseOptions,
|
||||
RequestHandler,
|
||||
ResponseError,
|
||||
ResponseErrorMeta,
|
||||
kibanaResponseFactory,
|
||||
KibanaResponseFactory,
|
||||
RouteConfig,
|
||||
Router,
|
||||
RouteMethod,
|
||||
RouteConfigOptions,
|
||||
|
@ -40,3 +52,4 @@ export {
|
|||
} from './lifecycle/auth';
|
||||
export { OnPostAuthHandler, OnPostAuthToolkit } from './lifecycle/on_post_auth';
|
||||
export { SessionStorageFactory, SessionStorage } from './session_storage';
|
||||
export { SessionStorageCookieOptions } from './cookie_session_storage';
|
||||
|
|
|
@ -16,12 +16,49 @@
|
|||
* specific language governing permissions and limitations
|
||||
* under the License.
|
||||
*/
|
||||
import { IncomingHttpHeaders } from 'http';
|
||||
|
||||
import { pick } from '../../../utils';
|
||||
|
||||
/** @public */
|
||||
export type Headers = Record<string, string | string[] | undefined>;
|
||||
export type ResponseHeaders = Record<string, string | string[]>;
|
||||
/**
|
||||
* Creates a Union type of all known keys of a given interface.
|
||||
* @example
|
||||
* ```ts
|
||||
* interface Person {
|
||||
* name: string;
|
||||
* age: number;
|
||||
* [attributes: string]: string | number;
|
||||
* }
|
||||
* type PersonKnownKeys = KnownKeys<Person>; // "age" | "name"
|
||||
* ```
|
||||
*/
|
||||
type KnownKeys<T> = {
|
||||
[K in keyof T]: string extends K ? never : number extends K ? never : K;
|
||||
} extends { [_ in keyof T]: infer U }
|
||||
? U
|
||||
: never;
|
||||
|
||||
/**
|
||||
* Set of well-known HTTP headers.
|
||||
* @public
|
||||
*/
|
||||
export type KnownHeaders = KnownKeys<IncomingHttpHeaders>;
|
||||
|
||||
/**
|
||||
* Http request headers to read.
|
||||
* @public
|
||||
*/
|
||||
export type Headers = { [header in KnownHeaders]?: string | string[] | undefined } & {
|
||||
[header: string]: string | string[] | undefined;
|
||||
};
|
||||
|
||||
/**
|
||||
* Http response headers to set.
|
||||
* @public
|
||||
*/
|
||||
export type ResponseHeaders = { [header in KnownHeaders]?: string | string[] } & {
|
||||
[header: string]: string | string[];
|
||||
};
|
||||
|
||||
const normalizeHeaderField = (field: string) => field.trim().toLowerCase();
|
||||
|
||||
|
|
|
@ -17,8 +17,23 @@
|
|||
* under the License.
|
||||
*/
|
||||
|
||||
export { Headers, filterHeaders, ResponseHeaders } from './headers';
|
||||
export { Router } from './router';
|
||||
export { KibanaRequest, KibanaRequestRoute, ensureRawRequest, isRealRequest } from './request';
|
||||
export { RouteMethod, RouteConfigOptions } from './route';
|
||||
export { ResponseError, ResponseErrorMeta } from './response';
|
||||
export { Headers, filterHeaders, ResponseHeaders, KnownHeaders } from './headers';
|
||||
export { Router, RequestHandler } from './router';
|
||||
export {
|
||||
KibanaRequest,
|
||||
KibanaRequestRoute,
|
||||
isRealRequest,
|
||||
LegacyRequest,
|
||||
ensureRawRequest,
|
||||
} from './request';
|
||||
export { RouteMethod, RouteConfig, RouteConfigOptions } from './route';
|
||||
export {
|
||||
CustomHttpResponseOptions,
|
||||
HttpResponseOptions,
|
||||
HttpResponsePayload,
|
||||
RedirectResponseOptions,
|
||||
ResponseError,
|
||||
ResponseErrorMeta,
|
||||
kibanaResponseFactory,
|
||||
KibanaResponseFactory,
|
||||
} from './response';
|
||||
|
|
|
@ -38,16 +38,22 @@ export interface KibanaRequestRoute {
|
|||
options: Required<RouteConfigOptions>;
|
||||
}
|
||||
|
||||
/**
|
||||
* @deprecated
|
||||
* `hapi` request object, supported during migration process only for backward compatibility.
|
||||
* @public
|
||||
*/
|
||||
export interface LegacyRequest extends Request {} // eslint-disable-line @typescript-eslint/no-empty-interface
|
||||
|
||||
/**
|
||||
* Kibana specific abstraction for an incoming request.
|
||||
* @public
|
||||
* */
|
||||
*/
|
||||
export class KibanaRequest<Params = unknown, Query = unknown, Body = unknown> {
|
||||
/**
|
||||
* Factory for creating requests. Validates the request before creating an
|
||||
* instance of a KibanaRequest.
|
||||
* @internal
|
||||
*
|
||||
*/
|
||||
public static from<P extends ObjectType, Q extends ObjectType, B extends ObjectType>(
|
||||
req: Request,
|
||||
|
@ -68,6 +74,7 @@ export class KibanaRequest<Params = unknown, Query = unknown, Body = unknown> {
|
|||
* Validates the different parts of a request based on the schemas defined for
|
||||
* the route. Builds up the actual params, query and body object that will be
|
||||
* received in the route handler.
|
||||
* @internal
|
||||
*/
|
||||
private static validate<P extends ObjectType, Q extends ObjectType, B extends ObjectType>(
|
||||
req: Request,
|
||||
|
@ -102,8 +109,9 @@ export class KibanaRequest<Params = unknown, Query = unknown, Body = unknown> {
|
|||
|
||||
return { query, params, body };
|
||||
}
|
||||
|
||||
/** a WHATWG URL standard object. */
|
||||
public readonly url: Url;
|
||||
/** matched route details */
|
||||
public readonly route: RecursiveReadonly<KibanaRequestRoute>;
|
||||
/**
|
||||
* Readonly copy of incoming request headers.
|
||||
|
@ -153,14 +161,14 @@ export class KibanaRequest<Params = unknown, Query = unknown, Body = unknown> {
|
|||
* Returns underlying Hapi Request
|
||||
* @internal
|
||||
*/
|
||||
export const ensureRawRequest = (request: KibanaRequest | Request) =>
|
||||
export const ensureRawRequest = (request: KibanaRequest | LegacyRequest) =>
|
||||
isKibanaRequest(request) ? request[requestSymbol] : request;
|
||||
|
||||
function isKibanaRequest(request: unknown): request is KibanaRequest {
|
||||
return request instanceof KibanaRequest;
|
||||
}
|
||||
|
||||
function isRequest(request: any): request is Request {
|
||||
function isRequest(request: any): request is LegacyRequest {
|
||||
try {
|
||||
return request.raw.req && typeof request.raw.req === 'object';
|
||||
} catch {
|
||||
|
@ -172,6 +180,6 @@ function isRequest(request: any): request is Request {
|
|||
* Checks if an incoming request either KibanaRequest or Legacy.Request
|
||||
* @internal
|
||||
*/
|
||||
export function isRealRequest(request: unknown): request is KibanaRequest | Request {
|
||||
export function isRealRequest(request: unknown): request is KibanaRequest | LegacyRequest {
|
||||
return isKibanaRequest(request) || isRequest(request);
|
||||
}
|
||||
|
|
|
@ -16,8 +16,8 @@
|
|||
* specific language governing permissions and limitations
|
||||
* under the License.
|
||||
*/
|
||||
import { IncomingHttpHeaders } from 'http';
|
||||
import { Stream } from 'stream';
|
||||
import { ResponseHeaders } from './headers';
|
||||
|
||||
/**
|
||||
* Additional metadata to enhance error output or provide error details.
|
||||
|
@ -40,6 +40,10 @@ export type ResponseError =
|
|||
meta?: ResponseErrorMeta;
|
||||
};
|
||||
|
||||
/**
|
||||
* A response data object, expected to returned as a result of {@link RequestHandler} execution
|
||||
* @internal
|
||||
*/
|
||||
export class KibanaResponse<T extends HttpResponsePayload | ResponseError> {
|
||||
constructor(
|
||||
readonly status: number,
|
||||
|
@ -48,51 +52,31 @@ export class KibanaResponse<T extends HttpResponsePayload | ResponseError> {
|
|||
) {}
|
||||
}
|
||||
|
||||
/**
|
||||
* Creates a Union type of all known keys of a given interface.
|
||||
* @example
|
||||
* ```ts
|
||||
* interface Person {
|
||||
* name: string;
|
||||
* age: number;
|
||||
* [attributes: string]: string | number;
|
||||
* }
|
||||
* type PersonKnownKeys = KnownKeys<Person>; // "age" | "name"
|
||||
* ```
|
||||
*/
|
||||
type KnownKeys<T> = {
|
||||
[K in keyof T]: string extends K ? never : number extends K ? never : K;
|
||||
} extends { [_ in keyof T]: infer U }
|
||||
? U
|
||||
: never;
|
||||
|
||||
type KnownHeaders = KnownKeys<IncomingHttpHeaders>;
|
||||
/**
|
||||
* HTTP response parameters
|
||||
* @public
|
||||
*/
|
||||
export interface HttpResponseOptions {
|
||||
/** HTTP Headers with additional information about response */
|
||||
headers?: { [header in KnownHeaders]?: string | string[] } & {
|
||||
[header: string]: string | string[];
|
||||
};
|
||||
headers?: ResponseHeaders;
|
||||
}
|
||||
|
||||
/**
|
||||
* Data send to the client as a response payload.
|
||||
* @public
|
||||
*/
|
||||
export type HttpResponsePayload = undefined | string | Record<string, any> | Buffer | Stream;
|
||||
|
||||
/**
|
||||
* HTTP response parameters
|
||||
* HTTP response parameters for a response with adjustable status code.
|
||||
* @public
|
||||
*/
|
||||
export interface CustomResponseOptions extends HttpResponseOptions {
|
||||
export interface CustomHttpResponseOptions extends HttpResponseOptions {
|
||||
statusCode: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* HTTP response parameters
|
||||
* HTTP response parameters for redirection response
|
||||
* @public
|
||||
*/
|
||||
export type RedirectResponseOptions = HttpResponseOptions & {
|
||||
|
@ -101,7 +85,99 @@ export type RedirectResponseOptions = HttpResponseOptions & {
|
|||
};
|
||||
};
|
||||
|
||||
export const responseFactory = {
|
||||
/**
|
||||
* Set of helpers used to create `KibanaResponse` to form HTTP response on an incoming request.
|
||||
* Should be returned as a result of {@link RequestHandler} execution.
|
||||
*
|
||||
* @example
|
||||
* 1. Successful response. Supported types of response body are:
|
||||
* - `undefined`, no content to send.
|
||||
* - `string`, send text
|
||||
* - `JSON`, send JSON object, HTTP server will throw if given object is not valid (has circular references, for example)
|
||||
* - `Stream` send data stream
|
||||
* - `Buffer` send binary stream
|
||||
* ```js
|
||||
* return response.ok(undefined);
|
||||
* return response.ok('ack');
|
||||
* return response.ok({ id: '1' });
|
||||
* return response.ok(Buffer.from(...););
|
||||
*
|
||||
* const stream = new Stream.PassThrough();
|
||||
* fs.createReadStream('./file').pipe(stream);
|
||||
* return res.ok(stream);
|
||||
* ```
|
||||
* HTTP headers are configurable via response factory parameter `options` {@link HttpResponseOptions}.
|
||||
*
|
||||
* ```js
|
||||
* return response.ok({ id: '1' }, {
|
||||
* headers: {
|
||||
* 'content-type': 'application/json'
|
||||
* }
|
||||
* });
|
||||
* ```
|
||||
* 2. Redirection response. Redirection URL is configures via 'Location' header.
|
||||
* ```js
|
||||
* return response.redirected('The document has moved', {
|
||||
* headers: {
|
||||
* location: '/new-url',
|
||||
* },
|
||||
* });
|
||||
* ```
|
||||
* 3. Error response. You may pass an error message to the client, where error message can be:
|
||||
* - `string` send message text
|
||||
* - `Error` send the message text of given Error object.
|
||||
* - `{ message: string | Error, meta: {data: Record<string, any>, ...} }` - send message text and attach additional error metadata.
|
||||
* ```js
|
||||
* return response.unauthorized('User has no access to the requested resource.', {
|
||||
* headers: {
|
||||
* 'WWW-Authenticate': 'challenge',
|
||||
* }
|
||||
* })
|
||||
* return response.badRequest();
|
||||
* return response.badRequest('validation error');
|
||||
*
|
||||
* try {
|
||||
* // ...
|
||||
* } catch(error){
|
||||
* return response.badRequest(error);
|
||||
* }
|
||||
*
|
||||
* return response.badRequest({
|
||||
* message: 'validation error',
|
||||
* meta: {
|
||||
* data: {
|
||||
* requestBody: request.body,
|
||||
* failedFields: validationResult
|
||||
* },
|
||||
* }
|
||||
* });
|
||||
*
|
||||
* try {
|
||||
* // ...
|
||||
* } catch(error) {
|
||||
* return response.badRequest({
|
||||
* message: error,
|
||||
* meta: {
|
||||
* data: {
|
||||
* requestBody: request.body,
|
||||
* },
|
||||
* }
|
||||
* });
|
||||
* }
|
||||
*
|
||||
* ```
|
||||
* 4. Custom response. `ResponseFactory` may not cover your use case, so you can use the `custom` function to customize the response.
|
||||
* ```js
|
||||
* return response.custom('ok', {
|
||||
* statusCode: 201,
|
||||
* headers: {
|
||||
* location: '/created-url'
|
||||
* }
|
||||
* })
|
||||
* ```
|
||||
* @public
|
||||
*/
|
||||
export const kibanaResponseFactory = {
|
||||
// Success
|
||||
/**
|
||||
* The request has succeeded.
|
||||
|
@ -131,9 +207,9 @@ export const responseFactory = {
|
|||
/**
|
||||
* Creates a response with defined status code and payload.
|
||||
* @param payload - {@link HttpResponsePayload} payload to send to the client
|
||||
* @param options - {@link CustomResponseOptions} configures HTTP response parameters.
|
||||
* @param options - {@link CustomHttpResponseOptions} configures HTTP response parameters.
|
||||
*/
|
||||
custom: (payload: HttpResponsePayload | ResponseError, options: CustomResponseOptions) => {
|
||||
custom: (payload: HttpResponsePayload | ResponseError, options: CustomHttpResponseOptions) => {
|
||||
if (!options || !options.statusCode) {
|
||||
throw new Error(`options.statusCode is expected to be set. given options: ${options}`);
|
||||
}
|
||||
|
@ -213,4 +289,4 @@ export const responseFactory = {
|
|||
* Creates an object containing request response payload, HTTP headers, error details, and other data transmitted to the client.
|
||||
* @public
|
||||
*/
|
||||
export type ResponseFactory = typeof responseFactory;
|
||||
export type KibanaResponseFactory = typeof kibanaResponseFactory;
|
||||
|
|
|
@ -21,18 +21,18 @@ import { ObjectType } from '@kbn/config-schema';
|
|||
/**
|
||||
* The set of common HTTP methods supported by Kibana routing.
|
||||
* @public
|
||||
* */
|
||||
*/
|
||||
export type RouteMethod = 'get' | 'post' | 'put' | 'delete';
|
||||
|
||||
/**
|
||||
* Route specific configuration.
|
||||
* Additional route options.
|
||||
* @public
|
||||
* */
|
||||
*/
|
||||
export interface RouteConfigOptions {
|
||||
/**
|
||||
* A flag shows that authentication for a route:
|
||||
* enabled when true
|
||||
* disabled when false
|
||||
* `enabled` when true
|
||||
* `disabled` when false
|
||||
*
|
||||
* Enabled by default.
|
||||
*/
|
||||
|
@ -44,27 +44,58 @@ export interface RouteConfigOptions {
|
|||
tags?: readonly string[];
|
||||
}
|
||||
|
||||
/**
|
||||
* Route specific configuration.
|
||||
* @public
|
||||
*/
|
||||
export interface RouteConfig<P extends ObjectType, Q extends ObjectType, B extends ObjectType> {
|
||||
/**
|
||||
* The endpoint _within_ the router path to register the route. E.g. if the
|
||||
* router is registered at `/elasticsearch` and the route path is `/search`,
|
||||
* the full path for the route is `/elasticsearch/search`.
|
||||
* Supports:
|
||||
* - named path segments `path/{name}`.
|
||||
* - optional path segments `path/{position?}`.
|
||||
* - multi-segments `path/{coordinates*2}`.
|
||||
* Segments are accessible within a handler function as `params` property of {@link KibanaRequest} object.
|
||||
* To have read access to `params` you *must* specify validation schema with {@link RouteConfig.validate}.
|
||||
*/
|
||||
path: string;
|
||||
|
||||
/**
|
||||
* A schema created with `@kbn/config-schema` that every request will be validated against.
|
||||
*
|
||||
* You *must* specify a validation schema to be able to read:
|
||||
* - url path segments
|
||||
* - request query
|
||||
* - request body
|
||||
* To opt out of validating the request, specify `false`.
|
||||
* @example
|
||||
* ```ts
|
||||
* import { schema } from '@kbn/config-schema';
|
||||
* router.get({
|
||||
* path: 'path/{id}'
|
||||
* validate: {
|
||||
* params: schema.object({
|
||||
* id: schema.string(),
|
||||
* }),
|
||||
* query: schema.object({...}),
|
||||
* body: schema.object({...}),
|
||||
* },
|
||||
* })
|
||||
* ```
|
||||
*/
|
||||
validate: RouteSchemas<P, Q, B> | false;
|
||||
|
||||
/**
|
||||
* Additional route options {@link RouteConfigOptions}.
|
||||
*/
|
||||
options?: RouteConfigOptions;
|
||||
}
|
||||
|
||||
/**
|
||||
* RouteSchemas contains the schemas for validating the different parts of a
|
||||
* request.
|
||||
* @public
|
||||
*/
|
||||
export interface RouteSchemas<P extends ObjectType, Q extends ObjectType, B extends ObjectType> {
|
||||
params?: P;
|
||||
|
|
|
@ -22,25 +22,41 @@ import { Request, ResponseObject, ResponseToolkit } from 'hapi';
|
|||
|
||||
import { Logger } from '../../logging';
|
||||
import { KibanaRequest } from './request';
|
||||
import { KibanaResponse, ResponseFactory, responseFactory } from './response';
|
||||
import { KibanaResponse, KibanaResponseFactory, kibanaResponseFactory } from './response';
|
||||
import { RouteConfig, RouteConfigOptions, RouteMethod, RouteSchemas } from './route';
|
||||
import { HapiResponseAdapter } from './response_adapter';
|
||||
|
||||
export interface RouterRoute {
|
||||
interface RouterRoute {
|
||||
method: RouteMethod;
|
||||
path: string;
|
||||
options: RouteConfigOptions;
|
||||
handler: (req: Request, responseToolkit: ResponseToolkit, log: Logger) => Promise<ResponseObject>;
|
||||
}
|
||||
|
||||
/** @public */
|
||||
/**
|
||||
* Provides ability to declare a handler function for a particular path and HTTP request method.
|
||||
* Each route can have only one handler functions, which is executed when the route is matched.
|
||||
*
|
||||
* @example
|
||||
* ```ts
|
||||
* const router = new Router('my-app');
|
||||
* // handler is called when 'my-app/path' resource is requested with `GET` method
|
||||
* router.get({ path: '/path', validate: false }, (req, res) => res.ok({ content: 'ok' }));
|
||||
* ```
|
||||
*
|
||||
* @public
|
||||
* */
|
||||
export class Router {
|
||||
public routes: Array<Readonly<RouterRoute>> = [];
|
||||
|
||||
/**
|
||||
* @param path - a router path, set as the very first path segment for all registered routes.
|
||||
*/
|
||||
constructor(readonly path: string) {}
|
||||
|
||||
/**
|
||||
* Register a `GET` request with the router
|
||||
* Register a route handler for `GET` request.
|
||||
* @param route {@link RouteConfig} - a route configuration.
|
||||
* @param handler {@link RequestHandler} - a function to call to respond to an incoming request
|
||||
*/
|
||||
public get<P extends ObjectType, Q extends ObjectType, B extends ObjectType>(
|
||||
route: RouteConfig<P, Q, B>,
|
||||
|
@ -58,7 +74,9 @@ export class Router {
|
|||
}
|
||||
|
||||
/**
|
||||
* Register a `POST` request with the router
|
||||
* 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
|
||||
*/
|
||||
public post<P extends ObjectType, Q extends ObjectType, B extends ObjectType>(
|
||||
route: RouteConfig<P, Q, B>,
|
||||
|
@ -76,7 +94,9 @@ export class Router {
|
|||
}
|
||||
|
||||
/**
|
||||
* Register a `PUT` request with the router
|
||||
* 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
|
||||
*/
|
||||
public put<P extends ObjectType, Q extends ObjectType, B extends ObjectType>(
|
||||
route: RouteConfig<P, Q, B>,
|
||||
|
@ -94,7 +114,9 @@ export class Router {
|
|||
}
|
||||
|
||||
/**
|
||||
* Register a `DELETE` request with the router
|
||||
* 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
|
||||
*/
|
||||
public delete<P extends ObjectType, Q extends ObjectType, B extends ObjectType>(
|
||||
route: RouteConfig<P, Q, B>,
|
||||
|
@ -114,13 +136,14 @@ export class Router {
|
|||
/**
|
||||
* Returns all routes registered with the this router.
|
||||
* @returns List of registered routes.
|
||||
* @internal
|
||||
*/
|
||||
public getRoutes() {
|
||||
return [...this.routes];
|
||||
}
|
||||
|
||||
/**
|
||||
* Create the schemas for a route
|
||||
* Create the validation schemas for a route
|
||||
*
|
||||
* @returns Route schemas if `validate` is specified on the route, otherwise
|
||||
* undefined.
|
||||
|
@ -167,7 +190,7 @@ export class Router {
|
|||
}
|
||||
|
||||
try {
|
||||
const kibanaResponse = await handler(kibanaRequest, responseFactory);
|
||||
const kibanaResponse = await handler(kibanaRequest, kibanaResponseFactory);
|
||||
return hapiResponseAdapter.handle(kibanaResponse);
|
||||
} catch (e) {
|
||||
log.error(e);
|
||||
|
@ -176,7 +199,40 @@ export class Router {
|
|||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* A function executed when route path matched requested resource path.
|
||||
* Request handler is expected to return a result of one of {@link KibanaResponseFactory} functions.
|
||||
* @param request {@link KibanaRequest} - object containing information about requested resource,
|
||||
* such as path, method, headers, parameters, query, body, etc.
|
||||
* @param response {@link KibanaResponseFactory} - a set of helper functions used to respond to a request.
|
||||
*
|
||||
* @example
|
||||
* ```ts
|
||||
* const router = new Router('my-app');
|
||||
* // creates a route handler for GET request on 'my-app/path/{id}' path
|
||||
* router.get(
|
||||
* {
|
||||
* path: 'path/{id}',
|
||||
* // defines a validation schema for a named segment of the route path
|
||||
* validate: {
|
||||
* params: schema.object({
|
||||
* id: schema.string(),
|
||||
* }),
|
||||
* },
|
||||
* },
|
||||
* // function to execute to create a responses
|
||||
* async (request, response) => {
|
||||
* const data = await findObject(request.params.id);
|
||||
* // creates a command to respond with 'not found' error
|
||||
* if (!data) return response.notFound();
|
||||
* // creates a command to send found data to the client
|
||||
* return response.ok(data);
|
||||
* }
|
||||
* );
|
||||
* ```
|
||||
* @public
|
||||
*/
|
||||
export type RequestHandler<P extends ObjectType, Q extends ObjectType, B extends ObjectType> = (
|
||||
request: KibanaRequest<TypeOf<P>, TypeOf<Q>, TypeOf<B>>,
|
||||
createResponse: ResponseFactory
|
||||
response: KibanaResponseFactory
|
||||
) => KibanaResponse<any> | Promise<KibanaResponse<any>>;
|
||||
|
|
|
@ -56,27 +56,41 @@ export {
|
|||
ElasticsearchErrorHelpers,
|
||||
APICaller,
|
||||
FakeRequest,
|
||||
LegacyRequest,
|
||||
} from './elasticsearch';
|
||||
export {
|
||||
AuthenticationHandler,
|
||||
AuthHeaders,
|
||||
AuthResultParams,
|
||||
AuthStatus,
|
||||
AuthToolkit,
|
||||
CustomHttpResponseOptions,
|
||||
GetAuthHeaders,
|
||||
GetAuthState,
|
||||
HttpResponseOptions,
|
||||
HttpResponsePayload,
|
||||
HttpServerSetup,
|
||||
IsAuthenticated,
|
||||
KibanaRequest,
|
||||
KibanaRequestRoute,
|
||||
KnownHeaders,
|
||||
LegacyRequest,
|
||||
OnPreAuthHandler,
|
||||
OnPreAuthToolkit,
|
||||
OnPostAuthHandler,
|
||||
OnPostAuthToolkit,
|
||||
RedirectResponseOptions,
|
||||
RequestHandler,
|
||||
ResponseError,
|
||||
ResponseErrorMeta,
|
||||
kibanaResponseFactory,
|
||||
KibanaResponseFactory,
|
||||
RouteConfig,
|
||||
Router,
|
||||
RouteMethod,
|
||||
RouteConfigOptions,
|
||||
SessionStorageFactory,
|
||||
SessionStorage,
|
||||
SessionStorageCookieOptions,
|
||||
SessionStorageFactory,
|
||||
} from './http';
|
||||
export { Logger, LoggerFactory, LogMeta, LogRecord, LogLevel } from './logging';
|
||||
|
||||
|
|
|
@ -39,6 +39,13 @@ export interface AuthResultParams {
|
|||
state?: Record<string, any>;
|
||||
}
|
||||
|
||||
// @public
|
||||
export enum AuthStatus {
|
||||
authenticated = "authenticated",
|
||||
unauthenticated = "unauthenticated",
|
||||
unknown = "unknown"
|
||||
}
|
||||
|
||||
// @public
|
||||
export interface AuthToolkit {
|
||||
authenticated: (data?: AuthResultParams) => AuthResult;
|
||||
|
@ -108,6 +115,12 @@ export interface CoreSetup {
|
|||
export interface CoreStart {
|
||||
}
|
||||
|
||||
// @public
|
||||
export interface CustomHttpResponseOptions extends HttpResponseOptions {
|
||||
// (undocumented)
|
||||
statusCode: number;
|
||||
}
|
||||
|
||||
// @public
|
||||
export interface DiscoveredPlugin {
|
||||
readonly configPath: ConfigPath;
|
||||
|
@ -161,13 +174,55 @@ export interface FakeRequest {
|
|||
}
|
||||
|
||||
// @public
|
||||
export type GetAuthHeaders = (request: KibanaRequest | Request) => AuthHeaders | undefined;
|
||||
export type GetAuthHeaders = (request: KibanaRequest | LegacyRequest) => AuthHeaders | undefined;
|
||||
|
||||
// @public (undocumented)
|
||||
export type Headers = Record<string, string | string[] | undefined>;
|
||||
// @public
|
||||
export type GetAuthState = (request: KibanaRequest | LegacyRequest) => {
|
||||
status: AuthStatus;
|
||||
state: unknown;
|
||||
};
|
||||
|
||||
// @public
|
||||
export type Headers = {
|
||||
[header in KnownHeaders]?: string | string[] | undefined;
|
||||
} & {
|
||||
[header: string]: string | string[] | undefined;
|
||||
};
|
||||
|
||||
// @public
|
||||
export interface HttpResponseOptions {
|
||||
// Warning: (ae-forgotten-export) The symbol "ResponseHeaders" needs to be exported by the entry point index.d.ts
|
||||
headers?: ResponseHeaders;
|
||||
}
|
||||
|
||||
// @public
|
||||
export type HttpResponsePayload = undefined | string | Record<string, any> | Buffer | Stream;
|
||||
|
||||
// @public
|
||||
export interface HttpServerSetup {
|
||||
// (undocumented)
|
||||
auth: {
|
||||
get: GetAuthState;
|
||||
isAuthenticated: IsAuthenticated;
|
||||
getAuthHeaders: GetAuthHeaders;
|
||||
};
|
||||
// (undocumented)
|
||||
basePath: {
|
||||
get: (request: KibanaRequest | LegacyRequest) => string;
|
||||
set: (request: KibanaRequest | LegacyRequest, basePath: string) => void;
|
||||
prepend: (url: string) => string;
|
||||
remove: (url: string) => string;
|
||||
};
|
||||
createCookieSessionStorageFactory: <T>(cookieOptions: SessionStorageCookieOptions<T>) => Promise<SessionStorageFactory<T>>;
|
||||
isTlsEnabled: boolean;
|
||||
registerAuth: (handler: AuthenticationHandler) => void;
|
||||
registerOnPostAuth: (handler: OnPostAuthHandler) => void;
|
||||
registerOnPreAuth: (handler: OnPreAuthHandler) => void;
|
||||
registerRouter: (router: Router) => void;
|
||||
// (undocumented)
|
||||
server: Server;
|
||||
}
|
||||
|
||||
// Warning: (ae-forgotten-export) The symbol "HttpServerSetup" needs to be exported by the entry point index.d.ts
|
||||
//
|
||||
// @public (undocumented)
|
||||
export type HttpServiceSetup = HttpServerSetup;
|
||||
|
||||
|
@ -192,6 +247,9 @@ export interface InternalCoreStart {
|
|||
plugins: PluginsServiceStart;
|
||||
}
|
||||
|
||||
// @public
|
||||
export type IsAuthenticated = (request: KibanaRequest | LegacyRequest) => boolean;
|
||||
|
||||
// @public
|
||||
export class KibanaRequest<Params = unknown, Query = unknown, Body = unknown> {
|
||||
// @internal (undocumented)
|
||||
|
@ -208,9 +266,7 @@ export class KibanaRequest<Params = unknown, Query = unknown, Body = unknown> {
|
|||
readonly params: Params;
|
||||
// (undocumented)
|
||||
readonly query: Query;
|
||||
// (undocumented)
|
||||
readonly route: RecursiveReadonly<KibanaRequestRoute>;
|
||||
// (undocumented)
|
||||
readonly url: Url;
|
||||
}
|
||||
|
||||
|
@ -225,7 +281,37 @@ export interface KibanaRequestRoute {
|
|||
}
|
||||
|
||||
// @public
|
||||
export type LegacyRequest = Request;
|
||||
export type KibanaResponseFactory = typeof kibanaResponseFactory;
|
||||
|
||||
// @public
|
||||
export const kibanaResponseFactory: {
|
||||
ok: (payload: HttpResponsePayload, options?: HttpResponseOptions) => KibanaResponse<string | Record<string, any> | Buffer | Stream>;
|
||||
accepted: (payload?: HttpResponsePayload, options?: HttpResponseOptions) => KibanaResponse<string | Record<string, any> | Buffer | Stream>;
|
||||
noContent: (options?: HttpResponseOptions) => KibanaResponse<undefined>;
|
||||
custom: (payload: string | Error | Record<string, any> | Buffer | Stream | {
|
||||
message: string | Error;
|
||||
meta?: ResponseErrorMeta | undefined;
|
||||
} | undefined, options: CustomHttpResponseOptions) => KibanaResponse<string | Error | Record<string, any> | Buffer | Stream | {
|
||||
message: string | Error;
|
||||
meta?: ResponseErrorMeta | undefined;
|
||||
}>;
|
||||
redirected: (payload: HttpResponsePayload, options: RedirectResponseOptions) => KibanaResponse<string | Record<string, any> | Buffer | Stream>;
|
||||
badRequest: (error?: ResponseError, options?: HttpResponseOptions) => KibanaResponse<ResponseError>;
|
||||
unauthorized: (error?: ResponseError, options?: HttpResponseOptions) => KibanaResponse<ResponseError>;
|
||||
forbidden: (error?: ResponseError, options?: HttpResponseOptions) => KibanaResponse<ResponseError>;
|
||||
notFound: (error?: ResponseError, options?: HttpResponseOptions) => KibanaResponse<ResponseError>;
|
||||
conflict: (error?: ResponseError, options?: HttpResponseOptions) => KibanaResponse<ResponseError>;
|
||||
internal: (error?: ResponseError, options?: HttpResponseOptions) => KibanaResponse<ResponseError>;
|
||||
};
|
||||
|
||||
// Warning: (ae-forgotten-export) The symbol "KnownKeys" needs to be exported by the entry point index.d.ts
|
||||
//
|
||||
// @public
|
||||
export type KnownHeaders = KnownKeys<IncomingHttpHeaders>;
|
||||
|
||||
// @public @deprecated (undocumented)
|
||||
export interface LegacyRequest extends Request {
|
||||
}
|
||||
|
||||
// @public
|
||||
export interface Logger {
|
||||
|
@ -381,6 +467,16 @@ export type RecursiveReadonly<T> = T extends (...args: any[]) => any ? T : T ext
|
|||
[K in keyof T]: RecursiveReadonly<T[K]>;
|
||||
}> : T;
|
||||
|
||||
// @public
|
||||
export type RedirectResponseOptions = HttpResponseOptions & {
|
||||
headers: {
|
||||
location: string;
|
||||
};
|
||||
};
|
||||
|
||||
// @public
|
||||
export type RequestHandler<P extends ObjectType, Q extends ObjectType, B extends ObjectType> = (request: KibanaRequest<TypeOf<P>, TypeOf<Q>, TypeOf<B>>, response: KibanaResponseFactory) => KibanaResponse<any> | Promise<KibanaResponse<any>>;
|
||||
|
||||
// @public
|
||||
export type ResponseError = string | Error | {
|
||||
message: string | Error;
|
||||
|
@ -397,6 +493,13 @@ export interface ResponseErrorMeta {
|
|||
errorCode?: string;
|
||||
}
|
||||
|
||||
// @public
|
||||
export interface RouteConfig<P extends ObjectType, Q extends ObjectType, B extends ObjectType> {
|
||||
options?: RouteConfigOptions;
|
||||
path: string;
|
||||
validate: RouteSchemas<P, Q, B> | false;
|
||||
}
|
||||
|
||||
// @public
|
||||
export interface RouteConfigOptions {
|
||||
authRequired?: boolean;
|
||||
|
@ -406,13 +509,12 @@ export interface RouteConfigOptions {
|
|||
// @public
|
||||
export type RouteMethod = 'get' | 'post' | 'put' | 'delete';
|
||||
|
||||
// @public (undocumented)
|
||||
// @public
|
||||
export class Router {
|
||||
constructor(path: string);
|
||||
delete<P extends ObjectType, Q extends ObjectType, B extends ObjectType>(route: RouteConfig<P, Q, B>, handler: RequestHandler<P, Q, B>): void;
|
||||
// Warning: (ae-forgotten-export) The symbol "RouteConfig" needs to be exported by the entry point index.d.ts
|
||||
// Warning: (ae-forgotten-export) The symbol "RequestHandler" needs to be exported by the entry point index.d.ts
|
||||
get<P extends ObjectType, Q extends ObjectType, B extends ObjectType>(route: RouteConfig<P, Q, B>, handler: RequestHandler<P, Q, B>): void;
|
||||
// @internal
|
||||
getRoutes(): Readonly<RouterRoute>[];
|
||||
// (undocumented)
|
||||
readonly path: string;
|
||||
|
@ -861,7 +963,7 @@ export interface SavedObjectsUpdateResponse<T extends SavedObjectAttributes = an
|
|||
|
||||
// @public
|
||||
export class ScopedClusterClient {
|
||||
constructor(internalAPICaller: APICaller, scopedAPICaller: APICaller, headers?: Record<string, string | string[] | undefined> | undefined);
|
||||
constructor(internalAPICaller: APICaller, scopedAPICaller: APICaller, headers?: Headers | undefined);
|
||||
callAsCurrentUser(endpoint: string, clientParams?: Record<string, any>, options?: CallAPIOptions): Promise<unknown>;
|
||||
callAsInternalUser(endpoint: string, clientParams?: Record<string, any>, options?: CallAPIOptions): Promise<unknown>;
|
||||
}
|
||||
|
@ -873,6 +975,14 @@ export interface SessionStorage<T> {
|
|||
set(sessionValue: T): void;
|
||||
}
|
||||
|
||||
// @public
|
||||
export interface SessionStorageCookieOptions<T> {
|
||||
encryptionKey: string;
|
||||
isSecure: boolean;
|
||||
name: string;
|
||||
validate: (sessionValue: T) => boolean | Promise<boolean>;
|
||||
}
|
||||
|
||||
// @public
|
||||
export interface SessionStorageFactory<T> {
|
||||
// (undocumented)
|
||||
|
@ -882,6 +992,7 @@ export interface SessionStorageFactory<T> {
|
|||
|
||||
// Warnings were encountered during analysis:
|
||||
//
|
||||
// src/core/server/http/router/response.ts:188:3 - (ae-forgotten-export) The symbol "KibanaResponse" needs to be exported by the entry point index.d.ts
|
||||
// src/core/server/plugins/plugin_context.ts:34:10 - (ae-forgotten-export) The symbol "EnvironmentMode" needs to be exported by the entry point index.d.ts
|
||||
// src/core/server/plugins/plugins_service.ts:37:5 - (ae-forgotten-export) The symbol "DiscoveredPluginInternal" needs to be exported by the entry point index.d.ts
|
||||
|
||||
|
|
Loading…
Add table
Add a link
Reference in a new issue