@fluidframework/container-runtime 2.33.0-333010 → 2.33.0

package/src/dataStoreContext.ts

@@ -5,11 +5,17 @@
 
 import { TypedEventEmitter, type ILayerCompatDetails } from "@fluid-internal/client-utils";
 import { AttachState, IAudience } from "@fluidframework/container-definitions";
-import { IDeltaManager } from "@fluidframework/container-definitions/internal";
+import {
+	IDeltaManager,
+	isIDeltaManagerFull,
+	type IDeltaManagerFull,
+	type ReadOnlyInfo,
+} from "@fluidframework/container-definitions/internal";
 import {
 	FluidObject,
 	IDisposable,
 	ITelemetryBaseProperties,
+	type IErrorBase,
 	type IEvent,
 } from "@fluidframework/core-interfaces";
 import {
@@ -75,6 +81,7 @@ import {
 	tagCodeArtifacts,
 } from "@fluidframework/telemetry-utils/internal";
 
+import { BaseDeltaManagerProxy } from "./deltaManagerProxies.js";
 import {
 	runtimeCompatDetailsForDataStore,
 	validateDatastoreCompatibility,
@@ -188,6 +195,58 @@ export interface IFluidDataStoreContextEvents extends IEvent {
 	(event: "attaching" | "attached", listener: () => void);
 }
 
+/**
+ * Eventually we should remove the delta manger from being exposed to Datastore runtimes via the context. However to remove that exposure we need to add new
+ * features, and those features themselves need forward and back compat. This proxy is here to enable that back compat. Each feature this proxy is used to
+ * support should be listed below, and as layer compat support goes away for those feature, we should also remove them from this proxy, with the eventual goal
+ * of completely removing this proxy.
+ *
+ * - Everything regarding readonly is to support older datastore runtimes which do not have the setReadonly function, so they must get their readonly state via the delta manager.
+ *
+ */
+class ContextDeltaManagerProxy extends BaseDeltaManagerProxy {
+	constructor(
+		base: IDeltaManagerFull,
+		private readonly isReadOnly: () => boolean,
+	) {
+		super(base, {
+			onReadonly: (): void => {
+				/* readonly is controlled from the context which calls setReadonly */
+			},
+		});
+	}
+
+	public get readOnlyInfo(): ReadOnlyInfo {
+		const readonly = this.isReadOnly();
+		if (readonly === this.deltaManager.readOnlyInfo.readonly) {
+			return this.deltaManager.readOnlyInfo;
+		} else {
+			return readonly === true
+				? {
+						readonly,
+						forced: false,
+						permissions: undefined,
+						storageOnly: false,
+					}
+				: { readonly };
+		}
+	}
+
+	/**
+	 * Called by the owning datastore context to configure the readonly
+	 * state of the delta manger that is project down to the datastore
+	 * runtime. This state may not align with that of the true delta
+	 * manager if the context wishes to control the read only state
+	 * differently than the delta manager itself.
+	 */
+	public setReadonly(
+		readonly: boolean,
+		readonlyConnectionReason?: { reason: string; error?: IErrorBase },
+	): void {
+		this.emit("readonly", readonly, readonlyConnectionReason);
+	}
+}
+
 /**
  * Represents the context for the store. This context is passed to the store runtime.
  * @internal
@@ -217,10 +276,13 @@ export abstract class FluidDataStoreContext
 		return this.parentContext.baseLogger;
 	}
 
+	private readonly _contextDeltaManagerProxy: ContextDeltaManagerProxy;
 	public get deltaManager(): IDeltaManager<ISequencedDocumentMessage, IDocumentMessage> {
-		return this.parentContext.deltaManager;
+		return this._contextDeltaManagerProxy;
 	}
 
+	public isReadOnly = (): boolean => this.parentContext.isReadOnly?.() ?? false;
+
 	public get connected(): boolean {
 		return this.parentContext.connected;
 	}
@@ -420,6 +482,16 @@ export abstract class FluidDataStoreContext
 		// By default, a data store can log maximum 10 local changes telemetry in summarizer.
 		this.localChangesTelemetryCount =
 			this.mc.config.getNumber("Fluid.Telemetry.LocalChangesTelemetryCount") ?? 10;
+
+		assert(
+			isIDeltaManagerFull(this.parentContext.deltaManager),
+			0xb83 /* Invalid delta manager */,
+		);
+
+		this._contextDeltaManagerProxy = new ContextDeltaManagerProxy(
+			this.parentContext.deltaManager,
+			() => this.isReadOnly(),
+		);
 	}
 
 	public dispose(): void {
@@ -437,6 +509,7 @@ export abstract class FluidDataStoreContext
 				})
 				.catch((error) => {});
 		}
