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

package/dist/index.d.ts

@@ -8,15 +8,12 @@
 
 import { Config } from '@backstage/config';
 import { Handler } from 'express';
-import { Logger } from 'winston';
-import { PermissionAuthorizer } from '@backstage/plugin-permission-common';
+import { IdentityApi } from '@backstage/plugin-auth-node';
+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 { PluginTaskScheduler } from '@backstage/backend-tasks';
 import { Readable } from 'stream';
-import { TokenManager } from '@backstage/backend-common';
-import { TransportStreamOptions } from 'winston-transport';
 
 /** @public */
 export declare interface BackendFeature {
@@ -25,16 +22,16 @@ export declare interface BackendFeature {
 }
 
 /** @public */
-export declare interface BackendModuleConfig<TOptions> {
+export declare interface BackendModuleConfig {
     pluginId: string;
     moduleId: string;
-    register(reg: Omit<BackendRegistrationPoints, 'registerExtensionPoint'>, options: TOptions): void;
+    register(reg: Omit<BackendRegistrationPoints, 'registerExtensionPoint'>): void;
 }
 
 /** @public */
-export declare interface BackendPluginConfig<TOptions> {
+export declare interface BackendPluginConfig {
     id: string;
-    register(reg: BackendRegistrationPoints, options: TOptions): void;
+    register(reg: BackendRegistrationPoints): void;
 }
 
 /** @public */
@@ -50,49 +47,192 @@ 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
  */
-declare const cacheServiceRef: ServiceRef<PluginCacheManager, "plugin">;
+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
  */
-export declare type ConfigService = Config;
+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
  */
-declare const configServiceRef: ServiceRef<Config, "root">;
+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;
+};
 
-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,
-        rootLifecycleServiceRef as rootLifecycle,
-        rootLoggerServiceRef as rootLogger,
-        pluginMetadataServiceRef as pluginMetadata,
-        lifecycleServiceRef as lifecycle
-    }
+/**
+ * Manages access to cache stores that plugins get.
+ *
+ * @public
+ */
+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;
 }
-export { coreServices }
 
 /**
  * @public
+ */
+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">;
+    /**
+     * The service reference for the plugin scoped {@link IdentityService}.
+     *
+     * @public
+     */
+    const identity: ServiceRef<IdentityService, "plugin">;
+}
+
+/**
  * Creates a new backend module for a given plugin.
  *
+ * @public
+ *
+ * @remarks
+ *
  * The `moduleId` should be equal to the module-specific prefix of the exported name, such
  * that the full name is `moduleId + PluginId + "Module"`. For example, a GitHub entity
  * provider module for the `catalog` plugin might have the module ID `'githubEntityProvider'`,
@@ -100,51 +240,119 @@ export { coreServices }
  *
  * The `pluginId` should exactly match the `id` of the plugin that the module extends.
  */
-export declare function createBackendModule<TOptions extends object | undefined = undefined>(config: BackendModuleConfig<TOptions>): undefined extends TOptions ? (options?: TOptions) => BackendFeature : (options: TOptions) => BackendFeature;
+export declare function createBackendModule<TOptions extends [options?: object] = []>(config: BackendModuleConfig | ((...params: TOptions) => BackendModuleConfig)): (...params: TOptions) => BackendFeature;
 
 /** @public */
-export declare function createBackendPlugin<TOptions extends object | undefined = undefined>(config: {
-    id: string;
-    register(reg: BackendRegistrationPoints, options: TOptions): void;
-}): undefined extends TOptions ? (options?: TOptions) => BackendFeature : (options: TOptions) => BackendFeature;
+export declare function createBackendPlugin<TOptions extends [options?: object] = []>(config: BackendPluginConfig | ((...params: TOptions) => BackendPluginConfig)): (...params: TOptions) => BackendFeature;
 
 /** @public */
-export declare function createExtensionPoint<T>(options: {
-    id: string;
-}): ExtensionPoint<T>;
+export declare function createExtensionPoint<T>(config: ExtensionPointConfig): ExtensionPoint<T>;
 
 /**
+ * Creates a root scoped service factory without options.
+ *
  * @public
+ * @param config - The service factory configuration.
  */
