Large-object support in AOF, Migration, and diskless Replication

[Ted Hart (TedHartMS)]

This pull request introduces support for chunked migration and replication of large records that do not fit into a single send buffer. It adds a new chunked record type, logic for splitting and reassembling records, and updates the migration and replication code paths to handle records of arbitrary size, including those with object values exceeding buffer limits. The implementation ensures efficient and reliable transfer of large records during cluster migration and diskless replication.

Chunked Record Support

• Added a new ChunkedLogRecord type to MigrationRecordSpanType to represent records split across multiple send buffers.
• Implemented TryWriteChunkedRecordSpan in GarnetClientSession to write record chunks with continuation flags, handling buffer flush and retry logic.
• Added reusable buffers and logic in MigrateSessionCommonUtils to assemble and send records as either a whole or in chunked form, with length prefixes for overflow segments.

Migration and Replication Pipeline Updates

• Updated migration methods to use the new chunked record logic, ensuring records are sent whole if they fit a buffer or chunked otherwise, including handling of overflow keys/values and large object values.
• Updated replication code (AofSyncDriver, AofSyncTask, ReplicaSyncSession, and ReplicationSnapshotIterator) to support chunked record writing and to expose the new chunked write API. [1] [2] [3] [4]

Buffer Size and Overhead Handling

• Standardized calculation of maximum send buffer content size to ensure correct chunking and avoid buffer overflows during migration. [1] [2]

Object Serialization Integration

• Integrated chunked object serialization into the snapshot iterator for diskless replication, allowing seamless chunked transfer of large serialized object values. [1] [2]

Code Comments and Cleanup

• Improved comments and removed outdated TODOs, clarifying the migration and replication logic and documenting the new chunked record handling. [1] [2]
• Extensive documentation in aof-record-layout.md and migration-replication-record-layout.md

These changes together enable robust migration and replication of very large records, improving the reliability and scalability of cluster operations.

[Copilot]

Pull request overview

This PR adds end-to-end support for transferring very large records (including large object values) across AOF, cluster migration, and diskless replication by introducing chunked record framing, streaming serialization/deserialization, and replay/rehydration support so records are no longer constrained by a single send buffer.

Changes:

• Introduces chunked framing and streaming serializers/consumers to write, send, reassemble, and replay records whose serialized size exceeds buffer/page limits (including >2GB object values via ReadOnlySequence<byte>).
• Updates AOF logging + replay coordinator/processor to persist and replay chunked logical records without materializing a contiguous image.
• Extends migration + diskless sync pipelines to emit/consume chunked records, and adds tests + documentation for record layouts and edge cases.

Reviewed changes