+		this._contextDeltaManagerProxy.dispose();
 	}
 
 	/**
@@ -615,6 +688,13 @@ export abstract class FluidDataStoreContext
 		this.channel!.setConnectionState(connected, clientId);
 	}
 
+	public notifyReadOnlyState(readonly: boolean): void {
+		this.verifyNotClosed("notifyReadOnlyState", false /* checkTombstone */);
+
+		this.channel?.notifyReadOnlyState?.(readonly);
+		this._contextDeltaManagerProxy.setReadonly(readonly);
+	}
+
 	/**
 	 * Process messages for this data store. The messages here are contiguous messages for this data store in a batch.
 	 * @param messageCollection - The collection of messages to process.

package/src/deltaManagerProxies.ts

@@ -25,13 +25,68 @@ import {
 import type { PendingStateManager } from "./pendingStateManager.js";
 import { summarizerClientType } from "./summary/index.js";
 
+/**
+ * Interface defining event handlers for the BaseDeltaManagerProxy.
+ * These handlers allow customization of behavior for various DeltaManager events.
+ */
+export interface BaseDeltaManagerProxyEventHandlers {
+	/**
+	 * Event handler triggered when the readonly state changes.
+	 * @param readonly - Indicates if the connection is readonly.
+	 * @param readonlyConnectionReason - Optional reason and error details for the readonly state.
+	 */
+	onReadonly: (
+		readonly: boolean,
+		readonlyConnectionReason?: { reason: string; error?: IErrorBase },
+	) => void;
+
+	/**
+	 * Event handler triggered before sending a message.
+	 * @param messageBuffer - The buffer of messages to be sent.
+	 */
+	onPrepareSend: (messageBuffer: unknown[]) => void;
+
+	/**
+	 * Event handler triggered when an operation is submitted.
+	 * @param message - The document message being submitted.
+	 */
+	onSubmitOp: (message: IDocumentMessage) => void;
+
+	/**
+	 * Event handler triggered when an operation is received.
+	 * @param message - The sequenced document message received.
+	 * @param processingTime - The time taken to process the message.
+	 */
+	onOp: (message: ISequencedDocumentMessage, processingTime: number) => void;
+
+	/**
+	 * Event handler triggered when a pong response is received.
+	 * @param latency - The latency of the pong response.
+	 */
+	onPong: (latency: number) => void;
+
+	/**
+	 * Event handler triggered when a connection is established.
+	 * @param details - The connection details.
+	 * @param opsBehind - Optional number of operations behind the latest state.
+	 */
+	onConnect: (details: IConnectionDetails, opsBehind?: number) => void;
+
+	/**
+	 * Event handler triggered when a disconnection occurs.
+	 * @param reason - The reason for the disconnection.
+	 * @param error - Optional error details for the disconnection.
+	 */
+	onDisconnect: (reason: string, error?: IAnyDriverError) => void;
+}
+
 /**
  * Base class for DeltaManager proxy that proxy's access to the real DeltaManager.
  *
  * This class allows us to build proxy functionality without actually having to implement all the methods
  * of the DeltaManager.
  */
-export abstract class BaseDeltaManagerProxy
+export class BaseDeltaManagerProxy
 	extends TypedEventEmitter<IDeltaManagerEvents>
 	implements IDeltaManagerFull
 {
@@ -99,29 +154,64 @@ export abstract class BaseDeltaManagerProxy
 		return this.deltaManager.readOnlyInfo;
 	}
 
