SendInterface¶

class jetstream.sendinterface.SendInterface(api_interface, sync_interface, logging_interface)¶: SendInterface provides methods for controlling aspects of JetStream related to sending files. SendInterface is accessed from the APIInterface.

Tip

Methods whose names end with Async are asynchronous commands. These commands are sent to the server as a request and queued for processing. Asynchronous methods return a RequestId. Use getRequestStatus() and getRequestResult() to monitor the status of a request.

Method Summary¶

`authorizeReverseReceiver`	Allows a receiver to register with this server, so this server can send to it even though it is behind NAT.
`clearWebLink`	Removes a download token's web link id.
`createDestination`	Adds a new destination to the JetStream server or returns an existing destination with matching parameters.
`createManifest`	Creates a manifest for the provided file mapping.
`createSharedToken`	Creates a shared token for a manifest.
`createTransfer`	Initiates a new transfer from a manifest, to a given destination.
`deleteDestination`	Deletes the specified destination.
`deleteManifest`	Deletes the specified manifest.
`deleteObjectUserData`	Remove a piece of user data associated with a destination, manifest, transfer or shared token.
`deleteSharedToken`	Deletes the specified shared token.
`deleteTransfer`	Deletes a transfer.
`failTransfer`	Causes an active transfer to fail and present the given error message.
`getConnection`	Returns the configuration for a specified connection.
`getConnections`	Returns the current configurations for all known connections.
`getDestination`	Returns the configuration for a specified destination.
`getDestinations`	Returns the current configurations for all known destinations.
`getManifest`	Returns a structure describing the current state of the given manifest.
`getManifestFiles`	Returns the file mappings for a manifest.
`getManifests`	Returns information for all known manifests.
`getReverseReceivers`	Lists the receivers allowed to register with this server, and whether each one is registered right now.
`getSharedToken`	Returns a structure describing a shared token.
`getSharedTokens`	Returns information for all known shared tokens.
`getTransfer`	Returns a structure describing the current state of a transfer.
`getTransfers`	Returns a list of structures describing the state of all transfers.
`getWebDownloads`	Returns the browser downloads of web shares on this server.
`mintWebLink`	Creates a web link id for a download token, so a browser recipient can be sent an ordinary https link instead of being asked to paste a `jetstream://` one.
`resumeTransferAsync`	Resumes a transfer that has been suspended.
`revokeReverseReceiver`	Withdraws a receiver's permission to register with this server.
`schedulePingAsync`	Schedules a series of pings to be sent to a destination.
`setSendRateMaxAsync`	Submits a request to adjust the maximum send rate for the specified destination.
`setTransferSendRateMaxAsync`	Adjusts the maximum send rate of a transfer.
`setTransferUrgencyAsync`	Adjusts the urgency of a transfer.
`suspendTransferAsync`	Suspends a transfer.
`updateConnectionParamsAsync`	Update connection parameters.
`updateObjectUserData`	Add or change a piece of user data associated with a destination, manifest, transfer or shared token.
`updateSharedToken`	Updates the specified shared token.
`updateTransferDefaults`	Sets the default values for new transfers.
`waitForManifest`	Waits for the server to finish processing a manifest.
`waitForTransfer`	Waits for a transfer to finish sending all data.

Method Documentation¶

SendInterface.authorizeReverseReceiver(receiverPublicKey)¶

Allows a receiver to register with this server, so this server can send to it even though it is behind NAT.

A receiver that cannot be dialled – almost every desktop, and any server behind a firewall it does not control – reaches this server instead and holds a channel open. This server then sends down that channel. Registering is refused unless the receiver’s identity key is authorized here, which is what this call does.

Authorization only. It does not make any transfer use reverse dial: a destination decides that per connection from whether its receiver is registered at the time (reverseDial="auto", the default). Nor does it start anything – the receiver must separately be told to register here, with addRegistration().

Idempotent: authorizing an already-authorized receiver succeeds and changes nothing.

Parameters:: receiverPublicKey (str) – The receiver’s public key, from its getServerInfo.

Example

>>> sender.authorizeReverseReceiver(receiver.getServerInfo()['publicKey'])

Added in version 3.0.0.

SendInterface.clearWebLink(token)¶

Removes a download token’s web link id.

This closes the web door only: the jetstream:// link keeps working, and so does the token itself. Idempotent, so a revoke script survives its second run.

Parameters:: token (str, dict) – A Shared Token or Token Structure.
Raises:: CommandError – The shared token was not found, or is not a download token.

