Metadata-Version: 2.4
Name: archipellabs-runtime
Version: 0.3.0
Summary: Async Redis runtime: services that call, dispatch and emit — Moleculer semantics on Redis Streams
Author-email: Loïc Veyssière <loic.veyssiere@archipellabs.com>
License-Expression: MIT
Project-URL: Homepage, https://archipellabs.com
Project-URL: Repository, https://github.com/archipellabs/runtime
Project-URL: Documentation, https://github.com/archipellabs/runtime/blob/main/doc/index.md
Project-URL: Changelog, https://github.com/archipellabs/runtime/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/archipellabs/runtime/issues
Keywords: redis,asyncio,streams,task-queue,orchestration,microservices,rpc,request-reply,pubsub,moleculer,job-queue,load-testing
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Framework :: AsyncIO
Classifier: Operating System :: OS Independent
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: redis>=5
Requires-Dist: pydantic>=2.12
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: pytest-timeout>=2.2; extra == "dev"
Requires-Dist: pytest-cov>=5; extra == "dev"
Requires-Dist: fakeredis>=2.21; extra == "dev"
Requires-Dist: mypy>=1.8; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Provides-Extra: playwright
Requires-Dist: playwright>=1.40; extra == "playwright"
Dynamic: license-file

# archipellabs-runtime

An async runtime for distributing work over Redis — Playwright sessions, API
calls, SSE streams, timed waits — without losing control of how many run at once.

These tasks spend most of their time *waiting* (on a network call, a browser, a
timer), so you want many of them going at once. Two easy approaches both break:

- **A new task per event:** a spike starts thousands at once and falls over — too
  many browsers, too many open connections.
- **One at a time:** safe, but a single slow call holds up everything behind it.
  All that waiting happens in sequence instead of together.

A **service** is the middle ground: a fixed budget of workers (`max_slots`, say
20) sharing the work. Up to 20 run together — enough to overlap the waiting — and
never more. Each service has its own budget, so a slow batch of browser sessions
cannot hog the workers your API calls need.

Services talk to each other with three verbs and nothing else. No registry, no
service discovery, no configuration tying them together: a producer in one process
and a consumer in another agree because they share a string.

> Distribution name `archipellabs-runtime`; it imports as `runtime`.

## Install

```sh
pip install archipellabs-runtime   # requires Python 3.12+ and a Redis server
```

## Quickstart

```python
import os
from runtime import App, Service

pricing = Service("pricing", max_slots=20)

@pricing.action("pricing.quote")          # one executant, returns a value
async def quote(ctx, params):
    return {"total": round(19.99 * params["qty"], 2)}

@pricing.event("order.placed")            # every subscriber gets a copy
async def note_order(ctx, params):
    print(f"order {params['id']}")

@pricing.every("500ms")                   # runs on a schedule
async def tick(ctx):
    total = await ctx.call("pricing.quote", qty=3)
    print(f"quote: {total}")

app = App(redis=os.environ.get("REDIS_URL", "redis://localhost:6379/0"))
app.include(pricing)
app.start()                               # blocking; logs the topology first
```

## The three verbs

| | Cardinality | Reply | Caller |
|---|---|---|---|
| `await ctx.call(action, **params)` | exactly one executant | the return value, awaited | coupled in time |
| `await ctx.dispatch(action, **params)` | exactly one executant | a task id | not coupled |
| `await ctx.emit(event, **params)` | every subscriber | none | not coupled |

Every message can carry a `ttl` — a deadline that travels with it, and that any
`call` or `dispatch` the handler makes inherits and can only narrow — and a
`delay`. Failures cross the wire as typed errors and are re-raised in the caller.
Actions can declare a pydantic model for their params and get validation before
the handler runs.

```python
await ctx.call("pricing.quote", ttl="2s", qty=3)
await ctx.dispatch("report.build", delay="30s", month="2026-07")
await ctx.emit("order.placed", id="o1")
```

### Prior art