-	constructor(protected readonly deltaManager: IDeltaManagerFull) {
+	private readonly eventHandlers: BaseDeltaManagerProxyEventHandlers;
+
+	constructor(
+		protected readonly deltaManager: IDeltaManagerFull,
+		overrides?: Partial<BaseDeltaManagerProxyEventHandlers>,
+	) {
 		super();
 
+		this.eventHandlers = {
+			onPrepareSend: (messageBuffer: unknown[]): void => {
+				this.emit("prepareSend", messageBuffer);
+			},
+			onSubmitOp: (message: IDocumentMessage): void => {
+				this.emit("submitOp", message);
+			},
+			onOp: (message: ISequencedDocumentMessage, processingTime: number): void => {
+				this.emit("op", message, processingTime);
+			},
+			onPong: (latency: number): void => {
+				this.emit("pong", latency);
+			},
+			onConnect: (details: IConnectionDetails, opsBehind?: number): void => {
+				this.emit("connect", details, opsBehind);
+			},
+			onDisconnect: (reason: string, error?: IAnyDriverError): void => {
+				this.emit("disconnect", reason, error);
+			},
+			onReadonly: (
+				readonly: boolean,
+				readonlyConnectionReason?: { reason: string; error?: IErrorBase },
+			): void => {
+				this.emit("readonly", readonly, readonlyConnectionReason);
+			},
+
+			...overrides,
+		};
+
 		// We are expecting this class to have many listeners, so we suppress noisy "MaxListenersExceededWarning" logging.
 		super.setMaxListeners(0);
 
-		this.deltaManager.on("prepareSend", this.onPrepareSend);
-		this.deltaManager.on("submitOp", this.onSubmitOp);
-		this.deltaManager.on("op", this.onOp);
-		this.deltaManager.on("pong", this.onPong);
-		this.deltaManager.on("connect", this.onConnect);
-		this.deltaManager.on("disconnect", this.onDisconnect);
-		this.deltaManager.on("readonly", this.onReadonly);
+		this.deltaManager.on("prepareSend", this.eventHandlers.onPrepareSend);
+		this.deltaManager.on("submitOp", this.eventHandlers.onSubmitOp);
+		this.deltaManager.on("op", this.eventHandlers.onOp);
+		this.deltaManager.on("pong", this.eventHandlers.onPong);
+		this.deltaManager.on("connect", this.eventHandlers.onConnect);
+		this.deltaManager.on("disconnect", this.eventHandlers.onDisconnect);
+		this.deltaManager.on("readonly", this.eventHandlers.onReadonly);
 	}
 
 	public dispose(): void {
-		this.deltaManager.off("prepareSend", this.onPrepareSend);
-		this.deltaManager.off("submitOp", this.onSubmitOp);
-		this.deltaManager.off("op", this.onOp);
-		this.deltaManager.off("pong", this.onPong);
-		this.deltaManager.off("connect", this.onConnect);
-		this.deltaManager.off("disconnect", this.onDisconnect);
-		this.deltaManager.off("readonly", this.onReadonly);
+		this.deltaManager.off("prepareSend", this.eventHandlers.onPrepareSend);
+		this.deltaManager.off("submitOp", this.eventHandlers.onSubmitOp);
+		this.deltaManager.off("op", this.eventHandlers.onOp);
+		this.deltaManager.off("pong", this.eventHandlers.onPong);
+		this.deltaManager.off("connect", this.eventHandlers.onConnect);
+		this.deltaManager.off("disconnect", this.eventHandlers.onDisconnect);
+		this.deltaManager.off("readonly", this.eventHandlers.onReadonly);
+		this.removeAllListeners();
 	}
 
 	public submitSignal(content: string, targetClientId?: string): void {
@@ -131,34 +221,6 @@ export abstract class BaseDeltaManagerProxy
 	public flush(): void {
 		return this.deltaManager.flush();
 	}
-
-	private readonly onPrepareSend = (messageBuffer: unknown[]): void => {
-		this.emit("prepareSend", messageBuffer);
-	};
-	private readonly onSubmitOp = (message: IDocumentMessage): void => {
-		this.emit("submitOp", message);
-	};
-	protected readonly onOp = (
-		message: ISequencedDocumentMessage,
-		processingTime: number,
-	): void => {
-		this.emit("op", message, processingTime);
-	};
-	private readonly onPong = (latency: number): void => {
-		this.emit("pong", latency);
-	};
-	private readonly onConnect = (details: IConnectionDetails, opsBehind?: number): void => {
-		this.emit("connect", details, opsBehind);
-	};
-	private readonly onDisconnect = (reason: string, error?: IAnyDriverError): void => {
-		this.emit("disconnect", reason, error);
-	};
-	private readonly onReadonly = (
-		readonly: boolean,
-		readonlyConnectionReason?: { reason: string; error?: IErrorBase },
-	): void => {
-		this.emit("readonly", readonly, readonlyConnectionReason);
-	};
 }
 
 /**
@@ -167,31 +229,34 @@ export abstract class BaseDeltaManagerProxy
  * - Summarizer client should not be active to layers below the container runtime to restrict local changes.
  */
 export class DeltaManagerSummarizerProxy extends BaseDeltaManagerProxy {
+	public static wrapIfSummarizer(deltaManager: IDeltaManagerFull): IDeltaManagerFull {
+		if (deltaManager.clientDetails.type === summarizerClientType) {
+			return new DeltaManagerSummarizerProxy(deltaManager);
+		}
+		return deltaManager;
+	}
+
+	// eslint-disable-next-line @typescript-eslint/class-literal-property-style
 	public get active(): boolean {
 		// Summarize clients should not be active. There shouldn't be any local changes (writes) in the summarizer
 		// except for the SummarizeOp which is generated by the runtime.
-		return !this.isSummarizerClient && this.deltaManager.active;
+		return false;
 	}
 
 	public get readOnlyInfo(): ReadOnlyInfo {
 		// Summarizer clients should be read-only as far as the runtime and layers below are concerned. There shouldn't
 		// be any local changes (writes) in the summarizer except for the summarize op which is generated by the runtime.
-		if (this.isSummarizerClient) {
-			return {
-				readonly: true,
-				forced: false,
-				permissions: undefined,
-				storageOnly: false,
-			};
-		}
-		return this.deltaManager.readOnlyInfo;
-	}
 
-	private readonly isSummarizerClient: boolean;
+		return {
+			readonly: true,
+			forced: false,
+			permissions: undefined,
+			storageOnly: false,
+		};
+	}
 
 	constructor(protected readonly deltaManager: IDeltaManagerFull) {
-		super(deltaManager);
-		this.isSummarizerClient = this.deltaManager.clientDetails.type === summarizerClientType;
+		super(deltaManager, { onReadonly: () => {} });
 	}
 }
 