Added in version 3.0.0.

SendInterface.createDestination(destinationAddress, sendRateMax=None, destinationPort=None, authenticateDestination=None, destinationPublicKey=None, relayAddress=None, relayPort=None, reverseDial=None, senderPort=None, exclusive=None, permanent=None)¶

Adds a new destination to the JetStream server or returns an existing destination with matching parameters.

A destination describes to JetStream how to configure its send operation such that its data will be successfully retrieved by a JetStream receiver. Fundamentally, a destination is identified by its host name (or IP) and its receiver port.

Note

Creating a destination does not guarantee there is a listening JetStream server at the other end.

Parameters:

destinationAddress (str) – The address (host name or IP) through which to connect to the destination. Pass '' when there is no direct path to the peer – a receiver behind NAT, for instance. Such a destination is reached by reverse dial only and is named by its identity, so it must also pass authenticateDestination and destinationPublicKey, and must not set relayAddress or reverseDial='never'. Requires a server at API 59 or later. Supplying an address behaves exactly as it always has.
sendRateMax (int) – The maximum send rate allowed for this server, in kilobits-per-second. If the destination already exists, then this value is ignored.
destinationPort (int) – The receiver UDP port for a destination.
authenticateDestination (bool) – Only allow connections to a destination with the public key specified by destinationPublicKey.
destinationPublicKey (str) – The public key of the destination to use for authentication.
relayAddress (str) – The address (host name or IP) for the relay server, if using a relay. Otherwise unspecified.
relayPort (int) – The port for the relay server, if using a relay. Otherwise unspecified.
reverseDial (str or bool) –
How this destination is reached. Reverse dial means the receiver holds a registration channel with this server and dials back when asked, so a receiver behind NAT needs no reachable address at all.
- "auto" – the default, and what you almost always want. Reverse-dial the destination if its receiver is registered with this server at the moment the connection is made; dial its address otherwise. Nothing has to be configured for this to work, and nothing is lost when the receiver is directly reachable.
- "always" – require reverse dial. Needs authenticateDestination and destinationPublicKey (the receiver is located by an id derived from its key) and excludes relayAddress; both are rejected at this call rather than at connection time.
- "never" – always dial the address.
True/False are accepted and mean "always"/"never".

The receiver must be authorized to register here first – see authorizeReverseReceiver() – and must itself be told where to register, with addRegistration() or the --recv-relay-host/--recv-relay-port flags. The destination reports reverseDial (the mode) and receiverRegistered (whether that receiver is registered right now, which is what "auto" resolves against).
senderPort (int) – Recorded and echoed back, but NOT bound. Neither transport binds a local port – the TCP data plane dials without one deliberately, and QUIC lets msquic pick an ephemeral port – so this does not control which port the sender sends from. Do not write a firewall rule against it. Historically 0 meant “choose a port” and -1 meant “multiplex the receiver’s port”; both now mean the same thing, because nothing is chosen and nothing is multiplexed.
exclusive (bool) – Create a new destination, even there is an existing one with matching parameters.
permanent (bool) – Do not allow the destination to be garbage collected once all transfers are deleted.

Returns:

Destination Structure

Return type:

dict

Example

>>> sender.createDestination(destinationAddress='receiver01')

Changed in version 1.7.0: Removed sendRateMin, sendRate, encryptionEnabled and tag parameters.

Changed in version 1.7.1: Added exclusive parameter.

Changed in version 2.3.0: Added permanent parameter.

SendInterface.createManifest(fileMappings=None, mappings=None, symlinkOptions=None)¶

Creates a manifest for the provided file mapping.

The creation of a manifest happens immediately. The createManifest() method returns a structure with manifestId, which identifies the new manifest. This manifestId indicates that the JetStream server has started to collect information from the file system for all of the specified files. However, the manifest is not necessarily yet ready for use to create a transfer. If one or more directory paths are specified for the manifest, or a large list of files, then the server must recursively visit each subdirectory and file, which may take some time. You will need to monitor the progress of the manifest to know when the traversal has completed. Use getManifest() or waitForManifest() to monitor the status of a manifest.

Parameters:

fileMappings (dict) – Deprecated. A dictionary mapping source paths to their desired path file name at the destination.
mappings (dict) – A dictionary mapping destination paths to source paths.
symlinkOptions (int) – A bitflag specifying how and whether to follow and copy symlinks during a transfer. If not specified, the default is to copy the contents of file or directory symlinks.

