diff --git a/docs/development/core/server/kibana-plugin-server.configpath.md b/docs/development/core/server/kibana-plugin-server.configpath.md new file mode 100644 index 0000000000000..674769115b181 --- /dev/null +++ b/docs/development/core/server/kibana-plugin-server.configpath.md @@ -0,0 +1,12 @@ + + +[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [ConfigPath](./kibana-plugin-server.configpath.md) + +## ConfigPath type + + +Signature: + +```typescript +export declare type ConfigPath = string | string[]; +``` diff --git a/docs/development/core/server/kibana-plugin-server.md b/docs/development/core/server/kibana-plugin-server.md index bf56b1d2380ab..9d5432312a645 100644 --- a/docs/development/core/server/kibana-plugin-server.md +++ b/docs/development/core/server/kibana-plugin-server.md @@ -6,6 +6,8 @@ The Kibana Core APIs for server-side plugins. +A plugin requires a `kibana.json` file at it's root directory that follows [the manfiest schema](./kibana-plugin-server.pluginmanifest.md) to define static plugin information required to load the plugin. + A plugin's `server/index` file must contain a named import, `plugin`, that implements [PluginInitializer](./kibana-plugin-server.plugininitializer.md) which returns an object that implements [Plugin](./kibana-plugin-server.plugin.md). The plugin integrates with the core system via lifecycle events: `setup`, `start`, and `stop`. In each lifecycle method, the plugin will receive the corresponding core services available (either [CoreSetup](./kibana-plugin-server.coresetup.md) or [CoreStart](./kibana-plugin-server.corestart.md)) and any interfaces returned by dependency plugins' lifecycle method. Anything returned by the plugin's lifecycle method will be exposed to downstream dependencies when their corresponding lifecycle methods are invoked. @@ -57,6 +59,7 @@ The plugin integrates with the core system via lifecycle events: `setup` | [OnPreAuthToolkit](./kibana-plugin-server.onpreauthtoolkit.md) | A tool set defining an outcome of OnPreAuth interceptor for incoming request. | | [Plugin](./kibana-plugin-server.plugin.md) | The interface that should be returned by a PluginInitializer. | | [PluginInitializerContext](./kibana-plugin-server.plugininitializercontext.md) | Context that's available to plugins during initialization stage. | +| [PluginManifest](./kibana-plugin-server.pluginmanifest.md) | Describes the set of required and optional properties plugin can define in its mandatory JSON manifest file. | | [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. | @@ -107,6 +110,7 @@ The plugin integrates with the core system via lifecycle events: `setup` | [APICaller](./kibana-plugin-server.apicaller.md) | | | [AuthenticationHandler](./kibana-plugin-server.authenticationhandler.md) | | | [AuthHeaders](./kibana-plugin-server.authheaders.md) | Auth Headers map | +| [ConfigPath](./kibana-plugin-server.configpath.md) | | | [ElasticsearchClientConfig](./kibana-plugin-server.elasticsearchclientconfig.md) | | | [GetAuthHeaders](./kibana-plugin-server.getauthheaders.md) | Get headers to authenticate a user against Elasticsearch. | | [GetAuthState](./kibana-plugin-server.getauthstate.md) | Get authentication state for a request. Returned by auth interceptor. | diff --git a/docs/development/core/server/kibana-plugin-server.pluginmanifest.configpath.md b/docs/development/core/server/kibana-plugin-server.pluginmanifest.configpath.md new file mode 100644 index 0000000000000..39c1eeda47e0e --- /dev/null +++ b/docs/development/core/server/kibana-plugin-server.pluginmanifest.configpath.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [PluginManifest](./kibana-plugin-server.pluginmanifest.md) > [configPath](./kibana-plugin-server.pluginmanifest.configpath.md) + +## PluginManifest.configPath property + +Root [configuration path](./kibana-plugin-server.configpath.md) used by the plugin, defaults to "id". + +Signature: + +```typescript +readonly configPath: ConfigPath; +``` diff --git a/docs/development/core/server/kibana-plugin-server.pluginmanifest.id.md b/docs/development/core/server/kibana-plugin-server.pluginmanifest.id.md new file mode 100644 index 0000000000000..44e61f11fa215 --- /dev/null +++ b/docs/development/core/server/kibana-plugin-server.pluginmanifest.id.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [PluginManifest](./kibana-plugin-server.pluginmanifest.md) > [id](./kibana-plugin-server.pluginmanifest.id.md) + +## PluginManifest.id property + +Identifier of the plugin. + +Signature: + +```typescript +readonly id: PluginName; +``` diff --git a/docs/development/core/server/kibana-plugin-server.pluginmanifest.kibanaversion.md b/docs/development/core/server/kibana-plugin-server.pluginmanifest.kibanaversion.md new file mode 100644 index 0000000000000..f568dce9a8a9e --- /dev/null +++ b/docs/development/core/server/kibana-plugin-server.pluginmanifest.kibanaversion.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [PluginManifest](./kibana-plugin-server.pluginmanifest.md) > [kibanaVersion](./kibana-plugin-server.pluginmanifest.kibanaversion.md) + +## PluginManifest.kibanaVersion property + +The version of Kibana the plugin is compatible with, defaults to "version". + +Signature: + +```typescript +readonly kibanaVersion: string; +``` diff --git a/docs/development/core/server/kibana-plugin-server.pluginmanifest.md b/docs/development/core/server/kibana-plugin-server.pluginmanifest.md new file mode 100644 index 0000000000000..4a9498f0e9fab --- /dev/null +++ b/docs/development/core/server/kibana-plugin-server.pluginmanifest.md @@ -0,0 +1,31 @@ + + +[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [PluginManifest](./kibana-plugin-server.pluginmanifest.md) + +## PluginManifest interface + +Describes the set of required and optional properties plugin can define in its mandatory JSON manifest file. + +Signature: + +```typescript +export interface PluginManifest +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [configPath](./kibana-plugin-server.pluginmanifest.configpath.md) | ConfigPath | Root [configuration path](./kibana-plugin-server.configpath.md) used by the plugin, defaults to "id". | +| [id](./kibana-plugin-server.pluginmanifest.id.md) | PluginName | Identifier of the plugin. | +| [kibanaVersion](./kibana-plugin-server.pluginmanifest.kibanaversion.md) | string | The version of Kibana the plugin is compatible with, defaults to "version". | +| [optionalPlugins](./kibana-plugin-server.pluginmanifest.optionalplugins.md) | readonly PluginName[] | An optional list of the other plugins that if installed and enabled \*\*may be\*\* leveraged by this plugin for some additional functionality but otherwise are not required for this plugin to work properly. | +| [requiredPlugins](./kibana-plugin-server.pluginmanifest.requiredplugins.md) | readonly PluginName[] | An optional list of the other plugins that \*\*must be\*\* installed and enabled for this plugin to function properly. | +| [server](./kibana-plugin-server.pluginmanifest.server.md) | boolean | Specifies whether plugin includes some server-side specific functionality. | +| [ui](./kibana-plugin-server.pluginmanifest.ui.md) | boolean | Specifies whether plugin includes some client/browser specific functionality that should be included into client bundle via public/ui_plugin.js file. | +| [version](./kibana-plugin-server.pluginmanifest.version.md) | string | Version of the plugin. | + +## Remarks + +Should never be used in code outside of Core but is exported for documentation purposes. + diff --git a/docs/development/core/server/kibana-plugin-server.pluginmanifest.optionalplugins.md b/docs/development/core/server/kibana-plugin-server.pluginmanifest.optionalplugins.md new file mode 100644 index 0000000000000..692785a705d40 --- /dev/null +++ b/docs/development/core/server/kibana-plugin-server.pluginmanifest.optionalplugins.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [PluginManifest](./kibana-plugin-server.pluginmanifest.md) > [optionalPlugins](./kibana-plugin-server.pluginmanifest.optionalplugins.md) + +## PluginManifest.optionalPlugins property + +An optional list of the other plugins that if installed and enabled \*\*may be\*\* leveraged by this plugin for some additional functionality but otherwise are not required for this plugin to work properly. + +Signature: + +```typescript +readonly optionalPlugins: readonly PluginName[]; +``` diff --git a/docs/development/core/server/kibana-plugin-server.pluginmanifest.requiredplugins.md b/docs/development/core/server/kibana-plugin-server.pluginmanifest.requiredplugins.md new file mode 100644 index 0000000000000..0ea7c872dfa07 --- /dev/null +++ b/docs/development/core/server/kibana-plugin-server.pluginmanifest.requiredplugins.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [PluginManifest](./kibana-plugin-server.pluginmanifest.md) > [requiredPlugins](./kibana-plugin-server.pluginmanifest.requiredplugins.md) + +## PluginManifest.requiredPlugins property + +An optional list of the other plugins that \*\*must be\*\* installed and enabled for this plugin to function properly. + +Signature: + +```typescript +readonly requiredPlugins: readonly PluginName[]; +``` diff --git a/docs/development/core/server/kibana-plugin-server.pluginmanifest.server.md b/docs/development/core/server/kibana-plugin-server.pluginmanifest.server.md new file mode 100644 index 0000000000000..676ad721edf7c --- /dev/null +++ b/docs/development/core/server/kibana-plugin-server.pluginmanifest.server.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [PluginManifest](./kibana-plugin-server.pluginmanifest.md) > [server](./kibana-plugin-server.pluginmanifest.server.md) + +## PluginManifest.server property + +Specifies whether plugin includes some server-side specific functionality. + +Signature: + +```typescript +readonly server: boolean; +``` diff --git a/docs/development/core/server/kibana-plugin-server.pluginmanifest.ui.md b/docs/development/core/server/kibana-plugin-server.pluginmanifest.ui.md new file mode 100644 index 0000000000000..ad5ce2237c580 --- /dev/null +++ b/docs/development/core/server/kibana-plugin-server.pluginmanifest.ui.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [PluginManifest](./kibana-plugin-server.pluginmanifest.md) > [ui](./kibana-plugin-server.pluginmanifest.ui.md) + +## PluginManifest.ui property + +Specifies whether plugin includes some client/browser specific functionality that should be included into client bundle via `public/ui_plugin.js` file. + +Signature: + +```typescript +readonly ui: boolean; +``` diff --git a/docs/development/core/server/kibana-plugin-server.pluginmanifest.version.md b/docs/development/core/server/kibana-plugin-server.pluginmanifest.version.md new file mode 100644 index 0000000000000..75255096408f3 --- /dev/null +++ b/docs/development/core/server/kibana-plugin-server.pluginmanifest.version.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [kibana-plugin-server](./kibana-plugin-server.md) > [PluginManifest](./kibana-plugin-server.pluginmanifest.md) > [version](./kibana-plugin-server.pluginmanifest.version.md) + +## PluginManifest.version property + +Version of the plugin. + +Signature: + +```typescript +readonly version: string; +``` diff --git a/src/core/server/config/config.ts b/src/core/server/config/config.ts index f054817fe9ee6..b1a6a8cc525bf 100644 --- a/src/core/server/config/config.ts +++ b/src/core/server/config/config.ts @@ -17,6 +17,7 @@ * under the License. */ +/** @public */ export type ConfigPath = string | string[]; /** diff --git a/src/core/server/index.ts b/src/core/server/index.ts index 65b986a1d78c5..cc0e0dc51f318 100644 --- a/src/core/server/index.ts +++ b/src/core/server/index.ts @@ -20,6 +20,10 @@ /** * The Kibana Core APIs for server-side plugins. * + * A plugin requires a `kibana.json` file at it's root directory that follows + * {@link PluginManifest | the manfiest schema} to define static plugin + * information required to load the plugin. + * * A plugin's `server/index` file must contain a named import, `plugin`, that * implements {@link PluginInitializer} which returns an object that implements * {@link Plugin}. @@ -46,7 +50,7 @@ import { PluginsServiceSetup, PluginsServiceStart, PluginOpaqueId } from './plug import { ContextSetup } from './context'; export { bootstrap } from './bootstrap'; -export { ConfigService } from './config'; +export { ConfigPath, ConfigService } from './config'; export { CoreId } from './core_context'; export { CallAPIOptions, @@ -101,6 +105,7 @@ export { Plugin, PluginInitializer, PluginInitializerContext, + PluginManifest, PluginName, } from './plugins'; diff --git a/src/core/server/plugins/types.ts b/src/core/server/plugins/types.ts index 1372c60eb860e..4b66c9fb65c18 100644 --- a/src/core/server/plugins/types.ts +++ b/src/core/server/plugins/types.ts @@ -40,7 +40,12 @@ export type PluginOpaqueId = symbol; /** * Describes the set of required and optional properties plugin can define in its * mandatory JSON manifest file. - * @internal + * + * @remarks + * Should never be used in code outside of Core but is exported for + * documentation purposes. + * + * @public */ export interface PluginManifest { /** @@ -59,7 +64,8 @@ export interface PluginManifest { readonly kibanaVersion: string; /** - * Root configuration path used by the plugin, defaults to "id". + * Root {@link ConfigPath | configuration path} used by the plugin, defaults + * to "id". */ readonly configPath: ConfigPath; diff --git a/src/core/server/server.api.md b/src/core/server/server.api.md index dd889ea1995e0..2f2f93b417487 100644 --- a/src/core/server/server.api.md +++ b/src/core/server/server.api.md @@ -74,6 +74,9 @@ export class ClusterClient { close(): void; } +// @public (undocumented) +export type ConfigPath = string | string[]; + // @internal (undocumented) export class ConfigService { // Warning: (ae-forgotten-export) The symbol "Config" needs to be exported by the entry point index.d.ts @@ -88,7 +91,6 @@ export class ConfigService { // (undocumented) isEnabledAtPath(path: ConfigPath): Promise; optionalAtPath(path: ConfigPath): Observable; - // Warning: (ae-forgotten-export) The symbol "ConfigPath" needs to be exported by the entry point index.d.ts setSchema(path: ConfigPath, schema: Type): Promise; } @@ -458,6 +460,18 @@ export interface PluginInitializerContext { opaqueId: PluginOpaqueId; } +// @public +export interface PluginManifest { + readonly configPath: ConfigPath; + readonly id: PluginName; + readonly kibanaVersion: string; + readonly optionalPlugins: readonly PluginName[]; + readonly requiredPlugins: readonly PluginName[]; + readonly server: boolean; + readonly ui: boolean; + readonly version: string; +} + // @public export type PluginName = string; @@ -1017,6 +1031,6 @@ export interface SessionStorageFactory { // // 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/plugins_service.ts:39:5 - (ae-forgotten-export) The symbol "DiscoveredPluginInternal" needs to be exported by the entry point index.d.ts -// src/core/server/plugins/types.ts:156:10 - (ae-forgotten-export) The symbol "EnvironmentMode" needs to be exported by the entry point index.d.ts +// src/core/server/plugins/types.ts:162:10 - (ae-forgotten-export) The symbol "EnvironmentMode" needs to be exported by the entry point index.d.ts ```