teos.appointments_dbm¶

class AppointmentsDBM(db_path)[source]¶

Bases: common.db_manager.DBManager

The AppointmentsDBM is in charge of interacting with the appointments database (LevelDB). Keys and values are stored as bytes in the database but processed as strings by the manager.

The database is split in six prefixes:

WATCHER_PREFIX, defined as b'w, is used to store Watcher appointments.

RESPONDER_PREFIX, defines as b'r, is used to store Responder trackers.

WATCHER_LAST_BLOCK_KEY, defined as b'bw, is used to store the last block hash known by the Watcher.

RESPONDER_LAST_BLOCK_KEY, defined as b'br, is used to store the last block hash known by the Responder.

LOCATOR_MAP_PREFIX, defined as b'm, is used to store the locator:uuid maps.

TRIGGERED_APPOINTMENTS_PREFIX, defined as b'ta, is used to stored triggered appointments (appointments that have been handed to the Responder.)

Parameters: db_path (str) – the path (relative or absolute) to the system folder containing the database. A fresh database will be created if the specified path does not contain one.

logger¶

the logger for this component.

Type: Logger

Raises

ValueError – If the provided db_path is not a string.
plyvel.Error – If the db is currently unavailable (being used by another process).

batch_create_triggered_appointment_flag(uuids)[source]¶

Creates a flag that signals that an appointment has been triggered for every appointment in the given list.

Parameters: uuids (list) – a list of identifiers for the appointments to flag.

batch_delete_responder_trackers(uuids)[source]¶

Deletes multiple trackers from the database.

Parameters: uuids (list) – a list of 16-byte hex-encoded strings identifying the trackers to be deleted.

batch_delete_triggered_appointment_flag(uuids)[source]¶

Deletes a list of flag signaling that some appointment have been triggered.

Parameters: uuids (list) – the identifier of the flag to be removed.

batch_delete_watcher_appointments(uuids)[source]¶

Deletes multiple appointments from the database.

Parameters: uuids (list) – a list of 16-byte hex-encoded strings identifying the appointments to be deleted.

create_append_locator_map(locator, uuid)[source]¶

Creates a locator:uuid map.

If the map already exists, the new uuid is appended to the existing ones (if it is not already there).

Parameters

locator (str) – a 16-byte hex-encoded string used as the key of the map.
uuid (str) – a 16-byte hex-encoded unique id to create (or add to) the map.

create_triggered_appointment_flag(uuid)[source]¶

Creates a flag that signals that an appointment has been triggered.

Parameters: uuid (str) – the identifier of the flag to be created.

delete_locator_map(locator)[source]¶

Deletes a locator:uuid map.

Parameters: locator (str) – a 16-byte hex-encoded string identifying the map to delete.
Returns: True if the locator map was deleted from the database or it was non-existent, False otherwise.
Return type: bool

delete_responder_tracker(uuid)[source]¶

Deletes a tracker from the database.

Parameters: uuid (str) – a 16-byte hex-encoded string identifying the tracker to be deleted.
Returns: True if the tracker was deleted from the database or it was non-existent, False otherwise.
Return type: bool

delete_triggered_appointment_flag(uuid)[source]¶

Deletes a flag that signals that an appointment has been triggered.

Parameters: uuid (str) – the identifier of the flag to be removed.
Returns: True if the flag was deleted from the database or it was non-existent, False otherwise.
Return type: bool

delete_watcher_appointment(uuid)[source]¶

Deletes an appointment from the database.

Parameters: uuid (str) – a 16-byte hex-encoded string identifying the appointment to be deleted.
Returns: True if the appointment was deleted from the database or it was non-existent, False otherwise.
Return type: bool

get_last_known_block(key)[source]¶

Loads the last known block given a key.

Parameters

key (str) – the identifier of the db to look into (either WATCHER_LAST_BLOCK_KEY or RESPONDER_LAST_BLOCK_KEY).

Returns

A 32-byte hex-encoded str representing the last known block hash.

Returns None if the entry is not found.

