Frame Manager
Listeners do not buffer multi-chunk agent transfers themselves. The teamserver FrameManager owns two directions for a numeric session id:
Upstream. The agent sends a file or a large check-in in pieces. The listener calls
TsFramePut,TsFramePutDecoded, orTsFramePutStream. The first time the call reports the object complete, the returned buffer is the assembled body. A later put for that same finished session returns complete and a nil body.Downstream. The listener asks
TsFrameGetChunkorTsFrameGetChunkStickyfor a slice of hosted tasks at the offset it passes.TsFrameAckDeliveryconfirms bytes; it does not move a cursor.TsFrameResetUpstreamandTsFrameResetDownstreamdrop a half-finished transfer.
TsFrameHasPending tells a listener whether a session still has hosted work, so an agent can sleep instead of polling an empty queue.
Modes
TsFramePut and TsFramePutDecoded select the mode from the arguments.
TsFramePut / TsFramePutDecoded, chunkCount above 0
Chunk index
Pieces are numbered. sackBitmap marks up to 32 chunks after the next expected index.
TsFramePut / TsFramePutDecoded, chunkCount zero and totalSize above 0
Byte offset
Pieces are a byte range in a known total. sackBitmap is always 0. The next hole is walked in steps of the first chunk's size.
TsFramePutStream
Stream
Pieces are a seqNum from 0 plus an isLast flag.
TsFramePut returns complete, nextExpected, received, sackBitmap, and assembled. The body is set only the first time that object completes. Listeners put sackBitmap into the protocol ack only for chunk index.
TsFramePutDecoded runs the caller decode on that body. If the callback returns an error or a nil body, complete stays true and assembled is nil.
The default upload cap is 4 MB. Byte offset rejects a larger totalSize immediately. Chunk index and stream return no body once the assembled buffer would pass the cap.
What the listener still does
Authenticates the agent and calls
TsAgentSetTick.Decrypts one protocol frame.
Hands the plaintext piece to
TsFrame*.On a completed upstream object, calls
TsAgentProcessData. A nil body afterTsFramePutDecodedis not a body to dispatch.Writes the downstream slice from
TsFrameGetChunkorTsFrameGetChunkStickyback in its own protocol.
Build this only inside a listener extender. Agent plugins keep using PackTasks and ProcessData; the server calls those around the frame manager.
Downstream
TsFrameGetChunk and TsFrameGetChunkSticky return total, chunkOffset, data, taskNonce, and isEmpty. The offset in the call is the slice copied out of the stored data. Concurrent calls for one session pack that data once. The default size passed to TsAgentGetHostedAll is 4 MB; maxChunkSize then slices it. An encode callback runs before the data is stored.
isEmpty true means there is nothing to send. Sticky mode is for a lossy transport: repeating the same offset does not drop the session when the attempt limit is passed. The default limit is 10. Without sticky, passing it drops the session and returns no data with isEmpty false. A new offset resets the attempt count.
TsFrameAckDelivery ignores a non-zero nonce that does not match. A nonce of 0 skips that check. A matching ack clears the attempt count. The session is dropped only when ackOffset covers the data. A GetChunk* whose offset is already at or past the end drops the session and then packs whatever hosted work is left.
When a GetChunk* finds no download session and the hosted queue is empty, unfinished TASK_TYPE_TASK and TASK_TYPE_FEATURE entries that still have data are put back on the queue before the pack. TsFrameHasPending counts an open download session, the hosted queue, pivot tasks, and those same unfinished entries.
A request at offset 0, after the last byte of the current data was already served and more hosted work exists, drops that session and packs the next data.
Progress, notes, and reset
A stored upstream piece, the first GetChunk* of an offset, an AckDelivery that finishes the data, and either reset call TsAgentIoProgress. A repeated byte offset, a stream sequence that has already been appended, and an ack that does not finish the data do not. The teamserver sends that broadcast at most every 250 ms, and always when the active flag changes. A listener does not call TsAgentIoProgress itself.
After GetChunk* or a completed put, the listener should call adaptix.NoteFrameSent or adaptix.NoteFrameRecv. Each helper takes its stat once (TsFrameTakeStatTasks, TsFrameTakeStatRecv). Sent stats exist only after a served slice reaches the end of the data, and the size is the packed length. The console line looks like Sent 12.00 Kb (in 4 requests) or Received …. Units are bytes, Kb, Mb, and Gb. (in N requests) is added only when N is greater than 1. A receive under 256 bytes in one request, or a non-positive size, is omitted. An empty sent selection, or a packed size of 0, is omitted too.
TsFrameResetUpstream drops an in-progress upload and leaves the finished-upload cache, so a repeat of that finished object still returns complete and a nil body until the cache expires. TsFrameResetDownstream drops the download session. Canceling an upload calls TsFrameResetDownstream, so the agent stops reading the canceled bytes. TsTaskCancel does the same for a task already in RunningTasks. Finalizing a managed feature that was already running does the same. A task that was still only queued does not.
About once a minute the manager drops an upstream session with no new piece for 5 minutes, and a finished-upload cache entry 5 minutes after completion. A download session is dropped after 10 minutes without a chunk, and a non-sticky one is also dropped once it is over the attempt limit. Those intervals and the 4 MB caps are the defaults.
Last updated