Initial implementation of interface (#1)

* Initial project setup and stub out interfaces

* Start using TDD and rework APIs a bit

* Refactor test a bit, finish filling in request fields

* Finish Request implementation

Type hints don't work as well on Python 3.5 and don't provide any actual
validation in any case, so switched to Marshmallow for schema
definition, validation, and de/serialization.

* Implement Response class, except for creating from a Request

* Implement requesting and responding via interface APIs

There are still some outstanding issues with loading responses on the
providing side, as mentioned in the functional test, and the test needs
to be finished to verify the return trip of the response.

* Refactor how schema is used and complete implementation

* Add CODEOWNERS file

* Add events and flags, split functional test into separate tox env

* Add README and clear flags when all requests or responses have been processed

* Add GitHub Actions workflow for tests

* Add missing links in README

* Make Request.name a property since it should never be changed

* Make all_responses exclude empty responses and make address option on failed responses

* Split README into separate docs and examples

* Fix unnecessary escaping in API reference docs

* Add TOC to API reference

* Split schema out into versioned submodules to make it more clear how it will be extended in the future

Author: johnsca

.github/workflows/tests.yaml

@@ -0,0 +1,63 @@
+name: Test Suite
+
+on:
+  - pull_request
+
+jobs:
+  lint-unit-and-func-tests:
+    name: Lint, Unit, & Functional Tests
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: [3.5, 3.6, 3.7, 3.8, 3.9]
+    steps:
+    - name: Check out code
+      uses: actions/checkout@v2
+    - name: Setup Python
+      uses: actions/setup-python@v2
+      with:
+        python-version: ${{ matrix.python }}
+    - name: Install Tox
+      run: pip install tox
+    - name: Run lint, unit, and functional tests
+      run: tox
+
+  # TODO
+  #integration-test:
+  #  name: Integration test with LXD
+  #  runs-on: ubuntu-latest
+  #  timeout-minutes: 40
+  #  steps:
+  #  - name: Check out code
+  #    uses: actions/checkout@v2
+  #  - name: Setup Python
+  #    uses: actions/setup-python@v2
+  #    with:
+  #      python-version: 3.8
+  #  - name: Fix global gitconfig for confined snap
+  #    run: |
+  #      # GH automatically includes the git-lfs plugin and configures it in
+  #      # /etc/gitconfig.  However, the confinement of the charmcraft snap
+  #      # means that it can see that this file exists but cannot read it, even
+  #      # if the file permissions should allow it; this breaks git usage within
+  #      # the snap. To get around this, we move it from the global gitconfig to
+  #      # the user's .gitconfig file.
+  #      cat /etc/gitconfig >> $HOME/.gitconfig
+  #      sudo rm /etc/gitconfig
+  #  - name: Install Dependencies
+  #    run: |
+  #      pip install tox
+  #      sudo apt-get remove -qy lxd lxd-client
+  #      sudo snap install core
+  #      sudo snap install lxd
+  #      sudo lxd waitready
+  #      sudo lxd init --auto
+  #      sudo chmod a+wr /var/snap/lxd/common/lxd/unix.socket
+  #      echo "/snap/bin" >> $GITHUB_PATH
+  #      lxc network set lxdbr0 ipv6.address none
+  #      sudo snap install juju --classic
+  #      sudo snap install juju-wait --classic
+  #      sudo snap install charmcraft --beta
+  #      sudo snap install charm --classic
+  #  - name: Run integration tests
+  #    run: tox -e integration

CODEOWNERS

@@ -0,0 +1 @@
+@johnsca @joedborg

README.md

@@ -1,2 +1,63 @@
-# loadbalancer-interface
-"loadbalancer" interface protocol API library
+# `loadbalancer` Interface Protocol API Library
+
+This library provides an API for requesting and providing load balancers or
+ingress endpoints from one charm to another. It can be used in either charms
+written in the newer [Operator Framework][] or older charms still using the
+[charms.reactive Framework][].
+
+
+## Installation / Setup
+
+Include this library as a dependency for your charm, either in
+`requirements.txt` for Operator Framework charms, or `wheelhouse.txt` for
+reactive charms:
+
+```
+# TODO: publish this to PyPI
+https://github.com/juju-solutions/loadbalancer-interface/archive/master.zip#egg=loadbalancer_interface
+```
+
+## Usage
+
+### Requesting Load Balancers
+
+Requesting a load balancer from a provider is done via the `LBProvider` class.
+The general pattern for using the class is:
+
+  * Wait for the provider to become available
+  * Get a `Request` object via the `get_request(name)` method
+  * Set the appropriate fields on the request object
+  * Send the `Request` via the `send_request(request)` method
+  * Wait for the `Response` to be provided (or updated)
+  * Get the `Response` object via either the `get_response(name)` method or
+    via the `new_responses` property
+  * Confirm that the request was successful and use the provided LB's address
+  * Acknowledge the `Response` via `ack_response(response)`
+
+There are examples in the docs on how to do this in [an operator charm](docs/examples/requires_operator.md)
+or in [a reactive charm](docs/examples/requires_reactive.md).
+
+
+### Providing Load Balancers
+
+Providing a load balancer to consumers is done via the `LBConsumers` class.  The
+general pattern for using the class is:
+
+  * Wait for new or updated requests to come in
+  * Iterate over each request object in the `new_requests` property
+  * Create a load balancer according to the request's fields
+  * Set the appropriate fields on the request's `response` object
+  * Send the request's response via the `send_response(request)` method
+
+There are examples in the docs on how to do this in [an operator charm](docs/examples/provides_operator.md)
+or in [a reactive charm](docs/examples/provides_reactive.md).
+
+## API Reference
+
+See [the docs](docs/api.md) for detailed reference on the API.
+
+
+<!-- Links -->
+
+[Operator Framework]: https://github.com/canonical/operator/
+[charms.reactive Framework]: https://charmsreactive.readthedocs.io/

docs/api.md

@@ -0,0 +1,138 @@
+# API Reference
+
+## Table of Contents
+
+  * [`LBProvider` Class](#lbprovider-class)
+  * [`LBConsumers` Class](#lbconsumers-class)
+  * [`Request` Objects](#request-objects)
+  * [`HealthCheck` Objects](#healthcheck-objects)
+  * [`Response` Objects](#response-objects)
+
+-----------------------------------------
+
+## `LBProvider` Class
+
+This is the main API class for requesting load balancers from a provider charm.
+When instantiated, it should be passed a charm instance and a relation name.
+
+### Events
+
+  * `available` Emitted once the provider is available to take requests
+  * `responses_changed` Emitted whenever one or more responses have been received or updated
+
+### Methods
+
+  * `get_request(name)` Get or create a request with the given name
+  * `send_request(request)` Send the completed request to the provider
+  * `get_response(name)` Get the response to a specific request (equivalent to `get_request(name).response`)
+  * `ack_response(response)` Acknowledge a response so that it is no longer considered new or changed
+
+### Properties
+
+  * `is_available` Whether the provider is available to take requests
+  * `is_changed` Whether there are any new or changed responses which have not been acknowledged
+  * `all_responses` A list of all received responses, even if they have not changed
+  * `new_responses` A list of all responses which are new or have changed and not been acknowledged
+
+### Flags
+
+For charms using the older charms.reactive framework, the following flags will
+be automatically managed:
+
+  * `endpoint.{relation_name}.available` Set or cleared based on `is_available`
+  * `endpoint.{relation_name}.responses_changed` Set or cleared based on `is_changed`
+
+
+## `LBConsumers` Class
+
+This is the main API class for providing load balancers to consumer charms.
+When instantiated, it should be passed a charm instance and a relation name.
+
+### Events
+
+  * `requests_changed` Emitted whenever one or more requests have been received or updated
+
+### Methods
+
+  * `send_response(request)` Send the completed `Response` attached to the given `Request`
+
+### Properties
+
+  * `is_changed` Whether there are any new or changed requests which have not been responded to
+  * `all_requests` A list of all received requests, even if they have not changed
+  * `new_requests` A list of all requests which are new or have changed and not been responded to
+
+### Flags
+
+For charms using the older charms.reactive framework, the following flags will
+be automatically managed:
+
+  * `endpoint.{relation_name}.requests_changed` Set or cleared based on `is_changed`
+
+
+## `Request` Objects
+
+Represents a request for a load balancer.
+
+Acquired from `LBProvider.get_request(name)`, `LBConsumers.all_requests`, or `LBConsumers.new_requests`.
+
+### Properties
+
+  * `name` Name of the request (`str`, read-only)
+  * `response` `Reponse` to this request (will always exist, but may be "empty"; see below)
+  * `hash` An MD5 hash of the data for the request (`str`, read-only)
+
+### Fields
+
+  * `traffic_type` Type of traffic to route (`str`, required)
+  * `backends` List of backend addresses (`str`s, default: every units' `ingress-address`)
+  * `backend_ports` List of ports or `range`s to route (`int`s or `range(int, int)`, required)
+  * `algorithm` List of traffic distribution algorithms, in order of preference (`str`s, optional)
+  * `sticky` Whether traffic "sticks" to a given backend (`bool`, default: `False`)
+  * `health_checks` List of `HealthCheck` objects (see below, optional)
+  * `public` Whether the address should be public (`bool`, default: `True`)
+  * `tls_termination` Whether to enable TLS termination (`bool`, default: `False`)
+  * `tls_cert` If TLS termination is enabled, a manually provided cert (`str`, optional)
+  * `tls_key` If TLS termination is enabled, a manually provided key (`str`, optional)
+  * `ingress_address` A manually provided ingress address (optional, may not be supported)
+  * `ingress_ports` A list of ingress ports or `range`s (`int`s or `range(int, int)`; default: `backend_ports`)
+
+### Methods
+
+  * `add_health_check(**fields)` Create a `HealthCheck` object (see below) with the given fields and add it to the list.
+
+
+## `HealthCheck` Objects
+
+Represents a health check endpoint to determine if a backend is functional.
+
+Acquired from `Request.add_health_check()`, or `Request.health_checks`.
+
+### Fields
+
+  * `traffic_type` Type of traffic to use to make the check (e.g., "https", "udp", etc.) (`str`, required)
+  * `port` Port to check on (`int`, required)
+  * `path` Path on the backend to check (e.g., for "https" or "http" types) (`str`, optional)
+  * `interval` How many seconds to wait between checks (`int`, default: 30)
+  * `retries` How many failed attempts before considering a backend down (`int`, default: 3)
+
+
+## `Response` Objects
+
+Represents a response to a load balancer request.
+
+Acquired from `Request.response`.  A `Request` object will always have a
+`response` attribute, but the response might be "empty" if it has not been
+filled in with valid data, in which case `bool(response)` will be `False`.
+
+### Properties
+
+  * `name` Name of the request (`str`, read-only)
+  * `hash` An MD5 hash of the data for the request (read-only)
+
+### Fields
+
+  * `success` Whether the request was successful (`bool`, required)
+  * `message` If not successful, an indication as to why (`str`, required if `success` is `False`)
+  * `address` The address of the LB (`str`, required if `success` is `True`)
+  * `request_hash` The hash of the `Request` when this `Response` was sent (`str`, set automatically)

docs/examples/provides_operator.md

@@ -0,0 +1,42 @@
+# Operator Framework Provides Charm Example
+
+## `metadata.yaml`
+
+```yaml
+provides:  # provides LBs to consumers
+  lb-consumers:
+    interface: loadbalancer
+```
+
+## `src/charm.py`
+
+```python
+import logging
+
+from ops.charm import CharmBase
+from ops.model import ActiveStatus, BlockedStatus
+
+from loadbalancer_interface import LBConsumers
+
+
+log = logging.getLogger(__name__)
+
+
+class MyCharm(CharmBase):
+    def __init__(self, *args):
+        super().__init__(*args)
+        self.lb_consumers = LBConsumers(self, 'lb-consumers')
+
+        self.framework.observe(self.lb_consumers.on.requests_changed,
+                               self._provide_lbs)
+
+    def _provide_lbs(self, event):
+        for request in self.lb_consumers.new_requests:
+            try:
+                request.response.address = self._create_lb(request)
+                request.response.success = True
+            except LBError as e:
+                request.response.success = False
+                request.response.message = e.message
+            self.lb_consumers.send_response(request)
+```

docs/examples/provides_reactive.md

@@ -0,0 +1,29 @@
+# charms.reactive Framework Provides Charm Example
+
+## `metadata.yaml`
+
+```yaml
+provides:  # provides LBs to consumers
+  lb-consumers:
+    interface: loadbalancer
+```
+
+## `reactive/my_charm.py`
+
+```python
+from charms.reactive import when, endpoint_from_name
+from charms import layer
+
+
+@when('endpoint.lb-consumers.requests_changed')
+def get_lb():
+    lb_consumers = endpoint_from_name('lb-consumers')
+    for request in lb_consumers.new_requests:
+        try:
+            request.response.address = layer.my_charm.create_lb(request)
+            request.response.success = True
+        except LBError as e:
+            request.response.success = False
+            request.response.message = e.message
+        lb_consumers.send_response(request)
+```

docs/examples/requires_operator.md

@@ -0,0 +1,48 @@
+# Operator Framework Requires Charm Example
+
+## `metadata.yaml`
+
+```yaml
+requires:  # consumes a LB from a provider
+  lb-provider:
+    interface: loadbalancer
+    limit: 1  # only supports a single LB provider per relation endpoint
+```
+
+## `src/charm.py`
+
+```python
+import logging
+
+from ops.charm import CharmBase
+from ops.model import ActiveStatus, BlockedStatus
+
+from loadbalancer_interface import LBProvider
+
+
+log = logging.getLogger(__name__)
+
+
+class MyCharm(CharmBase):
+    def __init__(self, *args):
+        super().__init__(*args)
+        self.lb_provider = LBProvider(self, 'lb-provider')
+
+        self.framework.observe(self.lb_provider.on.available, self._request_lb)
+        self.framework.observe(self.lb_provider.on.responses_changed, self._get_lb)
+
+    def _request_lb(self, event):
+        request = self.lb_provider.get_request('my-service')
+        request.traffic_type = 'https'
+        request.backend_ports = [443]
+        self.lb_provider.send_request(request)
+
+    def _get_lb(self, event):
+        response = self.lb_provider.get_response('my-service')
+        if not response.success:
+            self.unit.status = BlockedStatus(response.message)
+            return
+        log.info(f'LB is available at {response.address}')
+        self.lb_provider.ack_response(response)
+        self.unit.status = ActiveStatus()
+```