# grelmicro

> grelmicro is a lightweight, 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 you can swap Redis for PostgreSQL, SQLite, Kubernetes, or in-memory without changing application code. grelmicro is async-first, type-safe, and fully tested, and it drops into FastAPI, FastStream, and any asyncio stack. It is pre-1.0 and follows semantic versioning.

## Getting started

- [Introduction](https://grelmicro.grel.info/): what grelmicro is and the problem it solves.
- [Installation](https://grelmicro.grel.info/installation/): install with pip, uv, or poetry, plus optional extras for Redis, PostgreSQL, SQLite, Kubernetes, OpenTelemetry, and structlog.
- [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 the application lifespan.

## User guide

- [Cache](https://grelmicro.grel.info/cache/): `TTLCache`, backends, serializers, tags, and batch operations.
- [The @cached decorator](https://grelmicro.grel.info/cache/cached/): custom keys, refresh, streaming producers, stampede protection, and serve-stale-on-error.
- [Idempotency](https://grelmicro.grel.info/idempotency/): idempotency keys that make a retried operation safe.
- [Idempotency middleware](https://grelmicro.grel.info/idempotency/middleware/): replay a whole HTTP response when a request repeats its `Idempotency-Key` header.
- [Coordination](https://grelmicro.grel.info/coordination/): pick a backend for distributed `Lock`, `ReadWriteLock`, `TaskLock`, and `LeaderElection`.
- [Lock](https://grelmicro.grel.info/coordination/lock/): distributed mutual exclusion, bounded acquire, lease extension, and fencing tokens.
- [Read-Write Lock](https://grelmicro.grel.info/coordination/read-write-lock/): many readers at once, one writer alone, with typed guards and poison detection.
- [Task Lock](https://grelmicro.grel.info/coordination/task-lock/): a lock for scheduled tasks that holds past completion to stop re-execution.
- [Leader Election](https://grelmicro.grel.info/coordination/leader-election/): elect one worker for a long-lived role, with the lease record and `lead`.
- [Outbox](https://grelmicro.grel.info/outbox/): a transactional outbox that delivers messages at least once after your database transaction commits.
- [Outbox producer](https://grelmicro.grel.info/outbox/producer/): `publish` inside your own transaction, with SQLModel, SQLAlchemy, and FastAPI.
- [Outbox consumer](https://grelmicro.grel.info/outbox/consumer/): handlers, the `Message` fields, retry control, and dead-lettering.
- [Outbox relay](https://grelmicro.grel.info/outbox/relay/): scaling the relay, retention, observability, and every configuration field.
- [Outbox schema](https://grelmicro.grel.info/outbox/schema/): the table layout and managing it with Alembic.
- [Task Scheduler](https://grelmicro.grel.info/task/): interval and cron tasks with durable, distributed at-most-once execution.
- [Resilience](https://grelmicro.grel.info/resilience/): circuit breaker and rate limiter with pluggable algorithms.
- [Health](https://grelmicro.grel.info/health/): health checks with FastAPI liveness and readiness integration.
- [Logging](https://grelmicro.grel.info/logging/): 12-factor logging with JSON, LOGFMT, TEXT, or PRETTY output.
- [Logging integrations](https://grelmicro.grel.info/logging/integrations/): OpenTelemetry trace context, FastAPI, and uvicorn access logs.
- [Logging filters](https://grelmicro.grel.info/logging/filters/): deduplicate and rate limit a noisy logger.
- [Tracing](https://grelmicro.grel.info/tracing/): OpenTelemetry spans and structured log context through `@instrument`.
- [Metrics](https://grelmicro.grel.info/metrics/): OpenTelemetry metrics with a `@measure` decorator and a Prometheus router.
- [Configuration](https://grelmicro.grel.info/config/): reconfigure live components from a ConfigMap, Secret, or file.
- [Deployment](https://grelmicro.grel.info/deployment/): run a grelmicro app in a container, starting with the `GREL_ENV_LOAD` opt-in.
- [Testing](https://grelmicro.grel.info/testing/): test grelmicro apps with the in-memory backends.

## API reference

- [API reference](https://grelmicro.grel.info/reference/cache/): reference for every public module, generated from the source docstrings.

## Architecture

- [Architecture](https://grelmicro.grel.info/architecture/): design decisions, backends, asyncio model, and internals.

## Optional

- [Providers](https://grelmicro.grel.info/providers/): the connection object behind every component, its construction forms, lifecycle, and factory methods.
- [Redis and Valkey](https://grelmicro.grel.info/providers/redis/): environment variables, Sentinel, Cluster, and the hash-tag rule.
- [Postgres](https://grelmicro.grel.info/providers/postgres/): environment variables, `command_timeout`, and splitting reader and writer pools.
- [Comparison](https://grelmicro.grel.info/comparison/): grelmicro next to aiocache, slowapi, pybreaker, tenacity, and aioredlock.
- [Benchmarks](https://grelmicro.grel.info/benchmarks/): performance measurements for the primitives.
- [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.
