ServerInterface¶

class jetstream.serverinterface.ServerInterface(api_interface, sync_interface, logging_interface)¶

Method Summary¶

`auth`	Authenticates a user.
`authAsync`	Authenticates a user.
`authToken`	Authenticates using a shared token.
`deleteSandboxMapping`	Deletes the sandbox mappings for a user.
`duAsync`	Submits a request to retrieve the total size, in bytes, for all files in the specified remote path, as visible to the connected server.
`echo`	Sends the (optionally) given text to the server, and returns it from the server.
`garbageCollect`	Initiates an immediate garbage collection on the connected server.
`getEventLog`	Returns the JetStream event log.
`getRequestResult`	Returns the result for an asynchronous request.
`getRequestStatus`	Returns the status for an asynchronous request.
`getSandboxMappings`	Gets the sandbox mappings for all users.
`getServerInfo`	Returns information about the connected server, including its name and API version.
`getThirdPartyLicenses`	Returns the licenses for third-party software components used by JetStream.
`lsAsync`	Submits a request to retrieve a list of remote files, as visible to the connected server.
`lsRootsAsync`	Submits a request to retrieve a list of the root folders, as visible to the connected server.
`mkdirAsync`	Submits a request to create a new directory on the connected server, creating all parent directories as needed.
`mvAsync`	Submits a request to move or rename a path on the connected server.
`recvDiscoverPacketAsync`	Creates a request to wait for an incoming receiver discovery packet.
`rmAsync`	Submits a request to remove a path on the connected server.
`sendDiscoverPacketAsync`	Sends a discovery packet to a waiting server.
`setLicenseKeyAsync`	Submits a request to set the license key for the server.
`setSandboxMapping`	Sets the sandbox mappings for a user.
`sleep`	Sleep for specified number of miliseconds.
`superuser`	Gives a user permission to access and modify all data.
`terminate`	Terminate the server.
`updateBandwidthLimits`	Sets limits on incoming and outgoing bandwidth utilization.
`updateGarbageCollectSettings`	Updates garbage collection.

Method Documentation¶

ServerInterface.auth(userName, password)¶

Authenticates a user.

Helper method for authAsync() to make the call synchronous.

Parameters:	userName (string) – Name of the user on the JetStream server. password (string) – Password for the user above. Pass in getpass.getpass() if you wish to input the password interactively.
Returns:	None
Raises:	`CommandError` – On auth failure

ServerInterface.authAsync(userName=None, password=None, token=None, tokenSession=None)¶

Authenticates a user.

If the JetStream server is running as root or daemon, you must call either auth() or authAsync() after calling connect(), before any other method is called (except getServerInfo())

Parameters:

userName (string) – Name of the user on the JetStream server. Must be None if token is set.
password (string) – Password for the user or token.
token (string) – Shared token. Must be None if userName is set.
tokenSession (string) – Shared token session. If token is set, this parameter specifies the optional session. Sharing a session between two token authed connections allows them to share data such as transfers. If tokenSession is not specified, one will be generated automatically. The current token session is returned by getServerInfo().

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 None on success, or raise a CommandError.

Return type:

dict

Tip

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

Changed in version 1.4.1: Multiple calls to authAsync are allowed on single API connection.

ServerInterface.authToken(token, password=None, tokenSession=None)¶

Authenticates using a shared token.

Helper method for authAsync() to make the call synchronous.

Parameters:	token (string) – Shared token as generated by `createSharedToken()` password (string) – Password for the token above. Pass in getpass.getpass() if you wish to input the password interactively. tokenSession (string) – Shared token session. If `token` is set, this parameter specifies the optional session. Sharing a session between two token authed connections allows them to share data such as transfers. If `tokenSession` is not specified, one will be generated automatically. The current token session is returned by `getServerInfo()`.
Returns:	None
Raises:	`CommandError` – On auth failure

