RecvInterface¶

class jetstream.recvinterface.RecvInterface(api_interface, sync_interface, _logging_interface)¶: RecvInterface provides methods for controlling aspects of JetStream related to receiving files. RecvInterface is accessed from the APIInterface.

Method Summary¶

`addAuthorizedClientAsync`	Adds a public key to the list of authorized clients.
`addRegistration`	Holds a connection open to a server so that it can send files to this receiver.
`allowOnlyAuthorizedClientsAsync`	Submits a request to enable or disable the restriction to allow only authorized clients to connect to this server.
`getSourcesAsync`	Submits a request to retrieve the sources that have established a connection with this Receiver.
`getTransfersAsync`	Submits a request to retrieve the transfers from a receive server.
`recvDeleteTransfer`	Deletes a incoming (receiving) transfer.
`recvResumeTransferAsync`	Resumes a receiving (incoming) transfer that has been suspended.
`recvSuspendTransferAsync`	Suspends a recveiving (incoming) transfer.
`removeAuthorizedClientAsync`	Removes a public key from the list of authorized clients.
`removeRegistration`	Stops holding a connection open to a server.

Method Documentation¶

RecvInterface.addAuthorizedClientAsync(clientPublicKey)¶

Adds a public key to the list of authorized clients.

If allowOnlyAuthorizedClientsAsync() is used to restrict incoming connections, a Receiver server will allow incoming connections only from trusted clients. Adding a client’s public key will permit it to connect.

If a JetStream server was launched with the --persistent-state-dir flag, its list of authorized clients will be saved, and restored if the server is restarted. If a JetStream server is launched without this flag, its list of authorized clients must be configured again.

Parameters:: clientPublicKey (str) – The public key of an trusted client that is authorized to connect to a Receiver server. Here, “client” refers to a JetStream Sender server. Also allowed is a dict with a string value extracted from the clientPublicKey key.

Note

This is machine-wide security policy, and it is why the command needs super-user rights. It is not how you make a receiver reachable from behind a NAT – that is addRegistration(), which any user may call.

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

RecvInterface.addRegistration(address)¶

Holds a connection open to a server so that it can send files to this receiver.

Use this when this receiver is behind a NAT or a firewall and the other server cannot connect to it. The receiver connects out to that server and keeps the connection. The server then sends through that connection. This is done again automatically if the connection stops, and after a restart.

This does not give the other server permission to do anything. It makes a PATH. A transfer that arrives on it gets the same checks as a transfer on any other path.

Because it is not a permission, any user can call it. It is the opposite of createDestination(): one says “I want to reach that machine”, this one says “let that machine reach me”.

The other server must also permit this receiver to connect, with authorizeReverseReceiver(). Until it does, this receiver tries again and does not succeed.

Parameters:: address (str) – The server to connect to, as host or host:port. The port is the API port of that server if you do not give one.

Example

>>> receiver.addRegistration('sender.example.com')

Added in version 3.0.0.

RecvInterface.allowOnlyAuthorizedClientsAsync(onlyAuthorizedClientsAllowed)¶

Submits a request to enable or disable the restriction to allow only authorized clients to connect to this server.

When enabled, only incoming connections from trusted clients will be accepted. Trusted clients can be added using addAuthorizedClientAsync() and removed using removeAuthorizedClientAsync().

Parameters:: onlyAuthorizedClientsAllowed (bool) – True restricts connections to allow only clients authorized with addAuthorizedClientAsync(). False allows connections from any client. Also allowed is a dict with a bool value extracted from the onlyAuthorizedClientsAllowed key.
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

RecvInterface.getSourcesAsync()¶

Submits a request to retrieve the sources that have established a connection with this Receiver.

A “source” is a sending JetStream, from the viewpoint of the receiver.

Returns:

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

getRequestResult() will return dictionary Source Structure.

Return type:

dict

RecvInterface.getTransfersAsync(getTransferInfo=False)¶

Submits a request to retrieve the transfers from a receive server.

This command differs from getTransfers() in that this result describes the transfers being received on a server. The SendInterface method describes transfers being sent from a server.

Returns:

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

getRequestResult() will return dictionary Receive Transfer Structure.

Return type:

dict

RecvInterface.recvDeleteTransfer(transferId)¶

Deletes a incoming (receiving) transfer.

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

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

RecvInterface.recvResumeTransferAsync(transferId)¶

Resumes a receiving (incoming) transfer that has been suspended.

Resuming a transfer will restore it to the send 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 = recv.resumeTransferAsync(transfer)
{'requestId': 7}
>>> status = send.getRequestStatus(request)
{'status': 'complete', ...}
>>> result = send.getRequestResult(request)
{'transferId': 13}
>>> transfer = send.getTransfer(result)
{'status': 'resuming', ...}

RecvInterface.recvSuspendTransferAsync(transferId)¶

Suspends a recveiving (incoming) transfer.

Suspending a receiving transfer removes it from the send 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 = recv.suspendTransferAsync(transfer)
{'requestId': 7}
>>> status = send.getRequestStatus(request)
{'status': 'complete', ...}
>>> result = send.getRequestResult(request)
{'transferId': 13}
>>> transfer = send.getTransfer(result)
{'status': 'suspended', ...}

RecvInterface.removeAuthorizedClientAsync(clientPublicKey)¶

Removes a public key from the list of authorized clients.

If allowOnlyAuthorizedClientsAsync() is used to restrict incoming connections, a Receiver server will allow incoming connections only from trusted clients. Removing a client’s public key will result in its connections being refused.

If a JetStream server was launched with the --persistent-state-dir flag, its list of authorized clients will be saved, and restored if the server is restarted. If a JetStream server is launched without this flag, its list of authorized clients must be configured again.

Parameters:: clientPublicKey (str) – The public key of an untrusted client that is not authorized to connect to a Receiver server. Here, “client” refers to a JetStream Sender server. Also allowed is a dict with a string value extracted from the clientPublicKey key.
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

RecvInterface.removeRegistration(address)¶

Stops holding a connection open to a server.

The connection stops immediately. That server can no longer send files to this receiver unless it can connect to it directly.

Parameters:: address (str) – The same address you gave to addRegistration().

Added in version 3.0.0.