Returns:

Manifest Structure

Return type:

dict

mappings:

A dictionary that maps the desired destination path to a given source path. For example, suppose you want to send the file “readme.txt”. At your location (as the sender), the file exists at the path “/usr/docs”. At its destination, you want the file to be named “introduction.txt” as part of a package below the path “project”. The file mapping would be as follows:

Each source path may be a file or directory and must exist at the time of the call.

Example:

>>> createManifest( mappings={'/project/introduction.txt': '/usr/docs/readme.txt'} )

When the source files do not exist, or the file sizes are known in advance, a manifest that skips all I/O may be created (i.e. no directory traversal or existence checks are run). To do this, specify a mapping with information about the source data:

src: Source file name (it must exist when transfer is started).

size: Size of the source file, specified in bytes.

flags: Specifies whether the entry is a file or directory. Use one of the FILETYPE_* constants (See constants).

access: A string which represents the file permissions. The only recognized access is ‘x’ (executable).

exclude: An array of exclude patterns in the file names i.e. [’.png’, ‘.jpeg’] to exclude them from manifest

include: An array of include patterns in the file name i.e. [’.mp3’, ‘.mov’] to include them in the manifest.

If neither size nor flags is specified, the entry is interpreted to be an empty directory. If flags specifies a directory, size is ignored.

Example:

>>> createManifest( mappings={'/storage/destinationFile.txt': {'src':'/sourceFile.txt', 'size':100}} )

>>> createManifest( mappings={'/project/data/destinationEmptyDir': {'src':'/emptyDir'}} )

>>> createManifest( mappings={'/path/to/destination': {'src':'/path/to/source', exclude: ['*.png', '*.PNG'], include: ['*.mp3']}} )

symlinkOptions can be one of:

SYMLINKS_IGNORE

SYMLINKS_COPY_CONTENTS (default)

>>> createManifest( mappings={'/project/': '/src/project/'}, symlinkOptions=SYMLINKS_IGNORE )

Changed in version 1.8.2: Added symlinkOptions parameter. Added``flags`` and access to mappings.

SendInterface.createSharedToken(manifestId, password=None, downloadLimit=None, timeLimitSeconds=None, description=None)¶

Creates a shared token for a manifest.

The returned structure provides a ‘token’ which may be be used by clients to log on and have access to the manifest.

Parameters:

manifestId (str, dict) – A manifest ID or a Manifest Structure.
password (str) – (optional) A password required to auth this token.
downloadLimit – (optional) Number of times a transfer can be initiated using this token.
timeLimitSeconds – (optional) Number of seconds from now before this token expires.
description – (optional) A description of what this token represents.

Returns:

Token Structure

Return type:

dict

Raises:

CommandError – The manifest was not found.

See also

Shared Links

Added in version 1.4.0.

SendInterface.createTransfer(destinationId, manifestId, destinationPath=None, userName=None, password=None, urgency=None, transferFlags=None, checkpointFrequencySeconds=None, sendRateMax=None, overwriteMode=None, fileTimeResolutionMicroseconds=None, timeoutSeconds=None, userData=None, token=None, transferLog=False, congestionControl=None, transport=None)¶

Initiates a new transfer from a manifest, to a given destination.

The returned structure provides a transferId which may be submitted to getTransfer() in order to track the status of the transfer. Also provided is a processing key that indicates if the transfer is still in progress. The processing key clears to False once the transfer is completed, if it fails, or when it is suspended.

Parameters:

destinationId (str, dict) – A destination ID or a Destination Structure.
manifestId (str, dict) – A manifest ID or a Manifest Structure.
destinationPath – (optional) Specifies a 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.
userName (str) – (optional) User name to authenticate the transfer. The transfer is authenticated by the receiving server. Only one of userName and token should be used.
token (str) – (optional) Token used to authenticate the transfer. The transfer is authenticated by the receiving server. Only one of userName and token should be used.
password (str) – (optional) Password to authenticate the transfer. The transfer is authenticated by the receiving server.
urgency (str) – (optional) How urgent this transfer is: one of critical, high, medium, low or idle. Transfers are served most-urgent first and, within one level, in the order they were requested. Defaults to the destination’s transferDefaults urgency (medium unless changed). May be adjusted at any time using setTransferUrgencyAsync(). On a server with an outgoing bandwidth limit configured, urgency decides which transfers RUN, not merely which goes first: only as many transfers are admitted as the limit can carry at a guaranteed minimum rate, and the rest report a status of waiting until capacity frees. A less urgent transfer gets nothing at all while a more urgent one is running.
transferFlags (int) – (optional) A flag which controls whether to enable writes and reads on the destination.
checkpointFrequencySeconds (int) – (optional) How frequently to take a checkpoint. 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 0 (zero), checkpoints are disabled. If None, the transfer will use the default from the destination.
sendRateMax (float) – (optional) Specifies the maximum transfer rate in kilobits/second. The actual transfer rate may be less depending on the destination settings and network conditions. The maximum send rate may be adjusted at any time using setTransferSendRateMaxAsync(). This is a self-limit: it can hold the transfer below whatever bandwidth the server allocated it, never above.
overwriteMode (int) – (optional) How to handle creating files, if a file with the same name already exists.
fileTimeResolutionMicroseconds (int) – (optional) Files with modification times within the given number of microseconds are considered equal.
timeoutSeconds (float) – (optional) Fail the transfer if it’s disconnected for this many seconds. 0 seconds indicates no timeout.
userData (dict) – (optional) A dictionary of string keys and string values used as the initial user data of the transfer.
transferLog (bool) – (optional) A flag which enable the creation of individual transfer log data. The server must have enabled the option –log-transfer-dir.
transport (str) – (optional) 'udp' (default: QUIC over UDP with JetStream’s own congestion controller) or 'tcp' (the TLS-over-TCP data plane, for a network that will not pass UDP). Any other value is rejected, except the retired spellings 'auto', 'bbr' and 'cubic', which are accepted as aliases of 'udp'. Applied only if this transfer opens the connection to the destination: the transport belongs to the connection and cannot be changed while it is up, so a transfer joining an existing connection runs whatever that connection runs. The transport actually in effect is reported as transport in the transfer structure, beside requestedTransport, which is always spelled out ('udp' or 'tcp') and is what this transfer asked for.
congestionControl (str) – (optional) Deprecated name for transport (API 45-55); ignored when transport is given.

Returns:

Transfer Structure

Return type:

dict

Raises:

CommandError – The destination or manifest was not found, or transport was not one of the accepted values.

transferFlags can be one of:

overwriteMode can be one of:

Tip

Use getpass.getuser() to auto-fill the userName parameter.

Use getpass.getpass() to prompt for the password parameter interactively.

Changed in version 1.7.0: Added overwriteMode parameters.

Changed in version 2.3.0: Added TRANSFER_FLAG_WRITE_MTIME and TRANSFER_FLAG_WRITE_ONLY_NEWER transferFlags. Renamed several overwrite modes. Added fileTimeResolutionMicroseconds, timeoutSeconds and userData.

Changed in version 2.4.0: Added token parameter.

Changed in version 3.0.0: Added congestionControl parameter (API 45); renamed transport with values udp|tcp (API 56).

SendInterface.deleteDestination(destinationId)¶

Deletes the specified destination.

This deletes all transfers associated with the destination. If the destination is recreated, any transfers will need to be recreated, as well.

Note

A destination may not be deleted while any transfers are active. You must delete any active transfers first.

Parameters:: destinationId (str, dict) – A destination ID or a Destination Structure.
Returns:: None
Raises:: CommandError – The destination was not found.

SendInterface.deleteManifest(manifestId)¶

Deletes the specified manifest.

A manifest may be deleted at any time, even if it has been used to initiate a transfer which is currently active.

Parameters:: manifestId (str, dict) – A manifest ID or a Manifest Structure.
Returns:: None
Raises:: CommandError – The manifest was not found.

SendInterface.deleteObjectUserData(objId, key)¶

Remove a piece of user data associated with a destination, manifest, transfer or shared token.

Parameters:: id (int, dict) – An object ID or a structure (Destination Structure, Manifest Structure, Transfer Structure, Token Structure)
Returns:: None
Raises:: CommandError – The user data could not be deleted.

Added in version 1.4.1.

SendInterface.deleteSharedToken(token)¶

Deletes the specified shared token.

A shared token may be deleted at any time, even if it is currently being used as part of a transfer or log in session. The active transfer will continue and will not be terminated.

Parameters:: token (str, dict) – A Shared Token or Token Structure.
Returns:: None
Raises:: CommandError – The shared token was not found.

Added in version 1.4.0.

SendInterface.deleteTransfer(transferId)¶

Deletes a transfer.

