From 85106586796938ef2e7d660616ae3db9f229d933 Mon Sep 17 00:00:00 2001 From: Alec Jacobs Date: Tue, 16 Apr 2024 16:20:45 -0700 Subject: [PATCH] docs(root-http-router): update docs for server configuration Signed-off-by: Alec Jacobs --- .../core-services/root-http-router.md | 25 ++++++++++++++++++- 1 file changed, 24 insertions(+), 1 deletion(-) diff --git a/docs/backend-system/core-services/root-http-router.md b/docs/backend-system/core-services/root-http-router.md index 97666cae9d..b3522e1752 100644 --- a/docs/backend-system/core-services/root-http-router.md +++ b/docs/backend-system/core-services/root-http-router.md @@ -5,7 +5,7 @@ sidebar_label: Root Http Router description: Documentation for the Root Http Router service --- -The root HTTP router is a service that allows you to register routes on the root of the backend service. This is useful for things like health checks, or other routes that you want to expose on the root of the backend service. It is used as the base router that backs the `httpRouter` service. Most likely you won't need to use this service directly, but rather use the `httpRouter` service. +The root HTTP router is a service that allows you to register routes on the root of the backend service. This is useful for things like health checks, or other routes that you want to expose on the root of the backend service. It is used as the base router that backs the `httpRouter` service and starts the Node.js HTTP server on backend startup. Most likely you won't need to use this service directly, but rather use the `httpRouter` service. The `/api/:pluginId/` path prefix is reserved for use by plugins to register their own routes via the [HttpRouter](./http-router.md) service. @@ -78,3 +78,26 @@ backend.add( ``` Note that requests towards `/api/*` will never be handled by the `routes` handler unless a matching plugin exists, and will instead typically falling through to the `middleware.notFound()` handler. That is the case regardless of whether there is a configured `indexPath` or not. + +The root HTTP Router service also allows for configuration of the underlying Node.js HTTP server object. This is useful for modifying settings on the HTTP server itself, such as server [timeout](https://nodejs.org/api/http.html#servertimeout), [keepAliveTimeout](https://nodejs.org/api/http.html#serverkeepalivetimeout), and [headersTimeout](https://nodejs.org/api/http.html#serverheaderstimeout). + +A `applyDefaults` helper is also made available to use the default app/router configuration while still enabling custom server configuration + +```ts +import { rootHttpRouterServiceFactory } from '@backstage/backend-app-api'; + +const backend = createBackend(); + +backend.add( + rootHttpRouterServiceFactory({ + configure: ({ server, applyDefaults }) => { + // apply default app/router configuration + applyDefaults(); + + // customize the Node.js HTTP Server timeouts + server.keepAliveTimeout = 65 * 1000; + server.headersTimeout = 66 * 1000; + }, + }), +); +```