Transfer Structure

A Transfer structure is returned from createTransfer(), getTransfer() and getTransfers().

bytesAcked

The number of bytes confirmed as received by the remote server: the contiguous prefix of the transfer it holds. This is the progress numerator — progress is bytesAcked / totalBytes.

bytesSent

The total number of bytes sent for a transfer. This is the wire cost, so it can exceed bytesAcked while data is in flight.

checkpointFrequencySeconds

How frequently to take a checkpoint, in seconds. A checkpoint is a guarantee that files have been written to storage. If the receiver of a transfer is terminated and subsequently resumed, the transfer can safely continue from its last checkpoint. If checkpoints are disabled, this is None.

connectionPath

How the live connection was established: 'direct' (the sender dialled the destination address), 'reverse' (the receiver dialled back through its registration channel — the NAT-traversal path) or 'relay' (dialled out through a standalone relay). Empty until a connection is up, under the same rule as transport, and connection-scoped the same way — every transfer sharing a destination reports the same value. It names the mechanism the connection used, not a conclusion about the network: reverseDial='always' and relay policy both take these paths to perfectly reachable receivers.

destinationId

A destination ID. Destination IDs are returned from createDestination, and used in other methods to refer to a specific destination.

destinationPath

The directory that will be created as the parent for all files in the transfer. The manifest paths are respected, and added below this destination path.

effectiveRateCapBps

The rate cap in force for this transfer, in bytes-per-second. None when nothing caps the transfer, or before the first measurement.

endTime

The timestamp at which a transfer ended. See Timestamps.

errorMessage

If unsuccessful, this contains a description of the error that occurred. See status.

integrity

What the receiving server’s end-to-end integrity check concluded, relayed to this server: verified, verifiedOnDisk, unverified, failed, disabled, pending or unknown. unknown means the answer has not arrived yet, because the transfer is still running or the receiver is older than this feature. See Receive Transfer Structure.

limitedBy

The main reason this transfer is not faster. One of measuring, notMeasured, fullSpeed, rateCap, urgencyCap, schedulerQueue, disconnected, sourceRead, destinationWrite or senderHost. Read an unknown value as measuring.

limitedByReason

A sentence that explains limitedBy, ready to show to a user. None while there is no verdict.

manifestId

A manifest ID. Manifest IDs are returned from createManifest(), and used in other methods to refer to a specific manifest.

owner

The owner of this transfer. A transfer may be monitored or modified only by its owner, or by a superuser.

ownerToken

The owner of this transfer, if this transfer was created by a token. A transfer is only visible to its token, owner, or a superuser.

ownerTokenSession

The token session of this token that created this transfer.

processing

If True, the JetStream server is still processing this item. Use the getTransfer() or waitForTransfer() method to monitor its progress.

queuePosition

How many transfers are ahead of this one in the server’s wait queue, counting from 1. None unless status is waiting. The queue is box-wide, across every destination, so a transfer to one destination can be held behind a more urgent transfer to another.

queueTime

A timestamp indicating when a transfer was added to the queue. See Timestamps.

rateCapSource

Which limit set effectiveRateCapBps. None together with effectiveRateCapBps.

requestedTransport

The transport this transfer asked for: 'udp' or 'tcp'. This is the transfer’s own request, or the destination default it took. It is always spelled out, also before a connection is up.

requestTime

A timestamp indicating when a transfer was requested. See Timestamps.

sendRateMax

The maximum send rate of this transfer in kilobits per second. Will be None if no maximum rate is set for this transfer.

Changed in version 3.0.0: (API 47) This is now enforced. It was accepted, stored and echoed back without ever limiting anything; it is applied as one input to the transfer’s rate cap. It is a self-limit only: it can hold a transfer below the bandwidth the server allocated it, never above.

sharing

True while this transfer gives way to a more urgent one. This happens when its connection yields to more urgent traffic elsewhere on the server, or when a more urgent transfer runs on the same connection.

snapshotTime

A timestamp indicating when the information was recorded. JetStream captures a snapshot of its state once per second. See Timestamps.

startTime

A timestamp indicating when a transfer was started. See Timestamps.

status

The status may be one of the following values:

pending

The transfer has been queued, but data has not been transmitted yet.

sending

Data is actively being transferred.

waiting

The server is holding this transfer back because it already runs the most transfers it allows. It will start on its own as soon as a place frees; nothing needs to be done to it. queuePosition says how many transfers are ahead of it.

Do not confuse this with suspended. A waiting transfer is waiting on the server and processing is True for it, so a loop that polls until a transfer stops processing must not stop here; a suspended transfer is waiting on the client and will not move until it is resumed. Offering a resume action for a waiting transfer is a bug.

Two counts decide this, and getServerInfo().bandwidthLimits reports both. maxConcurrentTransfers is the most transfers the server runs at once. maxTransfersPerDestination is the most it runs to one destination, and its default is 1. A bandwidth limit never holds a transfer. A more urgent transfer can take the place of a running transfer of lower urgency, which then reports waiting until a place frees.

