@fluidframework/odsp-driver-definitions 2.0.0-internal.3.0.2 → 2.0.0-internal.3.2.0

package/src/factory.ts

@@ -4,141 +4,147 @@
  */
 
 export interface ISnapshotOptions {
-    blobs?: number;
-    deltas?: number;
-    channels?: number;
-    /*
-     * Maximum Data size (in bytes)
-     * If specified, SPO will fail snapshot request with 413 error (see OdspErrorType.snapshotTooBig)
-     * if snapshot is bigger in size than specified limit.
-     */
-    mds?: number;
-
-    /*
-     * Maximum time limit to fetch snapshot (in seconds)
-     * If specified, client will timeout the fetch request if it exceeds the time limit and
-     * will try to fetch the snapshot without blobs.
-     */
-    timeout?: number;
+	blobs?: number;
+	deltas?: number;
+	channels?: number;
+	/*
+	 * Maximum Data size (in bytes)
+	 * If specified, SPO will fail snapshot request with 413 error (see OdspErrorType.snapshotTooBig)
+	 * if snapshot is bigger in size than specified limit.
+	 */
+	mds?: number;
+
+	/*
+	 * Maximum time limit to fetch snapshot (in seconds)
+	 * If specified, client will timeout the fetch request if it exceeds the time limit and
+	 * will try to fetch the snapshot without blobs.
+	 */
+	timeout?: number;
 }
 
 export interface IOpsCachingPolicy {
-    /**
-     * Batch size. Controls how many ops are grouped together as single cache entry
-     * The bigger the number, the more efficient it is (less reads & writes)
-     * At the same time, big number means we wait for so many ops to accumulate, which
-     * increases chances and number of trailing ops that would not be flushed to cache
-     * when user closes tab
-     * Use any number below 1 to disable caching
-     * Default: 100
-     */
-    batchSize?: number;
-
-    /**
-     * To reduce the problem of losing trailing ops when using big batch sizes, host
-     * could specify how often driver should flush ops it has not flushed yet.
-     * -1 means do not use timer.
-     * Measured in ms.
-     * Default: 5000
-     */
-    timerGranularity?: number;
-
-    /**
-     * Total number of ops to cache. When we reach that number, ops caching stops
-     * Default: 5000
-     */
-    totalOpsToCache?: number;
+	/**
+	 * Batch size. Controls how many ops are grouped together as single cache entry
+	 * The bigger the number, the more efficient it is (less reads & writes)
+	 * At the same time, big number means we wait for so many ops to accumulate, which
+	 * increases chances and number of trailing ops that would not be flushed to cache
+	 * when user closes tab
+	 * Use any number below 1 to disable caching
+	 * Default: 100
+	 */
+	batchSize?: number;
+
+	/**
+	 * To reduce the problem of losing trailing ops when using big batch sizes, host
+	 * could specify how often driver should flush ops it has not flushed yet.
+	 * -1 means do not use timer.
+	 * Measured in ms.
+	 * Default: 5000
+	 */
+	timerGranularity?: number;
+
+	/**
+	 * Total number of ops to cache. When we reach that number, ops caching stops
+	 * Default: 5000
+	 */
+	totalOpsToCache?: number;
 }
 
 export interface ICollabSessionOptions {
-    /**
-     * Value indicating the display name for session that admits unauthenticated user.
-     * This name will be used in attribution associated with edits made by such user.
-     */
-    unauthenticatedUserDisplayName?: string;
-    /**
-     * @deprecated Due to security reasons we will be passing the token via Authorization header only.
-     * Value indicating session preference to always pass access token via Authorization header.
-     * Default behavior is to pass access token via query parameter unless overall href string
-     * length exceeds 2048 characters. Using query param is performance optimization which results
-     * in ODSP XHR request being treated as 'simple' request which do not require OPTIONS call to
-     * validate CORS. However, not all ODSP implementations understand this optimization.
-     * For instance, auth layer on Converged stack will fail request with access token passed via
-     * query param.
-     */
-    forceAccessTokenViaAuthorizationHeader?: boolean;
+	/**
+	 * Value indicating the display name for session that admits unauthenticated user.
+	 * This name will be used in attribution associated with edits made by such user.
+	 */
+	unauthenticatedUserDisplayName?: string;
+	/**
+	 * @deprecated Due to security reasons we will be passing the token via Authorization header only.
+	 * Value indicating session preference to always pass access token via Authorization header.
+	 * Default behavior is to pass access token via query parameter unless overall href string
+	 * length exceeds 2048 characters. Using query param is performance optimization which results
+	 * in ODSP XHR request being treated as 'simple' request which do not require OPTIONS call to
+	 * validate CORS. However, not all ODSP implementations understand this optimization.
+	 * For instance, auth layer on Converged stack will fail request with access token passed via
+	 * query param.
+	 */
+	forceAccessTokenViaAuthorizationHeader?: boolean;
 }
 
 export interface HostStoragePolicy {
-    snapshotOptions?: ISnapshotOptions;
-
-    /**
-     * If set to true, tells driver to concurrently fetch snapshot from storage (SPO) and cache
-     * Container loads from whatever comes first in such case.
-     * Snapshot fetched from storage is pushed to cache in either case.
-     * If set to false, driver will first consult with cache. Only on cache miss (cache does not
-     * return snapshot), driver will fetch snapshot from storage (and push it to cache), otherwise
-     * it will load from cache and not reach out to storage.
-     * Passing true results in faster loads and keeping cache more current, but it increases bandwidth consumption.
-     */
-    concurrentSnapshotFetch?: boolean;
-
-    // Options overwriting default ops fetching from storage.
-    opsBatchSize?: number;
-    concurrentOpsBatches?: number;
-
-    /**
-     * Policy controlling ops caching (leveraging IPersistedCache passed to driver factory)
-     */
-    opsCaching?: IOpsCachingPolicy;
-
-    /**
-     * Policy controlling how collaboration session is established
-     */
-    sessionOptions?: ICollabSessionOptions;
-
-    /**
-     * @deprecated This field will be always set to true after removal.
-     * True to have the sharing link redeem fallback in case the Trees Latest/Redeem 1RT call fails with redeem error.
-     * During fallback it will first redeem the sharing link and then make the Trees latest call.
-     */
-    enableRedeemFallback?: boolean;
-
-    /**
-     * Policy controlling if we will cache initial summary when we create a document
-     */
-    cacheCreateNewSummary?: boolean;
-
-    /**
-     * @deprecated This will be replaced with feature gate snapshotFormatFetchType.
-     * Policy controlling if we want to fetch binary format snapshot.
-     */
-    fetchBinarySnapshotFormat?: boolean;
-
-    /**
-     * If set to true, socket cache are per OdspDocumentService instead of shared across all instances
-     */
-    isolateSocketCache?: boolean;
-
-    /**
-     * @deprecated Switch to using the new feature gated by enableSingleRequestForShareLinkWithCreate
-     * with 'createLinkScope' and 'createLinkRole' is requested to the odsp apis instead of 'createLinkType'.
-     * It enables the creation of sharing link along with the creation of file by setting this value to true.
-     * If the host provides a 'createLinkType' parameter in the request URL to the container.attach()
-     * method, we will send the request to ODSP with the same (if the flag is enabled) so
-     * that a share link can be created with the creation of file to save number for round trips made to ODSP.
-     * (This flag works independently of enableSingleRequestForShareLinkWithCreate which is used for sharing link
-     * requests where 'createLinkScope' is requested.)
-     */
-     enableShareLinkWithCreate?: boolean;
-
-    /**
-     * Enable creation of sharing link along with the creation of file by setting this value to true.
-     * If the host provides a 'createLinkScope' parameter in the request URL to the container.attach()
-     * method, we will send the request to ODSP with the same (if the flag is enabled) so
-     * that a share link can be created with the creation of file to save number for round trips made to ODSP.
-     * (This flag works independently of enableShareLinkWithCreate which was used for old sharing link requests
-     * where 'createLinkType' was requested.)
-     */
-    enableSingleRequestForShareLinkWithCreate?: boolean;
+	snapshotOptions?: ISnapshotOptions;
+
+	/**
+	 * If set to true, tells driver to concurrently fetch snapshot from storage (SPO) and cache
+	 * Container loads from whatever comes first in such case.
+	 * Snapshot fetched from storage is pushed to cache in either case.
+	 * If set to false, driver will first consult with cache. Only on cache miss (cache does not
+	 * return snapshot), driver will fetch snapshot from storage (and push it to cache), otherwise
+	 * it will load from cache and not reach out to storage.
+	 * Passing true results in faster loads and keeping cache more current, but it increases bandwidth consumption.
+	 */
+	concurrentSnapshotFetch?: boolean;
+
+	// Options overwriting default ops fetching from storage.
+	opsBatchSize?: number;
+	concurrentOpsBatches?: number;
+
+	/**
+	 * Policy controlling ops caching (leveraging IPersistedCache passed to driver factory)
+	 */
+	opsCaching?: IOpsCachingPolicy;
+
+	/**
+	 * Policy controlling how collaboration session is established
+	 */
+	sessionOptions?: ICollabSessionOptions;
+
+	/**
+	 * @deprecated This field will be always set to true after removal.
+	 * True to have the sharing link redeem fallback in case the Trees Latest/Redeem 1RT call fails with redeem error.
+	 * During fallback it will first redeem the sharing link and then make the Trees latest call.
+	 */
+	enableRedeemFallback?: boolean;
+
+	/**
+	 * Policy controlling if we will cache initial summary when we create a document
+	 */
+	cacheCreateNewSummary?: boolean;
+
+	/**
+	 * @deprecated This will be replaced with feature gate snapshotFormatFetchType.
+	 * Policy controlling if we want to fetch binary format snapshot.
+	 */
+	fetchBinarySnapshotFormat?: boolean;
+
+	/**
+	 * If set to true, socket cache are per OdspDocumentService instead of shared across all instances
+	 */
+	isolateSocketCache?: boolean;
+
+	/**
+	 * @deprecated Switch to using the new feature gated by enableSingleRequestForShareLinkWithCreate
+	 * with 'createLinkScope' and 'createLinkRole' is requested to the odsp apis instead of 'createLinkType'.
+	 * It enables the creation of sharing link along with the creation of file by setting this value to true.
+	 * If the host provides a 'createLinkType' parameter in the request URL to the container.attach()
+	 * method, we will send the request to ODSP with the same (if the flag is enabled) so
+	 * that a share link can be created with the creation of file to save number for round trips made to ODSP.
+	 * (This flag works independently of enableSingleRequestForShareLinkWithCreate which is used for sharing link
+	 * requests where 'createLinkScope' is requested.)
+	 */
+	enableShareLinkWithCreate?: boolean;
+
+	/**
+	 * Enable creation of sharing link along with the creation of file by setting this value to true.
+	 * If the host provides a 'createLinkScope' parameter in the request URL to the container.attach()
+	 * method, we will send the request to ODSP with the same (if the flag is enabled) so
+	 * that a share link can be created with the creation of file to save number for round trips made to ODSP.
+	 * (This flag works independently of enableShareLinkWithCreate which was used for old sharing link requests
+	 * where 'createLinkType' was requested.)
+	 */
+	enableSingleRequestForShareLinkWithCreate?: boolean;
+
+	/**
+	 * True if host does not want the storage service to use the prefetch cache to get the snapshot. Undefined will be treated
+	 * as false. This is if the host wants to do some A/B testing.
+	 */
+	avoidPrefetchSnapshotCache?: boolean;
 }

