hexkit 3.0.0

A Toolkit for Building Microservices using the Hexagonal Architecture

hexkit

A chassis library for building domain-focused, infrastructure-agnostic and event-driven microservices in Python.

In a Nutshell

This project implements the Triple Hexagonal Architecture pattern which is an optimization of the ordinary Hexagonal Architecture for use with microservices. In brief, adapters (as per the hexagonal architecture) are divided into two parts. One part called translator is specific to one individual microservice and its domain-oriented ports. The other part called provider is service-agnostic but specific to one technology of the surrounding infrastructure. Both parts interact through a high-level interface called protocol (not to be confused with Python's typing.Protocol) which is neither specific to the technology nor to the microservice. For more details on the Triple Hexagonal Architecture, refer to the concept paper that can be found here.

As a chassis lib, hexkit tries to reduce the redundancy and boilerplate across microservices. It does so by providing ready-to-use triple-hexagonal building blocks that are service-independent - hence protocols and providers. The only task that remains for an individual service is to implement service-specific translators between the service's ports and the general-purpose protocols (in addition to implementing the domain functionality of the service, of course).

Hexkit is designed as a general-purpose library. However, currently, it only contains a very limited collection of protocol-provider pairs that are of immediate interest to the authors. We like to add support for more protocols and technologies over time.

The following protocols and providers are currently available:

Protocol	Providers
Event Publishing	Apache Kafka
Event Subscription	Apache Kafka
Object Storage	S3(-compatible)
Data Access Object	MongoDB

Hexkit does not force you to go all-in on the idea of Triple Hexagonal Architecture. You can use it just for the technologies where you see benefits and use another approach for the rest. For example, you could use hexkit for simplifying the exchange of events between microservices but use a classical web framework such as FastAPI for designing REST API and an ORM like SQLAlchemy for interacting with databases.

Please also feel free to develop hexagonal components yourself (using the base classes of hexkit or not). Not every protocol or provider has to be general-purpose, however, if they are, please consider contributing them to hexkit.

Getting started

Please have a look at the example application described in ./examples/stream_calc.

We put a lot of effort into making the code self-documenting, so please do not be afraid of jumping directly into it. You can find the protocols being defined at ./src/hexkit/protocols and the providers being implemented at ./src/hexkit/providers.

A more elaborate documentation and tutorial is on the way.

Installation

This package is available at PyPI: https://pypi.org/project/hexkit

You can install it from there using:

pip install hexkit

The following extras are available:

• akafka: when using the Apache Kafka-based event publishing or subscription
• s3: when interacting with S3-compatible Object Storages
• mongodb: when using mongodb as backend for the DAO protocol
• test-akafka: testing utils for Apache Kafka
• test-s3: testing utils for S3-compatible Object Storages
• test-mongodb: testing utils for MongoDB
• all: a union of all the above

Development

For setting up the development environment, we rely on the devcontainer feature of vscode.

To use it, you have to have Docker as well as vscode with its "Remote - Containers" extension (ms-vscode-remote.remote-containers) extension installed. Then, you just have to open this repo in vscode and run the command Remote-Containers: Reopen in Container from the vscode "Command Palette".

This will give you a full-fledged, pre-configured development environment including:

• infrastructural dependencies of the service (databases, etc.)
• all relevant vscode extensions pre-installed
• pre-configured linting and auto-formating
• a pre-configured debugger
• automatic license-header insertion

Moreover, inside the devcontainer, there is follwing convenience command available (please type it in the integrated terminal of vscode):

• dev_install - install the lib with all development dependencies and pre-commit hooks (please run that if you are starting the devcontainer for the first time or if added any python dependencies to the ./setup.cfg)

If you prefer not to use vscode, you could get a similar setup (without the editor specific features) by running the following commands:

# Execute in the repo's root dir:
cd ./.devcontainer

# build and run the environment with docker-compose
docker build -t hexkit .
docker run -it hexkit /bin/bash

License

This repository is free to use and modify according to the Apache 2.0 License.