From 0a76425d7a212e7f05968d53ac27c02006470dda Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabrice=20Flore-Th=C3=A9bault?= Date: Mon, 14 Apr 2025 12:31:33 +0200 Subject: [PATCH 1/5] RHIDP-6502 Overriding Core Backend Service Configuration MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Fabrice Flore-Thébault --- .../assembly-configuring-rhdh-plugins.adoc | 2 +- .../con-overriding-core-backend-services.adoc | 101 ----------------- ...proc-overriding-core-backend-services.adoc | 105 ++++++++++++++++++ 3 files changed, 106 insertions(+), 102 deletions(-) delete mode 100644 modules/dynamic-plugins/con-overriding-core-backend-services.adoc create mode 100644 modules/dynamic-plugins/proc-overriding-core-backend-services.adoc diff --git a/assemblies/dynamic-plugins/assembly-configuring-rhdh-plugins.adoc b/assemblies/dynamic-plugins/assembly-configuring-rhdh-plugins.adoc index e4740b72ff..352278bc8a 100644 --- a/assemblies/dynamic-plugins/assembly-configuring-rhdh-plugins.adoc +++ b/assemblies/dynamic-plugins/assembly-configuring-rhdh-plugins.adoc @@ -31,4 +31,4 @@ include::../assembly-using-servicenow.adoc[leveloffset=+1] include::../assembly-using-kubernetes-custom-actions.adoc[leveloffset=+1] // Overriding Core Backend Service Configuration -include::../modules/dynamic-plugins/con-overriding-core-backend-services.adoc[leveloffset=+1] +include::../modules/dynamic-plugins/proc-overriding-core-backend-services.adoc[leveloffset=+1] diff --git a/modules/dynamic-plugins/con-overriding-core-backend-services.adoc b/modules/dynamic-plugins/con-overriding-core-backend-services.adoc deleted file mode 100644 index 233c801d28..0000000000 --- a/modules/dynamic-plugins/con-overriding-core-backend-services.adoc +++ /dev/null @@ -1,101 +0,0 @@ -[id="overriding-core-backend-services_{context}"] -= Overriding Core Backend Service Configuration - -The {product} ({product-very-short}) backend platform consists of a number of core services that are well encapsulated. The {product-very-short} backend installs these default core services statically during initialization. - -You can configure these core services by customizing the backend source code and rebuilding your {product-short} application. Alternatively, you can customize a core service by installing it as a `BackendFeature` by using dynamic plugin functionality. - -To use the dynamic plugin functionality to customize a core service in your RHDH application, you must configure the backend to avoid statically installing a given default core service. - -For example, adding a middleware function to handle all incoming requests can be done by installing a custom `configure` function for the root `HTTP` router backend service which allows access to the underlying Express application. - -.Example of a `BackendFeature` middleware function to handle incoming `HTTP` requests - -[source,javascript] ----- -// Create the BackendFeature -export const customRootHttpServerFactory: BackendFeature = - rootHttpRouterServiceFactory({ - configure: ({ app, routes, middleware, logger }) => { - logger.info( - 'Using custom root HttpRouterServiceFactory configure function', - ); - app.use(middleware.helmet()); - app.use(middleware.cors()); - app.use(middleware.compression()); - app.use(middleware.logging()); - // Add a the custom middleware function before all - // of the route handlers - app.use(addTestHeaderMiddleware({ logger })); - app.use(routes); - app.use(middleware.notFound()); - app.use(middleware.error()); - }, - }); - -// Export the BackendFeature as the default entrypoint -export default customRootHttpServerFactory; ----- - -In the above example, as the `BackendFeature` overrides the default implementation of the HTTP router service, you must set the `ENABLE_CORE_ROOTHTTPROUTER_OVERRIDE` environment variable to `true` so that the {product-short} does not install the default implementation automatically. - -== Overriding environment variables -To allow a dynamic plugin to load a core service override, you must start the {product-short} backend with the corresponding core service ID environment variable set to `true`. - -.Environment variables and core service IDs -[cols="50%,50%", frame="all", options="header"] -|=== -|Variable -|Description - -|`ENABLE_CORE_AUTH_OVERRIDE` -|Override the `core.auth` service - -| `ENABLE_CORE_CACHE_OVERRIDE` -| Override the `core.cache` service - -| `ENABLE_CORE_ROOTCONFIG_OVERRIDE` -| Override the `core.rootConfig` service - -| `ENABLE_CORE_DATABASE_OVERRIDE` -| Override the `core.database` service - -| `ENABLE_CORE_DISCOVERY_OVERRIDE` -| Override the `core.discovery` service - -| `ENABLE_CORE_HTTPAUTH_OVERRIDE` -| Override the `core.httpAuth` service - -| `ENABLE_CORE_HTTPROUTER_OVERRIDE` -| Override the `core.httpRouter` service - -| `ENABLE_CORE_LIFECYCLE_OVERRIDE` -| Override the `core.lifecycle` service - -| `ENABLE_CORE_LOGGER_OVERRIDE` -| Override the `core.logger` service - -| `ENABLE_CORE_PERMISSIONS_OVERRIDE` -| Override the `core.permissions` service - -| `ENABLE_CORE_ROOTHEALTH_OVERRIDE` -| Override the `core.rootHealth` service - -| `ENABLE_CORE_ROOTHTTPROUTER_OVERRIDE` -| Override the `core.rootHttpRouter` service - -| `ENABLE_CORE_ROOTLIFECYCLE_OVERRIDE` -| Override the `core.rootLifecycle` service - -| `ENABLE_CORE_SCHEDULER_OVERRIDE` -| Override the `core.scheduler` service - -| `ENABLE_CORE_USERINFO_OVERRIDE` -| Override the `core.userInfo` service - -| `ENABLE_CORE_URLREADER_OVERRIDE` -| Override the `core.urlReader` service - -| `ENABLE_EVENTS_SERVICE_OVERRIDE` -| Override the `events.service` service -|=== \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-overriding-core-backend-services.adoc b/modules/dynamic-plugins/proc-overriding-core-backend-services.adoc new file mode 100644 index 0000000000..9836a95c9b --- /dev/null +++ b/modules/dynamic-plugins/proc-overriding-core-backend-services.adoc @@ -0,0 +1,105 @@ +[id="overriding-core-backend-services_{context}"] += Overriding Core Backend Service Configuration + +The {product} ({product-very-short}) backend platform consists of a number of core services that are well encapsulated. +The {product-very-short} backend installs these default core services statically during initialization. + +Customize a core service by installing it as a `BackendFeature` by using dynamic plugin functionality. + +.Procedure +. Configure {product-short} to allow a core service override, by setting the corresponding core service ID environment variable set to `true` in the {product-short} `{my-app-config-file}` configuration file. ++ +.Environment variables and core service IDs +[cols="50%,50%",frame="all",options="header"] +|=== +|Variable +|Overrides the related service + +|`ENABLE_CORE_AUTH_OVERRIDE` +|`core.auth` + +| `ENABLE_CORE_CACHE_OVERRIDE` +| `core.cache` + +| `ENABLE_CORE_ROOTCONFIG_OVERRIDE` +| `core.rootConfig` + +| `ENABLE_CORE_DATABASE_OVERRIDE` +| `core.database` + +| `ENABLE_CORE_DISCOVERY_OVERRIDE` +| `core.discovery` + +| `ENABLE_CORE_HTTPAUTH_OVERRIDE` +| `core.httpAuth` + +| `ENABLE_CORE_HTTPROUTER_OVERRIDE` +| `core.httpRouter` + +| `ENABLE_CORE_LIFECYCLE_OVERRIDE` +| `core.lifecycle` + +| `ENABLE_CORE_LOGGER_OVERRIDE` +| `core.logger` + +| `ENABLE_CORE_PERMISSIONS_OVERRIDE` +| `core.permissions` + +| `ENABLE_CORE_ROOTHEALTH_OVERRIDE` +| `core.rootHealth` + +| `ENABLE_CORE_ROOTHTTPROUTER_OVERRIDE` +| `core.rootHttpRouter` + +| `ENABLE_CORE_ROOTLIFECYCLE_OVERRIDE` +| `core.rootLifecycle` + +| `ENABLE_CORE_SCHEDULER_OVERRIDE` +| `core.scheduler` + +| `ENABLE_CORE_USERINFO_OVERRIDE` +| `core.userInfo` + +| `ENABLE_CORE_URLREADER_OVERRIDE` +| `core.urlReader` + +| `ENABLE_EVENTS_SERVICE_OVERRIDE` +| `events.service` +|=== + +. Install your custom core service as a `BackendFeature`. ++ +For example, +adding a middleware function to handle all incoming requests can be done +by installing a custom `configure` function for the root `HTTP` router backend service +which allows access to the underlying Express application. ++ +.Example of a `BackendFeature` middleware function to handle incoming `HTTP` requests +[source,javascript] +---- +// Create the BackendFeature +export const customRootHttpServerFactory: BackendFeature = + rootHttpRouterServiceFactory({ + configure: ({ app, routes, middleware, logger }) => { + logger.info( + 'Using custom root HttpRouterServiceFactory configure function', + ); + app.use(middleware.helmet()); + app.use(middleware.cors()); + app.use(middleware.compression()); + app.use(middleware.logging()); + // Add a the custom middleware function before all + // of the route handlers + app.use(addTestHeaderMiddleware({ logger })); + app.use(routes); + app.use(middleware.notFound()); + app.use(middleware.error()); + }, + }); + +// Export the BackendFeature as the default entrypoint +export default customRootHttpServerFactory; +---- ++ +In the above example, as the `BackendFeature` overrides the default implementation of the HTTP router service, you must set the `ENABLE_CORE_ROOTHTTPROUTER_OVERRIDE` environment variable to `true` so that the {product-short} does not install the default implementation automatically. + From d6826b00fb6eea251fa70a75047a44669c42a713 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabrice=20Flore-Th=C3=A9bault?= Date: Wed, 30 Apr 2025 09:19:19 +0200 Subject: [PATCH 2/5] Update modules/dynamic-plugins/proc-overriding-core-backend-services.adoc Co-authored-by: Priyanka Abel --- .../dynamic-plugins/proc-overriding-core-backend-services.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/dynamic-plugins/proc-overriding-core-backend-services.adoc b/modules/dynamic-plugins/proc-overriding-core-backend-services.adoc index 9836a95c9b..c1dc46de52 100644 --- a/modules/dynamic-plugins/proc-overriding-core-backend-services.adoc +++ b/modules/dynamic-plugins/proc-overriding-core-backend-services.adoc @@ -4,7 +4,7 @@ The {product} ({product-very-short}) backend platform consists of a number of core services that are well encapsulated. The {product-very-short} backend installs these default core services statically during initialization. -Customize a core service by installing it as a `BackendFeature` by using dynamic plugin functionality. +Customize a core service by installing it as a `BackendFeature` by using the dynamic plugin functionality. .Procedure . Configure {product-short} to allow a core service override, by setting the corresponding core service ID environment variable set to `true` in the {product-short} `{my-app-config-file}` configuration file. From 5d5449cf446d325412669b8c62d8ab7900234a45 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabrice=20Flore-Th=C3=A9bault?= Date: Wed, 30 Apr 2025 14:46:19 +0200 Subject: [PATCH 3/5] Update modules/dynamic-plugins/proc-overriding-core-backend-services.adoc Co-authored-by: Lindsey Frazier --- .../proc-overriding-core-backend-services.adoc | 9 ++------- 1 file changed, 2 insertions(+), 7 deletions(-) diff --git a/modules/dynamic-plugins/proc-overriding-core-backend-services.adoc b/modules/dynamic-plugins/proc-overriding-core-backend-services.adoc index c1dc46de52..23ef08bd71 100644 --- a/modules/dynamic-plugins/proc-overriding-core-backend-services.adoc +++ b/modules/dynamic-plugins/proc-overriding-core-backend-services.adoc @@ -67,13 +67,8 @@ Customize a core service by installing it as a `BackendFeature` by using the dyn | `events.service` |=== -. Install your custom core service as a `BackendFeature`. -+ -For example, -adding a middleware function to handle all incoming requests can be done -by installing a custom `configure` function for the root `HTTP` router backend service -which allows access to the underlying Express application. -+ +. Install your custom core service as a `BackendFeature` as shown in the following example: + .Example of a `BackendFeature` middleware function to handle incoming `HTTP` requests [source,javascript] ---- From 4c9bebf98f87f84412fe07d0391cf42607aae8cc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabrice=20Flore-Th=C3=A9bault?= Date: Wed, 30 Apr 2025 14:47:04 +0200 Subject: [PATCH 4/5] Update modules/dynamic-plugins/proc-overriding-core-backend-services.adoc --- .../dynamic-plugins/proc-overriding-core-backend-services.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/dynamic-plugins/proc-overriding-core-backend-services.adoc b/modules/dynamic-plugins/proc-overriding-core-backend-services.adoc index 23ef08bd71..1789b37283 100644 --- a/modules/dynamic-plugins/proc-overriding-core-backend-services.adoc +++ b/modules/dynamic-plugins/proc-overriding-core-backend-services.adoc @@ -96,5 +96,5 @@ export const customRootHttpServerFactory: BackendFeature = export default customRootHttpServerFactory; ---- + -In the above example, as the `BackendFeature` overrides the default implementation of the HTTP router service, you must set the `ENABLE_CORE_ROOTHTTPROUTER_OVERRIDE` environment variable to `true` so that the {product-short} does not install the default implementation automatically. +In the previous example, as the `BackendFeature` overrides the default implementation of the HTTP router service, you must set the `ENABLE_CORE_ROOTHTTPROUTER_OVERRIDE` environment variable to `true` so that the {product-short} does not install the default implementation automatically. From a927a448f2238602c0daad86c65268a5875dd1b1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabrice=20Flore-Th=C3=A9bault?= Date: Wed, 30 Apr 2025 15:01:34 +0200 Subject: [PATCH 5/5] Update modules/dynamic-plugins/proc-overriding-core-backend-services.adoc Co-authored-by: Priyanka Abel --- .../dynamic-plugins/proc-overriding-core-backend-services.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/dynamic-plugins/proc-overriding-core-backend-services.adoc b/modules/dynamic-plugins/proc-overriding-core-backend-services.adoc index 1789b37283..37da22ea01 100644 --- a/modules/dynamic-plugins/proc-overriding-core-backend-services.adoc +++ b/modules/dynamic-plugins/proc-overriding-core-backend-services.adoc @@ -7,7 +7,7 @@ The {product-very-short} backend installs these default core services statically Customize a core service by installing it as a `BackendFeature` by using the dynamic plugin functionality. .Procedure -. Configure {product-short} to allow a core service override, by setting the corresponding core service ID environment variable set to `true` in the {product-short} `{my-app-config-file}` configuration file. +. Configure {product-short} to allow a core service override, by setting the corresponding core service ID environment variable to `true` in the {product-short} `{my-app-config-file}` configuration file. + .Environment variables and core service IDs [cols="50%,50%",frame="all",options="header"]