A transfer may not be deleted while it is active. You must first suspend it using suspendTransferAsync().

Parameters:: transferId (int, dict) – A transfer ID or a Transfer Structure.
Returns:: None
Raises:: CommandError – The transfer was not found.

SendInterface.failTransfer(transferId, errorMessage=None)¶

Causes an active transfer to fail and present the given error message.

Parameters:

transferId (int, dict) – A transfer ID or a Transfer Structure.
errorMessage (string, optional) – A message describing why the transfer failed.

Returns:

None

Raises:

CommandError – The transfer was not found.

Added in version 1.4.1.

SendInterface.getConnection(connectionId)¶

Returns the configuration for a specified connection.

A connection describes amalgamate configuration information and performance statistics shared by destinations which connect to the same server.

Parameters:: connectionId (int, dict) – A connection ID or a Connection Structure.
Returns:: Connection Structure
Return type:: dict

Added in version 1.7.0.

SendInterface.getConnections(limit=0)¶

Returns the current configurations for all known connections.

A connection describes amalgamate configuration information and performance statistics shared by destinations which connect to the same server.

Parameters:: limit (int) – (optional) The maximum number of results to retrieve. If not specified, all available connections are returned.
Returns:: A list of connection structures, each describing a connection.
Return type:: list

Added in version 1.7.0.

SendInterface.getDestination(destinationId)¶

Returns the configuration for a specified destination.

Parameters:: destinationId (str, dict) – A destination ID or a Destination Structure.
Returns:: Destination Structure
Return type:: dict
Raises:: CommandError – The destination was not found.

SendInterface.getDestinations(limit=0)¶

Returns the current configurations for all known destinations.

Parameters:: limit (int) – (optional) The maximum number of results to retrieve. If not specified, all available transfers are returned.
Returns:: A list of destination structures, each describing a destination.
Return type:: list

SendInterface.getManifest(manifestId)¶

Returns a structure describing the current state of the given manifest.

Parameters:: manifestId (str, dict) – A manifest ID or a Manifest Structure.
Returns:: Manifest Structure
Return type:: dict
Raises:: CommandError – The manifest was not found.

Tip

The status field in the returned structure may be used to determine whether the server is still processing the manifest. Please refer to Manifest Structure for list of possible values and their meaning.

SendInterface.getManifestFiles(manifestId, limit=None)¶

Returns the file mappings for a manifest.

Parameters:: manifestId (str, dict) – A manifest ID or a Manifest Structure.
Returns:: Manifest Files Structure
Return type:: dict
Raises:: CommandError – The manifest was not found.

SendInterface.getManifests(before=None, after=None, limit=None)¶

Returns information for all known manifests.

Parameters:

before (str, dict) – (optional) This expects a manifest ID. If specified, filter results to include only manifests before this manifest ID. The specified manifest ID will not be included in the result. Also allowed is the full dict representating a manifest structure, as from createManifest().
after (str, dict) – (optional) This expects a manifest ID. If specified, filter results to include only manifests after this manifest ID. The specified manifest ID will not be included in the result. Also allowed is the full dict representating a manifest structure, as from createManifest().
limit (int) – (optional) The maximum number of results to retrieve. If not specified, all available manifests are returned.

Returns:

A list of manifest structures, each describing a manifest.

Return type:

list

SendInterface.getReverseReceivers()¶

Lists the receivers allowed to register with this server, and whether each one is registered right now.

Returns:: One dict per receiver, with receiverPublicKey, rendezvousId and registered. registered is the live fact a reverseDial="auto" destination resolves against, and the first thing to check when a transfer to a NAT’d receiver will not start.
Return type:: list

Added in version 3.0.0.

SendInterface.getSharedToken(token)¶

Returns a structure describing a shared token.

Parameters:: token (str, dict) – A Shared Token or Token Structure.
Returns:: Token Structure
Return type:: dict
Raises:: CommandError – The shared token was not found.

See also

Shared Links

Added in version 1.4.0.

SendInterface.getSharedTokens(limit=None)¶

Returns information for all known shared tokens.

Parameters:: limit (int) – (optional) The maximum number of results to retrieve. If not specified, all available shared tokens are returned.
Returns:: A list of shared token structures, each describing a shared token.
Return type:: list

See also

Shared Links

Added in version 1.4.0.

SendInterface.getTransfer(transferId, getCompleteFlags=None)¶

Returns a structure describing the current state of a transfer.

Parameters:

