8.3.1. vantage6.algorithm.client.AlgorithmClient

class AlgorithmClient(token, *args, **kwargs)

Bases: ClientBase

Interface to communicate between the algorithm container and the central server via a local proxy server.

An algorithm container cannot communicate directly to the central server as it has no internet connection. The algorithm can, however, talk to a local proxy server which has interface to the central server. This way we make sure that the algorithm container does not share details with others, and we also can encrypt the results for a specific receiver. Thus, this not a interface to the central server but to the local proxy server - however, the interface looks identical to make it easier to use.

Parameters:

• token (str) – JWT (container) token, generated by the node the algorithm container runs on

• *args – Arguments passed to the parent ClientBase class.

• **kwargs – Arguments passed to the parent ClientBase class.

__init__(token, *args, **kwargs)

Basic setup for the client

Parameters:

• host (str) – Adress (including protocol, e.g. https://) of the vantage6 server

• port (int) – port numer to which the server listens

• path (str, optional) – path of the api, by default ‘/api’

Methods

__init__(token, *args, **kwargs)	Basic setup for the client
authenticate([credentials, path])	Overwrite base authenticate function to prevent algorithm containers from trying to authenticate, which they would be unable to do (they are already provided with a token on container startup).
generate_path_to(endpoint, ...)	Generate URL to endpoint using host, port and endpoint
refresh_token()	Overwrite base refresh_token function to prevent algorithm containers from trying to refresh their token, which they would be unable to do.
request(*args, **kwargs)	Make a request to the central server.
setup_encryption(private_key_file)	Use private key file to setup encryption of sensitive data.
wait_for_results(task_id[, interval])	Poll the central server until results are available and then return them.

Attributes

base_path	Full path to the server URL.
headers	Defines headers that are sent with each request.
host	Host including protocol (HTTP/HTTPS)
name	Return the node's/client's name
path	Path/endpoint at the server where the api resides
port	Port on which vantage6 server listens
token	JWT Authorization token

class Collaboration(parent)

Bases: SubClient

Get information about the collaboration.

get()

Get the collaboration data.

Returns:

Dictionary containing the collaboration data.

Return type:

dict

class Node(parent)

Bases: SubClient

Get information about the node.

get()

Get the node data.

Returns:

Dictionary containing data on the node this algorithm is running on.

Return type:

dict

class Organization(parent)

Bases: SubClient

Get information about organizations in the collaboration.

get(id_)

Get an organization by ID.

Parameters:

id (int) – ID of the organization to retrieve

Returns:

Dictionary containing the organization data.

Return type:

dict

list()

Obtain all organization in the collaboration.

The container runs in a Node which is part of a single collaboration. This method retrieves all organization data that are within that collaboration. This can be used to target specific organizations in a collaboration.

Returns:

List of organizations in the collaboration.

Return type:

list[dict]

class Result(parent)

Bases: SubClient

Result client for the algorithm container.

This client is used to get results from the central server.

from_task(task_id)

Obtain results from a specific task at the server.

Containers are allowed to obtain the results of their children (having the same job_id at the server). The permissions are checked at te central server.

Results are decrypted by the proxy server and decoded here before returning them to the algorithm.

Parameters:

task_id (int) – ID of the task from which you want to obtain the results

Returns:

List of results. The type of the results depends on the algorithm.

Return type:

list[Any]

get(id_)

Obtain a specific result from the central server.

Parameters:

id (int) – ID of the algorithm run of which the result should be obtained.

Returns:

Result of the algorithm run.

Return type:

Any

class Run(parent)

Bases: SubClient

Algorithm Run client for the algorithm container.

This client is used to obtain algorithm runs of tasks with the same job_id from the central server.

from_task(task_id)

Obtain algorithm runs from a specific task at the server.

Containers are allowed to obtain the runs of their children (having the same job_id at the server). The permissions are checked at te central server.

Note that the returned results are not decrypted. The algorithm is responsible for decrypting the results.

Parameters:

task_id (int) – ID of the task from which you want to obtain the algorithm runs

Returns:

List of algorithm run data. The type of the results depends on the algorithm.

Return type:

list

get(id_)

Obtain a specific algorithm run from the central server.

Parameters:

id (int) – ID of the algorithm run that should be obtained.

Returns:

Algorithm run data.

Return type:

dict

class Study(parent)

Bases: SubClient

Get information about the study or studies.

get(id_)

Get the study data by ID.

Parameters:

id (int) – ID of the study to retrieve

Returns:

Dictionary containing study data.

Return type:

dict

list()

Obtain all studies in the collaboration.

The container runs in a node which is part of a single collaboration, which may contain zero or more studies. This method retrieves all studies that are part of the collaboration.

Returns:

List of studies in the collaboration.

Return type:

list[dict]

class SubClient(parent)

Bases: object

Create sub groups of commands using this SubClient

Parameters:

parent (UserClient | AlgorithmClient) – The parent client

class Task(parent)

Bases: SubClient

A task client for the algorithm container.

It provides functions to get task information and create new tasks.

create(input_, organizations=None, name='subtask', description=None)

Create a new (child) task at the central server.

Containers are allowed to create child tasks (having the same job_id) at the central server. The docker image must be the same as the docker image of this container self.

Parameters:

• input (bytes) – Input to the task. Should be b64 encoded.

• organizations (list[int]) – List of organization IDs that should execute the task.

• name (str, optional) – Name of the subtask

• description (str, optional) – Description of the subtask

Returns:

Dictionary containing information on the created task

Return type:

dict

get(task_id)

Retrieve a task at the central server.

Parameters:

task_id (int) – ID of the task to retrieve

Returns:

Dictionary containing the task information

Return type:

dict

class VPN(parent)

Bases: SubClient

A VPN client for the algorithm container.

It provides functions to obtain the IP addresses of other containers.

get_addresses(only_children=False, only_parent=False, only_siblings=False, only_self=False, include_children=False, include_parent=False, label=None)

Get information about the VPN IP addresses and ports of other algorithm containers involved in the current task. These addresses can be used to send VPN communication to.

Multiple ports may be exposed for a single algorithm run, so it is possible that multiple ports are returned for a single IP.

Parameters:

• only_children (bool, optional) – Only return the IP addresses of the children of the current task, by default False. Incompatible with other only_* parameters.

• only_parent (bool, optional) – Only return the IP address of the parent of the current task, by default False. Incompatible with other only_* parameters.

• only_siblings (bool, optional) – Only return the IP addresses of the siblings of the current task, by default False. Incompatible with other only_* parameters.

• only_self (bool, optional) – Only return the IP address of the current task, by default False. Incompatible with other only_* parameters.

• include_children (bool, optional) – Include the IP addresses of the children of the current task, by default False. Incompatible with only_parent, superseded by only_children.

• include_parent (bool, optional) – Include the IP address of the parent of the current task, by default False. Incompatible with only_children, superseded by only_parent.

• label (str, optional) – The label of the port you are interested in, which is set in the algorithm Dockerfile. If this parameter is set, only the ports with this label will be returned.

Returns:

List of dictionaries with algorithm addresses. Each dictionary contains the keys ‘ip’, ‘port’, ‘label’, ‘organization_id’, ‘task_id’, and ‘parent_id’. If obtaining the VPN addresses from the server fails, a dictionary with a ‘message’ key is returned instead.

Return type:

list[dict]

get_child_addresses()

Get the IP addresses and port numbers of the children of the current algorithm run.

Multiple ports may be exposed for a single algorithm run, so it is possible that multiple ports are returned for a single IP.

Returns:

List of dictionaries with algorithm addresses. Each dictionary contains the keys ‘ip’, ‘port’, ‘label’, ‘organization_id’, ‘task_id’, and ‘parent_id’. If obtaining the VPN addresses from the server fails, a dictionary with a ‘message’ key is returned instead.

Return type:

list[dict]

get_own_address()

Get the IP address and port number of the current algorithm run.

Multiple ports may be exposed for a single algorithm run, so it is possible that multiple ports are returned for a single IP.

Returns:

List of dictionaries with algorithm addresses. Each dictionary contains the keys ‘ip’, ‘port’, ‘label’, ‘organization_id’, ‘task_id’, and ‘parent_id’. If obtaining the VPN addresses from the server fails, a dictionary with a ‘message’ key is returned instead.

Return type:

list[dict]

get_parent_address()

Get the IP address and port number of the parent of the current algorithm run.

Multiple ports may be exposed for a single algorithm run, so it is possible that multiple ports are returned for a single IP.

Returns:

List of dictionaries with algorithm addresses. Each dictionary contains the keys ‘ip’, ‘port’, ‘label’, ‘organization_id’, ‘task_id’, and ‘parent_id’. If obtaining the VPN addresses from the server fails, a dictionary with a ‘message’ key is returned instead.

Return type:

list[dict]

get_sibling_addresses()

Get the IP addresses and port numbers of the siblings of the current algorithm run.

Multiple ports may be exposed for a single algorithm run, so it is possible that multiple ports are returned for a single IP.

Returns:

List of dictionaries with algorithm addresses. Each dictionary contains the keys ‘ip’, ‘port’, ‘label’, ‘organization_id’, ‘task_id’, and ‘parent_id’. If obtaining the VPN addresses from the server fails, a dictionary with a ‘message’ key is returned instead.

Return type:

list[dict]

authenticate(credentials=None, path=None)

Overwrite base authenticate function to prevent algorithm containers from trying to authenticate, which they would be unable to do (they are already provided with a token on container startup).

Function parameters have only been included to make the interface identical to the parent class. They are not used.

Parameters:

• credentials (dict) – Credentials to authenticate with.

• path (str) – Path to the credentials file.

Raises:

NotImplementedError – Always.

Return type:

None

property base_path: str

Full path to the server URL. Combination of host, port and api-path

Returns:

Server URL

Return type:

str

generate_path_to(endpoint, is_for_algorithm_store)

Generate URL to endpoint using host, port and endpoint

Parameters:

• endpoint (str) – endpoint to which a fullpath needs to be generated

• is_for_algorithm_store (bool) – Whether the request is for the algorithm store or not

Returns:

URL to the endpoint

Return type:

str

property headers: dict

Defines headers that are sent with each request. This includes the authorization token.

Returns:

Headers

Return type:

dict

property host: str

Host including protocol (HTTP/HTTPS)

Returns:

Host address of the vantage6 server

Return type:

str

property name: str

Return the node’s/client’s name

Returns:

Name of the user or node

Return type:

str

property path: str

Path/endpoint at the server where the api resides

Returns:

Path to the api

Return type:

str

property port: int

Port on which vantage6 server listens

Returns:

Port number

Return type:

int

refresh_token()

Overwrite base refresh_token function to prevent algorithm containers from trying to refresh their token, which they would be unable to do.

Raises:

NotImplementedError – Always.

Return type:

None

request(*args, **kwargs)

Make a request to the central server. This overwrites the parent function so that containers will not try to refresh their token, which they would be unable to do.

Parameters:

• *args – Arguments passed to the parent ClientBase.request function.

• **kwargs – Arguments passed to the parent ClientBase.request function.

Returns:

Response from the central server.

Return type:

dict

setup_encryption(private_key_file)

Use private key file to setup encryption of sensitive data.

This function will use the private key file to setup encryption and decryption of task input and results. It needs to be called once per client in encrypted collaborations to ensure that the client can read and write encrypted data.

A Cryptor object that handles encryption and decryption will be attached to the client, after verifying that the public key at the server matches the provided private key. In case the server’s public key does not match with the local public key, the local one is uploaded to the server.

Parameters:

private_key_file (str | None) – File path of the private key file, or None if encryption is not enabled

Raises:

AssertionError – If the client is not authenticated

Return type:

None

property token: str

JWT Authorization token

Returns:

JWT token

Return type:

str

wait_for_results(task_id, interval=1)

Poll the central server until results are available and then return them.

Parameters:

• task_id (int) – ID of the task for which the results should be obtained.

• interval (float) – Interval in seconds to wait between checking server for results.

Returns:

List of task results.

Return type:

list