-export declare function createServiceFactory<TService, TScope extends 'root' | 'plugin', TImpl extends TService, TDeps extends {
+export declare function createServiceFactory<TService, TImpl extends TService, TDeps extends {
     [name in string]: ServiceRef<unknown>;
-}, TOpts extends object | undefined = undefined>(config: {
-    service: ServiceRef<TService, TScope>;
-    deps: TDeps;
-    factory(deps: ServiceRefsToInstances<TDeps, 'root'>, options: TOpts): TScope extends 'root' ? Promise<TImpl> : Promise<(deps: ServiceRefsToInstances<TDeps>) => Promise<TImpl>>;
-}): undefined extends TOpts ? (options?: TOpts) => ServiceFactory<TService> : (options: TOpts) => ServiceFactory<TService>;
+}, TOpts extends object | undefined = undefined>(config: RootServiceFactoryConfig<TService, TImpl, TDeps>): () => ServiceFactory<TService>;
 
-/** @public */
-export declare function createServiceRef<T>(options: {
-    id: string;
-    scope?: 'plugin';
-    defaultFactory?: (service: ServiceRef<T, 'plugin'>) => Promise<ServiceFactory<T> | (() => ServiceFactory<T>)>;
-}): ServiceRef<T, 'plugin'>;
+/**
+ * Creates a root scoped service factory with optional options.
+ *
+ * @public
+ * @param config - The service factory configuration.
+ */
+export declare function createServiceFactory<TService, TImpl extends TService, TDeps extends {
+    [name in string]: ServiceRef<unknown>;
+}, TOpts extends object | undefined = undefined>(config: (options?: TOpts) => RootServiceFactoryConfig<TService, TImpl, TDeps>): (options?: TOpts) => ServiceFactory<TService>;
 
-/** @public */
-export declare function createServiceRef<T>(options: {
-    id: string;
-    scope: 'root';
-    defaultFactory?: (service: ServiceRef<T, 'root'>) => Promise<ServiceFactory<T> | (() => ServiceFactory<T>)>;
-}): ServiceRef<T, 'root'>;
+/**
+ * Creates a root scoped service factory with required options.
+ *
+ * @public
+ * @param config - The service factory configuration.
+ */
+export declare function createServiceFactory<TService, TImpl extends TService, TDeps extends {
+    [name in string]: ServiceRef<unknown>;
+}, TOpts extends object | undefined = undefined>(config: (options: TOpts) => RootServiceFactoryConfig<TService, TImpl, TDeps>): (options: TOpts) => ServiceFactory<TService>;
 
-/** @public */
-export declare type DatabaseService = PluginDatabaseManager;
+/**
+ * Creates a plugin scoped service factory without options.
+ *
+ * @public
+ * @param config - The service factory configuration.
+ */
+export declare function createServiceFactory<TService, TImpl extends TService, TDeps extends {
+    [name in string]: ServiceRef<unknown>;
+}, TContext = undefined, TOpts extends object | undefined = undefined>(config: PluginServiceFactoryConfig<TService, TContext, TImpl, TDeps>): () => ServiceFactory<TService>;
+
+/**
+ * Creates a plugin scoped service factory with optional options.
+ *
+ * @public
+ * @param config - The service factory configuration.
+ */
+export declare function createServiceFactory<TService, TImpl extends TService, TDeps extends {
+    [name in string]: ServiceRef<unknown>;
+}, TContext = undefined, TOpts extends object | undefined = undefined>(config: (options?: TOpts) => PluginServiceFactoryConfig<TService, TContext, TImpl, TDeps>): (options?: TOpts) => ServiceFactory<TService>;
+
+/**
+ * Creates a plugin scoped service factory with required options.
+ *
+ * @public
+ * @param config - The service factory configuration.
+ */
+export declare function createServiceFactory<TService, TImpl extends TService, TDeps extends {
+    [name in string]: ServiceRef<unknown>;
+}, TContext = undefined, TOpts extends object | undefined = undefined>(config: PluginServiceFactoryConfig<TService, TContext, TImpl, TDeps> | ((options: TOpts) => PluginServiceFactoryConfig<TService, TContext, TImpl, TDeps>)): (options: TOpts) => ServiceFactory<TService>;
+
+/**
+ * Creates a new service definition. This overload is used to create plugin scoped services.
+ *
+ * @public
+ */
+export declare function createServiceRef<TService>(config: ServiceRefConfig<TService, 'plugin'>): ServiceRef<TService, 'plugin'>;
+
+/**
+ * Creates a new service definition. This overload is used to create root scoped services.
+ *
+ * @public
+ */
+export declare function createServiceRef<TService>(config: ServiceRefConfig<TService, 'root'>): ServiceRef<TService, 'root'>;
 
 /**
+ * Creates a shared backend environment which can be used to create multiple backends
  * @public
  */
