@fluidframework/container-loader 2.0.0-internal.3.0.5 → 2.0.0-internal.3.1.1

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.
Files changed (148) hide show
  1. package/.eslintrc.js +18 -21
  2. package/.mocharc.js +2 -2
  3. package/README.md +45 -43
  4. package/api-extractor.json +2 -2
  5. package/closeAndGetPendingLocalState.md +51 -0
  6. package/dist/audience.d.ts.map +1 -1
  7. package/dist/audience.js.map +1 -1
  8. package/dist/catchUpMonitor.d.ts.map +1 -1
  9. package/dist/catchUpMonitor.js.map +1 -1
  10. package/dist/collabWindowTracker.d.ts.map +1 -1
  11. package/dist/collabWindowTracker.js.map +1 -1
  12. package/dist/connectionManager.d.ts +2 -2
  13. package/dist/connectionManager.d.ts.map +1 -1
  14. package/dist/connectionManager.js +51 -24
  15. package/dist/connectionManager.js.map +1 -1
  16. package/dist/connectionState.d.ts.map +1 -1
  17. package/dist/connectionState.js.map +1 -1
  18. package/dist/connectionStateHandler.d.ts.map +1 -1
  19. package/dist/connectionStateHandler.js +35 -16
  20. package/dist/connectionStateHandler.js.map +1 -1
  21. package/dist/container.d.ts +1 -10
  22. package/dist/container.d.ts.map +1 -1
  23. package/dist/container.js +89 -44
  24. package/dist/container.js.map +1 -1
  25. package/dist/containerContext.d.ts.map +1 -1
  26. package/dist/containerContext.js +6 -2
  27. package/dist/containerContext.js.map +1 -1
  28. package/dist/containerStorageAdapter.d.ts.map +1 -1
  29. package/dist/containerStorageAdapter.js +2 -4
  30. package/dist/containerStorageAdapter.js.map +1 -1
  31. package/dist/contracts.d.ts.map +1 -1
  32. package/dist/contracts.js.map +1 -1
  33. package/dist/deltaManager.d.ts +3 -3
  34. package/dist/deltaManager.d.ts.map +1 -1
  35. package/dist/deltaManager.js +56 -27
  36. package/dist/deltaManager.js.map +1 -1
  37. package/dist/deltaManagerProxy.d.ts.map +1 -1
  38. package/dist/deltaManagerProxy.js.map +1 -1
  39. package/dist/deltaQueue.d.ts.map +1 -1
  40. package/dist/deltaQueue.js +4 -2
  41. package/dist/deltaQueue.js.map +1 -1
  42. package/dist/index.d.ts +1 -1
  43. package/dist/index.d.ts.map +1 -1
  44. package/dist/index.js.map +1 -1
  45. package/dist/loader.d.ts +3 -3
  46. package/dist/loader.d.ts.map +1 -1
  47. package/dist/loader.js +18 -15
  48. package/dist/loader.js.map +1 -1
  49. package/dist/packageVersion.d.ts +1 -1
  50. package/dist/packageVersion.js +1 -1
  51. package/dist/packageVersion.js.map +1 -1
  52. package/dist/protocol.d.ts.map +1 -1
  53. package/dist/protocol.js +2 -1
  54. package/dist/protocol.js.map +1 -1
  55. package/dist/protocolTreeDocumentStorageService.d.ts.map +1 -1
  56. package/dist/protocolTreeDocumentStorageService.js.map +1 -1
  57. package/dist/quorum.d.ts.map +1 -1
  58. package/dist/quorum.js.map +1 -1
  59. package/dist/retriableDocumentStorageService.d.ts.map +1 -1
  60. package/dist/retriableDocumentStorageService.js +6 -2
  61. package/dist/retriableDocumentStorageService.js.map +1 -1
  62. package/dist/utils.d.ts.map +1 -1
  63. package/dist/utils.js +6 -4
  64. package/dist/utils.js.map +1 -1
  65. package/lib/audience.d.ts.map +1 -1
  66. package/lib/audience.js.map +1 -1
  67. package/lib/catchUpMonitor.d.ts.map +1 -1
  68. package/lib/catchUpMonitor.js.map +1 -1
  69. package/lib/collabWindowTracker.d.ts.map +1 -1
  70. package/lib/collabWindowTracker.js.map +1 -1
  71. package/lib/connectionManager.d.ts +2 -2
  72. package/lib/connectionManager.d.ts.map +1 -1
  73. package/lib/connectionManager.js +53 -26
  74. package/lib/connectionManager.js.map +1 -1
  75. package/lib/connectionState.d.ts.map +1 -1
  76. package/lib/connectionState.js.map +1 -1
  77. package/lib/connectionStateHandler.d.ts.map +1 -1
  78. package/lib/connectionStateHandler.js +35 -16
  79. package/lib/connectionStateHandler.js.map +1 -1
  80. package/lib/container.d.ts +1 -10
  81. package/lib/container.d.ts.map +1 -1
  82. package/lib/container.js +93 -48
  83. package/lib/container.js.map +1 -1
  84. package/lib/containerContext.d.ts.map +1 -1
  85. package/lib/containerContext.js +6 -2
  86. package/lib/containerContext.js.map +1 -1
  87. package/lib/containerStorageAdapter.d.ts.map +1 -1
  88. package/lib/containerStorageAdapter.js +2 -4
  89. package/lib/containerStorageAdapter.js.map +1 -1
  90. package/lib/contracts.d.ts.map +1 -1
  91. package/lib/contracts.js.map +1 -1
  92. package/lib/deltaManager.d.ts +3 -3
  93. package/lib/deltaManager.d.ts.map +1 -1
  94. package/lib/deltaManager.js +58 -29
  95. package/lib/deltaManager.js.map +1 -1
  96. package/lib/deltaManagerProxy.d.ts.map +1 -1
  97. package/lib/deltaManagerProxy.js.map +1 -1
  98. package/lib/deltaQueue.d.ts.map +1 -1
  99. package/lib/deltaQueue.js +4 -2
  100. package/lib/deltaQueue.js.map +1 -1
  101. package/lib/index.d.ts +1 -1
  102. package/lib/index.d.ts.map +1 -1
  103. package/lib/index.js.map +1 -1
  104. package/lib/loader.d.ts +3 -3
  105. package/lib/loader.d.ts.map +1 -1
  106. package/lib/loader.js +18 -15
  107. package/lib/loader.js.map +1 -1
  108. package/lib/packageVersion.d.ts +1 -1
  109. package/lib/packageVersion.js +1 -1
  110. package/lib/packageVersion.js.map +1 -1
  111. package/lib/protocol.d.ts.map +1 -1
  112. package/lib/protocol.js +2 -1
  113. package/lib/protocol.js.map +1 -1
  114. package/lib/protocolTreeDocumentStorageService.d.ts.map +1 -1
  115. package/lib/protocolTreeDocumentStorageService.js.map +1 -1
  116. package/lib/quorum.d.ts.map +1 -1
  117. package/lib/quorum.js.map +1 -1
  118. package/lib/retriableDocumentStorageService.d.ts.map +1 -1
  119. package/lib/retriableDocumentStorageService.js +6 -2
  120. package/lib/retriableDocumentStorageService.js.map +1 -1
  121. package/lib/utils.d.ts.map +1 -1
  122. package/lib/utils.js +6 -4
  123. package/lib/utils.js.map +1 -1
  124. package/package.json +115 -114
  125. package/prettier.config.cjs +1 -1
  126. package/src/audience.ts +51 -46
  127. package/src/catchUpMonitor.ts +39 -37
  128. package/src/collabWindowTracker.ts +75 -70
  129. package/src/connectionManager.ts +1006 -944
  130. package/src/connectionState.ts +19 -19
  131. package/src/connectionStateHandler.ts +544 -465
  132. package/src/container.ts +2056 -1909
  133. package/src/containerContext.ts +350 -340
  134. package/src/containerStorageAdapter.ts +163 -153
  135. package/src/contracts.ts +155 -153
  136. package/src/deltaManager.ts +1069 -992
  137. package/src/deltaManagerProxy.ts +143 -137
  138. package/src/deltaQueue.ts +155 -151
  139. package/src/index.ts +14 -17
  140. package/src/loader.ts +428 -430
  141. package/src/packageVersion.ts +1 -1
  142. package/src/protocol.ts +93 -87
  143. package/src/protocolTreeDocumentStorageService.ts +30 -33
  144. package/src/quorum.ts +34 -34
  145. package/src/retriableDocumentStorageService.ts +118 -102
  146. package/src/utils.ts +89 -82
  147. package/tsconfig.esnext.json +6 -6
  148. package/tsconfig.json +8 -12
package/src/container.ts CHANGED
@@ -7,87 +7,79 @@
7
7
  import merge from "lodash/merge";
8
8
  import { v4 as uuid } from "uuid";
9
9
  import {
10
- ITelemetryBaseLogger,
11
- ITelemetryLogger,
12
- ITelemetryProperties,
13
- TelemetryEventCategory,
10
+ ITelemetryBaseLogger,
11
+ ITelemetryLogger,
12
+ ITelemetryProperties,
13
+ TelemetryEventCategory,
14
14
  } from "@fluidframework/common-definitions";
15
15
  import { assert, performance, unreachableCase } from "@fluidframework/common-utils";
16
+ import { IRequest, IResponse, IFluidRouter } from "@fluidframework/core-interfaces";
16
17
  import {
17
- IRequest,
18
- IResponse,
19
- IFluidRouter,
20
- FluidObject,
21
- } from "@fluidframework/core-interfaces";
22
- import {
23
- IAudience,
24
- IConnectionDetails,
25
- IContainer,
26
- IContainerEvents,
27
- IDeltaManager,
28
- ICriticalContainerError,
29
- ContainerWarning,
30
- AttachState,
31
- IThrottlingWarning,
32
- ReadOnlyInfo,
33
- IContainerLoadMode,
34
- IFluidCodeDetails,
35
- isFluidCodeDetails,
36
- IBatchMessage,
18
+ IAudience,
19
+ IConnectionDetails,
20
+ IContainer,
21
+ IContainerEvents,
22
+ IDeltaManager,
23
+ ICriticalContainerError,
24
+ ContainerWarning,
25
+ AttachState,
26
+ IThrottlingWarning,
27
+ ReadOnlyInfo,
28
+ IContainerLoadMode,
29
+ IFluidCodeDetails,
30
+ isFluidCodeDetails,
31
+ IBatchMessage,
37
32
  } from "@fluidframework/container-definitions";
33
+ import { GenericError, UsageError } from "@fluidframework/container-utils";
38
34
  import {
39
- GenericError,
40
- UsageError,
41
- } from "@fluidframework/container-utils";
42
- import {
43
- IDocumentService,
44
- IDocumentStorageService,
45
- IFluidResolvedUrl,
46
- IResolvedUrl,
35
+ IDocumentService,
36
+ IDocumentStorageService,
37
+ IFluidResolvedUrl,
38
+ IResolvedUrl,
47
39
  } from "@fluidframework/driver-definitions";
48
40
  import {
49
- readAndParse,
50
- OnlineStatus,
51
- isOnline,
52
- ensureFluidResolvedUrl,
53
- combineAppAndProtocolSummary,
54
- runWithRetry,
55
- isFluidResolvedUrl,
41
+ readAndParse,
42
+ OnlineStatus,
43
+ isOnline,
44
+ ensureFluidResolvedUrl,
45
+ combineAppAndProtocolSummary,
46
+ runWithRetry,
47
+ isFluidResolvedUrl,
56
48
  } from "@fluidframework/driver-utils";
57
49
  import { IQuorumSnapshot } from "@fluidframework/protocol-base";
58
50
  import {
59
- IClient,
60
- IClientConfiguration,
61
- IClientDetails,
62
- ICommittedProposal,
63
- IDocumentAttributes,
64
- IDocumentMessage,
65
- IProtocolState,
66
- IQuorumClients,
67
- IQuorumProposals,
68
- ISequencedClient,
69
- ISequencedDocumentMessage,
70
- ISequencedProposal,
71
- ISignalMessage,
72
- ISnapshotTree,
73
- ISummaryContent,
74
- ISummaryTree,
75
- IVersion,
76
- MessageType,
77
- SummaryType,
51
+ IClient,
52
+ IClientConfiguration,
53
+ IClientDetails,
54
+ ICommittedProposal,
55
+ IDocumentAttributes,
56
+ IDocumentMessage,
57
+ IProtocolState,
58
+ IQuorumClients,
59
+ IQuorumProposals,
60
+ ISequencedClient,
61
+ ISequencedDocumentMessage,
62
+ ISequencedProposal,
63
+ ISignalMessage,
64
+ ISnapshotTree,
65
+ ISummaryContent,
66
+ ISummaryTree,
67
+ IVersion,
68
+ MessageType,
69
+ SummaryType,
78
70
  } from "@fluidframework/protocol-definitions";
79
71
  import {
80
- ChildLogger,
81
- EventEmitterWithErrorHandling,
82
- PerformanceEvent,
83
- raiseConnectedEvent,
84
- TelemetryLogger,
85
- connectedEventName,
86
- disconnectedEventName,
87
- normalizeError,
88
- MonitoringContext,
89
- loggerToMonitoringContext,
90
- wrapError,
72
+ ChildLogger,
73
+ EventEmitterWithErrorHandling,
74
+ PerformanceEvent,
75
+ raiseConnectedEvent,
76
+ TelemetryLogger,
77
+ connectedEventName,
78
+ disconnectedEventName,
79
+ normalizeError,
80
+ MonitoringContext,
81
+ loggerToMonitoringContext,
82
+ wrapError,
91
83
  } from "@fluidframework/telemetry-utils";
92
84
  import { Audience } from "./audience";
93
85
  import { ContainerContext } from "./containerContext";
@@ -97,20 +89,17 @@ import { DeltaManagerProxy } from "./deltaManagerProxy";
97
89
  import { ILoaderOptions, Loader, RelativeLoader } from "./loader";
98
90
  import { pkgVersion } from "./packageVersion";
99
91
  import { ContainerStorageAdapter } from "./containerStorageAdapter";
100
- import {
101
- IConnectionStateHandler,
102
- createConnectionStateHandler,
103
- } from "./connectionStateHandler";
92
+ import { IConnectionStateHandler, createConnectionStateHandler } from "./connectionStateHandler";
104
93
  import { getProtocolSnapshotTree, getSnapshotTreeFromSerializedContainer } from "./utils";
105
- import { initQuorumValuesFromCodeDetails, getCodeDetailsFromQuorumValues, QuorumProxy } from "./quorum";
94
+ import {
95
+ initQuorumValuesFromCodeDetails,
96
+ getCodeDetailsFromQuorumValues,
97
+ QuorumProxy,
98
+ } from "./quorum";
106
99
  import { CollabWindowTracker } from "./collabWindowTracker";
107
100
  import { ConnectionManager } from "./connectionManager";
108
101
  import { ConnectionState } from "./connectionState";
109
- import {
110
- IProtocolHandler,
111
- ProtocolHandler,
112
- ProtocolHandlerBuilder,
113
- } from "./protocol";
102
+ import { IProtocolHandler, ProtocolHandler, ProtocolHandlerBuilder } from "./protocol";
114
103
 
115
104
  const detachedContainerRefSeqNumber = 0;
116
105
 
@@ -118,54 +107,46 @@ const dirtyContainerEvent = "dirty";
118
107
  const savedContainerEvent = "saved";
119
108
 
120
109
  export interface IContainerLoadOptions {
121
- /**
122
- * Disables the Container from reconnecting if false, allows reconnect otherwise.
123
- */
124
- canReconnect?: boolean;
125
- /**
126
- * Client details provided in the override will be merged over the default client.
127
- */
128
- clientDetailsOverride?: IClientDetails;
129
- resolvedUrl: IFluidResolvedUrl;
130
- /**
131
- * Control which snapshot version to load from. See IParsedUrl for detailed information.
132
- */
133
- version: string | undefined;
134
- /**
135
- * Loads the Container in paused state if true, unpaused otherwise.
136
- */
137
- loadMode?: IContainerLoadMode;
138
- /**
139
- * A logger that the container will use for logging operations. If not provided, the container will
140
- * use the loader's logger, `Loader.services.subLogger`.
141
- */
142
- baseLogger?: ITelemetryBaseLogger;
143
- /**
144
- * A scope object to replace the one provided on the Loader.
145
- */
146
- scopeOverride?: FluidObject;
110
+ /**
111
+ * Disables the Container from reconnecting if false, allows reconnect otherwise.
112
+ */
113
+ canReconnect?: boolean;
114
+ /**
115
+ * Client details provided in the override will be merged over the default client.
116
+ */
117
+ clientDetailsOverride?: IClientDetails;
118
+ resolvedUrl: IFluidResolvedUrl;
119
+ /**
120
+ * Control which snapshot version to load from. See IParsedUrl for detailed information.
121
+ */
122
+ version: string | undefined;
123
+ /**
124
+ * Loads the Container in paused state if true, unpaused otherwise.
125
+ */
126
+ loadMode?: IContainerLoadMode;
127
+ /**
128
+ * A logger that the container will use for logging operations. If not provided, the container will
129
+ * use the loader's logger, `Loader.services.subLogger`.
130
+ */
131
+ baseLogger?: ITelemetryBaseLogger;
147
132
  }
148
133
 
149
134
  export interface IContainerConfig {
150
- resolvedUrl?: IFluidResolvedUrl;
151
- canReconnect?: boolean;
152
- /**
153
- * Client details provided in the override will be merged over the default client.
154
- */
155
- clientDetailsOverride?: IClientDetails;
156
- /**
157
- * Serialized state from a previous instance of this container
158
- */
159
- serializedContainerState?: IPendingContainerState;
160
- /**
161
- * A logger that the container will use for logging operations. If not provided, the container will
162
- * use the loader's logger, `Loader.services.subLogger`.
163
- */
164
- baseLogger?: ITelemetryBaseLogger;
165
- /**
166
- * A scope object to replace the one provided on the Loader.
167
- */
168
- scopeOverride?: FluidObject;
135
+ resolvedUrl?: IFluidResolvedUrl;
136
+ canReconnect?: boolean;
137
+ /**
138
+ * Client details provided in the override will be merged over the default client.
139
+ */
140
+ clientDetailsOverride?: IClientDetails;
141
+ /**
142
+ * Serialized state from a previous instance of this container
143
+ */
144
+ serializedContainerState?: IPendingContainerState;
145
+ /**
146
+ * A logger that the container will use for logging operations. If not provided, the container will
147
+ * use the loader's logger, `Loader.services.subLogger`.
148
+ */
149
+ baseLogger?: ITelemetryBaseLogger;
169
150
  }
170
151
 
171
152
  /**
@@ -185,77 +166,84 @@ export interface IContainerConfig {
185
166
  * @throws an error beginning with `"Container closed"` if the container is closed before it catches up.
186
167
  */
