@backstage/backend-plugin-api 0.2.0 → 0.2.1-next.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @backstage/backend-plugin-api
 
+## 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
 
 ### Minor Changes

package/alpha/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backstage/backend-plugin-api",
-  "version": "0.2.0",
+  "version": "0.2.1-next.0",
   "main": "../dist/index.cjs.js",
   "types": "../dist/index.alpha.d.ts"
 }

package/dist/index.alpha.d.ts

@@ -4,6 +4,8 @@
  * @packageDocumentation
  */
 
+/// <reference types="node" />
+
 import { Config } from '@backstage/config';
 import { Handler } from 'express';
 import { Logger } from 'winston';
@@ -11,11 +13,10 @@ 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 {
@@ -79,6 +80,7 @@ declare namespace coreServices {
         tokenManagerServiceRef as tokenManager,
         permissionsServiceRef as permissions,
         schedulerServiceRef as scheduler,
+        rootLifecycleServiceRef as rootLifecycle,
         rootLoggerServiceRef as rootLogger,
         pluginMetadataServiceRef as pluginMetadata,
         lifecycleServiceRef as lifecycle
@@ -144,13 +146,57 @@ export declare type DatabaseService = PluginDatabaseManager;
  */
 declare const databaseServiceRef: ServiceRef<PluginDatabaseManager, "plugin">;
 
-/** @public */
-export declare type DiscoveryService = PluginEndpointDiscovery;
+/**
+ * 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
+ */
+export declare type 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>;
+};
 
 /**
  * @public
  */
-declare const discoveryServiceRef: ServiceRef<PluginEndpointDiscovery, "plugin">;
+declare const discoveryServiceRef: ServiceRef<DiscoveryService, "plugin">;
 
 /**
  * TODO
@@ -200,6 +246,8 @@ declare const lifecycleServiceRef: ServiceRef<LifecycleService, "plugin">;
  **/
 export declare type LifecycleServiceShutdownHook = {
     fn: () => void | Promise<void>;
+    /** Labels to help identify the shutdown hook */
+    labels?: Record<string, string>;
 };
 
 /**
@@ -248,6 +296,187 @@ export declare interface PluginMetadataService {
  */
 declare const pluginMetadataServiceRef: ServiceRef<PluginMetadataService, "plugin">;
 
+/**
+ * An options object for {@link UrlReaderService.readTree} operations.
+ *
+ * @public
+ */
+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
+ */
+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;
+};
+
+/**
+ * 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
+ */
+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 type RootLifecycleService = LifecycleService;
+
+/**
+ * @public
+ */
+declare const rootLifecycleServiceRef: ServiceRef<LifecycleService, "root">;
+
 /** @public */
 export declare type RootLoggerService = LoggerService;
 
@@ -264,6 +493,66 @@ export declare type SchedulerService = PluginTaskScheduler;
  */
 declare const schedulerServiceRef: ServiceRef<PluginTaskScheduler, "plugin">;
 
+/**
+ * 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
+ */
+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> = {
     scope: 'root';
@@ -335,12 +624,29 @@ 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
+ */
+export declare type 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>;
+};
 
 /**
  * @public
  */
-declare const urlReaderServiceRef: ServiceRef<UrlReader, "plugin">;
+declare const urlReaderServiceRef: ServiceRef<UrlReaderService, "plugin">;
 
 export { }