@backstage/backend-plugin-api 0.0.0-nightly-20230103022231 → 0.0.0-nightly-20230104022659

package/CHANGELOG.md

@@ -1,14 +1,31 @@
 # @backstage/backend-plugin-api
 
-## 0.0.0-nightly-20230103022231
+## 0.0.0-nightly-20230104022659
 
 ### Patch Changes
 
+- 6cfd4d7073: Added `RootLifecycleService` and `rootLifecycleServiceRef`, as well as added a `labels` option to the existing `LifecycleServiceShutdownHook`.
+- 5e2cebe9a3: Migrate `UrlReader` into this package to gradually remove the dependency on backend-common.
+- 6f02d23b01: Moved `PluginEndpointDiscovery` type from backend-common to backend-plugin-api.
+- 16054afdec: Documented `coreServices` an all of its members.
 - Updated dependencies
-  - @backstage/config@0.0.0-nightly-20230103022231
-  - @backstage/backend-common@0.0.0-nightly-20230103022231
-  - @backstage/backend-tasks@0.0.0-nightly-20230103022231
-  - @backstage/plugin-permission-common@0.0.0-nightly-20230103022231
+  - @backstage/backend-common@0.0.0-nightly-20230104022659
+  - @backstage/config@0.0.0-nightly-20230104022659
+  - @backstage/backend-tasks@0.0.0-nightly-20230104022659
+  - @backstage/plugin-permission-common@0.0.0-nightly-20230104022659
+
+## 0.2.1-next.0
+
+### Patch Changes
+
+- 6cfd4d7073: Added `RootLifecycleService` and `rootLifecycleServiceRef`, as well as added a `labels` option to the existing `LifecycleServiceShutdownHook`.
+- 5e2cebe9a3: Migrate `UrlReader` into this package to gradually remove the dependency on backend-common.
+- 6f02d23b01: Moved `PluginEndpointDiscovery` type from backend-common to backend-plugin-api.
+- Updated dependencies
+  - @backstage/backend-common@0.18.0-next.0
+  - @backstage/config@1.0.6-next.0
+  - @backstage/backend-tasks@0.4.1-next.0
+  - @backstage/plugin-permission-common@0.7.3-next.0
 
 ## 0.2.0
 

package/alpha/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backstage/backend-plugin-api",
-  "version": "0.0.0-nightly-20230103022231",
+  "version": "0.0.0-nightly-20230104022659",
   "main": "../dist/index.cjs.js",
   "types": "../dist/index.alpha.d.ts"
 }

package/dist/index.alpha.d.ts

@@ -4,18 +4,18 @@
  * @packageDocumentation
  */
 
+/// <reference types="node" />
+
 import { Config } from '@backstage/config';
 import { Handler } from 'express';
 import { Logger } from 'winston';
-import { PermissionAuthorizer } from '@backstage/plugin-permission-common';
 import { PermissionEvaluator } from '@backstage/plugin-permission-common';
 import { PluginCacheManager } from '@backstage/backend-common';
 import { PluginDatabaseManager } from '@backstage/backend-common';
-import { PluginEndpointDiscovery } from '@backstage/backend-common';
 import { PluginTaskScheduler } from '@backstage/backend-tasks';
+import { Readable } from 'stream';
 import { TokenManager } from '@backstage/backend-common';
 import { TransportStreamOptions } from 'winston-transport';
