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

package/dist/index.d.ts

@@ -4,18 +4,15 @@
  * @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 { JsonValue } from '@backstage/types';
+import { Knex } from 'knex';
 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 { TokenManager } from '@backstage/backend-common';
-import { TransportStreamOptions } from 'winston-transport';
-import { UrlReader } from '@backstage/backend-common';
+import { Readable } from 'stream';
 
 /** @public */
 export declare interface BackendFeature {
@@ -49,42 +46,178 @@ export declare interface BackendRegistrationPoints {
     }): void;
 }
 
-/** @public */
-export declare type CacheService = PluginCacheManager;
+/**
+ * A pre-configured, storage agnostic cache client suitable for use by
+ * Backstage plugins.
+ *
+ * @public
+ */
+export declare interface CacheClient {
+    /**
+     * Reads data from a cache store for the given key. If no data was found,
+     * returns undefined.
+     */
+    get(key: string): Promise<JsonValue | undefined>;
+    /**
+     * Writes the given data to a cache store, associated with the given key. An
+     * optional TTL may also be provided, otherwise it defaults to the TTL that
+     * was provided when the client was instantiated.
+     */
+    set(key: string, value: JsonValue, options?: CacheClientSetOptions): Promise<void>;
+    /**
+     * Removes the given key from the cache store.
+     */
+    delete(key: string): Promise<void>;
+}
 
 /**
+ * Options given when constructing a {@link CacheClient}.
+ *
  * @public
  */
-declare const cacheServiceRef: ServiceRef<PluginCacheManager, "plugin">;
+export declare type CacheClientOptions = {
+    /**
+     * An optional default TTL (in milliseconds) to be set when getting a client
+     * instance. If not provided, data will persist indefinitely by default (or
+     * can be configured per entry at set-time).
+     */
+    defaultTtl?: number;
+};
 
 /**
+ * Options passed to {@link CacheClient.set}.
+ *
+ * @public
+ */
+export declare type CacheClientSetOptions = {
+    /**
+     * Optional TTL in milliseconds. Defaults to the TTL provided when the client
+     * was set up (or no TTL if none are provided).
+     */
+    ttl?: number;
+};
+
+/**
+ * Manages access to cache stores that plugins get.
+ *
  * @public
  */
-export declare type ConfigService = Config;
+export declare interface CacheService {
+    /**
+     * Provides backend plugins cache connections for themselves.
+     *
+     * @remarks
+     *
+     * The purpose of this method is to allow plugins to get isolated data stores
+     * so that plugins are discouraged from cache-level integration and/or cache
+     * key collisions.
+     */
+    getClient: (options?: CacheClientOptions) => CacheClient;
+}
 
 /**
  * @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 interface ConfigService extends Config {
+}
+
+/**
+ * All core services references
+ *
+ * @public
+ */
+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 RootHttpRouterService}.
+     *
+     * @public
+     */
+    const rootHttpRouter: ServiceRef<RootHttpRouterService, "root">;
+    /**
+     * 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
@@ -136,21 +269,78 @@ 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;
-
 /**
+ * The DatabaseService manages access to databases that Plugins get.
+ *gs
  * @public
  */
-declare const databaseServiceRef: ServiceRef<PluginDatabaseManager, "plugin">;
-
-/** @public */
-export declare type DiscoveryService = PluginEndpointDiscovery;
+export declare interface DatabaseService {
+    /**
+     * getClient provides backend plugins database connections for itself.
+     *
+     * The purpose of this method is to allow plugins to get isolated data
+     * stores so that plugins are discouraged from database integration.
+     */
+    getClient(): Promise<Knex>;
+    /**
+     * This property is used to control the behavior of database migrations.
+     */
+    migrations?: {
+        /**
+         * skip database migrations. Useful if connecting to a read-only database.
+         *
+         * @defaultValue false
+         */
+        skip?: boolean;
+    };
+}
 
 /**
+ * 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 +365,6 @@ export declare interface HttpRouterService {
     use(handler: Handler): void;
 }
 
-/**
- * @public
- */
-declare const httpRouterServiceRef: ServiceRef<HttpRouterService, "plugin">;
-
 /**
  * @public
  **/
@@ -190,19 +375,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 {
@@ -216,53 +400,276 @@ export declare interface LoggerService {
 /**
  * @public
  */
-declare const loggerServiceRef: ServiceRef<LoggerService, "plugin">;
+export declare type LogMeta = {
+    [name: string]: unknown;
+};
 
 /** @public */
-export declare function loggerToWinstonLogger(logger: LoggerService, opts?: TransportStreamOptions): Logger;
+export declare interface PermissionsService extends PermissionEvaluator {
+}
 
 /**
  * @public
  */
-export declare type LogMeta = {
-    [name: string]: unknown;
+export declare interface PluginMetadataService {
+    getId(): string;
+}
+
+/**
+ * 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;
 };
 
-/** @public */
-export declare type PermissionsService = PermissionEvaluator | PermissionAuthorizer;
+/**
+ * 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
  */
-declare const permissionsServiceRef: ServiceRef<PermissionsService, "plugin">;
+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 interface PluginMetadataService {
-    getId(): string;
-}
+export declare type ReadTreeResponseFile = {
+    path: string;
+    content(): Promise<Buffer>;
+};
 
 /**
+ * An options object for readUrl operations.
+ *
  * @public
  */
-declare const pluginMetadataServiceRef: ServiceRef<PluginMetadataService, "plugin">;
+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;
+};
 
-/** @public */
-export declare type RootLoggerService = LoggerService;
+/**
+ * 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
  */
-declare const rootLoggerServiceRef: ServiceRef<LoggerService, "root">;
+export declare 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;
+}
 
 /** @public */
-export declare type SchedulerService = PluginTaskScheduler;
+export declare interface RootLifecycleService extends LifecycleService {
+}
+
+/** @public */
+export declare interface RootLoggerService extends LoggerService {
+}
+
+/** @public */
+export declare interface SchedulerService extends PluginTaskScheduler {
+}
 
 /**
+ * An options object for search operations.
+ *
  * @public
  */
-declare const schedulerServiceRef: ServiceRef<PluginTaskScheduler, "plugin">;
+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> = {
@@ -322,25 +729,54 @@ declare type ServiceRefsToInstances<T extends {
     }[keyof T]]: T[name] extends ServiceRef<infer TImpl> ? TImpl : never;
 };
 
-/** @public */
-export declare type TokenManagerService = TokenManager;
-
 /**
+ * Interface for creating and validating tokens.
+ *
  * @public
  */
-declare const tokenManagerServiceRef: ServiceRef<TokenManager, "plugin">;
+export declare interface TokenManagerService {
+    /**
+     * Fetches a valid token.
+     *
+     * @remarks
+     *
+     * Tokens are valid for roughly one hour; the actual deadline is set in the
+     * payload `exp` claim. Never hold on to tokens for reuse; always ask for a
+     * new one for each outgoing request. This ensures that you always get a
+     * valid, fresh one.
+     */
+    getToken(): Promise<{
+        token: string;
+    }>;
+    /**
+     * Validates a given token.
+     */
+    authenticate(token: string): Promise<void>;
+}
 
 /** @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 { }