package/src/index.ts

@@ -4,8 +4,21 @@
  */
 
 export { IOdspError, IOdspErrorAugmentations, OdspError, OdspErrorType } from "./errors";
-export { HostStoragePolicy, ICollabSessionOptions, IOpsCachingPolicy, ISnapshotOptions } from "./factory";
-export { CacheContentType, ICacheEntry, IEntry, IFileEntry, IPersistedCache, snapshotKey } from "./odspCache";
+export {
+	HostStoragePolicy,
+	ICollabSessionOptions,
+	IOpsCachingPolicy,
+	ISnapshotOptions,
+} from "./factory";
+export {
+	CacheContentType,
+	getKeyForCacheEntry,
+	ICacheEntry,
+	IEntry,
+	IFileEntry,
+	IPersistedCache,
+	snapshotKey,
+} from "./odspCache";
 export {
 	IOdspResolvedUrl,
 	IOdspUrlParts,

package/src/odspCache.ts

@@ -17,50 +17,50 @@ export type CacheContentType = "snapshot" | "ops";
  * to implement storage / identify files.
  */
 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: IFluidResolvedUrl;
+	/**
+	 * 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: IFluidResolvedUrl;
 }
 
 /**
  * Cache entry. Identifies file that this entry belongs to, and type of content stored in it.
  */
- 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: CacheContentType;
+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: CacheContentType;
 
-    /**
-     * 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;
+	/**
+	 * 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.
  */
 export interface ICacheEntry extends IEntry {
-    /**
-     * Identifies file in storage this cached entry is for
-     */
-    file: IFileEntry;
+	/**
+	 * Identifies file in storage this cached entry is for
+	 */
+	file: IFileEntry;
 }
 
 /**
@@ -71,24 +71,33 @@ export interface ICacheEntry extends IEntry {
  * information.
  */
 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<any>;
+	/**
+	 * 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<any>;
 
-    /**
-     * 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: any): Promise<void>;
+	/**
+	 * 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: any): Promise<void>;
 
-    /**
-     * Removes the entries from the cache for given parametres.
-     * @param file - file entry to be deleted.
-     */
-    removeEntries(file: IFileEntry): Promise<void>;
+	/**
+	 * Removes the entries from the cache for given parametres.
+	 * @param file - file entry to be deleted.
+	 */
+	removeEntries(file: IFileEntry): Promise<void>;
+}
+
+/**
+ * Api to generate a cache key from cache entry.
+ * @param entry - cache entry from which a cache key is generated
+ * @returns - key for cache.
+ */
+export function getKeyForCacheEntry(entry: ICacheEntry): string {
+	return `${entry.file.docId}_${entry.type}_${entry.key}`;
 }

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/odsp-driver-definitions";
-export const pkgVersion = "2.0.0-internal.3.0.2";
+export const pkgVersion = "2.0.0-internal.3.2.0";