dpcharmlibs-interfaces 1.0.0__py3-none-any.whl

dpcharmlibs/interfaces/__init__.py

@@ -0,0 +1,434 @@
+# Copyright 2025 Canonical Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+r"""Library to manage the relation for the data-platform products.
+
+This V1 has been specified in
+https://docs.google.com/document/d/1lnuonWnoQb36RWYwfHOBwU0VClLbawpTISXIC_yNKYo,
+and should be backward compatible with v0 clients.
+
+This library contains the Requires and Provides classes for handling the relation
+between an application and multiple managed application supported by the data-team:
+MySQL, Postgresql, MongoDB, Redis, Kafka, and Karapace.
+
+#### Models
+
+This library exposes basic default models that can be used in most cases.
+If you need more complex models, you can subclass them.
+
+```python
+from dpcharmlibs.interfaces import RequirerCommonModel, ExtraSecretStr
+
+class ExtendedCommonModel(RequirerCommonModel):
+    operator_password: ExtraSecretStr
+```
+
+Secret groups are handled using annotated types.
+If you wish to add extra secret groups, please follow the following model.
+The string metadata represents the secret group name, and `OptionalSecretStr` is a TypeAlias for
+`SecretStr | None`. Finally, `SecretStr` represents a field validating the URI pattern `secret:.*`
+
+```python
+MyGroupSecretStr = Annotated[OptionalSecretStr, Field(exclude=True, default=None), "mygroup"]
+```
+
+Fields not specified as OptionalSecretStr and extended with a group name in the metadata will NOT
+get serialised.
+
+
+#### Requirer Charm
+
+This library is a uniform interface to a selection of common database
+metadata, with added custom events that add convenience to database management,
+and methods to consume the application related data.
+
+
+```python
+from dpcharmlibs.interfaces import (
+    RequirerCommonModel,
+    RequirerDataContractV1,
+    ResourceCreatedEvent,
+    ResourceEntityCreatedEvent,
+    ResourceProviderModel,
+    ResourceRequirerEventHandler,
+)
+
+class ClientCharm(CharmBase):
+    # Database charm that accepts connections from application charms.
+    def __init__(self, *args) -> None:
+        super().__init__(*args)
+
+        requests = [
+            RequirerCommonModel(
+                resource="clientdb",
+            ),
+            RequirerCommonModel(
+                resource="clientbis",
+            ),
+            RequirerCommonModel(
+                entity_type="USER",
+            )
+        ]
+        self.database = ResourceRequirerEventHandler(
+            self,"database", requests, response_model=ResourceProviderModel
+        )
+        self.framework.observe(self.database.on.resource_created, self._on_resource_created)
+        self.framework.observe(self.database.on.resource_entity_created, self._on_entity_created)
+
+    def _on_resource_created(self, event: ResourceCreatedEvent) -> None:
+        # Event triggered when a new database is created.
+        relation_id = event.relation.id
+        response = event.response # This is the response model
+
+        username = event.response.username
+        password = event.response.password
+        ...
+
+    def _on_entity_created(self, event: ResourceCreatedEvent) -> None:
+        # Event triggered when a new entity is created.
+        ...
+```
+
+Compared to V0, this library makes heavy use of pydantic models, and allows for
+multiple requests, specified as a list.
+On the Requirer side, each response will trigger one custom event for that response.
+This way, it allows for more strategic events to be emitted according to the request.
+
+As show above, the library provides some custom events to handle specific situations,
+which are listed below:
+-  resource_created: event emitted when the requested database is created.
+-  resource_entity_created: event emitted when the requested entity is created.
+-  endpoints_changed: event emitted when the read/write endpoints of the database have changed.
+-  read_only_endpoints_changed: event emitted when the read-only endpoints of the database
+  have changed. Event is not triggered if read/write endpoints changed too.
+
+If it is needed to connect multiple database clusters to the same relation endpoint
+the application charm can implement the same code as if it would connect to only
+one database cluster (like the above code example).
+
+To differentiate multiple clusters connected to the same relation endpoint
+the application charm can use the name of the remote application:
+
+```python
+
+def _on_resource_created(self, event: ResourceCreatedEvent) -> None:
+    # Get the remote app name of the cluster that triggered this event
+    cluster = event.relation.app.name
+```
+
+It is also possible to provide an alias for each different database cluster/relation.
+
+So, it is possible to differentiate the clusters in two ways.
+The first is to use the remote application name, i.e., `event.relation.app.name`, as above.
+
+The second way is to use different event handlers to handle each cluster events.
+The implementation would be something like the following code:
+
+```python
+
+from dpcharmlibs.interfaces import (
+    RequirerCommonModel,
+    RequirerDataContractV1,
+    ResourceCreatedEvent,
+    ResourceEntityCreatedEvent,
+    ResourceProviderModel,
+    ResourceRequirerEventHandler,
+)
+
+class ApplicationCharm(CharmBase):
+    # Application charm that connects to database charms.
+
+    def __init__(self, *args):
+        super().__init__(*args)
+
+        requests = [
+            RequirerCommonModel(
+                resource="clientdb",
+            ),
+            RequirerCommonModel(
+                resource="clientbis",
+            ),
+        ]
+        # Define the cluster aliases and one handler for each cluster database created event.
+        self.database = ResourceRequirerEventHandler(
+            self,
+            relation_name="database"
+            relations_aliases = ["cluster1", "cluster2"],
+            requests=
+        )
+        self.framework.observe(
+            self.database.on.cluster1_resource_created, self._on_cluster1_resource_created
+        )
+        self.framework.observe(
+            self.database.on.cluster2_resource_created, self._on_cluster2_resource_created
+        )
+
+    def _on_cluster1_resource_created(self, event: ResourceCreatedEvent) -> None:
+        # Handle the created database on the cluster named cluster1
+
+        # Create configuration file for app
+        config_file = self._render_app_config_file(
+            event.response.username,
+            event.response.password,
+            event.response.endpoints,
+        )
+        ...
+
+    def _on_cluster2_resource_created(self, event: ResourceCreatedEvent) -> None:
+        # Handle the created database on the cluster named cluster2
+
+        # Create configuration file for app
+        config_file = self._render_app_config_file(
+            event.response.username,
+            event.response.password,
+            event.response.endpoints,
+        )
+        ...
+```
+
+### Provider Charm
+
+Following an example of using the ResourceRequestedEvent, in the context of the
+database charm code:
+
+```python
+from dpcharmlibs.interfaces import (
+    ResourceProviderEventHandler,
+    ResourceProviderModel,
+    ResourceRequestedEvent,
+    RequirerCommonModel,
+)
+
+class SampleCharm(CharmBase):
+
+    def __init__(self, *args):
+        super().__init__(*args)
+        # Charm events defined in the database provides charm library.
+        self.provided_database = ResourceProviderEventHandler(self, "database", RequirerCommonModel)
+        self.framework.observe(self.provided_database.on.resource_requested,
+            self._on_resource_requested)
+        # Database generic helper
+        self.database = DatabaseHelper()
+
+    def _on_resource_requested(self, event: ResourceRequestedEvent) -> None:
+        # Handle the event triggered by a new database requested in the relation
+        # Retrieve the database name using the charm library.
+        db_name = event.request.resource
+        # generate a new user credential
+        username = self.database.generate_user(event.request.request_id)
+        password = self.database.generate_password(event.request.request_id)
+        # set the credentials for the relation
+        response = ResourceProviderModel(
+            salt=event.request.salt,
+            request_id=event.request.request_id,
+            resource=db_name,
+            username=username,
+            password=password,
+            ...
+        )
+        self.provided_database.set_response(event.relation.id, response)
+```
+
+As shown above, the library provides a custom event (resource_requested) to handle
+the situation when an application charm requests a new database to be created.
+It's preferred to subscribe to this event instead of relation changed event to avoid
+creating a new database when other information other than a database name is
+exchanged in the relation databag.
+
+"""
+
+from ._version import __version__ as __version__
+from .diff import (
+    Diff,
+    diff,
+    resource_added,
+    store_new_data,
+)
+from .errors import (
+    DataInterfacesError,
+    IllegalOperationError,
+    SecretAlreadyExistsError,
+    SecretError,
+    SecretsUnavailableError,
+)
+from .events import (
+    AuthenticationUpdatedEvent,
+    BulkResourcesRequestedEvent,
+    MtlsCertUpdatedEvent,
+    ResourceCreatedEvent,
+    ResourceEndpointsChangedEvent,
+    ResourceEntityCreatedEvent,
+    ResourceEntityPermissionsChangedEvent,
+    ResourceEntityRequestedEvent,
+    ResourceProviderEvent,
+    ResourceProvidesEvents,
+    ResourceReadOnlyEndpointsChangedEvent,
+    ResourceRequestedEvent,
+    ResourceRequirerEvent,
+    ResourceRequiresEvents,
+    StatusEventBase,
+    StatusRaisedEvent,
+    StatusResolvedEvent,
+)
+from .handlers import (
+    EventHandlers,
+    ResourceProviderEventHandler,
+    ResourceRequirerEventHandler,
+)
+from .models import (
+    SECRET_PREFIX,
+    BaseCommonModel,
+    CommonModel,
+    DataContract,
+    DataContractV0,
+    DataContractV1,
+    EntityPermissionModel,
+    KafkaRequestModel,
+    KafkaResponseModel,
+    PeerModel,
+    ProviderCommonModel,
+    RelationStatus,
+    RequirerCommonModel,
+    RequirerDataContract,
+    RequirerDataContractType,
+    RequirerDataContractV0,
+    RequirerDataContractV1,
+    ResourceProviderModel,
+)
+from .repository import (
+    AbstractRepository,
+    OpsOtherPeerUnitRepository,
+    OpsPeerRepository,
+    OpsPeerUnitRepository,
+    OpsRelationRepository,
+    OpsRepository,
+)
+from .repository_interfaces import (
+    OpsOtherPeerUnitRepositoryInterface,
+    OpsPeerRepositoryInterface,
+    OpsPeerUnitRepositoryInterface,
+    OpsRelationRepositoryInterface,
+    RepositoryInterface,
+    build_model,
+    write_model,
+)
+from .secrets import (
+    CachedSecret,
+    SecretCache,
+)
+from .types import (
+    EntitySecretStr,
+    ExtraSecretStr,
+    MtlsSecretStr,
+    OptionalPathLike,
+    OptionalSecretBool,
+    OptionalSecrets,
+    OptionalSecretStr,
+    RelationStatusDict,
+    Scope,
+    SecretGroup,
+    SecretString,
+    TlsSecretBool,
+    TlsSecretStr,
+    UserSecretStr,
+)
+from .utils import (
+    ensure_leader_for_app,
+    gen_hash,
+    gen_salt,
+    get_encoded_dict,
+)
+
+__all__ = [
+    'SECRET_PREFIX',
+    'AbstractRepository',
+    'AuthenticationUpdatedEvent',
+    'BaseCommonModel',
+    'BulkResourcesRequestedEvent',
+    'CachedSecret',
+    'CommonModel',
+    'DataContract',
+    'DataContractV0',
+    'DataContractV1',
+    'DataInterfacesError',
+    'Diff',
+    'EntityPermissionModel',
+    'EntitySecretStr',
+    'EventHandlers',
+    'ExtraSecretStr',
+    'IllegalOperationError',
+    'KafkaRequestModel',
+    'KafkaResponseModel',
+    'MtlsCertUpdatedEvent',
+    'MtlsSecretStr',
+    'OpsOtherPeerUnitRepository',
+    'OpsOtherPeerUnitRepositoryInterface',
+    'OpsPeerRepository',
+    'OpsPeerRepositoryInterface',
+    'OpsPeerUnitRepository',
+    'OpsPeerUnitRepositoryInterface',
+    'OpsRelationRepository',
+    'OpsRelationRepositoryInterface',
+    'OpsRepository',
+    'OptionalPathLike',
+    'OptionalSecretBool',
+    'OptionalSecretStr',
+    'OptionalSecrets',
+    'PeerModel',
+    'ProviderCommonModel',
+    'RelationStatus',
+    'RelationStatusDict',
+    'RepositoryInterface',
+    'RequirerCommonModel',
+    'RequirerDataContract',
+    'RequirerDataContractType',
+    'RequirerDataContractV0',
+    'RequirerDataContractV1',
+    'ResourceCreatedEvent',
+    'ResourceEndpointsChangedEvent',
+    'ResourceEntityCreatedEvent',
+    'ResourceEntityPermissionsChangedEvent',
+    'ResourceEntityRequestedEvent',
+    'ResourceProviderEvent',
+    'ResourceProviderEventHandler',
+    'ResourceProviderModel',
+    'ResourceProvidesEvents',
+    'ResourceReadOnlyEndpointsChangedEvent',
+    'ResourceRequestedEvent',
+    'ResourceRequirerEvent',
+    'ResourceRequirerEventHandler',
+    'ResourceRequiresEvents',
+    'Scope',
+    'SecretAlreadyExistsError',
+    'SecretCache',
+    'SecretError',
+    'SecretGroup',
+    'SecretString',
+    'SecretsUnavailableError',
+    'StatusEventBase',
+    'StatusRaisedEvent',
+    'StatusResolvedEvent',
+    'TlsSecretBool',
+    'TlsSecretStr',
+    'UserSecretStr',
+    'build_model',
+    'diff',
+    'ensure_leader_for_app',
+    'gen_hash',
+    'gen_salt',
+    'get_encoded_dict',
+    'resource_added',
+    'store_new_data',
+    'write_model',
+]

dpcharmlibs/interfaces/_version.py

@@ -0,0 +1,15 @@
+# Copyright 2025 Canonical Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+__version__ = '1.0.0'

dpcharmlibs/interfaces/diff.py

@@ -0,0 +1,94 @@
+# Copyright 2026 Canonical Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Logic to compute diffs and modelling for diffs."""
+
+import json
+from typing import Any, NamedTuple
+
+from ops.model import Application, Relation, Unit
+
+from dpcharmlibs.interfaces.utils import RESOURCE_ALIASES
+
+
+class Diff(NamedTuple):
+    """A tuple for storing the diff between two data mappings.
+
+    added - keys that were added
+    changed - keys that still exist but have new values
+    deleted - key that were deleted
+    """
+
+    added: set[str]
+    changed: set[str]
+    deleted: set[str]
+
+
+def diff(old_data: dict[str, str] | None, new_data: dict[str, str]) -> Diff:
+    """Retrieves the diff of the data in the relation changed databag for v1.
+
+    Args:
+        old_data: dictionary of the stored data before the event.
+        new_data: dictionary of the received data to compute the diff.
+
+    Returns:
+        a Diff instance containing the added, deleted and changed
+            keys from the event relation databag.
+    """
+    old_data = old_data or {}
+
+    # These are the keys that were added to the databag and triggered this event.
+    added = new_data.keys() - old_data.keys()
+    # These are the keys that were removed from the databag and triggered this event.
+    deleted = old_data.keys() - new_data.keys()
+    # These are the keys that already existed in the databag,
+    # but had their values changed.
+    changed = {key for key in old_data.keys() & new_data.keys() if old_data[key] != new_data[key]}
+    # Return the diff with all possible changes.
+    return Diff(added, changed, deleted)
+
+
+def resource_added(diff: Diff, aliases: list[str] | None = None) -> bool:
+    """Ensures that one of the aliased resources has been added."""
+    all_aliases = RESOURCE_ALIASES + ['resource'] + (aliases or [])
+    return any(item in diff.added for item in all_aliases)
+
+
+def store_new_data(
+    relation: Relation,
+    component: Unit | Application,
+    new_data: dict[str, str],
+    short_uuid: str | None = None,
+    global_data: dict[str, Any] | None = None,
+):
+    """Stores the new data in the databag for diff computation.
+
+    Args:
+        relation: The relation considered to write data to
+        component: The component databag to write data to
+        new_data: a dictionary containing the data to write
+        short_uuid: Only present in V1, the request-id of that data to write.
+        global_data: request-independent, global state data to be written.
+    """
+    global_data = global_data or {}
+    global_data = {k: v for k, v in global_data.items() if v}
+    # First, the case for V0
+    if not short_uuid:
+        relation.data[component].update({'data': json.dumps(new_data | global_data)})
+    # Then the case for V1, where we have a ShortUUID
+    else:
+        data = json.loads(relation.data[component].get('data', '{}')) | global_data
+        if not isinstance(data, dict):
+            raise ValueError
+        data[short_uuid] = new_data
+        relation.data[component].update({'data': json.dumps(data)})

dpcharmlibs/interfaces/errors.py

@@ -0,0 +1,34 @@
+# Copyright 2026 Canonical Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Exceptions."""
+
+
+class DataInterfacesError(Exception):
+    """Common ancestor for DataInterfaces related exceptions."""
+
+
+class SecretError(DataInterfacesError):
+    """Common ancestor for Secrets related exceptions."""
+
+
+class SecretAlreadyExistsError(SecretError):
+    """A secret that was to be added already exists."""
+
+
+class SecretsUnavailableError(SecretError):
+    """Secrets aren't yet available for Juju version used."""
+
+
+class IllegalOperationError(DataInterfacesError):
+    """To be used when an operation is not allowed to be performed."""