@fluidframework/driver-definitions 2.0.0-dev.7.4.0.215930 → 2.0.0-dev.7.4.0.217212

package/api-extractor-lint.json

@@ -0,0 +1,13 @@
+{
+	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+	"extends": "../../../common/build/build-common/api-extractor-lint.json",
+	"messages": {
+		"extractorMessageReporting": {
+			// TODO: remove once base config has this enabled as an error
+			"ae-incompatible-release-tags": {
+				"logLevel": "error",
+				"addToApiReportFile": false
+			}
+		}
+	}
+}

package/api-extractor.json

@@ -3,10 +3,6 @@
 	"extends": "../../../common/build/build-common/api-extractor-base.json",
 	"messages": {
 		"extractorMessageReporting": {
-			"ae-missing-release-tag": {
-				// TODO: Fix violations and remove this rule override
-				"logLevel": "none"
-			},
 			// TODO: Add missing documentation and remove this rule override
 			"ae-undocumented": {
 				"logLevel": "none"

package/api-report/driver-definitions.api.md

@@ -24,10 +24,10 @@ import { ITelemetryBaseLogger } from '@fluidframework/core-interfaces';
 import { ITokenClaims } from '@fluidframework/protocol-definitions';
 import { IVersion } from '@fluidframework/protocol-definitions';
 
-// @public (undocumented)
+// @internal (undocumented)
 export type DriverError = IThrottlingWarning | IGenericNetworkError | IAuthorizationError | ILocationRedirectionError | IDriverBasicError;
 
-// @public @deprecated
+// @alpha @deprecated
 export enum DriverErrorType {
     authorizationError = "authorizationError",
     deltaStreamConnectionForbidden = "deltaStreamConnectionForbidden",
@@ -50,7 +50,7 @@ export enum DriverErrorType {
     writeError = "writeError"
 }
 
-// @public
+// @internal
 export const DriverErrorTypes: {
     readonly genericNetworkError: "genericNetworkError";
     readonly authorizationError: "authorizationError";
@@ -72,10 +72,10 @@ export const DriverErrorTypes: {
     readonly usageError: "usageError";
 };
 
-// @public (undocumented)
+// @internal (undocumented)
 export type DriverErrorTypes = (typeof DriverErrorTypes)[keyof typeof DriverErrorTypes];
 
-// @public
+// @internal
 export enum DriverHeader {
     // (undocumented)
     createNew = "createNew",
@@ -83,13 +83,13 @@ export enum DriverHeader {
     summarizingClient = "fluid-client-summarizer"
 }
 
-// @public
+// @internal
 export interface DriverPreCheckInfo {
     codeDetailsHint?: string;
     criticalBootDomains?: string[];
 }
 
-// @public (undocumented)
+// @alpha (undocumented)
 export enum FetchSource {
     // (undocumented)
     default = "default",
@@ -97,16 +97,16 @@ export enum FetchSource {
     noCache = "noCache"
 }
 
-// @public (undocumented)
+// @alpha (undocumented)
 export type FiveDaysMs = 432000000;
 
-// @public
+// @alpha
 export interface IAnyDriverError extends Omit<IDriverErrorBase, "errorType"> {
     // (undocumented)
     readonly errorType: string;
 }
 
-// @public (undocumented)
+// @internal (undocumented)
 export interface IAuthorizationError extends IDriverErrorBase {
     // (undocumented)
     readonly claims?: string;
@@ -116,25 +116,25 @@ export interface IAuthorizationError extends IDriverErrorBase {
     readonly tenantId?: string;
 }
 
-// @public
+// @alpha
 export interface IContainerPackageInfo {
     name: string;
 }
 
-// @public (undocumented)
+// @internal (undocumented)
 export interface IDeltasFetchResult {
     messages: ISequencedDocumentMessage[];
     partialResult: boolean;
 }
 
-// @public
+// @internal
 export interface IDeltaStorageService {
     get(tenantId: string, id: string, from: number, // inclusive
     to: number, // exclusive
     fetchReason?: string): Promise<IDeltasFetchResult>;
 }
 
-// @public (undocumented)
+// @alpha (undocumented)
 export interface IDocumentDeltaConnection extends IDisposable, IEventProvider<IDocumentDeltaConnectionEvents> {
     checkpointSequenceNumber?: number;
     claims: ITokenClaims;
@@ -151,7 +151,7 @@ export interface IDocumentDeltaConnection extends IDisposable, IEventProvider<ID
     version: string;
 }
 
-// @public (undocumented)
+// @alpha (undocumented)
 export interface IDocumentDeltaConnectionEvents extends IErrorEvent {
     // (undocumented)
     (event: "nack", listener: (documentId: string, message: INack[]) => void): any;
@@ -167,12 +167,12 @@ export interface IDocumentDeltaConnectionEvents extends IErrorEvent {
     (event: "error", listener: (error: any) => void): any;
 }
 
-// @public
+// @alpha
 export interface IDocumentDeltaStorageService {
     fetchMessages(from: number, to: number | undefined, abortSignal?: AbortSignal, cachedOnly?: boolean, fetchReason?: string): IStream<ISequencedDocumentMessage[]>;
 }
 
-// @public (undocumented)
+// @alpha (undocumented)
 export interface IDocumentService {
     connectToDeltaStorage(): Promise<IDocumentDeltaStorageService>;
     connectToDeltaStream(client: IClient): Promise<IDocumentDeltaConnection>;
@@ -183,19 +183,19 @@ export interface IDocumentService {
     resolvedUrl: IResolvedUrl;
 }
 
-// @public (undocumented)
+// @alpha (undocumented)
 export interface IDocumentServiceFactory {
     createContainer(createNewSummary: ISummaryTree | undefined, createNewResolvedUrl: IResolvedUrl, logger?: ITelemetryBaseLogger, clientIsSummarizer?: boolean): Promise<IDocumentService>;
     createDocumentService(resolvedUrl: IResolvedUrl, logger?: ITelemetryBaseLogger, clientIsSummarizer?: boolean): Promise<IDocumentService>;
 }
 
-// @public (undocumented)
+// @alpha (undocumented)
 export interface IDocumentServicePolicies {
     readonly storageOnly?: boolean;
     readonly summarizeProtocolTree?: boolean;
 }
 
-// @public
+// @alpha
 export interface IDocumentStorageService extends Partial<IDisposable> {
     createBlob(file: ArrayBufferLike): Promise<ICreateBlobResponse>;
     downloadSummary(handle: ISummaryHandle): Promise<ISummaryTree>;
@@ -208,13 +208,13 @@ export interface IDocumentStorageService extends Partial<IDisposable> {
     uploadSummaryWithContext(summary: ISummaryTree, context: ISummaryContext): Promise<string>;
 }
 
-// @public
+// @alpha
 export interface IDocumentStorageServicePolicies {
     readonly caching?: LoaderCachingPolicy;
     readonly maximumCacheDurationMs?: FiveDaysMs;
 }
 
-// @public
+// @internal
 export interface IDriverBasicError extends IDriverErrorBase {
     // (undocumented)
     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;
@@ -222,7 +222,7 @@ export interface IDriverBasicError extends IDriverErrorBase {
     readonly statusCode?: number;
 }
 
-// @public
+// @alpha
 export interface IDriverErrorBase {
     canRetry: boolean;
     endpointReached?: boolean;
@@ -231,7 +231,7 @@ export interface IDriverErrorBase {
     online?: string;
 }
 
-// @public (undocumented)
+// @internal (undocumented)
 export interface IDriverHeader {
     // (undocumented)
     [DriverHeader.summarizingClient]: boolean;
@@ -239,7 +239,7 @@ export interface IDriverHeader {
     [DriverHeader.createNew]: any;
 }
 
-// @public (undocumented)
+// @internal (undocumented)
 export interface IGenericNetworkError extends IDriverErrorBase {
     // (undocumented)
     readonly errorType: DriverErrorType.genericNetworkError;
@@ -247,7 +247,7 @@ export interface IGenericNetworkError extends IDriverErrorBase {
     readonly statusCode?: number;
 }
 
-// @public (undocumented)
+// @internal (undocumented)
 export interface ILocationRedirectionError extends IDriverErrorBase {
     // (undocumented)
     readonly errorType: DriverErrorType.locationRedirection;
@@ -255,7 +255,7 @@ export interface ILocationRedirectionError extends IDriverErrorBase {
     readonly redirectUrl: IResolvedUrl;
 }
 
-// @public (undocumented)
+// @alpha (undocumented)
 export interface IResolvedUrl {
     // (undocumented)
     endpoints: {
@@ -272,13 +272,13 @@ export interface IResolvedUrl {
     url: string;
 }
 
-// @public
+// @alpha
 export interface IStream<T> {
     // (undocumented)
     read(): Promise<IStreamResult<T>>;
 }
 
-// @public (undocumented)
+// @alpha (undocumented)
 export type IStreamResult<T> = {
     done: true;
 } | {
@@ -286,7 +286,7 @@ export type IStreamResult<T> = {
     value: T;
 };
 
-// @public
+// @alpha
 export interface ISummaryContext {
     readonly ackHandle: string | undefined;
     readonly proposalHandle: string | undefined;
@@ -294,7 +294,7 @@ export interface ISummaryContext {
     readonly referenceSequenceNumber: number;
 }
 
-// @public (undocumented)
+// @internal (undocumented)
 export interface IThrottlingWarning extends IDriverErrorBase {
     // (undocumented)
     readonly errorType: DriverErrorType.throttlingError;
@@ -302,14 +302,14 @@ export interface IThrottlingWarning extends IDriverErrorBase {
     readonly retryAfterSeconds: number;
 }
 
-// @public (undocumented)
+// @alpha (undocumented)
 export interface IUrlResolver {
     getAbsoluteUrl(resolvedUrl: IResolvedUrl, relativeUrl: string, packageInfoSource?: IContainerPackageInfo): Promise<string>;
     // (undocumented)
     resolve(request: IRequest): Promise<IResolvedUrl | undefined>;
 }
 
-// @public (undocumented)
+// @alpha (undocumented)
 export enum LoaderCachingPolicy {
     NoCaching = 0,
     Prefetch = 1

package/dist/driver-definitions-alpha.d.ts

@@ -18,13 +18,14 @@ import { ITelemetryBaseLogger } from '@fluidframework/core-interfaces';
 import { ITokenClaims } from '@fluidframework/protocol-definitions';
 import { IVersion } from '@fluidframework/protocol-definitions';
 
-export declare type DriverError = IThrottlingWarning | IGenericNetworkError | IAuthorizationError | ILocationRedirectionError | IDriverBasicError;
+/* Excluded from this release type: DriverError */
 
 /**
  * Driver Error types
  * Lists types that are likely to be used by all drivers
  *
  * @deprecated Use {@link (DriverErrorTypes:type)} instead.
+ * @alpha
  */
 export declare enum DriverErrorType {
     /**
@@ -110,114 +111,23 @@ export declare enum DriverErrorType {
     outOfStorageError = "outOfStorageError"
 }
 
-/**
- * Different error types the Driver may report out to the Host.
- */
-export declare const DriverErrorTypes: {
-    /**
-     * Some non-categorized (below) networking error
-     * Include errors like  fatal server error (usually 500).
-     */
-    readonly genericNetworkError: "genericNetworkError";
-    /**
-     * Access denied - user does not have enough privileges to open a file, or continue to operate on a file
-     */
-    readonly authorizationError: "authorizationError";
-    /**
-     * File not found, or file deleted during session
-     */
-    readonly fileNotFoundOrAccessDeniedError: "fileNotFoundOrAccessDeniedError";
-    /**
-     * We can not reach server due to computer being offline.
-     */
-    readonly offlineError: "offlineError";
-    readonly 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.
-     */
-    readonly 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.
-     */
-    readonly fetchFailure: "fetchFailure";
-    /**
-     * This error occurs when token provider fails to fetch orderer token
-     */
-    readonly fetchTokenError: "fetchTokenError";
-    /**
-     * Unexpected response from server. Either JSON is malformed, or some required properties are missing
-     */
-    readonly 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.
-     */
-    readonly fileOverwrittenInStorage: "fileOverwrittenInStorage";
-    /**
-     * The document is read-only and delta stream connection is forbidden.
-     */
-    readonly 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.
-     */
-    readonly 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"
-     */
-    readonly fluidInvalidSchema: "fluidInvalidSchema";
-    /**
-     * File is locked for read/write by storage, e.g. whole collection is locked and access denied.
-     */
-    readonly fileIsLocked: "fileIsLocked";
-    /**
-     * Storage is out of space
-     */
-    readonly outOfStorageError: "outOfStorageError";
-    readonly genericError: "genericError";
-    readonly throttlingError: "throttlingError";
-    readonly usageError: "usageError";
-};
+/* Excluded from this release type: DriverErrorTypes */
 
-export declare type DriverErrorTypes = (typeof DriverErrorTypes)[keyof typeof DriverErrorTypes];
+/* Excluded from this release type: DriverHeader */
 
-/**
- * Additional key in the loader request header
- */
-export declare enum DriverHeader {
-    summarizingClient = "fluid-client-summarizer",
-    createNew = "createNew"
-}
+/* Excluded from this release type: DriverPreCheckInfo */
 
 /**
- * Information that can be returned by a lightweight, seperately exported driver function. Used to preanalyze a URL
- * for driver compatibility and preload information.
+ * @alpha
  */
-export declare interface DriverPreCheckInfo {
-    /**
-     * A code details hint that can potentially be used to prefetch container code prior to having a snapshot.
-     */
-    codeDetailsHint?: string;
-    /**
-     * Domains that will be connected to on the critical boot path. Hosts can choose to preconnect to these for
-     * improved performance.
-     */
-    criticalBootDomains?: string[];
-}
-
 export declare enum FetchSource {
     default = "default",
     noCache = "noCache"
 }
 
+/**
+ * @alpha
+ */
 export declare type FiveDaysMs = 432000000;
 
 /**
@@ -228,19 +138,17 @@ export declare type FiveDaysMs = 432000000;
  * "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,
  * but we can't reference a specific driver's error type enum in this code.
+ * @alpha
  */
 export declare interface IAnyDriverError extends Omit<IDriverErrorBase, "errorType"> {
     readonly errorType: string;
 }
 
-export declare interface IAuthorizationError extends IDriverErrorBase {
-    readonly errorType: DriverErrorType.authorizationError;
-    readonly claims?: string;
-    readonly tenantId?: string;
-}
+/* Excluded from this release type: IAuthorizationError */
 
 /**
  * Container package info handed off to resolver.
+ * @alpha
  */
 export declare interface IContainerPackageInfo {
     /**
@@ -249,39 +157,13 @@ export declare interface IContainerPackageInfo {
     name: string;
 }
 
-export declare interface IDeltasFetchResult {
-    /**
-     * Sequential set of messages starting from 'from' sequence number.
-     * May be partial result, i.e. not fulfill original request in full.
-     */
-    messages: ISequencedDocumentMessage[];
-    /**
-     * If true, storage only partially fulfilled request, but has more ops
-     * If false, the request was fulfilled. If less ops were returned then
-     * requested, then storage does not have more ops in this range.
-     */
-    partialResult: boolean;
-}
+/* Excluded from this release type: IDeltasFetchResult */
+
+/* Excluded from this release type: IDeltaStorageService */
 
 /**
- * Interface to provide access to stored deltas for a shared object
+ * @alpha
  */
-export declare interface IDeltaStorageService {
-    /**
-     * Retrieves all the delta operations within the inclusive sequence number range
-     * @param tenantId - Id of the tenant.
-     * @param id - document id.
-     * @param from - first op to retrieve (inclusive)
-     * @param to - first op not to retrieve (exclusive end)
-     * @param fetchReason - Reason for fetching the messages, for logging.
-     * Example, gap between seq number of Op on wire and known seq number.
-     * It can be logged by spo which could help in debugging sessions if any issue occurs.
-     */
-    get(tenantId: string, id: string, from: number, // inclusive
-    to: number, // exclusive
-    fetchReason?: string): Promise<IDeltasFetchResult>;
-}
-
 export declare interface IDocumentDeltaConnection extends IDisposable, IEventProvider<IDocumentDeltaConnectionEvents> {
     /**
      * ClientID for the connection
@@ -344,6 +226,9 @@ export declare interface IDocumentDeltaConnection extends IDisposable, IEventPro
     submitSignal(content: any, targetClientId?: string): void;
 }
 
+/**
+ * @alpha
+ */
 export declare interface IDocumentDeltaConnectionEvents extends IErrorEvent {
     (event: "nack", listener: (documentId: string, message: INack[]) => void): any;
     (event: "disconnect", listener: (reason: IAnyDriverError) => void): any;
@@ -355,6 +240,7 @@ export declare interface IDocumentDeltaConnectionEvents extends IErrorEvent {
 
 /**
  * Interface to provide access to stored deltas for a shared object
+ * @alpha
  */
 export declare interface IDocumentDeltaStorageService {
     /**
@@ -370,6 +256,9 @@ export declare interface IDocumentDeltaStorageService {
     fetchMessages(from: number, to: number | undefined, abortSignal?: AbortSignal, cachedOnly?: boolean, fetchReason?: string): IStream<ISequencedDocumentMessage[]>;
 }
 
+/**
+ * @alpha
+ */
 export declare interface IDocumentService {
     resolvedUrl: IResolvedUrl;
     /**
@@ -401,6 +290,9 @@ export declare interface IDocumentService {
     dispose(error?: any): void;
 }
 
+/**
+ * @alpha
+ */
 export declare interface IDocumentServiceFactory {
     /**
      * Creates the document service after extracting different endpoints URLs from a resolved URL.
@@ -428,6 +320,9 @@ export declare interface IDocumentServiceFactory {
     createContainer(createNewSummary: ISummaryTree | undefined, createNewResolvedUrl: IResolvedUrl, logger?: ITelemetryBaseLogger, clientIsSummarizer?: boolean): Promise<IDocumentService>;
 }
 
+/**
+ * @alpha
+ */
 export declare interface IDocumentServicePolicies {
     /**
      * Do not connect to delta stream
@@ -441,6 +336,7 @@ export declare interface IDocumentServicePolicies {
 
 /**
  * Interface to provide access to snapshots saved for a shared object
+ * @alpha
  */
 export declare interface IDocumentStorageService extends Partial<IDisposable> {
     repositoryUrl: string;
@@ -492,6 +388,7 @@ export declare interface IDocumentStorageService extends Partial<IDisposable> {
 /**
  * Policies describing attributes or characteristics of the driver's storage service,
  * to direct how other components interact with the driver
+ * @alpha
  */
 export declare interface IDocumentStorageServicePolicies {
     /**
@@ -509,17 +406,11 @@ export declare interface IDocumentStorageServicePolicies {
     readonly maximumCacheDurationMs?: FiveDaysMs;
 }
 
-/**
- * Having this uber interface without types that have their own interfaces
- * allows compiler to differentiate interfaces based on error type
- */
-export declare 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;
-    readonly statusCode?: number;
-}
+/* Excluded from this release type: IDriverBasicError */
 
 /**
  * Base interface for all errors and warnings
+ * @alpha
  */
 export declare interface IDriverErrorBase {
     /**
@@ -547,21 +438,15 @@ export declare interface IDriverErrorBase {
     endpointReached?: boolean;
 }
 
-export declare interface IDriverHeader {
-    [DriverHeader.summarizingClient]: boolean;
-    [DriverHeader.createNew]: any;
-}
+/* Excluded from this release type: IDriverHeader */
 
-export declare interface IGenericNetworkError extends IDriverErrorBase {
-    readonly errorType: DriverErrorType.genericNetworkError;
-    readonly statusCode?: number;
-}
+/* Excluded from this release type: IGenericNetworkError */
 
-export declare interface ILocationRedirectionError extends IDriverErrorBase {
-    readonly errorType: DriverErrorType.locationRedirection;
-    readonly redirectUrl: IResolvedUrl;
-}
+/* Excluded from this release type: ILocationRedirectionError */
 
+/**
+ * @alpha
+ */
 export declare interface IResolvedUrl {
     type: "fluid";
     /**
@@ -579,11 +464,15 @@ export declare interface IResolvedUrl {
 
 /**
  * Read interface for the Queue
+ * @alpha
  */
 export declare interface IStream<T> {
     read(): Promise<IStreamResult<T>>;
 }
 
+/**
+ * @alpha
+ */
 export declare type IStreamResult<T> = {
     done: true;
 } | {
@@ -594,6 +483,7 @@ export declare type IStreamResult<T> = {
 /**
  * Context for uploading a summary to storage.
  * Indicates the previously acked summary.
+ * @alpha
  */
 export declare interface ISummaryContext {
     /**
@@ -607,11 +497,11 @@ export declare interface ISummaryContext {
     readonly referenceSequenceNumber: number;
 }
 
-export declare interface IThrottlingWarning extends IDriverErrorBase {
-    readonly errorType: DriverErrorType.throttlingError;
-    readonly retryAfterSeconds: number;
-}
+/* Excluded from this release type: IThrottlingWarning */
 
+/**
+ * @alpha
+ */
 export declare interface IUrlResolver {
     resolve(request: IRequest): Promise<IResolvedUrl | undefined>;
     /**
@@ -624,6 +514,9 @@ export declare interface IUrlResolver {
     getAbsoluteUrl(resolvedUrl: IResolvedUrl, relativeUrl: string, packageInfoSource?: IContainerPackageInfo): Promise<string>;
 }
 
+/**
+ * @alpha
+ */
 export declare enum LoaderCachingPolicy {
     /**
      * The loader should not implement any prefetching or caching policy.