@fluidframework/driver-definitions 2.0.0-dev-rc.1.0.0.228517 → 2.0.0-dev-rc.1.0.0.232845

package/src/driverError.ts

@@ -110,124 +110,15 @@ export const DriverErrorTypes = {
  */
 export type DriverErrorTypes = (typeof DriverErrorTypes)[keyof typeof DriverErrorTypes];
 
-/**
- * Driver Error types
- * Lists types that are likely to be used by all drivers
- *
- * @deprecated Use {@link (DriverErrorTypes:type)} instead.
- * @public
- */
-export enum DriverErrorType {
-	/**
-	 * A fatal error with no specific interpretation covered by other DriverErrorType values
-	 */
-	genericError = "genericError",
-
-	/**
-	 * Some non-categorized (below) networking error
-	 * Include errors like  fatal server error (usually 500).
-	 */
-	genericNetworkError = "genericNetworkError",
-
-	/**
-	 * Access denied - user does not have enough privileges to open a file, or continue to operate on a file
-	 */
-	authorizationError = "authorizationError",
-
-	/**
-	 * File not found, or file deleted during session
-	 */
-	fileNotFoundOrAccessDeniedError = "fileNotFoundOrAccessDeniedError",
-
-	/**
-	 * Throttling error from server. Server is busy and is asking not to reconnect for some time
-	 */
-	throttlingError = "throttlingError",
-
-	/**
-	 * We can not reach server due to computer being offline.
-	 */
-	offlineError = "offlineError",
-
-	/*
-	 * Unsupported client protocol
-	 */
-	unsupportedClientProtocolVersion = "unsupportedClientProtocolVersion",
-
-	/**
-	 * User does not have write permissions to a file, but is changing content of a file.
-	 * That might be indication of some data store error - data stores should not generate ops in readonly mode.
-	 */
-	writeError = "writeError",
-
-	/**
-	 * A generic fetch failure that indicates we were not able to get a response from the server.
-	 * This may be due to the client being offline (though, if we are able to detect offline state it will be
-	 * logged as an offlineError instead).  Other possibilities could be DNS errors, malformed fetch request,
-	 * CSP violation, etc.
-	 */
-	fetchFailure = "fetchFailure",
-
-	/**
-	 * This error occurs when token provider fails to fetch orderer token
-	 */
-	fetchTokenError = "fetchTokenError",
-
-	/**
-	 * Unexpected response from server. Either JSON is malformed, or some required properties are missing
-	 */
-	incorrectServerResponse = "incorrectServerResponse",
-
-	/**
-	 * This error occurs when the file is modified externally (not through Fluid protocol) in storage.
-	 * It will occur in cases where client has some state or cache that is based on old content (identity) of a file,
-	 * and storage / driver / loader detects such mismatch.
-	 * When it's hit, client needs to forget all the knowledge about this file and start over.
-	 */
-	fileOverwrittenInStorage = "fileOverwrittenInStorage",
-
-	/**
-	 * The document is read-only and delta stream connection is forbidden.
-	 */
-	deltaStreamConnectionForbidden = "deltaStreamConnectionForbidden",
-
-	/**
-	 * The location of file/container can change on server. So if the file location moves and we try to access the old
-	 * location, then this error is thrown to let the client know about the new location info.
-	 */
-	locationRedirection = "locationRedirection",
-
-	/**
-	 * When a file is not a Fluid file, but has Fluid extension such as ".note",
-	 * server won't be able to open it and will return this error. The innerMostErrorCode will be
-	 * "fluidInvalidSchema"
-	 */
-	fluidInvalidSchema = "fluidInvalidSchema",
-
-	/**
-	 * Error indicating an API is being used improperly resulting in an invalid operation.
-	 * ! Should match the value of ContainerErrorType.usageError
-	 */
-	usageError = "usageError",
-
-	/**
-	 * File is locked for read/write by storage, e.g. whole collection is locked and access denied.
-	 */
-	fileIsLocked = "fileIsLocked",
-
-	/**
-	 * Storage is out of space
-	 */
-	outOfStorageError = "outOfStorageError",
-}
-
 /**
  * Interface describing errors and warnings raised by any driver code.
+ *
+ * @remarks
  * Not expected to be implemented by a class or an object literal, but rather used in place of
  * any or unknown in various function signatures that pass errors around.
  *
  * "Any" in the interface name is a nod to the fact that errorType has lost its type constraint.
- * It will be either DriverErrorType or the specific driver's specialized error type enum,
+ * It will be either {@link @fluidframework/driver-definitions#(DriverErrorTypes:variable)} or the specific driver's specialized error type enum,
  * but we can't reference a specific driver's error type enum in this code.
  * @public
  */
@@ -245,7 +136,7 @@ export interface IDriverErrorBase {
 	 *
 	 * @privateRemarks TODO: use {@link DriverErrorTypes} instead (breaking change).
 	 */
-	readonly errorType: DriverErrorType;
+	readonly errorType: DriverErrorTypes;
 
 	/**
 	 * Free-form error message
@@ -273,7 +164,7 @@ export interface IDriverErrorBase {
  * @alpha
  */
 export interface IThrottlingWarning extends IDriverErrorBase {
-	readonly errorType: DriverErrorType.throttlingError;
+	readonly errorType: typeof DriverErrorTypes.throttlingError;
 	readonly retryAfterSeconds: number;
 }
 
@@ -281,7 +172,7 @@ export interface IThrottlingWarning extends IDriverErrorBase {
  * @alpha
  */
 export interface IGenericNetworkError extends IDriverErrorBase {
-	readonly errorType: DriverErrorType.genericNetworkError;
+	readonly errorType: typeof DriverErrorTypes.genericNetworkError;
 	readonly statusCode?: number;
 }
 
@@ -289,7 +180,7 @@ export interface IGenericNetworkError extends IDriverErrorBase {
  * @alpha
  */
 export interface IAuthorizationError extends IDriverErrorBase {
-	readonly errorType: DriverErrorType.authorizationError;
+	readonly errorType: typeof DriverErrorTypes.authorizationError;
 	readonly claims?: string;
 	readonly tenantId?: string;
 }
@@ -298,7 +189,7 @@ export interface IAuthorizationError extends IDriverErrorBase {
  * @alpha
  */
 export interface ILocationRedirectionError extends IDriverErrorBase {
-	readonly errorType: DriverErrorType.locationRedirection;
+	readonly errorType: typeof DriverErrorTypes.locationRedirection;
 	readonly redirectUrl: IResolvedUrl;
 }
 
@@ -309,19 +200,19 @@ export interface ILocationRedirectionError extends IDriverErrorBase {
  */
 export interface IDriverBasicError extends IDriverErrorBase {
 	readonly errorType:
-		| DriverErrorType.genericError
-		| DriverErrorType.fileNotFoundOrAccessDeniedError
-		| DriverErrorType.offlineError
-		| DriverErrorType.unsupportedClientProtocolVersion
-		| DriverErrorType.writeError
-		| DriverErrorType.fetchFailure
-		| DriverErrorType.fetchTokenError
-		| DriverErrorType.incorrectServerResponse
-		| DriverErrorType.fileOverwrittenInStorage
-		| DriverErrorType.fluidInvalidSchema
-		| DriverErrorType.usageError
-		| DriverErrorType.fileIsLocked
-		| DriverErrorType.outOfStorageError;
+		| typeof DriverErrorTypes.genericError
+		| typeof DriverErrorTypes.fileNotFoundOrAccessDeniedError
+		| typeof DriverErrorTypes.offlineError
+		| typeof DriverErrorTypes.unsupportedClientProtocolVersion
+		| typeof DriverErrorTypes.writeError
+		| typeof DriverErrorTypes.fetchFailure
+		| typeof DriverErrorTypes.fetchTokenError
+		| typeof DriverErrorTypes.incorrectServerResponse
+		| typeof DriverErrorTypes.fileOverwrittenInStorage
+		| typeof DriverErrorTypes.fluidInvalidSchema
+		| typeof DriverErrorTypes.usageError
+		| typeof DriverErrorTypes.fileIsLocked
+		| typeof DriverErrorTypes.outOfStorageError;
 	readonly statusCode?: number;
 }
 

package/src/index.ts

@@ -5,7 +5,6 @@
 
 export {
 	DriverError,
-	DriverErrorType,
 	DriverErrorTypes,
 	IAnyDriverError,
 	IAuthorizationError,
@@ -24,10 +23,13 @@ export {
 	IDocumentDeltaConnectionEvents,
 	IDocumentDeltaStorageService,
 	IDocumentService,
+	IDocumentServiceEvents,
 	IDocumentServiceFactory,
 	IDocumentServicePolicies,
 	IDocumentStorageService,
 	IDocumentStorageServicePolicies,
+	ISnapshot,
+	ISnapshotFetchOptions,
 	IStream,
 	IStreamResult,
 	ISummaryContext,

package/src/storage.ts

@@ -8,6 +8,7 @@ import {
 	IEventProvider,
 	IErrorEvent,
 	ITelemetryBaseLogger,
+	IEvent,
 } from "@fluidframework/core-interfaces";
 import {
 	ConnectionMode,
@@ -160,6 +161,14 @@ export interface IDocumentStorageService extends Partial<IDisposable> {
 	// eslint-disable-next-line @rushstack/no-new-null
 	getSnapshotTree(version?: IVersion, scenarioName?: string): Promise<ISnapshotTree | null>;
 
+	/**
+	 * Returns the snapshot which can contain other artifacts too like blob contents, ops etc. It is different from
+	 * `getSnapshotTree` api in that, that API only returns the snapshot tree from the snapshot.
+	 * @param snapshotFetchOptions - Options specified by the caller to specify and want certain behavior from the
+	 * driver when fetching the snapshot.
+	 */
+	getSnapshot?(snapshotFetchOptions?: ISnapshotFetchOptions): Promise<ISnapshot>;
+
 	/**
 	 * Retrieves all versions of the document starting at the specified versionId - or null if from the head
 	 * @param versionId - Version id of the requested version.
@@ -205,6 +214,18 @@ export interface IDocumentStorageService extends Partial<IDisposable> {
 	downloadSummary(handle: ISummaryHandle): Promise<ISummaryTree>;
 }
 
+/**
+ * Events emitted by {@link IDocumentService}.
+ * @alpha
+ */
+export interface IDocumentServiceEvents extends IEvent {
+	/**
+	 * This event is used to communicate any metadata related to the container. We might have received metadata from the service.
+	 * Read more info on this event from here `IContainer.containerMetadata`.
+	 */
+	(event: "metadataUpdate", listener: (metadata: Record<string, string>) => void);
+}
+
 /**
  * @alpha
  */
@@ -328,12 +349,19 @@ export interface IDocumentServicePolicies {
 	 * Summarizer uploads the protocol tree too when summarizing.
 	 */
 	readonly summarizeProtocolTree?: boolean;
+
+	/**
+	 * Whether the driver supports the new getSnapshot api which returns snapshot which
+	 * contains all contents along with the snapshot tree. Enable this by default when the
+	 * driver can fully support the api.
+	 */
+	readonly supportGetSnapshotApi?: boolean;
 }
 
 /**
  * @alpha
  */
-export interface IDocumentService {
+export interface IDocumentService extends IEventProvider<IDocumentServiceEvents> {
 	resolvedUrl: IResolvedUrl;
 
 	/**
@@ -437,3 +465,48 @@ export enum FetchSource {
 	default = "default",
 	noCache = "noCache",
 }
+
+/**
+ * @alpha
+ */
+export interface ISnapshot {
+	snapshotTree: ISnapshotTree;
+	blobContents: Map<string, ArrayBuffer>;
+	ops: ISequencedDocumentMessage[];
+
+	/**
+	 * Sequence number of the snapshot
+	 */
+	sequenceNumber: number | undefined;
+
+	/**
+	 * Sequence number for the latest op/snapshot for the file in ODSP
+	 */
+	latestSequenceNumber: number | undefined;
+
+	snapshotFormatV: 1;
+}
+
+/**
+ * Snapshot fetch options which are used to communicate different things to the driver
+ * when fetching the snapshot.
+ * @alpha
+ */
+export interface ISnapshotFetchOptions {
+	/**
+	 * Indicates scenario in which the snapshot is fetched. It is a free form string  mostly
+	 * used for telemetry purposes.
+	 */
+	scenarioName?: string;
+	/**
+	 * Tell driver to cache the fetched snapshot. Driver is supposed to cache the fetched snapshot if this is
+	 * set to true. If undefined, then it is upto the driver, to cache it or not.
+	 */
+	cacheSnapshot?: boolean;
+
+	/**
+	 * Version of the snapshot to be fetched. Certain storage services just keep 1 snapshot for the
+	 * container, so specifying version is not necessary for storage services.
+	 */
+	versionId?: string;
+}