From e06f658b0cbb89ebc88a90feaa768bb4166df679 Mon Sep 17 00:00:00 2001 From: Christiane Heiligers Date: Thu, 25 Feb 2021 18:40:29 -0700 Subject: [PATCH 1/5] Converts core README from .md to .mdx and adds the heading needed to mount the doc in the new docs system --- src/core/{README.md => README.mdx} | 18 +++++++++++++----- 1 file changed, 13 insertions(+), 5 deletions(-) rename src/core/{README.md => README.mdx} (85%) diff --git a/src/core/README.md b/src/core/README.mdx similarity index 85% rename from src/core/README.md rename to src/core/README.mdx index 799cdb5c799ae..4ba6fd4f45a3b 100644 --- a/src/core/README.md +++ b/src/core/README.mdx @@ -1,3 +1,11 @@ +--- +id: kibServerAndCoreComponents +slug: /kibana-dev-docs/getting-started/kibana-server-and-core-components +title: Kibana server and core components +summary: Core components consist of the main services used by the Kibana server +date: 2021-02-25 +tags: ['kibana','dev', 'contributor', 'api docs'] +--- # Core Core is a set of systems (frontend, backend etc.) that Kibana and its plugins are built on top of. @@ -9,7 +17,7 @@ Core Plugin API Documentation: - [Conventions for Plugins](./CONVENTIONS.md) - [Testing Kibana Plugins](./TESTING.md) - [Kibana Platform Plugin API](./docs/developer/architecture/kibana-platform-plugin-api.asciidoc ) - + Internal Documentation: - [Saved Objects Migrations](./server/saved_objects/migrations/README.md) @@ -18,18 +26,18 @@ Internal Documentation: Most of the existing core functionality is still spread over "legacy" Kibana and it will take some time to upgrade it. Kibana is started using existing "legacy" CLI that bootstraps `core` which in turn creates the "legacy" Kibana server. At the moment `core` manages HTTP connections, handles TLS configuration and base path proxy. All requests to Kibana server -will hit HTTP server exposed by the `core` first and it will decide whether request can be solely handled by the new +will hit HTTP server exposed by the `core` first and it will decide whether request can be solely handled by the new platform or request should be proxied to the "legacy" Kibana. This setup allows `core` to gradually introduce any "pre-route" processing logic, expose new routes or replace old ones handled by the "legacy" Kibana currently. -Once config has been loaded and some of its parts were validated by the `core` it's passed to the "legacy" Kibana where +Once config has been loaded and some of its parts were validated by the `core` it's passed to the "legacy" Kibana where it will be additionally validated so that we can make config validation stricter with the new config validation system. -Even though the new validation system provided by the `core` is also based on Joi internally it is complemented with custom +Even though the new validation system provided by the `core` is also based on Joi internally it is complemented with custom rules tailored to our needs (e.g. `byteSize`, `duration` etc.). That means that config values that were previously accepted by the "legacy" Kibana may be rejected by the `core` now. ### Logging -`core` has its own [logging system](./server/logging/README.mdx) and will output log records directly (e.g. to file or terminal) when configured. When no +`core` has its own [logging system](./server/logging/README.mdx) and will output log records directly (e.g. to file or terminal) when configured. When no specific configuration is provided, logs are forwarded to the "legacy" Kibana so that they look the same as the rest of the log records throughout Kibana. From 6af9125a96062b5fe3a4586a3927ce06a88c8eac Mon Sep 17 00:00:00 2001 From: Christiane Heiligers Date: Fri, 26 Feb 2021 10:24:33 -0700 Subject: [PATCH 2/5] Adds new section for core intro, converts core-conventions to .mdx --- dev_docs/kibana_platform_plugin_intro.mdx | 4 +-- dev_docs/kibana_server_core_components.mdx | 30 +++++++++++++++++++ src/core/CONVENTIONS.md | 8 ++--- ...RE_CONVENTIONS.md => CORE_CONVENTIONS.mdx} | 25 +++++++++++----- src/core/{README.mdx => README.md} | 8 ----- 5 files changed, 53 insertions(+), 22 deletions(-) create mode 100644 dev_docs/kibana_server_core_components.mdx rename src/core/{CORE_CONVENTIONS.md => CORE_CONVENTIONS.mdx} (93%) rename src/core/{README.mdx => README.md} (91%) diff --git a/dev_docs/kibana_platform_plugin_intro.mdx b/dev_docs/kibana_platform_plugin_intro.mdx index bf009a3c5251d..f70c42cb520cc 100644 --- a/dev_docs/kibana_platform_plugin_intro.mdx +++ b/dev_docs/kibana_platform_plugin_intro.mdx @@ -68,7 +68,7 @@ We will continue to focus on adding clarity around these types of services and w ### Core services -Sometimes referred to just as Core, Core services provide the most basic and fundamental tools neccessary for building a plugin, like creating saved objects, +Sometimes referred to just as provide the most basic and fundamental tools neccessary for building a plugin, like creating saved objects, routing, application registration, notifications and . The Core platform is not a plugin itself, although there are some plugins that provide platform functionality. We call these . @@ -141,4 +141,4 @@ plugins to customize the Kibana experience. Examples of extension points are: ## Follow up material -Learn how to build your own plugin by following +Learn how to build your own plugin by following . diff --git a/dev_docs/kibana_server_core_components.mdx b/dev_docs/kibana_server_core_components.mdx new file mode 100644 index 0000000000000..d51dfeb93c5d0 --- /dev/null +++ b/dev_docs/kibana_server_core_components.mdx @@ -0,0 +1,30 @@ +--- +id: kibServerAndCoreComponents +slug: /kibana-dev-docs/core-intro +title: Kibana server and core components +summary: An introduction to the Kibana server and core components. +date: 2021-02-26 +tags: ['kibana','onboarding', 'dev', 'architecture'] +--- + +Core is a set of systems (frontend, backend etc.) that Kibana and its plugins are built on top of. + +## Integration with the "legacy" Kibana + +Most of the existing core functionality is still spread over "legacy" Kibana and it will take some time to upgrade it. +Kibana is started using existing "legacy" CLI that bootstraps `core` which in turn creates the "legacy" Kibana server. +At the moment `core` manages HTTP connections, handles TLS configuration and base path proxy. All requests to Kibana server +will hit HTTP server exposed by the `core` first and it will decide whether request can be solely handled by the new +platform or request should be proxied to the "legacy" Kibana. This setup allows `core` to gradually introduce any "pre-route" +processing logic, expose new routes or replace old ones handled by the "legacy" Kibana currently. + +Once config has been loaded and some of its parts were validated by the `core` it's passed to the "legacy" Kibana where +it will be additionally validated so that we can make config validation stricter with the new config validation system. +Even though the new validation system provided by the `core` is also based on Joi internally it is complemented with custom +rules tailored to our needs (e.g. `byteSize`, `duration` etc.). That means that config values that were previously accepted +by the "legacy" Kibana may be rejected by the `core` now. + +### Logging +`core` has its own and will output log records directly (e.g. to file or terminal) when configured. When no specific configuration is provided, logs are forwarded to the "legacy" Kibana so that they look the same as the rest of the +log records throughout Kibana. + diff --git a/src/core/CONVENTIONS.md b/src/core/CONVENTIONS.md index 56da185d023a9..05782b3fe5594 100644 --- a/src/core/CONVENTIONS.md +++ b/src/core/CONVENTIONS.md @@ -202,14 +202,14 @@ export class MyPlugin implements Plugin { } ``` -Prefer the pattern shown above, using `core.getStartServices()`, rather than store local references retrieved from `start`. +Prefer the pattern shown above, using `core.getStartServices()`, rather than store local references retrieved from `start`. **Bad:** ```ts export class MyPlugin implements Plugin { // Anti pattern private coreStart?: CoreStart; - private depsStart?: DepsStart; + private depsStart?: DepsStart; public setup(core) { core.application.register({ @@ -220,7 +220,7 @@ export class MyPlugin implements Plugin { return renderApp(this.coreStart, this.depsStart, params); } }); - } + } public start(core, deps) { // Anti pattern @@ -361,5 +361,5 @@ Migration example from the legacy format is available in `src/core/MIGRATION_EXA ### Naming conventions -Export start and setup contracts as `MyPluginStart` and `MyPluginSetup`. +Export start and setup contracts as `MyPluginStart` and `MyPluginSetup`. This avoids naming clashes, if everyone exported them simply as `Start` and `Setup`. diff --git a/src/core/CORE_CONVENTIONS.md b/src/core/CORE_CONVENTIONS.mdx similarity index 93% rename from src/core/CORE_CONVENTIONS.md rename to src/core/CORE_CONVENTIONS.mdx index 76f3be1595258..047c27961e323 100644 --- a/src/core/CORE_CONVENTIONS.md +++ b/src/core/CORE_CONVENTIONS.mdx @@ -1,3 +1,12 @@ +--- +id: kibCoreConventions +slug: /kibana-dev-docs/core-conventions +title: Kibana core conventions +summary: Conventions to follow for developing in core services +date: 2021-02-26 +tags: ['kibana','onboarding', 'dev', 'architecture'] +--- + - [Core Conventions](#core-conventions) - [1. Exposing API Types](#1-exposing-api-types) - [2. API Structure and nesting](#2-api-structure-and-nesting) @@ -15,7 +24,7 @@ area of Core API's and does not apply to internal types. - 1.1 All API types must be exported from the top-level `server` or `public` directories. - + ```ts // -- good -- import { IRouter } from 'src/core/server'; @@ -23,15 +32,15 @@ area of Core API's and does not apply to internal types. // -- bad -- import { IRouter } from 'src/core/server/http/router.ts'; ``` - + > Why? This is required for generating documentation from our inline > typescript doc comments, makes it easier for API consumers to find the > relevant types and creates a clear distinction between external and > internal types. - + - 1.2 Classes must not be exposed directly. Instead, use a separate type, prefixed with an 'I', to describe the public contract of the class. - + ```ts // -- good (alternative 1) -- /** @@ -66,14 +75,14 @@ area of Core API's and does not apply to internal types. ``` > Why? Classes' private members form part of their type signature making it - > impossible to mock a dependency typed as a `class`. + > impossible to mock a dependency typed as a `class`. > > Until we can use ES private field support in Typescript 3.8 > https://github.com/elastic/kibana/issues/54906 we have two alternatives > each with their own pro's and cons: > > #### Using a derived class (alternative 1) - > + > > Pro's: > - TSDoc comments are located with the source code > - The class acts as a single source of type information @@ -81,12 +90,12 @@ area of Core API's and does not apply to internal types. > Con's: > - "Go to definition" first takes you to where the type gets derived > requiring a second "Go to definition" to navigate to the type source. - > + > > #### Using a separate interface (alternative 2) > Pro's: > - Creates an explicit external API contract > - "Go to definition" will take you directly to the type definition. - > + > > Con's: > - TSDoc comments are located with the interface not next to the > implementation source code. diff --git a/src/core/README.mdx b/src/core/README.md similarity index 91% rename from src/core/README.mdx rename to src/core/README.md index 4ba6fd4f45a3b..4dd045f37b483 100644 --- a/src/core/README.mdx +++ b/src/core/README.md @@ -1,11 +1,3 @@ ---- -id: kibServerAndCoreComponents -slug: /kibana-dev-docs/getting-started/kibana-server-and-core-components -title: Kibana server and core components -summary: Core components consist of the main services used by the Kibana server -date: 2021-02-25 -tags: ['kibana','dev', 'contributor', 'api docs'] ---- # Core Core is a set of systems (frontend, backend etc.) that Kibana and its plugins are built on top of. From 726213c6d77b0163f7845f2d213c68bf2edbdc42 Mon Sep 17 00:00:00 2001 From: Christiane Heiligers Date: Fri, 26 Feb 2021 10:27:36 -0700 Subject: [PATCH 3/5] Reverts converting core-conventions from .md to .mdx --- src/core/{CORE_CONVENTIONS.mdx => CORE_CONVENTIONS.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename src/core/{CORE_CONVENTIONS.mdx => CORE_CONVENTIONS.md} (100%) diff --git a/src/core/CORE_CONVENTIONS.mdx b/src/core/CORE_CONVENTIONS.md similarity index 100% rename from src/core/CORE_CONVENTIONS.mdx rename to src/core/CORE_CONVENTIONS.md From 99bf86ec6c648628049eea9e986742ef745f983a Mon Sep 17 00:00:00 2001 From: Christiane Heiligers Date: Fri, 26 Feb 2021 10:28:55 -0700 Subject: [PATCH 4/5] Deletes header --- src/core/CORE_CONVENTIONS.md | 9 --------- 1 file changed, 9 deletions(-) diff --git a/src/core/CORE_CONVENTIONS.md b/src/core/CORE_CONVENTIONS.md index 047c27961e323..1cd997d570b6a 100644 --- a/src/core/CORE_CONVENTIONS.md +++ b/src/core/CORE_CONVENTIONS.md @@ -1,12 +1,3 @@ ---- -id: kibCoreConventions -slug: /kibana-dev-docs/core-conventions -title: Kibana core conventions -summary: Conventions to follow for developing in core services -date: 2021-02-26 -tags: ['kibana','onboarding', 'dev', 'architecture'] ---- - - [Core Conventions](#core-conventions) - [1. Exposing API Types](#1-exposing-api-types) - [2. API Structure and nesting](#2-api-structure-and-nesting) From 6ab5c78d2822e2e9bf2b7f5ef845a0da1125b2f3 Mon Sep 17 00:00:00 2001 From: Christiane Heiligers Date: Fri, 26 Feb 2021 10:48:29 -0700 Subject: [PATCH 5/5] Renames doc title --- dev_docs/kibana_server_core_components.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dev_docs/kibana_server_core_components.mdx b/dev_docs/kibana_server_core_components.mdx index d51dfeb93c5d0..701043059be02 100644 --- a/dev_docs/kibana_server_core_components.mdx +++ b/dev_docs/kibana_server_core_components.mdx @@ -1,7 +1,7 @@ --- id: kibServerAndCoreComponents slug: /kibana-dev-docs/core-intro -title: Kibana server and core components +title: Core components summary: An introduction to the Kibana server and core components. date: 2021-02-26 tags: ['kibana','onboarding', 'dev', 'architecture']