Extension mechanism (#268)

* The Extension API is available through the module symphony.bdk.core.extension. Extensions are registered programmatically via the ExtensionService. The BDK Extension Model allows extensions to access to some core objects such as the configuration or the api clients. Developers that wish to use these objects are free to implement a set of abstract base classes all suffixed with the Aware keyword.

* As part of this PR we also leveraged this new Extension Mechanism to implement a new custom extension to support the Symphony Groups APIs.

Author: symphony-mariacristina

docsrc/index.md

@@ -13,6 +13,7 @@ Contents
 * [Application service](markdown/application_service.md)
 * [Signal service](markdown/signal_service.md)
 * [Presence service](markdown/presence_service.md)
+* [Extending the BDK](markdown/extension.md)
 * [FAQ](markdown/faq.md)
 
 ```eval_rst
@@ -47,6 +48,7 @@ The reference documentation consists of the following sections:
   * [Connection service](markdown/connection_service.md): Managing connections between users
   * [Signal service](markdown/signal_service.md): Managing signals, subscribing/unsubscribing to signals
   * [Presence service](markdown/presence_service.md): Reacting and managing presences
+* [Extending the BDK](markdown/extension.md): How to use or develop BDK extensions 
 
 ### Technical Documentation
 * Information on how we generate client side code from swagger specs in the

docsrc/markdown/extension.md

@@ -0,0 +1,179 @@
+# Extension Model
+
+> The BDK Extension Mechanism is still an experimental feature, contracts might be subject to **breaking changes**
+> in following versions.
+
+## Overview
+
+The Extension API is available through the module `symphony.bdk.core.extension` but other modules might be required
+depending on what your extension needs to use.
+
+## Registering Extensions
+
+Extensions are registered _programmatically_ via the `ExtensionService`:
+
+```python
+ async with SymphonyBdk(config) as bdk:
+    extension_service = bdk.extensions()
+    extension_service.register(MyExtensionType)
+```
+
+## Service Provider Extension
+
+A _Service Provider_ extension is a specific type of extension loaded on demand when calling the
+`ExtensionService#service(MyExtensionType)` method.
+
+To make your extension _Service Provider_, your extension definition must implement the method `get_service(self)`:
+
+```python
+# The Service implementation class.
+class MyBdkExtensionService:
+    def say_hello(self, name):
+        print(f"Hello, {name}!")
+
+
+# The Extension definition class.
+class MyBdkExtension:
+    def __init__(self):
+        self._service = MyBdkExtensionService()
+
+    def get_service(self):
+        return self._service
+
+
+# Usage example.
+async def run():
+    config = BdkConfigLoader.load_from_symphony_dir("config.yaml")
+
+    async with SymphonyBdk(config) as bdk:
+        extension_service = bdk.extensions()
+        extension_service.register(MyBdkExtensionService)
+
+        service = extension_service.service(MyBdkExtensionService)
+        service.say_hello("Symphony")
+
+
+asyncio.run(run())
+```
+
+## BDK Aware Extensions
+
+The BDK Extension Model allows extensions to access to some core objects such as the configuration or the api clients.
+Developers that wish to use these objects are free to implement a set of abstract base classes all suffixed with
+the `Aware` keyword.
+
+If an extension do not extend one of `Aware` classes but implements the corresponding method, the latter will be used as
+the `ExtensionService` uses duck typing internally.
+
+### `BdkConfigAware`
+
+The abc `symphony.bdk.core.extension.BdkConfigAware` allows extensions to read the `BdkConfig`:
+
+```python
+class MyBdkExtension(BdkConfigAware):
+    def __init__(self):
+        self._config = None
+
+    def set_config(self, config):
+        self._config = config
+```
+
+### `BdkApiClientFactoryAware`
+
+The abc `symphony.bdk.core.extension.BdkApiClientFactoryAware` can be used by extensions that need to use
+the `ApiClientFactory`:
+
+```python
+class MyBdkExtension(BdkApiClientFactoryAware):
+    def __init__(self):
+        self._api_client_factory = None
+
+    def set_api_client_factory(self, api_client_factory):
+        self._api_client_factory = api_client_factory
+```
+
+### `BdkAuthenticationAware`
+
+The abc `symphony.bdk.core.extension.BdkAuthenticationAware` can be used by extensions that need to rely on the service
+account authentication session (`AuthSession`), which provides the `sessionToken` and
+`keyManagerToken` that are used to call the Symphony's APIs:
+
+```python
+class MyBdkExtension(BdkAuthenticationAware):
+    def __init__(self):
+        self._auth_session = None
+
+    def set_auth_session(self, auth_session):
+        self._auth_session = auth_session
+```
+
+## Retry
+
+In order to leverage the retry mechanism your service class should have the field `self._retry_config` of type
+`BdkRetryConfig` and each function that needs a retry mechanism can use the `@retry` decorator. This decorator will
+reuse the config declared in `self._retry_config`. 
+
+The default retry mechanism is defined here: [`refresh_session_if_unauthorized`](../_autosummary/symphony.bdk.core.retry.strategy.refresh_session_if_unauthorized.html).
+It retries on connection errors (more precisely `ClientConnectionError` and `TimeoutError`) and
+on the following HTTP status codes:
+* 401
+* 429
+* codes greater than or equal to 500.
+
+In case of unauthorized, it will call `await self._auth_session.refresh()` before retrying.
+
+Following is a sample code to show how it can be used:
+```python
+from symphony.bdk.core.extension import BdkExtensionServiceProvider, BdkAuthenticationAware, BdkConfigAware
+from symphony.bdk.core.retry import retry
+
+class MyExtension(BdkConfigAware, BdkAuthenticationAware, BdkExtensionServiceProvider):
+    def __init__(self):
+        self._config = None
+        self._auth_session = None
+
+    def set_config(self, config):
+        self._config = config
+
+    def set_bot_session(self, auth_session):
+        self._auth_session = auth_session
+
+    def get_service(self):
+        return MyService(self._config.retry, self._auth_session)
+
+
+class MyService:
+    def __init__(self, retry_config, auth_session):
+        self._retry_config = retry_config  # used by the @retry decorator
+        self._auth_session = auth_session  # default retry logic will call refresh on self._auth_session
+
+    @retry
+    async def my_service_method(self):
+        pass  # do stuff which will be retried
+```
+
+Retry conditions and mechanism can be customized as follows:
+```python
+async def my_retry_mechanism(retry_state):
+    """Function used by the retry decorator to check if a function call has to be retried.
+
+    :param retry_state: current retry state, of type RetryCallState: https://tenacity.readthedocs.io/en/latest/#retrycallstate
+    :return: True if we want to retry, False otherwise
+    """
+    if retry_state.outcome.failed:
+        exception = retry_state.outcome.exception()  # exception that lead to the failure 
+        if condition_on_exception(exception):
+            # do stuff to recover the exception
+            # method args can be accessed as follows: retry_state.args
+            return True  # return True to retry the function
+    return False  # return False to not retry and make function call fail
+
+class MyService:
+    def __init__(self, retry_config, auth_session):
+        self._retry_config = retry_config  # used by the @retry decorator
+        self._auth_session = auth_session  # default retry logic will call refresh on self._auth_session
+
+    @retry(retry=my_retry_mechanism)
+    async def my_service_method(self):
+        pass  # do stuff which will be retried
+```

examples/extension/groups_extension.py

@@ -0,0 +1,63 @@
+import asyncio
+import logging.config
+from pathlib import Path
+
+from symphony.bdk.core.config.loader import BdkConfigLoader
+from symphony.bdk.core.symphony_bdk import SymphonyBdk
+from symphony.bdk.ext.group import SymphonyGroupBdkExtension, SymphonyGroupService
+from symphony.bdk.gen.group_model.base_profile import BaseProfile
+from symphony.bdk.gen.group_model.create_group import CreateGroup
+from symphony.bdk.gen.group_model.member import Member
+from symphony.bdk.gen.group_model.owner import Owner
+from symphony.bdk.gen.group_model.status import Status
+from symphony.bdk.gen.group_model.update_group import UpdateGroup
+
+logging.config.fileConfig(Path(__file__).parent.parent / "logging.conf", disable_existing_loggers=False)
+
+
+async def run():
+    async with SymphonyBdk(BdkConfigLoader.load_from_symphony_dir("config.yaml")) as bdk:
+        bdk.extensions().register(SymphonyGroupBdkExtension)
+        group_service: SymphonyGroupService = bdk.extensions().service(SymphonyGroupBdkExtension)
+
+        # list groups
+        groups = await group_service.list_groups(status=Status("ACTIVE"))
+        logging.debug(f"List groups: {groups}")
+
+        # create a new group
+        profile = BaseProfile(display_name="Mary's SDL")
+        member = Member(member_tenant=190, member_id=13056700580915)
+        create_group = CreateGroup(type="SDL", owner_type=Owner(value="TENANT"), owner_id=190, name="Another SDL",
+                                   members=[member], profile=profile)
+        group = await group_service.insert_group(create_group=create_group)
+        logging.debug(f"Group created: {group}")
+
+        # update group name
+        update_group = UpdateGroup(name="Updated name", type=group.type, owner_type=Owner(value="TENANT"),
+                                   owner_id=group.owner_id, id=group.id, e_tag=group.e_tag,
+                                   status=Status(value="ACTIVE"), profile=profile, members=[member])
+        group = await group_service.update_group(if_match=group.e_tag, group_id=group.id, update_group=update_group)
+        logging.debug(f"Group after name update: {group}")
+
+        # add member to a group
+        group = await group_service.add_member_to_group(group.id, 13056700580913)
+        logging.debug(f"Group after a new member is added: {group}")
+
+        # update group avatar
+        image_base_64 = "base_64_format_image"
+        group = await group_service.update_avatar(group_id=group.id, image=image_base_64)
+        logging.debug(f"Group after avatar update: {group}")
+
+        # get a group by id
+        group = await group_service.get_group(group_id=group.id)
+        logging.debug(f"Retrieve group by id: {group}")
+
+        # Delete group
+        update_group = UpdateGroup(name=group.name, type=group.type, owner_type=Owner(value="TENANT"),
+                                   owner_id=group.owner_id, id=group.id, e_tag=group.e_tag,
+                                   status=Status(value="DELETED"), profile=profile, members=[member])
+        group = await group_service.update_group(if_match=group.e_tag, group_id=group.id, update_group=update_group)
+        logging.debug(f"Group removed: {group}")
+
+
+asyncio.run(run())