ServerInterface.deleteSandboxMapping(userName)¶

Deletes the sandbox mappings for a user.

Sandbox mappings can only be modified by a superuser.

Warning

Deleted sandbox mapping only take effect for new user sessions. Existing user sessions will not be affected.

See Sandboxing in JetStream Server Documentation.

Parameters:	userName (string) – The user name of the user to sandbox. Note that the user name may be left blank to indicates the system sandbox.
Returns:	None
Raises:	`CommandError` – If the user is not granted superuser privileges, or no sandbox exists for the user.

New in version 1.5.0.

ServerInterface.duAsync(path)¶

Submits a request to retrieve the total size, in bytes, for all files in the specified remote path, as visible to the connected server.

The result is provided as a dictionary with a single key:

du: The total size, in bytes, collected from the specified path.

Parameters:	path (string) – The remote path to enumerate on the connected server.
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

ServerInterface.echo(text=None)¶

Sends the (optionally) given text to the server, and returns it from the server.

Tip

This method can be used to check if the API connection is still active.

Parameters:	text (string) – Optional text to be echoed by the server.
Returns:	None if not input text given, or the given text.
Return type:	None, str

ServerInterface.garbageCollect(force=False)¶

Initiates an immediate garbage collection on the connected server.

A periodic garbage collection is automatically performed on the server. This causes an immediate garbage collection, with the option to override the allowed grace period.

A garbage collection can only be initiated by a superuser.

Parameters:	force – (optional) If set, disregards the grace period for items that are ready to be garbage collected and discard immediately. Default is False.
Raises:	`CommandError` – If the user is not granted superuser privileges.

New in version 1.8.0.

ServerInterface.getEventLog(eventName=None, before=None, after=None, limit=None)¶

Returns the JetStream event log.

The log is retrieved chronologically, ordered oldest event to newest. Optional parameters may be provided to filter which events are retrieved.

Parameters:	eventName (str) – (optional) Filters the results to include only this event type. If None, retrieve all events. before (int) – (optional) Filters the results to include only events before this time. If None, retrieve all entries to the end of the log. after (int) – (optional) Filters the results to include only events after this time. If None, retrieve all entries from the start of the log. limit (int) – (optional) The maximum number of log entries to retrieve. If None, retrieve all entries.
Returns:	Dictionary with an `eventLog` key containing a list of event log structures.
Return type:	dict

Example

>>> api.server.getEventLog()
{'eventLog': [{'_event': 'serverStarted', '_timestamp': 1485547699055816},
              {'_event': 'destinationCreated',
               '_timestamp': 1485547708422759,
               'destinationId': '127.0.0.1:8886'}
             ]
}

Changed in version 1.3.0: Added limit parameter. Returns items owned by authenticated user only, unless superuser.

ServerInterface.getRequestResult(requestId)¶

Returns the result for an asynchronous request.

API methods whose name ends with Async represent asynchronous requests. These methods are sent a request which must be processed by the destination server, and return a requestId.

getRequestResult() returns the result from an asynchronous request, where the request is identified with its requestId.

If the request is not yet complete, this blocks until the result is available.

If a request fails, getRequestResult() will yield None. Use getRequestStatus() to determine the cause of the failure.

Note

Allowing the results from asynchronous requests to be retrieved at an arbitrary time means that the result must be cached on the server. To avoid resource exhaustion, requests are set to expire after a period a time. Once expired, a request is no longer available.

Parameters:	requestId (int, dict) – A request ID or Request Structure.
Returns:	A dictionary describing the result from the request. The structure of the result varies depending on which API method initiated the request.
Return type:	dict, None
Raises:	`CommandError` – The request was not found, either expired, or never issued. `CommandError` – If the API method that initiated this request resulted in an error.

ServerInterface.getRequestStatus(requestId)¶

Returns the status for an asynchronous request.

API methods whose name ends with Async represent asynchronous requests. These methods are sent a request which must be processed by the destination server, and return a requestId.