187
168
  export async function waitContainerToCatchUp(container: IContainer) {
188
- // Make sure we stop waiting if container is closed.
189
- if (container.closed) {
190
- throw new UsageError("waitContainerToCatchUp: Container closed");
191
- }
192
-
193
- return new Promise<boolean>((resolve, reject) => {
194
- const deltaManager = container.deltaManager;
195
-
196
- const closedCallback = (err?: ICriticalContainerError | undefined) => {
197
- container.off("closed", closedCallback);
198
- const baseMessage = "Container closed while waiting to catch up";
199
- reject(
200
- err !== undefined
201
- ? wrapError(err, (innerMessage) => new GenericError(`${baseMessage}: ${innerMessage}`))
202
- : new GenericError(baseMessage),
203
- );
204
- };
205
- container.on("closed", closedCallback);
206
-
207
- // Depending on config, transition to "connected" state may include the guarantee
208
- // that all known ops have been processed. If so, we may introduce additional wait here.
209
- // Waiting for "connected" state in either case gets us at least to our own Join op
210
- // which is a reasonable approximation of "caught up"
211
- const waitForOps = () => {
212
- assert(container.connectionState === ConnectionState.CatchingUp
213
- || container.connectionState === ConnectionState.Connected,
214
- 0x0cd /* "Container disconnected while waiting for ops!" */);
215
- const hasCheckpointSequenceNumber = deltaManager.hasCheckpointSequenceNumber;
216
-
217
- const connectionOpSeqNumber = deltaManager.lastKnownSeqNumber;
218
- assert(deltaManager.lastSequenceNumber <= connectionOpSeqNumber,
219
- 0x266 /* "lastKnownSeqNumber should never be below last processed sequence number" */);
220
- if (deltaManager.lastSequenceNumber === connectionOpSeqNumber) {
221
- container.off("closed", closedCallback);
222
- resolve(hasCheckpointSequenceNumber);
223
- return;
224
- }
225
- const callbackOps = (message: ISequencedDocumentMessage) => {
226
- if (connectionOpSeqNumber <= message.sequenceNumber) {
227
- container.off("closed", closedCallback);
228
- resolve(hasCheckpointSequenceNumber);
229
- deltaManager.off("op", callbackOps);
230
- }
231
- };
232
- deltaManager.on("op", callbackOps);
233
- };
234
-
235
- // We can leverage DeltaManager's "connect" event here and test for ConnectionState.Disconnected
236
- // But that works only if service provides us checkPointSequenceNumber
237
- // Our internal testing is based on R11S that does not, but almost all tests connect as "write" and
238
- // use this function to catch up, so leveraging our own join op as a fence/barrier
239
- if (container.connectionState === ConnectionState.Connected) {
240
- waitForOps();
241
- return;
242
- }
243
-
244
- const callback = () => {
245
- container.off(connectedEventName, callback);
246
- waitForOps();
247
- };
248
- container.on(connectedEventName, callback);
249
-
250
- if (container.connectionState === ConnectionState.Disconnected) {
251
- container.connect();
252
- }
253
- });
169
+ // Make sure we stop waiting if container is closed.
170
+ if (container.closed) {
171
+ throw new UsageError("waitContainerToCatchUp: Container closed");
172
+ }
173
+
174
+ return new Promise<boolean>((resolve, reject) => {
175
+ const deltaManager = container.deltaManager;
176
+
177
+ const closedCallback = (err?: ICriticalContainerError | undefined) => {
178
+ container.off("closed", closedCallback);
179
+ const baseMessage = "Container closed while waiting to catch up";
180
+ reject(
181
+ err !== undefined
182
+ ? wrapError(
183
+ err,
184
+ (innerMessage) => new GenericError(`${baseMessage}: ${innerMessage}`),
185
+ )
186
+ : new GenericError(baseMessage),
187
+ );
188
+ };
189
+ container.on("closed", closedCallback);
190
+
191
+ // Depending on config, transition to "connected" state may include the guarantee
192
+ // that all known ops have been processed. If so, we may introduce additional wait here.
193
+ // Waiting for "connected" state in either case gets us at least to our own Join op
194
+ // which is a reasonable approximation of "caught up"
195
+ const waitForOps = () => {
196
+ assert(
197
+ container.connectionState === ConnectionState.CatchingUp ||
198
+ container.connectionState === ConnectionState.Connected,
199
+ 0x0cd /* "Container disconnected while waiting for ops!" */,
200
+ );
201
+ const hasCheckpointSequenceNumber = deltaManager.hasCheckpointSequenceNumber;
202
+
203
+ const connectionOpSeqNumber = deltaManager.lastKnownSeqNumber;
204
+ assert(
205
+ deltaManager.lastSequenceNumber <= connectionOpSeqNumber,
206
+ 0x266 /* "lastKnownSeqNumber should never be below last processed sequence number" */,
207
+ );
208
+ if (deltaManager.lastSequenceNumber === connectionOpSeqNumber) {
209
+ container.off("closed", closedCallback);
210
+ resolve(hasCheckpointSequenceNumber);
211
+ return;
212
+ }
213
+ const callbackOps = (message: ISequencedDocumentMessage) => {
214
+ if (connectionOpSeqNumber <= message.sequenceNumber) {
215
+ container.off("closed", closedCallback);
216
+ resolve(hasCheckpointSequenceNumber);
217
+ deltaManager.off("op", callbackOps);
218
+ }
219
+ };
220
+ deltaManager.on("op", callbackOps);
221
+ };
222
+
223
+ // We can leverage DeltaManager's "connect" event here and test for ConnectionState.Disconnected
224
+ // But that works only if service provides us checkPointSequenceNumber
225
+ // Our internal testing is based on R11S that does not, but almost all tests connect as "write" and
226
+ // use this function to catch up, so leveraging our own join op as a fence/barrier
227
+ if (container.connectionState === ConnectionState.Connected) {
228
+ waitForOps();
229
+ return;
230
+ }
231
+
232
+ const callback = () => {
233
+ container.off(connectedEventName, callback);
234
+ waitForOps();
235
+ };
236
+ container.on(connectedEventName, callback);
237
+
238
+ if (container.connectionState === ConnectionState.Disconnected) {
239
+ container.connect();
240
+ }
241
+ });
254
242
  }
255
243
 
256
244
  const getCodeProposal =
257
- // eslint-disable-next-line @typescript-eslint/no-unsafe-return
258
- (quorum: IQuorumProposals) => quorum.get("code") ?? quorum.get("code2");
245
+ // eslint-disable-next-line @typescript-eslint/no-unsafe-return
246
+ (quorum: IQuorumProposals) => quorum.get("code") ?? quorum.get("code2");
259
247
 
260
248
  /**
261
249
  * Helper function to report to telemetry cases where operation takes longer than expected (200ms)
@@ -264,15 +252,15 @@ const getCodeProposal =
264
252
  * @param action - functor to call and measure
265
253
  */
266
254
  export async function ReportIfTooLong(
267
- logger: ITelemetryLogger,
268
- eventName: string,
269
- action: () => Promise<ITelemetryProperties>,
255
+ logger: ITelemetryLogger,
256
+ eventName: string,
257
+ action: () => Promise<ITelemetryProperties>,
270
258
  ) {
271
- const event = PerformanceEvent.start(logger, { eventName });
272
- const props = await action();
273
- if (event.duration > 200) {
274
- event.end(props);
275
- }
259
+ const event = PerformanceEvent.start(logger, { eventName });
260
+ const props = await action();
261
+ if (event.duration > 200) {
262
+ event.end(props);
263
+ }
276
264
  }
277
265
 
278
266
  /**
@@ -280,1717 +268,1876 @@ export async function ReportIfTooLong(
280
268
  * of the container to the same state
281
269
  */
282
270
  export interface IPendingContainerState {
283
- pendingRuntimeState: unknown;
284
- url: string;
285
- protocol: IProtocolState;
286
- term: number;
287
- clientId?: string;
271
+ pendingRuntimeState: unknown;
272
+ url: string;
273
+ protocol: IProtocolState;
274
+ term: number;
275
+ clientId?: string;
288
276
  }
289
277
 
290
278
  const summarizerClientType = "summarizer";
291
279
 
