Merge pull request #15545 from backstage/jhaals/dbcache

Migrate Cache and Database types into backend-plugin-api

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