getRequestStatus() returns the current status for an asynchronous request, where the request is identified with its requestId. When an asynchronous request is complete, its result is available to getRequestResult().

Note

Allowing the results from asynchronous requests to be retrieved at an arbitrary time means that the result must be cached on the server. To avoid resource exhaustion, requests are set to expire after a period a time. Once expired, a request is no longer available.

The status field in the result indicates whether the request was successful. It may be one of three values:

pending: The request has not yet been processed.

success: The request was successful.

error: An unrecoverable error has terminated the request.

You may use the pending status to implement your own asynchronous poll behavior while your script waits for the request to be processed.

If the status is error then the errorMessage field contains a description of the error.

Parameters:	requestId (int, dict) – A request ID, as returned from any of the `Async` methods. Also allowed is the full dict from an `Async` method. The request ID is extracted from the `requestId` key.
Returns:	Request Structure
Return type:	dict
Raises:	`CommandError` – The request was not found, either expired, or never issued.

ServerInterface.getSandboxMappings()¶

Gets the sandbox mappings for all users.

Sandbox mappings can only be accessed by a superuser.

See Sandboxing in JetStream Server Documentation.

Returns:	Returns a dictionary that maps user names to sandbox mappings, where a sandbox mapping is a dictionary that maps sandbox names to sandbox paths.
Return type:	dict
Raises:	`CommandError` – If the user is not granted superuser privileges.

New in version 1.5.0.

ServerInterface.getServerInfo()¶

Returns information about the connected server, including its name and API version.

Tip

This method does not require authentication.

Returns:	Server Information Structure
Return type:	dict

Changed in version 1.5.0: Renamed username to userName in return structure. Added version and revision to return structure

ServerInterface.getThirdPartyLicenses()¶

Returns the licenses for third-party software components used by JetStream.

Returns:	Library name, license text.
Return type:	dict

ServerInterface.lsAsync(path, directory=False)¶

Submits a request to retrieve a list of remote files, as visible to the connected server.

The result is provided as a dictionary with two keys:

path: The path to the directory being listed.

files: The stats for the requested files.

Each item in the “file” list is a dictionary containing the following keys:

name: The name of the file. To build the full path, join the parent path with this name.

type: Whether this file is a regular file (4), a directory (2) or a symlink (5).

size: The size, in bytes, of a regular file. For a directory or symlink, this will be 0 (zero).

mtime: The file’s last modification time. Use time.ctime to convert to a human readable form.

access: Combined read (1 << 2), write (1 << 1) and execute (1 << 0) bits that describes the current user’s access to this file.

Parameters:	path (string) – The remote path to list on the connected server. directory (bool) – (optional) If True, the specified path is a directory, and the result should return information about the directory itself, rather than the content of the directory.
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

ServerInterface.lsRootsAsync()¶

Submits a request to retrieve a list of the root folders, as visible to the connected server.

The result is provided as a dictionary with two keys:

path: Representing the parent of the root folder, this will be an empty string.

files: The stats for each root folder.

Each item in the “file” list is a dictionary containing the following keys:

name: The name of the root folder.

type: 10, combining drive (8) and directory (2).

size: 0 (zero).

mtime: The folder’s last modification time. Use time.ctime to convert to a human readable form.

access: Combined read (1 << 2), write (1 << 1) and execute (1 << 0) bits that describes the current user’s access to this root.

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

ServerInterface.mkdirAsync(path)¶

Submits a request to create a new directory on the connected server, creating all parent directories as needed.

Tip

This will not fail if the requested directory already exists.

Parameters:	path (string) – The remote path to create on the connected 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 `None` on success, or raise a `CommandError`.
Return type:	dict

New in version 1.3.0.

Changed in version 1.8.0: Removed parents parameter. Parent directories are always created.

ServerInterface.mvAsync(path, newPath)¶