-declare const databaseServiceRef: ServiceRef<PluginDatabaseManager, "plugin">;
+export declare function createSharedEnvironment<TOptions extends [options?: object] = []>(config: SharedBackendEnvironmentConfig | ((...params: TOptions) => SharedBackendEnvironmentConfig)): (...options: TOptions) => SharedBackendEnvironment;
+
+/**
+ * The DatabaseService manages access to databases that Plugins get.
+ *
+ * @public
+ */
+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
@@ -160,7 +368,7 @@ declare const databaseServiceRef: ServiceRef<PluginDatabaseManager, "plugin">;
  *
  * @public
  */
-export declare type DiscoveryService = {
+export declare interface DiscoveryService {
     /**
      * Returns the internal HTTP base URL for a given plugin, without a trailing slash.
      *
@@ -191,12 +399,7 @@ export declare type DiscoveryService = {
      * like `https://backstage.example.com/api/catalog`
      */
     getExternalBaseUrl(pluginId: string): Promise<string>;
-};
-
-/**
- * @public
- */
-declare const discoveryServiceRef: ServiceRef<DiscoveryService, "plugin">;
+}
 
 /**
  * TODO
@@ -214,6 +417,11 @@ export declare type ExtensionPoint<T> = {
     $$ref: 'extension-point';
 };
 
+/** @public */
+export declare interface ExtensionPointConfig {
+    id: string;
+}
+
 /**
  * @public
  */
@@ -221,10 +429,9 @@ export declare interface HttpRouterService {
     use(handler: Handler): void;
 }
 