Copilot reviewed 59 out of 59 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
website/sidebars.js	Adds a docs sidebar category for the new chunked record layout documents.
website/docs/dev/aof-record-layout.md	New detailed documentation for non-chunked vs chunked AOF record layout and replay flow.
test/standalone/Garnet.test/TestUtils.cs	Adds AOF page/sublog configuration plumbing for tests.
test/cluster/Garnet.test.cluster/ClusterTestContext.cs	Threads through AOF page size option for cluster test instances.
test/cluster/Garnet.test.cluster.replication.disklesssync/ReplicationTests/ClusterReplicationDisklessSyncTests.cs	Adds diskless-sync tests for chunked large values and explicit huge-object coverage.
test/cluster/Garnet.test.cluster.migrate/ClusterMigrateTests.cs	Adds migration tests for chunked large values and explicit huge-object coverage.
libs/storage/Tsavorite/cs/test/ChunkedByteStreamTests.cs	Adds unit tests for value-only chunked byte-stream serialization/reassembly.
libs/storage/Tsavorite/cs/test/AllocateBlockPartialTests.cs	Adds unit tests for page-tail partial allocation behavior.
libs/storage/Tsavorite/cs/src/core/TsavoriteLog/TsavoriteLogScanSingleIterator.cs	Adjusts iterator disposal to remove the correct iterator type.
libs/storage/Tsavorite/cs/src/core/TsavoriteLog/TsavoriteLog.cs	Refactors/enhances log internals (partial class, allocation guards, exposes buffer pool).
libs/storage/Tsavorite/cs/src/core/Allocator/OverflowByteArray.cs	Adds helper allocation for direct-populated overflow buffers.
libs/storage/Tsavorite/cs/src/core/Allocator/ObjectSerialization/IChunkedObjectSerializerConsumer.cs	New consumer interface for chunked serialization drains (value-only and key/input variants).
libs/storage/Tsavorite/cs/src/core/Allocator/ObjectSerialization/ChunkHeader.cs	Adds a chunk header type intended for chunk framing.
libs/storage/Tsavorite/cs/src/core/Allocator/ObjectSerialization/ChunkedRecordConstants.cs	Adds shared continuation-flag constant for chunk prefix framing.
libs/storage/Tsavorite/cs/src/core/Allocator/ObjectSerialization/ChunkedObjectSerializer.cs	Adds bounded-ring streaming serializer that drains to chunk consumers.
libs/storage/Tsavorite/cs/src/core/Allocator/ConditionallyHoistedKey.cs	Makes ConditionallyHoistedKey.Create public for chunked serializer usage.
libs/storage/Tsavorite/cs/src/core/Allocator/AllocatorBase.cs	Adds partial page-tail allocation support and refactors retry/backoff allocation logic.
libs/server/UnifiedOutput.cs	Adds migration accumulator field to carry out-of-line pieces captured in-epoch.
libs/server/Storage/Functions/UnifiedStore/UpsertMethods.cs	Routes object upsert logging through the new chunked AOF object path.
libs/server/Storage/Functions/UnifiedStore/ReadMethods.cs	Updates MIGRATE read path to capture inline/overflow/object pieces into an accumulator.
libs/server/Storage/Functions/UnifiedStore/PrivateMethods.cs	Switches object upsert AOF logging to stream/emit chunk records (no full materialization).
libs/server/Storage/Functions/ObjectStore/UpsertMethods.cs	Routes object-store upsert logging through chunked AOF object path.
libs/server/Storage/Functions/ObjectStore/PrivateMethods.cs	Switches object-store object upsert AOF logging to chunked streaming path.
libs/server/Storage/Functions/FunctionsState.cs	Makes per-session GarnetObjectSerializer lazy to support streaming safely per session.
libs/server/Servers/GarnetServerOptions.cs	Clarifies AOF page-size constraints relative to chunking support.
libs/server/Resp/Vector/VectorManager.Callbacks.cs	Updates a docstring in vector key construction logic.
libs/server/Objects/Types/GarnetObjectSerializer.cs	Adds ReadOnlySequence<byte> streaming deserialize support via ReadOnlySequenceStream.
libs/server/MigrationChunkWriterAccumulator.cs	New accumulator for migration to capture overflow/object chunks in-epoch for async sending.
libs/server/AOF/ReplayCoordinator/TransactionGroup.cs	Adjusts transaction buffering to store typed replay operations.
libs/server/AOF/ReplayCoordinator/ReplayOperation.cs	New discriminated holder for raw records vs completed chunked accumulators.
libs/server/AOF/ReplayCoordinator/AofReplayCoordinator.cs	Buffers/replays both chunked and non-chunked ops; updates txn + fuzzy-region handling.
libs/server/AOF/ReplayCoordinator/AofReplayContext.cs	Adds per-sublog chunked record reader and switches fuzzy buffer to typed operations.
libs/server/AOF/Recover/AofRecover.cs	Minor comment update in recovery loop.
libs/server/AOF/GarnetLog.cs	Adds chunkability logic; writes large records as chunk records; adds object chunked enqueue.
libs/server/AOF/AofProcessor.cs	Adds chunk-detection path and refactors shared replay preamble; routes chunk records by keyHash.
libs/server/AOF/AofProcessor.ChunkReplay.cs	New chunked replay path that dispatches directly from ChunkedAccumulator.
libs/server/AOF/AofHeader.cs	Adds chunked header variants, mask updates, helpers, and embedded chunk header accessors.
libs/server/AOF/AofEntryType.cs	Adds helpers to indicate which ops carry chunked value/input and whether value is object-streamed.
libs/server/AOF/AofChunkHeader.cs	New per-chunk header for AOF chunk records (lengths/objectId/keyHash).
libs/server/AOF/AofChunkedRecordReader.cs	New chunked AOF record reassembler keyed by objectId that yields completed accumulators.
libs/common/ReadOnlySequenceStream.cs	New Stream wrapper to read a multi-segment ReadOnlySequence<byte> without flattening.
libs/common/ReadOnlySequenceBuilder.cs	New helper to build a ReadOnlySequence<byte> over chunk byte[] segments without copying.
libs/common/NetworkBufferSettings.cs	Standardizes send-buffer payload sizing with explicit overhead reserve and exposes max payload size.
libs/cluster/Session/RespClusterReplicationCommands.cs	Adds receiver-side handling of chunked incoming records during replication sync.
libs/cluster/Session/RespClusterMigrateCommands.cs	Adds receiver-side handling of chunked incoming records during migration.
libs/cluster/Session/ChunkedRecordReassembler.cs	New state machine to reassemble chunked network records into inline + overflow/object pieces.
libs/cluster/Server/Replication/ReplicaOps/AOFReplay/ReplicaReplaySession.cs	Fixes method name typo for background replay initialization.
libs/cluster/Server/Replication/ReplicaOps/AOFReplay/ReplicaReplayDriver.cs	Renames method to InitializeBackgroundReplayTask.
libs/cluster/Server/Replication/PrimaryOps/DisklessReplication/ReplicationSnapshotIterator.cs	Streams snapshot records as whole or chunked, with shared chunker fan-out to replicas.
libs/cluster/Server/Replication/PrimaryOps/DisklessReplication/ReplicaSyncSession.cs	Adds TryWriteChunkedRecordSpan for chunked streaming to replica.
libs/cluster/Server/Replication/PrimaryOps/AofOperations/AofSyncTask.cs	Improves comment and corrects log method name usage.
libs/cluster/Server/Replication/PrimaryOps/AofOperations/AofSyncDriver.cs	Exposes chunked record write API from the driver.
libs/cluster/Server/Migration/MigrateSessionCommonUtils.cs	Assembles/sends accumulated overflow/object pieces and supports chunked record emission.
libs/cluster/Server/Migration/MigrateOperation.cs	Removes outdated TODOs; uses max send buffer content size consistently.
libs/client/ClientSession/GarnetClientSessionIncremental.cs	Adds ChunkedLogRecord span type and a chunked write API with continuation framing.

