Migrate Cache and Database types into backend-plugin-api

Signed-off-by: Johan Haals <johan.haals@gmail.com>

.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.

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<CacheService>;
+) => ServiceFactory<PluginCacheManager>;
 
 // @public (undocumented)
 export const configFactory: (
@@ -55,7 +55,7 @@ export interface CreateSpecializedBackendOptions {
 // @public (undocumented)
 export const databaseFactory: (
   options?: undefined,
-) => ServiceFactory<DatabaseService>;
+) => ServiceFactory<PluginDatabaseManager>;
 
 // @public (undocumented)
 export const discoveryFactory: (

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<void>;
-  get(key: string): Promise<JsonValue | undefined>;
-  set(
-    key: string,
-    value: JsonValue,
-    options?: CacheClientSetOptions,
-  ): Promise<void>;
-}
+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<Knex>;
-  migrations?: {
-    skip?: boolean;
-  };
-}
+export { PluginDatabaseManager };
 
 export { PluginEndpointDiscovery };
 

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<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>;
-}
-
 /**
  * A basic, concrete implementation of the CacheClient, suitable for almost
  * all uses in Backstage.

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;
-};

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<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;
-  };
-}
+export type { DatabaseService as PluginDatabaseManager } from '@backstage/backend-plugin-api';
 
 /**
  * DatabaseConnector manages an underlying Knex database driver.

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:^"

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<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 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;
+};

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<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;
+  };
+}

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';

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';