# grelmicro

> grelmicro is an async-first Python toolkit that ships microservice patterns as small composable modules with pluggable backends. It provides distributed locks, leader election, rate limiting, circuit breakers, cache, a transactional outbox, task scheduling, logging, tracing, metrics, and health checks. The same primitives serve microservices, a modular monolith, or a self-contained system.

Each primitive is a protocol, so Redis, PostgreSQL, SQLite, Kubernetes, and in-memory swap without an application change. grelmicro drops into FastAPI, Starlette, Litestar, FastStream, and any asyncio stack. It is pre-1.0 and follows semantic versioning. This index is curated. Every page of the site is listed in [llms-full.txt](https://grelmicro.grel.info/llms-full.txt).

## Getting started

- [Introduction](https://grelmicro.grel.info/): what grelmicro is and the problem it solves.
- [Installation](https://grelmicro.grel.info/installation/): install it and pick the extras.
- [First steps](https://grelmicro.grel.info/first-steps/): wire an app and use your first primitive.
- [Wiring](https://grelmicro.grel.info/wiring/): providers, components, and `micro.install(app)`, the one call that wires a framework.
- [Frameworks](https://grelmicro.grel.info/frameworks/): what `install` wires for FastAPI, Starlette, Litestar, and FastStream.
- Coming from another stack: [Spring Boot](https://grelmicro.grel.info/coming-from/spring-boot/), [Quarkus](https://grelmicro.grel.info/coming-from/quarkus/), [Django](https://grelmicro.grel.info/coming-from/django/), [Laravel](https://grelmicro.grel.info/coming-from/laravel/), [Symfony](https://grelmicro.grel.info/coming-from/symfony/), and [APScheduler, slowapi or aioredlock](https://grelmicro.grel.info/coming-from/python-libraries/) map their concepts to grelmicro.

## User guide

One page per module. Each one links the rest of its section.

- [Cache](https://grelmicro.grel.info/cache/): `TTLCache` over any backend. Start here, then [@cached](https://grelmicro.grel.info/cache/cached/).
- [Idempotency](https://grelmicro.grel.info/idempotency/): idempotency keys that make a retried operation safe.
- [Coordination](https://grelmicro.grel.info/coordination/): distributed `Lock`, `ReadWriteLock`, `TaskLock`, and `LeaderElection`.
- [Outbox](https://grelmicro.grel.info/outbox/): deliver messages at least once after your database transaction commits.
- [Task Scheduler](https://grelmicro.grel.info/task/): interval and cron tasks on every worker, or on one with `gate="claim"` or a leader election.
- [Resilience](https://grelmicro.grel.info/resilience/): start with [Shield](https://grelmicro.grel.info/resilience/shield/), the recommended entry point, and use [Stack](https://grelmicro.grel.info/resilience/composition/) to compose patterns you tuned yourself.
- [Health](https://grelmicro.grel.info/health/): liveness, readiness, and aggregate health endpoints.
- [HTTP](https://grelmicro.grel.info/http/): error responses, authentication, conditional requests, idempotency, caching, and rate limits on the wire.
- [Security](https://grelmicro.grel.info/security/): checks on an inbound request and tokens for an outbound one. [JWT](https://grelmicro.grel.info/security/jwt/) is the usual start.
- [Logging](https://grelmicro.grel.info/logging/): 12-factor logging with JSON, LOGFMT, TEXT, or PRETTY output.
- [Tracing](https://grelmicro.grel.info/tracing/): OpenTelemetry spans and log context through `@instrument`.
- [Metrics](https://grelmicro.grel.info/metrics/): OpenTelemetry metrics and a Prometheus endpoint.
- [Configuration](https://grelmicro.grel.info/config/): build with keyword arguments, tune with environment variables.
- [Deployment](https://grelmicro.grel.info/deployment/): run a grelmicro app in a container, and the backend scope check that refuses a per-process store in production.
- [Testing](https://grelmicro.grel.info/testing/): enter `micro.fake()` before the test client starts, so the app you ship runs on in-process stores.

## Optional

- [Full page index](https://grelmicro.grel.info/llms-full.txt): every page of the site, one line each.
- [API reference](https://grelmicro.grel.info/reference/cache/): every public symbol, generated from the source docstrings.
- [Architecture](https://grelmicro.grel.info/architecture/): design decisions, guarantees, and internals.
- [Providers](https://grelmicro.grel.info/providers/): the connection object behind every component.
- [Capability matrix](https://grelmicro.grel.info/capabilities/): which pattern and adapter combinations ship today.
- [Comparison](https://grelmicro.grel.info/comparison/): grelmicro next to aiocache, slowapi, pybreaker, tenacity, and aioredlock.
- [Performance](https://grelmicro.grel.info/performance/): where the overhead is and when it matters.
- [Migration](https://grelmicro.grel.info/migration/): what to change on each minor release.
- [Diagnostics](https://grelmicro.grel.info/diagnostics/): the startup warnings and their codes.
- [Roadmap](https://grelmicro.grel.info/roadmap/): where grelmicro is going.
- [Changelog](https://grelmicro.grel.info/changelog/): release notes for every version.
- [Contributing](https://github.com/grelinfo/grelmicro/blob/main/CONTRIBUTING.md): how to report bugs, request features, and contribute code.