transferId (int, dict) – A transfer ID or a Transfer Structure.
getCompleteFlags (bool) – (optional) True request the transfer complete file flags, False don’t request file flags.

Returns:

Transfer Structure

Return type:

dict

Raises:

CommandError – The transfer was not found.

Tip

The status field in the returned structure may be used to determine the state of the transfer. Please refer to Transfer Structure for list of possible values and their meaning.

See also

Timestamps

SendInterface.getTransfers(destinationId=None, before=None, after=None, limit=None)¶

Returns a list of structures describing the state of all transfers.

If the optional destinationId parameter is specified, the results are limited to only the transfers for the given destination. Otherwise, all transfers are returned.

Parameters:

destinationId (str, dict) – (optional) A destination ID or a Destination Structure.
before (str, dict) – (optional) A transfer ID or a Transfer Structure. If specified, filter results to include only transfers before this transferId. The specified transfer ID will not be included in the result.
after (str, dict) – (optional) A transfer ID or a Transfer Structure. If specified, filter results to include only transfers after this transferId. The specified transfer ID will not be included in the result.
limit (int) – (optional) The maximum number of results to retrieve. If not specified, all available transfers are returned.

Returns:

A list of transfer structures, each describing a transfer.

Return type:

list

Raises:

CommandError – The destination was not found.

SendInterface.getWebDownloads()¶

Returns the browser downloads of web shares on this server.

A recipient with no JetStream software downloads a share in a browser, and those downloads do not appear in getTransfers(): they are not transfers – they have no destination, no manifest send and no receiver. This command reports them so an administrator can see and manage them beside real transfers.

One row per DOWNLOAD, not per unlock. A download interrupted and resumed keeps its transferId and reports resumed as True, and a recipient downloading three files has three rows. Rows for finished downloads are kept until 256 newer ones replace them; there is no time limit.

A wrangler sees every row. Any other user sees only rows for shares they own. A token user sees none. The list is empty on a server started without --web-share-port.

Returns:

A list of dictionaries, each describing one browser download:

kind: Always "web", which is what tells this apart from a transfer.
transferId: The download’s own ID. Stable across a resume.
status: sending, complete or error, spelled as a transfer’s status is.
errorMessage: Present only when the status is error.
route: file for one file, archive for a Download all.
name: The file’s name, or files.zip for an archive.
clientAddress: The recipient’s address, as the reverse proxy reported it.
owner: The user who created the share.
resumed: True when this download was interrupted and continued.
transport: Always "https". These bytes went over the web share tier’s own socket.
bytesSent, totalBytes: Progress, in bytes.
transferThroughputRate: Bytes per second, measured over the last second or more.
startTime, endTime: Microseconds since the epoch. endTime is None while the download runs.

Return type:

list

Added in version 3.0.0: API 59.

SendInterface.mintWebLink(token)¶

Creates a web link id for a download token, so a browser recipient can be sent an ordinary https link instead of being asked to paste a jetstream:// one.

The id is a fresh 128-bit random value stored beside the token, absent unless you ask for one – a share created for client recipients acquires no web-reachable identifier at all. It is not the token and cannot be presented to auth: it names the share, and the server resolves it. Minting REPLACES any existing id, so this is also how a link is rotated.

The recipient opens <web share origin>/l/<webLinkId>. The origin is reported by getServerInfo() as serverWebShareUrl.

Parameters:: token (str, dict) – A Shared Token or Token Structure.
Returns:: {'webLinkId': str}
Return type:: dict
Raises:: CommandError – The shared token was not found, or is not a download token.

Note

For a share with no passphrase the link is the whole credential, exactly as the jetstream:// link is: anyone holding it can download.

Added in version 3.0.0.

SendInterface.resumeTransferAsync(transferId)¶

Resumes a transfer that has been suspended.

Resuming a transfer will restore it to the server’s processing queue, and it will resume sending data to its destination.

Resuming a transfer moves the transfer back in the processing queue. The transfer may not resume sending files immediately, depending on the traffic from other ongoing transfers. Use getTransfer() or waitForTransfer() to monitor the status of the transfer.

Only suspended transfers can be resumed. If a transfer is already complete, or has failed, this request will fail.

Parameters:

transferId (int, dict) – A transfer ID or a Transfer Structure.

Returns:

Request Structure containing a requestId for this request. Use getRequestStatus() or getRequestResult() to monitor the status of the request.

getRequestResult() will return Transfer Structure.

Return type:

dict