Return type

str or None

load_all_triggered_flags()[source]¶

Loads all the appointment triggered flags from the database.

Returns: a list of all the uuids of the triggered appointments.
Return type: list

load_appointments_db(prefix)[source]¶

Loads all data from the appointments database given a prefix. Two prefixes are defined: WATCHER_PREFIX and RESPONDER_PREFIX.

Parameters

prefix (str) – the prefix of the data to load.

Returns

A dictionary containing the requested data (appointments or trackers) indexed by uuid.

Returns an empty dictionary if no data is found.

Return type

dict

load_last_block_hash_responder()[source]¶

Loads the last known block hash of the Responder from the database.

Returns

A 32-byte hex-encoded string representing the last known block hash if found.

Returns None otherwise.

Return type

str or None

load_last_block_hash_watcher()[source]¶

Loads the last known block hash of the Watcher from the database.

Returns

A 32-byte hex-encoded string representing the last known block hash if found.

Returns None otherwise.

Return type

str or None

load_locator_map(locator)[source]¶

Loads the locator:uuid map of a given locator from the database.

Parameters

locator (str) – a 16-byte hex-encoded string representing the appointment locator.

Returns

The requested locator:uuid map if found.

Returns None otherwise.

Return type

dict or None

load_responder_tracker(uuid)[source]¶

Loads a tracker from the database using RESPONDER_PREFIX as a prefix to the given uuid.

Parameters

uuid (str) – the tracker’s unique identifier.

Returns

A dictionary containing the tracker data if they key is found.

Returns None otherwise.

Return type

dict

load_responder_trackers()[source]¶

Loads all the trackers from the database (all entries with the RESPONDER_PREFIX prefix).

Returns: A dictionary with all the trackers stored in the database. An empty dictionary if there are none.
Return type: dict

load_watcher_appointment(uuid)[source]¶

Loads an appointment from the database using WATCHER_PREFIX as prefix to the given uuid.

Parameters

uuid (str) – the appointment’s unique identifier.

Returns

A dictionary containing the appointment data if they key is found.

Returns None otherwise.

Return type

dict

load_watcher_appointments(include_triggered=False)[source]¶

Loads all the appointments from the database (all entries with the WATCHER_PREFIX prefix).

Parameters: include_triggered (bool) – whether to include the appointments flagged as triggered or not. False by default.
Returns: A dictionary with all the appointments stored in the database. An empty dictionary if there are none.
Return type: dict

store_last_block_hash_responder(block_hash)[source]¶

Stores a block hash as the last known block of the Responder.

Parameters: block_hash (str) – the block hash to be stored (32-byte hex-encoded)
Returns: True if the block hash was stored in the db. False otherwise.
Return type: bool

store_last_block_hash_watcher(block_hash)[source]¶

Stores a block hash as the last known block of the Watcher.

Parameters: block_hash (str) – the block hash to be stored (32-byte hex-encoded)
Returns: True if the block hash was stored in the db. False otherwise.
Return type: bool

store_responder_tracker(uuid, tracker)[source]¶

Stores a tracker in the database using the RESPONDER_PREFIX prefix.

Parameters

uuid (str) – the identifier of the appointment to be stored.
tracker (dict) – a tracker encoded as a dictionary.

Returns

True if the tracker was stored in the db. False otherwise.

Return type

bool

store_watcher_appointment(uuid, appointment)[source]¶

Stores an appointment in the database using the WATCHER_PREFIX prefix.

Parameters

uuid (str) – the identifier of the appointment to be stored.
appointment (dict) – an appointment encoded as a dictionary.

Returns

True if the appointment was stored in the db. False otherwise.

Return type

bool

update_locator_map(locator, locator_map)[source]¶

Updates a locator:uuid map in the database by deleting one of it’s uuid. It will only work as long as the given locator_map is a subset of the current one and it’s not empty.

Parameters

locator (str) – a 16-byte hex-encoded string used as the key of the map.
locator_map (list) – a list of uuids to replace the current one on the db.