Submits a request to move or rename a path on the connected server.

Parameters:

path (string) – The remote path to create on the connected server.
newPath (string) – The new name for the path.

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 None on success, or raise a CommandError.

Return type:

dict

New in version 1.5.0.

ServerInterface.recvDiscoverPacketAsync(timeoutSeconds=None)¶

Creates a request to wait for an incoming receiver discovery packet.

A JetStream server may not know its address and port as visible to another. This function creates a token called a discover id and then waits for another server to send it a special packet that contains this data. Upon receipt, this server can derive the address of the server that sent the data. The server whose address is being discovered should send the discover id using sendDiscoverPacketAsync().

Parameters:	timeoutSeconds (float) – (optional) The number of seconds to wait for an incoming discover packet. If unused, a default timeout is used.
Returns:	Returns a Request Structure containing a `requestId` for this request. Use `getRequestStatus()` or `getRequestResult()` to monitor the status of the request. The dict additionally contains a `discoverId` key for use with `sendDiscoverPacketAsync()`. Ultimately, the result from the async function will be a Discover Packet Structure. `getRequestResult()` will return dictionary Discover Packet Structure.
Return type:	dict

Example

# Server A wants to transfer data to B, but does not know B's public address.
# We do, however, have API access to both server A and B, and we know A's public address.
# Server A can "discover" B's address as follows:

# 1. Ask server A to listen for a discover packet.
>>> recvRequest = A.server.recvDiscoverPacketAsync()
>>> discoverId = recvRequest['discoverId']

# 2. Ask server B to send a discover packet using the return value form recvDiscoverPacketAsync.
>>> sendRequest = B.server.sendDiscoverPacketAsync(discoverId, A_addr, A_port)
>>> B.server.getRequestResult(sendRequest)
{'discoverPacketSent': True}

# 3. Wait for the discovery packet to be received or a timeout. On success, returns the address of B.
>>> A.server.getRequestResult(recvRequest)
{'port': 54946, 'address': '10.96.64.60'}

ServerInterface.rmAsync(path)¶

Submits a request to remove a path on the connected server. If the path refers to a directory, all files and directories under that path will be removed.

Parameters:	path (string) – The remote path to remove on the connected 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 `None` on success, or raise a `CommandError`.
Return type:	dict

New in version 1.5.0.

ServerInterface.sendDiscoverPacketAsync(discoverId, destinationAddress, destinationPort=None)¶

Sends a discovery packet to a waiting server.

A JetStream server may not know its address and port as visible to another. This function sends a special packet to another server to allow that server to discover this server’s receiving address and port. This function must be used in conjunction with recvDiscoverPacketAsync(). See that function for a usage example.

Parameters:	discoverId (int, dict) – A discover id as returned by `recvDiscoverPacketAsync()`. Also allowed is the full dict from `recvDiscoverPacketAsync()`. The discover ID is extracted from the `discoverId` key. destinationAddress (str) – The host name or IP of the server that called `recvDiscoverPacketAsync()`. destinationPort (int) – (optional) The port of the serer that called `recvDiscoverPacketAsync()`.
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

Note

A discovery packet may be lost, so it is prudent to send several packets before concluding that the connection failed.

ServerInterface.setLicenseKeyAsync(key, validate=None)¶

Submits a request to set the license key for the server.

The license key can only be modified by a superuser.

Parameters:	key (string) – The new license key. validate (bool) – Only set the license after validating the key with the license server.
Returns:	None
Raises:	`CommandError` – If the user is not granted superuser privileges.

New in version 2.1.0.

ServerInterface.setSandboxMapping(userName, sandboxRoots)¶

Sets the sandbox mappings for a user.

Sandbox mappings can only be modified by a superuser.

A sandbox mapping is a dictionary that maps sandbox names to sandbox roots for a particular user. This sandbox names provide the roots paths available to the user (see lsRootsAsync()). All sandbox root paths are accessed by prefixing paths with the sandbox name followed by a colon.

