Destination Structure¶

A Destination structure is returned from createDestination(), getDestination() and getDestinations().

connectionId¶

A connection ID. Connection IDs are returned from getConnection(), and used to refer to a specific connection.

destinationAddress¶

The address (host name) for a destination, as the client gave it. This is an empty string for a destination that has no address. The server reaches such a destination by reverse dial only.

destinationId¶

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

destinationIP¶

The IP for a destination.

destinationPort¶

The UDP receiver port for a destination.

lastDestinationServerId¶

The server instance ID that most recently acknowledged a transmission to a destination. This value may be None if no communication has yet been established.

lastDestinationServerUid¶

The persistent server ID that most recently acknowledged a transmission to a destination. This value may be None if no communication has yet been established.

lastError¶

The last critical error that occurred when connecting to the remote server. None if there are currently no errors.

lastErrorMessage¶

Error message associated with lastError.

lastRecvTime¶

A timestamp indicating the last receive activity. See Timestamps.

lastSendTime¶

A timestamp indicating the last send activity. See Timestamps.

numTransfersQueued¶

The number of transfers waiting in a destination’s queue.

owner¶

The owner of this destination. A destination is only visible to its owner, or a superuser.

ownerToken¶

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

ownerTokenSession¶

The token session of this token that created this destination.

permanent¶

True if garbage collection never removes this destination. Set it with the permanent parameter of createDestination().

permittedDestinationPublicKey¶

The key used to authorize the remote server. If the remote server’s public key doens’t match this key, the connection will not succeed.

receiverEverRegistered¶

Whether that receiver has held a registration with this server at any time. None for a "never" destination.

If receiverRegistered and this field are both False, no receiver with the pinned key has ever connected to this server. Waiting does not correct this. Point the destination at the receiver’s current public key.

receiverRegistered¶

Whether that receiver currently holds a registration with this server. None for a "never" destination, where the question does not apply.

For "always", False means transfers cannot start — check that the receiver is running and is pointed at this server. For "auto" it is not a warning but the deciding value: True means the next connection reverse-dials, False means it connects to the address.

relayIP¶

The IP for the relay server, if using a relay. Will be None if not using a relay.

relayPort¶

The port for the relay server, if using a relay. Will be None if not using a relay.

reverseDial¶

How this destination is reached: "auto", "always" or "never". Reverse dial means the receiver registers with this server and connects out when asked, so nothing connects to the destination address. "auto" — the default — reverse-dials when the receiver is registered at the moment the connection is made, and connects to the address otherwise. See createDestination.

Changed in version 3.0.0: Was a boolean; it is now the mode. What a connection actually did is reported as reverseDial on the connection, which is still a boolean.

roundTripTimeMs¶

The ‘ping time’ between the sender and receiver in milliseconds.

senderIP¶

The IP for the sender connection.

senderPort¶

The port that was given for the sender connection, if one was given.

The sender does not use this port. The operating system gives the sender a port for each transfer. This field shows only what the client asked for.

sendRateAverage¶

The average send rate for a transfer, in kilobits-per-second. This rate represents a “slice” of time, per “send rate average window”.

sendRateMax¶

The maximum send rate allowed for this server. The Rate Controller will not allow the send rate to exceed this value.

snapshotTime¶

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

socketRecvBufferSize¶

The size of the buffer allocated for receiving data.

socketSendBufferSize¶

The size of the buffer allocated for sending data.

transferDefaults¶

Destination Transfer Defaults Structure

transportBandwidthMbps¶

The transport’s own estimate of the path’s available bandwidth, in megabits-per-second. See Transport Counters.

transportBytesInFlight¶

Bytes sent on the wire and not yet acknowledged. See Transport Counters.

transportBytesRecv¶

Total bytes received on this connection, including acknowledgements and protocol overhead. See Transport Counters.

transportBytesSent¶

Total bytes sent on this connection, including retransmissions and protocol overhead. This is larger than the sum of the transfers’ bytesSent, which counts file data only. See Transport Counters.

transportCongestionCount¶

The number of times the transport has entered congestion avoidance. See Transport Counters.

transportCongestionWindow¶

The transport’s current congestion window, in bytes — how much it is willing to have unacknowledged on the path at once. See Transport Counters.

transportHandshakeMs¶

How long the connection’s handshake took, in milliseconds. 0 until the handshake completes. See Transport Counters.

transportIdealBytes¶

How many bytes the transport would need to have available in order not to be limiting throughput. Compare with transportPostedBytes to tell a network-limited transfer from one the application is failing to keep fed. See Transport Counters.

transportLossPct¶

