From 1a83f71b5b29f51e5e6e4cfe03c805e326aae576 Mon Sep 17 00:00:00 2001 From: Daniel Widdis Date: Tue, 15 Nov 2022 18:27:51 -0800 Subject: [PATCH] Add sequence diagram to DESIGN.md Signed-off-by: Daniel Widdis --- DESIGN.md | 32 +++++++++++++++++++++++++++++--- Docs/NamedXContent.svg | 1 + 2 files changed, 30 insertions(+), 3 deletions(-) create mode 100644 Docs/NamedXContent.svg diff --git a/DESIGN.md b/DESIGN.md index 34cddf258..14599b91d 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -74,10 +74,10 @@ The sequence diagram below shows the process of initializing an Extension, regis The `org.opensearch.sdk.sample` package contains a sample `HelloWorldExtension` implementing the below steps. It is executed following the steps in the [`DEVELOPER_GUIDE`](DEVELOPER_GUIDE.md). -![](Docs/ExtensionRestActions.svg) - #### Extension REST Actions Walk Through +![](Docs/ExtensionRestActions.svg) + ##### Extension Startup (1) Extensions must implement the `Extension` interface which requires them to define their settings (name, host address and port) and a list of `ExtensionRestHandler` implementations they will handle. They are started up using a `main()` method which passes an instance of the extension to the `ExtensionsRunner` using `ExtensionsRunner.run(this)`. @@ -116,9 +116,35 @@ The `ExtensionsOrchestrator` reads a list of extensions present in `extensions.y (27) The User receives the response. +#### Extension Point Implementation Walk Through + +An example of a more complex extension point, `getNamedXConten()` is shown below. A similar pattern can be followed for most extension points. + +![](Docs/NamedXContent.svg) + +##### Extension Startup + +(1, 2) Extensions initialize by passing an instance of themselves to the `ExtensionsRunner`. The first step in the constructor is for the `ExtensionsRunner` to pass its own instance back to the Extension via setter. + +(3, 4) The `Extension` interface includes extensions points such as `getNamedXContent()` (returning a default empty list). If overridden, the Extension will return a list of `NamedXContentRegistry.Entry` which will be saved as `customNamedXContent`. Other extension points operate in a similar manner. + +(5) The `ExtensionsRunner` registers an `ExtensionInitRequestHandler` which will complete the initialization process on OpenSearch startup. + +##### OpenSearch Startup, Extension Initialization, and NamedXContent Registration + +(6) Upon receipt of an `InitializeExtensionsRequest` (among other actions): + +(7, 8) Obtains Environment Settings from OpenSearch, necessary for some core XContent. + +(9, 10) Instantiates a new `ExtensionNamedXContentRegistry` which is set on the ExtensionsRunner. +This uses the OpenSearch environment settings along with NamedXContent from several OpenSearch modules, +and combines it the custom Extension NamedXContent. + +Since the Extension has an instance of the ExtensionsRunner, it can now access the registry via getter and pass it to Extension Rest Handlers as needed. + ## FAQ - Will extensions replace plugins? - Plugins will continue to be supported and extensions are preferred as they will be easier to develop, deploy, and operate. + Plugins will continue to be supported in the near term but are on a path to deprecation. New development should consider using extensions, as they will be easier to develop, deploy, and operate. - How is the latency going to be for extensions? https://github.com/opensearch-project/OpenSearch/issues/3012#issuecomment-1122682444 diff --git a/Docs/NamedXContent.svg b/Docs/NamedXContent.svg new file mode 100644 index 000000000..0395c7fc1 --- /dev/null +++ b/Docs/NamedXContent.svg @@ -0,0 +1 @@ +title%20NamedXContent%20Registration%0A%0Aentryspacing%200.6%0Aparticipantgroup%20%23lightgreen%20**Extension%20Node**%0Aparticipant%20Extension%0Aparticipant%20ExtensionsRunner%0Aparticipant%20ExtensionNamedXContentRegistry%0Aend%0A%0Aparticipantgroup%20%23lightblue%20**OpenSearch%20Node**%0Aparticipant%20ExtensionsOrchestrator%0Aend%0Aautonumber%201%0AExtension-%3EExtensionsRunner%3Arun(this)%0AExtension%3C-ExtensionsRunner%3AsetExtensionsRunner(this)%0AExtension%3C-ExtensionsRunner%3AgetNamedXContent()%0AExtension-%3EExtensionsRunner%3AcustomNamedXContent%0AExtensionsRunner%3C-ExtensionsRunner%3Aregister%20ExtensionsInitRequestHandler%0A%0AExtensionsRunner%3C-ExtensionsOrchestrator%3AInitializeExtensionsRequest%0Anote%20over%20ExtensionsRunner%2CExtensionNamedXContentRegistry%3A**ExtensionsInitRequestHandler**%5CnUse%20customNamedXContent%20and%5CnOpenSearch%20Environment%20Settings%5Cnto%20create%20a%20combined%20registry%0AExtensionsRunner-%3EExtensionsOrchestrator%3AsendEnvironmentSettingsRequest()%0AExtensionsRunner%3C-ExtensionsOrchestrator%3AEnvironmentSettingsResponse%0AExtensionsRunner-%3E*ExtensionNamedXContentRegistry%3Anew%0AExtensionsRunner%3C-ExtensionNamedXContentRegistry%3AsetNamedXContentRegistry()%0Adestroysilent%20ExtensionNamedXContentRegistry%0Anote%20over%20Extension%2CExtensionsRunner%3AExtension%20can%20now%20access%5CnNamedXContentRegistry%0A%0ANamedXContent RegistrationExtension NodeOpenSearch NodeExtensionExtensionsRunnerExtensionsOrchestratorrun(this)1 setExtensionsRunner(this)2 getNamedXContent()3 customNamedXContent4 register ExtensionsInitRequestHandler5 InitializeExtensionsRequest6 ExtensionsInitRequestHandlerUse customNamedXContent andOpenSearch Environment Settingsto create a combined registrysendEnvironmentSettingsRequest()7 EnvironmentSettingsResponse8 ExtensionNamedXContentRegistrynew9 setNamedXContentRegistry()10 Extension can now accessNamedXContentRegistry