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

package/dist/index.d.ts

@@ -4,18 +4,19 @@
  * @packageDocumentation
  */
 
+/// <reference types="node" />
+
 import { Config } from '@backstage/config';
 import { Handler } from 'express';
-import { Logger as Logger_2 } from 'winston';
+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 {
@@ -23,23 +24,6 @@ export declare interface BackendFeature {
     register(reg: BackendRegistrationPoints): void;
 }
 
-/**
- * @public
- **/
-export declare interface BackendLifecycle {
-    /**
-     * Register a function to be called when the backend is shutting down.
-     */
-    addShutdownHook(options: BackendLifecycleShutdownHook): void;
-}
-
-/**
- * @public
- **/
-export declare type BackendLifecycleShutdownHook = {
-    fn: () => void | Promise<void>;
-};
-
 /** @public */
 export declare interface BackendModuleConfig<TOptions> {
     pluginId: string;
@@ -66,11 +50,19 @@ export declare interface BackendRegistrationPoints {
     }): void;
 }
 
+/** @public */
+export declare type CacheService = PluginCacheManager;
+
 /**
  * @public
  */
 declare const cacheServiceRef: ServiceRef<PluginCacheManager, "plugin">;
 
+/**
+ * @public
+ */
+export declare type ConfigService = Config;
+
 /**
  * @public
  */
@@ -88,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
@@ -145,15 +138,65 @@ export declare function createServiceRef<T>(options: {
     defaultFactory?: (service: ServiceRef<T, 'root'>) => Promise<ServiceFactory<T> | (() => ServiceFactory<T>)>;
 }): ServiceRef<T, 'root'>;
 
+/** @public */
+export declare type DatabaseService = PluginDatabaseManager;
+
 /**
  * @public
  */
 declare const databaseServiceRef: ServiceRef<PluginDatabaseManager, "plugin">;
 
+/**
+ * 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
@@ -183,56 +226,333 @@ export declare interface HttpRouterService {
  */
 declare const httpRouterServiceRef: ServiceRef<HttpRouterService, "plugin">;
 
+/**
+ * @public
+ **/
+export declare interface LifecycleService {
+    /**
+     * Register a function to be called when the backend is shutting down.
+     */
+    addShutdownHook(options: LifecycleServiceShutdownHook): void;
+}
+
 /**
  * @public
  */
-declare const lifecycleServiceRef: ServiceRef<BackendLifecycle, "plugin">;
+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>;
+};
 
 /**
  * @public
  */
-export declare interface Logger {
-    info(message: string): void;
-    child(fields: {
-        [name: string]: string;
-    }): Logger;
+export declare interface LoggerService {
+    error(message: string, meta?: Error | LogMeta): void;
+    warn(message: string, meta?: Error | LogMeta): void;
+    info(message: string, meta?: Error | LogMeta): void;
+    debug(message: string, meta?: Error | LogMeta): void;
+    child(meta: LogMeta): LoggerService;
 }
 
 /**
  * @public
  */
-declare const loggerServiceRef: ServiceRef<Logger, "plugin">;
+declare const loggerServiceRef: ServiceRef<LoggerService, "plugin">;
 
 /** @public */
-export declare function loggerToWinstonLogger(logger: Logger, opts?: TransportStreamOptions): Logger_2;
+export declare function loggerToWinstonLogger(logger: LoggerService, opts?: TransportStreamOptions): Logger;
 
 /**
  * @public
  */
-declare const permissionsServiceRef: ServiceRef<PermissionAuthorizer | PermissionEvaluator, "plugin">;
+export declare type LogMeta = {
+    [name: string]: unknown;
+};
+
+/** @public */
+export declare type PermissionsService = PermissionEvaluator | PermissionAuthorizer;
 
 /**
  * @public
  */
-export declare interface PluginMetadata {
+declare const permissionsServiceRef: ServiceRef<PermissionsService, "plugin">;
+
+/**
+ * @public
+ */
+export declare interface PluginMetadataService {
     getId(): string;
 }
 
 /**
  * @public
  */
-declare const pluginMetadataServiceRef: ServiceRef<PluginMetadata, "plugin">;
+declare const pluginMetadataServiceRef: ServiceRef<PluginMetadataService, "plugin">;
 
 /**
+ * An options object for {@link UrlReaderService.readTree} operations.
+ *
  * @public
  */
-declare const rootLoggerServiceRef: ServiceRef<Logger, "root">;
+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;
+
+/**
+ * @public
+ */
+declare const rootLoggerServiceRef: ServiceRef<LoggerService, "root">;
+
+/** @public */
+export declare type SchedulerService = PluginTaskScheduler;
 
 /**
  * @public
  */
 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';
@@ -291,6 +611,9 @@ declare type ServiceRefsToInstances<T extends {
     }[keyof T]]: T[name] extends ServiceRef<infer TImpl> ? TImpl : never;
 };
 
+/** @public */
+export declare type TokenManagerService = TokenManager;
+
 /**
  * @public
  */
@@ -301,9 +624,29 @@ export declare type TypesToServiceRef<T> = {
     [key in keyof T]: ServiceRef<T[key]>;
 };
 
+/**
+ * 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 { }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@backstage/backend-plugin-api",
   "description": "Core API used by Backstage backend plugins",
-  "version": "0.2.0-next.3",
+  "version": "0.2.1-next.0",
   "main": "dist/index.cjs.js",
   "types": "dist/index.d.ts",
   "publishConfig": {
@@ -33,17 +33,17 @@
     "start": "backstage-cli package start"
   },
   "dependencies": {
-    "@backstage/backend-common": "^0.17.0-next.3",
-    "@backstage/backend-tasks": "^0.4.0-next.3",
-    "@backstage/config": "^1.0.5-next.1",
-    "@backstage/plugin-permission-common": "^0.7.2-next.2",
+    "@backstage/backend-common": "^0.18.0-next.0",
+    "@backstage/backend-tasks": "^0.4.1-next.0",
+    "@backstage/config": "^1.0.6-next.0",
+    "@backstage/plugin-permission-common": "^0.7.3-next.0",
     "@types/express": "^4.17.6",
     "express": "^4.17.1",
     "winston": "^3.2.1",
     "winston-transport": "^4.5.0"
   },
   "devDependencies": {
-    "@backstage/cli": "^0.22.0-next.4"
+    "@backstage/cli": "^0.22.1-next.1"
   },
   "files": [
     "dist",