-import { UrlReader } from '@backstage/backend-common';
 
 /** @public */
 export declare interface BackendFeature {
@@ -50,41 +50,106 @@ export declare interface BackendRegistrationPoints {
 }
 
 /** @public */
-export declare type CacheService = PluginCacheManager;
-
-/**
- * @public
- */
-declare const cacheServiceRef: ServiceRef<PluginCacheManager, "plugin">;
+export declare interface CacheService extends PluginCacheManager {
+}
 
 /**
  * @public
  */
-export declare type ConfigService = Config;
+export declare interface ConfigService extends Config {
+}
 
 /**
+ * All core services references
+ *
  * @public
  */
-declare const configServiceRef: ServiceRef<Config, "root">;
-
-declare namespace coreServices {
-    export {
-        configServiceRef as config,
-        httpRouterServiceRef as httpRouter,
-        loggerServiceRef as logger,
-        urlReaderServiceRef as urlReader,
-        cacheServiceRef as cache,
-        databaseServiceRef as database,
-        discoveryServiceRef as discovery,
-        tokenManagerServiceRef as tokenManager,
-        permissionsServiceRef as permissions,
-        schedulerServiceRef as scheduler,
-        rootLoggerServiceRef as rootLogger,
-        pluginMetadataServiceRef as pluginMetadata,
-        lifecycleServiceRef as lifecycle
-    }
+export declare namespace coreServices {
+    /**
+     * The service reference for the plugin scoped {@link CacheService}.
+     *
+     * @public
+     */
+    const cache: ServiceRef<CacheService, "plugin">;
+    /**
+     * The service reference for the root scoped {@link ConfigService}.
+     *
+     * @public
+     */
+    const config: ServiceRef<ConfigService, "root">;
+    /**
+     * The service reference for the plugin scoped {@link DatabaseService}.
+     *
+     * @public
+     */
+    const database: ServiceRef<DatabaseService, "plugin">;
+    /**
+     * The service reference for the plugin scoped {@link DiscoveryService}.
+     *
+     * @public
+     */
+    const discovery: ServiceRef<DiscoveryService, "plugin">;
+    /**
+     * The service reference for the plugin scoped {@link HttpRouterService}.
+     *
+     * @public
+     */
+    const httpRouter: ServiceRef<HttpRouterService, "plugin">;
+    /**
+     * The service reference for the plugin scoped {@link LifecycleService}.
+     *
+     * @public
+     */
+    const lifecycle: ServiceRef<LifecycleService, "plugin">;
+    /**
+     * The service reference for the plugin scoped {@link LoggerService}.
+     *
+     * @public
+     */
+    const logger: ServiceRef<LoggerService, "plugin">;
+    /**
+     * The service reference for the plugin scoped {@link PermissionsService}.
+     *
+     * @public
+     */
+    const permissions: ServiceRef<PermissionsService, "plugin">;
+    /**
+     * The service reference for the plugin scoped {@link PluginMetadataService}.
+     *
+     * @public
+     */
+    const pluginMetadata: ServiceRef<PluginMetadataService, "plugin">;
+    /**
+     * The service reference for the root scoped {@link RootLifecycleService}.
+     *
+     * @public
+     */
+    const rootLifecycle: ServiceRef<RootLifecycleService, "root">;
+    /**
+     * The service reference for the root scoped {@link RootLoggerService}.
+     *
+     * @public
+     */
+    const rootLogger: ServiceRef<RootLoggerService, "root">;
+    /**
+     * The service reference for the plugin scoped {@link SchedulerService}.
+     *
+     * @public
+     */
+    const scheduler: ServiceRef<SchedulerService, "plugin">;
+    /**
+     * The service reference for the plugin scoped {@link TokenManagerService}.
+     *
+     * @public
+     */
+    const tokenManager: ServiceRef<TokenManagerService, "plugin">;
+    /**
+     * The service reference for the plugin scoped {@link UrlReaderService}.
+     *
+     * @public
+     */
+    const urlReader: ServiceRef<UrlReaderService, "plugin">;
 }
-export { coreServices }
 
 /**
  * @public
@@ -137,20 +202,55 @@ export declare function createServiceRef<T>(options: {
 }): ServiceRef<T, 'root'>;
 
 /** @public */
-export declare type DatabaseService = PluginDatabaseManager;
-
-/**
- * @public
- */
-declare const databaseServiceRef: ServiceRef<PluginDatabaseManager, "plugin">;
-
-/** @public */
-export declare type DiscoveryService = PluginEndpointDiscovery;
+export declare interface DatabaseService extends PluginDatabaseManager {
+}
 
 /**
+ * The DiscoveryService is used to provide a mechanism for backend
+ * plugins to discover the endpoints for itself or other backend plugins.
+ *
+ * The purpose of the discovery API is to allow for many different deployment
+ * setups and routing methods through a central configuration, instead
+ * of letting each individual plugin manage that configuration.
+ *
+ * Implementations of the discovery API can be as simple as a URL pattern
+ * using the pluginId, but could also have overrides for individual plugins,
+ * or query a separate discovery service.
+ *
  * @public
  */
-declare const discoveryServiceRef: ServiceRef<PluginEndpointDiscovery, "plugin">;
+export declare interface DiscoveryService {
+    /**
+     * Returns the internal HTTP base URL for a given plugin, without a trailing slash.
+     *
+     * The returned URL should point to an internal endpoint for the plugin, with
+     * the shortest route possible. The URL should be used for service-to-service
+     * communication within a Backstage backend deployment.
+     *
+     * This method must always be called just before making a request, as opposed to
+     * fetching the URL when constructing an API client. That is to ensure that more
+     * flexible routing patterns can be supported.
+     *
+     * For example, asking for the URL for `catalog` may return something
+     * like `http://10.1.2.3/api/catalog`
+     */
+    getBaseUrl(pluginId: string): Promise<string>;
+    /**
+     * Returns the external HTTP base backend URL for a given plugin, without a trailing slash.
+     *
+     * The returned URL should point to an external endpoint for the plugin, such that
+     * it is reachable from the Backstage frontend and other external services. The returned
+     * URL should be usable for example as a callback / webhook URL.
+     *
+     * The returned URL should be stable and in general not change unless other static
+     * or external configuration is changed. Changes should not come as a surprise
+     * to an operator of the Backstage backend.
+     *
+     * For example, asking for the URL for `catalog` may return something
+     * like `https://backstage.example.com/api/catalog`
+     */
+    getExternalBaseUrl(pluginId: string): Promise<string>;
+}
 
 /**
  * TODO
@@ -175,11 +275,6 @@ export declare interface HttpRouterService {
     use(handler: Handler): void;
 }
 
-/**
- * @public
- */
-declare const httpRouterServiceRef: ServiceRef<HttpRouterService, "plugin">;
-
 /**
  * @public
  **/
@@ -190,19 +285,18 @@ export declare interface LifecycleService {
     addShutdownHook(options: LifecycleServiceShutdownHook): void;
 }
 
-/**
- * @public
- */
-declare const lifecycleServiceRef: ServiceRef<LifecycleService, "plugin">;
-
 /**
  * @public
  **/
 export declare type LifecycleServiceShutdownHook = {
     fn: () => void | Promise<void>;
+    /** Labels to help identify the shutdown hook */
+    labels?: Record<string, string>;
 };
 
 /**
+ * A service that provides a logging facility.
+ *
  * @public
  */
 export declare interface LoggerService {
@@ -213,11 +307,6 @@ export declare interface LoggerService {
     child(meta: LogMeta): LoggerService;
 }
 
-/**
- * @public
- */
-declare const loggerServiceRef: ServiceRef<LoggerService, "plugin">;
-
 /** @public */
 export declare function loggerToWinstonLogger(logger: LoggerService, opts?: TransportStreamOptions): Logger;
 
@@ -229,40 +318,260 @@ export declare type LogMeta = {
 };
 
 /** @public */
-export declare type PermissionsService = PermissionEvaluator | PermissionAuthorizer;
+export declare interface PermissionsService extends PermissionEvaluator {
+}
 
 /**
  * @public
  */
-declare const permissionsServiceRef: ServiceRef<PermissionsService, "plugin">;
+export declare interface PluginMetadataService {
+    getId(): string;
+}
 
 /**
+ * An options object for {@link UrlReaderService.readTree} operations.
+ *
  * @public
  */
-export declare interface PluginMetadataService {
-    getId(): string;
-}
+export declare type ReadTreeOptions = {
+    /**
+     * A filter that can be used to select which files should be included.
+     *
+     * @remarks
+     *
+     * The path passed to the filter function is the relative path from the URL
+     * that the file tree is fetched from, without any leading '/'.
+     *
+     * For example, given the URL https://github.com/my/repo/tree/master/my-dir, a file
+     * at https://github.com/my/repo/blob/master/my-dir/my-subdir/my-file.txt will
+     * be represented as my-subdir/my-file.txt
+     *
+     * If no filter is provided, all files are extracted.
+     */
+    filter?(path: string, info?: {
+        size: number;
+    }): boolean;
+    /**
+     * An ETag which can be provided to check whether a
+     * {@link UrlReaderService.readTree} response has changed from a previous execution.
+     *
+     * @remarks
+     *
+     * In the {@link UrlReaderService.readTree} response, an ETag is returned along with
+     * the tree blob. The ETag is a unique identifier of the tree blob, usually
+     * the commit SHA or ETag from the target.
+     *
+     * When an ETag is given as a request option, {@link UrlReaderService.readTree} will
+     * first compare the ETag against the ETag on the target branch. If they
+     * match, {@link UrlReaderService.readTree} will throw a
+     * {@link @backstage/errors#NotModifiedError} indicating that the response
+     * will not differ from the previous response which included this particular
+     * ETag. If they do not match, {@link UrlReaderService.readTree} will return the
+     * rest of the response along with a new ETag.
+     */
+    etag?: string;
+    /**
+     * An abort signal to pass down to the underlying request.
+     *
+     * @remarks
+     *
+     * Not all reader implementations may take this field into account.
+     */
+    signal?: AbortSignal;
+};
 
 /**
+ * A response object for {@link UrlReaderService.readTree} operations.
+ *
  * @public
  */
-declare const pluginMetadataServiceRef: ServiceRef<PluginMetadataService, "plugin">;
+export declare type ReadTreeResponse = {
+    /**
+     * Returns an array of all the files inside the tree, and corresponding
+     * functions to read their content.
+     */
+    files(): Promise<ReadTreeResponseFile[]>;
+    /**
+     * Returns the tree contents as a binary archive, using a stream.
+     */
+    archive(): Promise<NodeJS.ReadableStream>;
+    /**
+     * Extracts the tree response into a directory and returns the path of the
+     * directory.
+     *
+     * **NOTE**: It is the responsibility of the caller to remove the directory after use.
+     */
+    dir(options?: ReadTreeResponseDirOptions): Promise<string>;
+    /**
+     * Etag returned by content provider.
+     *
+     * @remarks
+     *
+     * Can be used to compare and cache responses when doing subsequent calls.
+     */
+    etag: string;
+};
 
-/** @public */
-export declare type RootLoggerService = LoggerService;
+/**
+ * Options that control {@link ReadTreeResponse.dir} execution.
+ *
+ * @public
+ */
+export declare type ReadTreeResponseDirOptions = {
+    /**
+     * The directory to write files to.
+     *
+     * @remarks
+     *
+     * Defaults to the OS tmpdir, or `backend.workingDirectory` if set in config.
+     */
+    targetDir?: string;
+};
+
+/**
+ * Represents a single file in a {@link UrlReaderService.readTree} response.
+ *
+ * @public
+ */
+export declare type ReadTreeResponseFile = {
+    path: string;
+    content(): Promise<Buffer>;
+};
 
 /**
+ * An options object for readUrl operations.
+ *
  * @public
  */
-declare const rootLoggerServiceRef: ServiceRef<LoggerService, "root">;
+export declare type ReadUrlOptions = {
+    /**
+     * An ETag which can be provided to check whether a
+     * {@link UrlReaderService.readUrl} response has changed from a previous execution.
+     *
+     * @remarks
+     *
+     * In the {@link UrlReaderService.readUrl} response, an ETag is returned along with
+     * the data. The ETag is a unique identifier of the data, usually the commit
+     * SHA or ETag from the target.
+     *
+     * When an ETag is given in ReadUrlOptions, {@link UrlReaderService.readUrl} will
+     * first compare the ETag against the ETag of the target. If they match,
+     * {@link UrlReaderService.readUrl} will throw a
+     * {@link @backstage/errors#NotModifiedError} indicating that the response
+     * will not differ from the previous response which included this particular
+     * ETag. If they do not match, {@link UrlReaderService.readUrl} will return the rest
+     * of the response along with a new ETag.
+     */
+    etag?: string;
+    /**
+     * An abort signal to pass down to the underlying request.
+     *
+     * @remarks
+     *
+     * Not all reader implementations may take this field into account.
+     */
+    signal?: AbortSignal;
+};
+
+/**
+ * A response object for {@link UrlReaderService.readUrl} operations.
+ *
+ * @public
+ */
+export declare type ReadUrlResponse = {
+    /**
+     * Returns the data that was read from the remote URL.
+     */
+    buffer(): Promise<Buffer>;
+    /**
+     * Returns the data that was read from the remote URL as a Readable stream.
+     *
+     * @remarks
+     *
+     * This method will be required in a future release.
+     */
+    stream?(): Readable;
+    /**
+     * Etag returned by content provider.
+     *
+     * @remarks
+     *
+     * Can be used to compare and cache responses when doing subsequent calls.
+     */
+    etag?: string;
+};
+
+/** @public */
+export declare interface RootLifecycleService extends LifecycleService {
+}
+
+/** @public */
+export declare interface RootLoggerService extends LoggerService {
+}
 
 /** @public */
-export declare type SchedulerService = PluginTaskScheduler;
+export declare interface SchedulerService extends PluginTaskScheduler {
+}
+
+/**
+ * An options object for search operations.
+ *
+ * @public
+ */
+export declare type SearchOptions = {
+    /**
+     * An etag can be provided to check whether the search response has changed from a previous execution.
+     *
+     * In the search() response, an etag is returned along with the files. The etag is a unique identifier
+     * of the current tree, usually the commit SHA or etag from the target.
+     *
+     * When an etag is given in SearchOptions, search will first compare the etag against the etag
+     * on the target branch. If they match, search will throw a NotModifiedError indicating that the search
+     * response will not differ from the previous response which included this particular etag. If they mismatch,
+     * search will return the rest of SearchResponse along with a new etag.
+     */
+    etag?: string;
+    /**
+     * An abort signal to pass down to the underlying request.
+     *
+     * @remarks
+     *
+     * Not all reader implementations may take this field into account.
+     */
+    signal?: AbortSignal;
+};
+
+/**
+ * The output of a search operation.
+ *
+ * @public
+ */
+export declare type SearchResponse = {
+    /**
+     * The files that matched the search query.
+     */
+    files: SearchResponseFile[];
+    /**
+     * A unique identifier of the current remote tree, usually the commit SHA or etag from the target.
+     */
+    etag: string;
+};
 
 /**
+ * Represents a single file in a search response.
+ *
  * @public
  */
-declare const schedulerServiceRef: ServiceRef<PluginTaskScheduler, "plugin">;
+export declare type SearchResponseFile = {
+    /**
+     * The full URL to the file.
+     */
+    url: string;
+    /**
+     * The binary contents of the file.
+     */
+    content(): Promise<Buffer>;
+};
 
 /** @public */
 export declare type ServiceFactory<TService = unknown> = {
@@ -323,24 +632,32 @@ declare type ServiceRefsToInstances<T extends {
 };
 
 /** @public */
-export declare type TokenManagerService = TokenManager;
-
-/**
- * @public
- */
-declare const tokenManagerServiceRef: ServiceRef<TokenManager, "plugin">;
+export declare interface TokenManagerService extends TokenManager {
+}
 
 /** @public */
 export declare type TypesToServiceRef<T> = {
     [key in keyof T]: ServiceRef<T[key]>;
 };
 
-/** @public */
-export declare type UrlReaderService = UrlReader;
-
 /**
+ * A generic interface for fetching plain data from URLs.
+ *
  * @public
  */
-declare const urlReaderServiceRef: ServiceRef<UrlReader, "plugin">;
+export declare interface UrlReaderService {
+    /**
+     * Reads a single file and return its content.
+     */
+    readUrl(url: string, options?: ReadUrlOptions): Promise<ReadUrlResponse>;
+    /**
+     * Reads a full or partial file tree.
+     */
+    readTree(url: string, options?: ReadTreeOptions): Promise<ReadTreeResponse>;
+    /**
+     * Searches for a file in a tree using a glob pattern.
+     */
+    search(url: string, options?: SearchOptions): Promise<SearchResponse>;
+}
 
 export { }