held

The receiving server is holding this transfer back, because its own inbound admission pass has not admitted it. Like waiting it will start again on its own – the receiver asks the sender to resume when it readmits the transfer – and processing is True for it, so a loop that polls until a transfer stops processing must not stop here either.

Distinct from suspended for the reason that matters to a user: nobody on this end did it, and there is nothing on this end to undo. The receiver enforces a hold by asking this server to suspend the transfer, so before this status existed a held transfer was indistinguishable from one a person had suspended.

Appears when the receiving server already runs as many transfers as its --max-concurrent-transfers allows, or when this machine is over the receiver’s incomingMaxConnections limit.

suspended

The transfer was suspended. Use resumeTransfer() to resume transmitting.

resuming

The transfer is being resumed, but data is not being transmitted yet (the transfer is waiting in the queue).

complete

The transfer has been completed successfully.

error

The transfer failed. The errorMessage field will contain a description of the error.

suspendedUnreachable

True if this server suspended the transfer itself because the destination stayed unreachable. The transfer resumes on its own when the destination comes back. Only True while status is suspended.

totalBytes

The total number of bytes in a transfer.

transferDataSendRate

Rate, in kilobits per second, that file data is being sent. This value can be directly compared to transferThroughputRate.

transferFileReadRate

Rate, in kilobits per second, that file data is being read from disk.

transferId

A transfer ID. Transfer IDs are returned from createTransfer(), and used in other methods to refer to a specific transfer.

transferNetSendRate

Raw socket send rate, in kilobits per second.

transferSendRate

Rate, in kilobits per second, that data is being sent, including protocol overhead such as encryption. This value can be compared to the expected link speed.

transferThroughputRate

Rate, in kilobits per second, of file data being received and confirmed as received by the remote server. This value can be directly compared to transferDataSendRate.

transport

The transport this transfer is actually running: 'udp' or 'tcp'. This is what is in effect, not what was requested. The transport belongs to the connection to the destination and is fixed when that connection opens, so a transport route or the fallback from UDP to TCP can give a transfer a different transport from its request. Empty until a connection is up, because until then nothing is running.

urgency

How urgent the transfer is: critical, high, medium, low or idle. More urgent transfers are sent ahead of less urgent ones, and transfers of equal urgency are sent in the order they were requested. Defaults to medium.

userData

Key-value map of user attached metadata. Use updateObjectUserData() and deleteObjectUserData() to manipulate object user data.

Note

For each transfer, the system time is recorded in requestTime. The other times are internally calculated as durations since requestTime, so differences between reported times for a particular transfer will always be accurate.

Times may not compare accurately against your system’s time, the JetStream sender’s current system time, or the times reported for different transfers, since any system can change its system time. A common source of time changes is NTP correcting clock drift.

Changed in version 1.4.3: Added transferSendRate, transferDataSendRate, transferThroughputRate keys.

Changed in version 1.5.1: Added transferFileReadRate, and transferNetSendRate keys.

Changed in version 1.6.1: Added sendRateMax, and priorityLane keys.

Changed in version 1.9.0: Added owner key.

Changed in version 2.4.0: Added ownerToken, ownerTokenSession keys.

Changed in version 3.0.0: Added bytesAcked. Removed blockSize, blocksAcked, blocksRetransmitted, blocksSent and totalBlocks — the transport addresses a transfer by byte offset, not by fixed-size block, so use bytesAcked / bytesSent / totalBytes. Also removed bytesRecv, packetsRecv and packetsSent: these are properties of the network connection rather than of one transfer, and a single connection carries every transfer to a destination. Per-connection counters are on the destination as transportBytesRecv, transportPacketsRecv and transportPacketsSent. Added congestionControl (API 45).

Changed in version 3.0.0: (API 47) Removed priority and priorityLane, replaced by urgency. Priority lanes are gone entirely, along with the priorityLanes key and the send.setPriorityLanesAsync command; send.setTransferPriorityAsync is replaced by send.setTransferUrgencyAsync.

Changed in version 3.0.0: (API 50) Added connectionPath — how the live connection was established (direct / reverse / relay; empty while no connection is up).

Changed in version 3.0.0: (API 47) Added queuePosition, allocationBps and loanBps, and a new status value, waiting. A server with an outgoing bandwidth limit now admits only as many transfers as that limit can run at a guaranteed minimum rate, most urgent first, and holds the rest — so urgency decides who runs, not merely who goes first. sendRateMax on a transfer is enforced from this version.

Changed in version 3.0.0: (API 61) Removed allocationBps and loanBps. The server no longer divides its outgoing bandwidth between transfers, so neither number exists. An outgoing bandwidth limit is now a ceiling on the machine’s total and nothing more, and urgency is enforced by the congestion controller instead: a connection whose transfers are all below the most urgent level in use yields to the traffic that is above it. Read sharing to see that a transfer is giving way, and effectiveRateCapBps to see what is actually limiting it. queuePosition is unchanged and is the only scheduler field left.