backend-plugin-api: add RootHttpRouterService definition

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

@@ -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 {}
 

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;
+}

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}.
    *

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';