292
- export class Container extends EventEmitterWithErrorHandling<IContainerEvents> implements IContainer {
293
- public static version = "^0.1.0";
294
-
295
- /**
296
- * Load an existing container.
297
- */
298
- public static async load(
299
- loader: Loader,
300
- loadOptions: IContainerLoadOptions,
301
- pendingLocalState?: IPendingContainerState,
302
- protocolHandlerBuilder?: ProtocolHandlerBuilder,
303
- ): Promise<Container> {
304
- const container = new Container(
305
- loader,
306
- {
307
- clientDetailsOverride: loadOptions.clientDetailsOverride,
308
- resolvedUrl: loadOptions.resolvedUrl,
309
- canReconnect: loadOptions.canReconnect,
310
- serializedContainerState: pendingLocalState,
311
- baseLogger: loadOptions.baseLogger,
312
- scopeOverride: loadOptions.scopeOverride,
313
- },
314
- protocolHandlerBuilder);
315
-
316
- return PerformanceEvent.timedExecAsync(
317
- container.mc.logger,
318
- { eventName: "Load" },
319
- async (event) => new Promise<Container>((resolve, reject) => {
320
- const version = loadOptions.version;
321
-
322
- const defaultMode: IContainerLoadMode = { opsBeforeReturn: "cached" };
323
- // if we have pendingLocalState, anything we cached is not useful and we shouldn't wait for connection
324
- // to return container, so ignore this value and use undefined for opsBeforeReturn
325
- const mode: IContainerLoadMode = pendingLocalState
326
- ? { ...(loadOptions.loadMode ?? defaultMode), opsBeforeReturn: undefined }
327
- : loadOptions.loadMode ?? defaultMode;
328
-
329
- const onClosed = (err?: ICriticalContainerError) => {
330
- // pre-0.58 error message: containerClosedWithoutErrorDuringLoad
331
- reject(err ?? new GenericError("Container closed without error during load"));
332
- };
333
- container.on("closed", onClosed);
334
-
335
- container.load(version, mode, pendingLocalState)
336
- .finally(() => {
337
- container.removeListener("closed", onClosed);
338
- })
339
- .then((props) => {
340
- event.end({ ...props, ...loadOptions.loadMode });
341
- resolve(container);
342
- },
343
- (error) => {
344
- const err = normalizeError(error);
345
- // Depending where error happens, we can be attempting to connect to web socket
346
- // and continuously retrying (consider offline mode)
347
- // Host has no container to close, so it's prudent to do it here
348
- container.close(err);
349
- onClosed(err);
350
- });
351
- }),
352
- { start: true, end: true, cancel: "generic" },
353
- );
354
- }
355
-
356
- /**
357
- * Create a new container in a detached state.
358
- */
359
- public static async createDetached(
360
- loader: Loader,
361
- codeDetails: IFluidCodeDetails,
362
- protocolHandlerBuilder?: ProtocolHandlerBuilder,
363
- ): Promise<Container> {
364
- const container = new Container(
365
- loader,
366
- {},
367
- protocolHandlerBuilder);
368
-
369
- return PerformanceEvent.timedExecAsync(
370
- container.mc.logger,
371
- { eventName: "CreateDetached" },
372
- async (_event) => {
373
- await container.createDetached(codeDetails);
374
- return container;
375
- },
376
- { start: true, end: true, cancel: "generic" });
377
- }
378
-
379
- /**
380
- * Create a new container in a detached state that is initialized with a
381
- * snapshot from a previous detached container.
382
- */
383
- public static async rehydrateDetachedFromSnapshot(
384
- loader: Loader,
385
- snapshot: string,
386
- protocolHandlerBuilder?: ProtocolHandlerBuilder,
387
- ): Promise<Container> {
388
- const container = new Container(
389
- loader,
390
- {},
391
- protocolHandlerBuilder);
392
-
393
- return PerformanceEvent.timedExecAsync(
394
- container.mc.logger,
395
- { eventName: "RehydrateDetachedFromSnapshot" },
396
- async (_event) => {
397
- const deserializedSummary = JSON.parse(snapshot) as ISummaryTree;
398
- await container.rehydrateDetachedFromSnapshot(deserializedSummary);
399
- return container;
400
- },
401
- { start: true, end: true, cancel: "generic" });
402
- }
403
-
404
- public subLogger: TelemetryLogger;
405
-
406
- // Tells if container can reconnect on losing fist connection
407
- // If false, container gets closed on loss of connection.
408
- private readonly _canReconnect: boolean = true;
409
-
410
- private readonly mc: MonitoringContext;
411
-
412
- /**
413
- * Lifecycle state of the container, used mainly to prevent re-entrancy and telemetry
414
- *
415
- * States are allowed to progress to further states:
416
- * "loading" - "loaded" - "closing" - "disposing" - "closed" - "disposed"
417
- *
418
- * For example, moving from "closed" to "disposing" is not allowed since it is an earlier state.
419
- *
420
- * loading: Container has been created, but is not yet in normal/loaded state
421
- * loaded: Container is in normal/loaded state
422
- * closing: Container has started closing process (for re-entrancy prevention)
423
- * disposing: Container has started disposing process (for re-entrancy prevention)
424
- * closed: Container has closed
425
- * disposed: Container has been disposed
426
- */
427
- private _lifecycleState: "loading" | "loaded" | "closing" | "disposing" | "closed" | "disposed" = "loading";
428
-
429
- private setLoaded() {
430
- // It's conceivable the container could be closed when this is called
431
- // Only transition states if currently loading
432
- if (this._lifecycleState === "loading") {
433
- // Propagate current connection state through the system.
434
- this.propagateConnectionState(true /* initial transition */);
435
- this._lifecycleState = "loaded";
436
- }
437
- }
438
-
439
- public get closed(): boolean {
440
- return (this._lifecycleState === "closing" || this._lifecycleState === "closed"
441
- || this._lifecycleState === "disposing" || this._lifecycleState === "disposed");
442
- }
443
-
444
- private _attachState = AttachState.Detached;
445
-
446
- private readonly storageService: ContainerStorageAdapter;
447
- public get storage(): IDocumentStorageService {
448
- return this.storageService;
449
- }
450
-
451
- private readonly clientDetailsOverride: IClientDetails | undefined;
452
- private readonly _scopeOverride: FluidObject | undefined;
453
- private readonly _deltaManager: DeltaManager<ConnectionManager>;
454
- private service: IDocumentService | undefined;
455
-
456
- private _context: ContainerContext | undefined;
457
- private get context() {
458
- if (this._context === undefined) {
459
- throw new GenericError("Attempted to access context before it was defined");
460
- }
461
- return this._context;
462
- }
463
- private _protocolHandler: IProtocolHandler | undefined;
464
- private get protocolHandler() {
465
- if (this._protocolHandler === undefined) {
466
- throw new Error("Attempted to access protocolHandler before it was defined");
467
- }
468
- return this._protocolHandler;
469
- }
470
-
471
- /** During initialization we pause the inbound queues. We track this state to ensure we only call resume once */
472
- private inboundQueuePausedFromInit = true;
473
- private firstConnection = true;
474
- private readonly connectionTransitionTimes: number[] = [];
475
- private messageCountAfterDisconnection: number = 0;
476
- private _loadedFromVersion: IVersion | undefined;
477
- private _resolvedUrl: IFluidResolvedUrl | undefined;
478
- private attachStarted = false;
479
- private _dirtyContainer = false;
480
-
481
- private lastVisible: number | undefined;
482
- private readonly visibilityEventHandler: (() => void) | undefined;
483
- private readonly connectionStateHandler: IConnectionStateHandler;
484
-
485
- private setAutoReconnectTime = performance.now();
486
-
487
- private collabWindowTracker: CollabWindowTracker | undefined;
488
-
489
- private get connectionMode() { return this._deltaManager.connectionManager.connectionMode; }
490
-
491
- public get IFluidRouter(): IFluidRouter { return this; }
492
-
493
- public get resolvedUrl(): IResolvedUrl | undefined {
494
- return this._resolvedUrl;
495
- }
496
-
497
- public get loadedFromVersion(): IVersion | undefined {
498
- return this._loadedFromVersion;
499
- }
500
-
501
- public get readOnlyInfo(): ReadOnlyInfo {
502
- return this._deltaManager.readOnlyInfo;
503
- }
504
-
505
- public get closeSignal(): AbortSignal {
506
- return this._deltaManager.closeAbortController.signal;
507
- }
508
-
509
- /**
510
- * Tracks host requiring read-only mode.
511
- */
512
- public forceReadonly(readonly: boolean) {
513
- this._deltaManager.connectionManager.forceReadonly(readonly);
514
- }
515
-
516
- public get deltaManager(): IDeltaManager<ISequencedDocumentMessage, IDocumentMessage> {
517
- return this._deltaManager;
518
- }
519
-
520
- public get connectionState(): ConnectionState {
521
- return this.connectionStateHandler.connectionState;
522
- }
523
-
524
- public get connected(): boolean {
525
- return this.connectionStateHandler.connectionState === ConnectionState.Connected;
526
- }
527
-
528
- /**
529
- * Service configuration details. If running in offline mode will be undefined otherwise will contain service
530
- * configuration details returned as part of the initial connection.
531
- */
532
- public get serviceConfiguration(): IClientConfiguration | undefined {
533
- return this._deltaManager.serviceConfiguration;
534
- }
535
-
536
- private _clientId: string | undefined;
537
-
538
- /**
539
- * The server provided id of the client.
540
- * Set once this.connected is true, otherwise undefined
541
- */
542
- public get clientId(): string | undefined {
543
- return this._clientId;
544
- }
545
-
546
- /**
547
- * The server provided claims of the client.
548
- * Set once this.connected is true, otherwise undefined
549
- */
550
- public get scopes(): string[] | undefined {
551
- return this._deltaManager.connectionManager.scopes;
552
- }
553
-
554
- public get clientDetails(): IClientDetails {
555
- return this._deltaManager.clientDetails;
556
- }
557
-
558
- /**
559
- * Get the code details that are currently specified for the container.
560
- * @returns The current code details if any are specified, undefined if none are specified.
561
- */
562
- public getSpecifiedCodeDetails(): IFluidCodeDetails | undefined {
563
- return this.getCodeDetailsFromQuorum();
564
- }
565
-
566
- /**
567
- * Get the code details that were used to load the container.
568
- * @returns The code details that were used to load the container if it is loaded, undefined if it is not yet
569
- * loaded.
570
- */
571
- public getLoadedCodeDetails(): IFluidCodeDetails | undefined {
572
- return this._context?.codeDetails;
573
- }
574
-
575
- /**
576
- * Retrieves the audience associated with the document
577
- */
578
- public get audience(): IAudience {
579
- return this.protocolHandler.audience;
580
- }
581
-
582
- /**
583
- * Returns true if container is dirty.
584
- * Which means data loss if container is closed at that same moment
585
- * Most likely that happens when there is no network connection to Relay Service
586
- */
587
- public get isDirty() {
588
- return this._dirtyContainer;
589
- }
590
-
591
- private get serviceFactory() { return this.loader.services.documentServiceFactory; }
592
- private get urlResolver() { return this.loader.services.urlResolver; }
593
- public readonly options: ILoaderOptions;
594
- private get scope() { return this._scopeOverride ?? this.loader.services.scope; }
595
- private get codeLoader() { return this.loader.services.codeLoader; }
596
-
597
- constructor(
598
- private readonly loader: Loader,
599
- config: IContainerConfig,
600
- private readonly protocolHandlerBuilder?: ProtocolHandlerBuilder,
601
- ) {
602
- super((name, error) => {
603
- this.mc.logger.sendErrorEvent(
604
- {
605
- eventName: "ContainerEventHandlerException",
606
- name: typeof name === "string" ? name : undefined,
607
- },
608
- error);
609
- });
610
-
611
- this.clientDetailsOverride = config.clientDetailsOverride;
612
- this._scopeOverride = config.scopeOverride;
613
- this._resolvedUrl = config.resolvedUrl;
614
- if (config.canReconnect !== undefined) {
615
- this._canReconnect = config.canReconnect;
616
- }
617
-
618
- // Create logger for data stores to use
619
- const type = this.client.details.type;
620
- const interactive = this.client.details.capabilities.interactive;
621
- const clientType =
622
- `${interactive ? "interactive" : "noninteractive"}${type !== undefined && type !== "" ? `/${type}` : ""}`;
623
- // Need to use the property getter for docId because for detached flow we don't have the docId initially.
624
- // We assign the id later so property getter is used.
625
- this.subLogger = ChildLogger.create(
626
- // If a baseLogger was provided, use it; otherwise use the loader's logger.
627
- config.baseLogger ?? loader.services.subLogger,
628
- undefined,
629
- {
630
- all: {
631
- clientType, // Differentiating summarizer container from main container
632
- containerId: uuid(),
633
- docId: () => this._resolvedUrl?.id ?? undefined,
634
- containerAttachState: () => this._attachState,
635
- containerLifecycleState: () => this._lifecycleState,
636
- containerConnectionState: () => ConnectionState[this.connectionState],
637
- serializedContainer: config.serializedContainerState !== undefined,
638
- },
639
- // we need to be judicious with our logging here to avoid generating too much data
640
- // all data logged here should be broadly applicable, and not specific to a
641
- // specific error or class of errors
642
- error: {
643
- // load information to associate errors with the specific load point
644
- dmInitialSeqNumber: () => this._deltaManager?.initialSequenceNumber,
645
- dmLastProcessedSeqNumber: () => this._deltaManager?.lastSequenceNumber,
646
- dmLastKnownSeqNumber: () => this._deltaManager?.lastKnownSeqNumber,
647
- containerLoadedFromVersionId: () => this.loadedFromVersion?.id,
648
- containerLoadedFromVersionDate: () => this.loadedFromVersion?.date,
649
- // message information to associate errors with the specific execution state
650
- // dmLastMsqSeqNumber: if present, same as dmLastProcessedSeqNumber
651
- dmLastMsqSeqNumber: () => this.deltaManager?.lastMessage?.sequenceNumber,
652
- dmLastMsqSeqTimestamp: () => this.deltaManager?.lastMessage?.timestamp,
653
- dmLastMsqSeqClientId: () => this.deltaManager?.lastMessage?.clientId,
654
- connectionStateDuration:
655
- () => performance.now() - this.connectionTransitionTimes[this.connectionState],
656
- },
657
- });
658
-
659
- // Prefix all events in this file with container-loader
660
- this.mc = loggerToMonitoringContext(ChildLogger.create(this.subLogger, "Container"));
661
-
662
- const summarizeProtocolTree =
663
- this.mc.config.getBoolean("Fluid.Container.summarizeProtocolTree2")
664
- ?? this.loader.services.options.summarizeProtocolTree;
665
-
666
- this.options = {
667
- ... this.loader.services.options,
668
- summarizeProtocolTree,
669
- };
670
-
671
- this._deltaManager = this.createDeltaManager();
672
-
673
- this._clientId = config.serializedContainerState?.clientId;
674
- this.connectionStateHandler = createConnectionStateHandler(
675
- {
676
- logger: this.mc.logger,
677
- connectionStateChanged: (value, oldState, reason) => {
678
- if (value === ConnectionState.Connected) {
679
- this._clientId = this.connectionStateHandler.pendingClientId;
680
- }
681
- this.logConnectionStateChangeTelemetry(value, oldState, reason);
682
- if (this._lifecycleState === "loaded") {
683
- this.propagateConnectionState(
684
- false /* initial transition */,
685
- value === ConnectionState.Disconnected ? reason : undefined /* disconnectedReason */,
686
- );
687
- }
688
- },
689
- shouldClientJoinWrite: () => this._deltaManager.connectionManager.shouldJoinWrite(),
690
- maxClientLeaveWaitTime: this.loader.services.options.maxClientLeaveWaitTime,
691
- logConnectionIssue: (eventName: string, category: TelemetryEventCategory, details?: ITelemetryProperties) => {
692
- const mode = this.connectionMode;
693
- // We get here when socket does not receive any ops on "write" connection, including
694
- // its own join op.
695
- // Report issues only if we already loaded container - op processing is paused while container is loading,
696
- // so we always time-out processing of join op in cases where fetching snapshot takes a minute.
697
- // It's not a problem with op processing itself - such issues should be tracked as part of boot perf monitoring instead.
698
- this._deltaManager.logConnectionIssue({
699
- eventName,
700
- mode,
701
- category: (this._lifecycleState === "loading") ? "generic" : category,
702
- duration: performance.now() - this.connectionTransitionTimes[ConnectionState.CatchingUp],
703
- ...(details === undefined ? {} : { details: JSON.stringify(details) }),
704
- });
705
-
706
- // If this is "write" connection, it took too long to receive join op. But in most cases that's due
707
- // to very slow op fetches and we will eventually get there.
708
- // For "read" connections, we get here due to self join signal not arriving on time. We will need to
709
- // better understand when and why it may happen.
710
- // For now, attempt to recover by reconnecting. In future, maybe we can query relay service for
711
- // current state of audience.
712
- // Other possible recovery path - move to connected state (i.e. ConnectionStateHandler.joinOpTimer
713
- // to call this.applyForConnectedState("addMemberEvent") for "read" connections)
714
- if (mode === "read") {
715
- this.disconnect();
716
- this.connect();
717
- }
718
- },
719
- },
720
- this.deltaManager,
721
- this._clientId,
722
- );
723
-
724
- this.on(savedContainerEvent, () => {
725
- this.connectionStateHandler.containerSaved();
726
- });
727
-
728
- this.storageService = new ContainerStorageAdapter(
729
- this.loader.services.detachedBlobStorage,
730
- this.mc.logger,
731
- this.options.summarizeProtocolTree === true
732
- ? () => this.captureProtocolSummary()
733
- : undefined,
734
- );
735
-
736
- const isDomAvailable = typeof document === "object" &&
737
- document !== null &&
738
- typeof document.addEventListener === "function" &&
739
- document.addEventListener !== null;
740
- // keep track of last time page was visible for telemetry
741
- if (isDomAvailable) {
742
- this.lastVisible = document.hidden ? performance.now() : undefined;
743
- this.visibilityEventHandler = () => {
744
- if (document.hidden) {
745
- this.lastVisible = performance.now();
746
- } else {
747
- // settimeout so this will hopefully fire after disconnect event if being hidden caused it
748
- setTimeout(() => { this.lastVisible = undefined; }, 0);
749
- }
750
- };
751
- document.addEventListener("visibilitychange", this.visibilityEventHandler);
752
- }
753
-
754
- // We observed that most users of platform do not check Container.connected event on load, causing bugs.
755
- // As such, we are raising events when new listener pops up.
756
- // Note that we can raise both "disconnected" & "connect" events at the same time,
757
- // if we are in connecting stage.
758
- this.on("newListener", (event: string, listener: (...args: any[]) => void) => {
759
- // Fire events on the end of JS turn, giving a chance for caller to be in consistent state.
760
- Promise.resolve().then(() => {
761
- switch (event) {
762
- case dirtyContainerEvent:
763
- if (this._dirtyContainer) {
764
- listener();
765
- }
766
- break;
767
- case savedContainerEvent:
768
- if (!this._dirtyContainer) {
769
- listener();
770
- }
771
- break;
772
- case connectedEventName:
773
- if (this.connected) {
774
- listener(this.clientId);
775
- }
776
- break;
777
- case disconnectedEventName:
778
- if (!this.connected) {
779
- listener();
780
- }
781
- break;
782
- default:
783
- }
784
- }).catch((error) => {
785
- this.mc.logger.sendErrorEvent({ eventName: "RaiseConnectedEventError" }, error);
786
- });
787
- });
788
- }
789
-
790
- /**
791
- * Retrieves the quorum associated with the document
792
- */
793
- public getQuorum(): IQuorumClients {
794
- return this.protocolHandler.quorum;
795
- }
796
-
797
- public dispose?(error?: ICriticalContainerError) {
798
- this._deltaManager.close(error, true /* doDispose */);
799
- this.verifyClosed();
800
- }
801
-
802
- public close(error?: ICriticalContainerError) {
803
- // 1. Ensure that close sequence is exactly the same no matter if it's initiated by host or by DeltaManager
804
- // 2. We need to ensure that we deliver disconnect event to runtime properly. See connectionStateChanged
805
- // handler. We only deliver events if container fully loaded. Transitioning from "loading" ->
806
- // "closing" will lose that info (can also solve by tracking extra state).
807
- this._deltaManager.close(error);
808
- this.verifyClosed();
809
- }
810
-
811
- private verifyClosed(): void {
812
- assert(this.connectionState === ConnectionState.Disconnected,
813
- 0x0cf /* "disconnect event was not raised!" */);
814
-
815
- assert(this._lifecycleState === "closed" || this._lifecycleState === "disposed", 0x314 /* Container properly closed */);
816
- }
817
-
818
- private closeCore(error?: ICriticalContainerError) {
819
- assert(!this.closed, 0x315 /* re-entrancy */);
820
-
821
- try {
822
- // Ensure that we raise all key events even if one of these throws
823
- try {
824
- // Raise event first, to ensure we capture _lifecycleState before transition.
825
- // This gives us a chance to know what errors happened on open vs. on fully loaded container.
826
- this.mc.logger.sendTelemetryEvent(
827
- {
828
- eventName: "ContainerClose",
829
- category: error === undefined ? "generic" : "error",
830
- },
831
- error,
832
- );
833
-
834
- this._lifecycleState = "closing";
835
-
836
- this._protocolHandler?.close();
837
-
838
- this.connectionStateHandler.dispose();
839
-
840
- this._context?.dispose(error !== undefined ? new Error(error.message) : undefined);
841
-
842
- this.storageService.dispose();
843
-
844
- // Notify storage about critical errors. They may be due to disconnect between client & server knowledge
845
- // about file, like file being overwritten in storage, but client having stale local cache.
846
- // Driver need to ensure all caches are cleared on critical errors
847
- this.service?.dispose(error);
848
- } catch (exception) {
849
- this.mc.logger.sendErrorEvent({ eventName: "ContainerCloseException" }, exception);
850
- }
851
-
852
- this.emit("closed", error);
853
-
854
- if (this.visibilityEventHandler !== undefined) {
855
- document.removeEventListener("visibilitychange", this.visibilityEventHandler);
856
- }
857
- } finally {
858
- this._lifecycleState = "closed";
859
- }
860
- }
861
-
862
- private _disposed = false;
863
- private disposeCore(error?: ICriticalContainerError) {
864
- assert(!this._disposed, 0x54c /* Container already disposed */);
865
- this._disposed = true;
866
-
867
- try {
868
- // Ensure that we raise all key events even if one of these throws
869
- try {
870
- // Raise event first, to ensure we capture _lifecycleState before transition.
871
- // This gives us a chance to know what errors happened on open vs. on fully loaded container.
872
- this.mc.logger.sendTelemetryEvent(
873
- {
874
- eventName: "ContainerDispose",
875
- category: error === undefined ? "generic" : "error",
876
- },
877
- error,
878
- );
879
-
880
- // ! Progressing from "closed" to "disposing" is not allowed
881
- if (this._lifecycleState !== "closed") {
882
- this._lifecycleState = "disposing";
883
- }
884
-
885
- this._protocolHandler?.close();
886
-
887
- this.connectionStateHandler.dispose();
888
-
889
- this._context?.dispose(error !== undefined ? new Error(error.message) : undefined);
890
-
891
- this.storageService.dispose();
892
-
893
- // Notify storage about critical errors. They may be due to disconnect between client & server knowledge
894
- // about file, like file being overwritten in storage, but client having stale local cache.
895
- // Driver need to ensure all caches are cleared on critical errors
896
- this.service?.dispose(error);
897
- } catch (exception) {
898
- this.mc.logger.sendErrorEvent({ eventName: "ContainerDisposeException" }, exception);
899
- }
900
-
901
- this.emit("disposed", error);
902
-
903
- this.removeAllListeners();
904
- if (this.visibilityEventHandler !== undefined) {
905
- document.removeEventListener("visibilitychange", this.visibilityEventHandler);
906
- }
907
- } finally {
908
- this._lifecycleState = "disposed";
909
- }
910
- }
911
-
912
- public closeAndGetPendingLocalState(): string {
913
- // runtime matches pending ops to successful ones by clientId and client seq num, so we need to close the
914
- // container at the same time we get pending state, otherwise this container could reconnect and resubmit with
915
- // a new clientId and a future container using stale pending state without the new clientId would resubmit them
916
- assert(this.attachState === AttachState.Attached, 0x0d1 /* "Container should be attached before close" */);
917
- assert(this.resolvedUrl !== undefined && this.resolvedUrl.type === "fluid",
918
- 0x0d2 /* "resolved url should be valid Fluid url" */);
919
- assert(!!this._protocolHandler, 0x2e3 /* "Must have a valid protocol handler instance" */);
920
- assert(this._protocolHandler.attributes.term !== undefined,
921
- 0x37e /* Must have a valid protocol handler instance */);
922
- const pendingState: IPendingContainerState = {
923
- pendingRuntimeState: this.context.getPendingLocalState(),
924
- url: this.resolvedUrl.url,
925
- protocol: this.protocolHandler.getProtocolState(),
926
- term: this._protocolHandler.attributes.term,
927
- clientId: this.clientId,
928
- };
929
-
930
- this.mc.logger.sendTelemetryEvent({ eventName: "CloseAndGetPendingLocalState" });
931
-
932
- // Only close here as method name suggests
933
- this.close();
934
-
935
- return JSON.stringify(pendingState);
936
- }
937
-
938
- public get attachState(): AttachState {
939
- return this._attachState;
940
- }
941
-
942
- public serialize(): string {
943
- assert(this.attachState === AttachState.Detached, 0x0d3 /* "Should only be called in detached container" */);
944
-
945
- const appSummary: ISummaryTree = this.context.createSummary();
946
- const protocolSummary = this.captureProtocolSummary();
947
- const combinedSummary = combineAppAndProtocolSummary(appSummary, protocolSummary);
948
-
949
- if (this.loader.services.detachedBlobStorage && this.loader.services.detachedBlobStorage.size > 0) {
950
- combinedSummary.tree[".hasAttachmentBlobs"] = { type: SummaryType.Blob, content: "true" };
951
- }
952
- return JSON.stringify(combinedSummary);
953
- }
954
-
955
- public async attach(request: IRequest): Promise<void> {
956
- await PerformanceEvent.timedExecAsync(this.mc.logger, { eventName: "Attach" }, async () => {
957
- if (this._lifecycleState !== "loaded") {
958
- // pre-0.58 error message: containerNotValidForAttach
959
- throw new UsageError(`The Container is not in a valid state for attach [${this._lifecycleState}]`);
960
- }
961
-
962
- // If container is already attached or attach is in progress, throw an error.
963
- assert(this._attachState === AttachState.Detached && !this.attachStarted,
964
- 0x205 /* "attach() called more than once" */);
965
- this.attachStarted = true;
966
-
967
- // If attachment blobs were uploaded in detached state we will go through a different attach flow
968
- const hasAttachmentBlobs = this.loader.services.detachedBlobStorage !== undefined
969
- && this.loader.services.detachedBlobStorage.size > 0;
970
-
971
- try {
972
- assert(this.deltaManager.inbound.length === 0,
973
- 0x0d6 /* "Inbound queue should be empty when attaching" */);
974
-
975
- let summary: ISummaryTree;
976
- if (!hasAttachmentBlobs) {
977
- // Get the document state post attach - possibly can just call attach but we need to change the
978
- // semantics around what the attach means as far as async code goes.
979
- const appSummary: ISummaryTree = this.context.createSummary();
980
- const protocolSummary = this.captureProtocolSummary();
981
- summary = combineAppAndProtocolSummary(appSummary, protocolSummary);
982
-
983
- // Set the state as attaching as we are starting the process of attaching container.
984
- // This should be fired after taking the summary because it is the place where we are
985
- // starting to attach the container to storage.
986
- // Also, this should only be fired in detached container.
987
- this._attachState = AttachState.Attaching;
988
- this.context.notifyAttaching(getSnapshotTreeFromSerializedContainer(summary));
989
- }
990
-
991
- // Actually go and create the resolved document
992
- const createNewResolvedUrl = await this.urlResolver.resolve(request);
993
- ensureFluidResolvedUrl(createNewResolvedUrl);
994
- if (this.service === undefined) {
995
- assert(this.client.details.type !== summarizerClientType,
996
- 0x2c4 /* "client should not be summarizer before container is created" */);
997
- this.service = await runWithRetry(
998
- async () => this.serviceFactory.createContainer(
999
- summary,
1000
- createNewResolvedUrl,
1001
- this.subLogger,
1002
- false, // clientIsSummarizer
1003
- ),
1004
- "containerAttach",
1005
- this.mc.logger,
1006
- {
1007
- cancel: this.closeSignal,
1008
- }, // progress
1009
- );
1010
- }
1011
- const resolvedUrl = this.service.resolvedUrl;
1012
- ensureFluidResolvedUrl(resolvedUrl);
1013
- this._resolvedUrl = resolvedUrl;
1014
- await this.storageService.connectToService(this.service);
1015
-
1016
- if (hasAttachmentBlobs) {
1017
- // upload blobs to storage
1018
- assert(!!this.loader.services.detachedBlobStorage, 0x24e /* "assertion for type narrowing" */);
1019
-
1020
- // build a table mapping IDs assigned locally to IDs assigned by storage and pass it to runtime to
1021
- // support blob handles that only know about the local IDs
1022
- const redirectTable = new Map<string, string>();
1023
- // if new blobs are added while uploading, upload them too
1024
- while (redirectTable.size < this.loader.services.detachedBlobStorage.size) {
1025
- const newIds = this.loader.services.detachedBlobStorage.getBlobIds().filter(
1026
- (id) => !redirectTable.has(id));
1027
- for (const id of newIds) {
1028
- const blob = await this.loader.services.detachedBlobStorage.readBlob(id);
1029
- const response = await this.storageService.createBlob(blob);
1030
- redirectTable.set(id, response.id);
1031
- }
1032
- }
1033
-
1034
- // take summary and upload
1035
- const appSummary: ISummaryTree = this.context.createSummary(redirectTable);
1036
- const protocolSummary = this.captureProtocolSummary();
1037
- summary = combineAppAndProtocolSummary(appSummary, protocolSummary);
1038
-
1039
- this._attachState = AttachState.Attaching;
1040
- this.context.notifyAttaching(getSnapshotTreeFromSerializedContainer(summary));
1041
-
1042
- await this.storageService.uploadSummaryWithContext(summary, {
1043
- referenceSequenceNumber: 0,
1044
- ackHandle: undefined,
1045
- proposalHandle: undefined,
1046
- });
1047
- }
1048
-
1049
- this._attachState = AttachState.Attached;
1050
- this.emit("attached");
1051
-
1052
- if (!this.closed) {
1053
- this.resumeInternal({ fetchOpsFromStorage: false, reason: "createDetached" });
1054
- }
1055
- } catch (error) {
1056
- // add resolved URL on error object so that host has the ability to find this document and delete it
1057
- const newError = normalizeError(error);
1058
- const resolvedUrl = this.resolvedUrl;
1059
- if (isFluidResolvedUrl(resolvedUrl)) {
1060
- newError.addTelemetryProperties({ resolvedUrl: resolvedUrl.url });
1061
- }
1062
- this.close(newError);
1063
- this.dispose?.(newError);
1064
- throw newError;
1065
- }
1066
- },
1067
- { start: true, end: true, cancel: "generic" });
1068
- }
1069
-
1070
- public async request(path: IRequest): Promise<IResponse> {
1071
- return PerformanceEvent.timedExecAsync(
1072
- this.mc.logger,
1073
- { eventName: "Request" },
1074
- async () => this.context.request(path),
1075
- { end: true, cancel: "error" },
1076
- );
1077
- }
1078
-
1079
- private setAutoReconnectInternal(mode: ReconnectMode) {
1080
- const currentMode = this._deltaManager.connectionManager.reconnectMode;
1081
-
1082
- if (currentMode === mode) {
1083
- return;
1084
- }
1085
-
1086
- const now = performance.now();
1087
- const duration = now - this.setAutoReconnectTime;
1088
- this.setAutoReconnectTime = now;
1089
-
1090
- this.mc.logger.sendTelemetryEvent({
1091
- eventName: mode === ReconnectMode.Enabled ? "AutoReconnectEnabled" : "AutoReconnectDisabled",
1092
- connectionMode: this.connectionMode,
1093
- connectionState: ConnectionState[this.connectionState],
1094
- duration,
1095
- });
1096
-
1097
- this._deltaManager.connectionManager.setAutoReconnect(mode);
1098
- }
1099
-
1100
- public connect() {
1101
- if (this.closed) {
1102
- throw new UsageError(`The Container is closed and cannot be connected`);
1103
- } else if (this._attachState !== AttachState.Attached) {
1104
- throw new UsageError(`The Container is not attached and cannot be connected`);
1105
- } else if (!this.connected) {
1106
- // Note: no need to fetch ops as we do it preemptively as part of DeltaManager.attachOpHandler().
1107
- // If there is gap, we will learn about it once connected, but the gap should be small (if any),
1108
- // assuming that connect() is called quickly after initial container boot.
1109
- this.connectInternal({ reason: "DocumentConnect", fetchOpsFromStorage: false });
1110
- }
1111
- }
1112
-
1113
- private connectInternal(args: IConnectionArgs) {
1114
- assert(!this.closed, 0x2c5 /* "Attempting to connect() a closed Container" */);
1115
- assert(this._attachState === AttachState.Attached,
1116
- 0x2c6 /* "Attempting to connect() a container that is not attached" */);
1117
-
1118
- // Resume processing ops and connect to delta stream
1119
- this.resumeInternal(args);
1120
-
1121
- // Set Auto Reconnect Mode
1122
- const mode = ReconnectMode.Enabled;
1123
- this.setAutoReconnectInternal(mode);
1124
- }
1125
-
1126
- public disconnect() {
1127
- if (this.closed) {
1128
- throw new UsageError(`The Container is closed and cannot be disconnected`);
1129
- } else {
1130
- this.disconnectInternal();
1131
- }
1132
- }
1133
-
1134
- private disconnectInternal() {
1135
- assert(!this.closed, 0x2c7 /* "Attempting to disconnect() a closed Container" */);
1136
-
1137
- // Set Auto Reconnect Mode
1138
- const mode = ReconnectMode.Disabled;
1139
- this.setAutoReconnectInternal(mode);
1140
- }
1141
-
1142
- private resumeInternal(args: IConnectionArgs) {
1143
- assert(!this.closed, 0x0d9 /* "Attempting to connect() a closed DeltaManager" */);
1144
-
1145
- // Resume processing ops
1146
- if (this.inboundQueuePausedFromInit) {
1147
- this.inboundQueuePausedFromInit = false;
1148
- this._deltaManager.inbound.resume();
1149
- this._deltaManager.inboundSignal.resume();
1150
- }
1151
-
1152
- // Ensure connection to web socket
1153
- this.connectToDeltaStream(args);
1154
- }
1155
-
1156
- public async getAbsoluteUrl(relativeUrl: string): Promise<string | undefined> {
1157
- if (this.resolvedUrl === undefined) {
1158
- return undefined;
1159
- }
1160
-
1161
- return this.urlResolver.getAbsoluteUrl(
1162
- this.resolvedUrl,
1163
- relativeUrl,
1164
- getPackageName(this._context?.codeDetails));
1165
- }
1166
-
1167
- public async proposeCodeDetails(codeDetails: IFluidCodeDetails) {
1168
- if (!isFluidCodeDetails(codeDetails)) {
1169
- throw new Error("Provided codeDetails are not IFluidCodeDetails");
1170
- }
1171
-
1172
- if (this.codeLoader.IFluidCodeDetailsComparer) {
1173
- const comparison = await this.codeLoader.IFluidCodeDetailsComparer.compare(
1174
- codeDetails,
1175
- this.getCodeDetailsFromQuorum());
1176
- if (comparison !== undefined && comparison <= 0) {
1177
- throw new Error("Proposed code details should be greater than the current");
1178
- }
1179
- }
1180
-
1181
- return this.protocolHandler.quorum.propose("code", codeDetails)
1182
- .then(() => true)
1183
- .catch(() => false);
1184
- }
1185
-
1186
- private async processCodeProposal(): Promise<void> {
1187
- const codeDetails = this.getCodeDetailsFromQuorum();
1188
-
1189
- await Promise.all([
1190
- this.deltaManager.inbound.pause(),
1191
- this.deltaManager.inboundSignal.pause()]);
1192
-
1193
- if ((await this.context.satisfies(codeDetails) === true)) {
1194
- this.deltaManager.inbound.resume();
1195
- this.deltaManager.inboundSignal.resume();
1196
- return;
1197
- }
1198
-
1199
- // pre-0.58 error message: existingContextDoesNotSatisfyIncomingProposal
1200
- const error = new GenericError("Existing context does not satisfy incoming proposal");
1201
- this.close(error);
1202
- this.dispose?.(error);
1203
- }
1204
-
1205
- private async getVersion(version: string | null): Promise<IVersion | undefined> {
1206
- const versions = await this.storageService.getVersions(version, 1);
1207
- return versions[0];
1208
- }
1209
-
1210
- private recordConnectStartTime() {
1211
- if (this.connectionTransitionTimes[ConnectionState.Disconnected] === undefined) {
1212
- this.connectionTransitionTimes[ConnectionState.Disconnected] = performance.now();
1213
- }
1214
- }
1215
-
1216
- private connectToDeltaStream(args: IConnectionArgs) {
1217
- this.recordConnectStartTime();
1218
-
1219
- // All agents need "write" access, including summarizer.
1220
- if (!this._canReconnect || !this.client.details.capabilities.interactive) {
1221
- args.mode = "write";
1222
- }
1223
-
1224
- this._deltaManager.connect(args);
1225
- }
1226
-
1227
- /**
1228
- * Load container.
1229
- *
1230
- * @param specifiedVersion - Version SHA to load snapshot. If not specified, will fetch the latest snapshot.
1231
- */
1232
- private async load(
1233
- specifiedVersion: string | undefined,
1234
- loadMode: IContainerLoadMode,
1235
- pendingLocalState?: IPendingContainerState,
1236
- ) {
1237
- if (this._resolvedUrl === undefined) {
1238
- throw new Error("Attempting to load without a resolved url");
1239
- }
1240
- this.service = await this.serviceFactory.createDocumentService(
1241
- this._resolvedUrl,
1242
- this.subLogger,
1243
- this.client.details.type === summarizerClientType,
1244
- );
1245
-
1246
- // Ideally we always connect as "read" by default.
1247
- // Currently that works with SPO & r11s, because we get "write" connection when connecting to non-existing file.
1248
- // We should not rely on it by (one of them will address the issue, but we need to address both)
1249
- // 1) switching create new flow to one where we create file by posting snapshot
1250
- // 2) Fixing quorum workflows (have retry logic)
1251
- // That all said, "read" does not work with memorylicious workflows (that opens two simultaneous
1252
- // connections to same file) in two ways:
1253
- // A) creation flow breaks (as one of the clients "sees" file as existing, and hits #2 above)
1254
- // B) Once file is created, transition from view-only connection to write does not work - some bugs to be fixed.
1255
- const connectionArgs: IConnectionArgs = { reason: "DocumentOpen", mode: "write", fetchOpsFromStorage: false };
1256
-
1257
- // Start websocket connection as soon as possible. Note that there is no op handler attached yet, but the
1258
- // DeltaManager is resilient to this and will wait to start processing ops until after it is attached.
1259
- if (loadMode.deltaConnection === undefined) {
1260
- this.connectToDeltaStream(connectionArgs);
1261
- }
1262
-
1263
- if (!pendingLocalState) {
1264
- await this.storageService.connectToService(this.service);
1265
- } else {
1266
- // if we have pendingLocalState we can load without storage; don't wait for connection
1267
- this.storageService.connectToService(this.service).catch((error) => {
1268
- this.close(error);
1269
- this.dispose?.(error);
1270
- });
1271
- }
1272
-
1273
- this._attachState = AttachState.Attached;
1274
-
1275
- // Fetch specified snapshot.
1276
- const { snapshot, versionId } = pendingLocalState === undefined
1277
- ? await this.fetchSnapshotTree(specifiedVersion)
1278
- : { snapshot: undefined, versionId: undefined };
1279
- assert(snapshot !== undefined || pendingLocalState !== undefined, 0x237 /* "Snapshot should exist" */);
1280
-
1281
- const attributes: IDocumentAttributes = pendingLocalState === undefined
1282
- ? await this.getDocumentAttributes(this.storageService, snapshot)
1283
- : {
1284
- sequenceNumber: pendingLocalState.protocol.sequenceNumber,
1285
- minimumSequenceNumber: pendingLocalState.protocol.minimumSequenceNumber,
1286
- term: pendingLocalState.term,
1287
- };
1288
-
1289
- let opsBeforeReturnP: Promise<void> | undefined;
1290
-
1291
- // Attach op handlers to finish initialization and be able to start processing ops
1292
- // Kick off any ops fetching if required.
1293
- switch (loadMode.opsBeforeReturn) {
1294
- case undefined:
1295
- // Start prefetch, but not set opsBeforeReturnP - boot is not blocked by it!
1296
- // eslint-disable-next-line @typescript-eslint/no-floating-promises
1297
- this.attachDeltaManagerOpHandler(attributes, loadMode.deltaConnection !== "none" ? "all" : "none");
1298
- break;
1299
- case "cached":
1300
- opsBeforeReturnP = this.attachDeltaManagerOpHandler(attributes, "cached");
1301
- break;
1302
- case "all":
1303
- opsBeforeReturnP = this.attachDeltaManagerOpHandler(attributes, "all");
1304
- break;
1305
- default:
1306
- unreachableCase(loadMode.opsBeforeReturn);
1307
- }
1308
-
1309
- // ...load in the existing quorum
1310
- // Initialize the protocol handler
1311
- if (pendingLocalState === undefined) {
1312
- await this.initializeProtocolStateFromSnapshot(
1313
- attributes,
1314
- this.storageService,
1315
- snapshot);
1316
- } else {
1317
- this.initializeProtocolState(
1318
- attributes,
1319
- {
1320
- members: pendingLocalState.protocol.members,
1321
- proposals: pendingLocalState.protocol.proposals,
1322
- values: pendingLocalState.protocol.values,
1323
- }, // pending IQuorumSnapshot
1324
- );
1325
- }
1326
-
1327
- const codeDetails = this.getCodeDetailsFromQuorum();
1328
- await this.instantiateContext(
1329
- true, // existing
1330
- codeDetails,
1331
- snapshot,
1332
- pendingLocalState?.pendingRuntimeState,
1333
- );
1334
-
1335
- // We might have hit some failure that did not manifest itself in exception in this flow,
1336
- // do not start op processing in such case - static version of Container.load() will handle it correctly.
1337
- if (!this.closed) {
1338
- if (opsBeforeReturnP !== undefined) {
1339
- this._deltaManager.inbound.resume();
1340
-
1341
- await PerformanceEvent.timedExecAsync(
1342
- this.mc.logger,
1343
- { eventName: "WaitOps" },
1344
- async () => opsBeforeReturnP
1345
- );
1346
- await PerformanceEvent.timedExecAsync(
1347
- this.mc.logger,
1348
- { eventName: "WaitOpProcessing" },
1349
- async () => this._deltaManager.inbound.waitTillProcessingDone()
1350
- );
1351
-
1352
- // eslint-disable-next-line @typescript-eslint/no-floating-promises
1353
- this._deltaManager.inbound.pause();
1354
- }
1355
-
1356
- switch (loadMode.deltaConnection) {
1357
- case undefined:
1358
- case "delayed":
1359
- assert(this.inboundQueuePausedFromInit, 0x346 /* inboundQueuePausedFromInit should be true */);
1360
- this.inboundQueuePausedFromInit = false;
1361
- this._deltaManager.inbound.resume();
1362
- this._deltaManager.inboundSignal.resume();
1363
- break;
1364
- case "none":
1365
- break;
1366
- default:
1367
- unreachableCase(loadMode.deltaConnection);
1368
- }
1369
- }
1370
-
1371
- // Safety net: static version of Container.load() should have learned about it through "closed" handler.
1372
- // But if that did not happen for some reason, fail load for sure.
1373
- // Otherwise we can get into situations where container is closed and does not try to connect to ordering
1374
- // service, but caller does not know that (callers do expect container to be not closed on successful path
1375
- // and listen only on "closed" event)
1376
- if (this.closed) {
1377
- throw new Error("Container was closed while load()");
1378
- }
1379
-
1380
- // Internal context is fully loaded at this point
1381
- this.setLoaded();
1382
-
1383
- return {
1384
- sequenceNumber: attributes.sequenceNumber,
1385
- version: versionId,
1386
- dmLastProcessedSeqNumber: this._deltaManager.lastSequenceNumber,
1387
- dmLastKnownSeqNumber: this._deltaManager.lastKnownSeqNumber,
1388
- };
1389
- }
1390
-
1391
- private async createDetached(source: IFluidCodeDetails) {
1392
- const attributes: IDocumentAttributes = {
1393
- sequenceNumber: detachedContainerRefSeqNumber,
1394
- term: 1,
1395
- minimumSequenceNumber: 0,
1396
- };
1397
-
1398
- await this.attachDeltaManagerOpHandler(attributes);
1399
-
1400
- // Need to just seed the source data in the code quorum. Quorum itself is empty
1401
- const qValues = initQuorumValuesFromCodeDetails(source);
1402
- this.initializeProtocolState(
1403
- attributes,
1404
- {
1405
- members: [],
1406
- proposals: [],
1407
- values: qValues,
1408
- }, // IQuorumSnapShot
1409
- );
1410
-
1411
- // The load context - given we seeded the quorum - will be great
1412
- await this.instantiateContextDetached(
1413
- false, // existing
1414
- );
1415
-
1416
- this.setLoaded();
1417
- }
1418
-
1419
- private async rehydrateDetachedFromSnapshot(detachedContainerSnapshot: ISummaryTree) {
1420
- if (detachedContainerSnapshot.tree[".hasAttachmentBlobs"] !== undefined) {
1421
- assert(!!this.loader.services.detachedBlobStorage && this.loader.services.detachedBlobStorage.size > 0,
1422
- 0x250 /* "serialized container with attachment blobs must be rehydrated with detached blob storage" */);
1423
- delete detachedContainerSnapshot.tree[".hasAttachmentBlobs"];
1424
- }
1425
-
1426
- const snapshotTree = getSnapshotTreeFromSerializedContainer(detachedContainerSnapshot);
1427
- this.storageService.loadSnapshotForRehydratingContainer(snapshotTree);
1428
- const attributes = await this.getDocumentAttributes(this.storageService, snapshotTree);
1429
-
1430
- await this.attachDeltaManagerOpHandler(attributes);
1431
-
1432
- // Initialize the protocol handler
1433
- const baseTree = getProtocolSnapshotTree(snapshotTree);
1434
- const qValues = await readAndParse<[string, ICommittedProposal][]>(
1435
- this.storageService,
1436
- baseTree.blobs.quorumValues,
1437
- );
1438
- const codeDetails = getCodeDetailsFromQuorumValues(qValues);
1439
- this.initializeProtocolState(
1440
- attributes,
1441
- {
1442
- members: [],
1443
- proposals: [],
1444
- values: codeDetails !== undefined ? initQuorumValuesFromCodeDetails(codeDetails) : [],
1445
- }, // IQuorumSnapShot
1446
- );
1447
-
1448
- await this.instantiateContextDetached(
1449
- true, // existing
1450
- snapshotTree,
1451
- );
1452
-
1453
- this.setLoaded();
1454
- }
1455
-
1456
- private async getDocumentAttributes(
1457
- storage: IDocumentStorageService,
1458
- tree: ISnapshotTree | undefined,
1459
- ): Promise<IDocumentAttributes> {
1460
- if (tree === undefined) {
1461
- return {
1462
- minimumSequenceNumber: 0,
1463
- sequenceNumber: 0,
1464
- term: 1,
1465
- };
1466
- }
1467
-
1468
- // Backward compatibility: old docs would have ".attributes" instead of "attributes"
1469
- const attributesHash = ".protocol" in tree.trees
1470
- ? tree.trees[".protocol"].blobs.attributes
1471
- : tree.blobs[".attributes"];
1472
-
1473
- const attributes = await readAndParse<IDocumentAttributes>(storage, attributesHash);
1474
-
1475
- // Backward compatibility for older summaries with no term
1476
- if (attributes.term === undefined) {
1477
- attributes.term = 1;
1478
- }
1479
-
1480
- return attributes;
1481
- }
1482
-
1483
- private async initializeProtocolStateFromSnapshot(
1484
- attributes: IDocumentAttributes,
1485
- storage: IDocumentStorageService,
1486
- snapshot: ISnapshotTree | undefined,
1487
- ): Promise<void> {
1488
- const quorumSnapshot: IQuorumSnapshot = {
1489
- members: [],
1490
- proposals: [],
1491
- values: [],
1492
- };
1493
-
1494
- if (snapshot !== undefined) {
1495
- const baseTree = getProtocolSnapshotTree(snapshot);
1496
- [quorumSnapshot.members, quorumSnapshot.proposals, quorumSnapshot.values] = await Promise.all([
1497
- readAndParse<[string, ISequencedClient][]>(storage, baseTree.blobs.quorumMembers),
1498
- readAndParse<[number, ISequencedProposal, string[]][]>(storage, baseTree.blobs.quorumProposals),
1499
- readAndParse<[string, ICommittedProposal][]>(storage, baseTree.blobs.quorumValues),
1500
- ]);
1501
- }
1502
-
1503
- this.initializeProtocolState(attributes, quorumSnapshot);
1504
- }
1505
-
1506
- private initializeProtocolState(
1507
- attributes: IDocumentAttributes,
1508
- quorumSnapshot: IQuorumSnapshot,
1509
- ): void {
1510
- const protocolHandlerBuilder =
1511
- this.protocolHandlerBuilder ?? ((...args) => new ProtocolHandler(...args, new Audience()));
1512
- const protocol = protocolHandlerBuilder(
1513
- attributes,
1514
- quorumSnapshot,
1515
- (key, value) => this.submitMessage(MessageType.Propose, JSON.stringify({ key, value })),
1516
- );
1517
-
1518
- const protocolLogger = ChildLogger.create(this.subLogger, "ProtocolHandler");
1519
-
1520
- protocol.quorum.on("error", (error) => {
1521
- protocolLogger.sendErrorEvent(error);
1522
- });
1523
-
1524
- // Track membership changes and update connection state accordingly
1525
- this.connectionStateHandler.initProtocol(protocol);
1526
-
1527
- protocol.quorum.on("addProposal", (proposal: ISequencedProposal) => {
1528
- if (proposal.key === "code" || proposal.key === "code2") {
1529
- this.emit("codeDetailsProposed", proposal.value, proposal);
1530
- }
1531
- });
1532
-
1533
- protocol.quorum.on(
1534
- "approveProposal",
1535
- (sequenceNumber, key, value) => {
1536
- if (key === "code" || key === "code2") {
1537
- if (!isFluidCodeDetails(value)) {
1538
- this.mc.logger.sendErrorEvent({
1539
- eventName: "CodeProposalNotIFluidCodeDetails",
1540
- });
1541
- }
1542
- this.processCodeProposal().catch((error) => {
1543
- const normalizedError = normalizeError(error);
1544
- this.close(normalizedError);
1545
- this.dispose?.(normalizedError);
1546
- throw error;
1547
- });
1548
- }
1549
- });
1550
- // we need to make sure this member get set in a synchronous context,
1551
- // or other things can happen after the object that will be set is created, but not yet set
1552
- // this was breaking this._initialClients handling
1553
- //
1554
- this._protocolHandler = protocol;
1555
- }
1556
-
1557
- private captureProtocolSummary(): ISummaryTree {
1558
- const quorumSnapshot = this.protocolHandler.snapshot();
1559
- const summary: ISummaryTree = {
1560
- tree: {
1561
- attributes: {
1562
- content: JSON.stringify(this.protocolHandler.attributes),
1563
- type: SummaryType.Blob,
1564
- },
1565
- quorumMembers: {
1566
- content: JSON.stringify(quorumSnapshot.members),
1567
- type: SummaryType.Blob,
1568
- },
1569
- quorumProposals: {
1570
- content: JSON.stringify(quorumSnapshot.proposals),
1571
- type: SummaryType.Blob,
1572
- },
1573
- quorumValues: {
1574
- content: JSON.stringify(quorumSnapshot.values),
1575
- type: SummaryType.Blob,
1576
- },
1577
- },
1578
- type: SummaryType.Tree,
1579
- };
1580
-
1581
- return summary;
1582
- }
1583
-
1584
- private getCodeDetailsFromQuorum(): IFluidCodeDetails {
1585
- const quorum = this.protocolHandler.quorum;
1586
-
1587
- const pkg = getCodeProposal(quorum);
1588
-
1589
- return pkg as IFluidCodeDetails;
1590
- }
1591
-
1592
- private get client(): IClient {
1593
- const client: IClient = this.options?.client !== undefined
1594
- ? (this.options.client as IClient)
1595
- : {
1596
- details: {
1597
- capabilities: { interactive: true },
1598
- },
1599
- mode: "read", // default reconnection mode on lost connection / connection error
1600
- permission: [],
1601
- scopes: [],
1602
- user: { id: "" },
1603
- };
1604
-
1605
- if (this.clientDetailsOverride !== undefined) {
1606
- merge(client.details, this.clientDetailsOverride);
1607
- }
1608
- client.details.environment = [client.details.environment, ` loaderVersion:${pkgVersion}`].join(";");
1609
- return client;
1610
- }
1611
-
1612
- /**
1613
- * Returns true if connection is active, i.e. it's "write" connection and
1614
- * container runtime was notified about this connection (i.e. we are up-to-date and could send ops).
1615
- * This happens after client received its own joinOp and thus is in the quorum.
1616
- * If it's not true, runtime is not in position to send ops.
1617
- */
1618
- private activeConnection() {
1619
- return this.connectionState === ConnectionState.Connected &&
1620
- this.connectionMode === "write";
1621
- }
1622
-
1623
- private createDeltaManager() {
1624
- const serviceProvider = () => this.service;
1625
- const deltaManager = new DeltaManager<ConnectionManager>(
1626
- serviceProvider,
1627
- ChildLogger.create(this.subLogger, "DeltaManager"),
1628
- () => this.activeConnection(),
1629
- (props: IConnectionManagerFactoryArgs) => new ConnectionManager(
1630
- serviceProvider,
1631
- this.client,
1632
- this._canReconnect,
1633
- ChildLogger.create(this.subLogger, "ConnectionManager"),
1634
- props),
1635
- );
1636
-
1637
- // Disable inbound queues as Container is not ready to accept any ops until we are fully loaded!
1638
- // eslint-disable-next-line @typescript-eslint/no-floating-promises
1639
- deltaManager.inbound.pause();
1640
- // eslint-disable-next-line @typescript-eslint/no-floating-promises
1641
- deltaManager.inboundSignal.pause();
1642
-
1643
- deltaManager.on("connect", (details: IConnectionDetails, _opsBehind?: number) => {
1644
- assert(this.connectionMode === details.mode, 0x4b7 /* mismatch */);
1645
- this.connectionStateHandler.receivedConnectEvent(
1646
- details,
1647
- );
1648
- });
1649
-
1650
- deltaManager.on("disconnect", (reason: string) => {
1651
- this.collabWindowTracker?.stopSequenceNumberUpdate();
1652
- if (!this.closed) {
1653
- this.connectionStateHandler.receivedDisconnectEvent(reason);
1654
- }
1655
- });
1656
-
1657
- deltaManager.on("throttled", (warning: IThrottlingWarning) => {
1658
- const warn = warning as ContainerWarning;
1659
- // Some "warning" events come from outside the container and are logged
1660
- // elsewhere (e.g. summarizing container). We shouldn't log these here.
1661
- if (warn.logged !== true) {
1662
- this.mc.logger.sendTelemetryEvent({ eventName: "ContainerWarning" }, warn);
1663
- }
1664
- this.emit("warning", warn);
1665
- });
1666
-
1667
- deltaManager.on("readonly", (readonly) => {
1668
- this.setContextConnectedState(this.connectionState === ConnectionState.Connected, readonly);
1669
- this.emit("readonly", readonly);
1670
- });
1671
-
1672
- deltaManager.on("closed", (error?: ICriticalContainerError) => {
1673
- this.closeCore(error);
1674
- });
1675
-
1676
- deltaManager.on("disposed", (error?: ICriticalContainerError) => {
1677
- this.disposeCore(error);
1678
- });
1679
-
1680
- return deltaManager;
1681
- }
1682
-
1683
- private async attachDeltaManagerOpHandler(
1684
- attributes: IDocumentAttributes,
1685
- prefetchType?: "cached" | "all" | "none") {
1686
- return this._deltaManager.attachOpHandler(
1687
- attributes.minimumSequenceNumber,
1688
- attributes.sequenceNumber,
1689
- attributes.term ?? 1,
1690
- {
1691
- process: (message) => this.processRemoteMessage(message),
1692
- processSignal: (message) => {
1693
- this.processSignal(message);
1694
- },
1695
- },
1696
- prefetchType);
1697
- }
1698
-
1699
- private logConnectionStateChangeTelemetry(
1700
- value: ConnectionState,
1701
- oldState: ConnectionState,
1702
- reason?: string,
1703
- ) {
1704
- // Log actual event
1705
- const time = performance.now();
1706
- this.connectionTransitionTimes[value] = time;
1707
- const duration = time - this.connectionTransitionTimes[oldState];
1708
-
1709
- let durationFromDisconnected: number | undefined;
1710
- let connectionInitiationReason: string | undefined;
1711
- let autoReconnect: ReconnectMode | undefined;
1712
- let checkpointSequenceNumber: number | undefined;
1713
- let opsBehind: number | undefined;
1714
- if (value === ConnectionState.Disconnected) {
1715
- autoReconnect = this._deltaManager.connectionManager.reconnectMode;
1716
- } else {
1717
- if (value === ConnectionState.Connected) {
1718
- durationFromDisconnected = time - this.connectionTransitionTimes[ConnectionState.Disconnected];
1719
- durationFromDisconnected = TelemetryLogger.formatTick(durationFromDisconnected);
1720
- } else {
1721
- // This info is of most interest on establishing connection only.
1722
- checkpointSequenceNumber = this.deltaManager.lastKnownSeqNumber;
1723
- if (this.deltaManager.hasCheckpointSequenceNumber) {
1724
- opsBehind = checkpointSequenceNumber - this.deltaManager.lastSequenceNumber;
1725
- }
1726
- }
1727
- connectionInitiationReason = this.firstConnection ? "InitialConnect" : "AutoReconnect";
1728
- }
1729
-
1730
- this.mc.logger.sendPerformanceEvent({
1731
- eventName: `ConnectionStateChange_${ConnectionState[value]}`,
1732
- from: ConnectionState[oldState],
1733
- duration,
1734
- durationFromDisconnected,
1735
- reason,
1736
- connectionInitiationReason,
1737
- pendingClientId: this.connectionStateHandler.pendingClientId,
1738
- clientId: this.clientId,
1739
- autoReconnect,
1740
- opsBehind,
1741
- online: OnlineStatus[isOnline()],
1742
- lastVisible: this.lastVisible !== undefined ? performance.now() - this.lastVisible : undefined,
1743
- checkpointSequenceNumber,
1744
- quorumSize: this._protocolHandler?.quorum.getMembers().size,
1745
- ...this._deltaManager.connectionProps,
1746
- });
1747
-
1748
- if (value === ConnectionState.Connected) {
1749
- this.firstConnection = false;
1750
- }
1751
- }
1752
-
1753
- private propagateConnectionState(initialTransition: boolean, disconnectedReason?: string) {
1754
- // When container loaded, we want to propagate initial connection state.
1755
- // After that, we communicate only transitions to Connected & Disconnected states, skipping all other states.
1756
- // This can be changed in the future, for example we likely should add "CatchingUp" event on Container.
1757
- if (!initialTransition &&
1758
- this.connectionState !== ConnectionState.Connected &&
1759
- this.connectionState !== ConnectionState.Disconnected) {
1760
- return;
1761
- }
1762
- const state = this.connectionState === ConnectionState.Connected;
1763
-
1764
- const logOpsOnReconnect: boolean =
1765
- this.connectionState === ConnectionState.Connected &&
1766
- !this.firstConnection &&
1767
- this.connectionMode === "write";
1768
- if (logOpsOnReconnect) {
1769
- this.messageCountAfterDisconnection = 0;
1770
- }
1771
-
1772
- // Both protocol and context should not be undefined if we got so far.
1773
-
1774
- this.setContextConnectedState(state, this._deltaManager.connectionManager.readOnlyInfo.readonly ?? false);
1775
- this.protocolHandler.setConnectionState(state, this.clientId);
1776
- raiseConnectedEvent(this.mc.logger, this, state, this.clientId, disconnectedReason);
1777
-
1778
- if (logOpsOnReconnect) {
1779
- this.mc.logger.sendTelemetryEvent(
1780
- { eventName: "OpsSentOnReconnect", count: this.messageCountAfterDisconnection });
1781
- }
1782
- }
1783
-
1784
- // back-compat: ADO #1385: Remove in the future, summary op should come through submitSummaryMessage()
1785
- private submitContainerMessage(type: MessageType, contents: any, batch?: boolean, metadata?: any): number {
1786
- switch (type) {
1787
- case MessageType.Operation:
1788
- return this.submitMessage(
1789
- type,
1790
- JSON.stringify(contents),
1791
- batch,
1792
- metadata);
1793
- case MessageType.Summarize:
1794
- return this.submitSummaryMessage(contents as unknown as ISummaryContent);
1795
- default: {
1796
- const newError = new GenericError("invalidContainerSubmitOpType",
1797
- undefined /* error */,
1798
- { messageType: type });
1799
- this.close(newError);
1800
- this.dispose?.(newError);
1801
- return -1;
1802
- }
1803
- }
1804
- }
1805
-
1806
- /** @returns clientSequenceNumber of last message in a batch */
1807
- private submitBatch(batch: IBatchMessage[]): number {
1808
- let clientSequenceNumber = -1;
1809
- for (const message of batch) {
1810
- clientSequenceNumber = this.submitMessage(
1811
- MessageType.Operation,
1812
- message.contents,
1813
- true, // batch
1814
- message.metadata,
1815
- message.compression);
1816
- }
1817
- this._deltaManager.flush();
1818
- return clientSequenceNumber;
1819
- }
1820
-
1821
- private submitSummaryMessage(summary: ISummaryContent) {
1822
- // github #6451: this is only needed for staging so the server
1823
- // know when the protocol tree is included
1824
- // this can be removed once all clients send
1825
- // protocol tree by default
1826
- if (summary.details === undefined) {
1827
- summary.details = {};
1828
- }
1829
- summary.details.includesProtocolTree =
1830
- this.options.summarizeProtocolTree === true;
1831
- return this.submitMessage(MessageType.Summarize, JSON.stringify(summary), false /* batch */);
1832
- }
1833
-
1834
- private submitMessage(type: MessageType,
1835
- contents?: string,
1836
- batch?: boolean,
1837
- metadata?: any,
1838
- compression?: string): number {
1839
- if (this.connectionState !== ConnectionState.Connected) {
1840
- this.mc.logger.sendErrorEvent({ eventName: "SubmitMessageWithNoConnection", type });
1841
- return -1;
1842
- }
1843
-
1844
- this.messageCountAfterDisconnection += 1;
1845
- this.collabWindowTracker?.stopSequenceNumberUpdate();
1846
- return this._deltaManager.submit(type, contents, batch, metadata, compression);
1847
- }
1848
-
1849
- private processRemoteMessage(message: ISequencedDocumentMessage) {
1850
- const local = this.clientId === message.clientId;
1851
-
1852
- // Allow the protocol handler to process the message
1853
- const result = this.protocolHandler.processMessage(message, local);
1854
-
1855
- // Forward messages to the loaded runtime for processing
1856
- this.context.process(message, local);
1857
-
1858
- // Inactive (not in quorum or not writers) clients don't take part in the minimum sequence number calculation.
1859
- if (this.activeConnection()) {
1860
- if (this.collabWindowTracker === undefined) {
1861
- // Note that config from first connection will be used for this container's lifetime.
1862
- // That means that if relay service changes settings, such changes will impact only newly booted
1863
- // clients.
1864
- // All existing will continue to use settings they got earlier.
1865
- assert(
1866
- this.serviceConfiguration !== undefined,
1867
- 0x2e4 /* "there should be service config for active connection" */);
1868
- this.collabWindowTracker = new CollabWindowTracker(
1869
- (type) => {
1870
- assert(this.activeConnection(),
1871
- 0x241 /* "disconnect should result in stopSequenceNumberUpdate() call" */);
1872
- this.submitMessage(type);
1873
- },
1874
- this.serviceConfiguration.noopTimeFrequency,
1875
- this.serviceConfiguration.noopCountFrequency,
1876
- );
1877
- }
1878
- this.collabWindowTracker.scheduleSequenceNumberUpdate(message, result.immediateNoOp === true);
1879
- }
1880
-
1881
- this.emit("op", message);
1882
- }
1883
-
1884
- private submitSignal(message: any) {
1885
- this._deltaManager.submitSignal(JSON.stringify(message));
1886
- }
1887
-
1888
- private processSignal(message: ISignalMessage) {
1889
- // No clientId indicates a system signal message.
1890
- if (message.clientId === null) {
1891
- this.protocolHandler.processSignal(message);
1892
- } else {
1893
- const local = this.clientId === message.clientId;
1894
- this.context.processSignal(message, local);
1895
- }
1896
- }
1897
-
1898
- /**
1899
- * Get the most recent snapshot, or a specific version.
1900
- * @param specifiedVersion - The specific version of the snapshot to retrieve
1901
- * @returns The snapshot requested, or the latest snapshot if no version was specified, plus version ID
1902
- */
1903
- private async fetchSnapshotTree(specifiedVersion: string | undefined):
1904
- Promise<{ snapshot?: ISnapshotTree; versionId?: string; }> {
1905
- const version = await this.getVersion(specifiedVersion ?? null);
1906
-
1907
- if (version === undefined && specifiedVersion !== undefined) {
1908
- // We should have a defined version to load from if specified version requested
1909
- this.mc.logger.sendErrorEvent({ eventName: "NoVersionFoundWhenSpecified", id: specifiedVersion });
1910
- }
1911
- this._loadedFromVersion = version;
1912
- const snapshot = await this.storageService.getSnapshotTree(version) ?? undefined;
1913
-
1914
- if (snapshot === undefined && version !== undefined) {
1915
- this.mc.logger.sendErrorEvent({ eventName: "getSnapshotTreeFailed", id: version.id });
1916
- }
1917
- return { snapshot, versionId: version?.id };
1918
- }
1919
-
1920
- private async instantiateContextDetached(
1921
- existing: boolean,
1922
- snapshot?: ISnapshotTree,
1923
- ) {
1924
- const codeDetails = this.getCodeDetailsFromQuorum();
1925
- if (codeDetails === undefined) {
1926
- throw new Error("pkg should be provided in create flow!!");
1927
- }
1928
-
1929
- await this.instantiateContext(
1930
- existing,
1931
- codeDetails,
1932
- snapshot,
1933
- );
1934
- }
1935
-
1936
- private async instantiateContext(
1937
- existing: boolean,
1938
- codeDetails: IFluidCodeDetails,
1939
- snapshot?: ISnapshotTree,
1940
- pendingLocalState?: unknown,
1941
- ) {
1942
- assert(this._context?.disposed !== false, 0x0dd /* "Existing context not disposed" */);
1943
-
1944
- // The relative loader will proxy requests to '/' to the loader itself assuming no non-cache flags
1945
- // are set. Global requests will still go directly to the loader
1946
- const loader = new RelativeLoader(this, this.loader);
1947
- this._context = await ContainerContext.createOrLoad(
1948
- this,
1949
- this.scope,
1950
- this.codeLoader,
1951
- codeDetails,
1952
- snapshot,
1953
- new DeltaManagerProxy(this._deltaManager),
1954
- new QuorumProxy(this.protocolHandler.quorum),
1955
- loader,
1956
- (type, contents, batch, metadata) => this.submitContainerMessage(type, contents, batch, metadata),
1957
- (summaryOp: ISummaryContent) => this.submitSummaryMessage(summaryOp),
1958
- (batch: IBatchMessage[]) => this.submitBatch(batch),
1959
- (message) => this.submitSignal(message),
1960
- (error?: ICriticalContainerError) => this.dispose?.(error),
1961
- (error?: ICriticalContainerError) => this.close(error),
1962
- Container.version,
1963
- (dirty: boolean) => this.updateDirtyContainerState(dirty),
1964
- existing,
1965
- pendingLocalState,
1966
- );
1967
-
1968
- this.emit("contextChanged", codeDetails);
1969
- }
1970
-
1971
- private updateDirtyContainerState(dirty: boolean) {
1972
- if (this._dirtyContainer === dirty) {
1973
- return;
1974
- }
1975
- this._dirtyContainer = dirty;
1976
- this.emit(dirty ? dirtyContainerEvent : savedContainerEvent);
1977
- }
1978
-
1979
- /**
1980
- * Set the connected state of the ContainerContext
1981
- * This controls the "connected" state of the ContainerRuntime as well
1982
- * @param state - Is the container currently connected?
1983
- * @param readonly - Is the container in readonly mode?
1984
- */
1985
- private setContextConnectedState(state: boolean, readonly: boolean): void {
1986
- if (this._context?.disposed === false) {
1987
- /**
1988
- * We want to lie to the ContainerRuntime when we are in readonly mode to prevent issues with pending
1989
- * ops getting through to the DeltaManager.
1990
- * The ContainerRuntime's "connected" state simply means it is ok to send ops
1991
- * See https://dev.azure.com/fluidframework/internal/_workitems/edit/1246
1992
- */
1993
- this.context.setConnectionState(state && !readonly, this.clientId);
1994
- }
1995
- }
280
+ export class Container
281
+ extends EventEmitterWithErrorHandling<IContainerEvents>
282
+ implements IContainer
283
+ {
284
+ public static version = "^0.1.0";
285
+
286
+ /**
287
+ * Load an existing container.
288
+ */
289
+ public static async load(
290
+ loader: Loader,
291
+ loadOptions: IContainerLoadOptions,
292
+ pendingLocalState?: IPendingContainerState,
293
+ protocolHandlerBuilder?: ProtocolHandlerBuilder,
294
+ ): Promise<Container> {
295
+ const container = new Container(
296
+ loader,
297
+ {
298
+ clientDetailsOverride: loadOptions.clientDetailsOverride,
299
+ resolvedUrl: loadOptions.resolvedUrl,
300
+ canReconnect: loadOptions.canReconnect,
301
+ serializedContainerState: pendingLocalState,
302
+ baseLogger: loadOptions.baseLogger,
303
+ },
304
+ protocolHandlerBuilder,
305
+ );
306
+
307
+ return PerformanceEvent.timedExecAsync(
308
+ container.mc.logger,
309
+ { eventName: "Load" },
310
+ async (event) =>
311
+ new Promise<Container>((resolve, reject) => {
312
+ const version = loadOptions.version;
313
+
314
+ const defaultMode: IContainerLoadMode = { opsBeforeReturn: "cached" };
315
+ // if we have pendingLocalState, anything we cached is not useful and we shouldn't wait for connection
316
+ // to return container, so ignore this value and use undefined for opsBeforeReturn
317
+ const mode: IContainerLoadMode = pendingLocalState
318
+ ? { ...(loadOptions.loadMode ?? defaultMode), opsBeforeReturn: undefined }
319
+ : loadOptions.loadMode ?? defaultMode;
320
+
321
+ const onClosed = (err?: ICriticalContainerError) => {
322
+ // pre-0.58 error message: containerClosedWithoutErrorDuringLoad
323
+ reject(
324
+ err ?? new GenericError("Container closed without error during load"),
325
+ );
326
+ };
327
+ container.on("closed", onClosed);
328
+
329
+ container
330
+ .load(version, mode, pendingLocalState)
331
+ .finally(() => {
332
+ container.removeListener("closed", onClosed);
333
+ })
334
+ .then(
335
+ (props) => {
336
+ event.end({ ...props, ...loadOptions.loadMode });
337
+ resolve(container);
338
+ },
339
+ (error) => {
340
+ const err = normalizeError(error);
341
+ // Depending where error happens, we can be attempting to connect to web socket
342
+ // and continuously retrying (consider offline mode)
343
+ // Host has no container to close, so it's prudent to do it here
344
+ container.close(err);
345
+ onClosed(err);
346
+ },
347
+ );
348
+ }),
349
+ { start: true, end: true, cancel: "generic" },
350
+ );
351
+ }
352
+
353
+ /**
354
+ * Create a new container in a detached state.
355
+ */
356
+ public static async createDetached(
357
+ loader: Loader,
358
+ codeDetails: IFluidCodeDetails,
359
+ protocolHandlerBuilder?: ProtocolHandlerBuilder,
360
+ ): Promise<Container> {
361
+ const container = new Container(loader, {}, protocolHandlerBuilder);
362
+
363
+ return PerformanceEvent.timedExecAsync(
364
+ container.mc.logger,
365
+ { eventName: "CreateDetached" },
366
+ async (_event) => {
367
+ await container.createDetached(codeDetails);
368
+ return container;
369
+ },
370
+ { start: true, end: true, cancel: "generic" },
371
+ );
372
+ }
373
+
374
+ /**
375
+ * Create a new container in a detached state that is initialized with a
376
+ * snapshot from a previous detached container.
377
+ */
378
+ public static async rehydrateDetachedFromSnapshot(
379
+ loader: Loader,
380
+ snapshot: string,
381
+ protocolHandlerBuilder?: ProtocolHandlerBuilder,
382
+ ): Promise<Container> {
383
+ const container = new Container(loader, {}, protocolHandlerBuilder);
384
+
385
+ return PerformanceEvent.timedExecAsync(
386
+ container.mc.logger,
387
+ { eventName: "RehydrateDetachedFromSnapshot" },
388
+ async (_event) => {
389
+ const deserializedSummary = JSON.parse(snapshot) as ISummaryTree;
390
+ await container.rehydrateDetachedFromSnapshot(deserializedSummary);
391
+ return container;
392
+ },
393
+ { start: true, end: true, cancel: "generic" },
394
+ );
395
+ }
396
+
397
+ public subLogger: TelemetryLogger;
398
+
399
+ // Tells if container can reconnect on losing fist connection
400
+ // If false, container gets closed on loss of connection.
401
+ private readonly _canReconnect: boolean = true;
402
+
403
+ private readonly mc: MonitoringContext;
404
+
405
+ /**
406
+ * Lifecycle state of the container, used mainly to prevent re-entrancy and telemetry
407
+ *
408
+ * States are allowed to progress to further states:
409
+ * "loading" - "loaded" - "closing" - "disposing" - "closed" - "disposed"
410
+ *
411
+ * For example, moving from "closed" to "disposing" is not allowed since it is an earlier state.
412
+ *
413
+ * loading: Container has been created, but is not yet in normal/loaded state
414
+ * loaded: Container is in normal/loaded state
415
+ * closing: Container has started closing process (for re-entrancy prevention)
416
+ * disposing: Container has started disposing process (for re-entrancy prevention)
417
+ * closed: Container has closed
418
+ * disposed: Container has been disposed
419
+ */
420
+ private _lifecycleState:
421
+ | "loading"
422
+ | "loaded"
423
+ | "closing"
424
+ | "disposing"
425
+ | "closed"
426
+ | "disposed" = "loading";
427
+
428
+ private setLoaded() {
429
+ // It's conceivable the container could be closed when this is called
430
+ // Only transition states if currently loading
431
+ if (this._lifecycleState === "loading") {
432
+ // Propagate current connection state through the system.
433
+ this.propagateConnectionState(true /* initial transition */);
434
+ this._lifecycleState = "loaded";
435
+ }
436
+ }
437
+
438
+ public get closed(): boolean {
439
+ return (
440
+ this._lifecycleState === "closing" ||
441
+ this._lifecycleState === "closed" ||
442
+ this._lifecycleState === "disposing" ||
443
+ this._lifecycleState === "disposed"
444
+ );
445
+ }
446
+
447
+ private _attachState = AttachState.Detached;
448
+
449
+ private readonly storageService: ContainerStorageAdapter;
450
+ public get storage(): IDocumentStorageService {
451
+ return this.storageService;
452
+ }
453
+
454
+ private readonly clientDetailsOverride: IClientDetails | undefined;
455
+ private readonly _deltaManager: DeltaManager<ConnectionManager>;
456
+ private service: IDocumentService | undefined;
457
+
458
+ private _context: ContainerContext | undefined;
459
+ private get context() {
460
+ if (this._context === undefined) {
461
+ throw new GenericError("Attempted to access context before it was defined");
462
+ }
463
+ return this._context;
464
+ }
465
+ private _protocolHandler: IProtocolHandler | undefined;
466
+ private get protocolHandler() {
467
+ if (this._protocolHandler === undefined) {
468
+ throw new Error("Attempted to access protocolHandler before it was defined");
469
+ }
470
+ return this._protocolHandler;
471
+ }
472
+
473
+ /** During initialization we pause the inbound queues. We track this state to ensure we only call resume once */
474
+ private inboundQueuePausedFromInit = true;
475
+ private firstConnection = true;
476
+ private readonly connectionTransitionTimes: number[] = [];
477
+ private messageCountAfterDisconnection: number = 0;
478
+ private _loadedFromVersion: IVersion | undefined;
479
+ private _resolvedUrl: IFluidResolvedUrl | undefined;
480
+ private attachStarted = false;
481
+ private _dirtyContainer = false;
482
+
483
+ private lastVisible: number | undefined;
484
+ private readonly visibilityEventHandler: (() => void) | undefined;
485
+ private readonly connectionStateHandler: IConnectionStateHandler;
486
+
487
+ private setAutoReconnectTime = performance.now();
488
+
489
+ private collabWindowTracker: CollabWindowTracker | undefined;
490
+
491
+ private get connectionMode() {
492
+ return this._deltaManager.connectionManager.connectionMode;
493
+ }
494
+
495
+ public get IFluidRouter(): IFluidRouter {
496
+ return this;
497
+ }
498
+
499
+ public get resolvedUrl(): IResolvedUrl | undefined {
500
+ return this._resolvedUrl;
501
+ }
502
+
503
+ public get loadedFromVersion(): IVersion | undefined {
504
+ return this._loadedFromVersion;
505
+ }
506
+
507
+ public get readOnlyInfo(): ReadOnlyInfo {
508
+ return this._deltaManager.readOnlyInfo;
509
+ }
510
+
511
+ public get closeSignal(): AbortSignal {
512
+ return this._deltaManager.closeAbortController.signal;
513
+ }
514
+
515
+ /**
516
+ * Tracks host requiring read-only mode.
517
+ */
518
+ public forceReadonly(readonly: boolean) {
519
+ this._deltaManager.connectionManager.forceReadonly(readonly);
520
+ }
521
+
522
+ public get deltaManager(): IDeltaManager<ISequencedDocumentMessage, IDocumentMessage> {
523
+ return this._deltaManager;
524
+ }
525
+
526
+ public get connectionState(): ConnectionState {
527
+ return this.connectionStateHandler.connectionState;
528
+ }
529
+
530
+ public get connected(): boolean {
531
+ return this.connectionStateHandler.connectionState === ConnectionState.Connected;
532
+ }
533
+
534
+ /**
535
+ * Service configuration details. If running in offline mode will be undefined otherwise will contain service
536
+ * configuration details returned as part of the initial connection.
537
+ */
538
+ public get serviceConfiguration(): IClientConfiguration | undefined {
539
+ return this._deltaManager.serviceConfiguration;
540
+ }
541
+
542
+ private _clientId: string | undefined;
543
+
544
+ /**
545
+ * The server provided id of the client.
546
+ * Set once this.connected is true, otherwise undefined
547
+ */
548
+ public get clientId(): string | undefined {
549
+ return this._clientId;
550
+ }
551
+
552
+ /**
553
+ * The server provided claims of the client.
554
+ * Set once this.connected is true, otherwise undefined
555
+ */
556
+ public get scopes(): string[] | undefined {
557
+ return this._deltaManager.connectionManager.scopes;
558
+ }
559
+
560
+ public get clientDetails(): IClientDetails {
561
+ return this._deltaManager.clientDetails;
562
+ }
563
+
564
+ /**
565
+ * Get the code details that are currently specified for the container.
566
+ * @returns The current code details if any are specified, undefined if none are specified.
567
+ */
568
+ public getSpecifiedCodeDetails(): IFluidCodeDetails | undefined {
569
+ return this.getCodeDetailsFromQuorum();
570
+ }
571
+
572
+ /**
573
+ * Get the code details that were used to load the container.
574
+ * @returns The code details that were used to load the container if it is loaded, undefined if it is not yet
575
+ * loaded.
576
+ */
577
+ public getLoadedCodeDetails(): IFluidCodeDetails | undefined {
578
+ return this._context?.codeDetails;
579
+ }
580
+
581
+ /**
582
+ * Retrieves the audience associated with the document
583
+ */
584
+ public get audience(): IAudience {
585
+ return this.protocolHandler.audience;
586
+ }
587
+
588
+ /**
589
+ * Returns true if container is dirty.
590
+ * Which means data loss if container is closed at that same moment
591
+ * Most likely that happens when there is no network connection to Relay Service
592
+ */
593
+ public get isDirty() {
594
+ return this._dirtyContainer;
595
+ }
596
+
597
+ private get serviceFactory() {
598
+ return this.loader.services.documentServiceFactory;
599
+ }
600
+ private get urlResolver() {
601
+ return this.loader.services.urlResolver;
602
+ }
603
+ public readonly options: ILoaderOptions;
604
+ private get scope() {
605
+ return this.loader.services.scope;
606
+ }
607
+ private get codeLoader() {
608
+ return this.loader.services.codeLoader;
609
+ }
610
+
611
+ constructor(
612
+ private readonly loader: Loader,
613
+ config: IContainerConfig,
614
+ private readonly protocolHandlerBuilder?: ProtocolHandlerBuilder,
615
+ ) {
616
+ super((name, error) => {
617
+ this.mc.logger.sendErrorEvent(
618
+ {
619
+ eventName: "ContainerEventHandlerException",
620
+ name: typeof name === "string" ? name : undefined,
621
+ },
622
+ error,
623
+ );
624
+ });
625
+
626
+ this.clientDetailsOverride = config.clientDetailsOverride;
627
+ this._resolvedUrl = config.resolvedUrl;
628
+ if (config.canReconnect !== undefined) {
629
+ this._canReconnect = config.canReconnect;
630
+ }
631
+
632
+ // Create logger for data stores to use
633
+ const type = this.client.details.type;
634
+ const interactive = this.client.details.capabilities.interactive;
635
+ const clientType = `${interactive ? "interactive" : "noninteractive"}${
636
+ type !== undefined && type !== "" ? `/${type}` : ""
637
+ }`;
638
+ // Need to use the property getter for docId because for detached flow we don't have the docId initially.
639
+ // We assign the id later so property getter is used.
640
+ this.subLogger = ChildLogger.create(
641
+ // If a baseLogger was provided, use it; otherwise use the loader's logger.
642
+ config.baseLogger ?? loader.services.subLogger,
643
+ undefined,
644
+ {
645
+ all: {
646
+ clientType, // Differentiating summarizer container from main container
647
+ containerId: uuid(),
648
+ docId: () => this._resolvedUrl?.id ?? undefined,
649
+ containerAttachState: () => this._attachState,
650
+ containerLifecycleState: () => this._lifecycleState,
651
+ containerConnectionState: () => ConnectionState[this.connectionState],
652
+ serializedContainer: config.serializedContainerState !== undefined,
653
+ },
654
+ // we need to be judicious with our logging here to avoid generating too much data
655
+ // all data logged here should be broadly applicable, and not specific to a
656
+ // specific error or class of errors
657
+ error: {
658
+ // load information to associate errors with the specific load point
659
+ dmInitialSeqNumber: () => this._deltaManager?.initialSequenceNumber,
660
+ dmLastProcessedSeqNumber: () => this._deltaManager?.lastSequenceNumber,
661
+ dmLastKnownSeqNumber: () => this._deltaManager?.lastKnownSeqNumber,
662
+ containerLoadedFromVersionId: () => this.loadedFromVersion?.id,
663
+ containerLoadedFromVersionDate: () => this.loadedFromVersion?.date,
664
+ // message information to associate errors with the specific execution state
665
+ // dmLastMsqSeqNumber: if present, same as dmLastProcessedSeqNumber
666
+ dmLastMsqSeqNumber: () => this.deltaManager?.lastMessage?.sequenceNumber,
667
+ dmLastMsqSeqTimestamp: () => this.deltaManager?.lastMessage?.timestamp,
668
+ dmLastMsqSeqClientId: () => this.deltaManager?.lastMessage?.clientId,
669
+ dmLastMsgClientSeq: () => this.deltaManager?.lastMessage?.clientSequenceNumber,
670
+ connectionStateDuration: () =>
671
+ performance.now() - this.connectionTransitionTimes[this.connectionState],
672
+ },
673
+ },
674
+ );
675
+
676
+ // Prefix all events in this file with container-loader
677
+ this.mc = loggerToMonitoringContext(ChildLogger.create(this.subLogger, "Container"));
678
+
679
+ const summarizeProtocolTree =
680
+ this.mc.config.getBoolean("Fluid.Container.summarizeProtocolTree2") ??
681
+ this.loader.services.options.summarizeProtocolTree;
682
+
683
+ this.options = {
684
+ ...this.loader.services.options,
685
+ summarizeProtocolTree,
686
+ };
687
+
688
+ this._deltaManager = this.createDeltaManager();
689
+
690
+ this._clientId = config.serializedContainerState?.clientId;
691
+ this.connectionStateHandler = createConnectionStateHandler(
692
+ {
693
+ logger: this.mc.logger,
694
+ connectionStateChanged: (value, oldState, reason) => {
695
+ if (value === ConnectionState.Connected) {
696
+ this._clientId = this.connectionStateHandler.pendingClientId;
697
+ }
698
+ this.logConnectionStateChangeTelemetry(value, oldState, reason);
699
+ if (this._lifecycleState === "loaded") {
700
+ this.propagateConnectionState(
701
+ false /* initial transition */,
702
+ value === ConnectionState.Disconnected
703
+ ? reason
704
+ : undefined /* disconnectedReason */,
705
+ );
706
+ }
707
+ },
708
+ shouldClientJoinWrite: () => this._deltaManager.connectionManager.shouldJoinWrite(),
709
+ maxClientLeaveWaitTime: this.loader.services.options.maxClientLeaveWaitTime,
710
+ logConnectionIssue: (
711
+ eventName: string,
712
+ category: TelemetryEventCategory,
713
+ details?: ITelemetryProperties,
714
+ ) => {
715
+ const mode = this.connectionMode;
716
+ // We get here when socket does not receive any ops on "write" connection, including
717
+ // its own join op.
718
+ // Report issues only if we already loaded container - op processing is paused while container is loading,
719
+ // so we always time-out processing of join op in cases where fetching snapshot takes a minute.
720
+ // It's not a problem with op processing itself - such issues should be tracked as part of boot perf monitoring instead.
721
+ this._deltaManager.logConnectionIssue({
722
+ eventName,
723
+ mode,
724
+ category: this._lifecycleState === "loading" ? "generic" : category,
725
+ duration:
726
+ performance.now() -
727
+ this.connectionTransitionTimes[ConnectionState.CatchingUp],
728
+ ...(details === undefined ? {} : { details: JSON.stringify(details) }),
729
+ });
730
+
731
+ // If this is "write" connection, it took too long to receive join op. But in most cases that's due
732
+ // to very slow op fetches and we will eventually get there.
733
+ // For "read" connections, we get here due to self join signal not arriving on time. We will need to
734
+ // better understand when and why it may happen.
735
+ // For now, attempt to recover by reconnecting. In future, maybe we can query relay service for
736
+ // current state of audience.
737
+ // Other possible recovery path - move to connected state (i.e. ConnectionStateHandler.joinOpTimer
738
+ // to call this.applyForConnectedState("addMemberEvent") for "read" connections)
739
+ if (mode === "read") {
740
+ this.disconnect();
741
+ this.connect();
742
+ }
743
+ },
744
+ },
745
+ this.deltaManager,
746
+ this._clientId,
747
+ );
748
+
749
+ this.on(savedContainerEvent, () => {
750
+ this.connectionStateHandler.containerSaved();
751
+ });
752
+
753
+ this.storageService = new ContainerStorageAdapter(
754
+ this.loader.services.detachedBlobStorage,
755
+ this.mc.logger,
756
+ this.options.summarizeProtocolTree === true
757
+ ? () => this.captureProtocolSummary()
758
+ : undefined,
759
+ );
760
+
761
+ const isDomAvailable =
762
+ typeof document === "object" &&
763
+ document !== null &&
764
+ typeof document.addEventListener === "function" &&
765
+ document.addEventListener !== null;
766
+ // keep track of last time page was visible for telemetry
767
+ if (isDomAvailable) {
768
+ this.lastVisible = document.hidden ? performance.now() : undefined;
769
+ this.visibilityEventHandler = () => {
770
+ if (document.hidden) {
771
+ this.lastVisible = performance.now();
772
+ } else {
773
+ // settimeout so this will hopefully fire after disconnect event if being hidden caused it
774
+ setTimeout(() => {
775
+ this.lastVisible = undefined;
776
+ }, 0);
777
+ }
778
+ };
779
+ document.addEventListener("visibilitychange", this.visibilityEventHandler);
780
+ }
781
+
782
+ // We observed that most users of platform do not check Container.connected event on load, causing bugs.
783
+ // As such, we are raising events when new listener pops up.
784
+ // Note that we can raise both "disconnected" & "connect" events at the same time,
785
+ // if we are in connecting stage.
786
+ this.on("newListener", (event: string, listener: (...args: any[]) => void) => {
787
+ // Fire events on the end of JS turn, giving a chance for caller to be in consistent state.
788
+ Promise.resolve()
789
+ .then(() => {
790
+ switch (event) {
791
+ case dirtyContainerEvent:
792
+ if (this._dirtyContainer) {
793
+ listener();
794
+ }
795
+ break;
796
+ case savedContainerEvent:
797
+ if (!this._dirtyContainer) {
798
+ listener();
799
+ }
800
+ break;
801
+ case connectedEventName:
802
+ if (this.connected) {
803
+ listener(this.clientId);
804
+ }
805
+ break;
806
+ case disconnectedEventName:
807
+ if (!this.connected) {
808
+ listener();
809
+ }
810
+ break;
811
+ default:
812
+ }
813
+ })
814
+ .catch((error) => {
815
+ this.mc.logger.sendErrorEvent({ eventName: "RaiseConnectedEventError" }, error);
816
+ });
817
+ });
818
+ }
819
+
820
+ /**
821
+ * Retrieves the quorum associated with the document
822
+ */
823
+ public getQuorum(): IQuorumClients {
824
+ return this.protocolHandler.quorum;
825
+ }
826
+
827
+ public dispose?(error?: ICriticalContainerError) {
828
+ this._deltaManager.close(error, true /* doDispose */);
829
+ this.verifyClosed();
830
+ }
831
+
832
+ public close(error?: ICriticalContainerError) {
833
+ // 1. Ensure that close sequence is exactly the same no matter if it's initiated by host or by DeltaManager
834
+ // 2. We need to ensure that we deliver disconnect event to runtime properly. See connectionStateChanged
835
+ // handler. We only deliver events if container fully loaded. Transitioning from "loading" ->
836
+ // "closing" will lose that info (can also solve by tracking extra state).
837
+ this._deltaManager.close(error);
838
+ this.verifyClosed();
839
+ }
840
+
841
+ private verifyClosed(): void {
842
+ assert(
843
+ this.connectionState === ConnectionState.Disconnected,
844
+ 0x0cf /* "disconnect event was not raised!" */,
845
+ );
846
+
847
+ assert(
848
+ this._lifecycleState === "closed" || this._lifecycleState === "disposed",
849
+ 0x314 /* Container properly closed */,
850
+ );
851
+ }
852
+
853
+ private closeCore(error?: ICriticalContainerError) {
854
+ assert(!this.closed, 0x315 /* re-entrancy */);
855
+
856
+ try {
857
+ // Ensure that we raise all key events even if one of these throws
858
+ try {
859
+ // Raise event first, to ensure we capture _lifecycleState before transition.
860
+ // This gives us a chance to know what errors happened on open vs. on fully loaded container.
861
+ this.mc.logger.sendTelemetryEvent(
862
+ {
863
+ eventName: "ContainerClose",
864
+ category: error === undefined ? "generic" : "error",
865
+ },
866
+ error,
867
+ );
868
+
869
+ this._lifecycleState = "closing";
870
+
871
+ this._protocolHandler?.close();
872
+
873
+ this.connectionStateHandler.dispose();
874
+
875
+ this._context?.dispose(error !== undefined ? new Error(error.message) : undefined);
876
+
877
+ this.storageService.dispose();
878
+
879
+ // Notify storage about critical errors. They may be due to disconnect between client & server knowledge
880
+ // about file, like file being overwritten in storage, but client having stale local cache.
881
+ // Driver need to ensure all caches are cleared on critical errors
882
+ this.service?.dispose(error);
883
+ } catch (exception) {
884
+ this.mc.logger.sendErrorEvent({ eventName: "ContainerCloseException" }, exception);
885
+ }
886
+
887
+ this.emit("closed", error);
888
+
889
+ if (this.visibilityEventHandler !== undefined) {
890
+ document.removeEventListener("visibilitychange", this.visibilityEventHandler);
891
+ }
892
+ } finally {
893
+ this._lifecycleState = "closed";
894
+ }
895
+ }
896
+
897
+ private _disposed = false;
898
+ private disposeCore(error?: ICriticalContainerError) {
899
+ assert(!this._disposed, 0x54c /* Container already disposed */);
900
+ this._disposed = true;
901
+
902
+ try {
903
+ // Ensure that we raise all key events even if one of these throws
904
+ try {
905
+ // Raise event first, to ensure we capture _lifecycleState before transition.
906
+ // This gives us a chance to know what errors happened on open vs. on fully loaded container.
907
+ this.mc.logger.sendTelemetryEvent(
908
+ {
909
+ eventName: "ContainerDispose",
910
+ category: "generic",
911
+ },
912
+ error,
913
+ );
914
+
915
+ // ! Progressing from "closed" to "disposing" is not allowed
916
+ if (this._lifecycleState !== "closed") {
917
+ this._lifecycleState = "disposing";
918
+ }
919
+
920
+ this._protocolHandler?.close();
921
+
922
+ this.connectionStateHandler.dispose();
923
+
924
+ this._context?.dispose(error !== undefined ? new Error(error.message) : undefined);
925
+
926
+ this.storageService.dispose();
927
+
928
+ // Notify storage about critical errors. They may be due to disconnect between client & server knowledge
929
+ // about file, like file being overwritten in storage, but client having stale local cache.
930
+ // Driver need to ensure all caches are cleared on critical errors
931
+ this.service?.dispose(error);
932
+ } catch (exception) {
933
+ this.mc.logger.sendErrorEvent(
934
+ { eventName: "ContainerDisposeException" },
935
+ exception,
936
+ );
937
+ }
938
+
939
+ this.emit("disposed", error);
940
+
941
+ this.removeAllListeners();
942
+ if (this.visibilityEventHandler !== undefined) {
943
+ document.removeEventListener("visibilitychange", this.visibilityEventHandler);
944
+ }
945
+ } finally {
946
+ this._lifecycleState = "disposed";
947
+ }
948
+ }
949
+
950
+ public closeAndGetPendingLocalState(): string {
951
+ // runtime matches pending ops to successful ones by clientId and client seq num, so we need to close the
952
+ // container at the same time we get pending state, otherwise this container could reconnect and resubmit with
953
+ // a new clientId and a future container using stale pending state without the new clientId would resubmit them
954
+ assert(
955
+ this.attachState === AttachState.Attached,
956
+ 0x0d1 /* "Container should be attached before close" */,
957
+ );
958
+ assert(
959
+ this.resolvedUrl !== undefined && this.resolvedUrl.type === "fluid",
960
+ 0x0d2 /* "resolved url should be valid Fluid url" */,
961
+ );
962
+ assert(!!this._protocolHandler, 0x2e3 /* "Must have a valid protocol handler instance" */);
963
+ assert(
964
+ this._protocolHandler.attributes.term !== undefined,
965
+ 0x37e /* Must have a valid protocol handler instance */,
966
+ );
967
+ const pendingState: IPendingContainerState = {
968
+ pendingRuntimeState: this.context.getPendingLocalState(),
969
+ url: this.resolvedUrl.url,
970
+ protocol: this.protocolHandler.getProtocolState(),
971
+ term: this._protocolHandler.attributes.term,
972
+ clientId: this.clientId,
973
+ };
974
+
975
+ this.mc.logger.sendTelemetryEvent({ eventName: "CloseAndGetPendingLocalState" });
976
+
977
+ // Only close here as method name suggests
978
+ this.close();
979
+
980
+ return JSON.stringify(pendingState);
981
+ }
982
+
983
+ public get attachState(): AttachState {
984
+ return this._attachState;
985
+ }
986
+
987
+ public serialize(): string {
988
+ assert(
989
+ this.attachState === AttachState.Detached,
990
+ 0x0d3 /* "Should only be called in detached container" */,
991
+ );
992
+
993
+ const appSummary: ISummaryTree = this.context.createSummary();
994
+ const protocolSummary = this.captureProtocolSummary();
995
+ const combinedSummary = combineAppAndProtocolSummary(appSummary, protocolSummary);
996
+
997
+ if (
998
+ this.loader.services.detachedBlobStorage &&
999
+ this.loader.services.detachedBlobStorage.size > 0
1000
+ ) {
1001
+ combinedSummary.tree[".hasAttachmentBlobs"] = {
1002
+ type: SummaryType.Blob,
1003
+ content: "true",
1004
+ };
1005
+ }
1006
+ return JSON.stringify(combinedSummary);
1007
+ }
1008
+
1009
+ public async attach(request: IRequest): Promise<void> {
1010
+ await PerformanceEvent.timedExecAsync(
1011
+ this.mc.logger,
1012
+ { eventName: "Attach" },
1013
+ async () => {
1014
+ if (this._lifecycleState !== "loaded") {
1015
+ // pre-0.58 error message: containerNotValidForAttach
1016
+ throw new UsageError(
1017
+ `The Container is not in a valid state for attach [${this._lifecycleState}]`,
1018
+ );
1019
+ }
1020
+
1021
+ // If container is already attached or attach is in progress, throw an error.
1022
+ assert(
1023
+ this._attachState === AttachState.Detached && !this.attachStarted,
1024
+ 0x205 /* "attach() called more than once" */,
1025
+ );
1026
+ this.attachStarted = true;
1027
+
1028
+ // If attachment blobs were uploaded in detached state we will go through a different attach flow
1029
+ const hasAttachmentBlobs =
1030
+ this.loader.services.detachedBlobStorage !== undefined &&
1031
+ this.loader.services.detachedBlobStorage.size > 0;
1032
+
1033
+ try {
1034
+ assert(
1035
+ this.deltaManager.inbound.length === 0,
1036
+ 0x0d6 /* "Inbound queue should be empty when attaching" */,
1037
+ );
1038
+
1039
+ let summary: ISummaryTree;
1040
+ if (!hasAttachmentBlobs) {
1041
+ // Get the document state post attach - possibly can just call attach but we need to change the
1042
+ // semantics around what the attach means as far as async code goes.
1043
+ const appSummary: ISummaryTree = this.context.createSummary();
1044
+ const protocolSummary = this.captureProtocolSummary();
1045
+ summary = combineAppAndProtocolSummary(appSummary, protocolSummary);
1046
+
1047
+ // Set the state as attaching as we are starting the process of attaching container.
1048
+ // This should be fired after taking the summary because it is the place where we are
1049
+ // starting to attach the container to storage.
1050
+ // Also, this should only be fired in detached container.
1051
+ this._attachState = AttachState.Attaching;
1052
+ this.context.notifyAttaching(
1053
+ getSnapshotTreeFromSerializedContainer(summary),
1054
+ );
1055
+ }
1056
+
1057
+ // Actually go and create the resolved document
1058
+ const createNewResolvedUrl = await this.urlResolver.resolve(request);
1059
+ ensureFluidResolvedUrl(createNewResolvedUrl);
1060
+ if (this.service === undefined) {
1061
+ assert(
1062
+ this.client.details.type !== summarizerClientType,
1063
+ 0x2c4 /* "client should not be summarizer before container is created" */,
1064
+ );
1065
+ this.service = await runWithRetry(
1066
+ async () =>
1067
+ this.serviceFactory.createContainer(
1068
+ summary,
1069
+ createNewResolvedUrl,
1070
+ this.subLogger,
1071
+ false, // clientIsSummarizer
1072
+ ),
1073
+ "containerAttach",
1074
+ this.mc.logger,
1075
+ {
1076
+ cancel: this.closeSignal,
1077
+ }, // progress
1078
+ );
1079
+ }
1080
+ const resolvedUrl = this.service.resolvedUrl;
1081
+ ensureFluidResolvedUrl(resolvedUrl);
1082
+ this._resolvedUrl = resolvedUrl;
1083
+ await this.storageService.connectToService(this.service);
1084
+
1085
+ if (hasAttachmentBlobs) {
1086
+ // upload blobs to storage
1087
+ assert(
1088
+ !!this.loader.services.detachedBlobStorage,
1089
+ 0x24e /* "assertion for type narrowing" */,
1090
+ );
1091
+
1092
+ // build a table mapping IDs assigned locally to IDs assigned by storage and pass it to runtime to
1093
+ // support blob handles that only know about the local IDs
1094
+ const redirectTable = new Map<string, string>();
1095
+ // if new blobs are added while uploading, upload them too
1096
+ while (redirectTable.size < this.loader.services.detachedBlobStorage.size) {
1097
+ const newIds = this.loader.services.detachedBlobStorage
1098
+ .getBlobIds()
1099
+ .filter((id) => !redirectTable.has(id));
1100
+ for (const id of newIds) {
1101
+ const blob =
1102
+ await this.loader.services.detachedBlobStorage.readBlob(id);
1103
+ const response = await this.storageService.createBlob(blob);
1104
+ redirectTable.set(id, response.id);
1105
+ }
1106
+ }
1107
+
1108
+ // take summary and upload
1109
+ const appSummary: ISummaryTree = this.context.createSummary(redirectTable);
1110
+ const protocolSummary = this.captureProtocolSummary();
1111
+ summary = combineAppAndProtocolSummary(appSummary, protocolSummary);
1112
+
1113
+ this._attachState = AttachState.Attaching;
1114
+ this.context.notifyAttaching(
1115
+ getSnapshotTreeFromSerializedContainer(summary),
1116
+ );
1117
+
1118
+ await this.storageService.uploadSummaryWithContext(summary, {
1119
+ referenceSequenceNumber: 0,
1120
+ ackHandle: undefined,
1121
+ proposalHandle: undefined,
1122
+ });
1123
+ }
1124
+
1125
+ this._attachState = AttachState.Attached;
1126
+ this.emit("attached");
1127
+
1128
+ if (!this.closed) {
1129
+ this.resumeInternal({
1130
+ fetchOpsFromStorage: false,
1131
+ reason: "createDetached",
1132
+ });
1133
+ }
1134
+ } catch (error) {
1135
+ // add resolved URL on error object so that host has the ability to find this document and delete it
1136
+ const newError = normalizeError(error);
1137
+ const resolvedUrl = this.resolvedUrl;
1138
+ if (isFluidResolvedUrl(resolvedUrl)) {
1139
+ newError.addTelemetryProperties({ resolvedUrl: resolvedUrl.url });
1140
+ }
1141
+ this.close(newError);
1142
+ this.dispose?.(newError);
1143
+ throw newError;
1144
+ }
1145
+ },
1146
+ { start: true, end: true, cancel: "generic" },
1147
+ );
1148
+ }
1149
+
1150
+ public async request(path: IRequest): Promise<IResponse> {
1151
+ return PerformanceEvent.timedExecAsync(
1152
+ this.mc.logger,
1153
+ { eventName: "Request" },
1154
+ async () => this.context.request(path),
1155
+ { end: true, cancel: "error" },
1156
+ );
1157
+ }
1158
+
1159
+ private setAutoReconnectInternal(mode: ReconnectMode) {
1160
+ const currentMode = this._deltaManager.connectionManager.reconnectMode;
1161
+
1162
+ if (currentMode === mode) {
1163
+ return;
1164
+ }
1165
+
1166
+ const now = performance.now();
1167
+ const duration = now - this.setAutoReconnectTime;
1168
+ this.setAutoReconnectTime = now;
1169
+
1170
+ this.mc.logger.sendTelemetryEvent({
1171
+ eventName:
1172
+ mode === ReconnectMode.Enabled ? "AutoReconnectEnabled" : "AutoReconnectDisabled",
1173
+ connectionMode: this.connectionMode,
1174
+ connectionState: ConnectionState[this.connectionState],
1175
+ duration,
1176
+ });
1177
+
1178
+ this._deltaManager.connectionManager.setAutoReconnect(mode);
1179
+ }
1180
+
1181
+ public connect() {
1182
+ if (this.closed) {
1183
+ throw new UsageError(`The Container is closed and cannot be connected`);
1184
+ } else if (this._attachState !== AttachState.Attached) {
1185
+ throw new UsageError(`The Container is not attached and cannot be connected`);
1186
+ } else if (!this.connected) {
1187
+ // Note: no need to fetch ops as we do it preemptively as part of DeltaManager.attachOpHandler().
1188
+ // If there is gap, we will learn about it once connected, but the gap should be small (if any),
1189
+ // assuming that connect() is called quickly after initial container boot.
1190
+ this.connectInternal({ reason: "DocumentConnect", fetchOpsFromStorage: false });
1191
+ }
1192
+ }
1193
+
1194
+ private connectInternal(args: IConnectionArgs) {
1195
+ assert(!this.closed, 0x2c5 /* "Attempting to connect() a closed Container" */);
1196
+ assert(
1197
+ this._attachState === AttachState.Attached,
1198
+ 0x2c6 /* "Attempting to connect() a container that is not attached" */,
1199
+ );
1200
+
1201
+ // Resume processing ops and connect to delta stream
1202
+ this.resumeInternal(args);
1203
+
1204
+ // Set Auto Reconnect Mode
1205
+ const mode = ReconnectMode.Enabled;
1206
+ this.setAutoReconnectInternal(mode);
1207
+ }
1208
+
1209
+ public disconnect() {
1210
+ if (this.closed) {
1211
+ throw new UsageError(`The Container is closed and cannot be disconnected`);
1212
+ } else {
1213
+ this.disconnectInternal();
1214
+ }
1215
+ }
1216
+
1217
+ private disconnectInternal() {
1218
+ assert(!this.closed, 0x2c7 /* "Attempting to disconnect() a closed Container" */);
1219
+
1220
+ // Set Auto Reconnect Mode
1221
+ const mode = ReconnectMode.Disabled;
1222
+ this.setAutoReconnectInternal(mode);
1223
+ }
1224
+
1225
+ private resumeInternal(args: IConnectionArgs) {
1226
+ assert(!this.closed, 0x0d9 /* "Attempting to connect() a closed DeltaManager" */);
1227
+
1228
+ // Resume processing ops
1229
+ if (this.inboundQueuePausedFromInit) {
1230
+ this.inboundQueuePausedFromInit = false;
1231
+ this._deltaManager.inbound.resume();
1232
+ this._deltaManager.inboundSignal.resume();
1233
+ }
1234
+
1235
+ // Ensure connection to web socket
1236
+ this.connectToDeltaStream(args);
1237
+ }
1238
+
1239
+ public async getAbsoluteUrl(relativeUrl: string): Promise<string | undefined> {
1240
+ if (this.resolvedUrl === undefined) {
1241
+ return undefined;
1242
+ }
1243
+
1244
+ return this.urlResolver.getAbsoluteUrl(
1245
+ this.resolvedUrl,
1246
+ relativeUrl,
1247
+ getPackageName(this._context?.codeDetails),
1248
+ );
1249
+ }
1250
+
1251
+ public async proposeCodeDetails(codeDetails: IFluidCodeDetails) {
1252
+ if (!isFluidCodeDetails(codeDetails)) {
1253
+ throw new Error("Provided codeDetails are not IFluidCodeDetails");
1254
+ }
1255
+
1256
+ if (this.codeLoader.IFluidCodeDetailsComparer) {
1257
+ const comparison = await this.codeLoader.IFluidCodeDetailsComparer.compare(
1258
+ codeDetails,
1259
+ this.getCodeDetailsFromQuorum(),
1260
+ );
1261
+ if (comparison !== undefined && comparison <= 0) {
1262
+ throw new Error("Proposed code details should be greater than the current");
1263
+ }
1264
+ }
1265
+
1266
+ return this.protocolHandler.quorum
1267
+ .propose("code", codeDetails)
1268
+ .then(() => true)
1269
+ .catch(() => false);
1270
+ }
1271
+
1272
+ private async processCodeProposal(): Promise<void> {
1273
+ const codeDetails = this.getCodeDetailsFromQuorum();
1274
+
1275
+ await Promise.all([
1276
+ this.deltaManager.inbound.pause(),
1277
+ this.deltaManager.inboundSignal.pause(),
1278
+ ]);
1279
+
1280
+ if ((await this.context.satisfies(codeDetails)) === true) {
1281
+ this.deltaManager.inbound.resume();
1282
+ this.deltaManager.inboundSignal.resume();
1283
+ return;
1284
+ }
1285
+
1286
+ // pre-0.58 error message: existingContextDoesNotSatisfyIncomingProposal
1287
+ const error = new GenericError("Existing context does not satisfy incoming proposal");
1288
+ this.close(error);
1289
+ this.dispose?.(error);
1290
+ }
1291
+
1292
+ private async getVersion(version: string | null): Promise<IVersion | undefined> {
1293
+ const versions = await this.storageService.getVersions(version, 1);
1294
+ return versions[0];
1295
+ }
1296
+
1297
+ private recordConnectStartTime() {
1298
+ if (this.connectionTransitionTimes[ConnectionState.Disconnected] === undefined) {
1299
+ this.connectionTransitionTimes[ConnectionState.Disconnected] = performance.now();
1300
+ }
1301
+ }
1302
+
1303
+ private connectToDeltaStream(args: IConnectionArgs) {
1304
+ this.recordConnectStartTime();
1305
+
1306
+ // All agents need "write" access, including summarizer.
1307
+ if (!this._canReconnect || !this.client.details.capabilities.interactive) {
1308
+ args.mode = "write";
1309
+ }
1310
+
1311
+ this._deltaManager.connect(args);
1312
+ }
1313
+
1314
+ /**
1315
+ * Load container.
1316
+ *
1317
+ * @param specifiedVersion - Version SHA to load snapshot. If not specified, will fetch the latest snapshot.
1318
+ */
1319
+ private async load(
1320
+ specifiedVersion: string | undefined,
1321
+ loadMode: IContainerLoadMode,
1322
+ pendingLocalState?: IPendingContainerState,
1323
+ ) {
1324
+ if (this._resolvedUrl === undefined) {
1325
+ throw new Error("Attempting to load without a resolved url");
1326
+ }
1327
+ this.service = await this.serviceFactory.createDocumentService(
1328
+ this._resolvedUrl,
1329
+ this.subLogger,
1330
+ this.client.details.type === summarizerClientType,
1331
+ );
1332
+
1333
+ // Ideally we always connect as "read" by default.
1334
+ // Currently that works with SPO & r11s, because we get "write" connection when connecting to non-existing file.
1335
+ // We should not rely on it by (one of them will address the issue, but we need to address both)
1336
+ // 1) switching create new flow to one where we create file by posting snapshot
1337
+ // 2) Fixing quorum workflows (have retry logic)
1338
+ // That all said, "read" does not work with memorylicious workflows (that opens two simultaneous
1339
+ // connections to same file) in two ways:
1340
+ // A) creation flow breaks (as one of the clients "sees" file as existing, and hits #2 above)
1341
+ // B) Once file is created, transition from view-only connection to write does not work - some bugs to be fixed.
1342
+ const connectionArgs: IConnectionArgs = {
1343
+ reason: "DocumentOpen",
1344
+ mode: "write",
1345
+ fetchOpsFromStorage: false,
1346
+ };
1347
+
1348
+ // Start websocket connection as soon as possible. Note that there is no op handler attached yet, but the
1349
+ // DeltaManager is resilient to this and will wait to start processing ops until after it is attached.
1350
+ if (loadMode.deltaConnection === undefined) {
1351
+ this.connectToDeltaStream(connectionArgs);
1352
+ }
1353
+
1354
+ if (!pendingLocalState) {
1355
+ await this.storageService.connectToService(this.service);
1356
+ } else {
1357
+ // if we have pendingLocalState we can load without storage; don't wait for connection
1358
+ this.storageService.connectToService(this.service).catch((error) => {
1359
+ this.close(error);
1360
+ this.dispose?.(error);
1361
+ });
1362
+ }
1363
+
1364
+ this._attachState = AttachState.Attached;
1365
+
1366
+ // Fetch specified snapshot.
1367
+ const { snapshot, versionId } =
1368
+ pendingLocalState === undefined
1369
+ ? await this.fetchSnapshotTree(specifiedVersion)
1370
+ : { snapshot: undefined, versionId: undefined };
1371
+ assert(
1372
+ snapshot !== undefined || pendingLocalState !== undefined,
1373
+ 0x237 /* "Snapshot should exist" */,
1374
+ );
1375
+
1376
+ const attributes: IDocumentAttributes =
1377
+ pendingLocalState === undefined
1378
+ ? await this.getDocumentAttributes(this.storageService, snapshot)
1379
+ : {
1380
+ sequenceNumber: pendingLocalState.protocol.sequenceNumber,
1381
+ minimumSequenceNumber: pendingLocalState.protocol.minimumSequenceNumber,
1382
+ term: pendingLocalState.term,
1383
+ };
1384
+
1385
+ let opsBeforeReturnP: Promise<void> | undefined;
1386
+
1387
+ // Attach op handlers to finish initialization and be able to start processing ops
1388
+ // Kick off any ops fetching if required.
1389
+ switch (loadMode.opsBeforeReturn) {
1390
+ case undefined:
1391
+ // Start prefetch, but not set opsBeforeReturnP - boot is not blocked by it!
1392
+ // eslint-disable-next-line @typescript-eslint/no-floating-promises
1393
+ this.attachDeltaManagerOpHandler(
1394
+ attributes,
1395
+ loadMode.deltaConnection !== "none" ? "all" : "none",
1396
+ );
1397
+ break;
1398
+ case "cached":
1399
+ opsBeforeReturnP = this.attachDeltaManagerOpHandler(attributes, "cached");
1400
+ break;
1401
+ case "all":
1402
+ opsBeforeReturnP = this.attachDeltaManagerOpHandler(attributes, "all");
1403
+ break;
1404
+ default:
1405
+ unreachableCase(loadMode.opsBeforeReturn);
1406
+ }
1407
+
1408
+ // ...load in the existing quorum
1409
+ // Initialize the protocol handler
1410
+ if (pendingLocalState === undefined) {
1411
+ await this.initializeProtocolStateFromSnapshot(
1412
+ attributes,
1413
+ this.storageService,
1414
+ snapshot,
1415
+ );
1416
+ } else {
1417
+ this.initializeProtocolState(
1418
+ attributes,
1419
+ {
1420
+ members: pendingLocalState.protocol.members,
1421
+ proposals: pendingLocalState.protocol.proposals,
1422
+ values: pendingLocalState.protocol.values,
1423
+ }, // pending IQuorumSnapshot
1424
+ );
1425
+ }
1426
+
1427
+ const codeDetails = this.getCodeDetailsFromQuorum();
1428
+ await this.instantiateContext(
1429
+ true, // existing
1430
+ codeDetails,
1431
+ snapshot,
1432
+ pendingLocalState?.pendingRuntimeState,
1433
+ );
1434
+
1435
+ // We might have hit some failure that did not manifest itself in exception in this flow,
1436
+ // do not start op processing in such case - static version of Container.load() will handle it correctly.
1437
+ if (!this.closed) {
1438
+ if (opsBeforeReturnP !== undefined) {
1439
+ this._deltaManager.inbound.resume();
1440
+
1441
+ await PerformanceEvent.timedExecAsync(
1442
+ this.mc.logger,
1443
+ { eventName: "WaitOps" },
1444
+ async () => opsBeforeReturnP,
1445
+ );
1446
+ await PerformanceEvent.timedExecAsync(
1447
+ this.mc.logger,
1448
+ { eventName: "WaitOpProcessing" },
1449
+ async () => this._deltaManager.inbound.waitTillProcessingDone(),
1450
+ );
1451
+
1452
+ // eslint-disable-next-line @typescript-eslint/no-floating-promises
1453
+ this._deltaManager.inbound.pause();
1454
+ }
1455
+
1456
+ switch (loadMode.deltaConnection) {
1457
+ case undefined:
1458
+ case "delayed":
1459
+ assert(
1460
+ this.inboundQueuePausedFromInit,
1461
+ 0x346 /* inboundQueuePausedFromInit should be true */,
1462
+ );
1463
+ this.inboundQueuePausedFromInit = false;
1464
+ this._deltaManager.inbound.resume();
1465
+ this._deltaManager.inboundSignal.resume();
1466
+ break;
1467
+ case "none":
1468
+ break;
1469
+ default:
1470
+ unreachableCase(loadMode.deltaConnection);
1471
+ }
1472
+ }
1473
+
1474
+ // Safety net: static version of Container.load() should have learned about it through "closed" handler.
1475
+ // But if that did not happen for some reason, fail load for sure.
1476
+ // Otherwise we can get into situations where container is closed and does not try to connect to ordering
1477
+ // service, but caller does not know that (callers do expect container to be not closed on successful path
1478
+ // and listen only on "closed" event)
1479
+ if (this.closed) {
1480
+ throw new Error("Container was closed while load()");
1481
+ }
1482
+
1483
+ // Internal context is fully loaded at this point
1484
+ this.setLoaded();
1485
+
1486
+ return {
1487
+ sequenceNumber: attributes.sequenceNumber,
1488
+ version: versionId,
1489
+ dmLastProcessedSeqNumber: this._deltaManager.lastSequenceNumber,
1490
+ dmLastKnownSeqNumber: this._deltaManager.lastKnownSeqNumber,
1491
+ };
1492
+ }
1493
+
1494
+ private async createDetached(source: IFluidCodeDetails) {
1495
+ const attributes: IDocumentAttributes = {
1496
+ sequenceNumber: detachedContainerRefSeqNumber,
1497
+ term: 1,
1498
+ minimumSequenceNumber: 0,
1499
+ };
1500
+
1501
+ await this.attachDeltaManagerOpHandler(attributes);
1502
+
1503
+ // Need to just seed the source data in the code quorum. Quorum itself is empty
1504
+ const qValues = initQuorumValuesFromCodeDetails(source);
1505
+ this.initializeProtocolState(
1506
+ attributes,
1507
+ {
1508
+ members: [],
1509
+ proposals: [],
1510
+ values: qValues,
1511
+ }, // IQuorumSnapShot
1512
+ );
1513
+
1514
+ // The load context - given we seeded the quorum - will be great
1515
+ await this.instantiateContextDetached(
1516
+ false, // existing
1517
+ );
1518
+
1519
+ this.setLoaded();
1520
+ }
1521
+
1522
+ private async rehydrateDetachedFromSnapshot(detachedContainerSnapshot: ISummaryTree) {
1523
+ if (detachedContainerSnapshot.tree[".hasAttachmentBlobs"] !== undefined) {
1524
+ assert(
1525
+ !!this.loader.services.detachedBlobStorage &&
1526
+ this.loader.services.detachedBlobStorage.size > 0,
1527
+ 0x250 /* "serialized container with attachment blobs must be rehydrated with detached blob storage" */,
1528
+ );
1529
+ delete detachedContainerSnapshot.tree[".hasAttachmentBlobs"];
1530
+ }
1531
+
1532
+ const snapshotTree = getSnapshotTreeFromSerializedContainer(detachedContainerSnapshot);
1533
+ this.storageService.loadSnapshotForRehydratingContainer(snapshotTree);
1534
+ const attributes = await this.getDocumentAttributes(this.storageService, snapshotTree);
1535
+
1536
+ await this.attachDeltaManagerOpHandler(attributes);
1537
+
1538
+ // Initialize the protocol handler
1539
+ const baseTree = getProtocolSnapshotTree(snapshotTree);
1540
+ const qValues = await readAndParse<[string, ICommittedProposal][]>(
1541
+ this.storageService,
1542
+ baseTree.blobs.quorumValues,
1543
+ );
1544
+ const codeDetails = getCodeDetailsFromQuorumValues(qValues);
1545
+ this.initializeProtocolState(
1546
+ attributes,
1547
+ {
1548
+ members: [],
1549
+ proposals: [],
1550
+ values:
1551
+ codeDetails !== undefined ? initQuorumValuesFromCodeDetails(codeDetails) : [],
1552
+ }, // IQuorumSnapShot
1553
+ );
1554
+
1555
+ await this.instantiateContextDetached(
1556
+ true, // existing
1557
+ snapshotTree,
1558
+ );
1559
+
1560
+ this.setLoaded();
1561
+ }
1562
+
1563
+ private async getDocumentAttributes(
1564
+ storage: IDocumentStorageService,
1565
+ tree: ISnapshotTree | undefined,
1566
+ ): Promise<IDocumentAttributes> {
1567
+ if (tree === undefined) {
1568
+ return {
1569
+ minimumSequenceNumber: 0,
1570
+ sequenceNumber: 0,
1571
+ term: 1,
1572
+ };
1573
+ }
1574
+
1575
+ // Backward compatibility: old docs would have ".attributes" instead of "attributes"
1576
+ const attributesHash =
1577
+ ".protocol" in tree.trees
1578
+ ? tree.trees[".protocol"].blobs.attributes
1579
+ : tree.blobs[".attributes"];
1580
+
1581
+ const attributes = await readAndParse<IDocumentAttributes>(storage, attributesHash);
1582
+
1583
+ // Backward compatibility for older summaries with no term
1584
+ if (attributes.term === undefined) {
1585
+ attributes.term = 1;
1586
+ }
1587
+
1588
+ return attributes;
1589
+ }
1590
+
1591
+ private async initializeProtocolStateFromSnapshot(
1592
+ attributes: IDocumentAttributes,
1593
+ storage: IDocumentStorageService,
1594
+ snapshot: ISnapshotTree | undefined,
1595
+ ): Promise<void> {
1596
+ const quorumSnapshot: IQuorumSnapshot = {
1597
+ members: [],
1598
+ proposals: [],
1599
+ values: [],
1600
+ };
1601
+
1602
+ if (snapshot !== undefined) {
1603
+ const baseTree = getProtocolSnapshotTree(snapshot);
1604
+ [quorumSnapshot.members, quorumSnapshot.proposals, quorumSnapshot.values] =
1605
+ await Promise.all([
1606
+ readAndParse<[string, ISequencedClient][]>(
1607
+ storage,
1608
+ baseTree.blobs.quorumMembers,
1609
+ ),
1610
+ readAndParse<[number, ISequencedProposal, string[]][]>(
1611
+ storage,
1612
+ baseTree.blobs.quorumProposals,
1613
+ ),
1614
+ readAndParse<[string, ICommittedProposal][]>(
1615
+ storage,
1616
+ baseTree.blobs.quorumValues,
1617
+ ),
1618
+ ]);
1619
+ }
1620
+
1621
+ this.initializeProtocolState(attributes, quorumSnapshot);
1622
+ }
1623
+
1624
+ private initializeProtocolState(
1625
+ attributes: IDocumentAttributes,
1626
+ quorumSnapshot: IQuorumSnapshot,
1627
+ ): void {
1628
+ const protocolHandlerBuilder =
1629
+ this.protocolHandlerBuilder ??
1630
+ ((...args) => new ProtocolHandler(...args, new Audience()));
1631
+ const protocol = protocolHandlerBuilder(attributes, quorumSnapshot, (key, value) =>
1632
+ this.submitMessage(MessageType.Propose, JSON.stringify({ key, value })),
1633
+ );
1634
+
1635
+ const protocolLogger = ChildLogger.create(this.subLogger, "ProtocolHandler");
1636
+
1637
+ protocol.quorum.on("error", (error) => {
1638
+ protocolLogger.sendErrorEvent(error);
1639
+ });
1640
+
1641
+ // Track membership changes and update connection state accordingly
1642
+ this.connectionStateHandler.initProtocol(protocol);
1643
+
1644
+ protocol.quorum.on("addProposal", (proposal: ISequencedProposal) => {
1645
+ if (proposal.key === "code" || proposal.key === "code2") {
1646
+ this.emit("codeDetailsProposed", proposal.value, proposal);
1647
+ }
1648
+ });
1649
+
1650
+ protocol.quorum.on("approveProposal", (sequenceNumber, key, value) => {
1651
+ if (key === "code" || key === "code2") {
1652
+ if (!isFluidCodeDetails(value)) {
1653
+ this.mc.logger.sendErrorEvent({
1654
+ eventName: "CodeProposalNotIFluidCodeDetails",
1655
+ });
1656
+ }
1657
+ this.processCodeProposal().catch((error) => {
1658
+ const normalizedError = normalizeError(error);
1659
+ this.close(normalizedError);
1660
+ this.dispose?.(normalizedError);
1661
+ throw error;
1662
+ });
1663
+ }
1664
+ });
1665
+ // we need to make sure this member get set in a synchronous context,
1666
+ // or other things can happen after the object that will be set is created, but not yet set
1667
+ // this was breaking this._initialClients handling
1668
+ //
1669
+ this._protocolHandler = protocol;
1670
+ }
1671
+
1672
+ private captureProtocolSummary(): ISummaryTree {
1673
+ const quorumSnapshot = this.protocolHandler.snapshot();
1674
+ const summary: ISummaryTree = {
1675
+ tree: {
1676
+ attributes: {
1677
+ content: JSON.stringify(this.protocolHandler.attributes),
1678
+ type: SummaryType.Blob,
1679
+ },
1680
+ quorumMembers: {
1681
+ content: JSON.stringify(quorumSnapshot.members),
1682
+ type: SummaryType.Blob,
1683
+ },
1684
+ quorumProposals: {
1685
+ content: JSON.stringify(quorumSnapshot.proposals),
1686
+ type: SummaryType.Blob,
1687
+ },
1688
+ quorumValues: {
1689
+ content: JSON.stringify(quorumSnapshot.values),
1690
+ type: SummaryType.Blob,
1691
+ },
1692
+ },
1693
+ type: SummaryType.Tree,
1694
+ };
1695
+
1696
+ return summary;
1697
+ }
1698
+
1699
+ private getCodeDetailsFromQuorum(): IFluidCodeDetails {
1700
+ const quorum = this.protocolHandler.quorum;
1701
+
1702
+ const pkg = getCodeProposal(quorum);
1703
+
1704
+ return pkg as IFluidCodeDetails;
1705
+ }
1706
+
1707
+ private get client(): IClient {
1708
+ const client: IClient =
1709
+ this.options?.client !== undefined
1710
+ ? (this.options.client as IClient)
1711
+ : {
1712
+ details: {
1713
+ capabilities: { interactive: true },
1714
+ },
1715
+ mode: "read", // default reconnection mode on lost connection / connection error
1716
+ permission: [],
1717
+ scopes: [],
1718
+ user: { id: "" },
1719
+ };
1720
+
1721
+ if (this.clientDetailsOverride !== undefined) {
1722
+ merge(client.details, this.clientDetailsOverride);
1723
+ }
1724
+ client.details.environment = [
1725
+ client.details.environment,
1726
+ ` loaderVersion:${pkgVersion}`,
1727
+ ].join(";");
1728
+ return client;
1729
+ }
1730
+
1731
+ /**
1732
+ * Returns true if connection is active, i.e. it's "write" connection and
1733
+ * container runtime was notified about this connection (i.e. we are up-to-date and could send ops).
1734
+ * This happens after client received its own joinOp and thus is in the quorum.
1735
+ * If it's not true, runtime is not in position to send ops.
1736
+ */
1737
+ private activeConnection() {
1738
+ return (
1739
+ this.connectionState === ConnectionState.Connected && this.connectionMode === "write"
1740
+ );
1741
+ }
1742
+
1743
+ private createDeltaManager() {
1744
+ const serviceProvider = () => this.service;
1745
+ const deltaManager = new DeltaManager<ConnectionManager>(
1746
+ serviceProvider,
1747
+ ChildLogger.create(this.subLogger, "DeltaManager"),
1748
+ () => this.activeConnection(),
1749
+ (props: IConnectionManagerFactoryArgs) =>
1750
+ new ConnectionManager(
1751
+ serviceProvider,
1752
+ this.client,
1753
+ this._canReconnect,
1754
+ ChildLogger.create(this.subLogger, "ConnectionManager"),
1755
+ props,
1756
+ ),
1757
+ );
1758
+
1759
+ // Disable inbound queues as Container is not ready to accept any ops until we are fully loaded!
1760
+ // eslint-disable-next-line @typescript-eslint/no-floating-promises
1761
+ deltaManager.inbound.pause();
1762
+ // eslint-disable-next-line @typescript-eslint/no-floating-promises
1763
+ deltaManager.inboundSignal.pause();
1764
+
1765
+ deltaManager.on("connect", (details: IConnectionDetails, _opsBehind?: number) => {
1766
+ assert(this.connectionMode === details.mode, 0x4b7 /* mismatch */);
1767
+ this.connectionStateHandler.receivedConnectEvent(details);
1768
+ });
1769
+
1770
+ deltaManager.on("disconnect", (reason: string) => {
1771
+ this.collabWindowTracker?.stopSequenceNumberUpdate();
1772
+ if (!this.closed) {
1773
+ this.connectionStateHandler.receivedDisconnectEvent(reason);
1774
+ }
1775
+ });
1776
+
1777
+ deltaManager.on("throttled", (warning: IThrottlingWarning) => {
1778
+ const warn = warning as ContainerWarning;
1779
+ // Some "warning" events come from outside the container and are logged
1780
+ // elsewhere (e.g. summarizing container). We shouldn't log these here.
1781
+ if (warn.logged !== true) {
1782
+ this.mc.logger.sendTelemetryEvent({ eventName: "ContainerWarning" }, warn);
1783
+ }
1784
+ this.emit("warning", warn);
1785
+ });
1786
+
1787
+ deltaManager.on("readonly", (readonly) => {
1788
+ this.setContextConnectedState(
1789
+ this.connectionState === ConnectionState.Connected,
1790
+ readonly,
1791
+ );
1792
+ this.emit("readonly", readonly);
1793
+ });
1794
+
1795
+ deltaManager.on("closed", (error?: ICriticalContainerError) => {
1796
+ this.closeCore(error);
1797
+ });
1798
+
1799
+ deltaManager.on("disposed", (error?: ICriticalContainerError) => {
1800
+ this.disposeCore(error);
1801
+ });
1802
+
1803
+ return deltaManager;
1804
+ }
1805
+
1806
+ private async attachDeltaManagerOpHandler(
1807
+ attributes: IDocumentAttributes,
1808
+ prefetchType?: "cached" | "all" | "none",
1809
+ ) {
1810
+ return this._deltaManager.attachOpHandler(
1811
+ attributes.minimumSequenceNumber,
1812
+ attributes.sequenceNumber,
1813
+ attributes.term ?? 1,
1814
+ {
1815
+ process: (message) => this.processRemoteMessage(message),
1816
+ processSignal: (message) => {
1817
+ this.processSignal(message);
1818
+ },
1819
+ },
1820
+ prefetchType,
1821
+ );
1822
+ }
1823
+
1824
+ private logConnectionStateChangeTelemetry(
1825
+ value: ConnectionState,
1826
+ oldState: ConnectionState,
1827
+ reason?: string,
1828
+ ) {
1829
+ // Log actual event
1830
+ const time = performance.now();
1831
+ this.connectionTransitionTimes[value] = time;
1832
+ const duration = time - this.connectionTransitionTimes[oldState];
1833
+
1834
+ let durationFromDisconnected: number | undefined;
1835
+ let connectionInitiationReason: string | undefined;
1836
+ let autoReconnect: ReconnectMode | undefined;
1837
+ let checkpointSequenceNumber: number | undefined;
1838
+ let opsBehind: number | undefined;
1839
+ if (value === ConnectionState.Disconnected) {
1840
+ autoReconnect = this._deltaManager.connectionManager.reconnectMode;
1841
+ } else {
1842
+ if (value === ConnectionState.Connected) {
1843
+ durationFromDisconnected =
1844
+ time - this.connectionTransitionTimes[ConnectionState.Disconnected];
1845
+ durationFromDisconnected = TelemetryLogger.formatTick(durationFromDisconnected);
1846
+ } else {
1847
+ // This info is of most interest on establishing connection only.
1848
+ checkpointSequenceNumber = this.deltaManager.lastKnownSeqNumber;
1849
+ if (this.deltaManager.hasCheckpointSequenceNumber) {
1850
+ opsBehind = checkpointSequenceNumber - this.deltaManager.lastSequenceNumber;
1851
+ }
1852
+ }
1853
+ connectionInitiationReason = this.firstConnection ? "InitialConnect" : "AutoReconnect";
1854
+ }
1855
+
1856
+ this.mc.logger.sendPerformanceEvent({
1857
+ eventName: `ConnectionStateChange_${ConnectionState[value]}`,
1858
+ from: ConnectionState[oldState],
1859
+ duration,
1860
+ durationFromDisconnected,
1861
+ reason,
1862
+ connectionInitiationReason,
1863
+ pendingClientId: this.connectionStateHandler.pendingClientId,
1864
+ clientId: this.clientId,
1865
+ autoReconnect,
1866
+ opsBehind,
1867
+ online: OnlineStatus[isOnline()],
1868
+ lastVisible:
1869
+ this.lastVisible !== undefined ? performance.now() - this.lastVisible : undefined,
1870
+ checkpointSequenceNumber,
1871
+ quorumSize: this._protocolHandler?.quorum.getMembers().size,
1872
+ ...this._deltaManager.connectionProps,
1873
+ });
1874
+
1875
+ if (value === ConnectionState.Connected) {
1876
+ this.firstConnection = false;
1877
+ }
1878
+ }
1879
+
1880
+ private propagateConnectionState(initialTransition: boolean, disconnectedReason?: string) {
1881
+ // When container loaded, we want to propagate initial connection state.
1882
+ // After that, we communicate only transitions to Connected & Disconnected states, skipping all other states.
1883
+ // This can be changed in the future, for example we likely should add "CatchingUp" event on Container.
1884
+ if (
1885
+ !initialTransition &&
1886
+ this.connectionState !== ConnectionState.Connected &&
1887
+ this.connectionState !== ConnectionState.Disconnected
1888
+ ) {
1889
+ return;
1890
+ }
1891
+ const state = this.connectionState === ConnectionState.Connected;
1892
+
1893
+ const logOpsOnReconnect: boolean =
1894
+ this.connectionState === ConnectionState.Connected &&
1895
+ !this.firstConnection &&
1896
+ this.connectionMode === "write";
1897
+ if (logOpsOnReconnect) {
1898
+ this.messageCountAfterDisconnection = 0;
1899
+ }
1900
+
1901
+ // Both protocol and context should not be undefined if we got so far.
1902
+
1903
+ this.setContextConnectedState(
1904
+ state,
1905
+ this._deltaManager.connectionManager.readOnlyInfo.readonly ?? false,
1906
+ );
1907
+ this.protocolHandler.setConnectionState(state, this.clientId);
1908
+ raiseConnectedEvent(this.mc.logger, this, state, this.clientId, disconnectedReason);
1909
+
1910
+ if (logOpsOnReconnect) {
1911
+ this.mc.logger.sendTelemetryEvent({
1912
+ eventName: "OpsSentOnReconnect",
1913
+ count: this.messageCountAfterDisconnection,
1914
+ });
1915
+ }
1916
+ }
1917
+
1918
+ // back-compat: ADO #1385: Remove in the future, summary op should come through submitSummaryMessage()
1919
+ private submitContainerMessage(
1920
+ type: MessageType,
1921
+ contents: any,
1922
+ batch?: boolean,
1923
+ metadata?: any,
1924
+ ): number {
1925
+ switch (type) {
1926
+ case MessageType.Operation:
1927
+ return this.submitMessage(type, JSON.stringify(contents), batch, metadata);
1928
+ case MessageType.Summarize:
1929
+ return this.submitSummaryMessage(contents as unknown as ISummaryContent);
1930
+ default: {
1931
+ const newError = new GenericError(
1932
+ "invalidContainerSubmitOpType",
1933
+ undefined /* error */,
1934
+ { messageType: type },
1935
+ );
1936
+ this.close(newError);
1937
+ this.dispose?.(newError);
1938
+ return -1;
1939
+ }
1940
+ }
1941
+ }
1942
+
1943
+ /** @returns clientSequenceNumber of last message in a batch */
1944
+ private submitBatch(batch: IBatchMessage[]): number {
1945
+ let clientSequenceNumber = -1;
1946
+ for (const message of batch) {
1947
+ clientSequenceNumber = this.submitMessage(
1948
+ MessageType.Operation,
1949
+ message.contents,
1950
+ true, // batch
1951
+ message.metadata,
1952
+ message.compression,
1953
+ );
1954
+ }
1955
+ this._deltaManager.flush();
1956
+ return clientSequenceNumber;
1957
+ }
1958
+
1959
+ private submitSummaryMessage(summary: ISummaryContent) {
1960
+ // github #6451: this is only needed for staging so the server
1961
+ // know when the protocol tree is included
1962
+ // this can be removed once all clients send
1963
+ // protocol tree by default
1964
+ if (summary.details === undefined) {
1965
+ summary.details = {};
1966
+ }
1967
+ summary.details.includesProtocolTree = this.options.summarizeProtocolTree === true;
1968
+ return this.submitMessage(
1969
+ MessageType.Summarize,
1970
+ JSON.stringify(summary),
1971
+ false /* batch */,
1972
+ );
1973
+ }
1974
+
1975
+ private submitMessage(
1976
+ type: MessageType,
1977
+ contents?: string,
1978
+ batch?: boolean,
1979
+ metadata?: any,
1980
+ compression?: string,
1981
+ ): number {
1982
+ if (this.connectionState !== ConnectionState.Connected) {
1983
+ this.mc.logger.sendErrorEvent({ eventName: "SubmitMessageWithNoConnection", type });
1984
+ return -1;
1985
+ }
1986
+
1987
+ this.messageCountAfterDisconnection += 1;
1988
+ this.collabWindowTracker?.stopSequenceNumberUpdate();
1989
+ return this._deltaManager.submit(type, contents, batch, metadata, compression);
1990
+ }
1991
+
1992
+ private processRemoteMessage(message: ISequencedDocumentMessage) {
1993
+ const local = this.clientId === message.clientId;
1994
+
1995
+ // Allow the protocol handler to process the message
1996
+ const result = this.protocolHandler.processMessage(message, local);
1997
+
1998
+ // Forward messages to the loaded runtime for processing
1999
+ this.context.process(message, local);
2000
+
2001
+ // Inactive (not in quorum or not writers) clients don't take part in the minimum sequence number calculation.
2002
+ if (this.activeConnection()) {
2003
+ if (this.collabWindowTracker === undefined) {
2004
+ // Note that config from first connection will be used for this container's lifetime.
2005
+ // That means that if relay service changes settings, such changes will impact only newly booted
2006
+ // clients.
2007
+ // All existing will continue to use settings they got earlier.
2008
+ assert(
2009
+ this.serviceConfiguration !== undefined,
2010
+ 0x2e4 /* "there should be service config for active connection" */,
2011
+ );
2012
+ this.collabWindowTracker = new CollabWindowTracker(
2013
+ (type) => {
2014
+ assert(
2015
+ this.activeConnection(),
2016
+ 0x241 /* "disconnect should result in stopSequenceNumberUpdate() call" */,
2017
+ );
2018
+ this.submitMessage(type);
2019
+ },
2020
+ this.serviceConfiguration.noopTimeFrequency,
2021
+ this.serviceConfiguration.noopCountFrequency,
2022
+ );
2023
+ }
2024
+ this.collabWindowTracker.scheduleSequenceNumberUpdate(
2025
+ message,
2026
+ result.immediateNoOp === true,
2027
+ );
2028
+ }
2029
+
2030
+ this.emit("op", message);
2031
+ }
2032
+
2033
+ private submitSignal(message: any) {
2034
+ this._deltaManager.submitSignal(JSON.stringify(message));
2035
+ }
2036
+
2037
+ private processSignal(message: ISignalMessage) {
2038
+ // No clientId indicates a system signal message.
2039
+ if (message.clientId === null) {
2040
+ this.protocolHandler.processSignal(message);
2041
+ } else {
2042
+ const local = this.clientId === message.clientId;
2043
+ this.context.processSignal(message, local);
2044
+ }
2045
+ }
2046
+
2047
+ /**
2048
+ * Get the most recent snapshot, or a specific version.
2049
+ * @param specifiedVersion - The specific version of the snapshot to retrieve
2050
+ * @returns The snapshot requested, or the latest snapshot if no version was specified, plus version ID
2051
+ */
2052
+ private async fetchSnapshotTree(
2053
+ specifiedVersion: string | undefined,
2054
+ ): Promise<{ snapshot?: ISnapshotTree; versionId?: string }> {
2055
+ const version = await this.getVersion(specifiedVersion ?? null);
2056
+
2057
+ if (version === undefined && specifiedVersion !== undefined) {
2058
+ // We should have a defined version to load from if specified version requested
2059
+ this.mc.logger.sendErrorEvent({
2060
+ eventName: "NoVersionFoundWhenSpecified",
2061
+ id: specifiedVersion,
2062
+ });
2063
+ }
2064
+ this._loadedFromVersion = version;
2065
+ const snapshot = (await this.storageService.getSnapshotTree(version)) ?? undefined;
2066
+
2067
+ if (snapshot === undefined && version !== undefined) {
2068
+ this.mc.logger.sendErrorEvent({ eventName: "getSnapshotTreeFailed", id: version.id });
2069
+ }
2070
+ return { snapshot, versionId: version?.id };
2071
+ }
2072
+
2073
+ private async instantiateContextDetached(existing: boolean, snapshot?: ISnapshotTree) {
2074
+ const codeDetails = this.getCodeDetailsFromQuorum();
2075
+ if (codeDetails === undefined) {
2076
+ throw new Error("pkg should be provided in create flow!!");
2077
+ }
2078
+
2079
+ await this.instantiateContext(existing, codeDetails, snapshot);
2080
+ }
2081
+
2082
+ private async instantiateContext(
2083
+ existing: boolean,
2084
+ codeDetails: IFluidCodeDetails,
2085
+ snapshot?: ISnapshotTree,
2086
+ pendingLocalState?: unknown,
2087
+ ) {
2088
+ assert(this._context?.disposed !== false, 0x0dd /* "Existing context not disposed" */);
2089
+
2090
+ // The relative loader will proxy requests to '/' to the loader itself assuming no non-cache flags
2091
+ // are set. Global requests will still go directly to the loader
2092
+ const loader = new RelativeLoader(this, this.loader);
2093
+ this._context = await ContainerContext.createOrLoad(
2094
+ this,
2095
+ this.scope,
2096
+ this.codeLoader,
2097
+ codeDetails,
2098
+ snapshot,
2099
+ new DeltaManagerProxy(this._deltaManager),
2100
+ new QuorumProxy(this.protocolHandler.quorum),
2101
+ loader,
2102
+ (type, contents, batch, metadata) =>
2103
+ this.submitContainerMessage(type, contents, batch, metadata),
2104
+ (summaryOp: ISummaryContent) => this.submitSummaryMessage(summaryOp),
2105
+ (batch: IBatchMessage[]) => this.submitBatch(batch),
2106
+ (message) => this.submitSignal(message),
2107
+ (error?: ICriticalContainerError) => this.dispose?.(error),
2108
+ (error?: ICriticalContainerError) => this.close(error),
2109
+ Container.version,
2110
+ (dirty: boolean) => this.updateDirtyContainerState(dirty),
2111
+ existing,
2112
+ pendingLocalState,
2113
+ );
2114
+
2115
+ this.emit("contextChanged", codeDetails);
2116
+ }
2117
+
2118
+ private updateDirtyContainerState(dirty: boolean) {
2119
+ if (this._dirtyContainer === dirty) {
2120
+ return;
2121
+ }
2122
+ this._dirtyContainer = dirty;
2123
+ this.emit(dirty ? dirtyContainerEvent : savedContainerEvent);
2124
+ }
2125
+
2126
+ /**
2127
+ * Set the connected state of the ContainerContext
2128
+ * This controls the "connected" state of the ContainerRuntime as well
2129
+ * @param state - Is the container currently connected?
2130
+ * @param readonly - Is the container in readonly mode?
2131
+ */
2132
+ private setContextConnectedState(state: boolean, readonly: boolean): void {
2133
+ if (this._context?.disposed === false) {
2134
+ /**
2135
+ * We want to lie to the ContainerRuntime when we are in readonly mode to prevent issues with pending
2136
+ * ops getting through to the DeltaManager.
2137
+ * The ContainerRuntime's "connected" state simply means it is ok to send ops
2138
+ * See https://dev.azure.com/fluidframework/internal/_workitems/edit/1246
2139
+ */
2140
+ this.context.setConnectionState(state && !readonly, this.clientId);
2141
+ }
2142
+ }
1996
2143
  }