Documentation
tomodachi
Documentation

Questions and answers

What is the best way to operate a tomodachi service?

Docker containers are great and can be scaled out in Kubernetes, Nomad or other orchestration engines. Some may instead run several services on the same environment, on the same machine if their workloads are smaller or more consistent. Remember to gather your output and monitor your instances or clusters.

Go for a Dockerized environment if possible – preferably orchestrated with for example Kubernetes to handle automated scaling events to meet demand of incoming requests and/or event queues.

Make sure to follow the recommendations for production on good practices when operating services in production or staging environments.

Are there any more example services?

There are a few examples in the https://github.com/kalaspuff/tomodachi/blob/master/examples folder, including using tomodachi in an example Docker environment (with or without docker-compose).

There are examples to publish events / messages to an AWS SNS topic and subscribe to an AWS SQS queue. There's also a similar code available of how to work with pub/sub for RabbitMQ via the AMQP transport protocol.

What's the recommended setup to run integration tests?

When unit tests are not enough, you can run integration tests towards your services using the third party
library tomodachi-testcontainers. This library provides a way to run your service in a Docker container.

Why should I use this?

tomodachi is an easy way to start when experimenting with your architecture or trying out a concept for a new service – specially if you're working on services that publish and consume messages (pub-sub messaging), such as events or commands from AWS SQS or AMQP message brokers.

tomodachi processes message flows through topics and queues, with enveloping and receiving execution handling.

tomodachi may not have all the features you desire out of the box and it may never do, but I believe
it's great for bootstrapping microservices in async Python.

While tomodachi provides HTTP handlers, the library may not be the best choice today if you are solely building services that exposes REST or GraphQL API. In such case, you may be better off to use,
for example fastapi or litestar, perhaps in combination with strawberry as your preferred interface.

Note that the HTTP layer on top of tomodachi is using aiohttp, which provides a more raw interface than libraries such as fastapi or starlette.

I have some great additions!

Sweet! Please send me a PR with your ideas. There's now automatic tests that are running as GitHub actions to verify linting and regressions. Get started by cloning the repo and install the dev dependencies.

Is it safe with beta software in production?

There are some projects and organizations that already run services based on tomodachi in production. The library is provided as is with an unregular release schedule, and as with most software, there will be unfortunate bugs or crashes. Consider this currently as beta software (with a strong ambition to work for production use). Would be great to hear about other use-cases in the wild!

Another good idea is to drop in Sentry or other exception debugging solutions. These are great to catch errors if something wouldn't work as expected in the internal routing or if your service code raises unhandled exceptions.

Who built this and why?

@kalaspuff on GitHub

My name is Carl Oscar Aaro and I'm a coder from Sweden.

When I started writing the first few lines of this library back in 2016, my intention was to experiment with Python's asyncio, the event loop, event sourcing and message queues.

A lot has happened since -- now running services in both production and development clusters, while also using microservices for quick proof of concepts and experimentation. 🎉