The semantics are lifted from **[Moleculer](https://moleculer.services)** — actions,
`call`, a propagated context, typed errors, distributed timeouts. What is not taken
is its protocol: no registry, no heartbeats, no discovery, because Redis Streams
already do that. `dispatch` is the one addition, where Moleculer folds decoupled
work into a balanced `emit`.

[doc/index.md](https://github.com/archipellabs/runtime/blob/main/doc/index.md) has
the argument; [doc/limits.md](https://github.com/archipellabs/runtime/blob/main/doc/limits.md)
has what it costs.

## Shared resources

A service's `lifespan` opens what its handlers share — a browser, a DB pool, an
API client — once at boot, and closes it on shutdown.

```python
from contextlib import asynccontextmanager

@asynccontextmanager
async def store(config):
    db = await connect(config["dsn"])
    try:
        yield {"db": db}                  # → ctx.resources["db"]
    finally:
        await db.close()

warehouse = Service("warehouse", max_slots=8, lifespan=store)

@warehouse.action("order.fulfil")
async def fulfil(ctx, params):
    await ctx.resources["db"].fulfil(params["id"])

app.include(warehouse, config={"dsn": "postgres://…"})
```

## Documentation

Full documentation is in [`doc/`](https://github.com/archipellabs/runtime/blob/main/doc/index.md):

| | |
|---|---|
| [concepts](https://github.com/archipellabs/runtime/blob/main/doc/concepts.md) | services, the three verbs, choosing between them |
| [messages](https://github.com/archipellabs/runtime/blob/main/doc/messages.md) | the envelope, correlation, deadlines, errors, params |
| [internals](https://github.com/archipellabs/runtime/blob/main/doc/internals.md) | the keyspace, a message's life, what runs in a process |
| [operations](https://github.com/archipellabs/runtime/blob/main/doc/operations.md) | budgets, runtime switches, deployment, `App` knobs |
| [limits](https://github.com/archipellabs/runtime/blob/main/doc/limits.md) | what this deliberately does not do — **read before deploying** |

Runnable examples in [`examples/`](https://github.com/archipellabs/runtime/tree/main/examples):

- [`minimal`](https://github.com/archipellabs/runtime/tree/main/examples/minimal) — one service, one action, one producer
- [`rpc`](https://github.com/archipellabs/runtime/tree/main/examples/rpc) — `call`, typed errors, params validation, a ttl expiry
- [`events`](https://github.com/archipellabs/runtime/tree/main/examples/events) — fan-out to independent subscribers
- [`jobs`](https://github.com/archipellabs/runtime/tree/main/examples/jobs) — `dispatch` + `task_status`, a `delay`, and a runtime switch
- [`orders`](https://github.com/archipellabs/runtime/tree/main/examples/orders) — two processes, lifespans on both sides
- [`poisson`](https://github.com/archipellabs/runtime/tree/main/examples/poisson) — a service that consumes *and* produces
- [`playwright`](https://github.com/archipellabs/runtime/tree/main/examples/playwright) — a heavy, isolated cost profile

Upgrading from 0.2? The API is replaced — see
[CHANGELOG.md](https://github.com/archipellabs/runtime/blob/main/CHANGELOG.md).

## Deployment

The same App runs in one process, split by role, or scaled to N replicas with no
code change. `App(namespace=...)` isolates environments sharing one Redis;
`include(enabled=False)` leaves a service out of a process entirely, and runtime
[switches](https://github.com/archipellabs/runtime/blob/main/doc/operations.md#switches)
pause one that is mounted.

## Development

```sh
uv sync --extra dev
uv run python -m pytest                             # auto-detects a backend
RUNTIME_TEST_BACKEND=fake uv run python -m pytest   # CI runs both legs
RUNTIME_TEST_BACKEND=real uv run python -m pytest   # needs a Redis on :6379
uv run python -m pytest --cov=runtime --cov-report=term-missing
uv run mypy && uv run ruff check .
```

## License

MIT — see [LICENSE](LICENSE).