Note

New sandbox mapping only take effect for new user sessions.

See Sandboxing in JetStream Server Documentation.

Parameters:	userName (string) – The user name of the user to sandbox. Note that the user name may be left blank to indicates the system sandbox. Any user who does not have a specific sandbox mapping will inherit the sandbox mapping from the system sandbox. The system sandbox may contain placeholders such as `%u`. sandboxRoots (dict) – A dictionary of sandbox names to sandbox root paths. Sandbox names may be left blank to indicate a root of `/`. If sandbox roots is False, then the user is not sandboxed.
Returns:	None
Raises:	`CommandError` – If the user is not granted superuser privileges, a sandbox path is empty, or a sandbox name contains illegal characters.

New in version 1.5.0.

ServerInterface.sleep(milliseconds)¶: Sleep for specified number of miliseconds.

Changed in version 1.3.0: Restricted to superusers only.

ServerInterface.superuser()¶

Gives a user permission to access and modify all data.

Only a user who has successfully called auth() with superuser eligible credentials will be granted superuser privileges. Users are eligible for superuser privileges if they share the same credentials as the user who started the server or have been listed as eligible during server configuration.

Returns:	None
Raises:	`CommandError` – If the user is not granted superuser privileges.

ServerInterface.terminate()¶

Terminate the server.

The user must be a supuser before shutting down the server.

Changed in version 1.3.0: Restricted to superusers only.

ServerInterface.updateBandwidthLimits(incomingLimitActive=None, incomingRateLimit=None, incomingMaxConnections=None, borrowOutgoing=None, outgoingLimitActive=None, outgoingRateLimit=None, borrowIncoming=None)¶

Sets limits on incoming and outgoing bandwidth utilization.

All parameters are optional. Any parameters which are unspecified or set to None will be unchanged.

Bandwidth limits can only be modified by a superuser.

Note

Bandwidth limits specified on the server command-line during startup become locked and cannot be changed. Attempting to update locked limits using this method will fail.

Warning

Compatibility note: When bandwidth control settings are enabled via the API or command line parameters on a JetStream server, clients prior to version 1.6.0 (API 22) will not be able to communicate with this server.

Parameters:	incomingLimitActive (bool) – Apply limits to incoming data. incomingRateLimit (float) – The maximum rate that data will be received, in kilobits/second. incomingMaxConnections (int) – The maximum number of incoming connections permitted. borrowOutgoing (bool) – If there is an outgoing rate limit, allow unused outgoing bandwidth to be added to the incoming rate limit. outgoingLimitActive (bool) – Apply limits to outgoing data. outgoingRateLimit (float) – The maximum rate that data will be sent, in kilobits/second. borrowIncoming (bool) – If there is an incoming rate limit, allow unused incoming bandwidth to be added to the outgoing rate limit.
Returns:	None
Raises:	`CommandError` – If the user is not granted superuser privileges, or if bandwidth changes are disallowed.

New in version 1.6.0.

ServerInterface.updateGarbageCollectSettings(intervalSeconds=None, timeLimitSeconds=None)¶

Updates garbage collection.

All parameters are optional. Any parameters which are unspecified or set to None will be unchanged.

Garbage collection can only be modified by a superuser.

Parameters:	intervalSeconds (int) – The time, in seconds, between each garbage collection. Allowed range is from 60 (1 minute) to 2147483647 (about 68 years). timeLimitSeconds (int) – The grace period, in seconds, to allow for items that are ready to be garbage collected. If 0, all eligible items will be discarded immediately. If non-zero, keep items that have been ready for garbage collection for less time than specified. Allowed range is from 0 to 2147483647 (about 68 years).
Returns:	Garbage Collect Structure
Return type:	dict
Raises:	`CommandError` – If the user is not granted superuser privileges.

New in version 1.8.0.