-/**
- * @public
- */
-declare const httpRouterServiceRef: ServiceRef<HttpRouterService, "plugin">;
+/** @public */
+export declare interface IdentityService extends IdentityApi {
+}
 
 /**
  * @public
@@ -236,21 +443,20 @@ 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>;
+    /**
+     * Optional {@link LoggerService} that will be used for logging instead of the default logger.
+     */
+    logger?: LoggerService;
 };
 
 /**
+ * A service that provides a logging facility.
+ *
  * @public
  */
 export declare interface LoggerService {
@@ -261,14 +467,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;
-
 /**
  * @public
  */
@@ -277,12 +475,8 @@ export declare type LogMeta = {
 };
 
 /** @public */
-export declare type PermissionsService = PermissionEvaluator | PermissionAuthorizer;
-
-/**
- * @public
- */
-declare const permissionsServiceRef: ServiceRef<PermissionsService, "plugin">;
+export declare interface PermissionsService extends PermissionEvaluator {
+}
 
 /**
  * @public
@@ -291,10 +485,15 @@ export declare interface PluginMetadataService {
     getId(): string;
 }
 
-/**
- * @public
- */
-declare const pluginMetadataServiceRef: ServiceRef<PluginMetadataService, "plugin">;
+/** @public */
+export declare interface PluginServiceFactoryConfig<TService, TContext, TImpl extends TService, TDeps extends {
+    [name in string]: ServiceRef<unknown>;
+}> {
+    service: ServiceRef<TService, 'plugin'>;
+    deps: TDeps;
+    createRootContext?(deps: ServiceRefsToInstances<TDeps, 'root'>): TContext | Promise<TContext>;
+    factory(deps: ServiceRefsToInstances<TDeps>, context: TContext): TImpl | Promise<TImpl>;
+}
 
 /**
  * An options object for {@link UrlReaderService.readTree} operations.
@@ -469,29 +668,37 @@ export declare type ReadUrlResponse = {
     etag?: string;
 };
 
-/** @public */
-export declare type RootLifecycleService = LifecycleService;
-
 /**
  * @public
  */
-declare const rootLifecycleServiceRef: ServiceRef<LifecycleService, "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 RootLoggerService = LoggerService;
+export declare interface RootLifecycleService extends LifecycleService {
+}
 
-/**
- * @public
- */
-declare const rootLoggerServiceRef: ServiceRef<LoggerService, "root">;
+/** @public */
+export declare interface RootLoggerService extends LoggerService {
+}
 
 /** @public */
-export declare type SchedulerService = PluginTaskScheduler;
+export declare interface RootServiceFactoryConfig<TService, TImpl extends TService, TDeps extends {
+    [name in string]: ServiceRef<unknown>;
+}> {
+    service: ServiceRef<TService, 'root'>;
+    deps: TDeps;
+    factory(deps: ServiceRefsToInstances<TDeps, 'root'>): TImpl | Promise<TImpl>;
+}
 
-/**
- * @public
- */
-declare const schedulerServiceRef: ServiceRef<PluginTaskScheduler, "plugin">;
+/** @public */
+export declare interface SchedulerService extends PluginTaskScheduler {
+}
 
 /**
  * An options object for search operations.
@@ -569,13 +776,21 @@ export declare type ServiceFactory<TService = unknown> = {
     deps: {
         [key in string]: ServiceRef<unknown>;
     };
-    factory(deps: {
+    createRootContext?(deps: {
         [key in string]: unknown;
-    }): Promise<(deps: {
+    }): Promise<unknown>;
+    factory(deps: {
         [key in string]: unknown;
-    }) => Promise<TService>>;
+    }, context: unknown): Promise<TService>;
 };
 
+/**
+ * Represents either a {@link ServiceFactory} or a function that returns one.
+ *
+ * @public
+ */
+export declare type ServiceFactoryOrFunction<TService = unknown> = ServiceFactory<TService> | (() => ServiceFactory<TService>);
+
 /**
  * TODO
  *
@@ -602,22 +817,56 @@ export declare type ServiceRef<TService, TScope extends 'root' | 'plugin' = 'roo
     $$ref: 'service';
 };
 
+/** @public */
+export declare interface ServiceRefConfig<TService, TScope extends 'root' | 'plugin'> {
+    id: string;
+    scope?: TScope;
+    defaultFactory?: (service: ServiceRef<TService, TScope>) => Promise<ServiceFactoryOrFunction<TService>>;
+}
+
 /** @ignore */
 declare type ServiceRefsToInstances<T extends {
     [key in string]: ServiceRef<unknown>;
 }, TScope extends 'root' | 'plugin' = 'root' | 'plugin'> = {
-    [name in {
-        [key in keyof T]: T[key] extends ServiceRef<unknown, TScope> ? key : never;
-    }[keyof T]]: T[name] extends ServiceRef<infer TImpl> ? TImpl : never;
+    [key in keyof T as T[key]['scope'] extends TScope ? key : never]: T[key]['T'];
 };
 
+/**
+ * @public
+ */
+export declare interface SharedBackendEnvironment {
+    $$type: 'SharedBackendEnvironment';
+}
+
 /** @public */
-export declare type TokenManagerService = TokenManager;
+export declare interface SharedBackendEnvironmentConfig {
+    services?: ServiceFactoryOrFunction[];
+}
 
 /**
+ * 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> = {
@@ -629,7 +878,7 @@ export declare type TypesToServiceRef<T> = {
  *
  * @public
  */
-export declare type UrlReaderService = {
+export declare interface UrlReaderService {
     /**
      * Reads a single file and return its content.
      */
@@ -642,11 +891,6 @@ export declare type UrlReaderService = {
      * Searches for a file in a tree using a glob pattern.
      */
     search(url: string, options?: SearchOptions): Promise<SearchResponse>;
-};
-
-/**
- * @public
- */
-declare const urlReaderServiceRef: ServiceRef<UrlReaderService, "plugin">;
+}
 
 export { }