Raises:

CommandError – The transfer was not found, or could not be resumed.

Example

>>> request = send.resumeTransferAsync(transfer)
{'requestId': 7}
>>> status = send.getRequestStatus(request)
{'status': 'complete', ...}
>>> result = send.getRequestResult(request)
{'transferId': 13}
>>> transfer = send.getTransfer(result)
{'status': 'resuming', ...}

SendInterface.revokeReverseReceiver(receiverPublicKey)¶

Withdraws a receiver’s permission to register with this server.

Takes effect within seconds on a channel that is already open, not only on the next attempt: held registrations are re-checked against the authorized set, and one that is no longer authorized is dropped.

Parameters:: receiverPublicKey (str) – The receiver’s public key.

Added in version 3.0.0.

SendInterface.schedulePingAsync(destinationId, pingCount)¶

Schedules a series of pings to be sent to a destination.

Pings are scheduled and interleaved into the transmission protocol at a regulated frequency. A response is assigned to the Destination as ‘lastReceiverDestinationId’. Use getDestination to monitor a ping response.

Parameters:

destinationId (str, dict) – A destination ID or a Destination Structure.
pingCount – The number of pings to send.

Returns:

Returns a Request Structure containing a requestId for this request. Use getRequestStatus() or getRequestResult() to monitor the status of the request.

Return type:

dict

Raises:

CommandError – The destination was not found.

SendInterface.setSendRateMaxAsync(destinationId, sendRateMax)¶

Submits a request to adjust the maximum send rate for the specified destination.

When the maximum send rate is adjusted, the minimum send rate and actual send rate will also be adjusted, if necessary, so as not to exceed the maximum rate.

Parameters:

destinationId (str, dict) – A destination ID or a Destination Structure.
sendRateMax (float) – The maximum send rate that will be allowed by the JetStream rate controller, in kilobits/second.

Returns:

Returns a Request Structure containing a requestId for this request. Use getRequestStatus() or getRequestResult() to monitor the status of the request.

Return type:

dict

Example

>>> request = send.setSendRateAsync(destinationId, sendRate=750000)
{'requestId': 1}
>>> result = send.getRequestResult(request)
{'sendRateMax': 750000.0}

SendInterface.setTransferSendRateMaxAsync(transferId, sendRateMax)¶

Adjusts the maximum send rate of a transfer.

The actual transfer rate of a transfer may be less depending on the destination settings and network conditions. A rate of -1 turns off rate throttling for this transfer.

Parameters:

transferId (int, dict) – A transfer ID or a Transfer Structure.
sendRateMax (float) – Specifies the maximum transfer rate in kilobits/second.

Returns:

Returns a Request Structure containing a requestId for this request. Use getRequestStatus() or getRequestResult() to monitor the status of the request.

Return type:

dict

Result:: dict: getRequestResult() yields a dict with the commited sendRateMax value.

Raises:: CommandError – The transfer was not found.

Added in version 1.6.1.

SendInterface.setTransferUrgencyAsync(transferId, urgency)¶

Adjusts the urgency of a transfer.

Urgency is how the server decides what to send: transfers are served most-urgent first, and within one level in the order they were requested. It is the only ordering input – it replaced both priority lanes and the numeric priority in API 47.

Parameters:

transferId (int, dict) – A transfer ID or a Transfer Structure.
urgency (str) – One of critical, high, medium, low or idle. Required; unrecognised values are rejected rather than defaulted.

Returns:

Returns a Request Structure containing a requestId for this request. Use getRequestStatus() or getRequestResult() to monitor the status of the request.

Return type:

dict

Result:: dict: getRequestResult() yields a dict with the transferId. Use getTransfer() to retrieve the full Transfer Structure.

Raises:

CommandError – An invalid urgency was specified.
CommandError – The transfer was not found.

Added in version 3.0.0.

SendInterface.suspendTransferAsync(transferId)¶

Suspends a transfer.

Suspending a transfer removes it from the server’s processing queue, and it will stop sending data to its destination. The transfer is kept in its current (incomplete) state until it is resumed, or deleted.

Only active transfers can be suspended. If a transfer is already complete, or has failed, this request will fail.

Parameters:

transferId (int, dict) – A transfer ID or a Transfer Structure.

Returns:

Request Structure containing a requestId for this request. Use getRequestStatus() or getRequestResult() to monitor the status of the request.

getRequestResult() will return Transfer Structure.

Return type:

dict

Raises:

CommandError – The transfer was not found, or could not be suspended.

Example

>>> request = send.suspendTransferAsync(transfer)
{'requestId': 7}
>>> status = send.getRequestStatus(request)
{'status': 'complete', ...}
>>> result = send.getRequestResult(request)
{'transferId': 13}
>>> transfer = send.getTransfer(result)
{'status': 'suspended', ...}

SendInterface.updateConnectionParamsAsync(connectionId, sendRateMax=None)¶

Update connection parameters.

Parameters:

connectionId (str, dict) – A connection ID or a structure Connection Structure
sendRateMax (float) – The maximum send rate allowed for this connection, in kilobits-per-second. This is an app-layer pacing ceiling above the transport’s own congestion control.

Returns:

None

Raises:

CommandError – The connection was not found.

Added in version 1.7.0.

SendInterface.updateObjectUserData(objId, key, value=None)¶

Add or change a piece of user data associated with a destination, manifest, transfer or shared token.

Parameters:

id (str, dict) – An object ID or a structure (Destination Structure, Manifest Structure, Transfer Structure, Token Structure)
value (string) – (optional) The value to associated with the key.

Returns:

None

Raises:

CommandError – The user data could not be added or changed.

Added in version 1.4.1.

SendInterface.updateSharedToken(token, timeLimitSeconds=None, description=None)¶

Updates the specified shared token.

Parameters:

token (str, dict) – A Shared Token or Token Structure.
timeLimitSeconds – (optional) Number of seconds from now before this token expires.
description – (optional) A description of what this token represents.

Returns:

None

Raises:

CommandError – The shared token was not found.

Added in version 2.6.0.

SendInterface.updateTransferDefaults(destinationId, urgency=None, transferFlags=None, checkpointFrequencySeconds=None, sendRateMax=None, overwriteMode=None, fileTimeResolutionMicroseconds=None, congestionControl=None, transport=None)¶

Sets the default values for new transfers.

Set the default values used when creating new transfer with createTransfer(). Only parameters that not None will be modified. See createTransfer() for more details on the parameters.

Parameters:

destinationId (str, dict) – A destination ID or a Destination Structure.
urgency (str) – (optional) Default urgency for new transfers to this destination: one of critical, high, medium, low or idle.
transferFlags – (optional) A flag which controls whether to enable writes and reads on the destination.
checkpointFrequencySeconds – (optional) How frequently to take a checkpoint. If 0 (zero), checkpoints are disabled.
sendRateMax – (optional) Maximum transfer rate in kilobits/second.
overwriteMode – (optional) How to handle creating files if a file with the same name already exists.
fileTimeResolutionMicroseconds (int) – (optional) Files with modification times within the given number of microseconds are considered equal.
transport (str) – (optional) Default transport for new transfers to this destination: 'udp' (QUIC over UDP with JetStream’s own congestion controller; the default) or 'tcp' (the TLS-over-TCP data plane). Any other value is rejected, except the retired spellings 'auto', 'bbr' and 'cubic', accepted as aliases of 'udp'. This is the default REQUEST; what a transfer actually runs is reported per transfer.
congestionControl (str) – (optional) Deprecated name for transport (API 45-55); ignored when transport is given.

Returns:

None

Raises:

CommandError – The destination was not found, or transport was not one of the accepted values.

Changed in version 1.7.0: Added overwriteMode parameter.

Changed in version 3.0.0: Added congestionControl parameter (API 45); renamed transport with values udp|tcp (API 56).

SendInterface.waitForManifest(manifestId)¶

Waits for the server to finish processing a manifest.

After a manifest is created, the server must recursively visit each subdirectory and file in the specified file mapping, which may take some time. This method may be used to wait until server has finished initializing the manifest.

Note

This method will block until the manifest is complete.

Parameters:: manifestId (str, dict) – A manifest ID or a Manifest Structure.
Returns:: Manifest Structure
Return type:: dict
Raises:: CommandError – The manifest was not found.

SendInterface.waitForTransfer(transferId)¶

Waits for a transfer to finish sending all data.

After a transfer is created, it may take some time to send its files to the destination. waitForTransfer() may be used to wait until a transfer has finished sending all files.

Note

This method will block until the transfer is complete.

Parameters:: transferId (int, dict) – A transfer ID or a Transfer Structure.
Returns:: Transfer Structure. The status field will indicate that the transfer is complete.
Return type:: dict
Raises:: CommandError – The transfer was not found.