From 5437fe488f363c654bfcd1626cfcf0175c541be3 Mon Sep 17 00:00:00 2001 From: Johan Haals Date: Wed, 4 Jan 2023 10:44:04 +0100 Subject: [PATCH] Migrate Cache and Database types into backend-plugin-api Signed-off-by: Johan Haals --- .changeset/nasty-pumas-kneel.md | 6 ++ packages/backend-app-api/api-report.md | 8 +- packages/backend-common/api-report.md | 40 +++------- .../backend-common/src/cache/CacheClient.ts | 52 +++---------- packages/backend-common/src/cache/types.ts | 36 +-------- packages/backend-common/src/database/types.ts | 27 +------ packages/backend-plugin-api/package.json | 4 +- .../src/services/definitions/CacheService.ts | 78 ++++++++++++++++++- .../services/definitions/DatabaseService.ts | 30 ++++++- .../src/services/definitions/index.ts | 7 +- plugins/auth-backend/api-report.md | 2 +- 11 files changed, 146 insertions(+), 144 deletions(-) create mode 100644 .changeset/nasty-pumas-kneel.md diff --git a/.changeset/nasty-pumas-kneel.md b/.changeset/nasty-pumas-kneel.md new file mode 100644 index 0000000000..3fcd46641e --- /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 `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 fa3f3bec2e..313c391bb3 100644 --- a/packages/backend-app-api/api-report.md +++ b/packages/backend-app-api/api-report.md @@ -4,14 +4,14 @@ ```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 { 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 { RootLifecycleService } from '@backstage/backend-plugin-api'; import { RootLoggerService } from '@backstage/backend-plugin-api'; @@ -34,7 +34,7 @@ export interface Backend { // @public (undocumented) export const cacheFactory: ( options?: undefined, -) => ServiceFactory; +) => ServiceFactory; // @public (undocumented) export const configFactory: ( @@ -55,7 +55,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..c8ddb807d8 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'; @@ -165,26 +169,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 +515,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 }; 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-plugin-api/package.json b/packages/backend-plugin-api/package.json index 0719ea8f45..9d92e5774a 100644 --- a/packages/backend-plugin-api/package.json +++ b/packages/backend-plugin-api/package.json @@ -36,9 +36,11 @@ "@backstage/backend-common": "workspace:^", "@backstage/backend-tasks": "workspace:^", "@backstage/config": "workspace:^", + "@backstage/types": "workspace:^", "@backstage/plugin-permission-common": "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/index.ts b/packages/backend-plugin-api/src/services/definitions/index.ts index dedfd6223e..cb4b5de3e7 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';