Lesson 7: Adapters - invoke/inquire

There are two mechanisms for controlling the logical flow of information in an Orchestra system. Both of these rely on outlets (see more at <https://docs.ledr.io/en/the-orchestra-platfrom/outlets>) The short version is that outlets are special entities the server allocate some resources to.

The first is the adapter mechanism, where the outlet is the place of rendez-vous between an adapter and an invoker/inquirer. This is what this lesson is about. see more at <https://docs.ledr.io/en/the-orchestra-platfrom/adapters>

The second is the pub/sub mechanism, where the outlet acts as an event queue. This will be detailed in the next lesson. see more at <https://docs.ledr.io/en/the-orchestra-platfrom/subscribers-events-and-pub-sub>

Ad adapter is a piece of code that calls adapt on an outlet. This tells the Orchestra server that any call to invoke or inquire arriving on the outlet should be handled by the adapter. In some sense, an adapter is a special client that connects to an Orchestra server, and declares itself as the server that will handle any request on a certain outlet. This lesson only focuses on invoke and not inquire. They both work in very similar way. TODO: document inquire more

The orchestra-toolkit library takes care of a lot of plumbing when creating an adapter, including conforming to orchestra standards of how adapter works. This makes developper’s life easier. see <https://docs.ledr.io/en/the-orchestra-platfrom/adapters-standard> for more details of what happens under the hood.

The example adapter any new adapter written in python should copy/paste from can be found at the link below. This is the definitive reference for how an adapter is supposed to look according to our latest standards. <https://gitlab.com/ledr/core/dev-platform/python-adapter-wireframe>

At the moment lesson_7_adapters.py includes code both for the adapter as well as the driver logic that interacts with the adapter. This is for ease of running the example.

Note: For most usecases, you would run your adapter code separate from your driver/client code.

To run the lesson_7 code:

python src/module/lesson_7_adapter.py

Code

import time
from dotenv import load_dotenv, find_dotenv
import avesterra as av
import orchestra.env as env
from orchestra import mount
import threading
from orchestra.orchestra_adapter import OrchestraAdapter, ValueType

MOUNT_KEY = "number_adapter"


adapter = None
"""We keep a global reference to the adapter just so we can shutdown it later"""


def run_number_adapter():
    global adapter
    """
    This function contains all the code required to create an adapter, declare
    all its different routes and their implementations, and run the adapter.

    Note: Must be ran from the main thread of the process, as it handles signals.
    """
    adapter = OrchestraAdapter(
        mount_key=MOUNT_KEY,
        version="1.0.0",
        description="Exposes interface for updating count",
    )

    number_count: dict[av.AvEntity, int] = {}
    """This is our in-memory store used in the `set` and `get` functions below"""

    @adapter.route("Set number count")
    @adapter.method(av.AvMethod.SET)
    @adapter.value_in(ValueType.integer())
    @adapter.value_out(ValueType.null())
    def set(entity: av.AvEntity, value: av.AvValue) -> av.AvValue:
        """
        Sets the number count.
        :param entity: (AvEntity) that is the entity set the count of
        :param value: (AvValue) that encodes number
        :return: (AvValue) with Null
        """
        count = value.decode_integer()
        number_count[entity] = count

        return av.NULL_VALUE

    @adapter.route("Get number count")
    @adapter.method(av.AvMethod.GET)
    @adapter.value_out(ValueType.integer())
    def get(entity: av.AvEntity) -> av.AvValue:
        """
        Gets the count value from the entity.
        :param entity: (AvEntity) the entity which contains the count
        :return: (AvValue) with the count
        """
        count = number_count.get(entity, 0)

        return av.AvValue.encode_integer(count)

    # /!\ Important: Calling `.run()` will block until the adapter is stopped, which
    # typically only happens when the process receives a SIGTERM signal.
    adapter.run()


#######
#
# All code below that point is there to invoke the adapter for demo purposes
# and typically wouldn't exist in a real adapter code.
#
######


def set_number(entity: av.AvEntity, n: int, auth: av.AvAuthorization):
    """
    Utility function to invoke the given number entity and set its value to `n`
    """
    av.invoke_entity_retry_bo(
        entity=entity,
        method=av.AvMethod.SET,
        value=av.AvValue.encode_integer(n),
        authorization=auth,
    )


def get_number(entity: av.AvEntity, auth: av.AvAuthorization) -> int:
    """
    Utility function to invoke the given number entity and get its current value
    """
    val = av.invoke_entity_retry_bo(
        entity=entity,
        method=av.AvMethod.GET,
        authorization=auth,
    )
    return val.decode_integer()


def create_number_entity(name: str, auth: av.AvAuthorization) -> av.AvEntity:
    """
    Utility function create a new number entity.
    :param name: The number entity name
    :param auth: The authorization token to use
    :return: The newly created number entity
    """
    # Note, the use of create_entity instead of create_object.
    # This is because create_object automatically connects to the object adapter
    # and we don't want that.
    number_entity = av.create_entity(
        name=name,
        key=name.lower(),
        context=av.AvContext.ORCHESTRA,
        category=av.AvCategory.MATHEMATICS,
        klass=av.AvClass.MATHEMATICS,
        authorization=auth,
    )
    av.connect_method(
        entity=number_entity,
        outlet=mount.get_outlet(MOUNT_KEY, auth=auth),
        authorization=auth,
    )

    return number_entity


def test_number_adapter():
    """
    Basic tests to showcase how the number adapter behaves
    """
    load_dotenv(find_dotenv())
    auth = env.get_or_raise(env.AVESTERRA_AUTH, av.AvAuthorization)

    time.sleep(0.1)  # Wait for the adapter to start

    # Create a number entity that we can update its count through an outlet
    number_entity = create_number_entity(name="My Number", auth=auth)
    print(f"The entity ID of the number entity is: {number_entity}")

    set_number(entity=number_entity, n=1, auth=auth)
    assert get_number(entity=number_entity, auth=auth) == 1
    set_number(entity=number_entity, n=42, auth=auth)
    assert get_number(entity=number_entity, auth=auth) == 42
    set_number(entity=number_entity, n=100, auth=auth)
    assert get_number(entity=number_entity, auth=auth) == 100

    assert adapter is not None
    adapter.shutdown()


if __name__ == "__main__":
    threading.Thread(target=test_number_adapter).start()
    run_number_adapter()