@fluidframework/odsp-driver-definitions 1.4.0-115997 → 2.0.0-dev-rc.1.0.0.224419

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

@@ -0,0 +1,626 @@
+import { DriverError } from '@fluidframework/driver-definitions';
+import { IDriverErrorBase } from '@fluidframework/driver-definitions';
+import { IResolvedUrl } from '@fluidframework/driver-definitions';
+
+/**
+ * @alpha
+ */
+export declare type CacheContentType = "snapshot" | "ops";
+
+/* Excluded from this release type: getKeyForCacheEntry */
+
+/**
+ * @alpha
+ */
+export declare 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;
+    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;
+}
+
+/**
+ * Cache entry. Identifies file that this entry belongs to, and type of content stored in it.
+ * @alpha
+ */
+export declare interface ICacheEntry extends IEntry {
+    /**
+     * Identifies file in storage this cached entry is for
+     */
+    file: IFileEntry;
+}
+
+/**
+ * @alpha
+ */
+export declare 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;
+}
+
+/**
+ * Identity types supported by ODSP driver.
+ * `Consumer` represents user authenticated with Microsoft Account (MSA).
+ * `Enterprise` represents user authenticated with M365 tenant account.
+ * @alpha
+ */
+export declare type IdentityType = "Consumer" | "Enterprise";
+
+/**
+ * Cache entry. Identifies file that this entry belongs to, and type of content stored in it.
+ * @alpha
+ */
+export declare 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;
+}
+
+/**
+ * @alpha
+ */
+export declare 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;
+}
+
+/* Excluded from this release type: InstrumentedStorageTokenFetcher */
+
+/**
+ * Base interface for all errors and warnings
+ * Superset of IDriverErrorBase, but with Odsp-specific errorType and properties
+ * @alpha
+ */
+export declare interface IOdspError extends Omit<IDriverErrorBase, "errorType">, IOdspErrorAugmentations {
+    readonly errorType: OdspErrorType;
+}
+
+/**
+ * @alpha
+ */
+export declare interface IOdspErrorAugmentations {
+    /**
+     * Server epoch indicates when the file was last modified.
+     * Used to detect modifications outside Fluid's services
+     */
+    serverEpoch?: string;
+    /**
+     * It is the redirection url at which the network call should have been made. It is due to change
+     * in site domain of the file on server.
+     */
+    redirectLocation?: string;
+    /**
+     * It is array of error codes included in error response from server.
+     */
+    facetCodes?: string[];
+}
+
+/**
+ * @alpha
+ */
+export declare interface IOdspResolvedUrl extends IResolvedUrl, IOdspUrlParts {
+    type: "fluid";
+    odspResolvedUrl: true;
+    url: string;
+    hashedDocumentId: string;
+    endpoints: {
+        snapshotStorageUrl: string;
+        attachmentPOSTStorageUrl: string;
+        attachmentGETStorageUrl: string;
+        deltaStorageUrl: string;
+    };
+    tokens: {};
+    fileName: string;
+    summarizer: boolean;
+    codeHint?: {
+        containerPackageName?: string;
+    };
+    fileVersion: string | undefined;
+    dataStorePath?: string;
+    /**
+     * Sharing link data created for the ODSP item.
+     * Contains information about either sharing link created while creating a new file or
+     * a redeemable share link created when loading an existing file
+     */
+    shareLinkInfo?: ShareLinkInfoType;
+    isClpCompliantApp?: boolean;
+}
+
+/**
+ * @alpha
+ */
+export declare interface IOdspUrlParts {
+    siteUrl: string;
+    driveId: string;
+    itemId: string;
+}
+
+/**
+ * @alpha
+ */
+export declare 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;
+}
+
+/**
+ * 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.
+ * @alpha
+ */
+export declare 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>;
+    /**
+     * 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>;
+}
+
+/**
+ * An interface that allows a concrete instance of a driver factory to interrogate itself
+ * to find out if it is session aware.
+ * @alpha
+ */
+export declare interface IProvideSessionAwareDriverFactory {
+    readonly IRelaySessionAwareDriverFactory: IRelaySessionAwareDriverFactory;
+}
+
+/**
+ * An interface that allows a concrete instance of a driver factory to call the `getRelayServiceSessionInfo`
+ * function if it session aware.
+ * @alpha
+ */
+export declare interface IRelaySessionAwareDriverFactory extends IProvideSessionAwareDriverFactory {
+    getRelayServiceSessionInfo(resolvedUrl: IResolvedUrl): Promise<ISocketStorageDiscovery | undefined>;
+}
+
+/**
+ * Sharing link data received from the /snapshot api response.
+ * @alpha
+ */
+export declare interface ISharingLink extends ISharingLinkKind {
+    webUrl: string;
+}
+
+/**
+ * Defines the permissions scope for a share link requested to be created during the creation the file in ODSP.
+ * Providing these properties to the /snapshot api will also create and return the requested kind of sharing link.
+ * @alpha
+ */
+export declare interface ISharingLinkKind {
+    scope: SharingLinkScope;
+    role?: SharingLinkRole;
+}
+
+/**
+ * @alpha
+ */
+export declare interface ISnapshotOptions {
+    blobs?: number;
+    deltas?: number;
+    channels?: number;
+    mds?: number;
+    timeout?: number;
+}
+
+/**
+ * Socket storage discovery api response
+ * @alpha
+ */
+export declare interface ISocketStorageDiscovery {
+    id: string;
+    runtimeTenantId?: string;
+    tenantId: string;
+    snapshotStorageUrl: string;
+    deltaStorageUrl: string;
+    /**
+     * PUSH URL
+     */
+    deltaStreamSocketUrl: string;
+    /**
+     * The access token for PushChannel. Optionally returned, depending on implementation.
+     * OneDrive for Consumer implementation returns it and OneDrive for Business implementation
+     * does not return it and instead expects token to be returned via `getWebsocketToken` callback
+     * passed as a parameter to `OdspDocumentService.create()` factory.
+     */
+    socketToken?: string;
+    /**
+     * This is the time within which client has to refresh the session on (ODSP) relay service.
+     */
+    refreshSessionDurationSeconds?: number;
+}
+
+/* Excluded from this release type: isTokenFromCache */
+
+/**
+ * @alpha
+ */
+export declare type OdspError = IOdspError | (DriverError & IOdspErrorAugmentations);
+
+/**
+ * ODSP Error types.
+ * Different error types that may be thrown by the ODSP driver.
+ *
+ * @deprecated Use {@link (OdspErrorTypes:variable)} instead.
+ * @alpha
+ */
+export declare enum OdspErrorType {
+    /**
+     * Storage is out of space
+     */
+    outOfStorageError = "outOfStorageError",
+    /**
+     * Invalid file name (at creation of the file)
+     */
+    invalidFileNameError = "invalidFileNameError",
+    /**
+     * Snapshot is too big. Host application specified limit for snapshot size, and snapshot was bigger
+     * that that limit, thus request failed. Hosting application is expected to have fall-back behavior for
+     * such case.
+     */
+    snapshotTooBig = "snapshotTooBig",
+    /**
+     * Maximum time limit to fetch reached. Host application specified limit for fetching of snapshot, when
+     * that limit is reached, request fails. Hosting application is expected to have fall-back behavior for
+     * such case.
+     */
+    fetchTimeout = "fetchTimeout",
+    /**
+     * SPO admin toggle: fluid service is not enabled.
+     */
+    fluidNotEnabled = "fluidNotEnabled",
+    /**
+     * {@inheritDoc @fluidframework/driver-definitions#FluidErrorType.fetchTokenError}
+     */
+    fetchTokenError = "fetchTokenError",
+    /**
+     * This error will be raised when client is too behind with no way to catch up.
+     * This condition will happen when user was offline for too long, resulting in old ops / blobs being deleted
+     * by storage, and thus removing an ability for client to catch up.
+     * This condition will result in any local changes being lost (i.e. only way to save state is by user
+     * copying it over manually)
+     */
+    cannotCatchUp = "cannotCatchUp",
+    /**
+     * SPO can occasionally return 403 for r/w operations on document when there is a fail over to another data center.
+     * So to preserve integrity of the data, the data becomes readonly.
+     */
+    serviceReadOnly = "serviceReadOnly",
+    /**
+     * Due to organizational policies, you can't access server resources from the current network location.
+     */
+    blockedIPAddress = "blockedIPAddress"
+}
+
+/**
+ * ODSP Error types.
+ * Different error types that may be thrown by the ODSP driver.
+ * @alpha
+ */
+export declare const OdspErrorTypes: {
+    /**
+     * Invalid file name (at creation of the file)
+     */
+    readonly invalidFileNameError: "invalidFileNameError";
+    /**
+     * Snapshot is too big. Host application specified limit for snapshot size, and snapshot was bigger
+     * that that limit, thus request failed. Hosting application is expected to have fall-back behavior for
+     * such case.
+     */
+    readonly snapshotTooBig: "snapshotTooBig";
+    /**
+     * Maximum time limit to fetch reached. Host application specified limit for fetching of snapshot, when
+     * that limit is reached, request fails. Hosting application is expected to have fall-back behavior for
+     * such case.
+     */
+    readonly fetchTimeout: "fetchTimeout";
+    /**
+     * SPO admin toggle: fluid service is not enabled.
+     */
+    readonly fluidNotEnabled: "fluidNotEnabled";
+    /**
+     * This error will be raised when client is too behind with no way to catch up.
+     * This condition will happen when user was offline for too long, resulting in old ops / blobs being deleted
+     * by storage, and thus removing an ability for client to catch up.
+     * This condition will result in any local changes being lost (i.e. only way to save state is by user
+     * copying it over manually)
+     */
+    readonly cannotCatchUp: "cannotCatchUp";
+    /**
+     * SPO can occasionally return 403 for r/w operations on document when there is a fail over to another data center.
+     * So to preserve integrity of the data, the data becomes readonly.
+     */
+    readonly serviceReadOnly: "serviceReadOnly";
+    /**
+     * Due to organizational policies, you can't access server resources from the current network location.
+     */
+    readonly blockedIPAddress: "blockedIPAddress";
+    readonly genericNetworkError: "genericNetworkError";
+    readonly authorizationError: "authorizationError";
+    readonly fileNotFoundOrAccessDeniedError: "fileNotFoundOrAccessDeniedError";
+    readonly offlineError: "offlineError";
+    readonly unsupportedClientProtocolVersion: "unsupportedClientProtocolVersion";
+    readonly writeError: "writeError";
+    readonly fetchFailure: "fetchFailure";
+    readonly fetchTokenError: "fetchTokenError";
+    readonly incorrectServerResponse: "incorrectServerResponse";
+    readonly fileOverwrittenInStorage: "fileOverwrittenInStorage";
+    readonly deltaStreamConnectionForbidden: "deltaStreamConnectionForbidden";
+    readonly locationRedirection: "locationRedirection";
+    readonly fluidInvalidSchema: "fluidInvalidSchema";
+    readonly fileIsLocked: "fileIsLocked";
+    readonly outOfStorageError: "outOfStorageError";
+    readonly genericError: "genericError";
+    readonly throttlingError: "throttlingError";
+    readonly usageError: "usageError";
+};
+
+/**
+ * @alpha
+ */
+export declare type OdspErrorTypes = (typeof OdspErrorTypes)[keyof typeof OdspErrorTypes];
+
+/**
+ * Represents access token fetch options for ODSP resource
+ * @alpha
+ */
+export declare interface OdspResourceTokenFetchOptions extends TokenFetchOptions {
+    /** Site url representing ODSP resource location */
+    siteUrl: string;
+    /** ODSP drive id where resource resides. Optional, used only when fetching token to access ODSP file */
+    driveId?: string;
+    /** ODSP item id representing resource. Optional, used only when fetching token to access ODSP file */
+    itemId?: string;
+}
+
+/**
+ * Sharing link data created for the ODSP item.
+ * Contains information about either sharing link created while creating a new file or
+ * a redeemable share link created when loading an existing file
+ * @alpha
+ */
+export declare interface ShareLinkInfoType {
+    /**
+     * We create a new file in ODSP with the /snapshot api call. Applications then need to make a separate apis call to
+     * create a sharing link for that file. To reduce the number of network calls, ODSP now provides a feature
+     * where we can create a share link along with creating a file by passing a query parameter called
+     * createShareLink (deprecated) or createLinkScope and createLinkRole. createLink object below saves the information
+     * from the /snapshot api response.
+     */
+    createLink?: {
+        /**
+         * @deprecated
+         * Type of shareLink requested/created when creating the file for the first time. The 'type' property here
+         * represents the type of sharing link requested.
+         * Will be deprecated soon. Type of sharing link will be present in the link:ISharingLink property below.
+         */
+        type?: ShareLinkTypes | ISharingLinkKind;
+        /**
+         * Share link created when the file is created for the first time with /snapshot api call.
+         */
+        link?: string | ISharingLink;
+        /**
+         * Error message if creation of sharing link fails with /snapshot api call
+         */
+        error?: any;
+        shareId?: string;
+    };
+    /**
+     * This is used to save the network calls while doing trees/latest call as if the client does not have
+     * permission then this link can be redeemed for the permissions in the same network call.
+     */
+    sharingLinkToRedeem?: string;
+}
+
+/**
+ * @deprecated Use ISharingLinkKind type instead.
+ * Type of shareLink requested/created when creating the file for the first time.
+ * @alpha
+ */
+export declare enum ShareLinkTypes {
+    csl = "csl"
+}
+
+/**
+ * View/edit permission role for a sharing link.
+ * @alpha
+ */
+export declare enum SharingLinkRole {
+    view = "view",
+    edit = "edit"
+}
+
+/**
+ * Sharing scope of the share links created for a file.
+ * @alpha
+ */
+export declare enum SharingLinkScope {
+    organization = "organization",
+    users = "users",
+    anonymous = "anonymous",
+    default = "default"
+}
+
+/* Excluded from this release type: snapshotKey */
+
+/**
+ * Method signature for callback method used to fetch access token
+ * @param options - token fetch options
+ * @returns If successful, TokenResponse object representing token value along with flag indicating
+ * whether token came from cache. Legacy implementation may return a string for token value;
+ * in this case it should be assumes that fromCache signal is undefined. Null is returned in case of failure.
+ * @alpha
+ */
+export declare type TokenFetcher<T> = (options: T) => Promise<string | TokenResponse | null>;
+
+/**
+ * Represents access token fetch options
+ * @alpha
+ */
+export declare interface TokenFetchOptions {
+    /**
+     * Value indicating whether fresh token has to be returned.
+     * If false then it is okay to return cached unexpired token if available.
+     */
+    refresh: boolean;
+    /**
+     * Claims that have to be passed with token fetch request.
+     * These can be used to specify additional information that must be passed to token authority.
+     */
+    claims?: string;
+    /**
+     * Tenant id of authority that must be handling token fetch.
+     * If it is not specified then it is up to token fetching logic to determine which tenant authority
+     * to use to issue access token.
+     */
+    tenantId?: string;
+}
+
+/* Excluded from this release type: tokenFromResponse */
+
+/**
+ * Represents token response
+ * @beta
+ */
+export declare interface TokenResponse {
+    /** Token value */
+    token: string;
+    /** Flag indicating whether token was obtained from local cache */
+    fromCache?: boolean;
+}
+
+export { }