diff --git a/.changeset/nasty-pumas-kneel.md b/.changeset/nasty-pumas-kneel.md new file mode 100644 index 0000000000..cdfda89868 --- /dev/null +++ b/.changeset/nasty-pumas-kneel.md @@ -0,0 +1,6 @@ +--- +'@backstage/backend-plugin-api': patch +'@backstage/backend-common': patch +--- + +Migrated types related to `TokenManagerService`, `CacheService` and `DatabaseService` into backend-plugin-api. diff --git a/packages/backend-app-api/api-report.md b/packages/backend-app-api/api-report.md index dcf3ced5e8..1ff40c8b5d 100644 --- a/packages/backend-app-api/api-report.md +++ b/packages/backend-app-api/api-report.md @@ -4,15 +4,15 @@ ```ts import { BackendFeature } from '@backstage/backend-plugin-api'; -import { CacheService } from '@backstage/backend-plugin-api'; import { ConfigService } from '@backstage/backend-plugin-api'; -import { DatabaseService } from '@backstage/backend-plugin-api'; import { ExtensionPoint } from '@backstage/backend-plugin-api'; import { Handler } from 'express'; import { HttpRouterService } from '@backstage/backend-plugin-api'; import { LifecycleService } from '@backstage/backend-plugin-api'; import { LoggerService } from '@backstage/backend-plugin-api'; import { PermissionsService } from '@backstage/backend-plugin-api'; +import { PluginCacheManager } from '@backstage/backend-common'; +import { PluginDatabaseManager } from '@backstage/backend-common'; import { PluginEndpointDiscovery } from '@backstage/backend-common'; import { RootHttpRouterService } from '@backstage/backend-plugin-api'; import { RootLifecycleService } from '@backstage/backend-plugin-api'; @@ -36,7 +36,7 @@ export interface Backend { // @public (undocumented) export const cacheFactory: ( options?: undefined, -) => ServiceFactory; +) => ServiceFactory; // @public (undocumented) export const configFactory: ( @@ -57,7 +57,7 @@ export interface CreateSpecializedBackendOptions { // @public (undocumented) export const databaseFactory: ( options?: undefined, -) => ServiceFactory; +) => ServiceFactory; // @public (undocumented) export const discoveryFactory: ( diff --git a/packages/backend-common/api-report.md b/packages/backend-common/api-report.md index 7e81d40394..43260c2a64 100644 --- a/packages/backend-common/api-report.md +++ b/packages/backend-common/api-report.md @@ -12,6 +12,9 @@ import { AzureIntegration } from '@backstage/integration'; import { BitbucketCloudIntegration } from '@backstage/integration'; import { BitbucketIntegration } from '@backstage/integration'; import { BitbucketServerIntegration } from '@backstage/integration'; +import { CacheClient } from '@backstage/backend-plugin-api'; +import { CacheClientOptions } from '@backstage/backend-plugin-api'; +import { CacheClientSetOptions } from '@backstage/backend-plugin-api'; import { Config } from '@backstage/config'; import cors from 'cors'; import Docker from 'dockerode'; @@ -24,13 +27,14 @@ import { GithubCredentialsProvider } from '@backstage/integration'; import { GithubIntegration } from '@backstage/integration'; import { GitLabIntegration } from '@backstage/integration'; import { isChildPath } from '@backstage/cli-common'; -import { JsonValue } from '@backstage/types'; import { Knex } from 'knex'; import { KubeConfig } from '@kubernetes/client-node'; import { LoadConfigOptionsRemote } from '@backstage/config-loader'; import { Logger } from 'winston'; import { LoggerService } from '@backstage/backend-plugin-api'; import { MergeResult } from 'isomorphic-git'; +import { CacheService as PluginCacheManager } from '@backstage/backend-plugin-api'; +import { DatabaseService as PluginDatabaseManager } from '@backstage/backend-plugin-api'; import { DiscoveryService as PluginEndpointDiscovery } from '@backstage/backend-plugin-api'; import { PushResult } from 'isomorphic-git'; import { Readable } from 'stream'; @@ -47,6 +51,7 @@ import { SearchOptions } from '@backstage/backend-plugin-api'; import { SearchResponse } from '@backstage/backend-plugin-api'; import { SearchResponseFile } from '@backstage/backend-plugin-api'; import { Server } from 'http'; +import { TokenManagerService as TokenManager } from '@backstage/backend-plugin-api'; import { TransportStreamOptions } from 'winston-transport'; import { UrlReaderService as UrlReader } from '@backstage/backend-plugin-api'; import { V1PodTemplateSpec } from '@kubernetes/client-node'; @@ -165,26 +170,11 @@ export class BitbucketUrlReader implements UrlReader { toString(): string; } -// @public -export interface CacheClient { - delete(key: string): Promise; - get(key: string): Promise; - set( - key: string, - value: JsonValue, - options?: CacheClientSetOptions, - ): Promise; -} +export { CacheClient }; -// @public -export type CacheClientOptions = { - defaultTtl?: number; -}; +export { CacheClientOptions }; -// @public -export type CacheClientSetOptions = { - ttl?: number; -}; +export { CacheClientSetOptions }; // @public export class CacheManager { @@ -526,18 +516,9 @@ export function loggerToWinstonLogger( // @public export function notFoundHandler(): RequestHandler; -// @public -export type PluginCacheManager = { - getClient: (options?: CacheClientOptions) => CacheClient; -}; +export { PluginCacheManager }; -// @public -export interface PluginDatabaseManager { - getClient(): Promise; - migrations?: { - skip?: boolean; - }; -} +export { PluginDatabaseManager }; export { PluginEndpointDiscovery }; @@ -718,13 +699,7 @@ export interface StatusCheckHandlerOptions { statusCheck?: StatusCheck; } -// @public -export interface TokenManager { - authenticate(token: string): Promise; - getToken(): Promise<{ - token: string; - }>; -} +export { TokenManager }; export { UrlReader }; diff --git a/packages/backend-common/src/cache/CacheClient.ts b/packages/backend-common/src/cache/CacheClient.ts index 96982edeaa..47cb786f14 100644 --- a/packages/backend-common/src/cache/CacheClient.ts +++ b/packages/backend-common/src/cache/CacheClient.ts @@ -14,57 +14,23 @@ * limitations under the License. */ +import { + CacheClient, + CacheClientSetOptions, +} from '@backstage/backend-plugin-api'; import { JsonValue } from '@backstage/types'; import { createHash } from 'crypto'; import Keyv from 'keyv'; +export type { + CacheClient, + CacheClientSetOptions, +} from '@backstage/backend-plugin-api'; + type CacheClientArgs = { client: Keyv; }; -/** - * Options passed to {@link CacheClient.set}. - * - * @public - */ -export 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; -}; - -/** - * A pre-configured, storage agnostic cache client suitable for use by - * Backstage plugins. - * - * @public - */ -export interface CacheClient { - /** - * Reads data from a cache store for the given key. If no data was found, - * returns undefined. - */ - get(key: string): Promise; - - /** - * 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; - - /** - * Removes the given key from the cache store. - */ - delete(key: string): Promise; -} - /** * A basic, concrete implementation of the CacheClient, suitable for almost * all uses in Backstage. diff --git a/packages/backend-common/src/cache/types.ts b/packages/backend-common/src/cache/types.ts index 5cf8323c52..40e30b1059 100644 --- a/packages/backend-common/src/cache/types.ts +++ b/packages/backend-common/src/cache/types.ts @@ -15,21 +15,11 @@ */ import { Logger } from 'winston'; -import { CacheClient } from './CacheClient'; -/** - * Options given when constructing a {@link CacheClient}. - * - * @public - */ -export 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; -}; +export type { + CacheService as PluginCacheManager, + CacheClientOptions, +} from '@backstage/backend-plugin-api'; /** * Options given when constructing a {@link CacheManager}. @@ -48,21 +38,3 @@ export type CacheManagerOptions = { */ onError?: (err: Error) => void; }; - -/** - * Manages access to cache stores that plugins get. - * - * @public - */ -export type PluginCacheManager = { - /** - * 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; -}; diff --git a/packages/backend-common/src/database/types.ts b/packages/backend-common/src/database/types.ts index 2fa8b749a8..2d59cf636e 100644 --- a/packages/backend-common/src/database/types.ts +++ b/packages/backend-common/src/database/types.ts @@ -17,32 +17,7 @@ import { Config } from '@backstage/config'; import { Knex } from 'knex'; -/** - * The PluginDatabaseManager manages access to databases that Plugins get. - * - * @public - */ -export interface PluginDatabaseManager { - /** - * 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; - - /** - * 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; - }; -} +export type { DatabaseService as PluginDatabaseManager } from '@backstage/backend-plugin-api'; /** * DatabaseConnector manages an underlying Knex database driver. diff --git a/packages/backend-common/src/tokens/types.ts b/packages/backend-common/src/tokens/types.ts index 2fa771b7e2..4e0fd698df 100644 --- a/packages/backend-common/src/tokens/types.ts +++ b/packages/backend-common/src/tokens/types.ts @@ -14,26 +14,4 @@ * limitations under the License. */ -/** - * Interface for creating and validating tokens. - * - * @public - */ -export interface TokenManager { - /** - * 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; -} +export type { TokenManagerService as TokenManager } from '@backstage/backend-plugin-api'; diff --git a/packages/backend-plugin-api/api-report.md b/packages/backend-plugin-api/api-report.md index 3ec60bde46..a829f6200c 100644 --- a/packages/backend-plugin-api/api-report.md +++ b/packages/backend-plugin-api/api-report.md @@ -7,12 +7,11 @@ import { Config } from '@backstage/config'; import { Handler } from 'express'; +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'; // @public (undocumented) export interface BackendFeature { @@ -63,8 +62,31 @@ export interface BackendRegistrationPoints { }): void; } -// @public (undocumented) -export interface CacheService extends PluginCacheManager {} +// @public +export interface CacheClient { + delete(key: string): Promise; + get(key: string): Promise; + set( + key: string, + value: JsonValue, + options?: CacheClientSetOptions, + ): Promise; +} + +// @public +export type CacheClientOptions = { + defaultTtl?: number; +}; + +// @public +export type CacheClientSetOptions = { + ttl?: number; +}; + +// @public +export interface CacheService { + getClient: (options?: CacheClientOptions) => CacheClient; +} // @public (undocumented) export interface ConfigService extends Config {} @@ -152,8 +174,13 @@ export function createServiceRef(options: { ) => Promise | (() => ServiceFactory)>; }): ServiceRef; -// @public (undocumented) -export interface DatabaseService extends PluginDatabaseManager {} +// @public +export interface DatabaseService { + getClient(): Promise; + migrations?: { + skip?: boolean; + }; +} // @public export interface DiscoveryService { @@ -329,8 +356,13 @@ export type ServiceRef< $$ref: 'service'; }; -// @public (undocumented) -export interface TokenManagerService extends TokenManager {} +// @public +export interface TokenManagerService { + authenticate(token: string): Promise; + getToken(): Promise<{ + token: string; + }>; +} // @public (undocumented) export type TypesToServiceRef = { diff --git a/packages/backend-plugin-api/package.json b/packages/backend-plugin-api/package.json index 0719ea8f45..dc484a33b0 100644 --- a/packages/backend-plugin-api/package.json +++ b/packages/backend-plugin-api/package.json @@ -33,12 +33,13 @@ "start": "backstage-cli package start" }, "dependencies": { - "@backstage/backend-common": "workspace:^", "@backstage/backend-tasks": "workspace:^", "@backstage/config": "workspace:^", "@backstage/plugin-permission-common": "workspace:^", + "@backstage/types": "workspace:^", "@types/express": "^4.17.6", - "express": "^4.17.1" + "express": "^4.17.1", + "knex": "^2.0.0" }, "devDependencies": { "@backstage/cli": "workspace:^" diff --git a/packages/backend-plugin-api/src/services/definitions/CacheService.ts b/packages/backend-plugin-api/src/services/definitions/CacheService.ts index 79c930f435..2702fdac6d 100644 --- a/packages/backend-plugin-api/src/services/definitions/CacheService.ts +++ b/packages/backend-plugin-api/src/services/definitions/CacheService.ts @@ -14,7 +14,79 @@ * limitations under the License. */ -import { PluginCacheManager } from '@backstage/backend-common'; +import { JsonValue } from '@backstage/types'; -/** @public */ -export interface CacheService extends PluginCacheManager {} +/** + * Manages access to cache stores that plugins get. + * + * @public + */ +export 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; +} + +/** + * Options passed to {@link CacheClient.set}. + * + * @public + */ +export 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; +}; + +/** + * A pre-configured, storage agnostic cache client suitable for use by + * Backstage plugins. + * + * @public + */ +export interface CacheClient { + /** + * Reads data from a cache store for the given key. If no data was found, + * returns undefined. + */ + get(key: string): Promise; + + /** + * 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; + + /** + * Removes the given key from the cache store. + */ + delete(key: string): Promise; +} + +/** + * Options given when constructing a {@link CacheClient}. + * + * @public + */ +export 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; +}; diff --git a/packages/backend-plugin-api/src/services/definitions/DatabaseService.ts b/packages/backend-plugin-api/src/services/definitions/DatabaseService.ts index 30f1f574f2..583dfe8b8f 100644 --- a/packages/backend-plugin-api/src/services/definitions/DatabaseService.ts +++ b/packages/backend-plugin-api/src/services/definitions/DatabaseService.ts @@ -14,7 +14,31 @@ * limitations under the License. */ -import { PluginDatabaseManager } from '@backstage/backend-common'; +import { Knex } from 'knex'; -/** @public */ -export interface DatabaseService extends PluginDatabaseManager {} +/** + * The DatabaseService manages access to databases that Plugins get. + *gs + * @public + */ +export 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; + + /** + * 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; + }; +} diff --git a/packages/backend-plugin-api/src/services/definitions/TokenManagerService.ts b/packages/backend-plugin-api/src/services/definitions/TokenManagerService.ts index 7fccb60c7a..c9d7edcaef 100644 --- a/packages/backend-plugin-api/src/services/definitions/TokenManagerService.ts +++ b/packages/backend-plugin-api/src/services/definitions/TokenManagerService.ts @@ -14,7 +14,26 @@ * limitations under the License. */ -import { TokenManager } from '@backstage/backend-common'; +/** + * Interface for creating and validating tokens. + * + * @public + */ +export 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 }>; -/** @public */ -export interface TokenManagerService extends TokenManager {} + /** + * Validates a given token. + */ + authenticate(token: string): Promise; +} diff --git a/packages/backend-plugin-api/src/services/definitions/index.ts b/packages/backend-plugin-api/src/services/definitions/index.ts index 82b16efda2..99b3cbd06d 100644 --- a/packages/backend-plugin-api/src/services/definitions/index.ts +++ b/packages/backend-plugin-api/src/services/definitions/index.ts @@ -15,7 +15,12 @@ */ export { coreServices } from './coreServices'; -export type { CacheService } from './CacheService'; +export type { + CacheService, + CacheClient, + CacheClientOptions, + CacheClientSetOptions, +} from './CacheService'; export type { ConfigService } from './ConfigService'; export type { DatabaseService } from './DatabaseService'; export type { DiscoveryService } from './DiscoveryService'; diff --git a/plugins/auth-backend/api-report.md b/plugins/auth-backend/api-report.md index cec3422d9c..88cb33863e 100644 --- a/plugins/auth-backend/api-report.md +++ b/plugins/auth-backend/api-report.md @@ -7,7 +7,7 @@ import { BackstageIdentityResponse } from '@backstage/plugin-auth-node'; import { BackstageSignInResult } from '@backstage/plugin-auth-node'; -import { CacheClient } from '@backstage/backend-common'; +import { CacheClient } from '@backstage/backend-plugin-api'; import { CatalogApi } from '@backstage/catalog-client'; import { Config } from '@backstage/config'; import { Entity } from '@backstage/catalog-model'; diff --git a/yarn.lock b/yarn.lock index 7ed5b1c798..f4f2e9a774 100644 --- a/yarn.lock +++ b/yarn.lock @@ -3492,13 +3492,14 @@ __metadata: version: 0.0.0-use.local resolution: "@backstage/backend-plugin-api@workspace:packages/backend-plugin-api" dependencies: - "@backstage/backend-common": "workspace:^" "@backstage/backend-tasks": "workspace:^" "@backstage/cli": "workspace:^" "@backstage/config": "workspace:^" "@backstage/plugin-permission-common": "workspace:^" + "@backstage/types": "workspace:^" "@types/express": ^4.17.6 express: ^4.17.1 + knex: ^2.0.0 languageName: unknown linkType: soft