-
Notifications
You must be signed in to change notification settings - Fork 519
/
loader.ts
405 lines (368 loc) · 11.7 KB
/
loader.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
/*!
* Copyright (c) Microsoft Corporation and contributors. All rights reserved.
* Licensed under the MIT License.
*/
import {
IContainer,
IFluidCodeDetails,
IFluidModule,
IHostLoader,
ILoader,
ILoaderOptions as ILoaderOptions1,
IProvideFluidCodeDetailsComparer,
LoaderHeader,
} from "@fluidframework/container-definitions/internal";
import {
FluidObject,
IConfigProviderBase,
IRequest,
ITelemetryBaseLogger,
} from "@fluidframework/core-interfaces";
import { IClientDetails } from "@fluidframework/driver-definitions";
import {
IDocumentServiceFactory,
IDocumentStorageService,
IResolvedUrl,
IUrlResolver,
} from "@fluidframework/driver-definitions/internal";
import {
ITelemetryLoggerExt,
MonitoringContext,
PerformanceEvent,
createChildMonitoringContext,
mixinMonitoringContext,
sessionStorageConfigProvider,
} from "@fluidframework/telemetry-utils/internal";
import { v4 as uuid } from "uuid";
import { Container } from "./container.js";
import { DebugLogger } from "./debugLogger.js";
import { pkgVersion } from "./packageVersion.js";
import { ProtocolHandlerBuilder } from "./protocol.js";
import type { IPendingContainerState } from "./serializedStateManager.js";
import {
getAttachedContainerStateFromSerializedContainer,
tryParseCompatibleResolvedUrl,
} from "./utils.js";
function ensureResolvedUrlDefined(
resolved: IResolvedUrl | undefined,
): asserts resolved is IResolvedUrl {
if (resolved === undefined) {
throw new Error(`Object is not a IResolveUrl.`);
}
}
/**
* @internal
*/
export class RelativeLoader implements ILoader {
constructor(
private readonly container: Container,
private readonly loader: ILoader | undefined,
) {}
public async resolve(request: IRequest): Promise<IContainer> {
if (request.url.startsWith("/")) {
ensureResolvedUrlDefined(this.container.resolvedUrl);
const container = await this.container.clone(
{
resolvedUrl: { ...this.container.resolvedUrl },
version: request.headers?.[LoaderHeader.version] ?? undefined,
loadMode: request.headers?.[LoaderHeader.loadMode],
},
{
canReconnect: request.headers?.[LoaderHeader.reconnect],
clientDetailsOverride: request.headers?.[LoaderHeader.clientDetails],
},
);
return container;
}
if (this.loader === undefined) {
throw new Error("Cannot resolve external containers");
}
return this.loader.resolve(request);
}
}
/**
* @alpha
*/
export interface ILoaderOptions extends ILoaderOptions1 {
summarizeProtocolTree?: boolean;
}
/**
* @deprecated IFluidModuleWithDetails interface is moved to
* {@link @fluidframework/container-definitions#IFluidModuleWithDetails}
* to have all the code loading modules in one package. #8193
* Encapsulates a module entry point with corresponding code details.
* @alpha
*/
export interface IFluidModuleWithDetails {
/** Fluid code module that implements the runtime factory needed to instantiate the container runtime. */
module: IFluidModule;
/**
* Code details associated with the module. Represents a document schema this module supports.
* If the code loader implements the {@link @fluidframework/core-interfaces#IFluidCodeDetailsComparer} interface,
* it'll be called to determine whether the module code details satisfy the new code proposal in the quorum.
*/
details: IFluidCodeDetails;
}
/**
* @deprecated ICodeDetailsLoader interface is moved to {@link @fluidframework/container-definitions#ICodeDetailsLoader}
* to have code loading modules in one package. #8193
* Fluid code loader resolves a code module matching the document schema, i.e. code details, such as
* a package name and package version range.
* @alpha
*/
export interface ICodeDetailsLoader extends Partial<IProvideFluidCodeDetailsComparer> {
/**
* Load the code module (package) that is capable to interact with the document.
*
* @param source - Code proposal that articulates the current schema the document is written in.
* @returns Code module entry point along with the code details associated with it.
*/
load(source: IFluidCodeDetails): Promise<IFluidModuleWithDetails>;
}
/**
* Services and properties necessary for creating a loader
* @alpha
*/
export interface ILoaderProps {
/**
* The url resolver used by the loader for resolving external urls
* into Fluid urls such that the container specified by the
* external url can be loaded.
*/
readonly urlResolver: IUrlResolver;
/**
* The document service factory take the Fluid url provided
* by the resolved url and constructs all the necessary services
* for communication with the container's server.
*/
readonly documentServiceFactory: IDocumentServiceFactory;
/**
* The code loader handles loading the necessary code
* for running a container once it is loaded.
*/
readonly codeLoader: ICodeDetailsLoader;
/**
* A property bag of options used by various layers
* to control features
*/
readonly options?: ILoaderOptions;
/**
* Scope is provided to all container and is a set of shared
* services for container's to integrate with their host environment.
*/
readonly scope?: FluidObject;
/**
* The logger that all telemetry should be pushed to.
*/
readonly logger?: ITelemetryBaseLogger;
/**
* Blobs storage for detached containers.
*/
readonly detachedBlobStorage?: IDetachedBlobStorage;
/**
* The configuration provider which may be used to control features.
*/
readonly configProvider?: IConfigProviderBase;
/**
* Optional property for allowing the container to use a custom
* protocol implementation for handling the quorum and/or the audience.
*/
readonly protocolHandlerBuilder?: ProtocolHandlerBuilder;
}
/**
* Services and properties used by and exposed by the loader
* @alpha
*/
export interface ILoaderServices {
/**
* The url resolver used by the loader for resolving external urls
* into Fluid urls such that the container specified by the
* external url can be loaded.
*/
readonly urlResolver: IUrlResolver;
/**
* The document service factory take the Fluid url provided
* by the resolved url and constructs all the necessary services
* for communication with the container's server.
*/
readonly documentServiceFactory: IDocumentServiceFactory;
/**
* The code loader handles loading the necessary code
* for running a container once it is loaded.
*/
readonly codeLoader: ICodeDetailsLoader;
/**
* A property bag of options used by various layers
* to control features
*/
readonly options: ILoaderOptions;
/**
* Scope is provided to all container and is a set of shared
* services for container's to integrate with their host environment.
*/
readonly scope: FluidObject;
/**
* The logger downstream consumers should construct their loggers from
*/
readonly subLogger: ITelemetryLoggerExt;
/**
* Blobs storage for detached containers.
* @deprecated - IDetachedBlobStorage will be removed in a future release without a replacement. Blobs created while detached will be stored in memory to align with attached container behavior. AB#8049
*/
readonly detachedBlobStorage?: IDetachedBlobStorage;
/**
* Optional property for allowing the container to use a custom
* protocol implementation for handling the quorum and/or the audience.
*/
readonly protocolHandlerBuilder?: ProtocolHandlerBuilder;
}
/**
* Subset of IDocumentStorageService which only supports createBlob() and readBlob(). This is used to support
* blobs in detached containers.
* @alpha
*
* @deprecated - IDetachedBlobStorage will be removed in a future release without a replacement. Blobs created while detached will be stored in memory to align with attached container behavior. AB#8049
*/
export type IDetachedBlobStorage = Pick<IDocumentStorageService, "createBlob" | "readBlob"> & {
size: number;
/**
* Return an array of all blob IDs present in storage
*/
getBlobIds(): string[];
/**
* After the container is attached, the detached blob storage is no longer needed and will be disposed.
*/
dispose?(): void;
};
/**
* Manages Fluid resource loading
* @alpha
*/
export class Loader implements IHostLoader {
public readonly services: ILoaderServices;
private readonly mc: MonitoringContext;
constructor(loaderProps: ILoaderProps) {
const {
urlResolver,
documentServiceFactory,
codeLoader,
options,
scope,
logger,
detachedBlobStorage,
configProvider,
protocolHandlerBuilder,
} = loaderProps;
const telemetryProps = {
loaderId: uuid(),
loaderVersion: pkgVersion,
};
const subMc = mixinMonitoringContext(
DebugLogger.mixinDebugLogger("fluid:telemetry", logger, {
all: telemetryProps,
}),
sessionStorageConfigProvider.value,
configProvider,
);
this.services = {
urlResolver,
documentServiceFactory,
codeLoader,
options: options ?? {},
scope:
options?.provideScopeLoader !== false ? { ...scope, ILoader: this } : { ...scope },
detachedBlobStorage,
protocolHandlerBuilder,
subLogger: subMc.logger,
};
this.mc = createChildMonitoringContext({
logger: this.services.subLogger,
namespace: "Loader",
});
}
public async createDetachedContainer(
codeDetails: IFluidCodeDetails,
createDetachedProps?: {
canReconnect?: boolean;
clientDetailsOverride?: IClientDetails;
},
): Promise<IContainer> {
return Container.createDetached(
{
...createDetachedProps,
...this.services,
},
codeDetails,
);
}
public async rehydrateDetachedContainerFromSnapshot(
snapshot: string,
createDetachedProps?: {
canReconnect?: boolean;
clientDetailsOverride?: IClientDetails;
},
): Promise<IContainer> {
return Container.rehydrateDetachedFromSnapshot(
{
...createDetachedProps,
...this.services,
},
snapshot,
);
}
public async resolve(request: IRequest, pendingLocalState?: string): Promise<IContainer> {
const eventName = pendingLocalState === undefined ? "Resolve" : "ResolveWithPendingState";
return PerformanceEvent.timedExecAsync(this.mc.logger, { eventName }, async () => {
return this.resolveCore(
request,
getAttachedContainerStateFromSerializedContainer(pendingLocalState),
);
});
}
private async resolveCore(
request: IRequest,
pendingLocalState?: IPendingContainerState,
): Promise<Container> {
const resolvedAsFluid = await this.services.urlResolver.resolve(request);
ensureResolvedUrlDefined(resolvedAsFluid);
// Parse URL into data stores
const parsed = tryParseCompatibleResolvedUrl(resolvedAsFluid.url);
if (parsed === undefined) {
throw new Error(`Invalid URL ${resolvedAsFluid.url}`);
}
if (pendingLocalState !== undefined) {
const parsedPendingUrl = tryParseCompatibleResolvedUrl(pendingLocalState.url);
if (
parsedPendingUrl?.id !== parsed.id ||
parsedPendingUrl?.path.replace(/\/$/, "") !== parsed.path.replace(/\/$/, "")
) {
const message = `URL ${resolvedAsFluid.url} does not match pending state URL ${pendingLocalState.url}`;
throw new Error(message);
}
}
request.headers ??= {};
// If set in both query string and headers, use query string. Also write the value from the query string into the header either way.
request.headers[LoaderHeader.version] =
parsed.version ?? request.headers[LoaderHeader.version];
return this.loadContainer(request, resolvedAsFluid, pendingLocalState);
}
private async loadContainer(
request: IRequest,
resolvedUrl: IResolvedUrl,
pendingLocalState?: IPendingContainerState,
): Promise<Container> {
return Container.load(
{
resolvedUrl,
version: request.headers?.[LoaderHeader.version] ?? undefined,
loadMode: request.headers?.[LoaderHeader.loadMode],
pendingLocalState,
},
{
canReconnect: request.headers?.[LoaderHeader.reconnect],
clientDetailsOverride: request.headers?.[LoaderHeader.clientDetails],
...this.services,
},
);
}
}