diff --git a/docs/development/core/server/kibana-plugin-server.basepath.get.md b/docs/development/core/server/kibana-plugin-server.basepath.get.md new file mode 100644 index 00000000000000..2b3b6c899e8ded --- /dev/null +++ b/docs/development/core/server/kibana-plugin-server.basepath.get.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [BasePath](./kibana-plugin-server.basepath.md) > [get](./kibana-plugin-server.basepath.get.md) + +## BasePath.get property + +returns `basePath` value, specific for an incoming request. + +Signature: + +```typescript +get: (request: KibanaRequest | LegacyRequest) => string; +``` diff --git a/docs/development/core/server/kibana-plugin-server.basepath.md b/docs/development/core/server/kibana-plugin-server.basepath.md new file mode 100644 index 00000000000000..45fb697b329f89 --- /dev/null +++ b/docs/development/core/server/kibana-plugin-server.basepath.md @@ -0,0 +1,28 @@ + + +[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [BasePath](./kibana-plugin-server.basepath.md) + +## BasePath class + +Access or manipulate the Kibana base path + +Signature: + +```typescript +export declare class BasePath +``` + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [get](./kibana-plugin-server.basepath.get.md) | | (request: KibanaRequest<unknown, unknown, unknown> | LegacyRequest) => string | returns basePath value, specific for an incoming request. | +| [prepend](./kibana-plugin-server.basepath.prepend.md) | | (path: string) => string | returns a new basePath value, prefixed with passed url. | +| [remove](./kibana-plugin-server.basepath.remove.md) | | (path: string) => string | returns a new basePath value, cleaned up from passed url. | +| [serverBasePath](./kibana-plugin-server.basepath.serverbasepath.md) | | string | returns the server's basePathSee [BasePath.get](./kibana-plugin-server.basepath.get.md) for getting the basePath value for a specific request | +| [set](./kibana-plugin-server.basepath.set.md) | | (request: KibanaRequest<unknown, unknown, unknown> | LegacyRequest, requestSpecificBasePath: string) => void | sets basePath value, specific for an incoming request. | + +## Remarks + +The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `BasePath` class. + diff --git a/docs/development/core/server/kibana-plugin-server.basepath.prepend.md b/docs/development/core/server/kibana-plugin-server.basepath.prepend.md new file mode 100644 index 00000000000000..113e8d9bf48803 --- /dev/null +++ b/docs/development/core/server/kibana-plugin-server.basepath.prepend.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [BasePath](./kibana-plugin-server.basepath.md) > [prepend](./kibana-plugin-server.basepath.prepend.md) + +## BasePath.prepend property + +returns a new `basePath` value, prefixed with passed `url`. + +Signature: + +```typescript +prepend: (path: string) => string; +``` diff --git a/docs/development/core/server/kibana-plugin-server.basepath.remove.md b/docs/development/core/server/kibana-plugin-server.basepath.remove.md new file mode 100644 index 00000000000000..c5f1092d2969d9 --- /dev/null +++ b/docs/development/core/server/kibana-plugin-server.basepath.remove.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [BasePath](./kibana-plugin-server.basepath.md) > [remove](./kibana-plugin-server.basepath.remove.md) + +## BasePath.remove property + +returns a new `basePath` value, cleaned up from passed `url`. + +Signature: + +```typescript +remove: (path: string) => string; +``` diff --git a/docs/development/core/server/kibana-plugin-server.basepath.serverbasepath.md b/docs/development/core/server/kibana-plugin-server.basepath.serverbasepath.md new file mode 100644 index 00000000000000..d7e45a92dba6d7 --- /dev/null +++ b/docs/development/core/server/kibana-plugin-server.basepath.serverbasepath.md @@ -0,0 +1,15 @@ + + +[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [BasePath](./kibana-plugin-server.basepath.md) > [serverBasePath](./kibana-plugin-server.basepath.serverbasepath.md) + +## BasePath.serverBasePath property + +returns the server's basePath + +See [BasePath.get](./kibana-plugin-server.basepath.get.md) for getting the basePath value for a specific request + +Signature: + +```typescript +readonly serverBasePath: string; +``` diff --git a/docs/development/core/server/kibana-plugin-server.basepath.set.md b/docs/development/core/server/kibana-plugin-server.basepath.set.md new file mode 100644 index 00000000000000..1272a134ef5c44 --- /dev/null +++ b/docs/development/core/server/kibana-plugin-server.basepath.set.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [BasePath](./kibana-plugin-server.basepath.md) > [set](./kibana-plugin-server.basepath.set.md) + +## BasePath.set property + +sets `basePath` value, specific for an incoming request. + +Signature: + +```typescript +set: (request: KibanaRequest | LegacyRequest, requestSpecificBasePath: string) => void; +``` diff --git a/docs/development/core/server/kibana-plugin-server.httpserversetup.basepath.md b/docs/development/core/server/kibana-plugin-server.httpserversetup.basepath.md index 5cfb2f5c4e8b43..173262de10494f 100644 --- a/docs/development/core/server/kibana-plugin-server.httpserversetup.basepath.md +++ b/docs/development/core/server/kibana-plugin-server.httpserversetup.basepath.md @@ -4,13 +4,10 @@ ## HttpServerSetup.basePath property +[BasePath](./kibana-plugin-server.basepath.md) + Signature: ```typescript -basePath: { - get: (request: KibanaRequest | LegacyRequest) => string; - set: (request: KibanaRequest | LegacyRequest, basePath: string) => void; - prepend: (url: string) => string; - remove: (url: string) => string; - }; +basePath: IBasePath; ``` diff --git a/docs/development/core/server/kibana-plugin-server.httpserversetup.md b/docs/development/core/server/kibana-plugin-server.httpserversetup.md index f495de850aff5e..7a126383116e7b 100644 --- a/docs/development/core/server/kibana-plugin-server.httpserversetup.md +++ b/docs/development/core/server/kibana-plugin-server.httpserversetup.md @@ -17,7 +17,7 @@ export interface HttpServerSetup | Property | Type | Description | | --- | --- | --- | | [auth](./kibana-plugin-server.httpserversetup.auth.md) | {
get: GetAuthState;
isAuthenticated: IsAuthenticated;
getAuthHeaders: GetAuthHeaders;
} | | -| [basePath](./kibana-plugin-server.httpserversetup.basepath.md) | {
get: (request: KibanaRequest | LegacyRequest) => string;
set: (request: KibanaRequest | LegacyRequest, basePath: string) => void;
prepend: (url: string) => string;
remove: (url: string) => string;
} | | +| [basePath](./kibana-plugin-server.httpserversetup.basepath.md) | IBasePath | [BasePath](./kibana-plugin-server.basepath.md) | | [createCookieSessionStorageFactory](./kibana-plugin-server.httpserversetup.createcookiesessionstoragefactory.md) | <T>(cookieOptions: SessionStorageCookieOptions<T>) => Promise<SessionStorageFactory<T>> | Creates cookie based session storage factory [SessionStorageFactory](./kibana-plugin-server.sessionstoragefactory.md) | | [isTlsEnabled](./kibana-plugin-server.httpserversetup.istlsenabled.md) | boolean | Flag showing whether a server was configured to use TLS connection. | | [registerAuth](./kibana-plugin-server.httpserversetup.registerauth.md) | (handler: AuthenticationHandler) => void | To define custom authentication and/or authorization mechanism for incoming requests. A handler should return a state to associate with the incoming request. The state can be retrieved later via http.auth.get(..) Only one AuthenticationHandler can be registered. | diff --git a/docs/development/core/server/kibana-plugin-server.ibasepath.md b/docs/development/core/server/kibana-plugin-server.ibasepath.md new file mode 100644 index 00000000000000..2baa8d623ce97b --- /dev/null +++ b/docs/development/core/server/kibana-plugin-server.ibasepath.md @@ -0,0 +1,15 @@ + + +[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [IBasePath](./kibana-plugin-server.ibasepath.md) + +## IBasePath type + +Access or manipulate the Kibana base path + +[BasePath](./kibana-plugin-server.basepath.md) + +Signature: + +```typescript +export declare type IBasePath = Pick; +``` diff --git a/docs/development/core/server/kibana-plugin-server.md b/docs/development/core/server/kibana-plugin-server.md index baecb180096de9..fec2fc4b64019f 100644 --- a/docs/development/core/server/kibana-plugin-server.md +++ b/docs/development/core/server/kibana-plugin-server.md @@ -16,6 +16,7 @@ The plugin integrates with the core system via lifecycle events: `setup` | Class | Description | | --- | --- | +| [BasePath](./kibana-plugin-server.basepath.md) | Access or manipulate the Kibana base path | | [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 asScoped(...)). | | [ElasticsearchErrorHelpers](./kibana-plugin-server.elasticsearcherrorhelpers.md) | Helpers for working with errors returned from the Elasticsearch service.Since the internal data of errors are subject to change, consumers of the Elasticsearch service should always use these helpers to classify errors instead of checking error internals such as body.error.header[WWW-Authenticate] | | [KibanaRequest](./kibana-plugin-server.kibanarequest.md) | Kibana specific abstraction for an incoming request. | @@ -122,6 +123,7 @@ The plugin integrates with the core system via lifecycle events: `setup` | [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) | | +| [IBasePath](./kibana-plugin-server.ibasepath.md) | Access or manipulate the Kibana base path[BasePath](./kibana-plugin-server.basepath.md) | | [IContextHandler](./kibana-plugin-server.icontexthandler.md) | A function registered by a plugin to perform some action. | | [IContextProvider](./kibana-plugin-server.icontextprovider.md) | A function that returns a context value for a specific key of given context type. | | [IsAuthenticated](./kibana-plugin-server.isauthenticated.md) | Return authentication status for a request. | diff --git a/src/core/server/http/base_path_service.test.ts b/src/core/server/http/base_path_service.test.ts index ffbbe158cb2d4d..01790b7c77e064 100644 --- a/src/core/server/http/base_path_service.test.ts +++ b/src/core/server/http/base_path_service.test.ts @@ -22,6 +22,18 @@ import { KibanaRequest } from './router'; import { httpServerMock } from './http_server.mocks'; describe('BasePath', () => { + describe('serverBasePath', () => { + it('defaults to an empty string', () => { + const basePath = new BasePath(); + expect(basePath.serverBasePath).toBe(''); + }); + + it('returns the server base path', () => { + const basePath = new BasePath('/server'); + expect(basePath.serverBasePath).toBe('/server'); + }); + }); + describe('#get()', () => { it('returns base path associated with an incoming Legacy.Request request', () => { const request = httpServerMock.createRawRequest(); diff --git a/src/core/server/http/base_path_service.ts b/src/core/server/http/base_path_service.ts index 951463a2c9919f..916419cac212a1 100644 --- a/src/core/server/http/base_path_service.ts +++ b/src/core/server/http/base_path_service.ts @@ -20,18 +20,39 @@ import { ensureRawRequest, KibanaRequest, LegacyRequest } from './router'; import { modifyUrl } from '../../utils'; +/** + * Access or manipulate the Kibana base path + * + * @public + */ export class BasePath { private readonly basePathCache = new WeakMap(); - constructor(private readonly serverBasePath?: string) {} + /** + * returns the server's basePath + * + * See {@link BasePath.get} for getting the basePath value for a specific request + */ + public readonly serverBasePath: string; + + /** @internal */ + constructor(serverBasePath: string = '') { + this.serverBasePath = serverBasePath; + } + /** + * returns `basePath` value, specific for an incoming request. + */ public get = (request: KibanaRequest | LegacyRequest) => { const requestScopePath = this.basePathCache.get(ensureRawRequest(request)) || ''; - const serverBasePath = this.serverBasePath || ''; - return `${serverBasePath}${requestScopePath}`; + return `${this.serverBasePath}${requestScopePath}`; }; - // should work only for KibanaRequest as soon as spaces migrate to NP + /** + * sets `basePath` value, specific for an incoming request. + * + * @privateRemarks should work only for KibanaRequest as soon as spaces migrate to NP + */ public set = (request: KibanaRequest | LegacyRequest, requestSpecificBasePath: string) => { const rawRequest = ensureRawRequest(request); @@ -43,8 +64,11 @@ export class BasePath { this.basePathCache.set(rawRequest, requestSpecificBasePath); }; + /** + * returns a new `basePath` value, prefixed with passed `url`. + */ public prepend = (path: string): string => { - if (!this.serverBasePath) return path; + if (this.serverBasePath === '') return path; return modifyUrl(path, parts => { if (!parts.hostname && parts.pathname && parts.pathname.startsWith('/')) { parts.pathname = `${this.serverBasePath}${parts.pathname}`; @@ -52,8 +76,11 @@ export class BasePath { }); }; + /** + * returns a new `basePath` value, cleaned up from passed `url`. + */ public remove = (path: string): string => { - if (!this.serverBasePath) { + if (this.serverBasePath === '') { return path; } @@ -68,3 +95,11 @@ export class BasePath { return path; }; } + +/** + * Access or manipulate the Kibana base path + * + * {@link BasePath} + * @public + */ +export type IBasePath = Pick; diff --git a/src/core/server/http/http_server.ts b/src/core/server/http/http_server.ts index cb6906379c4ef3..b56fef5f65c2a9 100644 --- a/src/core/server/http/http_server.ts +++ b/src/core/server/http/http_server.ts @@ -26,7 +26,7 @@ import { adoptToHapiAuthFormat, AuthenticationHandler } from './lifecycle/auth'; import { adoptToHapiOnPostAuthFormat, OnPostAuthHandler } from './lifecycle/on_post_auth'; import { adoptToHapiOnPreAuthFormat, OnPreAuthHandler } from './lifecycle/on_pre_auth'; -import { KibanaRequest, LegacyRequest, ResponseHeaders, IRouter } from './router'; +import { ResponseHeaders, IRouter } from './router'; import { SessionStorageCookieOptions, createCookieSessionStorageFactory, @@ -34,7 +34,7 @@ import { import { SessionStorageFactory } from './session_storage'; import { AuthStateStorage, GetAuthState, IsAuthenticated } from './auth_state_storage'; import { AuthHeadersStorage, GetAuthHeaders } from './auth_headers_storage'; -import { BasePath } from './base_path_service'; +import { BasePath, IBasePath } from './base_path_service'; /** * Kibana HTTP Service provides own abstraction for work with HTTP stack. @@ -148,24 +148,8 @@ export interface HttpServerSetup { * @param handler {@link OnPostAuthHandler} - function to call. */ registerOnPostAuth: (handler: OnPostAuthHandler) => void; - basePath: { - /** - * 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; - }; + /** {@link BasePath} */ + basePath: IBasePath; auth: { get: GetAuthState; isAuthenticated: IsAuthenticated; diff --git a/src/core/server/http/http_service.mock.ts b/src/core/server/http/http_service.mock.ts index c5f920dcb360e1..c0658ae8d1e5c4 100644 --- a/src/core/server/http/http_service.mock.ts +++ b/src/core/server/http/http_service.mock.ts @@ -30,6 +30,7 @@ type ServiceSetupMockType = jest.Mocked & { }; const createBasePathMock = (): jest.Mocked => ({ + serverBasePath: '/mock-server-basepath', get: jest.fn(), set: jest.fn(), prepend: jest.fn(), diff --git a/src/core/server/http/index.ts b/src/core/server/http/index.ts index 895396b91eb465..4f83cd996deba8 100644 --- a/src/core/server/http/index.ts +++ b/src/core/server/http/index.ts @@ -58,3 +58,4 @@ export { OnPostAuthHandler, OnPostAuthToolkit } from './lifecycle/on_post_auth'; export { SessionStorageFactory, SessionStorage } from './session_storage'; export { SessionStorageCookieOptions } from './cookie_session_storage'; export * from './types'; +export { BasePath, IBasePath } from './base_path_service'; diff --git a/src/core/server/index.ts b/src/core/server/index.ts index ef31804be62b2b..83328d560ee22f 100644 --- a/src/core/server/index.ts +++ b/src/core/server/index.ts @@ -77,6 +77,8 @@ export { AuthResultParams, AuthStatus, AuthToolkit, + BasePath, + IBasePath, CustomHttpResponseOptions, GetAuthHeaders, GetAuthState, diff --git a/src/core/server/server.api.md b/src/core/server/server.api.md index 94c7f6ec9b3255..0dc1ed50564837 100644 --- a/src/core/server/server.api.md +++ b/src/core/server/server.api.md @@ -54,6 +54,17 @@ export interface AuthToolkit { authenticated: (data?: AuthResultParams) => AuthResult; } +// @public +export class BasePath { + // @internal + constructor(serverBasePath?: string); + get: (request: KibanaRequest | LegacyRequest) => string; + prepend: (path: string) => string; + remove: (path: string) => string; + readonly serverBasePath: string; + set: (request: KibanaRequest | LegacyRequest, requestSpecificBasePath: string) => void; +} + // Warning: (ae-forgotten-export) The symbol "BootstrapArgs" needs to be exported by the entry point index.d.ts // // @internal (undocumented) @@ -230,12 +241,7 @@ export interface HttpServerSetup { getAuthHeaders: GetAuthHeaders; }; // (undocumented) - basePath: { - get: (request: KibanaRequest | LegacyRequest) => string; - set: (request: KibanaRequest | LegacyRequest, basePath: string) => void; - prepend: (url: string) => string; - remove: (url: string) => string; - }; + basePath: IBasePath; createCookieSessionStorageFactory: (cookieOptions: SessionStorageCookieOptions) => Promise>; isTlsEnabled: boolean; registerAuth: (handler: AuthenticationHandler) => void; @@ -257,6 +263,9 @@ export interface HttpServiceStart { isListening: (port: number) => boolean; } +// @public +export type IBasePath = Pick; + // @public export interface IContextContainer { createHandler(pluginOpaqueId: PluginOpaqueId, handler: IContextHandler): (...rest: THandlerParameters) => THandlerReturn extends Promise ? THandlerReturn : Promise;