@fluidframework/container-runtime 2.0.0-dev-rc.3.0.0.254274 → 2.0.0-dev-rc.3.0.0.254674

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,2002 +0,0 @@
1
- import { AliasResult } from '@fluidframework/runtime-definitions/internal';
2
- import { AttachState } from '@fluidframework/container-definitions';
3
- import { ContainerWarning } from '@fluidframework/container-definitions/internal';
4
- import { CreateChildSummarizerNodeFn } from '@fluidframework/runtime-definitions/internal';
5
- import { CreateChildSummarizerNodeParam } from '@fluidframework/runtime-definitions/internal';
6
- import { FluidDataStoreRegistryEntry } from '@fluidframework/runtime-definitions/internal';
7
- import { FluidObject } from '@fluidframework/core-interfaces';
8
- import { FlushMode } from '@fluidframework/runtime-definitions/internal';
9
- import { IAudience } from '@fluidframework/container-definitions';
10
- import { IClientDetails } from '@fluidframework/protocol-definitions';
11
- import { IContainerContext } from '@fluidframework/container-definitions/internal';
12
- import { IContainerRuntime } from '@fluidframework/container-runtime-definitions/internal';
13
- import { IContainerRuntimeBase } from '@fluidframework/runtime-definitions/internal';
14
- import { IContainerRuntimeEvents } from '@fluidframework/container-runtime-definitions/internal';
15
- import { ICriticalContainerError } from '@fluidframework/container-definitions';
16
- import { IDataStore } from '@fluidframework/runtime-definitions/internal';
17
- import { IDeltaManager } from '@fluidframework/container-definitions';
18
- import { IDisposable } from '@fluidframework/core-interfaces';
19
- import { IDocumentMessage } from '@fluidframework/protocol-definitions';
20
- import { IDocumentStorageService } from '@fluidframework/driver-definitions/internal';
21
- import { IEnvelope } from '@fluidframework/runtime-definitions/internal';
22
- import { IEvent } from '@fluidframework/core-interfaces';
23
- import { IEventProvider } from '@fluidframework/core-interfaces';
24
- import { IFluidDataStoreChannel } from '@fluidframework/runtime-definitions/internal';
25
- import { IFluidDataStoreContext } from '@fluidframework/runtime-definitions/internal';
26
- import { IFluidDataStoreContextDetached } from '@fluidframework/runtime-definitions/internal';
27
- import { IFluidDataStoreFactory } from '@fluidframework/runtime-definitions/internal';
28
- import { IFluidDataStoreRegistry } from '@fluidframework/runtime-definitions/internal';
29
- import { IFluidHandle } from '@fluidframework/core-interfaces';
30
- import { IFluidHandleContext } from '@fluidframework/core-interfaces';
31
- import { IFluidParentContext } from '@fluidframework/runtime-definitions/internal';
32
- import { IGarbageCollectionData } from '@fluidframework/runtime-definitions';
33
- import { IGarbageCollectionDetailsBase } from '@fluidframework/runtime-definitions/internal';
34
- import { IGetPendingLocalStateProps } from '@fluidframework/container-definitions/internal';
35
- import type { IIdCompressor } from '@fluidframework/id-compressor';
36
- import type { IIdCompressorCore } from '@fluidframework/id-compressor/internal';
37
- import { IInboundSignalMessage } from '@fluidframework/runtime-definitions';
38
- import { IProvideFluidHandleContext } from '@fluidframework/core-interfaces';
39
- import { IQuorumClients } from '@fluidframework/protocol-definitions';
40
- import { IRequest } from '@fluidframework/core-interfaces';
41
- import { IResponse } from '@fluidframework/core-interfaces';
42
- import { IRuntime } from '@fluidframework/container-definitions/internal';
43
- import { ISequencedDocumentMessage } from '@fluidframework/protocol-definitions';
44
- import { ISignalMessage } from '@fluidframework/protocol-definitions';
45
- import { ISnapshotTree } from '@fluidframework/protocol-definitions';
46
- import { ISummarizeResult } from '@fluidframework/runtime-definitions/internal';
47
- import { ISummarizerNodeWithGC } from '@fluidframework/runtime-definitions/internal';
48
- import { ISummaryAck } from '@fluidframework/protocol-definitions';
49
- import { ISummaryContent } from '@fluidframework/protocol-definitions';
50
- import { ISummaryNack } from '@fluidframework/protocol-definitions';
51
- import { ISummaryStats } from '@fluidframework/runtime-definitions';
52
- import { ISummaryTree } from '@fluidframework/protocol-definitions';
53
- import { ISummaryTreeWithStats } from '@fluidframework/runtime-definitions';
54
- import { ITelemetryBaseLogger } from '@fluidframework/core-interfaces';
55
- import { ITelemetryContext } from '@fluidframework/runtime-definitions';
56
- import { ITelemetryLoggerExt } from '@fluidframework/telemetry-utils';
57
- import { MessageType } from '@fluidframework/protocol-definitions';
58
- import { MonitoringContext } from '@fluidframework/telemetry-utils/internal';
59
- import { NamedFluidDataStoreRegistryEntries } from '@fluidframework/runtime-definitions/internal';
60
- import { SummarizeInternalFn } from '@fluidframework/runtime-definitions/internal';
61
- import { TypedEventEmitter } from '@fluid-internal/client-utils';
62
-
63
- /* Excluded from this release type: agentSchedulerId */
64
-
65
- /* Excluded from this release type: AllowInactiveRequestHeaderKey */
66
-
67
- /** True if a tombstoned object should be returned without erroring
68
- * @alpha
69
- */
70
- export declare const AllowTombstoneRequestHeaderKey = "allowTombstone";
71
-
72
- /* Excluded from this release type: ChannelCollection */
73
-
74
- /* Excluded from this release type: ChannelCollectionFactory */
75
-
76
- /* Excluded from this release type: CompatModeBehavior */
77
-
78
- /**
79
- * Available compression algorithms for op compression.
80
- * @alpha
81
- */
82
- export declare enum CompressionAlgorithms {
83
- lz4 = "lz4"
84
- }
85
-
86
- /**
87
- * @alpha
88
- */
89
- export declare enum ContainerMessageType {
90
- FluidDataStoreOp = "component",
91
- Attach = "attach",
92
- ChunkedOp = "chunkedOp",
93
- BlobAttach = "blobAttach",
94
- Rejoin = "rejoin",
95
- Alias = "alias",
96
- /**
97
- * An op containing an IdRange of Ids allocated using the runtime's IdCompressor since
98
- * the last allocation op was sent.
99
- * See the [IdCompressor README](./id-compressor/README.md) for more details.
100
- */
101
- IdAllocation = "idAllocation",
102
- /**
103
- * An op that changes document schema
104
- */
105
- DocumentSchemaChange = "schema",
106
- /**
107
- * Garbage collection specific op. This is sent by the summarizer client when GC runs. It's used to synchronize GC
108
- * state across all clients.
109
- */
110
- GC = "GC"
111
- }
112
-
113
- /**
114
- * Represents the runtime of the container. Contains helper functions/state of the container.
115
- * It will define the store level mappings.
116
- * @alpha
117
- */
118
- export declare class ContainerRuntime extends TypedEventEmitter<IContainerRuntimeEvents & ISummarizerEvents> implements IContainerRuntime, IRuntime, ISummarizerRuntime, ISummarizerInternalsProvider, IProvideFluidHandleContext {
119
- private readonly registry;
120
- private readonly metadata;
121
- private readonly runtimeOptions;
122
- private readonly containerScope;
123
- readonly logger: ITelemetryLoggerExt;
124
- private readonly _storage;
125
- private readonly createIdCompressor;
126
- private readonly documentsSchemaController;
127
- private readonly requestHandler?;
128
- private readonly summaryConfiguration;
129
- /**
130
- * Load the stores from a snapshot and returns the runtime.
131
- * @param params - An object housing the runtime properties:
132
- * - context - Context of the container.
133
- * - registryEntries - Mapping from data store types to their corresponding factories.
134
- * - existing - Pass 'true' if loading from an existing snapshot.
135
- * - requestHandler - (optional) Request handler for the request() method of the container runtime.
136
- * Only relevant for back-compat while we remove the request() method and move fully to entryPoint as the main pattern.
137
- * - runtimeOptions - Additional options to be passed to the runtime
138
- * - containerScope - runtime services provided with context
139
- * - containerRuntimeCtor - Constructor to use to create the ContainerRuntime instance.
140
- * This allows mixin classes to leverage this method to define their own async initializer.
141
- * - provideEntryPoint - Promise that resolves to an object which will act as entryPoint for the Container.
142
- * This object should provide all the functionality that the Container is expected to provide to the loader layer.
143
- */
144
- static loadRuntime(params: {
145
- context: IContainerContext;
146
- registryEntries: NamedFluidDataStoreRegistryEntries;
147
- existing: boolean;
148
- runtimeOptions?: IContainerRuntimeOptions;
149
- containerScope?: FluidObject;
150
- containerRuntimeCtor?: typeof ContainerRuntime;
151
- /** @deprecated Will be removed once Loader LTS version is "2.0.0-internal.7.0.0". Migrate all usage of IFluidRouter to the "entryPoint" pattern. Refer to Removing-IFluidRouter.md */
152
- requestHandler?: (request: IRequest, runtime: IContainerRuntime) => Promise<IResponse>;
153
- provideEntryPoint: (containerRuntime: IContainerRuntime) => Promise<FluidObject>;
154
- }): Promise<ContainerRuntime>;
155
- readonly options: Record<string | number, any>;
156
- private imminentClosure;
157
- private readonly _getClientId;
158
- get clientId(): string | undefined;
159
- readonly clientDetails: IClientDetails;
160
- get storage(): IDocumentStorageService;
161
- get containerRuntime(): this;
162
- private readonly submitFn;
163
- /**
164
- * Although current IContainerContext guarantees submitBatchFn, it is not available on older loaders.
165
- */
166
- private readonly submitBatchFn;
167
- private readonly submitSummaryFn;
168
- private readonly submitSignalFn;
169
- readonly disposeFn: (error?: ICriticalContainerError) => void;
170
- readonly closeFn: (error?: ICriticalContainerError) => void;
171
- get flushMode(): FlushMode;
172
- get scope(): FluidObject;
173
- get IFluidDataStoreRegistry(): IFluidDataStoreRegistry;
174
- private readonly _getAttachState;
175
- get attachState(): AttachState;
176
- get documentSchema(): {
177
- explicitSchemaControl?: true | undefined;
178
- compressionLz4?: true | undefined;
179
- idCompressorMode?: IdCompressorMode;
180
- opGroupingEnabled?: true | undefined;
181
- disallowedVersions?: string[] | undefined;
182
- };
183
- private _idCompressor;
184
- private pendingIdCompressorOps;
185
- private readonly skipSavedCompressorOps;
186
- get idCompressorMode(): IdCompressorMode;
187
- /**
188
- * See IContainerRuntimeBase.idCompressor() for details.
189
- */
190
- get idCompressor(): (IIdCompressor & IIdCompressorCore) | undefined;
191
- /**
192
- * True if we have ID compressor loading in-flight (async operation). Useful only for
193
- * this.idCompressorMode === "delayed" mode
194
- */
195
- protected _loadIdCompressor: Promise<void> | undefined;
196
- /**
197
- * See IContainerRuntimeBase.generateDocumentUniqueId() for details.
198
- */
199
- generateDocumentUniqueId(): string | (number & {
200
- readonly SessionUnique: "cea55054-6b82-4cbf-ad19-1fa645ea3b3e";
201
- } & {
202
- readonly OpNormalized: "9209432d-a959-4df7-b2ad-767ead4dbcae";
203
- });
204
- get IFluidHandleContext(): IFluidHandleContext;
205
- private readonly handleContext;
206
- /**
207
- * This is a proxy to the delta manager provided by the container context (innerDeltaManager). It restricts certain
208
- * accesses such as sets "read-only" mode for the summarizer client. This is the default delta manager that should
209
- * be used unless the innerDeltaManager is required.
210
- */
211
- readonly deltaManager: IDeltaManager<ISequencedDocumentMessage, IDocumentMessage>;
212
- /**
213
- * The delta manager provided by the container context. By default, using the default delta manager (proxy)
214
- * should be sufficient. This should be used only if necessary. For example, for validating and propagating connected
215
- * events which requires access to the actual real only info, this is needed.
216
- */
217
- private readonly innerDeltaManager;
218
- private readonly mc;
219
- private readonly summarizerClientElection?;
220
- /**
221
- * summaryManager will only be created if this client is permitted to spawn a summarizing client
222
- * It is created only by interactive client, i.e. summarizer client, as well as non-interactive bots
223
- * do not create it (see SummarizerClientElection.clientDetailsPermitElection() for details)
224
- */
225
- private readonly summaryManager?;
226
- private readonly summaryCollection;
227
- private readonly summarizerNode;
228
- private readonly maxConsecutiveReconnects;
229
- private readonly defaultMaxConsecutiveReconnects;
230
- private _orderSequentiallyCalls;
231
- private readonly _flushMode;
232
- private flushTaskExists;
233
- private _connected;
234
- private consecutiveReconnects;
235
- /**
236
- * Used to delay transition to "connected" state while we upload
237
- * attachment blobs that were added while disconnected
238
- */
239
- private delayConnectClientId?;
240
- private ensureNoDataModelChangesCalls;
241
- /**
242
- * Tracks the number of detected reentrant ops to report,
243
- * in order to self-throttle the telemetry events.
244
- *
245
- * This should be removed as part of ADO:2322
246
- */
247
- private opReentryCallsToReport;
248
- /**
249
- * Invokes the given callback and expects that no ops are submitted
250
- * until execution finishes. If an op is submitted, an error will be raised.
251
- *
252
- * Can be disabled by feature gate `Fluid.ContainerRuntime.DisableOpReentryCheck`
253
- *
254
- * @param callback - the callback to be invoked
255
- */
256
- ensureNoDataModelChanges<T>(callback: () => T): T;
257
- get connected(): boolean;
258
- /** clientId of parent (non-summarizing) container that owns summarizer container */
259
- get summarizerClientId(): string | undefined;
260
- private _disposed;
261
- get disposed(): boolean;
262
- private dirtyContainer;
263
- private emitDirtyDocumentEvent;
264
- private readonly enableOpReentryCheck;
265
- private readonly disableAttachReorder;
266
- private readonly closeSummarizerDelayMs;
267
- /**
268
- * If true, summary generated is validate before uploading it to the server. With single commit summaries,
269
- * summaries will be accepted once uploaded, so they should be validated before upload. However, this can
270
- * currently be controlled via a feature flag as its a new functionality.
271
- */
272
- private readonly validateSummaryBeforeUpload;
273
- private readonly defaultTelemetrySignalSampleCount;
274
- private readonly _perfSignalData;
275
- /**
276
- * Summarizer is responsible for coordinating when to send generate and send summaries.
277
- * It is the main entry point for summary work.
278
- * It is created only by summarizing container (i.e. one with clientType === "summarizer")
279
- */
280
- private readonly _summarizer?;
281
- private readonly scheduleManager;
282
- private readonly blobManager;
283
- private readonly pendingStateManager;
284
- private readonly outbox;
285
- private readonly garbageCollector;
286
- private readonly channelCollection;
287
- private readonly remoteMessageProcessor;
288
- /** The last message processed at the time of the last summary. */
289
- private messageAtLastSummary;
290
- private get summarizer();
291
- private readonly summariesDisabled;
292
- private isSummariesDisabled;
293
- private readonly maxOpsSinceLastSummary;
294
- private getMaxOpsSinceLastSummary;
295
- private readonly initialSummarizerDelayMs;
296
- private getInitialSummarizerDelayMs;
297
- private readonly createContainerMetadata;
298
- /**
299
- * The summary number of the next summary that will be generated for this container. This is incremented every time
300
- * a summary is generated.
301
- */
302
- private nextSummaryNumber;
303
- /** If false, loading or using a Tombstoned object should merely log, not fail */
304
- get gcTombstoneEnforcementAllowed(): boolean;
305
- /** If true, throw an error when a tombstone data store is used. */
306
- get gcThrowOnTombstoneUsage(): boolean;
307
- /**
308
- * GUID to identify a document in telemetry
309
- * ! Note: should not be used for anything other than telemetry and is not considered a stable GUID
310
- */
311
- private readonly telemetryDocumentId;
312
- /**
313
- * Whether this client is the summarizer client itself (type is summarizerClientType)
314
- */
315
- private readonly isSummarizerClient;
316
- /**
317
- * The id of the version used to initially load this runtime, or undefined if it's newly created.
318
- */
319
- private readonly loadedFromVersionId;
320
- /**
321
- * It a cache for holding mapping for loading groupIds with its snapshot from the service. Add expiry policy of 1 minute.
322
- * Starting with 1 min and based on recorded usage we can tweak it later on.
323
- */
324
- private readonly snapshotCacheForLoadingGroupIds;
325
- /***/
326
- protected constructor(context: IContainerContext, registry: IFluidDataStoreRegistry, metadata: IContainerRuntimeMetadata | undefined, electedSummarizerData: ISerializedElection | undefined, chunks: [string, string[]][], dataStoreAliasMap: [string, string][], runtimeOptions: Readonly<Required<IContainerRuntimeOptions>>, containerScope: FluidObject, logger: ITelemetryLoggerExt, existing: boolean, blobManagerSnapshot: IBlobManagerLoadInfo, _storage: IDocumentStorageService, createIdCompressor: () => Promise<IIdCompressor & IIdCompressorCore>, documentsSchemaController: DocumentsSchemaController, featureGatesForTelemetry: Record<string, boolean | number | undefined>, provideEntryPoint: (containerRuntime: IContainerRuntime) => Promise<FluidObject>, requestHandler?: ((request: IRequest, runtime: IContainerRuntime) => Promise<IResponse>) | undefined, summaryConfiguration?: ISummaryConfiguration);
327
- onSchemaChange(schema: IDocumentSchemaCurrent): void;
328
- getCreateChildSummarizerNodeFn(id: string, createParam: CreateChildSummarizerNodeParam): (summarizeInternal: SummarizeInternalFn, getGCDataFn: (fullGC?: boolean) => Promise<IGarbageCollectionData>) => ISummarizerNodeWithGC;
329
- deleteChildSummarizerNode(id: string): void;
330
- makeLocallyVisible(): void;
331
- setChannelDirty(address: string): void;
332
- /**
333
- * Initializes the state from the base snapshot this container runtime loaded from.
334
- */
335
- private initializeBaseState;
336
- dispose(error?: Error): void;
337
- /**
338
- * Api to fetch the snapshot from the service for a loadingGroupIds.
339
- * @param loadingGroupIds - LoadingGroupId for which the snapshot is asked for.
340
- * @param pathParts - Parts of the path, which we want to extract from the snapshot tree.
341
- * @returns - snapshotTree and the sequence number of the snapshot.
342
- */
343
- getSnapshotForLoadingGroupId(loadingGroupIds: string[], pathParts: string[]): Promise<{
344
- snapshotTree: ISnapshotTree;
345
- sequenceNumber: number;
346
- }>;
347
- /**
348
- * Api to find a snapshot tree inside a bigger snapshot tree based on the path in the pathParts array.
349
- * @param snapshotTree - snapshot tree to look into.
350
- * @param pathParts - Part of the path, which we want to extract from the snapshot tree.
351
- * @param hasIsolatedChannels - whether the channels are present inside ".channels" subtree. Older
352
- * snapshots will not have trees inside ".channels", so check that.
353
- * @returns - requested snapshot tree based on the path parts.
354
- */
355
- private getSnapshotTreeForPath;
356
- /**
357
- * Notifies this object about the request made to the container.
358
- * @param request - Request made to the handler.
359
- * @deprecated Will be removed in future major release. This method needs to stay private until LTS version of Loader moves to "2.0.0-internal.7.0.0".
360
- */
361
- private request;
362
- /**
363
- * Resolves URI representing handle
364
- * @param request - Request made to the handler.
365
- */
366
- resolveHandle(request: IRequest): Promise<IResponse>;
367
- /**
368
- * {@inheritDoc @fluidframework/container-definitions#IRuntime.getEntryPoint}
369
- */
370
- getEntryPoint(): Promise<FluidObject>;
371
- private readonly entryPoint;
372
- private internalId;
373
- /** Adds the container's metadata to the given summary tree. */
374
- private addMetadataToSummary;
375
- protected addContainerStateToSummary(summaryTree: ISummaryTreeWithStats, fullTree: boolean, trackState: boolean, telemetryContext?: ITelemetryContext): void;
376
- private shouldContinueReconnecting;
377
- private resetReconnectCount;
378
- private replayPendingStates;
379
- /**
380
- * Parse an op's type and actual content from given serialized content
381
- * ! Note: this format needs to be in-line with what is set in the "ContainerRuntime.submit(...)" method
382
- */
383
- private parseLocalOpContent;
384
- private applyStashedOp;
385
- private loadIdCompressor;
386
- setConnectionState(connected: boolean, clientId?: string): void;
387
- private setConnectionStateCore;
388
- notifyOpReplay(message: ISequencedDocumentMessage): Promise<void>;
389
- process(messageArg: ISequencedDocumentMessage, local: boolean): void;
390
- private _processedClientSequenceNumber;
391
- /**
392
- * Direct the message to the correct subsystem for processing, and implement other side effects
393
- */
394
- private processCore;
395
- /**
396
- * Assuming the given message is also a TypedContainerRuntimeMessage,
397
- * checks its type and dispatches the message to the appropriate handler in the runtime.
398
- * Throws a DataProcessingError if the message looks like but doesn't conform to a known TypedContainerRuntimeMessage type.
399
- */
400
- private validateAndProcessRuntimeMessage;
401
- /**
402
- * Emits the Signal event and update the perf signal data.
403
- * @param clientSignalSequenceNumber - is the client signal sequence number to be uploaded.
404
- */
405
- private sendSignalTelemetryEvent;
406
- processSignal(message: ISignalMessage, local: boolean): void;
407
- /**
408
- * Flush the pending ops manually.
409
- * This method is expected to be called at the end of a batch.
410
- */
411
- private flush;
412
- /**
413
- * {@inheritDoc @fluidframework/runtime-definitions#IContainerRuntimeBase.orderSequentially}
414
- */
415
- orderSequentially<T>(callback: () => T): T;
416
- /**
417
- * Returns the aliased data store's entryPoint, given the alias.
418
- * @param alias - The alias for the data store.
419
- * @returns The data store's entry point ({@link @fluidframework/core-interfaces#IFluidHandle}) if it exists and is aliased.
420
- * Returns undefined if no data store has been assigned the given alias.
421
- */
422
- getAliasedDataStoreEntryPoint(alias: string): Promise<IFluidHandle<FluidObject> | undefined>;
423
- createDetachedDataStore(pkg: Readonly<string[]>, loadingGroupId?: string): IFluidDataStoreContextDetached;
424
- createDataStore(pkg: Readonly<string | string[]>, loadingGroupId?: string): Promise<IDataStore>;
425
- /**
426
- * @deprecated 0.16 Issue #1537, #3631
427
- */
428
- _createDataStoreWithProps(pkg: Readonly<string | string[]>, props?: any): Promise<IDataStore>;
429
- private canSendOps;
430
- /**
431
- * Are we in the middle of batching ops together?
432
- */
433
- private currentlyBatching;
434
- private readonly _quorum;
435
- getQuorum(): IQuorumClients;
436
- private readonly _audience;
437
- getAudience(): IAudience;
438
- /**
439
- * Returns true of container is dirty, i.e. there are some pending local changes that
440
- * either were not sent out to delta stream or were not yet acknowledged.
441
- */
442
- get isDirty(): boolean;
443
- private isContainerMessageDirtyable;
444
- private createNewSignalEnvelope;
445
- /**
446
- * Submits the signal to be sent to other clients.
447
- * @param type - Type of the signal.
448
- * @param content - Content of the signal. Should be a JSON serializable object or primitive.
449
- * @param targetClientId - When specified, the signal is only sent to the provided client id.
450
- */
451
- submitSignal(type: string, content: unknown, targetClientId?: string): void;
452
- setAttachState(attachState: AttachState.Attaching | AttachState.Attached): void;
453
- /**
454
- * Create a summary. Used when attaching or serializing a detached container.
455
- *
456
- * @param blobRedirectTable - A table passed during the attach process. While detached, blob upload is supported
457
- * using IDs generated locally. After attach, these IDs cannot be used, so this table maps the old local IDs to the
458
- * new storage IDs so requests can be redirected.
459
- * @param telemetryContext - summary data passed through the layers for telemetry purposes
460
- */
461
- createSummary(blobRedirectTable?: Map<string, string>, telemetryContext?: ITelemetryContext): ISummaryTree;
462
- readonly getAbsoluteUrl: (relativeUrl: string) => Promise<string | undefined>;
463
- private summarizeInternal;
464
- /**
465
- * Returns a summary of the runtime at the current sequence number.
466
- */
467
- summarize(options: {
468
- /** True to generate the full tree with no handle reuse optimizations; defaults to false */
469
- fullTree?: boolean;
470
- /** True to track the state for this summary in the SummarizerNodes; defaults to true */
471
- trackState?: boolean;
472
- /** Logger to use for correlated summary events */
473
- summaryLogger?: ITelemetryLoggerExt;
474
- /** True to run garbage collection before summarizing; defaults to true */
475
- runGC?: boolean;
476
- /** True to generate full GC data */
477
- fullGC?: boolean;
478
- /** True to run GC sweep phase after the mark phase */
479
- runSweep?: boolean;
480
- }): Promise<ISummaryTreeWithStats>;
481
- /**
482
- * Before GC runs, called by the garbage collector to update any pending GC state. This is mainly used to notify
483
- * the garbage collector of references detected since the last GC run. Most references are notified immediately
484
- * but there can be some for which async operation is required (such as detecting new root data stores).
485
- * @see IGarbageCollectionRuntime.updateStateBeforeGC
486
- */
487
- updateStateBeforeGC(): Promise<void>;
488
- private getGCDataInternal;
489
- /**
490
- * Generates and returns the GC data for this container.
491
- * @param fullGC - true to bypass optimizations and force full generation of GC data.
492
- * @see IGarbageCollectionRuntime.getGCData
493
- */
494
- getGCData(fullGC?: boolean): Promise<IGarbageCollectionData>;
495
- /**
496
- * After GC has run, called to notify this container's nodes of routes that are used in it.
497
- * @param usedRoutes - The routes that are used in all nodes in this Container.
498
- * @see IGarbageCollectionRuntime.updateUsedRoutes
499
- */
500
- updateUsedRoutes(usedRoutes: readonly string[]): void;
501
- /**
502
- * After GC has run and identified nodes that are sweep ready, this is called to delete the sweep ready nodes.
503
- * @param sweepReadyRoutes - The routes of nodes that are sweep ready and should be deleted.
504
- * @returns The routes of nodes that were deleted.
505
- */
506
- deleteSweepReadyNodes(sweepReadyRoutes: readonly string[]): readonly string[];
507
- /**
508
- * This is called to update objects that are tombstones.
509
- *
510
- * A Tombstoned object has been unreferenced long enough that GC knows it won't be referenced again.
511
- * Tombstoned objects are eventually deleted by GC.
512
- *
513
- * @param tombstonedRoutes - Data store and attachment blob routes that are tombstones in this Container.
514
- */
515
- updateTombstonedRoutes(tombstonedRoutes: readonly string[]): void;
516
- /**
517
- * Returns a server generated referenced timestamp to be used to track unreferenced nodes by GC.
518
- */
519
- getCurrentReferenceTimestampMs(): number | undefined;
520
- /**
521
- * Returns the type of the GC node. Currently, there are nodes that belong to the root ("/"), data stores or
522
- * blob manager.
523
- */
524
- getNodeType(nodePath: string): GCNodeType;
525
- /**
526
- * Called by GC to retrieve the package path of the node with the given path. The node should belong to a
527
- * data store or an attachment blob.
528
- */
529
- getGCNodePackagePath(nodePath: string): Promise<readonly string[] | undefined>;
530
- /**
531
- * Returns whether a given path is for attachment blobs that are in the format - "/BlobManager.basePath/...".
532
- */
533
- private isBlobPath;
534
- /**
535
- * From a given list of routes, separate and return routes that belong to blob manager and data stores.
536
- * @param routes - A list of routes that can belong to data stores or blob manager.
537
- * @returns Two route lists - One that contains routes for blob manager and another one that contains routes
538
- * for data stores.
539
- */
540
- private getDataStoreAndBlobManagerRoutes;
541
- /**
542
- * Runs garbage collection and updates the reference / used state of the nodes in the container.
543
- * @returns the statistics of the garbage collection run; undefined if GC did not run.
544
- */
545
- collectGarbage(options: {
546
- /** Logger to use for logging GC events */
547
- logger?: ITelemetryLoggerExt;
548
- /** True to run GC sweep phase after the mark phase */
549
- runSweep?: boolean;
550
- /** True to generate full GC data */
551
- fullGC?: boolean;
552
- }, telemetryContext?: ITelemetryContext): Promise<IGCStats | undefined>;
553
- /**
554
- * Called when a new outbound reference is added to another node. This is used by garbage collection to identify
555
- * all references added in the system.
556
- * @param srcHandle - The handle of the node that added the reference.
557
- * @param outboundHandle - The handle of the outbound node that is referenced.
558
- */
559
- addedGCOutboundReference(srcHandle: {
560
- absolutePath: string;
561
- }, outboundHandle: {
562
- absolutePath: string;
563
- }): void;
564
- /**
565
- * Generates the summary tree, uploads it to storage, and then submits the summarize op.
566
- * This is intended to be called by the summarizer, since it is the implementation of
567
- * ISummarizerInternalsProvider.submitSummary.
568
- * It takes care of state management at the container level, including pausing inbound
569
- * op processing, updating SummarizerNode state tracking, and garbage collection.
570
- * @param options - options controlling how the summary is generated or submitted
571
- */
572
- submitSummary(options: ISubmitSummaryOptions): Promise<SubmitSummaryResult>;
573
- /**
574
- * This helper is called during summarization. If the container is dirty, it will return a failed summarize result
575
- * (IBaseSummarizeResult) unless this is the final summarize attempt and SkipFailingIncorrectSummary option is set.
576
- * @param logger - The logger to be used for sending telemetry.
577
- * @param referenceSequenceNumber - The reference sequence number of the summary attempt.
578
- * @param minimumSequenceNumber - The minimum sequence number of the summary attempt.
579
- * @param finalAttempt - Whether this is the final summary attempt.
580
- * @param beforeSummaryGeneration - Whether this is called before summary generation or after.
581
- * @returns failed summarize result (IBaseSummarizeResult) if summary should be failed, undefined otherwise.
582
- */
583
- private shouldFailSummaryOnPendingOps;
584
- private get pendingMessagesCount();
585
- private hasPendingMessages;
586
- private updateDocumentDirtyState;
587
- submitMessage(type: ContainerMessageType.FluidDataStoreOp | ContainerMessageType.Alias | ContainerMessageType.Attach, contents: any, localOpMetadata?: unknown): void;
588
- uploadBlob(blob: ArrayBufferLike, signal?: AbortSignal): Promise<IFluidHandle<ArrayBufferLike>>;
589
- private submitIdAllocationOpIfNeeded;
590
- private submit;
591
- private scheduleFlush;
592
- private submitSummaryMessage;
593
- /**
594
- * Throw an error if the runtime is closed. Methods that are expected to potentially
595
- * be called after dispose due to asynchrony should not call this.
596
- */
597
- private verifyNotClosed;
598
- private verifyCanSubmitOps;
599
- private reSubmitBatch;
600
- private reSubmit;
601
- /**
602
- * Finds the right store and asks it to resubmit the message. This typically happens when we
603
- * reconnect and there are pending messages.
604
- * ! Note: successfully resubmitting an op that has been successfully sequenced is not possible due to checks in the ConnectionStateHandler (Loader layer)
605
- * @param message - The original LocalContainerRuntimeMessage.
606
- * @param localOpMetadata - The local metadata associated with the original message.
607
- */
608
- private reSubmitCore;
609
- private rollback;
610
- /** Implementation of ISummarizerInternalsProvider.refreshLatestSummaryAck */
611
- refreshLatestSummaryAck(options: IRefreshSummaryAckOptions): Promise<void>;
612
- /**
613
- * Fetches the latest snapshot from storage to refresh the cache as a performance optimization and closes the
614
- * summarizer to reload from new state.
615
- * @param summaryLogger - logger to use when fetching snapshot from storage
616
- * @returns a generic summarization error
617
- */
618
- private prefetchLatestSummaryThenClose;
619
- private closeStaleSummarizer;
620
- /**
621
- * Downloads the latest snapshot from storage.
622
- * By default, it also closes the container after downloading the snapshot. However, this may be
623
- * overridden via options.
624
- */
625
- private fetchLatestSnapshotFromStorage;
626
- getPendingLocalState(props?: IGetPendingLocalStateProps): unknown;
627
- summarizeOnDemand(options: IOnDemandSummarizeOptions): ISummarizeResults;
628
- enqueueSummarize(options: IEnqueueSummarizeOptions): EnqueueSummarizeResult;
629
- /**
630
- * Forms a function that will create and retrieve a Summarizer.
631
- */
632
- private formCreateSummarizerFn;
633
- private validateSummaryHeuristicConfiguration;
634
- private get groupedBatchingEnabled();
635
- }
636
-
637
- /* Excluded from this release type: ContainerRuntimeMessage */
638
-
639
- /**
640
- * Current version known properties that define document schema
641
- * This must be bumped whenever the format of document schema or protocol for changing the current document schema changes.
642
- * Ex: adding a new configuration property (under IDocumentSchema.runtime) does not require changing this version.
643
- * Ex: Changing the 'document schema acceptance' mechanism from convert-and-swap to one requiring consensus does require changing this version.
644
- * @alpha
645
- */
646
- export declare const currentDocumentVersionSchema = 1;
647
-
648
- /* Excluded from this release type: DataStoreContexts */
649
-
650
- /**
651
- * @alpha
652
- */
653
- export declare const DefaultSummaryConfiguration: ISummaryConfiguration;
654
-
655
- /* Excluded from this release type: detectOutboundReferences */
656
-
657
- /** @alpha */
658
- export declare const disabledCompressionConfig: ICompressionRuntimeOptions;
659
-
660
- /**
661
- * Descripe allowed type for properties in document schema.
662
- * Please note that for all property types we should use undefined to indicate that particular capability is off.
663
- * Using false, or some string value (like "off") will result in clients who do not understand that property failing, whereas
664
- * we want them to continue to collaborate alongside clients who support that capability, but such capability is shipping dark for now.
665
- * @alpha
666
- */
667
- export declare type DocumentSchemaValueType = string | string[] | true | number | undefined;
668
-
669
- /**
670
- * Controller of document schema.
671
- *
672
- * Recommended pre-reading: https://github.com/microsoft/FluidFramework/blob/main/packages/dds/SchemaVersioning.md
673
- *
674
- * This class manages current document schema and transitions between document schemas.
675
- * At the moment, it only focuses on subset of document schema, specifically - how FluidFramework runtime serializes data
676
- * (summary and op format), features & capabilities that a version of runtime has to support and understand in
677
- * order to collaborate on a document.
678
- * New features that modify document format have to be included in document schema definition.
679
- * Usage of such features could only happen after document schema has been updated to reflect such feature.
680
- *
681
- * This formality allows clients that do not understand such features to fail right away when they observe
682
- * document schema listing capabilities that such client does not understand.
683
- * Old clients will fail in predictable way. This allows us to
684
- * 1) Immediately see such issues and adjust if features are enabled too early, before changes have been saturated.
685
- * 2) There is no way to get to 100% saturation with new code. Even if we have 99.99% saturation, there are
686
- * still 0.01% of clients who will fail. Failing early and predictably ensures they have no chance to limp along
687
- * and potentially corrupt the document. This is especially true for summarizer client, who could simply "undo"
688
- * changes it does not understands.
689
- *
690
- * It's important to note how it overlaps with feature gates and safe velocity.
691
- * If new feature was in use, that resulted in a number of documents referencing such feature in document schema.
692
- * But, developers (through code deployment or feature gates) could disable usage of such features.
693
- * That will stop a process of further document schema changes (for documents that were not using such feature).
694
- * And documents that already list such capability in their schema will continue to do so. Later ensures that old
695
- * clients who do not understand such feature will continue to fail to open such documents, as such documents very
696
- * likely contain data in a new format.
697
- *
698
- * Controller operates with 4 schemas:
699
- * - document schema: whatever we loaded from summary metadata + ops. It follows eventuall consistency rules (i.e. like DDS).
700
- * - desired schema - what client is asking for to have (i.e. all the desired settings, based on runtime options / feature gates).
701
- * - session schema - current session schema. It's "and" of the above two schemas.
702
- * - future schema - "or" of document and desires schemas.
703
- *
704
- * "or" & "and" operators are defined individually for each property. For Boolean properties it's literally &&, || operators.
705
- * But for other properties it's more nuanced.
706
- *
707
- * Whenver document schema does not match future schema, controller will send an op that attempts to changs documents schema to
708
- * future schema.
709
- *
710
- * Users of this class need to use DocumentsSchemaController.sessionSchema to determine what features can be used.
711
- *
712
- * There are two modes this class can operate:
713
- * 1) Legacy mode. In such mode it does not issue any ops to change document schema. Any changes happen implicitly,
714
- * right away, and new features are available right away
715
- * 2) Non-legacy mode. In such mode any changes to schema require an op roundtrip. This class will manage such transitions.
716
- * However code should assume that any new features that were not enabled in a given document will not be available
717
- * for a given session. That's because this session may never send any ops (including read-only documents). Or it may
718
- * fail to convert schema.
719
- * This class promises eventual movement forward. I.e. if new feature is allowed (let's say - through feature gates),
720
- * then eventually all documents that are modified will have that feature reflected in their schema. It could require
721
- * multiple reloads / new sessions to get there (depends on if code reacts to schema changes right away, or only consults
722
- * schema on document load).
723
- *
724
- * How schemas are changed (in non-legacy mode):
725
- * If a client needs to change a schema, it will attempt to do so as part of normal ops sending process.
726
- * Changes happen in CAS (Compare-and-swap) fashion, i.e. client tells current schema and schema it wants to change to.
727
- * When a number of clients race to change a schema, then only one of them will win, all others will fail because they will
728
- * reference old schema that is no longer in effect.
729
- * Clients can retry, but current implementation is simply - they will not (and will rely on next session / reload to do
730
- * recalc and decide if schema needs to be changed or not).
731
- *
732
- * @alpha
733
- */
734
- export declare class DocumentsSchemaController {
735
- private readonly onSchemaChange;
736
- private explicitSchemaControl;
737
- private sendOp;
738
- private documentSchema;
739
- private readonly desiredSchema;
740
- private futureSchema;
741
- sessionSchema: IDocumentSchemaCurrent;
742
- /**
743
- * Constructs DocumentsSchemaController that controls current schema and processes around it, including changes in schema.
744
- * @param existing - Is the document existing document, or a new doc.
745
- * @param documentMetadataSchema - current document's schema, if present.
746
- * @param features - features of the document schema that current session wants to see enabled.
747
- * @param onSchemaChange - callback that is called whenever schema is changed (not called on creation / load, only when processing document schema change ops)
748
- */
749
- constructor(existing: boolean, documentMetadataSchema: IDocumentSchema | undefined, features: IDocumentSchemaFeatures, onSchemaChange: (schema: IDocumentSchemaCurrent) => void);
750
- summarizeDocumentSchema(refSeq: number): IDocumentSchemaCurrent | undefined;
751
- /**
752
- * Called by Container runtime whenever it is about to send some op.
753
- * It gives opportunity for controller to issue its own ops - we do not want to send ops if there are no local changes in document.
754
- * @returns Optional message to send.
755
- */
756
- maybeSendSchemaMessage(): IDocumentSchemaChangeMessage | undefined;
757
- /**
758
- * Process document schema change message
759
- * Called by ContainerRuntime whenever it sees document schema messages.
760
- * @param content - content of the message
761
- * @param local - whether op is local
762
- * @param sequenceNumber - sequence number of the op
763
- * @returns - true if schema was accepted, otherwise false (rejected due to failed CAS)
764
- */
765
- processDocumentSchemaOp(content: IDocumentSchemaChangeMessage, local: boolean, sequenceNumber: number): boolean;
766
- onDisconnect(): void;
767
- }
768
-
769
- /**
770
- * @alpha
771
- */
772
- export declare type EnqueueSummarizeResult = (ISummarizeResults & {
773
- /**
774
- * Indicates that another summarize attempt is not already enqueued,
775
- * and this attempt has been enqueued.
776
- */
777
- readonly alreadyEnqueued?: undefined;
778
- }) | (ISummarizeResults & {
779
- /** Indicates that another summarize attempt was already enqueued. */
780
- readonly alreadyEnqueued: true;
781
- /**
782
- * Indicates that the other enqueued summarize attempt was abandoned,
783
- * and this attempt has been enqueued enqueued.
784
- */
785
- readonly overridden: true;
786
- }) | {
787
- /** Indicates that another summarize attempt was already enqueued. */
788
- readonly alreadyEnqueued: true;
789
- /**
790
- * Indicates that the other enqueued summarize attempt remains enqueued,
791
- * and this attempt has not been enqueued.
792
- */
793
- readonly overridden?: undefined;
794
- };
795
-
796
- /* Excluded from this release type: FluidDataStoreContext */
797
-
798
- /* Excluded from this release type: FluidDataStoreRegistry */
799
-
800
- /**
801
- * @see IGCMetadata.gcFeatureMatrix and @see gcGenerationOptionName
802
- * @alpha
803
- */
804
- export declare type GCFeatureMatrix = {
805
- /**
806
- * The GC Generation value in effect when this file was created.
807
- * Gives a way for an app to disqualify old files from GC Sweep.
808
- * Provided via Container Runtime Options.
809
- */
810
- gcGeneration?: number;
811
- /** Deprecated property from legacy type. Will not be set concurrently with gcGeneration */
812
- tombstoneGeneration?: undefined;
813
- } | {
814
- /**
815
- * The Tombstone Generation value in effect when this file was created.
816
- * Legacy - new containers would get gcGeneration instead (if anything)
817
- */
818
- tombstoneGeneration: number;
819
- };
820
-
821
- /**
822
- * The types of GC nodes in the GC reference graph.
823
- * @alpha
824
- */
825
- export declare const GCNodeType: {
826
- DataStore: string;
827
- SubDataStore: string;
828
- Blob: string;
829
- Other: string;
830
- };
831
-
832
- /**
833
- * @alpha
834
- */
835
- export declare type GCNodeType = (typeof GCNodeType)[keyof typeof GCNodeType];
836
-
837
- /**
838
- * @alpha
839
- */
840
- export declare type GCVersion = number;
841
-
842
- /**
843
- * A single summary which has already been acked by the server.
844
- * @alpha
845
- */
846
- export declare interface IAckedSummary {
847
- readonly summaryOp: ISummaryOpMessage;
848
- readonly summaryAck: ISummaryAckMessage;
849
- }
850
-
851
- /**
852
- * @alpha
853
- */
854
- export declare interface IAckSummaryResult {
855
- readonly summaryAckOp: ISummaryAckMessage;
856
- readonly ackNackDuration: number;
857
- }
858
-
859
- /**
860
- * Base results for all submitSummary attempts.
861
- * @alpha
862
- */
863
- export declare interface IBaseSummarizeResult {
864
- readonly stage: "base";
865
- /** Error object related to failed summarize attempt. */
866
- readonly error: any;
867
- /** Reference sequence number as of the generate summary attempt. */
868
- readonly referenceSequenceNumber: number;
869
- readonly minimumSequenceNumber: number;
870
- }
871
-
872
- /**
873
- * Information from a snapshot needed to load BlobManager
874
- * @alpha
875
- */
876
- export declare interface IBlobManagerLoadInfo {
877
- ids?: string[];
878
- redirectTable?: [string, string][];
879
- }
880
-
881
- /**
882
- * @alpha
883
- */
884
- export declare interface IBroadcastSummaryResult {
885
- readonly summarizeOp: ISummaryOpMessage;
886
- readonly broadcastDuration: number;
887
- }
888
-
889
- /**
890
- * Similar to AbortController, but using promise instead of events
891
- * @alpha
892
- */
893
- export declare interface ICancellableSummarizerController extends ISummaryCancellationToken {
894
- stop(reason: SummarizerStopReason): void;
895
- }
896
-
897
- /**
898
- * Similar to AbortSignal, but using promise instead of events
899
- * @param T - cancellation reason type
900
- * @alpha
901
- */
902
- export declare interface ICancellationToken<T> {
903
- /** Tells if this cancellable token is cancelled */
904
- readonly cancelled: boolean;
905
- /**
906
- * Promise that gets fulfilled when this cancellable token is cancelled
907
- * @returns reason of cancellation
908
- */
909
- readonly waitCancelled: Promise<T>;
910
- }
911
-
912
- /* Excluded from this release type: IChunkedOp */
913
-
914
- /**
915
- * Watches summaries created by a specific client.
916
- * @alpha
917
- */
918
- export declare interface IClientSummaryWatcher extends IDisposable {
919
- watchSummary(clientSequenceNumber: number): ISummary;
920
- waitFlushed(): Promise<IAckedSummary | undefined>;
921
- }
922
-
923
- /**
924
- * Options for op compression.
925
- * @alpha
926
- */
927
- export declare interface ICompressionRuntimeOptions {
928
- /**
929
- * The value the batch's content size must exceed for the batch to be compressed.
930
- * By default the value is 600 * 1024 = 614400 bytes. If the value is set to `Infinity`, compression will be disabled.
931
- */
932
- readonly minimumBatchSizeInBytes: number;
933
- /**
934
- * The compression algorithm that will be used to compress the op.
935
- * By default the value is `lz4` which is the only compression algorithm currently supported.
936
- */
937
- readonly compressionAlgorithm: CompressionAlgorithms;
938
- }
939
-
940
- /**
941
- * @alpha
942
- */
943
- export declare interface IConnectableRuntime {
944
- readonly disposed: boolean;
945
- readonly connected: boolean;
946
- readonly clientId: string | undefined;
947
- once(event: "connected" | "disconnected" | "dispose", listener: () => void): this;
948
- }
949
-
950
- /* Excluded from this release type: IContainerRuntimeMessageCompatDetails */
951
-
952
- /**
953
- * @alpha
954
- */
955
- export declare interface IContainerRuntimeMetadata extends ICreateContainerMetadata, IGCMetadata {
956
- readonly summaryFormatVersion: 1;
957
- /** @deprecated - used by old (prior to 2.0 RC3) runtimes */
958
- readonly message?: ISummaryMetadataMessage;
959
- /** The last message processed at the time of summary. Only primitive property types are added to the summary. */
960
- readonly lastMessage?: ISummaryMetadataMessage;
961
- /** True if channels are not isolated in .channels subtrees, otherwise isolated. */
962
- readonly disableIsolatedChannels?: true;
963
- /** The summary number for a container's summary. Incremented on summaries throughout its lifetime. */
964
- readonly summaryNumber?: number;
965
- /** GUID to identify a document in telemetry */
966
- readonly telemetryDocumentId?: string;
967
- readonly documentSchema?: IDocumentSchema;
968
- }
969
-
970
- /**
971
- * Options for container runtime.
972
- * @alpha
973
- */
974
- export declare interface IContainerRuntimeOptions {
975
- readonly summaryOptions?: ISummaryRuntimeOptions;
976
- readonly gcOptions?: IGCRuntimeOptions;
977
- /**
978
- * Affects the behavior while loading the runtime when the data verification check which
979
- * compares the DeltaManager sequence number (obtained from protocol in summary) to the
980
- * runtime sequence number (obtained from runtime metadata in summary) finds a mismatch.
981
- * 1. "close" (default) will close the container with an assertion.
982
- * 2. "log" will log an error event to telemetry, but still continue to load.
983
- * 3. "bypass" will skip the check entirely. This is not recommended.
984
- */
985
- readonly loadSequenceNumberVerification?: "close" | "log" | "bypass";
986
- /**
987
- * Sets the flush mode for the runtime. In Immediate flush mode the runtime will immediately
988
- * send all operations to the driver layer, while in TurnBased the operations will be buffered
989
- * and then sent them as a single batch at the end of the turn.
990
- * By default, flush mode is TurnBased.
991
- */
992
- readonly flushMode?: FlushMode;
993
- /**
994
- * Enables the runtime to compress ops. See {@link ICompressionRuntimeOptions}.
995
- */
996
- readonly compressionOptions?: ICompressionRuntimeOptions;
997
- /**
998
- * If specified, when in FlushMode.TurnBased, if the size of the ops between JS turns exceeds this value,
999
- * an error will be thrown and the container will close.
1000
- *
1001
- * If unspecified, the limit is 700Kb.
1002
- *
1003
- * 'Infinity' will disable any limit.
1004
- *
1005
- * @experimental This config should be driven by the connection with the service and will be moved in the future.
1006
- */
1007
- readonly maxBatchSizeInBytes?: number;
1008
- /**
1009
- * If the op payload needs to be chunked in order to work around the maximum size of the batch, this value represents
1010
- * how large the individual chunks will be. This is only supported when compression is enabled. If after compression, the
1011
- * batch content size exceeds this value, it will be chunked into smaller ops of this exact size.
1012
- *
1013
- * This value is a trade-off between having many small chunks vs fewer larger chunks and by default, the runtime is configured to use
1014
- * 200 * 1024 = 204800 bytes. This default value ensures that no compressed payload's content is able to exceed {@link IContainerRuntimeOptions.maxBatchSizeInBytes}
1015
- * regardless of the overhead of an individual op.
1016
- *
1017
- * Any value of `chunkSizeInBytes` exceeding {@link IContainerRuntimeOptions.maxBatchSizeInBytes} will disable this feature, therefore if a compressed batch's content
1018
- * size exceeds {@link IContainerRuntimeOptions.maxBatchSizeInBytes} after compression, the container will close with an instance of `GenericError` with
1019
- * the `BatchTooLarge` message.
1020
- */
1021
- readonly chunkSizeInBytes?: number;
1022
- /**
1023
- * Enable the IdCompressor in the runtime.
1024
- * @experimental Not ready for use.
1025
- */
1026
- readonly enableRuntimeIdCompressor?: IdCompressorMode;
1027
- /**
1028
- * If enabled, the runtime will block all attempts to send an op inside the
1029
- * {@link ContainerRuntime#ensureNoDataModelChanges} callback. The callback is used by
1030
- * {@link @fluidframework/shared-object-base#SharedObjectCore} for event handlers so enabling this
1031
- * will disallow modifying DDSes while handling DDS events.
1032
- *
1033
- * By default, the feature is disabled. If enabled from options, the `Fluid.ContainerRuntime.DisableOpReentryCheck`
1034
- * can be used to disable it at runtime.
1035
- */
1036
- readonly enableOpReentryCheck?: boolean;
1037
- /**
1038
- * If enabled, the runtime will group messages within a batch into a single
1039
- * message to be sent to the service.
1040
- * The grouping an ungrouping of such messages is handled by the "OpGroupingManager".
1041
- *
1042
- * By default, the feature is disabled. If enabled from options, the `Fluid.ContainerRuntime.DisableGroupedBatching`
1043
- * flag can be used to disable it at runtime.
1044
- *
1045
- * @experimental Not ready for use.
1046
- */
1047
- readonly enableGroupedBatching?: boolean;
1048
- /**
1049
- * When this property is set to true, it requires runtime to control is document schema properly through ops
1050
- * The benefit of this mode is that clients who do not understand schema will fail in predictable way, with predictable message,
1051
- * and will not attempt to limp along, which could cause data corruptions and crashes in random places.
1052
- * When this property is not set (or set to false), runtime operates in legacy mode, where new features (modifying document schema)
1053
- * are engaged as they become available, without giving legacy clients any chance to fail predictably.
1054
- */
1055
- readonly explicitSchemaControl?: boolean;
1056
- }
1057
-
1058
- /**
1059
- * @alpha
1060
- */
1061
- export declare interface ICreateContainerMetadata {
1062
- /** Runtime version of the container when it was first created */
1063
- createContainerRuntimeVersion?: string;
1064
- /** Timestamp of the container when it was first created */
1065
- createContainerTimestamp?: number;
1066
- }
1067
-
1068
- /**
1069
- * ID Compressor mode.
1070
- * "on" - compressor is On. It's loaded as part of container load. This mode is sticky - once on, compressor is On for all
1071
- * sessions for a given document. This results in IContainerRuntime.idCompressor to be always available.
1072
- * "delayed" - ID compressor bundle is loaded only on establishing of first delta connection, i.e. it does not impact boot of cotnainer.
1073
- * In such mode IContainerRuntime.idCompressor is not made available (unless previous sessions of same document had it "On").
1074
- * The only thing that is available is IContainerRuntime.generateDocumentUniqueId() that provides opportunistically short IDs.
1075
- * undefined - ID compressor is not loaded.
1076
- * While IContainerRuntime.generateDocumentUniqueId() is available, it will produce long IDs that are do not compress well.
1077
- *
1078
- * @alpha
1079
- */
1080
- export declare type IdCompressorMode = "on" | "delayed" | undefined;
1081
-
1082
- /**
1083
- * Document schema information.
1084
- * Describes overall shape of document schema, including unknown (to this version) properties.
1085
- *
1086
- * Used by runtime to make a call if it can understand document schema.
1087
- * If it can't, it should not continue with document and immediately fail, preventing random (cryptic) failures
1088
- * down the road and potentially corrupting documents.
1089
- * For now this structure and appropriate interpretation / behavior is focused only on runtime features.
1090
- * In the future that could be interpolated to more areas, including DDSs used, and even possibly - application
1091
- * schema.
1092
- *
1093
- * Runtime will ignore any properties at the root that it does not understand (i.e. IDocumentSchema.app), but will
1094
- * stop (and fail session) on any unknown properties within "runtime" sub-tree.
1095
- *
1096
- * In most cases values preserved in the document will not dictate if such features should be enabled in a given session.
1097
- * I.e. if compression is mentioned in document schema, this means that runtime version that opens such document must know
1098
- * how to interpret such ops, but does not need to actually use compression itself. That said, some options could be
1099
- * sticky, i.e. influence feature selection for all runtimes opening a document. ID compression is one such example.
1100
- * Currently there is no mechanism to remove feature from this property bag, i.e. once compression was used, even if it's
1101
- * disabled (through feature gate or code deployment), all existing documents that used compression will continue to fail
1102
- * if opened by clients who do not support compression.
1103
- *
1104
- * For now we are limiting it to just plain properties, and only really simple types, but that can be changed in the future.
1105
- *
1106
- * @alpha
1107
- */
1108
- export declare interface IDocumentSchema {
1109
- version: number;
1110
- refSeq: number;
1111
- runtime: Record<string, DocumentSchemaValueType>;
1112
- }
1113
-
1114
- /**
1115
- * Content of the type=ContainerMessageType.DocumentSchemaChange ops.
1116
- * The meaning of refSeq field is different in such messages (compared to other usages of IDocumentSchemaCurrent)
1117
- * ContainerMessageType.DocumentSchemaChange messages use CAS (Compare-and-swap) semantics, and convey
1118
- * regSeq of last known schema change (known to a client proposing schema change).
1119
- * @see ContainerRuntimeDocumentSchemaMessage
1120
- * @alpha
1121
- */
1122
- export declare type IDocumentSchemaChangeMessage = IDocumentSchema;
1123
-
1124
- /**
1125
- * Current document schema.
1126
- * @alpha
1127
- */
1128
- export declare type IDocumentSchemaCurrent = {
1129
- version: 1;
1130
- refSeq: number;
1131
- runtime: {
1132
- [P in keyof IDocumentSchemaFeatures]?: IDocumentSchemaFeatures[P] extends boolean ? true : IDocumentSchemaFeatures[P];
1133
- };
1134
- };
1135
-
1136
- /**
1137
- * Settings that this session would like to have, based on options and feature gates.
1138
- *
1139
- * WARNING: This type is used to infer IDocumentSchemaCurrent type!
1140
- * Any changes here (including renaming of properties) are potentially changing document format and should be considered carefully!
1141
- *
1142
- * @alpha
1143
- */
1144
- export declare interface IDocumentSchemaFeatures {
1145
- explicitSchemaControl: boolean;
1146
- compressionLz4: boolean;
1147
- idCompressorMode: IdCompressorMode;
1148
- opGroupingEnabled: boolean;
1149
- /**
1150
- * List of disallowed versions of the runtime.
1151
- * This option is sticky. Once a version of runtime is added to this list (when supplied to DocumentsSchemaController's constructor)
1152
- * it will be added to the list of disallowed versions and stored in document metadata.
1153
- * Each runtime checks if its version is in this list on container open. If it is, it immediately exits with error message
1154
- * indicating to the user that this version is no longer supported.
1155
- * Currently there is no mechanism to remove version from this list. I.e. If it was once added to the list,
1156
- * it gets added to any document metadata (documents that gets open by this runtime) and there is no way to clear it from document's
1157
- * metadata.
1158
- */
1159
- disallowedVersions: string[];
1160
- }
1161
-
1162
- /**
1163
- * Options to use when enqueueing a summarize attempt.
1164
- * @alpha
1165
- */
1166
- export declare interface IEnqueueSummarizeOptions extends IOnDemandSummarizeOptions {
1167
- /** If specified, The summarize attempt will not occur until after this sequence number. */
1168
- readonly afterSequenceNumber?: number;
1169
- /**
1170
- * True to override the existing enqueued summarize attempt if there is one.
1171
- * This will guarantee that this attempt gets enqueued. If override is false,
1172
- * than an existing enqueued summarize attempt will block a new one from being
1173
- * enqueued. There can only be one enqueued at a time. Defaults to false.
1174
- */
1175
- readonly override?: boolean;
1176
- }
1177
-
1178
- /* Excluded from this release type: IFluidDataStoreContextEvents */
1179
-
1180
- /* Excluded from this release type: IFluidDataStoreContextInternal */
1181
-
1182
- /* Excluded from this release type: IFluidDataStoreContextProps */
1183
-
1184
- /**
1185
- * GC-specific metadata to be written into the summary.
1186
- *
1187
- * @alpha
1188
- */
1189
- export declare interface IGCMetadata {
1190
- /**
1191
- * The version of the GC code that was run to generate the GC data that is written in the summary.
1192
- * If the persisted value doesn't match the current value in the code, saved GC data will be discarded and regenerated from scratch.
1193
- * Also, used to determine whether GC is enabled for this container or not:
1194
- * - A value of 0 or undefined means GC is disabled.
1195
- * - A value greater than 0 means GC is enabled.
1196
- */
1197
- readonly gcFeature?: GCVersion;
1198
- /**
1199
- * A collection of different numerical "Generations" for different features,
1200
- * used to determine feature availability over time.
1201
- * This info may come from multiple sources (FF code, config service, app via Container Runtime Options),
1202
- * and pertains to aspects of the document that may be fixed for its lifetime.
1203
- *
1204
- * For each dimension, if the persisted value doesn't match the currently provided value,
1205
- * then this file does not support the corresponding feature as currently implemented.
1206
- *
1207
- * Guidance is that if no value is provided at runtime, it should result in the current default behavior.
1208
- */
1209
- readonly gcFeatureMatrix?: GCFeatureMatrix;
1210
- /**
1211
- * Tells whether the GC sweep phase is enabled for this container.
1212
- * - True means sweep phase is enabled.
1213
- * - False means sweep phase is disabled. If GC is disabled as per gcFeature, sweep is also disabled.
1214
- *
1215
- * @deprecated use GCFeatureMatrix.gcGeneration instead. @see GCFeatureMatrix.gcGeneration
1216
- */
1217
- readonly sweepEnabled?: boolean;
1218
- /** If this is present, the session for this container will expire after this time and the container will close */
1219
- readonly sessionExpiryTimeoutMs?: number;
1220
- /**
1221
- * How long to wait after an object is unreferenced before it becomes a Tombstone.
1222
- *
1223
- * After this point, there's a grace period before the object is deleted.
1224
- * @see IGCRuntimeOptions.sweepGracePeriodMs
1225
- *
1226
- * So the full sweep timeout in a session is tombstoneTimeoutMs + sweepGracePeriodMs.
1227
- */
1228
- readonly tombstoneTimeoutMs?: number;
1229
- }
1230
-
1231
- /**
1232
- * @alpha
1233
- */
1234
- export declare interface IGCRuntimeOptions {
1235
- /**
1236
- * Flag that if true, will enable running garbage collection (GC) for a new container.
1237
- *
1238
- * GC has mark phase and sweep phase. In mark phase, unreferenced objects are identified
1239
- * and marked as such in the summary. This option enables the mark phase.
1240
- * In sweep phase, unreferenced objects are eventually deleted from the container if they meet certain conditions.
1241
- * Sweep phase can be enabled using the "enableGCSweep" option.
1242
- *
1243
- * Note: This setting is persisted in the container's summary and cannot be changed.
1244
- */
1245
- gcAllowed?: boolean;
1246
- /**
1247
- * Flag that if true, will disable garbage collection for the session.
1248
- * Can be used to disable running GC on containers where it is allowed via the gcAllowed option.
1249
- */
1250
- disableGC?: boolean;
1251
- /**
1252
- * Flag that if true, will enable the full Sweep Phase of garbage collection for this session,
1253
- * where Tombstoned objects are permanently deleted from the container.
1254
- *
1255
- * IMPORTANT: This only applies if this document is allowed to run Sweep Phase.
1256
- *
1257
- * Current default behavior is for Sweep Phase not to delete Tombstoned objects,
1258
- * but merely to prevent them from being loaded.
1259
- */
1260
- enableGCSweep?: true;
1261
- /**
1262
- * Flag that will bypass optimizations and generate GC data for all nodes irrespective of whether a node
1263
- * changed or not.
1264
- */
1265
- runFullGC?: boolean;
1266
- /**
1267
- * Maximum session duration for a new container. If not present, a default value will be used.
1268
- *
1269
- * Note: This setting is persisted in the container's summary and cannot be changed.
1270
- */
1271
- sessionExpiryTimeoutMs?: number;
1272
- /**
1273
- * Delay between when Tombstone should run and when the object should be deleted.
1274
- * This grace period gives a chance to intervene to recover if needed, before Sweep deletes the object.
1275
- * If not present, a default (non-zero) value will be used.
1276
- */
1277
- sweepGracePeriodMs?: number;
1278
- /**
1279
- * Allows additional GC options to be passed.
1280
- */
1281
- [key: string]: any;
1282
- }
1283
-
1284
- /**
1285
- * The statistics of the system state after a garbage collection run.
1286
- * @alpha
1287
- */
1288
- export declare interface IGCStats extends IMarkPhaseStats, ISweepPhaseStats {
1289
- }
1290
-
1291
- /**
1292
- * In addition to the normal summary tree + stats, this contains additional stats
1293
- * only relevant at the root of the tree.
1294
- * @alpha
1295
- */
1296
- export declare interface IGeneratedSummaryStats extends ISummaryStats {
1297
- /** The total number of data stores in the container. */
1298
- readonly dataStoreCount: number;
1299
- /** The number of data stores that were summarized in this summary. */
1300
- readonly summarizedDataStoreCount: number;
1301
- /** The number of data stores whose GC reference state was updated in this summary. */
1302
- readonly gcStateUpdatedDataStoreCount?: number;
1303
- /** The size of the gc blobs in this summary. */
1304
- readonly gcTotalBlobsSize?: number;
1305
- /** The number of gc blobs in this summary. */
1306
- readonly gcBlobNodeCount?: number;
1307
- /** The summary number for a container's summary. Incremented on summaries throughout its lifetime. */
1308
- readonly summaryNumber: number;
1309
- }
1310
-
1311
- /**
1312
- * Results of submitSummary after generating the summary tree.
1313
- * @alpha
1314
- */
1315
- export declare interface IGenerateSummaryTreeResult extends Omit<IBaseSummarizeResult, "stage"> {
1316
- readonly stage: "generate";
1317
- /** Generated summary tree. */
1318
- readonly summaryTree: ISummaryTree;
1319
- /** Stats for generated summary tree. */
1320
- readonly summaryStats: IGeneratedSummaryStats;
1321
- /** Time it took to generate the summary tree and stats. */
1322
- readonly generateDuration: number;
1323
- /** True if the full tree regeneration with no handle reuse optimizations was forced. */
1324
- readonly forcedFullTree: boolean;
1325
- }
1326
-
1327
- /* Excluded from this release type: ILocalDetachedFluidDataStoreContextProps */
1328
-
1329
- /* Excluded from this release type: ILocalFluidDataStoreContextProps */
1330
-
1331
- /**
1332
- * The statistics of the system state after a garbage collection mark phase run.
1333
- * @alpha
1334
- */
1335
- export declare interface IMarkPhaseStats {
1336
- /** The number of nodes in the container. */
1337
- nodeCount: number;
1338
- /** The number of data stores in the container. */
1339
- dataStoreCount: number;
1340
- /** The number of attachment blobs in the container. */
1341
- attachmentBlobCount: number;
1342
- /** The number of unreferenced nodes in the container. */
1343
- unrefNodeCount: number;
1344
- /** The number of unreferenced data stores in the container. */
1345
- unrefDataStoreCount: number;
1346
- /** The number of unreferenced attachment blobs in the container. */
1347
- unrefAttachmentBlobCount: number;
1348
- /** The number of nodes whose reference state updated since last GC run. */
1349
- updatedNodeCount: number;
1350
- /** The number of data stores whose reference state updated since last GC run. */
1351
- updatedDataStoreCount: number;
1352
- /** The number of attachment blobs whose reference state updated since last GC run. */
1353
- updatedAttachmentBlobCount: number;
1354
- }
1355
-
1356
- /**
1357
- * @alpha
1358
- */
1359
- export declare interface INackSummaryResult extends IRetriableFailureResult {
1360
- readonly summaryNackOp: ISummaryNackMessage;
1361
- readonly ackNackDuration: number;
1362
- }
1363
-
1364
- /**
1365
- * Inactive error responses will have this header set to true
1366
- * @alpha
1367
- */
1368
- export declare const InactiveResponseHeaderKey = "isInactive";
1369
-
1370
- /**
1371
- * @alpha
1372
- */
1373
- export declare interface IOnDemandSummarizeOptions extends ISummarizeOptions {
1374
- /** Reason for generating summary. */
1375
- readonly reason: string;
1376
- /** In case of a failure, will attempt to retry based on if the failure is retriable. */
1377
- readonly retryOnFailure?: boolean;
1378
- }
1379
-
1380
- /**
1381
- * Data required to update internal tracking state after receiving a Summary Ack.
1382
- * @alpha
1383
- */
1384
- export declare interface IRefreshSummaryAckOptions {
1385
- /** Handle from the ack's summary op. */
1386
- readonly proposalHandle: string | undefined;
1387
- /** Handle from the summary ack just received */
1388
- readonly ackHandle: string;
1389
- /** Reference sequence number from the ack's summary op */
1390
- readonly summaryRefSeq: number;
1391
- /** Telemetry logger to which telemetry events will be forwarded. */
1392
- readonly summaryLogger: ITelemetryLoggerExt;
1393
- }
1394
-
1395
- /**
1396
- * Type for summarization failures that are retriable.
1397
- * @alpha
1398
- */
1399
- export declare interface IRetriableFailureResult {
1400
- readonly retryAfterSeconds?: number;
1401
- }
1402
-
1403
- /**
1404
- * Serialized state of IOrderedClientElection.
1405
- * @alpha
1406
- */
1407
- export declare interface ISerializedElection {
1408
- /** Sequence number at the time of the latest election. */
1409
- readonly electionSequenceNumber: number;
1410
- /**
1411
- * Most recently elected client id. This is either:
1412
- *
1413
- * 1. the interactive elected parent client, in which case electedClientId === electedParentId,
1414
- * and the SummaryManager on the elected client will spawn a summarizer client, or
1415
- *
1416
- * 2. the non-interactive summarizer client itself.
1417
- */
1418
- readonly electedClientId: string | undefined;
1419
- /** Most recently elected parent client id. This is always an interactive client. */
1420
- readonly electedParentId: string | undefined;
1421
- }
1422
-
1423
- /* Excluded from this release type: ISnapshotDetails */
1424
-
1425
- /* Excluded from this release type: isRuntimeMessage */
1426
-
1427
- /**
1428
- * Results of submitSummary after submitting the summarize op.
1429
- * @alpha
1430
- */
1431
- export declare interface ISubmitSummaryOpResult extends Omit<IUploadSummaryResult, "stage" | "error"> {
1432
- readonly stage: "submit";
1433
- /** The client sequence number of the summarize op submitted for the summary. */
1434
- readonly clientSequenceNumber: number;
1435
- /** Time it took to submit the summarize op to the broadcasting service. */
1436
- readonly submitOpDuration: number;
1437
- }
1438
-
1439
- /**
1440
- * @alpha
1441
- */
1442
- export declare interface ISubmitSummaryOptions extends ISummarizeOptions {
1443
- /** Logger to use for correlated summary events */
1444
- readonly summaryLogger: ITelemetryLoggerExt;
1445
- /** Tells when summary process should be cancelled */
1446
- readonly cancellationToken: ISummaryCancellationToken;
1447
- /** Summarization may be attempted multiple times. This tells whether this is the final summarization attempt. */
1448
- readonly finalAttempt?: boolean;
1449
- /** The sequence number of the latest summary used to validate if summary state is correct before summarizing */
1450
- readonly latestSummaryRefSeqNum: number;
1451
- }
1452
-
1453
- /**
1454
- * @alpha
1455
- */
1456
- export declare interface ISummarizeEventProps {
1457
- result: "success" | "failure" | "canceled";
1458
- currentAttempt: number;
1459
- maxAttempts: number;
1460
- error?: any;
1461
- }
1462
-
1463
- /**
1464
- * Options affecting summarize behavior.
1465
- * @alpha
1466
- */
1467
- export declare interface ISummarizeOptions {
1468
- /** True to generate the full tree with no handle reuse optimizations; defaults to false */
1469
- readonly fullTree?: boolean;
1470
- /**
1471
- * True to ask the server what the latest summary is first; defaults to false
1472
- *
1473
- * @deprecated Summarize will not refresh latest snapshot state anymore. Instead it updates the cache and closes.
1474
- * It's expected a new summarizer client will be created, likely by the same parent.
1475
- */
1476
- readonly refreshLatestAck?: boolean;
1477
- }
1478
-
1479
- /**
1480
- * @alpha
1481
- */
1482
- export declare interface ISummarizer extends IEventProvider<ISummarizerEvents> {
1483
- /**
1484
- * Allows {@link ISummarizer} to be used with our {@link @fluidframework/core-interfaces#FluidObject} pattern.
1485
- */
1486
- readonly ISummarizer?: ISummarizer;
1487
- stop(reason: SummarizerStopReason): void;
1488
- close(): void;
1489
- run(onBehalfOf: string): Promise<SummarizerStopReason>;
1490
- /**
1491
- * Attempts to generate a summary on demand. If already running, takes no action.
1492
- * @param options - options controlling the summarize attempt
1493
- * @returns an alreadyRunning promise if a summarize attempt is already in progress,
1494
- * which will resolve when the current attempt completes. At that point caller can
1495
- * decide to try again or not. Otherwise, it will return an object containing promises
1496
- * that resolve as the summarize attempt progresses. They will resolve with success
1497
- * false if a failure is encountered.
1498
- */
1499
- summarizeOnDemand(options: IOnDemandSummarizeOptions): ISummarizeResults;
1500
- /**
1501
- * Enqueue an attempt to summarize after the specified sequence number.
1502
- * If afterSequenceNumber is provided, the summarize attempt is "enqueued"
1503
- * to run once an eligible op comes in with sequenceNumber \>= afterSequenceNumber.
1504
- * @param options - options controlling the summarize attempt
1505
- * @returns an object containing an alreadyEnqueued flag to indicate if another
1506
- * summarize attempt has already been enqueued. It also may contain an overridden flag
1507
- * when alreadyEnqueued is true, that indicates whether this attempt forced the
1508
- * previous attempt to abort. If this attempt becomes enqueued, it returns an object
1509
- * containing promises that resolve as the summarize attempt progresses. They will
1510
- * resolve with success false if a failure is encountered.
1511
- */
1512
- enqueueSummarize(options: IEnqueueSummarizeOptions): EnqueueSummarizeResult;
1513
- }
1514
-
1515
- /**
1516
- * @alpha
1517
- */
1518
- export declare interface ISummarizeResults {
1519
- /** Resolves when we generate, upload, and submit the summary. */
1520
- readonly summarySubmitted: Promise<SummarizeResultPart<SubmitSummaryResult, SubmitSummaryFailureData>>;
1521
- /** Resolves when we observe our summarize op broadcast. */
1522
- readonly summaryOpBroadcasted: Promise<SummarizeResultPart<IBroadcastSummaryResult>>;
1523
- /** Resolves when we receive a summaryAck or summaryNack. */
1524
- readonly receivedSummaryAckOrNack: Promise<SummarizeResultPart<IAckSummaryResult, INackSummaryResult>>;
1525
- }
1526
-
1527
- /**
1528
- * @alpha
1529
- */
1530
- export declare interface ISummarizerEvents extends IEvent {
1531
- (event: "summarize", listener: (props: ISummarizeEventProps) => void): any;
1532
- }
1533
-
1534
- /**
1535
- * @alpha
1536
- */
1537
- export declare interface ISummarizerInternalsProvider {
1538
- /** Encapsulates the work to walk the internals of the running container to generate a summary */
1539
- submitSummary(options: ISubmitSummaryOptions): Promise<SubmitSummaryResult>;
1540
- /** Callback whenever a new SummaryAck is received, to update internal tracking state */
1541
- refreshLatestSummaryAck(options: IRefreshSummaryAckOptions): Promise<void>;
1542
- }
1543
-
1544
- /**
1545
- * @alpha
1546
- */
1547
- export declare interface ISummarizerRuntime extends IConnectableRuntime {
1548
- readonly logger: ITelemetryLoggerExt;
1549
- /** clientId of parent (non-summarizing) container that owns summarizer container */
1550
- readonly summarizerClientId: string | undefined;
1551
- readonly deltaManager: IDeltaManager<ISequencedDocumentMessage, IDocumentMessage>;
1552
- disposeFn(): void;
1553
- closeFn(): void;
1554
- on(event: "op", listener: (op: ISequencedDocumentMessage, runtimeMessage?: boolean) => void): this;
1555
- off(event: "op", listener: (op: ISequencedDocumentMessage, runtimeMessage?: boolean) => void): this;
1556
- }
1557
-
1558
- /* Excluded from this release type: ISummarizingWarning */
1559
-
1560
- /**
1561
- * A single summary which can be tracked as it goes through its life cycle.
1562
- * The life cycle is: Local to Broadcast to Acked/Nacked.
1563
- * @alpha
1564
- */
1565
- export declare interface ISummary {
1566
- readonly clientId: string;
1567
- readonly clientSequenceNumber: number;
1568
- waitBroadcast(): Promise<ISummaryOpMessage>;
1569
- waitAckNack(): Promise<ISummaryAckMessage | ISummaryNackMessage>;
1570
- }
1571
-
1572
- /**
1573
- * Interface for summary ack messages with typed contents.
1574
- * @alpha
1575
- */
1576
- export declare interface ISummaryAckMessage extends ISequencedDocumentMessage {
1577
- type: MessageType.SummaryAck;
1578
- contents: ISummaryAck;
1579
- }
1580
-
1581
- /**
1582
- * @alpha
1583
- */
1584
- export declare interface ISummaryBaseConfiguration {
1585
- /**
1586
- * Delay before first attempt to spawn summarizing container.
1587
- */
1588
- initialSummarizerDelayMs: number;
1589
- /**
1590
- * Defines the maximum allowed time to wait for a pending summary ack.
1591
- * The maximum amount of time client will wait for a summarize is the minimum of
1592
- * maxSummarizeAckWaitTime (currently 3 * 60 * 1000) and maxAckWaitTime.
1593
- */
1594
- maxAckWaitTime: number;
1595
- /**
1596
- * Defines the maximum number of Ops in between Summaries that can be
1597
- * allowed before forcibly electing a new summarizer client.
1598
- */
1599
- maxOpsSinceLastSummary: number;
1600
- }
1601
-
1602
- /**
1603
- * Similar to AbortSignal, but using promise instead of events
1604
- * @alpha
1605
- */
1606
- export declare type ISummaryCancellationToken = ICancellationToken<SummarizerStopReason>;
1607
-
1608
- /**
1609
- * @alpha
1610
- */
1611
- export declare interface ISummaryCollectionOpEvents extends IEvent {
1612
- (event: OpActionEventName, listener: OpActionEventListener): any;
1613
- }
1614
-
1615
- /**
1616
- * @alpha
1617
- */
1618
- export declare type ISummaryConfiguration = ISummaryConfigurationDisableSummarizer | ISummaryConfigurationDisableHeuristics | ISummaryConfigurationHeuristics;
1619
-
1620
- /**
1621
- * @alpha
1622
- */
1623
- export declare interface ISummaryConfigurationDisableHeuristics extends ISummaryBaseConfiguration {
1624
- state: "disableHeuristics";
1625
- }
1626
-
1627
- /**
1628
- * @alpha
1629
- */
1630
- export declare interface ISummaryConfigurationDisableSummarizer {
1631
- state: "disabled";
1632
- }
1633
-
1634
- /**
1635
- * @alpha
1636
- */
1637
- export declare interface ISummaryConfigurationHeuristics extends ISummaryBaseConfiguration {
1638
- state: "enabled";
1639
- /**
1640
- * Defines the maximum allowed time, since the last received Ack, before running the summary
1641
- * with reason maxTime.
1642
- * For example, say we receive ops one by one just before the idle time is triggered.
1643
- * In this case, we still want to run a summary since it's been a while since the last summary.
1644
- */
1645
- maxTime: number;
1646
- /**
1647
- * Defines the maximum number of Ops, since the last received Ack, that can be allowed
1648
- * before running the summary with reason maxOps.
1649
- */
1650
- maxOps: number;
1651
- /**
1652
- * Defines the minimum number of Ops, since the last received Ack, that can be allowed
1653
- * before running the last summary.
1654
- */
1655
- minOpsForLastSummaryAttempt: number;
1656
- /**
1657
- * Defines the lower boundary for the allowed time in between summarizations.
1658
- * Pairs with maxIdleTime to form a range.
1659
- * For example, if we only receive 1 op, we don't want to have the same idle time as say 100 ops.
1660
- * Based on the boundaries we set in minIdleTime and maxIdleTime, the idle time will change
1661
- * linearly depending on the number of ops we receive.
1662
- */
1663
- minIdleTime: number;
1664
- /**
1665
- * Defines the upper boundary for the allowed time in between summarizations.
1666
- * Pairs with minIdleTime to form a range.
1667
- * For example, if we only receive 1 op, we don't want to have the same idle time as say 100 ops.
1668
- * Based on the boundaries we set in minIdleTime and maxIdleTime, the idle time will change
1669
- * linearly depending on the number of ops we receive.
1670
- */
1671
- maxIdleTime: number;
1672
- /**
1673
- * Runtime op weight to use in heuristic summarizing.
1674
- * This number is a multiplier on the number of runtime ops we process when running summarize heuristics.
1675
- * For example: (multiplier) * (number of runtime ops) = weighted number of runtime ops
1676
- */
1677
- runtimeOpWeight: number;
1678
- /**
1679
- * Non-runtime op weight to use in heuristic summarizing
1680
- * This number is a multiplier on the number of non-runtime ops we process when running summarize heuristics.
1681
- * For example: (multiplier) * (number of non-runtime ops) = weighted number of non-runtime ops
1682
- */
1683
- nonRuntimeOpWeight: number;
1684
- /**
1685
- * Number of ops since last summary needed before a non-runtime op can trigger running summary heuristics.
1686
- *
1687
- * Note: Any runtime ops sent before the threshold is reached will trigger heuristics normally.
1688
- * This threshold ONLY applies to non-runtime ops triggering summaries.
1689
- *
1690
- * For example: Say the threshold is 20. Sending 19 non-runtime ops will not trigger any heuristic checks.
1691
- * Sending the 20th non-runtime op will trigger the heuristic checks for summarizing.
1692
- */
1693
- nonRuntimeHeuristicThreshold?: number;
1694
- }
1695
-
1696
- /**
1697
- * The properties of an ISequencedDocumentMessage to be stored in the metadata blob in summary.
1698
- * @alpha
1699
- */
1700
- export declare type ISummaryMetadataMessage = Pick<ISequencedDocumentMessage, "clientId" | "clientSequenceNumber" | "minimumSequenceNumber" | "referenceSequenceNumber" | "sequenceNumber" | "timestamp" | "type">;
1701
-
1702
- /**
1703
- * Interface for summary nack messages with typed contents.
1704
- * @alpha
1705
- */
1706
- export declare interface ISummaryNackMessage extends ISequencedDocumentMessage {
1707
- type: MessageType.SummaryNack;
1708
- contents: ISummaryNack;
1709
- }
1710
-
1711
- /**
1712
- * Interface for summary op messages with typed contents.
1713
- * @alpha
1714
- */
1715
- export declare interface ISummaryOpMessage extends ISequencedDocumentMessage {
1716
- type: MessageType.Summarize;
1717
- contents: ISummaryContent;
1718
- }
1719
-
1720
- /**
1721
- * @alpha
1722
- */
1723
- export declare interface ISummaryRuntimeOptions {
1724
- /** Override summary configurations set by the server. */
1725
- summaryConfigOverrides?: ISummaryConfiguration;
1726
- /**
1727
- * Delay before first attempt to spawn summarizing container.
1728
- *
1729
- * @deprecated Use {@link ISummaryRuntimeOptions.summaryConfigOverrides}'s
1730
- * {@link ISummaryBaseConfiguration.initialSummarizerDelayMs} instead.
1731
- */
1732
- initialSummarizerDelayMs?: number;
1733
- }
1734
-
1735
- /**
1736
- * The statistics of the system state after a garbage collection sweep phase run.
1737
- * @alpha
1738
- */
1739
- export declare interface ISweepPhaseStats {
1740
- /** The number of nodes in the lifetime of the container. */
1741
- lifetimeNodeCount: number;
1742
- /** The number of data stores in the lifetime of the container. */
1743
- lifetimeDataStoreCount: number;
1744
- /** The number of attachment blobs in the lifetime of the container. */
1745
- lifetimeAttachmentBlobCount: number;
1746
- /** The number of deleted nodes in the container. */
1747
- deletedNodeCount: number;
1748
- /** The number of deleted data stores in the container. */
1749
- deletedDataStoreCount: number;
1750
- /** The number of deleted attachment blobs in the container. */
1751
- deletedAttachmentBlobCount: number;
1752
- }
1753
-
1754
- /**
1755
- * Results of submitSummary after uploading the tree to storage.
1756
- * @alpha
1757
- */
1758
- export declare interface IUploadSummaryResult extends Omit<IGenerateSummaryTreeResult, "stage"> {
1759
- readonly stage: "upload";
1760
- /** The handle returned by storage pointing to the uploaded summary tree. */
1761
- readonly handle: string;
1762
- /** Time it took to upload the summary tree to storage. */
1763
- readonly uploadDuration: number;
1764
- }
1765
-
1766
- /* Excluded from this release type: LocalFluidDataStoreContext */
1767
-
1768
- /* Excluded from this release type: LocalFluidDataStoreContextBase */
1769
-
1770
- /* Excluded from this release type: MonitoringContext */
1771
-
1772
- /* Excluded from this release type: neverCancelledSummaryToken */
1773
-
1774
- /**
1775
- * @alpha
1776
- */
1777
- export declare type OpActionEventListener = (op: ISequencedDocumentMessage) => void;
1778
-
1779
- /**
1780
- * @alpha
1781
- */
1782
- export declare type OpActionEventName = MessageType.Summarize | MessageType.SummaryAck | MessageType.SummaryNack | "default";
1783
-
1784
- /* Excluded from this release type: RecentlyAddedContainerRuntimeMessageDetails */
1785
-
1786
- /* Excluded from this release type: RuntimeHeaderData */
1787
-
1788
- /* Excluded from this release type: RuntimeHeaders */
1789
-
1790
- /**
1791
- * The data in summarizer result when submit summary stage fails.
1792
- * @alpha
1793
- */
1794
- export declare interface SubmitSummaryFailureData extends IRetriableFailureResult {
1795
- stage: SummaryStage;
1796
- }
1797
-
1798
- /**
1799
- * Strict type representing result of a submitSummary attempt.
1800
- * The result consists of 4 possible stages, each with its own data.
1801
- * The data is cumulative, so each stage will contain the data from the previous stages.
1802
- * If the final "submitted" stage is not reached, the result may contain the error object.
1803
- *
1804
- * Stages:
1805
- *
1806
- * 1. "base" - stopped before the summary tree was even generated, and the result only contains the base data
1807
- *
1808
- * 2. "generate" - the summary tree was generated, and the result will contain that tree + stats
1809
- *
1810
- * 3. "upload" - the summary was uploaded to storage, and the result contains the server-provided handle
1811
- *
1812
- * 4. "submit" - the summarize op was submitted, and the result contains the op client sequence number.
1813
- * @alpha
1814
- */
1815
- export declare type SubmitSummaryResult = IBaseSummarizeResult | IGenerateSummaryTreeResult | IUploadSummaryResult | ISubmitSummaryOpResult;
1816
-
1817
- /**
1818
- * Summarizer is responsible for coordinating when to generate and send summaries.
1819
- * It is the main entry point for summary work.
1820
- * It is created only by summarizing container (i.e. one with clientType === "summarizer")
1821
- * @alpha
1822
- */
1823
- export declare class Summarizer extends TypedEventEmitter<ISummarizerEvents> implements ISummarizer {
1824
- /** Reference to runtime that created this object.
1825
- * i.e. runtime with clientType === "summarizer"
1826
- */
1827
- private readonly runtime;
1828
- private readonly configurationGetter;
1829
- /** Represents an object that can generate summary.
1830
- * In practical terms, it's same runtime (this.runtime) with clientType === "summarizer".
1831
- */
1832
- private readonly internalsProvider;
1833
- readonly summaryCollection: SummaryCollection;
1834
- private readonly runCoordinatorCreateFn;
1835
- get ISummarizer(): this;
1836
- private readonly logger;
1837
- private runningSummarizer?;
1838
- private _disposed;
1839
- private starting;
1840
- private readonly stopDeferred;
1841
- constructor(
1842
- /** Reference to runtime that created this object.
1843
- * i.e. runtime with clientType === "summarizer"
1844
- */
1845
- runtime: ISummarizerRuntime, configurationGetter: () => ISummaryConfiguration,
1846
- /** Represents an object that can generate summary.
1847
- * In practical terms, it's same runtime (this.runtime) with clientType === "summarizer".
1848
- */
1849
- internalsProvider: ISummarizerInternalsProvider, handleContext: IFluidHandleContext, summaryCollection: SummaryCollection, runCoordinatorCreateFn: (runtime: IConnectableRuntime) => Promise<ICancellableSummarizerController>);
1850
- run(onBehalfOf: string): Promise<SummarizerStopReason>;
1851
- /**
1852
- * Stops the summarizer from running. This will complete
1853
- * the run promise, and also close the container.
1854
- * @param reason - reason code for stopping
1855
- */
1856
- stop(reason: SummarizerStopReason): void;
1857
- close(): void;
1858
- private runCore;
1859
- /**
1860
- * Should we try to run a last summary for the given stop reason?
1861
- * Currently only allows "parentNotConnected"
1862
- * @param stopReason - SummarizerStopReason
1863
- * @returns `true` if the stop reason can run a last summary, otherwise `false`.
1864
- */
1865
- static stopReasonCanRunLastSummary(stopReason: SummarizerStopReason): boolean;
1866
- private _heuristicData;
1867
- /**
1868
- * Put the summarizer in a started state, including creating and initializing the RunningSummarizer.
1869
- * The start request can come either from the SummaryManager (in the auto-summarize case) or from the user
1870
- * (in the on-demand case).
1871
- * @param onBehalfOf - ID of the client that requested that the summarizer start
1872
- * @param runCoordinator - cancellation token
1873
- * @param newConfig - Summary configuration to override the existing config when invoking the RunningSummarizer.
1874
- * @returns A promise that is fulfilled when the RunningSummarizer is ready.
1875
- */
1876
- private start;
1877
- private readonly handleSummarizeEvent;
1878
- /**
1879
- * Disposes of resources after running. This cleanup will
1880
- * clear any outstanding timers and reset some of the state
1881
- * properties.
1882
- * Called by ContainerRuntime when it is disposed, as well as at the end the run().
1883
- */
1884
- dispose(): void;
1885
- summarizeOnDemand(options: IOnDemandSummarizeOptions): ISummarizeResults;
1886
- enqueueSummarize(options: IEnqueueSummarizeOptions): EnqueueSummarizeResult;
1887
- recordSummaryAttempt?(summaryRefSeqNum?: number): void;
1888
- }
1889
-
1890
- /**
1891
- * @alpha
1892
- */
1893
- export declare type SummarizeResultPart<TSuccess, TFailure = undefined> = {
1894
- success: true;
1895
- data: TSuccess;
1896
- } | {
1897
- success: false;
1898
- data: TFailure | undefined;
1899
- message: string;
1900
- error: any;
1901
- };
1902
-
1903
- /**
1904
- * @alpha
1905
- */
1906
- export declare type SummarizerStopReason =
1907
- /** Summarizer client failed to summarize in all attempts. */
1908
- "failToSummarize"
1909
- /** Parent client reported that it is no longer connected. */
1910
- | "parentNotConnected"
1911
- /**
1912
- * Parent client reported that it is no longer elected the summarizer.
1913
- * This is the normal flow; a disconnect will always trigger the parent
1914
- * client to no longer be elected as responsible for summaries. Then it
1915
- * tries to stop its spawned summarizer client.
1916
- */
1917
- | "notElectedParent"
1918
- /**
1919
- * We are not already running the summarizer and we are not the current elected client id.
1920
- */
1921
- | "notElectedClient"
1922
- /** Summarizer client was disconnected */
1923
- | "summarizerClientDisconnected"
1924
- /** running summarizer threw an exception */
1925
- | "summarizerException"
1926
- /**
1927
- * The previous summary state on the summarizer is not the most recently acked summary. this also happens when the
1928
- * first submitSummary attempt fails for any reason and there's a 2nd summary attempt without an ack
1929
- */
1930
- | "latestSummaryStateStale";
1931
-
1932
- /**
1933
- * Data structure that looks at the op stream to track summaries as they
1934
- * are broadcast, acked and nacked.
1935
- * It provides functionality for watching specific summaries.
1936
- * @alpha
1937
- */
1938
- export declare class SummaryCollection extends TypedEventEmitter<ISummaryCollectionOpEvents> {
1939
- private readonly deltaManager;
1940
- private readonly logger;
1941
- private readonly summaryWatchers;
1942
- private readonly pendingSummaries;
1943
- private refreshWaitNextAck;
1944
- private lastSummaryTimestamp;
1945
- private maxAckWaitTime;
1946
- private pendingAckTimerTimeoutCallback;
1947
- private lastAck;
1948
- get latestAck(): IAckedSummary | undefined;
1949
- emit(event: OpActionEventName, ...args: Parameters<OpActionEventListener>): boolean;
1950
- get opsSinceLastAck(): number;
1951
- addOpListener(listener: () => void): void;
1952
- removeOpListener(listener: () => void): void;
1953
- constructor(deltaManager: IDeltaManager<ISequencedDocumentMessage, IDocumentMessage>, logger: ITelemetryLoggerExt);
1954
- /**
1955
- * Creates and returns a summary watcher for a specific client.
1956
- * This will allow for local sent summaries to be better tracked.
1957
- * @param clientId - client id for watcher
1958
- */
1959
- createWatcher(clientId: string): IClientSummaryWatcher;
1960
- removeWatcher(clientId: string): void;
1961
- setPendingAckTimerTimeoutCallback(maxAckWaitTime: number, timeoutCallback: () => void): void;
1962
- unsetPendingAckTimerTimeoutCallback(): void;
1963
- /**
1964
- * Returns a promise that resolves once all pending summary ops
1965
- * have been acked or nacked.
1966
- */
1967
- waitFlushed(): Promise<IAckedSummary | undefined>;
1968
- /**
1969
- * Returns a promise that resolves once a summary is acked that has a reference
1970
- * sequence number greater than or equal to the passed in sequence number.
1971
- * @param referenceSequenceNumber - reference sequence number to wait for
1972
- * @returns The latest acked summary
1973
- */
1974
- waitSummaryAck(referenceSequenceNumber: number): Promise<IAckedSummary>;
1975
- private parseContent;
1976
- /**
1977
- * Handler for ops; only handles ops relating to summaries.
1978
- * @param op - op message to handle
1979
- */
1980
- private handleOp;
1981
- private handleSummaryOp;
1982
- private handleSummaryAck;
1983
- private handleSummaryNack;
1984
- }
1985
-
1986
- /**
1987
- * The stages of Summarize, used to describe how far progress succeeded in case of a failure at a later stage.
1988
- * @alpha
1989
- */
1990
- export declare type SummaryStage = SubmitSummaryResult["stage"] | "unknown";
1991
-
1992
- /**
1993
- * Tombstone error responses will have this header set to true
1994
- * @alpha
1995
- */
1996
- export declare const TombstoneResponseHeaderKey = "isTombstoned";
1997
-
1998
- /* Excluded from this release type: UnknownContainerRuntimeMessage */
1999
-
2000
- /* Excluded from this release type: unpackRuntimeMessage */
2001
-
2002
- export { }