Summary docs #10435
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -21,41 +21,93 @@ export interface ISummaryCommitter { | |
| date: string; | ||
| } | ||
|
|
||
| /** | ||
| * Type tag used to distinguish different types of nodes in a {@link ISummaryTree}. | ||
| */ | ||
| // eslint-disable-next-line @typescript-eslint/no-namespace | ||
| export namespace SummaryType { | ||
| export type Tree = 1; | ||
| export type Blob = 2; | ||
| export type Handle = 3; | ||
| export type Attachment = 4; | ||
|
|
||
| /** | ||
| * Represents a sub-tree in the summary. | ||
| */ | ||
| export const Tree: Tree = 1 as const; | ||
|
|
||
| /** | ||
| * Represents a blob of data that is added to the summary. | ||
| * Such as the user data that is added to the DDS or metadata added by runtime | ||
| * such as data store / channel attributes. | ||
| */ | ||
| export const Blob: Blob = 2 as const; | ||
|
|
||
| /** | ||
andre4i marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| * Path to a summary tree object from the last successful summary. | ||
| */ | ||
| export const Handle: Handle = 3 as const; | ||
|
|
||
| /** | ||
| * Unique identifier to larger blobs uploaded outside of the summary. | ||
| * Ex. DDS has large images or video that will be uploaded by the BlobManager and | ||
| * receive an Id that can be used in the summary. | ||
| */ | ||
| export const Attachment: Attachment = 4 as const; | ||
| } | ||
|
There was a problem hiding this comment. If you happen to know the answer, it would be good to document if there was an explicit choice not to declare SummaryType as an enum? There was a problem hiding this comment. @anthony-murphy Do you know why ? There was a problem hiding this comment. Maybe because of the reason mentioned in this comment here - #9548 (comment) |
||
| export type SummaryType = SummaryType.Attachment | SummaryType.Blob | SummaryType.Handle | SummaryType.Tree; | ||
|
|
||
| export type SummaryTypeNoHandle = SummaryType.Tree | SummaryType.Blob | SummaryType.Attachment; | ||
|
|
||
| /** | ||
| * Path to a summary tree object from the last successful summary indicating the summary object hasn't | ||
| * changed since it was uploaded. | ||
| * To illustrate, if a DataStore did not change since last summary, the framework runtime will use a handle for the | ||
| * entire DataStore instead of re-sending the entire subtree. The same concept applies for a DDS. | ||
| * An example of handle would be: '/<DataStoreId>/<DDSId>'. | ||
| */ | ||
| export interface ISummaryHandle { | ||
| type: SummaryType.Handle; | ||
|
|
||
| /** | ||
| * Type of Summary Handle (SummaryType.Handle is not supported). | ||
|
There was a problem hiding this comment. Is this really the type of the handle, or is it the type of the data to which the handle points? #Resolved There was a problem hiding this comment. yes, it is a type for which the handle references to. |
||
| */ | ||
| handleType: SummaryTypeNoHandle; | ||
|
|
||
| /** | ||
| * Unique path that identifies the corresponding sub-tree in a previous summary. | ||
| */ | ||
| handle: string; | ||
|
There was a problem hiding this comment. How do I get one of these? There was a problem hiding this comment. As a developer, I don't think you need to get it - if I got it right, it is automatically set (id) when we create the fluid file from a summary: Ex. createNewFluidFileFromSummary. @agarwal-navin to confirm. There was a problem hiding this comment. Not really. Currently, every object that wants to use this to send a path to previous summary instead of full summary has to know what the path is. For example, the summarizer node for data store context and channel contexts tracks this path and adds it. There was a problem hiding this comment. I believe the way it should it be is similar to how summary tree is built. Each node just adds its summary tree when asked for it. It's the responsibility of the caller to add this tree against the correct path. This way by the time the summary tree reaches the root, all paths are fully built w.r.t. root. There was a problem hiding this comment. Let's sync up ? There was a problem hiding this comment. Just as a reference- the only place I found that adds the handle to the tree is when we call encodeSummary (builder.addHandle). There was a problem hiding this comment. This is the main usage of summary handle in our code - The There was a problem hiding this comment. Thanks Navin I had missed it - at the SummarizerNode level, if we are tracking it, it is stored under _latestSummary.fullPath.path |
||
| } | ||
|
|
||
| /** | ||
|
There was a problem hiding this comment. I think it would be good to mention here that to reference an already uploaded blob use ISummaryAttachment. Someone looking for how to do that is likley to find themselves here, and not realize they need to look into ISummaryAttachments. #Resolved |
||
| * String or Binary data to be uploaded to the server as part of the container's Summary. | ||
| * Note: Already uploaded blobs would be referenced by a ISummaryAttachment. | ||
| * Additional information can be found here: https://github.com/microsoft/FluidFramework/issues/6568 | ||
| * Ex. "content": "\{ \"pkg\":\"[\\\"OfficeRootComponent\\\",\\\"LastEditedComponent\\\"]\", | ||
| * \"summaryFormatVersion\":2,\"isRootDataStore\":false \}" | ||
| */ | ||
| export interface ISummaryBlob { | ||
| type: SummaryType.Blob; | ||
| content: string | Uint8Array; | ||
| } | ||
|
|
||
| /** | ||
| * Unique identifier for blobs uploaded outside of the summary. Attachment Blobs are uploaded and | ||
| * downloaded separately and do not take part of the snapshot payload. | ||
| * The id gets returned from the backend after the attachment has been uploaded. | ||
| * Additional information can be found here: https://github.com/microsoft/FluidFramework/issues/6374 | ||
|
There was a problem hiding this comment. This documentation on ISummaryAttachment is super useful to me even in its current state! #Resolved |
||
| * Ex. "id": "bQAQKARDdMdTgqICmBa_ZB86YXwGP" | ||
| */ | ||
| export interface ISummaryAttachment { | ||
| type: SummaryType.Attachment; | ||
| id: string; | ||
| } | ||
|
Comment on lines
104
to
105
There was a problem hiding this comment. What format is this in OR how do I get one from a IFluidHandle? Is it the absolute path? A json seralized handle? Something else? #Resolved There was a problem hiding this comment. Added an example, it is an id returned from the backend. There was a problem hiding this comment. This is not used so I am not really sure. I believe the idea is that There was a problem hiding this comment. I added an example that makes it easier to visualize. @navin, are you sure this is not used ? After all, we do write it :) Ex. ".blobs": { |
||
|
|
||
| /** | ||
| * Tree Node data structure with children that are nodes of SummaryObject type: | ||
| * Blob, Handle, Attachment or another Tree. | ||
| */ | ||
| export interface ISummaryTree { | ||
| type: SummaryType.Tree; | ||
|
|
||
|
|
||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Orthogonal to this PR - Interesting to note that
ISummaryAuthorandISummaryCommiterabove are never used. We may want to look into removing them. #ResolvedThere was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Tracking by #10456