transportPacketsLost as a percentage of transportPacketsSent — measured packet loss on this connection. None when no packets have been sent, because a connection that has sent nothing has no loss rate; do not read that as zero. See Transport Counters.

transportMaxRttMs¶

The largest round-trip time observed on this connection, in milliseconds. See Transport Counters.

transportMinRttMs¶

The smallest round-trip time observed on this connection, in milliseconds — the path’s latency with no queueing. See Transport Counters.

transportPacketsLost¶

Packets the transport sent and determined were lost. Packets first suspected lost and then found to have arrived are not counted, so a merely reordered path does not inflate this figure. See Transport Counters.

transportPacketsRecv¶

Total packets received on this connection. See Transport Counters.

transportPacketsSent¶

Total packets sent on this connection, including retransmissions, acknowledgements and the handshake. See Transport Counters.

transportPathMtu¶

The packet size the transport has settled on for this path, in bytes. See Transport Counters.

transportPersistentCongestionCount¶

The number of times the connection has entered persistent congestion — an extended period with no successful delivery, which is a stronger signal than transportCongestionCount. See Transport Counters.

transportPipeFillPct¶

transportPostedBytes as a percentage of transportIdealBytes, capped at 100 — how well the pipe is being kept full. None when the transport has no estimate yet, which must not be read as 0%. See Transport Counters.

transportPostedBytes¶

Bytes handed to the transport and not yet acknowledged, including those still queued rather than sent. See Transport Counters.

transportRttMs¶

The connection’s current round-trip time, in milliseconds. This is the transport’s measurement, and is not the same as roundTripTimeMs, which is an application-level ping that also reflects whether the remote server is processing. See Transport Counters.

transportRttVarianceMs¶

Variation in the round-trip time, in milliseconds. See Transport Counters.

transportSmoothedRttMs¶

The transport’s smoothed round-trip estimate, in milliseconds — less reactive than transportRttMs. See Transport Counters.

userData¶

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

Transport Counters¶

The transport* keys report what the transport itself measured about the network path to this destination. Three properties apply to all of them, and each one changes how they should be read:

They are connection-scoped, not per-transfer. One connection carries every transfer to a destination, so these counters cover all of them together, and there is no way to attribute a packet to one transfer once it is on the wire. Per-transfer progress is bytesSent/bytesAcked/totalBytes on the Transfer Structure.

A new connection restarts them at zero. They are the current connection’s totals, not the destination’s lifetime totals. If a connection is lost and re-established, the counters you read afterwards are smaller than the ones you read before. Do not compute a rate by differencing two readings without checking they came from the same connection.

``None`` means “not measured”, never “zero”. Every key is always present. All of them are None when no connection has reported — before the first connection is established, and for a destination that is never used. This distinction is deliberate: a link with no measured loss and a link nobody measured are different facts, and the second must not be reportable as the first. Two keys are None in a further case, documented individually: transportLossPct when nothing has been sent, and transportPipeFillPct when the transport has no estimate yet.

They are the sender’s view. transportPacketsLost counts this server’s own outbound packets. Loss on the path to the destination is measured directly; loss on the return path reaches these counters only as loss inferred from missing acknowledgements.

Changed in version 1.6.1: Added priorityLanes keys.

Changed in version 1.7.0: Added lastError, lastErrorMessage, owner, permittedDestinationPublicKey, and userData keys. Removed encryptionMismatch, rateControlActive, rateControlMethod, sendRate, sendRateMin, sendRateAverageWindow, and versionMismatch keys.

Changed in version 2.4.0: Added ownerToken, ownerTokenSession keys.

Changed in version 3.0.0: Added the transport* transport counter keys.

Destination Transfer Defaults Structure¶

A Destination Transfer Defaults structure is returned as part of the Destination Structure.

checkpointFrequencySeconds¶: The default value for the checkpointFrequencySeconds parameter of createTransfer().
fileTimeResolutionMicroseconds¶: The default value for the fileTimeResolutionMicroseconds parameter of createTransfer().
overwriteMode¶: The default value for the overwriteMode parameter of createTransfer().
sendRateMax¶: The default value for the sendRateMax parameter of createTransfer().
transferFlags¶: The default value for the transferFlags parameter of createTransfer().
transport¶: The default value for the transport parameter of createTransfer(): 'udp' or 'tcp'. This is a request, so it is always spelled out. The transfer structure’s field of the same name reports what is running.
urgency¶: The default value for the urgency parameter of createTransfer().

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

Changed in version 1.7.0: Added overwriteMode keys.

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 56) Renamed congestionControl to transport. Its values are 'udp' and 'tcp'.