Getting started

This page gives a high-level overview of what a walnats-based project looks like. It’s ok if you have unanswered questions after reading it. Later pages will dive into more details. This documentation targets to be as clear and approachable as possible with the cost of repetition.

Overview

Walnats is a Python library for writing event-driven services. Being event-driven means that when a service (producer or publisher) wants to run some job in the background, on schedule, or in another internal service, that service emits an event. The event tells other services that something happened in the system. Other services (subscribers) may have one or multiple actors that listen to events and handle them in some way.

For example, your project may have a “users” service that emits a “user-registered” event. And then “notifications” service may have a “send-email” actor that sends a welcome email to the newly registered user.

This decoupling is a very powerful idea that allows scaling services in a microservices architecture fast and independently. You may run multiple instances of the same actor, and walnats will make sure to evenly distribute the job among them. Or you can add a new actor (let’s say, you now want to also send an SMS to the registered user) without changing a line of code in the service emitting the event.

Components

A typical walnats-based service consists of a few parts, each having its own name and serving a distinct purpose:

  1. A schema describes the type of data you want to send in the event. For example, it can be a pydantic model User that has fields id: int and full_name: str.

  2. An event (walnats.Event) connects the event (identified by a name that is unique across the system) to a schema. For example, we can say that user-registered event has a User schema of data. It allows us to ensure type safety for both the publisher and the subscriber.

  3. A collection of events (walnats.Events) is used to emit events.

  4. A handler is a function that gets called when an event happens. It gets called with a message (a value of the schema type, the event payload) and can do inside anything it needs to do.

  5. An actor (walnats.Actor) connects a handler to an event. It makes sure to call the handler when an event occurs.

  6. A collection of actors (walnats.Actors) is used to listen to all relevant events.

Here is a little memo of how these things are related to each other:

schema

If you encounter an unfamiliar term in this documentation, check out Glossary. If the term is missed there, send a Pull Request.

Before you start

If you like a hands-on approach and want to write your own project as you follow along, you need to prepare the environment first:

  1. Install walnats: python3 -m pip install walnats

  2. Install nats server: go install github.com/nats-io/nats-server/v2@latest

  3. Run nats server: nats-server --jetstream