teos.api

class API(inspector, internal_api_endpoint)

Bases: object

The API is in charge of the interface between the user and the tower. It handles and serves user requests. The API is connected with the InternalAPI via gRPC.

Parameters

• inspector (Inspector) – an Inspector instance to check the correctness of the received appointment data.

• internal_api_endpoint (str) – the endpoint where the internal api is served.

logger

The logger for this component.

Type

Logger

app

The Flask app of the API server.

add_appointment()

Main endpoint of the Watchtower.

The client sends requests (appointments) to this endpoint to request a job to the Watchtower. Requests must be json encoded and contain an appointment and signature fields.

Returns

A tuple containing the response (str) and response code (int). For accepted appointments, the rcode is always 200 and the response contains the receipt signature (json). For rejected appointments, the rcode contains an application error, and an error message. Error messages can be found at common.errors.

Return type

tuple

get_appointment()

Gives information about a given appointment state in the Watchtower.

The information is requested by locator.

Returns

A json formatted dictionary containing information about the requested appointment.

Returns not found if the user does not have the requested appointment or the locator is invalid.

A status flag is added to the data provided by either the Watcher or the Responder that signals the status of the appointment.

• Appointments hold by the Watcher are flagged as being_watched.

• Appointments hold by the Responder are flagged as dispute_triggered.

• Unknown appointments are flagged as not_found.

Return type

str

register()

Registers a user by creating a subscription.

Registration is pretty straightforward for now, since it does not require payments. The amount of slots and expiry of the subscription cannot be requested by the user yet either. This is linked to the previous point. Users register by sending a public key to the proper endpoint. This is exploitable atm, but will be solved when payments are introduced.

Returns

A tuple containing the response (str) and response code (int). For accepted requests, the rcode is always 200 and the response contains a json with the public key and number of slots in the subscription. For rejected requests, the rcode is a 404 and the value contains an application error, and an error message. Error messages can be found at common.errors.

Return type

tuple

get_remote_addr()

Gets the remote client ip address. The HTTP_X_REAL_IP field is tried first in case the server is behind a reverse proxy.

Returns

The IP address of the client.

Return type

str

get_request_data_json(request)

Gets the content of a json POST request and makes sure it decodes to a dictionary.

Parameters

request (Request) – the request sent by the user.

Returns

The dictionary parsed from the json request.

Return type

dict

Raises

InvalidParameter – if the request is not json encoded or it does not decodes to a dictionary.

serve(internal_api_endpoint, endpoint, min_to_self_delay, auto_run=False)

Starts the API.

This method can be handled either form an external WSGI (like gunicorn) or by the Flask development server.

Parameters

• internal_api_endpoint (str) – endpoint where the internal api is running (host:port).

• endpoint (str) – endpoint where the http api will be running (host:port).

• min_to_self_delay (str) – the minimum to_self_delay accepted by the Inspector.

• auto_run (bool) – whether the server should be started by this process. False if run with an external WSGI. True is run by Flask.

Returns

The application object needed by the WSGI server to run if auto_run is False, None otherwise.