@@ -228,17 +293,6 @@ export class DeltaManagerPendingOpsProxy extends BaseDeltaManagerProxy {
 		};
 	}
 
-	protected readonly onOp = (
-		message: ISequencedDocumentMessage,
-		processingTime: number,
-	): void => {
-		const messageIntercept = {
-			...message,
-			minimumSequenceNumber: this.minimumSequenceNumber,
-		};
-		this.emit("op", messageIntercept, processingTime);
-	};
-
 	constructor(
 		protected readonly deltaManager: IDeltaManagerFull,
 		private readonly pendingStateManager: Pick<
@@ -246,6 +300,14 @@ export class DeltaManagerPendingOpsProxy extends BaseDeltaManagerProxy {
 			"minimumPendingMessageSequenceNumber"
 		>,
 	) {
-		super(deltaManager);
+		super(deltaManager, {
+			onOp: (message: ISequencedDocumentMessage, processingTime: number): void => {
+				const messageIntercept = {
+					...message,
+					minimumSequenceNumber: this.minimumSequenceNumber,
+				};
+				this.emit("op", messageIntercept, processingTime);
+			},
+		});
 	}
 }

package/src/gc/gcDefinitions.ts

@@ -333,6 +333,8 @@ export type GarbageCollectionMessage = ISweepMessage | ITombstoneLoadedMessage;
 
 /**
  * Defines the APIs for the runtime object to be passed to the garbage collector.
+ *
+ * @internal
  */
 export interface IGarbageCollectionRuntime {
 	/**

package/src/index.ts

@@ -4,6 +4,8 @@
  */
 
 export {
+	ContainerRuntimeOptions,
+	ContainerRuntimeOptionsInternal,
 	ISummaryRuntimeOptions,
 	IContainerRuntimeOptions,
 	IContainerRuntimeOptionsInternal,
@@ -14,11 +16,10 @@ export {
 	DeletedResponseHeaderKey,
 	TombstoneResponseHeaderKey,
 	InactiveResponseHeaderKey,
-	ICompressionRuntimeOptions,
-	CompressionAlgorithms,
 	RuntimeHeaderData,
-	disabledCompressionConfig,
 } from "./containerRuntime.js";
+export type { ICompressionRuntimeOptions } from "./compressionDefinitions.js";
+export { CompressionAlgorithms, disabledCompressionConfig } from "./compressionDefinitions.js";
 export {
 	ContainerMessageType,
 	UnknownContainerRuntimeMessage,
@@ -35,6 +36,7 @@ export {
 	IGCMetadata,
 	GCFeatureMatrix,
 	GCVersion,
+	IGarbageCollectionRuntime,
 	IGCRuntimeOptions,
 	IMarkPhaseStats,
 	ISweepPhaseStats,

package/src/opLifecycle/batchManager.ts

@@ -10,11 +10,12 @@ import {
 	TelemetryDataTag,
 } from "@fluidframework/telemetry-utils/internal";
 
-import { ICompressionRuntimeOptions } from "../containerRuntime.js";
+import { ICompressionRuntimeOptions } from "../compressionDefinitions.js";
 import { asBatchMetadata, type IBatchMetadata } from "../metadata.js";
 import type { IPendingMessage } from "../pendingStateManager.js";
 
 import { LocalBatchMessage, IBatchCheckpoint, type LocalBatch } from "./definitions.js";
+import { serializeOp } from "./opSerialization.js";
 import type { BatchStartInfo } from "./remoteMessageProcessor.js";
 
 export interface IBatchManagerOptions {
@@ -127,10 +128,12 @@ export class BatchManager {
 	 * Gets the pending batch and clears state for the next batch.
 	 */
 	public popBatch(batchId?: BatchId): LocalBatch {
+		assert(this.pendingBatch[0] !== undefined, 0xb8a /* expected non-empty batch */);
 		const batch: LocalBatch = {
 			messages: this.pendingBatch,
 			referenceSequenceNumber: this.referenceSequenceNumber,
 			hasReentrantOps: this.hasReentrantOps,
+			staged: this.pendingBatch[0].staged,
 		};
 
 		this.pendingBatch = [];
@@ -158,9 +161,7 @@ export class BatchManager {
 					throw new LoggingError("Ops generated during rollback", {
 						count,
 						...tagData(TelemetryDataTag.UserData, {
-							ops: JSON.stringify(
-								this.pendingBatch.slice(startPoint).map((b) => b.serializedOp),
-							),
+							ops: serializeOp(this.pendingBatch.slice(startPoint).map((b) => b.runtimeOp)),
 						}),
 					});
 				}

package/src/opLifecycle/definitions.ts

@@ -5,17 +5,33 @@
 
 import type { IBatchMessage } from "@fluidframework/container-definitions/internal";
 
-import { CompressionAlgorithms } from "../containerRuntime.js";
+import { CompressionAlgorithms } from "../compressionDefinitions.js";
+import type { LocalContainerRuntimeMessage } from "../messageTypes.js";
 
 /**
  * Local Batch message, before it is virtualized and sent to the ordering service
  */
 export interface LocalBatchMessage {
-	serializedOp: string;
+	/**
+	 * The original local op
+	 */
+	runtimeOp: LocalContainerRuntimeMessage;
+	/**
+	 * Optional metadata which is not to be serialized with the op, and is visible to the ordering service
+	 */
 	metadata?: Record<string, unknown>;
+	/**
+	 * Metadata used by this local client in flows such as rebase
+	 */
 	localOpMetadata?: unknown;
+	/**
+	 * Reference sequence number this op is based on
+	 */
 	referenceSequenceNumber: number;
-	compression?: CompressionAlgorithms;
+	/**
+	 * If true, this op is not to be submitted to the ordering service yet, since it was submitted during Staging Mode
+	 */
+	staged?: boolean;
 
 	/**
 	 * @deprecated Use serializedOp
@@ -23,6 +39,15 @@ export interface LocalBatchMessage {
 	contents?: never; // To ensure we don't leave this one when converting from OutboundBatchMessage
 }
 
+/**
+ * Placeholder for an empty batch, for tracking the pending local empty batch
+ */
+export interface LocalEmptyBatchPlaceholder {
+	metadata?: Record<string, unknown>;
+	localOpMetadata: { emptyBatch: true };
+	referenceSequenceNumber: number;
+}
+
 /**
  * Virtualized Batch message, on its way out the door to the ordering service
  */
@@ -40,7 +65,12 @@ export type OutboundBatchMessage = IBatchMessage & {
 /**
  * A batch of messages we have accumulated locally, but haven't sent to the ordering service yet.
  */
-export type LocalBatch = IBatch<LocalBatchMessage[]>;
+export interface LocalBatch extends IBatch<LocalBatchMessage[]> {
+	/**
+	 * If true, this batch is not to be submitted to the ordering service yet, since it was submitted during Staging Mode
+	 */
+	staged?: boolean;
+}
 
 /**
  * A batch of messages that has been virtualized as needed (grouped, compressed, chunked)

package/src/opLifecycle/index.ts

@@ -14,6 +14,7 @@ export {
 export {
 	LocalBatch,
 	LocalBatchMessage,
+	LocalEmptyBatchPlaceholder,
 	OutboundBatch,
 	OutboundBatchMessage,
 	OutboundSingletonBatch,

package/src/opLifecycle/opCompressor.ts

@@ -13,7 +13,7 @@ import {
 } from "@fluidframework/telemetry-utils/internal";
 import { compress } from "lz4js";
 
-import { CompressionAlgorithms } from "../containerRuntime.js";
+import { CompressionAlgorithms } from "../compressionDefinitions.js";
 
 import { type OutboundBatchMessage, type OutboundSingletonBatch } from "./definitions.js";
 import { estimateSocketSize } from "./outbox.js";

package/src/opLifecycle/opDecompressor.ts

@@ -13,7 +13,7 @@ import {
 } from "@fluidframework/telemetry-utils/internal";
 import { decompress } from "lz4js";
 
-import { CompressionAlgorithms } from "../containerRuntime.js";
+import { CompressionAlgorithms } from "../compressionDefinitions.js";
 import { IBatchMetadata } from "../metadata.js";
 
 /**

package/src/opLifecycle/opGroupingManager.ts

@@ -12,8 +12,8 @@ import {
 } from "@fluidframework/telemetry-utils/internal";
 
 import {
+	type LocalEmptyBatchPlaceholder,
 	type OutboundBatch,
-	type OutboundBatchMessage,
 	type OutboundSingletonBatch,
 } from "./definitions.js";
 
@@ -67,7 +67,10 @@ export class OpGroupingManager {
 	public createEmptyGroupedBatch(
 		resubmittingBatchId: string,
 		referenceSequenceNumber: number,
-	): { outboundBatch: OutboundSingletonBatch; placeholderMessage: OutboundBatchMessage } {
+	): {
+		outboundBatch: OutboundSingletonBatch;
+		placeholderMessage: LocalEmptyBatchPlaceholder;
+	} {
 		assert(
 			this.config.groupedBatchingEnabled,
 			0xa00 /* cannot create empty grouped batch when grouped batching is disabled */,
@@ -77,15 +80,14 @@ export class OpGroupingManager {
 			contents: [],
 		});
 
-		const placeholderMessage: OutboundBatchMessage = {
+		const placeholderMessage: LocalEmptyBatchPlaceholder = {
 			metadata: { batchId: resubmittingBatchId },
 			localOpMetadata: { emptyBatch: true },
 			referenceSequenceNumber,
-			contents: serializedOp,
 		};
 		const outboundBatch: OutboundSingletonBatch = {
 			contentSizeInBytes: 0,
-			messages: [placeholderMessage],
+			messages: [{ ...placeholderMessage, contents: serializedOp }],
 			referenceSequenceNumber,
 		};
 		return { outboundBatch, placeholderMessage };

package/src/opLifecycle/opSerialization.ts

@@ -30,10 +30,14 @@ export function ensureContentsDeserialized(mutableMessage: ISequencedDocumentMes
 /**
  * Before submitting an op to the Outbox, its contents must be serialized using this function.
  * @remarks - The deserialization on process happens via the function {@link ensureContentsDeserialized}.
+ *
+ * @param toSerialize - op message to serialize. Also supports an array of ops.
  */
-export function serializeOp(op: LocalContainerRuntimeMessage): string {
+export function serializeOp(
+	toSerialize: LocalContainerRuntimeMessage | LocalContainerRuntimeMessage[],
+): string {
 	return JSON.stringify(
-		op,
+		toSerialize,
 		// replacer:
 		(key, value: unknown) => {
 			// If 'value' is an IFluidHandle return its encoded form.