+#!/usr/bin/env python3
+# Copyright 2022 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.
+#
+# For those usages not covered by the Apache License, Version 2.0 please
+# contact: legal@canonical.com
+#
+# To get in touch with the maintainers, please contact:
+# osm-charmers@lists.launchpad.net
+#
+#
+# Learn more at: https://juju.is/docs/sdk
+
+"""Nbi library.
+
+This [library](https://juju.is/docs/sdk/libraries) implements both sides of the
+`nbi` [interface](https://juju.is/docs/sdk/relations).
+
+The *provider* side of this interface is implemented by the
+[osm-nbi Charmed Operator](https://charmhub.io/osm-nbi).
+
+Any Charmed Operator that *requires* NBI for providing its
+service should implement the *requirer* side of this interface.
+
+In a nutshell using this library to implement a Charmed Operator *requiring*
+NBI would look like
+
+```
+$ charmcraft fetch-lib charms.osm_nbi.v0.nbi
+```
+
+`metadata.yaml`:
+
+```
+requires:
+ nbi:
+ interface: nbi
+ limit: 1
+```
+
+`src/charm.py`:
+
+```
+from charms.osm_nbi.v0.nbi import NbiRequires
+from ops.charm import CharmBase
+
+
+class MyCharm(CharmBase):
+
+ def __init__(self, *args):
+ super().__init__(*args)
+ self.nbi = NbiRequires(self)
+ self.framework.observe(
+ self.on["nbi"].relation_changed,
+ self._on_nbi_relation_changed,
+ )
+ self.framework.observe(
+ self.on["nbi"].relation_broken,
+ self._on_nbi_relation_broken,
+ )
+ self.framework.observe(
+ self.on["nbi"].relation_broken,
+ self._on_nbi_broken,
+ )
+
+ def _on_nbi_relation_broken(self, event):
+ # Get NBI host and port
+ host: str = self.nbi.host
+ port: int = self.nbi.port
+ # host => "osm-nbi"
+ # port => 9999
+
+ def _on_nbi_broken(self, event):
+ # Stop service
+ # ...
+ self.unit.status = BlockedStatus("need nbi relation")
+```
+
+You can file bugs
+[here](https://osm.etsi.org/bugzilla/enter_bug.cgi), selecting the `devops` module!
+"""
+from typing import Optional
+
+from ops.charm import CharmBase, CharmEvents
+from ops.framework import EventBase, EventSource, Object
+from ops.model import Relation
+
+
+# The unique Charmhub library identifier, never change it
+LIBID = "8c888f7c869949409e12c16d78ec068b"
+
+# Increment this major API version when introducing breaking changes
+LIBAPI = 0
+
+# Increment this PATCH version before using `charmcraft publish-lib` or reset
+# to 0 if you are raising the major API version
+LIBPATCH = 1
+
+NBI_HOST_APP_KEY = "host"
+NBI_PORT_APP_KEY = "port"
+
+
+class NbiRequires(Object): # pragma: no cover
+ """Requires-side of the Nbi relation."""
+
+ def __init__(self, charm: CharmBase, endpoint_name: str = "nbi") -> None:
+ super().__init__(charm, endpoint_name)
+ self.charm = charm
+ self._endpoint_name = endpoint_name
+
+ # Observe relation events
+ event_observe_mapping = {
+ charm.on[self._endpoint_name].relation_changed: self._on_relation_changed,
+ }
+ for event, observer in event_observe_mapping.items():
+ self.framework.observe(event, observer)
+
+ @property
+ def host(self) -> str:
+ """Get nbi hostname."""
+ relation: Relation = self.model.get_relation(self._endpoint_name)
+ return (
+ relation.data[relation.app].get(NBI_HOST_APP_KEY)
+ if relation and relation.app
+ else None
+ )
+
+ @property
+ def port(self) -> int:
+ """Get nbi port number."""
+ relation: Relation = self.model.get_relation(self._endpoint_name)
+ return (
+ int(relation.data[relation.app].get(NBI_PORT_APP_KEY))
+ if relation and relation.app
+ else None
+ )
+
+
+class NbiProvides(Object):
+ """Provides-side of the Nbi relation."""
+
+ def __init__(self, charm: CharmBase, endpoint_name: str = "nbi") -> None:
+ super().__init__(charm, endpoint_name)
+ self._endpoint_name = endpoint_name
+
+ def set_host_info(self, host: str, port: int, relation: Optional[Relation] = None) -> None:
+ """Set Nbi host and port.
+
+ This function writes in the application data of the relation, therefore,
+ only the unit leader can call it.
+
+ Args:
+ host (str): Nbi hostname or IP address.
+ port (int): Nbi port.
+ relation (Optional[Relation]): Relation to update.
+ If not specified, all relations will be updated.
+
+ Raises:
+ Exception: if a non-leader unit calls this function.
+ """
+ if not self.model.unit.is_leader():
+ raise Exception("only the leader set host information.")
+
+ if relation:
+ self._update_relation_data(host, port, relation)
+ return
+
+ for relation in self.model.relations[self._endpoint_name]:
+ self._update_relation_data(host, port, relation)
+
+ def _update_relation_data(self, host: str, port: int, relation: Relation) -> None:
+ """Update data in relation if needed."""
+ relation.data[self.model.app][NBI_HOST_APP_KEY] = host
+ relation.data[self.model.app][NBI_PORT_APP_KEY] = str(port)
projects / osm / devops.git / commitdiff