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

package/dist/index.d.ts

@@ -8,15 +8,11 @@
 
 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 { 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 {
@@ -50,49 +46,186 @@ 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">;
+}
+
+/**
  * 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 +233,60 @@ 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 MaybeOptions = undefined>(config: BackendModuleConfig<TOptions>): FactoryFunctionWithOptions<BackendFeature, TOptions>;
 
 /** @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 MaybeOptions = undefined>(config: BackendPluginConfig<TOptions>): FactoryFunctionWithOptions<BackendFeature, TOptions>;
 
 /** @public */
-export declare function createExtensionPoint<T>(options: {
-    id: string;
-}): ExtensionPoint<T>;
+export declare function createExtensionPoint<T>(config: ExtensionPointConfig): ExtensionPoint<T>;
 
 /**
  * @public
  */
 export declare function createServiceFactory<TService, TScope extends 'root' | 'plugin', 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 MaybeOptions = undefined>(config: ServiceFactoryConfig<TService, TScope, TImpl, TDeps, TOpts>): FactoryFunctionWithOptions<ServiceFactory<TService>, TOpts>;
 
-/** @public */
-export declare function createServiceRef<T>(options: {
-    id: string;
-    scope?: 'plugin';
-    defaultFactory?: (service: ServiceRef<T, 'plugin'>) => Promise<ServiceFactory<T> | (() => ServiceFactory<T>)>;
-}): ServiceRef<T, 'plugin'>;
-
-/** @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 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'>;
 
-/** @public */
-export declare type DatabaseService = PluginDatabaseManager;
+/**
+ * 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'>;
 
 /**
+ * The DatabaseService manages access to databases that Plugins get.
+ *gs
  * @public
  */
-declare const databaseServiceRef: ServiceRef<PluginDatabaseManager, "plugin">;
+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 +302,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 +333,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,17 +351,24 @@ export declare type ExtensionPoint<T> = {
     $$ref: 'extension-point';
 };
 
+/** @public */
+export declare interface ExtensionPointConfig {
+    id: string;
+}
+
 /**
- * @public
+ * Helper type that makes the options argument optional if options are not required.
+ *
+ * @ignore
  */
-export declare interface HttpRouterService {
-    use(handler: Handler): void;
-}
+declare type FactoryFunctionWithOptions<TResult, TOptions> = undefined extends TOptions ? (options?: TOptions) => TResult : (options: TOptions) => TResult;
 
 /**
  * @public
  */
-declare const httpRouterServiceRef: ServiceRef<HttpRouterService, "plugin">;
+export declare interface HttpRouterService {
+    use(handler: Handler): void;
+}
 
 /**
  * @public
@@ -236,21 +380,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 +404,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
  */
@@ -276,13 +411,16 @@ export declare type LogMeta = {
     [name: string]: unknown;
 };
 
-/** @public */
-export declare type PermissionsService = PermissionEvaluator | PermissionAuthorizer;
-
 /**
- * @public
+ * Base type for options objects that aren't required.
+ *
+ * @ignore
  */
-declare const permissionsServiceRef: ServiceRef<PermissionsService, "plugin">;
+declare type MaybeOptions = object | undefined;
+
+/** @public */
+export declare interface PermissionsService extends PermissionEvaluator {
+}
 
 /**
  * @public
@@ -291,11 +429,6 @@ export declare interface PluginMetadataService {
     getId(): string;
 }
 
-/**
- * @public
- */
-declare const pluginMetadataServiceRef: ServiceRef<PluginMetadataService, "plugin">;
-
 /**
  * An options object for {@link UrlReaderService.readTree} operations.
  *
@@ -469,29 +602,28 @@ 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;
-
-/**
- * @public
- */
-declare const rootLoggerServiceRef: ServiceRef<LoggerService, "root">;
+export declare interface RootLifecycleService extends LifecycleService {
+}
 
 /** @public */
-export declare type SchedulerService = PluginTaskScheduler;
+export declare interface RootLoggerService extends LoggerService {
+}
 
-/**
- * @public
- */
-declare const schedulerServiceRef: ServiceRef<PluginTaskScheduler, "plugin">;
+/** @public */
+export declare interface SchedulerService extends PluginTaskScheduler {
+}
 
 /**
  * An options object for search operations.
@@ -576,6 +708,22 @@ export declare type ServiceFactory<TService = unknown> = {
     }) => Promise<TService>>;
 };
 
+/** @public */
+export declare interface ServiceFactoryConfig<TService, TScope extends 'root' | 'plugin', TImpl extends TService, TDeps extends {
+    [name in string]: ServiceRef<unknown>;
+}, TOpts extends MaybeOptions = undefined> {
+    service: ServiceRef<TService, TScope>;
+    deps: TDeps;
+    factory(deps: ServiceRefsToInstances<TDeps, 'root'>, options: TOpts): TScope extends 'root' ? Promise<TImpl> : Promise<(deps: ServiceRefsToInstances<TDeps>) => Promise<TImpl>>;
+}
+
+/**
+ * Represents either a {@link ServiceFactory} or a function that returns one.
+ *
+ * @public
+ */
+export declare type ServiceFactoryOrFunction<TService = unknown> = ServiceFactory<TService> | (() => ServiceFactory<TService>);
+
 /**
  * TODO
  *
@@ -602,6 +750,13 @@ 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>;
@@ -611,13 +766,30 @@ 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> = {
@@ -629,7 +801,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 +814,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 { }

package/package.json

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