From 23072102a2859f33f31304c987b0b50be4b6248e Mon Sep 17 00:00:00 2001
From: Patrik Oldsberg <poldsberg@gmail.com>
Date: Thu, 29 Dec 2022 14:40:01 +0100
Subject: [PATCH] backend-plugin-api: add RootHttpRouterService definition
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Fredrik Adelöw <freben@gmail.com>
Co-authored-by: blam <ben@blam.sh>
Co-authored-by: Johan Haals <johan.haals@gmail.com>
Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>
---
 packages/backend-plugin-api/api-report.md     |  6 ++++
 .../definitions/RootHttpRouterService.ts      | 28 +++++++++++++++++++
 .../src/services/definitions/coreServices.ts  |  9 ++++++
 .../src/services/definitions/index.ts         |  1 +
 4 files changed, 44 insertions(+)
 create mode 100644 packages/backend-plugin-api/src/services/definitions/RootHttpRouterService.ts

diff --git a/packages/backend-plugin-api/api-report.md b/packages/backend-plugin-api/api-report.md
index 9c6ffe6dd5..165f5dc738 100644
--- a/packages/backend-plugin-api/api-report.md
+++ b/packages/backend-plugin-api/api-report.md
@@ -82,6 +82,7 @@ export namespace coreServices {
   const logger: ServiceRef<LoggerService, 'plugin'>;
   const permissions: ServiceRef<PermissionsService, 'plugin'>;
   const pluginMetadata: ServiceRef<PluginMetadataService, 'plugin'>;
+  const rootHttpRouter: ServiceRef<RootHttpRouterService, 'root'>;
   const rootLifecycle: ServiceRef<RootLifecycleService, 'root'>;
   const rootLogger: ServiceRef<RootLoggerService, 'root'>;
   const scheduler: ServiceRef<SchedulerService, 'plugin'>;
@@ -265,6 +266,11 @@ export type ReadUrlResponse = {
   etag?: string;
 };
 
+// @public (undocumented)
+export interface RootHttpRouterService {
+  use(path: string, handler: Handler): void;
+}
+
 // @public (undocumented)
 export interface RootLifecycleService extends LifecycleService {}
 
diff --git a/packages/backend-plugin-api/src/services/definitions/RootHttpRouterService.ts b/packages/backend-plugin-api/src/services/definitions/RootHttpRouterService.ts
new file mode 100644
index 0000000000..e583e978fa
--- /dev/null
+++ b/packages/backend-plugin-api/src/services/definitions/RootHttpRouterService.ts
@@ -0,0 +1,28 @@
+/*
+ * Copyright 2022 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { Handler } from 'express';
+
+/**
+ * @public
+ */
+export interface RootHttpRouterService {
+  /**
+   * Registers a handler at the root of the backend router.
+   * The path is required and may not be empty.
+   */
+  use(path: string, handler: Handler): void;
+}
diff --git a/packages/backend-plugin-api/src/services/definitions/coreServices.ts b/packages/backend-plugin-api/src/services/definitions/coreServices.ts
index fc96ec8be9..7de92d6d01 100644
--- a/packages/backend-plugin-api/src/services/definitions/coreServices.ts
+++ b/packages/backend-plugin-api/src/services/definitions/coreServices.ts
@@ -103,6 +103,15 @@ export namespace coreServices {
     import('./PluginMetadataService').PluginMetadataService
   >({ id: 'core.pluginMetadata' });
 
+  /**
+   * The service reference for the root scoped {@link RootHttpRouterService}.
+   *
+   * @public
+   */
+  export const rootHttpRouter = createServiceRef<
+    import('./RootHttpRouterService').RootHttpRouterService
+  >({ id: 'core.rootHttpRouter', scope: 'root' });
+
   /**
    * The service reference for the root scoped {@link RootLifecycleService}.
    *
diff --git a/packages/backend-plugin-api/src/services/definitions/index.ts b/packages/backend-plugin-api/src/services/definitions/index.ts
index dedfd6223e..82b16efda2 100644
--- a/packages/backend-plugin-api/src/services/definitions/index.ts
+++ b/packages/backend-plugin-api/src/services/definitions/index.ts
@@ -27,6 +27,7 @@ export type {
 export type { LoggerService, LogMeta } from './LoggerService';
 export type { PermissionsService } from './PermissionsService';
 export type { PluginMetadataService } from './PluginMetadataService';
+export type { RootHttpRouterService } from './RootHttpRouterService';
 export type { RootLifecycleService } from './RootLifecycleService';
 export type { RootLoggerService } from './RootLoggerService';
 export type { SchedulerService } from './SchedulerService';