Merge pull request #15545 from backstage/jhaals/dbcache

Migrate Cache and Database types into backend-plugin-api

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<void>;
+  get(key: string): Promise<JsonValue | undefined>;
+  set(
+    key: string,
+    value: JsonValue,
+    options?: CacheClientSetOptions,
+  ): Promise<void>;
+}
+
+// @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<T>(options: {
   ) => Promise<ServiceFactory<T> | (() => ServiceFactory<T>)>;
 }): ServiceRef<T, 'root'>;
 
-// @public (undocumented)
-export interface DatabaseService extends PluginDatabaseManager {}
+// @public
+export interface DatabaseService {
+  getClient(): Promise<Knex>;
+  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<void>;
+  getToken(): Promise<{
+    token: string;
+  }>;
+}
 
 // @public (undocumented)
 export type TypesToServiceRef<T> = {

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

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

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