OdspDriver: Move IPersistedCache types to driver-definitions (#25518)

In an effort to decouple the driver web cache from the odsp driver a
number of types have been moved from
`@fluidframework/odsp-driver-definitions` to
`@fluidframework/driver-definitions`. The moved types have been
deprecated in `@fluidframework/odsp-driver-definitions`, and any usages
should be moved to `@fluidframework/driver-definitions`.

The moved type are:
 - `IEntry`
 - `IFileEntry`
 - `ICacheEntry`
 - `IPersistedCache`

---------

Co-authored-by: jzaffiro <110866475+jzaffiro@users.noreply.github.com>

Author: anthony-murphy

.changeset/stupid-ties-raise.md

@@ -0,0 +1,16 @@
+---
+"@fluidframework/driver-definitions": minor
+"@fluidframework/driver-web-cache": minor
+"@fluidframework/odsp-driver": minor
+"@fluidframework/odsp-driver-definitions": minor
+"__section": deprecation
+---
+Move IPersistedCache types to driver-definitions
+
+In an effort to decouple the driver web cache from the odsp driver a number of types have been moved from `@fluidframework/odsp-driver-definitions` to `@fluidframework/driver-definitions`. The moved types have been deprecated in `@fluidframework/odsp-driver-definitions`, and any usages should be moved to  `@fluidframework/driver-definitions`.
+
+The moved types are:
+ - `IEntry`
+ - `IFileEntry`
+ - `ICacheEntry`
+ - `IPersistedCache`

examples/benchmarks/odspsnapshotfetch-perftestapp/package.json

@@ -35,9 +35,10 @@
 	},
 	"dependencies": {
 		"@fluidframework/core-utils": "workspace:~",
+		"@fluidframework/driver-definitions": "workspace:~",
+		"@fluidframework/driver-utils": "workspace:~",
 		"@fluidframework/odsp-doclib-utils": "workspace:~",
 		"@fluidframework/odsp-driver": "workspace:~",
-		"@fluidframework/odsp-driver-definitions": "workspace:~",
 		"@fluidframework/odsp-urlresolver": "workspace:~",
 		"@fluidframework/telemetry-utils": "workspace:~",
 		"@fluidframework/tool-utils": "workspace:~",

examples/benchmarks/odspsnapshotfetch-perftestapp/src/odspPersistantCache.ts

@@ -3,12 +3,12 @@
  * Licensed under the MIT License.
  */
 
-import {
+import type {
 	ICacheEntry,
 	IFileEntry,
 	IPersistedCache,
-	getKeyForCacheEntry,
-} from "@fluidframework/odsp-driver-definitions/internal";
+} from "@fluidframework/driver-definitions/internal";
+import { getKeyForCacheEntry } from "@fluidframework/driver-utils/internal";
 
 export class OdspSampleCache implements IPersistedCache {
 	private readonly cache = new Map<string, any>();

examples/utils/webpack-fluid-loader/src/getDocumentServiceFactory.ts

@@ -4,16 +4,16 @@
  */
 
 import { assert } from "@fluidframework/core-utils/internal";
-import { IDocumentServiceFactory } from "@fluidframework/driver-definitions/internal";
+import {
+	IDocumentServiceFactory,
+	type IPersistedCache,
+} from "@fluidframework/driver-definitions/internal";
 import {
 	LocalDocumentServiceFactory,
 	LocalSessionStorageDbFactory,
 } from "@fluidframework/local-driver/internal";
 import { OdspDocumentServiceFactory } from "@fluidframework/odsp-driver/internal";
-import {
-	HostStoragePolicy,
-	IPersistedCache,
-} from "@fluidframework/odsp-driver-definitions/internal";
+import { HostStoragePolicy } from "@fluidframework/odsp-driver-definitions/internal";
 import { RouterliciousDocumentServiceFactory } from "@fluidframework/routerlicious-driver/internal";
 import { LocalDeltaConnectionServer } from "@fluidframework/server-local-server";
 import { InsecureTokenProvider } from "@fluidframework/test-runtime-utils/internal";

examples/utils/webpack-fluid-loader/src/loader.ts

@@ -23,17 +23,15 @@ import { IUser } from "@fluidframework/driver-definitions";
 import {
 	IDocumentServiceFactory,
 	IResolvedUrl,
+	type IPersistedCache,
 } from "@fluidframework/driver-definitions/internal";
 import { InsecureUrlResolver } from "@fluidframework/driver-utils/internal";
 import {
 	LocalDocumentServiceFactory,
 	LocalResolver,
 } from "@fluidframework/local-driver/internal";
 import { prefetchLatestSnapshot } from "@fluidframework/odsp-driver/internal";
-import {
-	HostStoragePolicy,
-	IPersistedCache,
-} from "@fluidframework/odsp-driver-definitions/internal";
+import { HostStoragePolicy } from "@fluidframework/odsp-driver-definitions/internal";
 import { RequestParser } from "@fluidframework/runtime-utils/internal";
 import { createChildLogger } from "@fluidframework/telemetry-utils/internal";
 import sillyname from "sillyname";

examples/utils/webpack-fluid-loader/src/odspPersistantCache.ts

@@ -7,8 +7,8 @@ import {
 	ICacheEntry,
 	IFileEntry,
 	IPersistedCache,
-	getKeyForCacheEntry,
-} from "@fluidframework/odsp-driver-definitions/internal";
+} from "@fluidframework/driver-definitions/internal";
+import { getKeyForCacheEntry } from "@fluidframework/driver-utils/internal";
 
 export class OdspPersistentCache implements IPersistedCache {
 	private readonly cache = new Map<string, any>();

packages/common/driver-definitions/api-report/driver-definitions.legacy.beta.api.md

@@ -113,6 +113,11 @@ export interface IBranchOrigin {
     sequenceNumber: number;
 }
 
+// @beta @legacy
+export interface ICacheEntry extends IEntry {
+    file: IFileEntry;
+}
+
 // @public
 export interface ICapabilities {
     interactive: boolean;
@@ -319,6 +324,19 @@ export interface IDriverErrorBase {
     online?: string;
 }
 
+// @beta @legacy
+export interface IEntry {
+    key: string;
+    type: string;
+}
+
+// @beta @legacy
+export interface IFileEntry {
+    docId: string;
+    fileVersion?: string;
+    resolvedUrl: IResolvedUrl;
+}
+
 // @beta @legacy (undocumented)
 export interface IGenericNetworkError extends IDriverErrorBase {
     // (undocumented)
@@ -350,6 +368,13 @@ export interface INackContent {
     type: NackErrorType;
 }
 
+// @beta @legacy
+export interface IPersistedCache {
+    get(entry: ICacheEntry): Promise<unknown>;
+    put(entry: ICacheEntry, value: unknown): Promise<void>;
+    removeEntries(file: IFileEntry): Promise<void>;
+}
+
 // @beta @legacy (undocumented)
 export interface IProcessMessageResult {
     // (undocumented)

packages/common/driver-definitions/src/cacheDefinitions.ts

@@ -0,0 +1,97 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { IResolvedUrl } from "./urlResolver.js";
+
+/**
+ * File / container identifier.
+ * There is overlapping information here - host can use all of it or parts
+ * to implement storage / identify files.
+ * @legacy @beta
+ */
+export interface IFileEntry {
+	/**
+	 * Unique and stable ID of the document.
+	 * Driver guarantees that docId is stable ID uniquely identifying document.
+	 */
+	docId: string;
+	/**
+	 * Resolved URI is provided for additional versatility - host can use it to
+	 * identify file in storage, and (as example) delete all cached entries for
+	 * a file if user requests so.
+	 * This is IOdspResolvedUrl in case of ODSP driver.
+	 */
+	resolvedUrl: IResolvedUrl;
+
+	/**
+	 * Optional version of the file.
+	 */
+	fileVersion?: string;
+}
+
+/**
+ * Cache entry. Identifies file that this entry belongs to, and type of content stored in it.
+ * @legacy @beta
+ */
+export interface IEntry {
+	/**
+	 * Identifies type of entry for a given file.
+	 * Each file can have multiple types of entries associated with it.
+	 * For example, it can be snapshot, blob, ops, etc.
+	 */
+	type: string;
+
+	/**
+	 * Identifies individual entry for a given file and type.
+	 * Each file can have multiple cache entries associated with it.
+	 * This property identifies a particular instance of entry.
+	 * For example, for blobs it will be unique ID of the blob in a file.
+	 * For batch of ops, it can be starting op sequence number.
+	 * For types that have only one entry (like snapshots), it will be empty string.
+	 */
+	key: string;
+}
+
+/**
+ * Cache entry. Identifies file that this entry belongs to, and type of content stored in it.
+ * @legacy @beta
+ */
+export interface ICacheEntry extends IEntry {
+	/**
+	 * Identifies file in storage this cached entry is for
+	 */
+	file: IFileEntry;
+}
+
+/**
+ * Persistent cache. This interface can be implemented by the host to provide durable caching
+ * across sessions. If not provided at driver factory construction, factory will use in-memory
+ * cache implementation that does not survive across sessions. Snapshot entires stored in the
+ * IPersistedCache will be considered stale and removed after 2 days. Read the README for more
+ * information.
+ * @legacy @beta
+ */
+export interface IPersistedCache {
+	/**
+	 * Get the cache value of the key
+	 * @param entry - cache entry, identifies file and particular key for this file.
+	 * @returns Cached value. undefined if nothing is cached.
+	 */
+	get(entry: ICacheEntry): Promise<unknown>;
+
+	/**
+	 * Put the value into cache.
+	 * Important - only serializable content is allowed since this cache may be persisted between sessions
+	 * @param entry - cache entry.
+	 * @param value - JSON-serializable content.
+	 */
+	put(entry: ICacheEntry, value: unknown): Promise<void>;
+
+	/**
+	 * Removes the entries from the cache for given parameters.
+	 * @param file - file entry to be deleted.
+	 */
+	removeEntries(file: IFileEntry): Promise<void>;
+}

packages/common/driver-definitions/src/index.ts

@@ -3,6 +3,13 @@
  * Licensed under the MIT License.
  */
 
+export type {
+	ICacheEntry,
+	IEntry,
+	IFileEntry,
+	IPersistedCache,
+} from "./cacheDefinitions.js";
+
 export type {
 	DriverError,
 	IAnyDriverError,

packages/drivers/driver-web-cache/package.json

@@ -91,7 +91,8 @@
 	"dependencies": {
 		"@fluidframework/core-interfaces": "workspace:~",
 		"@fluidframework/core-utils": "workspace:~",
-		"@fluidframework/odsp-driver-definitions": "workspace:~",
+		"@fluidframework/driver-definitions": "workspace:~",
+		"@fluidframework/driver-utils": "workspace:~",
 		"@fluidframework/telemetry-utils": "workspace:~",
 		"idb": "^6.1.2"
 	},