[Vasileios Zois (vazois)]

You might want to add an end-to-end test for multilog/multi-replay test. I see you are testing the recover path but not the AOF shipping when a primary is connected to a replica.
This will be testing the AofSyncDriver->AofSyncTask ->[network]-> ReplicaReplayDriver->ReplicaReplayTask path.

[Copilot]

Pull request overview

Copilot reviewed 58 out of 58 changed files in this pull request and generated 4 comments.

Suppressed comments (2)

libs/server/AOF/GarnetLog.cs:938

• If serialization or AOF allocation throws, this explicit Dispose is skipped. For a non-pinned key larger than the inline capacity, ConditionallyHoistedKey.Create rents SectorAlignedMemory, so repeated failures leak buffer-pool entries. Dispose the key in a finally block.

                var chKey = ConditionallyHoistedKey.Create(key, log.BufferPool);
                log.EnqueueChunkedObject(header, AofShardedChunkHeader.ObjectIdOffset, in chKey, ref input, objectSerializer, value, ChunkBufferSize(log, value), writeInput: opType.HasChunkInput(), epochAccessor, out logicalAddress);
                chKey.Dispose();

libs/server/AOF/GarnetLog.cs:914

• If serialization or AOF allocation throws, this explicit Dispose is skipped. For a non-pinned key larger than the inline capacity, ConditionallyHoistedKey.Create rents SectorAlignedMemory, so repeated failures leak buffer-pool entries. Dispose the key in a finally block.

This issue also appears on line 936 of the same file.

                var chKey = ConditionallyHoistedKey.Create(key, log.BufferPool);
                log.EnqueueChunkedObject(header, AofBasicChunkHeader.ObjectIdOffset, in chKey, ref input, objectSerializer, value, ChunkBufferSize(log, value), writeInput: opType.HasChunkInput(), epochAccessor, out logicalAddress);
                chKey.Dispose();