diff --git a/common/lib/protocol-definitions/api-report/protocol-definitions.api.md b/common/lib/protocol-definitions/api-report/protocol-definitions.api.md index 6bf72d08d97c..9b138e645dbf 100644 --- a/common/lib/protocol-definitions/api-report/protocol-definitions.api.md +++ b/common/lib/protocol-definitions/api-report/protocol-definitions.api.md @@ -7,7 +7,7 @@ // @alpha export type ConnectionMode = "write" | "read"; -// @internal (undocumented) +// @alpha (undocumented) export enum FileMode { // (undocumented) Directory = "040000", @@ -30,13 +30,13 @@ export type IApprovedProposal = { approvalSequenceNumber: number; } & ISequencedProposal; -// @internal (undocumented) +// @alpha (undocumented) export interface IAttachment { // (undocumented) id: string; } -// @internal +// @alpha export interface IBlob { contents: string; encoding: "utf-8" | "base64"; @@ -381,7 +381,7 @@ export interface ISnapshotTreeEx extends ISnapshotTree { // @alpha export type IsoDate = string; -// @internal +// @alpha export interface ISummaryAck { handle: string; summaryProposal: ISummaryProposal; @@ -420,7 +420,7 @@ export interface ISummaryHandle { type: SummaryType.Handle; } -// @internal +// @alpha export interface ISummaryNack { code?: number; message?: string; @@ -428,7 +428,7 @@ export interface ISummaryNack { summaryProposal: ISummaryProposal; } -// @internal +// @alpha export interface ISummaryProposal { summarySequenceNumber: number; } @@ -484,7 +484,7 @@ export interface ITrace { timestamp: number; } -// @internal (undocumented) +// @alpha (undocumented) export interface ITree { // (undocumented) entries: ITreeEntry[]; @@ -492,7 +492,7 @@ export interface ITree { unreferenced?: true; } -// @internal +// @alpha export type ITreeEntry = { path: string; mode: FileMode; @@ -590,7 +590,7 @@ export type SummaryType = SummaryType.Attachment | SummaryType.Blob | SummaryTyp // @alpha export type SummaryTypeNoHandle = SummaryType.Tree | SummaryType.Blob | SummaryType.Attachment; -// @internal +// @alpha export enum TreeEntry { // (undocumented) Attachment = "Attachment", diff --git a/common/lib/protocol-definitions/src/protocol.ts b/common/lib/protocol-definitions/src/protocol.ts index 44f50df1f9eb..554c390e979b 100644 --- a/common/lib/protocol-definitions/src/protocol.ts +++ b/common/lib/protocol-definitions/src/protocol.ts @@ -437,7 +437,7 @@ export interface IServerError { /** * Data about the original proposed summary message. - * @internal + * @alpha */ export interface ISummaryProposal { /** @@ -448,7 +448,7 @@ export interface ISummaryProposal { /** * Contents of summary ack expected from the server. - * @internal + * @alpha */ export interface ISummaryAck { /** @@ -464,7 +464,7 @@ export interface ISummaryAck { /** * Contents of summary nack expected from the server. - * @internal + * @alpha */ export interface ISummaryNack { /** diff --git a/common/lib/protocol-definitions/src/storage.ts b/common/lib/protocol-definitions/src/storage.ts index e9ef7965a5fe..196c9f6a3d05 100644 --- a/common/lib/protocol-definitions/src/storage.ts +++ b/common/lib/protocol-definitions/src/storage.ts @@ -21,7 +21,7 @@ export interface IDocumentAttributes { } /** - * @internal + * @alpha */ export enum FileMode { File = "100644", @@ -32,7 +32,7 @@ export enum FileMode { /** * Raw blob stored within the tree. - * @internal + * @alpha */ export interface IBlob { /** @@ -47,7 +47,7 @@ export interface IBlob { } /** - * @internal + * @alpha */ export interface IAttachment { id: string; @@ -62,7 +62,7 @@ export interface ICreateBlobResponse { /** * A tree entry wraps a path with a type of node. - * @internal + * @alpha */ export type ITreeEntry = { /** @@ -92,7 +92,7 @@ export type ITreeEntry = { /** * Type of entries that can be stored in a tree. - * @internal + * @alpha */ export enum TreeEntry { Blob = "Blob", @@ -101,7 +101,7 @@ export enum TreeEntry { } /** - * @internal + * @alpha */ export interface ITree { entries: ITreeEntry[]; diff --git a/experimental/dds/tree2/api-report/tree2.api.md b/experimental/dds/tree2/api-report/tree2.api.md index 518e93b9e635..50272171e065 100644 --- a/experimental/dds/tree2/api-report/tree2.api.md +++ b/experimental/dds/tree2/api-report/tree2.api.md @@ -452,6 +452,7 @@ export interface FieldAnchor { interface FieldChanges { // @deprecated readonly build?: readonly DetachedNodeBuild[]; + // @deprecated readonly destroy?: readonly DetachedNodeDestruction[]; readonly global?: readonly DetachedNodeChanges[]; readonly local?: readonly Mark[]; @@ -1585,6 +1586,7 @@ export enum RevertResult { // @alpha interface Root { readonly build?: readonly DetachedNodeBuild[]; + readonly destroy?: readonly DetachedNodeDestruction[]; readonly fields?: FieldMap; } diff --git a/experimental/dds/tree2/src/core/tree/delta.ts b/experimental/dds/tree2/src/core/tree/delta.ts index de4fe504628a..a3c98a9c6d19 100644 --- a/experimental/dds/tree2/src/core/tree/delta.ts +++ b/experimental/dds/tree2/src/core/tree/delta.ts @@ -83,6 +83,15 @@ export interface Root { * then the build should be listed under ID A. */ readonly build?: readonly DetachedNodeBuild[]; + /** + * New detached nodes to be destroyed. + * The ordering has no significance. + * + * Destruction instructions for a root that is undergoing a rename should be listed under the final name. + * For example, if one wishes to destroy a tree which is being renamed from ID A to ID B, + * then the destruction should be listed under ID B. + */ + readonly destroy?: readonly DetachedNodeDestruction[]; } /** * The default representation for inserted content. @@ -225,9 +234,12 @@ export interface FieldChanges { */ readonly build?: readonly DetachedNodeBuild[]; /** - * New detached nodes to be constructed. + * New detached nodes to be destroyed. * The ordering has no significance. * + * @deprecated - Destroys should be set at the root. + * TODO:6308 migrate all reader/writers away from this and remove it. + * * Destruction instructions for a root that is undergoing a rename should be listed under the final name. * For example, if one wishes to destroy a tree which is being renamed from ID A to ID B, * then the destruction should be listed under ID B. diff --git a/experimental/dds/tree2/src/core/tree/visitDelta.ts b/experimental/dds/tree2/src/core/tree/visitDelta.ts index d11b8aecc4af..d1df9f75b109 100644 --- a/experimental/dds/tree2/src/core/tree/visitDelta.ts +++ b/experimental/dds/tree2/src/core/tree/visitDelta.ts @@ -90,6 +90,7 @@ export function visitDelta( }; visitFieldMarks(delta.fields, visitor, attachConfig); fixedPointVisitOfRoots(visitor, attachPassRoots, attachConfig); + collectDestroys(delta.destroy, attachConfig); for (const { id, count } of rootDestructions) { for (let i = 0; i < count; i += 1) { const offsetId = offsetDetachId(id, i); @@ -355,9 +356,7 @@ function visitNode( */ function detachPass(delta: Delta.FieldChanges, visitor: DeltaVisitor, config: PassConfig): void { processBuilds(delta.build, config, visitor); - if (delta.destroy !== undefined) { - config.rootDestructions.push(...delta.destroy); - } + collectDestroys(delta.destroy, config); if (delta.global !== undefined) { for (const { id, fields } of delta.global) { const root = config.detachedFieldIndex.getEntry(id); @@ -419,6 +418,15 @@ function processBuilds( } } +function collectDestroys( + destroys: readonly Delta.DetachedNodeDestruction[] | undefined, + config: PassConfig, +) { + if (destroys !== undefined) { + config.rootDestructions.push(...destroys); + } +} + /** * Preforms the following: * - Executes attaches (top-down) applying nested changes on the attached nodes diff --git a/experimental/dds/tree2/src/feature-libraries/optional-field/optionalField.ts b/experimental/dds/tree2/src/feature-libraries/optional-field/optionalField.ts index 077536cd88c9..cbd32a7d52c9 100644 --- a/experimental/dds/tree2/src/feature-libraries/optional-field/optionalField.ts +++ b/experimental/dds/tree2/src/feature-libraries/optional-field/optionalField.ts @@ -250,7 +250,8 @@ export const optionalChangeRebaser: FieldChangeRebaser = { } for (const [id, childChange] of change.childChanges) { - const originalId = nextDstToSrc.get(withIntention(id)) ?? id; + const intentionedId = withIntention(id); + const originalId = current.dstToSrc.get(intentionedId) ?? intentionedId; const existingChanges = childChangesByOriginalId.get(originalId); const taggedChange = tagChange(childChange, revision); if (existingChanges === undefined) { @@ -278,7 +279,7 @@ export const optionalChangeRebaser: FieldChangeRebaser = { build: composedBuilds, moves: composedMoves, childChanges: Array.from(childChangesByOriginalId.entries(), ([id, childChanges]) => [ - current.srcToDst.get(id)?.[0] ?? id, + id, composeChild(childChanges), ]), }; @@ -306,7 +307,7 @@ export const optionalChangeRebaser: FieldChangeRebaser = { return { revision: id.revision ?? revision, localId: id.localId }; }; for (const [src, dst] of moves) { - invertIdMap.set(dst, src); + invertIdMap.set(src, dst); } let inverseFillsSelf = false; @@ -417,30 +418,14 @@ export const optionalChangeRebaser: FieldChangeRebaser = { const overChildChangesBySrc = new RegisterMap(); for (const [id, childChange] of overChange.childChanges ?? []) { - overChildChangesBySrc.set(overDstToSrc.get(withIntention(id)) ?? id, childChange); - } - - // Maps the content occupying a given register id in the output context of `change` to the register id - // that content occupies in the output context of the rebased change. - // This is necessary since child changes to nodes are keyed on the register they occupy in the output - // context of the changeset, and `change` might make child changes to content which it doesn't move, but - // `over` does. - const renamedDsts = new RegisterMap(); - for (const [_, dst] of moves) { - renamedDsts.set(dst, dst); - } - for (const [src, dst] of overSrcToDst.entries()) { - if (!renamedDsts.has(src)) { - renamedDsts.set(src, dst); - } + overChildChangesBySrc.set(withIntention(id) ?? id, childChange); } const rebasedChildChanges: typeof childChanges = []; for (const [id, childChange] of childChanges) { - const rebasedId = renamedDsts.get(id) ?? id; - // locate corresponding child change - const srcId = changeDstToSrc.get(id) ?? id; - const overChildChange = overChildChangesBySrc.get(srcId); + const overChildChange = overChildChangesBySrc.get(id); + + const rebasedId = overSrcToDst.get(id) ?? id; const rebasedChildChange = rebaseChild( childChange, overChildChange, @@ -568,15 +553,12 @@ export function optionalFieldIntoDelta( delta.build = builds; } - const dstToSrc = new RegisterMap(); - let markIsANoop = true; const mark: Mutable = { count: 1 }; if (change.moves.length > 0) { const renames: Delta.DetachedNodeRename[] = []; for (const [src, dst] of change.moves) { - dstToSrc.set(dst, src); if (src === "self" && dst !== "self") { mark.detach = { major: dst.revision ?? revision, minor: dst.localId }; markIsANoop = false; @@ -600,12 +582,11 @@ export function optionalFieldIntoDelta( if (change.childChanges.length > 0) { const globals: Delta.DetachedNodeChanges[] = []; for (const [id, childChange] of change.childChanges) { - const srcId = dstToSrc.get(id) ?? id; const childDelta = deltaFromChild(childChange); - if (srcId !== "self") { + if (id !== "self") { const fields = childDelta; globals.push({ - id: { major: srcId.revision ?? revision, minor: srcId.localId }, + id: { major: id.revision ?? revision, minor: id.localId }, fields, }); } else { diff --git a/experimental/dds/tree2/src/feature-libraries/optional-field/optionalFieldChangeTypes.ts b/experimental/dds/tree2/src/feature-libraries/optional-field/optionalFieldChangeTypes.ts index 4a9730741fe2..a94435ea6f6c 100644 --- a/experimental/dds/tree2/src/feature-libraries/optional-field/optionalFieldChangeTypes.ts +++ b/experimental/dds/tree2/src/feature-libraries/optional-field/optionalFieldChangeTypes.ts @@ -47,9 +47,7 @@ export interface OptionalChangeset { /** * Nested changes to nodes that occupy registers. * - * Nodes are identified by the register they occupy in the *output* context of the changeset. - * Note that this is different from the delta format. - * Switching this to be consistent is tracked by AB#6296. + * Nodes are identified by the register they occupy in the *input* context of the changeset. */ childChanges: [register: RegisterId, childChange: NodeChangeset][]; diff --git a/experimental/dds/tree2/src/simple-tree/proxies.ts b/experimental/dds/tree2/src/simple-tree/proxies.ts index 1004d2526fc0..e60619fdebe8 100644 --- a/experimental/dds/tree2/src/simple-tree/proxies.ts +++ b/experimental/dds/tree2/src/simple-tree/proxies.ts @@ -1095,8 +1095,6 @@ function extractContentIfProxy(input: T): { } const classKind = content instanceof NodeBase ? getNodeKind(content) : undefined; - // TODO: This checking could be made stronger by using `class-tree/Tree.schema(content).kind` - // to get the type when `content` is a proxy. At the moment, importing `Tree.schema` causes a cycle. let type: "object" | "list" | "map" | "leaf"; if (isFluidHandle(content)) { type = "leaf"; diff --git a/experimental/dds/tree2/src/test/feature-libraries/default-field-kinds/defaultFieldKinds.spec.ts b/experimental/dds/tree2/src/test/feature-libraries/default-field-kinds/defaultFieldKinds.spec.ts index 051ddb6e241a..725a001e26e6 100644 --- a/experimental/dds/tree2/src/test/feature-libraries/default-field-kinds/defaultFieldKinds.spec.ts +++ b/experimental/dds/tree2/src/test/feature-libraries/default-field-kinds/defaultFieldKinds.spec.ts @@ -105,7 +105,7 @@ describe("defaultFieldKinds", () => { [{ localId: brand(41) }, "self", "nodeTargeting"], ["self", { localId: brand(1) }, "cellTargeting"], ], - childChanges: [["self", nodeChange1]], + childChanges: [[{ localId: brand(41) }, nodeChange1]], }; /** @@ -167,7 +167,9 @@ describe("defaultFieldKinds", () => { "cellTargeting", ], ], - childChanges: [["self", nodeChange1]], + childChanges: [ + [{ localId: brand(41), revision: change1.revision }, nodeChange1], + ], }; const actual = fieldHandler.rebaser.compose( [change1, taggedChildChange1], @@ -206,9 +208,7 @@ describe("defaultFieldKinds", () => { "cellTargeting", ], ], - childChanges: [ - [{ revision: change1.revision, localId: brand(1) }, nodeChange1], - ], + childChanges: [["self", nodeChange1]], }; assertEqual(makeAnonChange(actual), makeAnonChange(expected2)); }); @@ -260,9 +260,7 @@ describe("defaultFieldKinds", () => { "cellTargeting", ], ], - childChanges: [ - [{ localId: brand(41), revision: taggedChange.revision }, nodeChange2], - ], + childChanges: [["self", nodeChange2]], }), ); }); diff --git a/experimental/dds/tree2/src/test/feature-libraries/optional-field/optionalField.spec.ts b/experimental/dds/tree2/src/test/feature-libraries/optional-field/optionalField.spec.ts index af7324d594ff..cc3ea8c82e99 100644 --- a/experimental/dds/tree2/src/test/feature-libraries/optional-field/optionalField.spec.ts +++ b/experimental/dds/tree2/src/test/feature-libraries/optional-field/optionalField.spec.ts @@ -97,7 +97,7 @@ const change1: TaggedChange = tagChange( { build: [{ id: { localId: brand(41) }, set: testTree("tree1") }], moves: [[{ localId: brand(41) }, "self", "nodeTargeting"]], - childChanges: [["self", nodeChange1]], + childChanges: [[{ localId: brand(41) }, nodeChange1]], reservedDetachId: { localId: brand(1) }, }, tag, @@ -185,7 +185,7 @@ describe("optionalField", () => { ], [{ localId: brand(42), revision: change2.revision }, "self", "nodeTargeting"], ], - childChanges: [[{ localId: brand(2), revision: change2.revision }, nodeChange1]], + childChanges: [[{ localId: brand(41), revision: change1.revision }, nodeChange1]], reservedDetachId: { localId: brand(1), revision: change1.revision }, }; @@ -203,7 +203,9 @@ describe("optionalField", () => { moves: [ [{ localId: brand(41), revision: change1.revision }, "self", "nodeTargeting"], ], - childChanges: [["self", arbitraryChildChange]], + childChanges: [ + [{ localId: brand(41), revision: change1.revision }, arbitraryChildChange], + ], reservedDetachId: { localId: brand(1), revision: change1.revision }, }; @@ -236,7 +238,7 @@ describe("optionalField", () => { moves: [ ["self", { localId: brand(41), revision: change1.revision }, "cellTargeting"], ], - childChanges: [[{ localId: brand(41), revision: change1.revision }, nodeChange2]], + childChanges: [["self", nodeChange2]], }; assert.deepEqual( @@ -367,7 +369,7 @@ describe("optionalField", () => { const baseChange: OptionalChangeset = { build: [], moves: [["self", { localId: brand(0) }, "cellTargeting"]], - childChanges: [[{ localId: brand(0) }, nodeChange1]], + childChanges: [["self", nodeChange1]], }; const taggedBaseChange = tagChange(baseChange, mintRevisionTag()); @@ -381,7 +383,7 @@ describe("optionalField", () => { [{ localId: brand(41) }, "self", "nodeTargeting"], ["self", { localId: brand(1) }, "cellTargeting"], ], - childChanges: [[{ localId: brand(1) }, nodeChange2]], + childChanges: [["self", nodeChange2]], }; const childRebaser = ( @@ -397,15 +399,13 @@ describe("optionalField", () => { build: [ { id: { localId: brand(41) }, set: { type: brand("value"), value: "X" } }, ], - // TODO:AB#6298: This test case demonstrates a problem with rebasing transactions: - // we don't realize that { localId: brand(1) } no longer refers to the right node - // because we rebased over a change that detaches that node. We either need to augment - // this with a move from { localId: brand(0), revision: taggedBaseChange.revision } => { localId: brand(1) } - // OR update the child change here to refer to { localId: brand(0), revision: taggedBaseChange.revision }! - // Right now we do things inconsistently with 'self' due to how renamedDsts works in optional field, which causes this bug. moves: [[{ localId: brand(41) }, "self", "nodeTargeting"]], - childChanges: [[{ localId: brand(1) }, arbitraryChildChange]], - // See comment above: this may need to change as well. + childChanges: [ + [ + { localId: brand(0), revision: taggedBaseChange.revision }, + arbitraryChildChange, + ], + ], reservedDetachId: { localId: brand(1) }, }; diff --git a/experimental/dds/tree2/src/test/snapshots/files/optional-field-scenarios-final.json b/experimental/dds/tree2/src/test/snapshots/files/optional-field-scenarios-final.json new file mode 100644 index 000000000000..01304acb9b4d --- /dev/null +++ b/experimental/dds/tree2/src/test/snapshots/files/optional-field-scenarios-final.json @@ -0,0 +1,721 @@ +{ + "type": "tree", + "tree": { + "type": "tree", + "indexes": { + "type": "tree", + "entries": [ + { + "type": "tree", + "EditManager": { + "type": "tree", + "tree": { + "type": "blob", + "String": { + "type": "blob", + "content": { + "trunk": [ + { + "change": { + "changes": [ + { + "fieldKey": "rootFieldKey", + "fieldKind": "ModularEditBuilder.Generic", + "change": [ + { + "index": 0, + "nodeChange": { + "fieldChanges": [ + { + "fieldKey": "root 1 child", + "fieldKind": "Optional", + "change": { + "b": [ + [ + { + "localId": 1 + }, + { + "type": "com.fluidframework.leaf.number", + "value": 40 + } + ] + ], + "m": [ + [ + { + "localId": 1 + }, + 0, + true + ] + ], + "d": { + "localId": 2 + } + } + } + ] + } + } + ] + } + ] + }, + "revision": "beefbeef-beef-4000-8000-000000000006", + "sequenceNumber": 4, + "sessionId": "beefbeef-beef-4000-8000-000000000002" + }, + { + "change": { + "changes": [ + { + "fieldKey": "rootFieldKey", + "fieldKind": "Optional", + "change": { + "b": [ + [ + { + "localId": 4 + }, + { + "type": "optional-field.TestNode", + "fields": { + "root 2 child": [ + { + "type": "com.fluidframework.leaf.number", + "value": 41 + } + ] + } + } + ] + ], + "m": [ + [ + { + "localId": 4 + }, + 0, + true + ], + [ + 0, + { + "localId": 5 + }, + false + ] + ] + } + } + ] + }, + "revision": "beefbeef-beef-4000-8000-000000000007", + "sequenceNumber": 5, + "sessionId": "beefbeef-beef-4000-8000-000000000002" + }, + { + "change": { + "changes": [ + { + "fieldKey": "rootFieldKey", + "fieldKind": "Optional", + "change": { + "b": [ + [ + { + "localId": 4 + }, + { + "type": "optional-field.TestNode" + } + ] + ], + "m": [ + [ + { + "localId": 4 + }, + 0, + true + ], + [ + 0, + { + "localId": 5 + }, + false + ] + ], + "c": [ + [ + { + "revision": "beefbeef-beef-4000-8000-000000000007", + "localId": 5 + }, + { + "fieldChanges": [ + { + "fieldKey": "root 1 child", + "fieldKind": "Optional", + "change": { + "b": [ + [ + { + "localId": 1 + }, + { + "type": "com.fluidframework.leaf.number", + "value": 42 + } + ] + ], + "m": [ + [ + { + "localId": 1 + }, + 0, + true + ], + [ + 0, + { + "localId": 2 + }, + false + ] + ] + } + } + ] + } + ], + [ + { + "localId": 4 + }, + { + "fieldChanges": [ + { + "fieldKey": "root 3 child", + "fieldKind": "Optional", + "change": { + "b": [ + [ + { + "localId": 7 + }, + { + "type": "com.fluidframework.leaf.number", + "value": 43 + } + ] + ], + "m": [ + [ + { + "localId": 7 + }, + 0, + true + ] + ], + "d": { + "localId": 8 + } + } + } + ] + } + ] + ] + } + } + ] + }, + "revision": "beefbeef-beef-4000-8000-00000000000b", + "sequenceNumber": 6, + "sessionId": "beefbeef-beef-4000-8000-000000000001" + }, + { + "change": { + "changes": [ + { + "fieldKey": "rootFieldKey", + "fieldKind": "Optional", + "change": { + "c": [ + [ + 0, + { + "fieldChanges": [ + { + "fieldKey": "root 3 child", + "fieldKind": "Optional", + "change": { + "b": [ + [ + { + "localId": 1 + }, + { + "type": "com.fluidframework.leaf.number", + "value": 44 + } + ] + ], + "m": [ + [ + { + "localId": 1 + }, + 0, + true + ], + [ + 0, + { + "localId": 2 + }, + false + ] + ] + } + } + ] + } + ] + ] + } + } + ] + }, + "revision": "beefbeef-beef-4000-8000-00000000000c", + "sequenceNumber": 7, + "sessionId": "beefbeef-beef-4000-8000-000000000001" + } + ], + "branches": [ + [ + "beefbeef-beef-4000-8000-000000000002", + { + "base": "beefbeef-beef-4000-8000-000000000007", + "commits": [] + } + ] + ] + }, + "encoding": "utf-8" + } + } + } + }, + { + "type": "tree", + "Schema": { + "type": "tree", + "tree": { + "type": "blob", + "SchemaString": { + "type": "blob", + "content": { + "version": "1.0.0", + "nodeSchema": [ + { + "name": "com.fluidframework.leaf.boolean", + "objectNodeFields": [], + "leafValue": 2 + }, + { + "name": "com.fluidframework.leaf.handle", + "objectNodeFields": [], + "leafValue": 3 + }, + { + "name": "com.fluidframework.leaf.null", + "objectNodeFields": [], + "leafValue": 4 + }, + { + "name": "com.fluidframework.leaf.number", + "objectNodeFields": [], + "leafValue": 0 + }, + { + "name": "com.fluidframework.leaf.string", + "objectNodeFields": [], + "leafValue": 1 + }, + { + "name": "optional-field.TestNode", + "mapFields": { + "kind": "Optional", + "types": [ + "com.fluidframework.leaf.handle", + "com.fluidframework.leaf.null", + "com.fluidframework.leaf.number", + "com.fluidframework.leaf.boolean", + "com.fluidframework.leaf.string" + ] + }, + "objectNodeFields": [] + } + ], + "rootFieldSchema": { + "kind": "Optional", + "types": [ + "optional-field.TestNode" + ] + } + }, + "encoding": "utf-8" + } + } + } + }, + { + "type": "tree", + "Forest": { + "type": "tree", + "tree": { + "type": "blob", + "ForestTree": { + "type": "blob", + "content": { + "version": 1, + "data": [ + [ + "rootFieldKey", + { + "version": 1, + "identifiers": [], + "shapes": [ + { + "c": { + "extraFields": 1, + "fields": [] + } + }, + { + "a": 0 + } + ], + "data": [ + 1, + [ + "optional-field.TestNode", + false, + [ + "root 3 child", + [ + "com.fluidframework.leaf.number", + true, + 44, + [] + ] + ] + ] + ] + } + ], + [ + "repair-6", + { + "version": 1, + "identifiers": [], + "shapes": [ + { + "c": { + "extraFields": 1, + "fields": [] + } + }, + { + "a": 0 + } + ], + "data": [ + 1, + [ + "com.fluidframework.leaf.number", + true, + 43, + [] + ] + ] + } + ], + [ + "repair-7", + { + "version": 1, + "identifiers": [], + "shapes": [ + { + "c": { + "extraFields": 1, + "fields": [] + } + }, + { + "a": 0 + } + ], + "data": [ + 1, + [ + "optional-field.TestNode", + false, + [] + ] + ] + } + ], + [ + "repair-8", + { + "version": 1, + "identifiers": [], + "shapes": [ + { + "c": { + "extraFields": 1, + "fields": [] + } + }, + { + "a": 0 + } + ], + "data": [ + 1, + [ + "com.fluidframework.leaf.number", + true, + 43, + [] + ] + ] + } + ], + [ + "repair-9", + { + "version": 1, + "identifiers": [], + "shapes": [ + { + "c": { + "extraFields": 1, + "fields": [] + } + }, + { + "a": 0 + } + ], + "data": [ + 1, + [ + "com.fluidframework.leaf.number", + true, + 44, + [] + ] + ] + } + ], + [ + "repair-11", + { + "version": 1, + "identifiers": [], + "shapes": [ + { + "c": { + "extraFields": 1, + "fields": [] + } + }, + { + "a": 0 + } + ], + "data": [ + 1, + [ + "com.fluidframework.leaf.number", + true, + 42, + [] + ] + ] + } + ], + [ + "repair-12", + { + "version": 1, + "identifiers": [], + "shapes": [ + { + "c": { + "extraFields": 1, + "fields": [] + } + }, + { + "a": 0 + } + ], + "data": [ + 1, + [ + "com.fluidframework.leaf.number", + true, + 40, + [] + ] + ] + } + ], + [ + "repair-14", + { + "version": 1, + "identifiers": [], + "shapes": [ + { + "c": { + "extraFields": 1, + "fields": [] + } + }, + { + "a": 0 + } + ], + "data": [ + 1, + [ + "optional-field.TestNode", + false, + [ + "root 1 child", + [ + "com.fluidframework.leaf.number", + true, + 42, + [] + ] + ] + ] + ] + } + ], + [ + "repair-15", + { + "version": 1, + "identifiers": [], + "shapes": [ + { + "c": { + "extraFields": 1, + "fields": [] + } + }, + { + "a": 0 + } + ], + "data": [ + 1, + [ + "optional-field.TestNode", + false, + [ + "root 2 child", + [ + "com.fluidframework.leaf.number", + true, + 41, + [] + ] + ] + ] + ] + } + ] + ] + }, + "encoding": "utf-8" + } + } + } + }, + { + "type": "tree", + "DetachedFieldIndex": { + "type": "tree", + "tree": { + "type": "blob", + "DetachedFieldIndexBlob": { + "type": "blob", + "content": { + "version": 1, + "data": [ + [ + "beefbeef-beef-4000-8000-00000000000b", + 4, + 7 + ], + [ + "beefbeef-beef-4000-8000-00000000000b", + 7, + 8 + ], + [ + "beefbeef-beef-4000-8000-00000000000b", + 1, + 11 + ], + [ + "beefbeef-beef-4000-8000-00000000000b", + 2, + 12 + ], + [ + "beefbeef-beef-4000-8000-00000000000b", + 5, + 15 + ], + [ + "beefbeef-beef-4000-8000-00000000000c", + 2, + 6 + ], + [ + "beefbeef-beef-4000-8000-00000000000c", + 1, + 9 + ], + [ + "beefbeef-beef-4000-8000-000000000007", + 5, + 14 + ] + ], + "maxId": 15 + }, + "encoding": "utf-8" + } + } + } + } + ] + } + } +} \ No newline at end of file diff --git a/experimental/dds/tree2/src/test/snapshots/testTrees.ts b/experimental/dds/tree2/src/test/snapshots/testTrees.ts index 00478d34bde8..6be0b73888f5 100644 --- a/experimental/dds/tree2/src/test/snapshots/testTrees.ts +++ b/experimental/dds/tree2/src/test/snapshots/testTrees.ts @@ -18,6 +18,8 @@ import { TreeFieldSchema, TreeCompressionStrategy, cursorForJsonableTreeNode, + cursorForTypedTreeData, + TreeNodeSchema, } from "../../feature-libraries"; import { typeboxValidator } from "../../external-utilities"; import { @@ -29,8 +31,25 @@ import { remove, wrongSchema, } from "../utils"; -import { AllowedUpdateType, FieldKey, JsonableTree, UpPath, rootFieldKey } from "../../core"; +import { + AllowedUpdateType, + FieldKey, + FieldUpPath, + ITreeCursorSynchronous, + JsonableTree, + UpPath, + rootFieldKey, +} from "../../core"; import { leaf, SchemaBuilder } from "../../domains"; +// eslint-disable-next-line import/no-internal-modules +import { TypedNode } from "../../feature-libraries/schema-aware"; + +const rootField: FieldUpPath = { parent: undefined, field: rootFieldKey }; +const rootNode: UpPath = { + parent: undefined, + parentField: rootFieldKey, + parentIndex: 0, +}; const factory = new SharedTreeFactory({ jsonValidator: typeboxValidator, @@ -199,6 +218,69 @@ export function generateTestTrees() { await takeSnapshot(provider.trees[1], "tree-1-final"); }, }, + { + /** + * Aims to exercise interesting scenarios that can happen within an optional field with respect to + * EditManager's persisted format. + */ + name: "optional-field-scenarios", + runScenario: async (takeSnapshot) => { + const innerBuilder = new SchemaBuilder({ + scope: "optional-field", + libraries: [leaf.library], + }); + const testNode = innerBuilder.map("TestNode", leaf.all); + const docSchema = innerBuilder.intoSchema(SchemaBuilder.optional(testNode)); + + const config = { + allowedSchemaModifications: AllowedUpdateType.None, + schema: docSchema, + initialTree: undefined, + } as const; + + // Enables below editing code to be slightly less verbose + const makeCursor = ( + schema: T, + data: TypedNode, + ): ITreeCursorSynchronous => + cursorForTypedTreeData({ schema: docSchema }, schema, data); + + const provider = new TestTreeProviderLite(2); + const tree = provider.trees[0].schematizeInternal(config); + const view = tree.checkout; + view.editor.optionalField(rootField).set(makeCursor(testNode, {}), true); + provider.processMessages(); + const view2 = provider.trees[1].schematizeInternal(config).checkout; + + view2.editor + .optionalField({ parent: rootNode, field: brand("root 1 child") }) + .set(makeCursor(leaf.number, 40), true); + view2.editor + .optionalField(rootField) + .set(makeCursor(testNode, { "root 2 child": 41 }), false); + + // Transaction with a root and child change + runSynchronous(view, () => { + view.editor + .optionalField({ parent: rootNode, field: brand("root 1 child") }) + .set(makeCursor(leaf.number, 42), true); + view.editor.optionalField(rootField).set(makeCursor(testNode, {}), false); + view.editor + .optionalField({ parent: rootNode, field: brand("root 3 child") }) + .set(makeCursor(leaf.number, 43), true); + }); + + view.editor + .optionalField({ parent: rootNode, field: brand("root 3 child") }) + .set(cursorForTypedTreeData({ schema: docSchema }, leaf.number, 44), false); + + provider.processMessages(); + + // EditManager snapshot should involve information about rebasing tree1's edits (a transaction with root & child changes) + // over tree2's edits (a root change and a child change outside of the transaction). + await takeSnapshot(provider.trees[0], "final"); + }, + }, { name: "competing-deletes", runScenario: async (takeSnapshot) => { diff --git a/experimental/dds/tree2/src/test/tree/visitDelta.spec.ts b/experimental/dds/tree2/src/test/tree/visitDelta.spec.ts index ed235d358c73..66dcc2392a61 100644 --- a/experimental/dds/tree2/src/test/tree/visitDelta.spec.ts +++ b/experimental/dds/tree2/src/test/tree/visitDelta.spec.ts @@ -442,7 +442,21 @@ describe("visitDelta", () => { testTreeVisit(delta, expected, index); assert.equal(index.entries().next().done, true); }); - it("build-rename-destroy", () => { + it("destroy (root level)", () => { + const index = makeDetachedFieldIndex(""); + const id = { minor: 42 }; + index.createEntry(id, 2); + const delta: Delta.Root = { + destroy: [{ id, count: 2 }], + }; + const expected: VisitScript = [ + ["destroy", field0, 1], + ["destroy", field1, 1], + ]; + testVisit(delta, expected, index); + assert.equal(index.entries().next().done, true); + }); + it("build-rename-destroy (field level)", () => { const index = makeDetachedFieldIndex(""); const buildId = { minor: 42 }; const detachId = { minor: 43 }; diff --git a/packages/common/client-utils/api-report/client-utils.api.md b/packages/common/client-utils/api-report/client-utils.api.md index db506a8aeaeb..f5163ad85317 100644 --- a/packages/common/client-utils/api-report/client-utils.api.md +++ b/packages/common/client-utils/api-report/client-utils.api.md @@ -26,7 +26,7 @@ export { Buffer_2 as Buffer } // @internal export const bufferToString: (blob: ArrayBufferLike, encoding: "utf8" | "utf-8" | "base64") => string; -// @internal +// @alpha export type EventEmitterEventType = EventEmitter extends { on(event: infer E, listener: any): any; } ? E : never; @@ -97,7 +97,7 @@ export class Trace { trace(): ITraceEvent; } -// @internal +// @alpha export class TypedEventEmitter extends EventEmitter implements IEventProvider { constructor(); // (undocumented) @@ -116,7 +116,7 @@ export class TypedEventEmitter extends EventEmitter implements IEventPro readonly removeListener: TypedEventTransform; } -// @internal (undocumented) +// @alpha (undocumented) export type TypedEventTransform = TransformedEvent void) => void>> & IEventTransformer & TransformedEvent; // @internal diff --git a/packages/common/client-utils/src/typedEventEmitter.ts b/packages/common/client-utils/src/typedEventEmitter.ts index 4a6fcd9e2d2f..046bddee9650 100644 --- a/packages/common/client-utils/src/typedEventEmitter.ts +++ b/packages/common/client-utils/src/typedEventEmitter.ts @@ -19,7 +19,7 @@ import { * * This type allow us to correctly handle either type * - * @internal + * @alpha */ // eslint-disable-next-line @typescript-eslint/no-explicit-any export type EventEmitterEventType = EventEmitter extends { on(event: infer E, listener: any) } @@ -27,7 +27,7 @@ export type EventEmitterEventType = EventEmitter extends { on(event: infer E, li : never; /** - * @internal + * @alpha */ export type TypedEventTransform = // Event emitter supports some special events for the emitter itself to use @@ -49,7 +49,7 @@ export type TypedEventTransform = /** * Event Emitter helper class the supports emitting typed events * - * @internal + * @alpha */ export class TypedEventEmitter extends EventEmitter diff --git a/packages/common/core-interfaces/api-report/core-interfaces.api.md b/packages/common/core-interfaces/api-report/core-interfaces.api.md index e0b8dbeab51b..e83c6f1475e3 100644 --- a/packages/common/core-interfaces/api-report/core-interfaces.api.md +++ b/packages/common/core-interfaces/api-report/core-interfaces.api.md @@ -27,7 +27,7 @@ export type FluidObject = { [P in FluidObjectProviderKeys]?: T[P]; }; -// @internal +// @alpha export type FluidObjectKeys = keyof FluidObject; // @alpha @@ -251,10 +251,10 @@ export interface IFluidCodeDetailsConfig { readonly [key: string]: string; } -// @internal (undocumented) +// @alpha (undocumented) export const IFluidHandle: keyof IProvideFluidHandle; -// @internal +// @alpha export interface IFluidHandle extends IProvideFluidHandle { // @deprecated (undocumented) readonly absolutePath: string; @@ -266,10 +266,10 @@ export interface IFluidHandle extends IProvide readonly isAttached: boolean; } -// @internal (undocumented) +// @alpha (undocumented) export const IFluidHandleContext: keyof IProvideFluidHandleContext; -// @internal +// @alpha export interface IFluidHandleContext extends IProvideFluidHandleContext { readonly absolutePath: string; attachGraph(): void; @@ -279,10 +279,10 @@ export interface IFluidHandleContext extends IProvideFluidHandleContext { readonly routeContext?: IFluidHandleContext; } -// @internal (undocumented) +// @alpha (undocumented) export const IFluidLoadable: keyof IProvideFluidLoadable; -// @internal +// @alpha export interface IFluidLoadable extends IProvideFluidLoadable { // (undocumented) handle: IFluidHandle; @@ -334,19 +334,19 @@ export interface IProvideFluidCodeDetailsComparer { readonly IFluidCodeDetailsComparer: IFluidCodeDetailsComparer; } -// @internal (undocumented) +// @alpha (undocumented) export interface IProvideFluidHandle { // (undocumented) readonly IFluidHandle: IFluidHandle; } -// @internal (undocumented) +// @alpha (undocumented) export interface IProvideFluidHandleContext { // (undocumented) readonly IFluidHandleContext: IFluidHandleContext; } -// @internal (undocumented) +// @alpha (undocumented) export interface IProvideFluidLoadable { // (undocumented) readonly IFluidLoadable: IFluidLoadable; diff --git a/packages/common/core-interfaces/src/fluidLoadable.ts b/packages/common/core-interfaces/src/fluidLoadable.ts index d595e6cba38b..151949d3b558 100644 --- a/packages/common/core-interfaces/src/fluidLoadable.ts +++ b/packages/common/core-interfaces/src/fluidLoadable.ts @@ -6,19 +6,19 @@ import { IFluidHandle } from "./handles"; /** - * @internal + * @alpha */ export const IFluidLoadable: keyof IProvideFluidLoadable = "IFluidLoadable"; /** - * @internal + * @alpha */ export interface IProvideFluidLoadable { readonly IFluidLoadable: IFluidLoadable; } /** * A shared FluidObject has a URL from which it can be referenced - * @internal + * @alpha */ export interface IFluidLoadable extends IProvideFluidLoadable { // Handle to the loadable FluidObject diff --git a/packages/common/core-interfaces/src/handles.ts b/packages/common/core-interfaces/src/handles.ts index 4a61792ac1fe..0423241fe3fb 100644 --- a/packages/common/core-interfaces/src/handles.ts +++ b/packages/common/core-interfaces/src/handles.ts @@ -8,12 +8,12 @@ import { IFluidLoadable } from "./fluidLoadable"; import { FluidObject } from "./provider"; /** - * @internal + * @alpha */ export const IFluidHandleContext: keyof IProvideFluidHandleContext = "IFluidHandleContext"; /** - * @internal + * @alpha */ export interface IProvideFluidHandleContext { readonly IFluidHandleContext: IFluidHandleContext; @@ -21,7 +21,7 @@ export interface IProvideFluidHandleContext { /** * Describes a routing context from which other `IFluidHandleContext`s are defined. - * @internal + * @alpha */ export interface IFluidHandleContext extends IProvideFluidHandleContext { /** @@ -49,12 +49,12 @@ export interface IFluidHandleContext extends IProvideFluidHandleContext { } /** - * @internal + * @alpha */ export const IFluidHandle: keyof IProvideFluidHandle = "IFluidHandle"; /** - * @internal + * @alpha */ export interface IProvideFluidHandle { readonly IFluidHandle: IFluidHandle; @@ -62,7 +62,7 @@ export interface IProvideFluidHandle { /** * Handle to a shared {@link FluidObject}. - * @internal + * @alpha */ export interface IFluidHandle< // REVIEW: Constrain `T` to something? How do we support dds and datastores safely? diff --git a/packages/common/core-interfaces/src/provider.ts b/packages/common/core-interfaces/src/provider.ts index 7b45cfaf6623..0caf98946eb7 100644 --- a/packages/common/core-interfaces/src/provider.ts +++ b/packages/common/core-interfaces/src/provider.ts @@ -83,6 +83,6 @@ export type FluidObject = { * See {@link FluidObject} * * For example `FluidObjectKeys` would result in `"IFoo" | "IBar"` - * @internal + * @alpha */ export type FluidObjectKeys = keyof FluidObject; diff --git a/packages/dds/merge-tree/api-report/merge-tree.api.md b/packages/dds/merge-tree/api-report/merge-tree.api.md index 169dab92bfba..3dbbdd0392fb 100644 --- a/packages/dds/merge-tree/api-report/merge-tree.api.md +++ b/packages/dds/merge-tree/api-report/merge-tree.api.md @@ -195,13 +195,10 @@ export class CollaborationWindow { clientId: number; // (undocumented) collaborating: boolean; - // (undocumented) currentSeq: number; // (undocumented) loadFrom(a: CollaborationWindow): void; - // (undocumented) localSeq: number; - // (undocumented) minSeq: number; } diff --git a/packages/dds/merge-tree/src/mergeTreeNodes.ts b/packages/dds/merge-tree/src/mergeTreeNodes.ts index f5601b5a09c1..ebf032cc95f4 100644 --- a/packages/dds/merge-tree/src/mergeTreeNodes.ts +++ b/packages/dds/merge-tree/src/mergeTreeNodes.ts @@ -246,8 +246,11 @@ export interface ISegment extends IMergeNodeCommon, Partial, Parti */ propertyManager?: PropertiesManager; /** - * Local seq at which this segment was inserted. If this is defined, `seq` will be UnassignedSequenceNumber. + * Local seq at which this segment was inserted. + * This is defined if and only if the insertion of the segment is pending ack, i.e. `seq` is UnassignedSequenceNumber. * Once the segment is acked, this field is cleared. + * + * See {@link CollaborationWindow.localSeq} for more information on the semantics of localSeq. */ localSeq?: number; /** @@ -255,7 +258,8 @@ export interface ISegment extends IMergeNodeCommon, Partial, Parti * UnassignedSequenceNumber. However, if another client concurrently removes the same segment, `removedSeq` * will be updated to the seq at which that client removed this segment. * - * Like `localSeq`, this field is cleared once the local removal of the segment is acked. + * Like {@link ISegment.localSeq}, this field is cleared once the local removal of the segment is acked. + * See {@link CollaborationWindow.localSeq} for more information on the semantics of localSeq. */ localRemovedSeq?: number; /** @@ -792,12 +796,79 @@ export class Marker extends BaseSegment implements ReferencePosition, ISegment { export class CollaborationWindow { clientId = LocalClientId; collaborating = false; - // Lowest-numbered segment in window; no client can reference a state before this one + + /** + * Lowest-numbered segment in window; no client can reference a state before this one + */ minSeq = 0; - // Highest-numbered segment in window and current - // reference segment for this client + /** + * Highest-numbered segment in window and current reference sequence number for this client. + */ currentSeq = 0; + /** + * Highest-numbered localSeq used for a pending segment. + * Semantically, `localSeq`s provide an ordering on in-flight merge-tree operations: + * for operations stamped with localSeqs `a` and `b`, `a < b` if and only if `a` was submitted before `b`. + * + * @remarks - This field is analogous to the `clientSequenceNumber` field on ops, but it's accessible to merge-tree + * at op submission time rather than only at ack time. This enables more natural state tracking for in-flight ops. + * + * It's useful to stamp ops with such an incrementing counter because it enables reasoning about which segments existed from + * the perspective of the local client at a given point in 'un-acked' time, which is necessary to support the reconnect flow. + * + * For example, imagine a client with initial state "123456" submits some ops to create the text "123456ABC". + * If they insert the "C" first, then "B", then "A", their local segment state might look like this: + * ```js + * [ + * { seq: 0, text: "1234" }, + * { seq: 5, text: "56" }, + * { localSeq: 3, seq: UnassignedSequenceNumber, text: "A" }, + * { localSeq: 2, seq: UnassignedSequenceNumber, text: "B" }, + * { localSeq: 1, seq: UnassignedSequenceNumber, text: "C" }, + * ] + * ``` + * (note that {@link ISegment.localSeq} tracks the localSeq at which a segment was inserted) + * + * Suppose the client then disconnects and reconnects before any of its insertions are acked. The reconnect flow will necessitate + * that the client regenerates and resubmits ops based on its current segment state as well as the original op that was sent. + * + * It will generate the ops + * 1. \{ pos: 6, text: "C" \} + * 2. \{ pos: 6, text: "B" \} + * 3. \{ pos: 6, text: "A" \} + * + * since when submitting the first op, remote clients don't know that this client is about to submit the "A" and "B". + * + * On the other hand, imagine if the client had originally submitted the ops in the order "A", "B", "C" + * such that the segments' local state was instead: + * + * ```js + * [ + * { seq: 0, text: "1234" }, + * { seq: 5, text: "56" }, + * { localSeq: 1, seq: UnassignedSequenceNumber, text: "A" }, + * { localSeq: 2, seq: UnassignedSequenceNumber, text: "B" }, + * { localSeq: 3, seq: UnassignedSequenceNumber, text: "C" }, + * ] + * ``` + * + * The resubmitted ops should instead be: + * 1. \{ pos: 6, text: "A" \} + * 2. \{ pos: 7, text: "B" \} + * 3. \{ pos: 8, text: "C" \} + * + * since remote clients will have seen the "A" when processing the "B" as well as both the "A" and "B" when processing the "C". + * As can be seen, the list of resubmitted ops is different in the two cases despite the merge-tree's segment state only differing + * in `localSeq`. + * + * This example is a bit simplified from the general scenario: since no remote clients modified the merge-tree while the client + * was disconnected, the resubmitted ops end up matching the original ops exactly. + * However, this is not generally true: the production reconnect code takes into account visibility of segments based on both acked + * and local information as appropriate. + * Nonetheless, this simple scenario is enough to understand why it's useful to be able to determine if a segment should be visible + * from a given (seq, localSeq) perspective. + */ localSeq = 0; loadFrom(a: CollaborationWindow) { diff --git a/packages/runtime/container-runtime-definitions/api-report/container-runtime-definitions.api.md b/packages/runtime/container-runtime-definitions/api-report/container-runtime-definitions.api.md index 23ff6b3185f6..17485b270f48 100644 --- a/packages/runtime/container-runtime-definitions/api-report/container-runtime-definitions.api.md +++ b/packages/runtime/container-runtime-definitions/api-report/container-runtime-definitions.api.md @@ -23,7 +23,7 @@ import { IRequest } from '@fluidframework/core-interfaces'; import { IResponse } from '@fluidframework/core-interfaces'; import { ISequencedDocumentMessage } from '@fluidframework/protocol-definitions'; -// @internal +// @alpha export interface IContainerRuntime extends IProvideFluidDataStoreRegistry, IContainerRuntimeBaseWithCombinedEvents { readonly attachState: AttachState; // (undocumented) @@ -48,10 +48,10 @@ export interface IContainerRuntime extends IProvideFluidDataStoreRegistry, ICont readonly storage: IDocumentStorageService; } -// @internal (undocumented) +// @alpha (undocumented) export type IContainerRuntimeBaseWithCombinedEvents = IContainerRuntimeBase & IEventProvider; -// @internal +// @alpha export interface IContainerRuntimeEvents extends IContainerRuntimeBaseEvents { // (undocumented) (event: "dirty" | "disconnected" | "dispose" | "saved" | "attached", listener: () => void): any; @@ -59,7 +59,7 @@ export interface IContainerRuntimeEvents extends IContainerRuntimeBaseEvents { (event: "connected", listener: (clientId: string) => void): any; } -// @internal @deprecated (undocumented) +// @alpha @deprecated (undocumented) export interface IContainerRuntimeWithResolveHandle_Deprecated extends IContainerRuntime { // (undocumented) readonly IFluidHandleContext: IFluidHandleContext; diff --git a/packages/runtime/container-runtime-definitions/src/containerRuntime.ts b/packages/runtime/container-runtime-definitions/src/containerRuntime.ts index 453f05d9dd9e..b8c0adf5394c 100644 --- a/packages/runtime/container-runtime-definitions/src/containerRuntime.ts +++ b/packages/runtime/container-runtime-definitions/src/containerRuntime.ts @@ -28,7 +28,7 @@ import { /** * @deprecated Will be removed in future major release. Migrate all usage of IFluidRouter to the "entryPoint" pattern. Refer to Removing-IFluidRouter.md - * @internal + * @alpha */ export interface IContainerRuntimeWithResolveHandle_Deprecated extends IContainerRuntime { readonly IFluidHandleContext: IFluidHandleContext; @@ -37,7 +37,7 @@ export interface IContainerRuntimeWithResolveHandle_Deprecated extends IContaine /** * Events emitted by {@link IContainerRuntime}. - * @internal + * @alpha */ export interface IContainerRuntimeEvents extends IContainerRuntimeBaseEvents { (event: "dirty" | "disconnected" | "dispose" | "saved" | "attached", listener: () => void); @@ -45,14 +45,14 @@ export interface IContainerRuntimeEvents extends IContainerRuntimeBaseEvents { } /** - * @internal + * @alpha */ export type IContainerRuntimeBaseWithCombinedEvents = IContainerRuntimeBase & IEventProvider; /** * Represents the runtime of the container. Contains helper functions/state of the container. - * @internal + * @alpha */ export interface IContainerRuntime extends IProvideFluidDataStoreRegistry, diff --git a/packages/runtime/container-runtime/api-report/container-runtime.api.md b/packages/runtime/container-runtime/api-report/container-runtime.api.md index c9ce030c4f1e..1a813b32abf4 100644 --- a/packages/runtime/container-runtime/api-report/container-runtime.api.md +++ b/packages/runtime/container-runtime/api-report/container-runtime.api.md @@ -70,7 +70,7 @@ export type CompatModeBehavior = /** Fail processing immediately. (The container will close) */ | "FailToProcess"; -// @internal +// @alpha export enum CompressionAlgorithms { // (undocumented) lz4 = "lz4" @@ -93,7 +93,7 @@ export enum ContainerMessageType { Rejoin = "rejoin" } -// @internal +// @alpha export class ContainerRuntime extends TypedEventEmitter implements IContainerRuntime, IRuntime, ISummarizerRuntime, ISummarizerInternalsProvider, IProvideFluidHandleContext { protected constructor(context: IContainerContext, registry: IFluidDataStoreRegistry, metadata: IContainerRuntimeMetadata | undefined, electedSummarizerData: ISerializedElection | undefined, chunks: [string, string[]][], dataStoreAliasMap: [string, string][], runtimeOptions: Readonly>, containerScope: FluidObject, logger: ITelemetryLoggerExt, existing: boolean, blobManagerSnapshot: IBlobManagerLoadInfo, _storage: IDocumentStorageService, idCompressor: (IIdCompressor & IIdCompressorCore) | undefined, provideEntryPoint: (containerRuntime: IContainerRuntime) => Promise, requestHandler?: ((request: IRequest, runtime: IContainerRuntime) => Promise) | undefined, summaryConfiguration?: ISummaryConfiguration); // (undocumented) @@ -230,7 +230,7 @@ export interface ContainerRuntimeMessage { // @internal (undocumented) export const DefaultSummaryConfiguration: ISummaryConfiguration; -// @internal (undocumented) +// @alpha (undocumented) export type EnqueueSummarizeResult = (ISummarizeResults & { readonly alreadyEnqueued?: undefined; }) | (ISummarizeResults & { @@ -250,13 +250,13 @@ export class FluidDataStoreRegistry implements IFluidDataStoreRegistry { get IFluidDataStoreRegistry(): this; } -// @internal (undocumented) +// @alpha (undocumented) export interface GCFeatureMatrix { sweepGeneration?: number; tombstoneGeneration?: number; } -// @internal +// @alpha export const GCNodeType: { DataStore: string; SubDataStore: string; @@ -264,10 +264,10 @@ export const GCNodeType: { Other: string; }; -// @internal (undocumented) +// @alpha (undocumented) export type GCNodeType = (typeof GCNodeType)[keyof typeof GCNodeType]; -// @internal (undocumented) +// @alpha (undocumented) export type GCVersion = number; // @internal @@ -281,7 +281,7 @@ export interface IAckedSummary { readonly summaryOp: ISummaryOpMessage; } -// @internal (undocumented) +// @alpha (undocumented) export interface IAckSummaryResult { // (undocumented) readonly ackNackDuration: number; @@ -289,7 +289,7 @@ export interface IAckSummaryResult { readonly summaryAckOp: ISummaryAckMessage; } -// @internal +// @alpha export interface IBaseSummarizeResult { readonly error: any; // (undocumented) @@ -299,7 +299,7 @@ export interface IBaseSummarizeResult { readonly stage: "base"; } -// @internal +// @alpha export interface IBlobManagerLoadInfo { // (undocumented) ids?: string[]; @@ -307,7 +307,7 @@ export interface IBlobManagerLoadInfo { redirectTable?: [string, string][]; } -// @internal (undocumented) +// @alpha (undocumented) export interface IBroadcastSummaryResult { // (undocumented) readonly broadcastDuration: number; @@ -321,7 +321,7 @@ export interface ICancellableSummarizerController extends ISummaryCancellationTo stop(reason: SummarizerStopReason): void; } -// @internal +// @alpha export interface ICancellationToken { readonly cancelled: boolean; readonly waitCancelled: Promise; @@ -351,13 +351,13 @@ export interface IClientSummaryWatcher extends IDisposable { watchSummary(clientSequenceNumber: number): ISummary; } -// @internal +// @alpha export interface ICompressionRuntimeOptions { readonly compressionAlgorithm: CompressionAlgorithms; readonly minimumBatchSizeInBytes: number; } -// @internal (undocumented) +// @alpha (undocumented) export interface IConnectableRuntime { // (undocumented) readonly clientId: string | undefined; @@ -374,7 +374,7 @@ export interface IContainerRuntimeMessageCompatDetails { behavior: CompatModeBehavior; } -// @internal (undocumented) +// @alpha (undocumented) export interface IContainerRuntimeMetadata extends ICreateContainerMetadata, IGCMetadata { readonly disableIsolatedChannels?: true; readonly idCompressorEnabled?: boolean; @@ -385,7 +385,7 @@ export interface IContainerRuntimeMetadata extends ICreateContainerMetadata, IGC readonly telemetryDocumentId?: string; } -// @internal +// @alpha export interface IContainerRuntimeOptions { readonly chunkSizeInBytes?: number; readonly compressionOptions?: ICompressionRuntimeOptions; @@ -401,19 +401,19 @@ export interface IContainerRuntimeOptions { readonly summaryOptions?: ISummaryRuntimeOptions; } -// @internal (undocumented) +// @alpha (undocumented) export interface ICreateContainerMetadata { createContainerRuntimeVersion?: string; createContainerTimestamp?: number; } -// @internal +// @alpha export interface IEnqueueSummarizeOptions extends IOnDemandSummarizeOptions { readonly afterSequenceNumber?: number; readonly override?: boolean; } -// @internal (undocumented) +// @alpha (undocumented) export interface IGCMetadata { readonly gcFeature?: GCVersion; readonly gcFeatureMatrix?: GCFeatureMatrix; @@ -423,7 +423,7 @@ export interface IGCMetadata { readonly sweepTimeoutMs?: number; } -// @internal (undocumented) +// @alpha (undocumented) export interface IGCRuntimeOptions { [key: string]: any; disableGC?: boolean; @@ -432,11 +432,11 @@ export interface IGCRuntimeOptions { sessionExpiryTimeoutMs?: number; } -// @internal +// @alpha export interface IGCStats extends IMarkPhaseStats, ISweepPhaseStats { } -// @internal +// @alpha export interface IGeneratedSummaryStats extends ISummaryStats { readonly dataStoreCount: number; readonly gcBlobNodeCount?: number; @@ -446,7 +446,7 @@ export interface IGeneratedSummaryStats extends ISummaryStats { readonly summaryNumber: number; } -// @internal +// @alpha export interface IGenerateSummaryTreeResult extends Omit { readonly forcedFullTree: boolean; readonly generateDuration: number; @@ -456,7 +456,7 @@ export interface IGenerateSummaryTreeResult extends Omit { readonly clientSequenceNumber: number; // (undocumented) @@ -520,14 +520,14 @@ export interface ISubmitSummaryOpResult extends Omit { summarizeOnDemand(options: IOnDemandSummarizeOptions): ISummarizeResults; } -// @internal (undocumented) +// @alpha (undocumented) export interface ISummarizeResults { readonly receivedSummaryAckOrNack: Promise>; readonly summaryOpBroadcasted: Promise>; readonly summarySubmitted: Promise>; } -// @internal (undocumented) +// @alpha (undocumented) export interface ISummarizerEvents extends IEvent { // (undocumented) (event: "summarize", listener: (props: ISummarizeEventProps) => void): any; } -// @internal (undocumented) +// @alpha (undocumented) export interface ISummarizerInternalsProvider { refreshLatestSummaryAck(options: IRefreshSummaryAckOptions): Promise; submitSummary(options: ISubmitSummaryOptions): Promise; } -// @internal (undocumented) +// @alpha (undocumented) export interface ISummarizerRuntime extends IConnectableRuntime { // (undocumented) closeFn(): void; @@ -615,7 +615,7 @@ export interface ISummary { waitBroadcast(): Promise; } -// @internal +// @alpha export interface ISummaryAckMessage extends ISequencedDocumentMessage { // (undocumented) contents: ISummaryAck; @@ -623,14 +623,14 @@ export interface ISummaryAckMessage extends ISequencedDocumentMessage { type: MessageType.SummaryAck; } -// @internal (undocumented) +// @alpha (undocumented) export interface ISummaryBaseConfiguration { initialSummarizerDelayMs: number; maxAckWaitTime: number; maxOpsSinceLastSummary: number; } -// @internal +// @alpha export type ISummaryCancellationToken = ICancellationToken; // @internal (undocumented) @@ -639,22 +639,22 @@ export interface ISummaryCollectionOpEvents extends IEvent { (event: OpActionEventName, listener: OpActionEventListener): any; } -// @internal (undocumented) +// @alpha (undocumented) export type ISummaryConfiguration = ISummaryConfigurationDisableSummarizer | ISummaryConfigurationDisableHeuristics | ISummaryConfigurationHeuristics; -// @internal (undocumented) +// @alpha (undocumented) export interface ISummaryConfigurationDisableHeuristics extends ISummaryBaseConfiguration { // (undocumented) state: "disableHeuristics"; } -// @internal (undocumented) +// @alpha (undocumented) export interface ISummaryConfigurationDisableSummarizer { // (undocumented) state: "disabled"; } -// @internal (undocumented) +// @alpha (undocumented) export interface ISummaryConfigurationHeuristics extends ISummaryBaseConfiguration { maxIdleTime: number; maxOps: number; @@ -668,10 +668,10 @@ export interface ISummaryConfigurationHeuristics extends ISummaryBaseConfigurati state: "enabled"; } -// @internal +// @alpha export type ISummaryMetadataMessage = Pick; -// @internal +// @alpha export interface ISummaryNackMessage extends ISequencedDocumentMessage { // (undocumented) contents: ISummaryNack; @@ -679,7 +679,7 @@ export interface ISummaryNackMessage extends ISequencedDocumentMessage { type: MessageType.SummaryNack; } -// @internal +// @alpha export interface ISummaryOpMessage extends ISequencedDocumentMessage { // (undocumented) contents: ISummaryContent; @@ -687,14 +687,14 @@ export interface ISummaryOpMessage extends ISequencedDocumentMessage { type: MessageType.Summarize; } -// @internal (undocumented) +// @alpha (undocumented) export interface ISummaryRuntimeOptions { // @deprecated initialSummarizerDelayMs?: number; summaryConfigOverrides?: ISummaryConfiguration; } -// @internal +// @alpha export interface ISweepPhaseStats { deletedAttachmentBlobCount: number; deletedDataStoreCount: number; @@ -704,7 +704,7 @@ export interface ISweepPhaseStats { lifetimeNodeCount: number; } -// @internal +// @alpha export interface IUploadSummaryResult extends Omit { readonly handle: string; // (undocumented) @@ -750,13 +750,13 @@ export enum RuntimeMessage { Rejoin = "rejoin" } -// @internal +// @alpha export interface SubmitSummaryFailureData extends IRetriableFailureResult { // (undocumented) stage: SummaryStage; } -// @internal +// @alpha export type SubmitSummaryResult = IBaseSummarizeResult | IGenerateSummaryTreeResult | IUploadSummaryResult | ISubmitSummaryOpResult; // @internal @@ -783,7 +783,7 @@ export class Summarizer extends TypedEventEmitter implements readonly summaryCollection: SummaryCollection; } -// @internal (undocumented) +// @alpha (undocumented) export type SummarizeResultPart = { success: true; data: TSuccess; @@ -794,7 +794,7 @@ export type SummarizeResultPart = { error: any; }; -// @internal (undocumented) +// @alpha (undocumented) export type SummarizerStopReason = /** Summarizer client failed to summarize in all 3 consecutive attempts. */ "failToSummarize" @@ -845,7 +845,7 @@ export class SummaryCollection extends TypedEventEmitter; } -// @internal +// @alpha export type SummaryStage = SubmitSummaryResult["stage"] | "unknown"; // @internal diff --git a/packages/runtime/container-runtime/src/blobManager.ts b/packages/runtime/container-runtime/src/blobManager.ts index 2c7b9255541e..932be279fca9 100644 --- a/packages/runtime/container-runtime/src/blobManager.ts +++ b/packages/runtime/container-runtime/src/blobManager.ts @@ -85,7 +85,7 @@ export class BlobHandle implements IFluidHandle { /** * Information from a snapshot needed to load BlobManager - * @internal + * @alpha */ export interface IBlobManagerLoadInfo { ids?: string[]; diff --git a/packages/runtime/container-runtime/src/containerRuntime.ts b/packages/runtime/container-runtime/src/containerRuntime.ts index 07285c3c9c1f..af2f2599305a 100644 --- a/packages/runtime/container-runtime/src/containerRuntime.ts +++ b/packages/runtime/container-runtime/src/containerRuntime.ts @@ -211,7 +211,7 @@ function compatBehaviorAllowsMessageType( } /** - * @internal + * @alpha */ export interface ISummaryBaseConfiguration { /** @@ -233,7 +233,7 @@ export interface ISummaryBaseConfiguration { } /** - * @internal + * @alpha */ export interface ISummaryConfigurationHeuristics extends ISummaryBaseConfiguration { state: "enabled"; @@ -296,21 +296,21 @@ export interface ISummaryConfigurationHeuristics extends ISummaryBaseConfigurati } /** - * @internal + * @alpha */ export interface ISummaryConfigurationDisableSummarizer { state: "disabled"; } /** - * @internal + * @alpha */ export interface ISummaryConfigurationDisableHeuristics extends ISummaryBaseConfiguration { state: "disableHeuristics"; } /** - * @internal + * @alpha */ export type ISummaryConfiguration = | ISummaryConfigurationDisableSummarizer @@ -347,7 +347,7 @@ export const DefaultSummaryConfiguration: ISummaryConfiguration = { }; /** - * @internal + * @alpha */ export interface ISummaryRuntimeOptions { /** Override summary configurations set by the server. */ @@ -364,7 +364,7 @@ export interface ISummaryRuntimeOptions { /** * Options for op compression. - * @internal + * @alpha */ export interface ICompressionRuntimeOptions { /** @@ -382,7 +382,7 @@ export interface ICompressionRuntimeOptions { /** * Options for container runtime. - * @internal + * @alpha */ export interface IContainerRuntimeOptions { readonly summaryOptions?: ISummaryRuntimeOptions; @@ -514,7 +514,7 @@ export const defaultRuntimeHeaderData: Required = { /** * Available compression algorithms for op compression. - * @internal + * @alpha */ export enum CompressionAlgorithms { lz4 = "lz4", @@ -710,7 +710,7 @@ async function createSummarizer(loader: ILoader, url: string): Promise diff --git a/packages/runtime/container-runtime/src/gc/gcDefinitions.ts b/packages/runtime/container-runtime/src/gc/gcDefinitions.ts index 7918061ae88b..6930ea3cbe7d 100644 --- a/packages/runtime/container-runtime/src/gc/gcDefinitions.ts +++ b/packages/runtime/container-runtime/src/gc/gcDefinitions.ts @@ -22,7 +22,7 @@ import { import { RuntimeHeaderData } from "../containerRuntime"; /** - * @internal + * @alpha */ export type GCVersion = number; @@ -92,7 +92,7 @@ export const defaultSessionExpiryDurationMs = 30 * oneDayMs; // 30 days /** * @see IGCMetadata.gcFeatureMatrix - * @internal + * @alpha */ export interface GCFeatureMatrix { /** @@ -110,7 +110,7 @@ export interface GCFeatureMatrix { } /** - * @internal + * @alpha */ export interface IGCMetadata { /** @@ -150,7 +150,7 @@ export interface IGCMetadata { /** * The statistics of the system state after a garbage collection mark phase run. - * @internal + * @alpha */ export interface IMarkPhaseStats { /** The number of nodes in the container. */ @@ -175,7 +175,7 @@ export interface IMarkPhaseStats { /** * The statistics of the system state after a garbage collection sweep phase run. - * @internal + * @alpha */ export interface ISweepPhaseStats { /** The number of nodes in the lifetime of the container. */ @@ -194,13 +194,13 @@ export interface ISweepPhaseStats { /** * The statistics of the system state after a garbage collection run. - * @internal + * @alpha */ export interface IGCStats extends IMarkPhaseStats, ISweepPhaseStats {} /** * The types of GC nodes in the GC reference graph. - * @internal + * @alpha */ export const GCNodeType = { // Nodes that are for data stores. @@ -214,7 +214,7 @@ export const GCNodeType = { }; /** - * @internal + * @alpha */ export type GCNodeType = (typeof GCNodeType)[keyof typeof GCNodeType]; @@ -320,7 +320,7 @@ export interface IGarbageCollectorCreateParams { } /** - * @internal + * @alpha */ export interface IGCRuntimeOptions { /** diff --git a/packages/runtime/container-runtime/src/summary/orderedClientElection.ts b/packages/runtime/container-runtime/src/summary/orderedClientElection.ts index 50283029b5a3..11a7d7b61700 100644 --- a/packages/runtime/container-runtime/src/summary/orderedClientElection.ts +++ b/packages/runtime/container-runtime/src/summary/orderedClientElection.ts @@ -227,7 +227,7 @@ export interface IOrderedClientElectionEvents extends IEvent { /** * Serialized state of IOrderedClientElection. - * @internal + * @alpha */ export interface ISerializedElection { /** Sequence number at the time of the latest election. */ diff --git a/packages/runtime/container-runtime/src/summary/summarizerTypes.ts b/packages/runtime/container-runtime/src/summary/summarizerTypes.ts index b8accbdb532c..887c2219f87c 100644 --- a/packages/runtime/container-runtime/src/summary/summarizerTypes.ts +++ b/packages/runtime/container-runtime/src/summary/summarizerTypes.ts @@ -19,7 +19,7 @@ import { SummarizeReason } from "./summaryGenerator"; /** * Similar to AbortSignal, but using promise instead of events * @param T - cancellation reason type - * @internal + * @alpha */ export interface ICancellationToken { /** Tells if this cancellable token is cancelled */ @@ -33,13 +33,13 @@ export interface ICancellationToken { /** * Similar to AbortSignal, but using promise instead of events - * @internal + * @alpha */ export type ISummaryCancellationToken = ICancellationToken; /** * Data required to update internal tracking state after receiving a Summary Ack. - * @internal + * @alpha */ export interface IRefreshSummaryAckOptions { /** Handle from the ack's summary op. */ @@ -53,7 +53,7 @@ export interface IRefreshSummaryAckOptions { } /** - * @internal + * @alpha */ export interface ISummarizerInternalsProvider { /** Encapsulates the work to walk the internals of the running container to generate a summary */ @@ -86,7 +86,7 @@ export interface ISummarizingWarning extends ContainerWarning { } /** - * @internal + * @alpha */ export interface IConnectableRuntime { readonly disposed: boolean; @@ -96,7 +96,7 @@ export interface IConnectableRuntime { } /** - * @internal + * @alpha */ export interface ISummarizerRuntime extends IConnectableRuntime { readonly logger: ITelemetryLoggerExt; @@ -117,7 +117,7 @@ export interface ISummarizerRuntime extends IConnectableRuntime { /** * Options affecting summarize behavior. - * @internal + * @alpha */ export interface ISummarizeOptions { /** True to generate the full tree with no handle reuse optimizations; defaults to false */ @@ -132,7 +132,7 @@ export interface ISummarizeOptions { } /** - * @internal + * @alpha */ export interface ISubmitSummaryOptions extends ISummarizeOptions { /** Logger to use for correlated summary events */ @@ -144,7 +144,7 @@ export interface ISubmitSummaryOptions extends ISummarizeOptions { } /** - * @internal + * @alpha */ export interface IOnDemandSummarizeOptions extends ISummarizeOptions { /** Reason for generating summary. */ @@ -153,7 +153,7 @@ export interface IOnDemandSummarizeOptions extends ISummarizeOptions { /** * Options to use when enqueueing a summarize attempt. - * @internal + * @alpha */ export interface IEnqueueSummarizeOptions extends IOnDemandSummarizeOptions { /** If specified, The summarize attempt will not occur until after this sequence number. */ @@ -171,7 +171,7 @@ export interface IEnqueueSummarizeOptions extends IOnDemandSummarizeOptions { /** * In addition to the normal summary tree + stats, this contains additional stats * only relevant at the root of the tree. - * @internal + * @alpha */ export interface IGeneratedSummaryStats extends ISummaryStats { /** The total number of data stores in the container. */ @@ -190,7 +190,7 @@ export interface IGeneratedSummaryStats extends ISummaryStats { /** * Base results for all submitSummary attempts. - * @internal + * @alpha */ export interface IBaseSummarizeResult { readonly stage: "base"; @@ -203,7 +203,7 @@ export interface IBaseSummarizeResult { /** * Results of submitSummary after generating the summary tree. - * @internal + * @alpha */ export interface IGenerateSummaryTreeResult extends Omit { readonly stage: "generate"; @@ -219,7 +219,7 @@ export interface IGenerateSummaryTreeResult extends Omit { readonly stage: "upload"; @@ -231,7 +231,7 @@ export interface IUploadSummaryResult extends Omit { readonly stage: "submit"; @@ -256,7 +256,7 @@ export interface ISubmitSummaryOpResult extends Omit = | { @@ -326,7 +326,7 @@ export type SummarizeResultPart = }; /** - * @internal + * @alpha */ export interface ISummarizeResults { /** Resolves when we generate, upload, and submit the summary. */ @@ -342,7 +342,7 @@ export interface ISummarizeResults { } /** - * @internal + * @alpha */ export type EnqueueSummarizeResult = | (ISummarizeResults & { @@ -372,7 +372,7 @@ export type EnqueueSummarizeResult = }; /** - * @internal + * @alpha */ export type SummarizerStopReason = /** Summarizer client failed to summarize in all 3 consecutive attempts. */ @@ -401,7 +401,7 @@ export type SummarizerStopReason = | "latestSummaryStateStale"; /** - * @internal + * @alpha */ export interface ISummarizeEventProps { result: "success" | "failure" | "canceled"; @@ -411,7 +411,7 @@ export interface ISummarizeEventProps { } /** - * @internal + * @alpha */ export interface ISummarizerEvents extends IEvent { (event: "summarize", listener: (props: ISummarizeEventProps) => void); diff --git a/packages/runtime/container-runtime/src/summary/summaryCollection.ts b/packages/runtime/container-runtime/src/summary/summaryCollection.ts index ad48bf747a13..15d67fc74e68 100644 --- a/packages/runtime/container-runtime/src/summary/summaryCollection.ts +++ b/packages/runtime/container-runtime/src/summary/summaryCollection.ts @@ -19,7 +19,7 @@ import { /** * Interface for summary op messages with typed contents. - * @internal + * @alpha */ export interface ISummaryOpMessage extends ISequencedDocumentMessage { type: MessageType.Summarize; @@ -28,7 +28,7 @@ export interface ISummaryOpMessage extends ISequencedDocumentMessage { /** * Interface for summary ack messages with typed contents. - * @internal + * @alpha */ export interface ISummaryAckMessage extends ISequencedDocumentMessage { type: MessageType.SummaryAck; @@ -37,7 +37,7 @@ export interface ISummaryAckMessage extends ISequencedDocumentMessage { /** * Interface for summary nack messages with typed contents. - * @internal + * @alpha */ export interface ISummaryNackMessage extends ISequencedDocumentMessage { type: MessageType.SummaryNack; diff --git a/packages/runtime/container-runtime/src/summary/summaryFormat.ts b/packages/runtime/container-runtime/src/summary/summaryFormat.ts index a5ce2f30a1b1..019f03246ae2 100644 --- a/packages/runtime/container-runtime/src/summary/summaryFormat.ts +++ b/packages/runtime/container-runtime/src/summary/summaryFormat.ts @@ -86,7 +86,7 @@ export function hasIsolatedChannels(attributes: ReadFluidDataStoreAttributes): b } /** - * @internal + * @alpha */ export interface IContainerRuntimeMetadata extends ICreateContainerMetadata, IGCMetadata { readonly summaryFormatVersion: 1; @@ -103,7 +103,7 @@ export interface IContainerRuntimeMetadata extends ICreateContainerMetadata, IGC } /** - * @internal + * @alpha */ export interface ICreateContainerMetadata { /** Runtime version of the container when it was first created */ @@ -114,7 +114,7 @@ export interface ICreateContainerMetadata { /** * The properties of an ISequencedDocumentMessage to be stored in the metadata blob in summary. - * @internal + * @alpha */ export type ISummaryMetadataMessage = Pick< ISequencedDocumentMessage, diff --git a/packages/runtime/runtime-definitions/api-report/runtime-definitions.api.md b/packages/runtime/runtime-definitions/api-report/runtime-definitions.api.md index 9ff20ddfb224..5dff28dcba6e 100644 --- a/packages/runtime/runtime-definitions/api-report/runtime-definitions.api.md +++ b/packages/runtime/runtime-definitions/api-report/runtime-definitions.api.md @@ -30,7 +30,7 @@ import type { IUser } from '@fluidframework/protocol-definitions'; import { SummaryTree } from '@fluidframework/protocol-definitions'; import { TelemetryEventPropertyType } from '@fluidframework/core-interfaces'; -// @internal +// @alpha export type AliasResult = "Success" | "Conflict" | "AlreadyAliased"; // @internal @@ -48,11 +48,11 @@ export const blobCountPropertyName = "BlobCount"; // @internal (undocumented) export const channelsTreeName = ".channels"; -// @internal (undocumented) +// @alpha (undocumented) export type CreateChildSummarizerNodeFn = (summarizeInternal: SummarizeInternalFn, getGCDataFn: (fullGC?: boolean) => Promise, getBaseGCDetailsFn?: () => Promise) => ISummarizerNodeWithGC; -// @internal (undocumented) +// @alpha (undocumented) export type CreateChildSummarizerNodeParam = { type: CreateSummarizerNodeSource.FromSummary; } | { @@ -63,7 +63,7 @@ export type CreateChildSummarizerNodeParam = { type: CreateSummarizerNodeSource.Local; }; -// @internal (undocumented) +// @alpha (undocumented) export enum CreateSummarizerNodeSource { // (undocumented) FromAttach = 1, @@ -80,10 +80,10 @@ export interface DetachedAttributionKey { type: "detached"; } -// @internal +// @alpha export type FluidDataStoreRegistryEntry = Readonly>; -// @internal +// @alpha export enum FlushMode { Immediate = 0, TurnBased = 1 @@ -113,7 +113,7 @@ export interface IAttachMessage { type: string; } -// @internal +// @alpha export interface IContainerRuntimeBase extends IEventProvider { // (undocumented) readonly clientDetails: IClientDetails; @@ -132,7 +132,7 @@ export interface IContainerRuntimeBase extends IEventProvider>; } -// @internal (undocumented) +// @alpha (undocumented) export interface IContainerRuntimeBaseEvents extends IEvent { // (undocumented) (event: "batchBegin", listener: (op: ISequencedDocumentMessage) => void): any; @@ -144,13 +144,13 @@ export interface IContainerRuntimeBaseEvents extends IEvent { (event: "signal", listener: (message: IInboundSignalMessage, local: boolean) => void): any; } -// @internal +// @alpha export interface IDataStore { readonly entryPoint: IFluidHandle; trySetAlias(alias: string): Promise; } -// @internal +// @alpha export interface IdCreationRange { // (undocumented) readonly ids?: { @@ -168,14 +168,14 @@ export interface IEnvelope { contents: any; } -// @internal +// @alpha export interface IExperimentalIncrementalSummaryContext { latestSummarySequenceNumber: number; summaryPath: string; summarySequenceNumber: number; } -// @internal +// @alpha export interface IFluidDataStoreChannel extends IDisposable { // (undocumented) applyStashedOp(content: any): Promise; @@ -201,7 +201,7 @@ export interface IFluidDataStoreChannel extends IDisposable { readonly visibilityState: VisibilityState; } -// @internal +// @alpha export interface IFluidDataStoreContext extends IEventProvider, Partial, IProvideFluidHandleContext { addedGCOutboundReference?(srcHandle: IFluidHandle, outboundHandle: IFluidHandle): void; readonly attachState: AttachState; @@ -250,49 +250,49 @@ export interface IFluidDataStoreContext extends IEventProvider>; } -// @internal (undocumented) +// @alpha (undocumented) export interface IFluidDataStoreContextDetached extends IFluidDataStoreContext { attachRuntime(factory: IProvideFluidDataStoreFactory, dataStoreRuntime: IFluidDataStoreChannel): Promise; } -// @internal (undocumented) +// @alpha (undocumented) export interface IFluidDataStoreContextEvents extends IEvent { // (undocumented) (event: "attaching" | "attached", listener: () => void): any; } -// @internal (undocumented) +// @alpha (undocumented) export const IFluidDataStoreFactory: keyof IProvideFluidDataStoreFactory; -// @internal +// @alpha export interface IFluidDataStoreFactory extends IProvideFluidDataStoreFactory { instantiateDataStore(context: IFluidDataStoreContext, existing: boolean): Promise; type: string; } -// @internal (undocumented) +// @alpha (undocumented) export const IFluidDataStoreRegistry: keyof IProvideFluidDataStoreRegistry; -// @internal +// @alpha export interface IFluidDataStoreRegistry extends IProvideFluidDataStoreRegistry { // (undocumented) get(name: string): Promise; } -// @internal +// @alpha export interface IGarbageCollectionData { gcNodes: { [id: string]: string[]; }; } -// @internal +// @alpha export interface IGarbageCollectionDetailsBase { gcData?: IGarbageCollectionData; usedRoutes?: string[]; } -// @internal +// @alpha export interface IIdCompressor { decompress(id: SessionSpaceCompressedId): StableId; generateCompressedId(): SessionSpaceCompressedId; @@ -304,7 +304,7 @@ export interface IIdCompressor { tryRecompress(uncompressed: StableId): SessionSpaceCompressedId | undefined; } -// @internal (undocumented) +// @alpha (undocumented) export interface IIdCompressorCore { finalizeCreationRange(range: IdCreationRange): void; serialize(withSession: true): SerializedIdCompressorWithOngoingSession; @@ -312,7 +312,7 @@ export interface IIdCompressorCore { takeNextCreationRange(): IdCreationRange; } -// @internal +// @alpha export interface IInboundSignalMessage extends ISignalMessage { // (undocumented) type: string; @@ -323,13 +323,13 @@ export type InboundAttachMessage = Omit & { snapshot: IAttachMessage["snapshot"] | null; }; -// @internal (undocumented) +// @alpha (undocumented) export interface IProvideFluidDataStoreFactory { // (undocumented) readonly IFluidDataStoreFactory: IFluidDataStoreFactory; } -// @internal (undocumented) +// @alpha (undocumented) export interface IProvideFluidDataStoreRegistry { // (undocumented) readonly IFluidDataStoreRegistry: IFluidDataStoreRegistry; @@ -345,14 +345,14 @@ export interface ISignalEnvelope { }; } -// @internal +// @alpha export interface ISummarizeInternalResult extends ISummarizeResult { // (undocumented) id: string; pathPartsForChildren?: string[]; } -// @internal +// @alpha export interface ISummarizeResult { // (undocumented) stats: ISummaryStats; @@ -360,7 +360,7 @@ export interface ISummarizeResult { summary: SummaryTree; } -// @internal (undocumented) +// @alpha (undocumented) export interface ISummarizerNode { // (undocumented) createChild( @@ -378,18 +378,18 @@ export interface ISummarizerNode { updateBaseSummaryState(snapshot: ISnapshotTree): void; } -// @internal (undocumented) +// @alpha (undocumented) export interface ISummarizerNodeConfig { readonly canReuseHandle?: boolean; readonly throwOnFailure?: true; } -// @internal (undocumented) +// @alpha (undocumented) export interface ISummarizerNodeConfigWithGC extends ISummarizerNodeConfig { readonly gcDisabled?: boolean; } -// @internal +// @alpha export interface ISummarizerNodeWithGC extends ISummarizerNode { // (undocumented) createChild( @@ -406,7 +406,7 @@ export interface ISummarizerNodeWithGC extends ISummarizerNode { updateUsedRoutes(usedRoutes: string[]): void; } -// @internal +// @alpha export interface ISummaryStats { // (undocumented) blobNodeCount: number; @@ -420,13 +420,13 @@ export interface ISummaryStats { unreferencedBlobSize: number; } -// @internal +// @alpha export interface ISummaryTreeWithStats { stats: ISummaryStats; summary: ISummaryTree; } -// @internal +// @alpha export interface ITelemetryContext { get(prefix: string, property: string): TelemetryEventPropertyType; serialize(): string; @@ -440,10 +440,10 @@ export interface LocalAttributionKey { type: "local"; } -// @internal +// @alpha export type NamedFluidDataStoreRegistryEntries = Iterable; -// @internal +// @alpha export type NamedFluidDataStoreRegistryEntry = [string, Promise]; // @internal @@ -452,55 +452,55 @@ export interface OpAttributionKey { type: "op"; } -// @internal +// @alpha export type OpSpaceCompressedId = number & { readonly OpNormalized: "9209432d-a959-4df7-b2ad-767ead4dbcae"; }; -// @internal +// @alpha export type SerializedIdCompressor = string & { readonly _serializedIdCompressor: "8c73c57c-1cf4-4278-8915-6444cb4f6af5"; }; -// @internal +// @alpha export type SerializedIdCompressorWithNoSession = SerializedIdCompressor & { readonly _noLocalState: "3aa2e1e8-cc28-4ea7-bc1a-a11dc3f26dfb"; }; -// @internal +// @alpha export type SerializedIdCompressorWithOngoingSession = SerializedIdCompressor & { readonly _hasLocalState: "1281acae-6d14-47e7-bc92-71c8ee0819cb"; }; -// @internal +// @alpha export type SessionId = StableId & { readonly SessionId: "4498f850-e14e-4be9-8db0-89ec00997e58"; }; -// @internal +// @alpha export type SessionSpaceCompressedId = number & { readonly SessionUnique: "cea55054-6b82-4cbf-ad19-1fa645ea3b3e"; }; -// @internal +// @alpha export type StableId = string & { readonly StableId: "53172b0d-a3d5-41ea-bd75-b43839c97f5a"; }; -// @internal (undocumented) +// @alpha (undocumented) export type SummarizeInternalFn = (fullTree: boolean, trackState: boolean, telemetryContext?: ITelemetryContext, incrementalSummaryContext?: IExperimentalIncrementalSummaryContext) => Promise; // @internal (undocumented) export const totalBlobSizePropertyName = "TotalBlobSize"; -// @internal +// @alpha export const VisibilityState: { NotVisible: string; LocallyVisible: string; GloballyVisible: string; }; -// @internal (undocumented) +// @alpha (undocumented) export type VisibilityState = (typeof VisibilityState)[keyof typeof VisibilityState]; // (No @packageDocumentation comment for this package) diff --git a/packages/runtime/runtime-definitions/src/dataStoreContext.ts b/packages/runtime/runtime-definitions/src/dataStoreContext.ts index 6c649e10421e..ea2a524c4b91 100644 --- a/packages/runtime/runtime-definitions/src/dataStoreContext.ts +++ b/packages/runtime/runtime-definitions/src/dataStoreContext.ts @@ -43,7 +43,7 @@ import { IIdCompressor } from "./id-compressor"; /** * Runtime flush mode handling - * @internal + * @alpha */ export enum FlushMode { /** @@ -77,7 +77,7 @@ export enum FlushModeExperimental { /** * This tells the visibility state of a Fluid object. It basically tracks whether the object is not visible, visible * locally within the container only or visible globally to all clients. - * @internal + * @alpha */ export const VisibilityState = { /** @@ -104,12 +104,12 @@ export const VisibilityState = { GloballyVisible: "GloballyVisible", }; /** - * @internal + * @alpha */ export type VisibilityState = (typeof VisibilityState)[keyof typeof VisibilityState]; /** - * @internal + * @alpha */ export interface IContainerRuntimeBaseEvents extends IEvent { (event: "batchBegin", listener: (op: ISequencedDocumentMessage) => void); @@ -130,7 +130,7 @@ export interface IContainerRuntimeBaseEvents extends IEvent { * the `IContainerRuntime.getAliasedDataStoreEntryPoint` function. The current datastore should be discarded * and will be garbage collected. The current datastore cannot be aliased to a different value. * 'AlreadyAliased' - the datastore has already been previously bound to another alias name. - * @internal + * @alpha */ export type AliasResult = "Success" | "Conflict" | "AlreadyAliased"; @@ -139,7 +139,7 @@ export type AliasResult = "Success" | "Conflict" | "AlreadyAliased"; * - Handle to the data store's entryPoint * - Fluid router for the data store * - Can be assigned an alias - * @internal + * @alpha */ export interface IDataStore { /** @@ -162,7 +162,7 @@ export interface IDataStore { /** * A reduced set of functionality of IContainerRuntime that a data store context/data store runtime will need * TODO: this should be merged into IFluidDataStoreContext - * @internal + * @alpha */ export interface IContainerRuntimeBase extends IEventProvider { readonly logger: ITelemetryBaseLogger; @@ -231,7 +231,7 @@ export interface IContainerRuntimeBase extends IEventProvider ISummarizerNodeWithGC; /** - * @internal + * @alpha */ export interface IFluidDataStoreContextEvents extends IEvent { (event: "attaching" | "attached", listener: () => void); @@ -353,7 +353,7 @@ export interface IFluidDataStoreContextEvents extends IEvent { /** * Represents the context for the data store. It is used by the data store runtime to * get information and call functionality to the container. - * @internal + * @alpha */ export interface IFluidDataStoreContext extends IEventProvider, @@ -490,7 +490,7 @@ export interface IFluidDataStoreContext } /** - * @internal + * @alpha */ export interface IFluidDataStoreContextDetached extends IFluidDataStoreContext { /** diff --git a/packages/runtime/runtime-definitions/src/dataStoreFactory.ts b/packages/runtime/runtime-definitions/src/dataStoreFactory.ts index cf85eb4f6af8..d290906f7750 100644 --- a/packages/runtime/runtime-definitions/src/dataStoreFactory.ts +++ b/packages/runtime/runtime-definitions/src/dataStoreFactory.ts @@ -6,12 +6,12 @@ import { IFluidDataStoreContext, IFluidDataStoreChannel } from "./dataStoreContext"; /** - * @internal + * @alpha */ export const IFluidDataStoreFactory: keyof IProvideFluidDataStoreFactory = "IFluidDataStoreFactory"; /** - * @internal + * @alpha */ export interface IProvideFluidDataStoreFactory { readonly IFluidDataStoreFactory: IFluidDataStoreFactory; @@ -20,7 +20,7 @@ export interface IProvideFluidDataStoreFactory { /** * IFluidDataStoreFactory create data stores. It is associated with an identifier (its `type` member) * and usually provided to consumers using this mapping through a data store registry. - * @internal + * @alpha */ export interface IFluidDataStoreFactory extends IProvideFluidDataStoreFactory { /** diff --git a/packages/runtime/runtime-definitions/src/dataStoreRegistry.ts b/packages/runtime/runtime-definitions/src/dataStoreRegistry.ts index 796fd1adabab..d4e60b026c96 100644 --- a/packages/runtime/runtime-definitions/src/dataStoreRegistry.ts +++ b/packages/runtime/runtime-definitions/src/dataStoreRegistry.ts @@ -8,7 +8,7 @@ import { IProvideFluidDataStoreFactory } from "./dataStoreFactory"; /** * A single registry entry that may be used to create data stores * It has to have either factory or registry, or both. - * @internal + * @alpha */ export type FluidDataStoreRegistryEntry = Readonly< Partial @@ -16,23 +16,23 @@ export type FluidDataStoreRegistryEntry = Readonly< /** * An associated pair of an identifier and registry entry. Registry entries * may be dynamically loaded. - * @internal + * @alpha */ export type NamedFluidDataStoreRegistryEntry = [string, Promise]; /** * An iterable identifier/registry entry pair list - * @internal + * @alpha */ export type NamedFluidDataStoreRegistryEntries = Iterable; /** - * @internal + * @alpha */ export const IFluidDataStoreRegistry: keyof IProvideFluidDataStoreRegistry = "IFluidDataStoreRegistry"; /** - * @internal + * @alpha */ export interface IProvideFluidDataStoreRegistry { readonly IFluidDataStoreRegistry: IFluidDataStoreRegistry; @@ -41,7 +41,7 @@ export interface IProvideFluidDataStoreRegistry { /** * An association of identifiers to data store registry entries, where the * entries can be used to create data stores. - * @internal + * @alpha */ export interface IFluidDataStoreRegistry extends IProvideFluidDataStoreRegistry { get(name: string): Promise; diff --git a/packages/runtime/runtime-definitions/src/garbageCollection.ts b/packages/runtime/runtime-definitions/src/garbageCollection.ts index c4b9eb15e516..1fada196aa08 100644 --- a/packages/runtime/runtime-definitions/src/garbageCollection.ts +++ b/packages/runtime/runtime-definitions/src/garbageCollection.ts @@ -31,7 +31,7 @@ export const gcDeletedBlobKey = "__deletedNodes"; /** * Garbage collection data returned by nodes in a Container. * Used for running GC in the Container. - * @internal + * @alpha */ export interface IGarbageCollectionData { /** @@ -42,7 +42,7 @@ export interface IGarbageCollectionData { /** * GC details provided to each node during creation. - * @internal + * @alpha */ export interface IGarbageCollectionDetailsBase { /** diff --git a/packages/runtime/runtime-definitions/src/id-compressor/idCompressor.ts b/packages/runtime/runtime-definitions/src/id-compressor/idCompressor.ts index a986776a76b5..952e6cbf15be 100644 --- a/packages/runtime/runtime-definitions/src/id-compressor/idCompressor.ts +++ b/packages/runtime/runtime-definitions/src/id-compressor/idCompressor.ts @@ -11,7 +11,7 @@ import { } from "./persisted-types"; /** - * @internal + * @alpha */ export interface IIdCompressorCore { /** @@ -101,7 +101,7 @@ export interface IIdCompressorCore { * * These two spaces naturally define a rule: consumers of compressed IDs should use session-space IDs, but serialized forms such as ops * should use op-space IDs. - * @internal + * @alpha */ export interface IIdCompressor { localSessionId: SessionId; diff --git a/packages/runtime/runtime-definitions/src/id-compressor/identifiers.ts b/packages/runtime/runtime-definitions/src/id-compressor/identifiers.ts index d3472b714eb1..310f4af874a7 100644 --- a/packages/runtime/runtime-definitions/src/id-compressor/identifiers.ts +++ b/packages/runtime/runtime-definitions/src/id-compressor/identifiers.ts @@ -7,7 +7,7 @@ * A compressed ID that has been normalized into "session space" (see `IdCompressor` for more). * Consumer-facing APIs and data structures should use session-space IDs as their lifetime and equality is stable and tied to * the scope of the session (i.e. compressor) that produced them. - * @internal + * @alpha */ export type SessionSpaceCompressedId = number & { readonly SessionUnique: "cea55054-6b82-4cbf-ad19-1fa645ea3b3e"; @@ -17,7 +17,7 @@ export type SessionSpaceCompressedId = number & { * A compressed ID that has been normalized into "op space". * Serialized/persisted structures (e.g. ops) should use op-space IDs as a performance optimization, as they require less normalizing when * received by a remote client due to the fact that op space for a given compressor is session space for all other compressors. - * @internal + * @alpha */ export type OpSpaceCompressedId = number & { readonly OpNormalized: "9209432d-a959-4df7-b2ad-767ead4dbcae"; @@ -28,12 +28,12 @@ export type OpSpaceCompressedId = number & { * A 128-bit Universally Unique IDentifier. Represented here * with a string of the form xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, * where x is a lowercase hex digit. - * @internal + * @alpha */ export type StableId = string & { readonly StableId: "53172b0d-a3d5-41ea-bd75-b43839c97f5a" }; /** * A StableId which is suitable for use as a session identifier - * @internal + * @alpha */ export type SessionId = StableId & { readonly SessionId: "4498f850-e14e-4be9-8db0-89ec00997e58" }; diff --git a/packages/runtime/runtime-definitions/src/id-compressor/persisted-types/0.0.1.ts b/packages/runtime/runtime-definitions/src/id-compressor/persisted-types/0.0.1.ts index 1007cd6de706..843cedde711f 100644 --- a/packages/runtime/runtime-definitions/src/id-compressor/persisted-types/0.0.1.ts +++ b/packages/runtime/runtime-definitions/src/id-compressor/persisted-types/0.0.1.ts @@ -7,7 +7,7 @@ import type { SessionId } from "../identifiers"; /** * The serialized contents of an IdCompressor, suitable for persistence in a summary. - * @internal + * @alpha */ export type SerializedIdCompressor = string & { readonly _serializedIdCompressor: "8c73c57c-1cf4-4278-8915-6444cb4f6af5"; @@ -15,7 +15,7 @@ export type SerializedIdCompressor = string & { /** * The serialized contents of an IdCompressor, suitable for persistence in a summary. - * @internal + * @alpha */ export type SerializedIdCompressorWithNoSession = SerializedIdCompressor & { readonly _noLocalState: "3aa2e1e8-cc28-4ea7-bc1a-a11dc3f26dfb"; @@ -23,7 +23,7 @@ export type SerializedIdCompressorWithNoSession = SerializedIdCompressor & { /** * The serialized contents of an IdCompressor, suitable for persistence in a summary. - * @internal + * @alpha */ export type SerializedIdCompressorWithOngoingSession = SerializedIdCompressor & { readonly _hasLocalState: "1281acae-6d14-47e7-bc92-71c8ee0819cb"; @@ -33,7 +33,7 @@ export type SerializedIdCompressorWithOngoingSession = SerializedIdCompressor & * Data describing a range of session-local IDs (from a remote or local session). * * A range is composed of local IDs that were generated. - * @internal + * @alpha */ export interface IdCreationRange { readonly sessionId: SessionId; diff --git a/packages/runtime/runtime-definitions/src/protocol.ts b/packages/runtime/runtime-definitions/src/protocol.ts index 00a85a145743..fe5005d3cb92 100644 --- a/packages/runtime/runtime-definitions/src/protocol.ts +++ b/packages/runtime/runtime-definitions/src/protocol.ts @@ -46,7 +46,7 @@ export interface ISignalEnvelope { /** * Represents ISignalMessage with its type. - * @internal + * @alpha */ export interface IInboundSignalMessage extends ISignalMessage { type: string; diff --git a/packages/runtime/runtime-definitions/src/summary.ts b/packages/runtime/runtime-definitions/src/summary.ts index 8347fa8b9921..3b5fc79ec31d 100644 --- a/packages/runtime/runtime-definitions/src/summary.ts +++ b/packages/runtime/runtime-definitions/src/summary.ts @@ -15,7 +15,7 @@ import { IGarbageCollectionData, IGarbageCollectionDetailsBase } from "./garbage /** * Contains the aggregation data from a Tree/Subtree. - * @internal + * @alpha */ export interface ISummaryStats { treeNodeCount: number; @@ -31,7 +31,7 @@ export interface ISummaryStats { * each of its DDS. * Any component that implements IChannelContext, IFluidDataStoreChannel or extends SharedObject * will be taking part of the summarization process. - * @internal + * @alpha */ export interface ISummaryTreeWithStats { /** @@ -47,7 +47,7 @@ export interface ISummaryTreeWithStats { /** * Represents a summary at a current sequence number. - * @internal + * @alpha */ export interface ISummarizeResult { stats: ISummaryStats; @@ -68,7 +68,7 @@ export interface ISummarizeResult { * ... * "path1": * ``` - * @internal + * @alpha */ export interface ISummarizeInternalResult extends ISummarizeResult { id: string; @@ -81,7 +81,7 @@ export interface ISummarizeInternalResult extends ISummarizeResult { /** * @experimental - Can be deleted/changed at any time * Contains the necessary information to allow DDSes to do incremental summaries - * @internal + * @alpha */ export interface IExperimentalIncrementalSummaryContext { /** @@ -107,7 +107,7 @@ export interface IExperimentalIncrementalSummaryContext { } /** - * @internal + * @alpha */ export type SummarizeInternalFn = ( fullTree: boolean, @@ -117,7 +117,7 @@ export type SummarizeInternalFn = ( ) => Promise; /** - * @internal + * @alpha */ export interface ISummarizerNodeConfig { /** @@ -138,7 +138,7 @@ export interface ISummarizerNodeConfig { } /** - * @internal + * @alpha */ export interface ISummarizerNodeConfigWithGC extends ISummarizerNodeConfig { /** @@ -149,7 +149,7 @@ export interface ISummarizerNodeConfigWithGC extends ISummarizerNodeConfig { } /** - * @internal + * @alpha */ export enum CreateSummarizerNodeSource { FromSummary, @@ -157,7 +157,7 @@ export enum CreateSummarizerNodeSource { Local, } /** - * @internal + * @alpha */ export type CreateChildSummarizerNodeParam = | { @@ -173,7 +173,7 @@ export type CreateChildSummarizerNodeParam = }; /** - * @internal + * @alpha */ export interface ISummarizerNode { /** @@ -263,7 +263,7 @@ export interface ISummarizerNode { * `isReferenced`: This tells whether this node is referenced in the document or not. * * `updateUsedRoutes`: Used to notify this node of routes that are currently in use in it. - * @internal + * @alpha */ export interface ISummarizerNodeWithGC extends ISummarizerNode { createChild( @@ -330,7 +330,7 @@ export const channelsTreeName = ".channels"; /** * Contains telemetry data relevant to summarization workflows. * This object is expected to be modified directly by various summarize methods. - * @internal + * @alpha */ export interface ITelemetryContext { /** diff --git a/packages/utils/telemetry-utils/api-report/telemetry-utils.api.md b/packages/utils/telemetry-utils/api-report/telemetry-utils.api.md index 5a477d5d0917..319f056e7379 100644 --- a/packages/utils/telemetry-utils/api-report/telemetry-utils.api.md +++ b/packages/utils/telemetry-utils/api-report/telemetry-utils.api.md @@ -208,7 +208,7 @@ export interface ITaggedTelemetryPropertyTypeExt { value: TelemetryEventPropertyTypeExt; } -// @internal +// @alpha export interface ITelemetryErrorEventExt extends ITelemetryPropertiesExt { // (undocumented) eventName: string; @@ -222,7 +222,7 @@ export interface ITelemetryEventExt extends ITelemetryPropertiesExt { eventName: string; } -// @internal +// @alpha export interface ITelemetryGenericEventExt extends ITelemetryPropertiesExt { // (undocumented) category?: TelemetryEventCategory; @@ -230,7 +230,7 @@ export interface ITelemetryGenericEventExt extends ITelemetryPropertiesExt { eventName: string; } -// @internal +// @alpha export interface ITelemetryLoggerExt extends ITelemetryBaseLogger { sendErrorEvent(event: ITelemetryErrorEventExt, error?: unknown): void; sendPerformanceEvent(event: ITelemetryPerformanceEventExt, error?: unknown, logLevel?: typeof LogLevel.verbose | typeof LogLevel.default): void; @@ -251,13 +251,13 @@ export interface ITelemetryLoggerPropertyBags { error?: ITelemetryLoggerPropertyBag; } -// @internal +// @alpha export interface ITelemetryPerformanceEventExt extends ITelemetryGenericEventExt { // (undocumented) duration?: number; } -// @internal +// @alpha export interface ITelemetryPropertiesExt { // (undocumented) [index: string]: TelemetryEventPropertyTypeExt | Tagged; @@ -401,10 +401,10 @@ export enum TelemetryDataTag { UserData = "UserData" } -// @internal +// @alpha export type TelemetryEventCategory = "generic" | "error" | "performance"; -// @internal +// @alpha export type TelemetryEventPropertyTypeExt = string | number | boolean | undefined | (string | number | boolean)[] | { [key: string]: // Flat objects can have the same properties as the event itself string | number | boolean | undefined | (string | number | boolean)[]; diff --git a/packages/utils/telemetry-utils/src/telemetryTypes.ts b/packages/utils/telemetry-utils/src/telemetryTypes.ts index 7682fab411e3..0d6a3ceed09d 100644 --- a/packages/utils/telemetry-utils/src/telemetryTypes.ts +++ b/packages/utils/telemetry-utils/src/telemetryTypes.ts @@ -13,8 +13,7 @@ import { ITelemetryBaseLogger, LogLevel, Tagged } from "@fluidframework/core-int * error - Error log event, ideally 0 of these are logged during a session * * performance - Includes duration, and often has _start, _end, or _cancel suffixes for activity tracking - * - * @internal + * @alpha */ export type TelemetryEventCategory = "generic" | "error" | "performance"; @@ -25,7 +24,7 @@ export type TelemetryEventCategory = "generic" | "error" | "performance"; * Includes extra types beyond {@link @fluidframework/core-interfaces#TelemetryBaseEventPropertyType}, which must be * converted before sending to a base logger. * - * @internal + * @alpha */ export type TelemetryEventPropertyTypeExt = | string @@ -54,7 +53,7 @@ export interface ITaggedTelemetryPropertyTypeExt { /** * JSON-serializable properties, which will be logged with telemetry. * - * @internal + * @alpha */ export interface ITelemetryPropertiesExt { [index: string]: TelemetryEventPropertyTypeExt | Tagged; @@ -76,8 +75,7 @@ export interface ITelemetryEventExt extends ITelemetryPropertiesExt { /** * Informational (non-error) telemetry event * @remarks Maps to category = "generic" - * - * @internal + * @alpha */ export interface ITelemetryGenericEventExt extends ITelemetryPropertiesExt { eventName: string; @@ -87,8 +85,7 @@ export interface ITelemetryGenericEventExt extends ITelemetryPropertiesExt { /** * Error telemetry event. * @remarks Maps to category = "error" - * - * @internal + * @alpha */ export interface ITelemetryErrorEventExt extends ITelemetryPropertiesExt { eventName: string; @@ -97,8 +94,7 @@ export interface ITelemetryErrorEventExt extends ITelemetryPropertiesExt { /** * Performance telemetry event. * @remarks Maps to category = "performance" - * - * @internal + * @alpha */ export interface ITelemetryPerformanceEventExt extends ITelemetryGenericEventExt { duration?: number; // Duration of event (optional) @@ -110,8 +106,7 @@ export interface ITelemetryPerformanceEventExt extends ITelemetryGenericEventExt * @remarks * This interface is meant to be used internally within the Fluid Framework, * and `ITelemetryBaseLogger` should be used when loggers are passed between layers. - * - * @internal + * @alpha */ export interface ITelemetryLoggerExt extends ITelemetryBaseLogger { /**