astrae

API reference

Runtime package

Buses, Redis, cache, loops, identify, health, metrics. You configure them on Client. Leave the adapters alone unless a page says they are public.

Cache guide, metrics.

Event delivery and Redis

Name Purpose
MemoryBus One process. Not cross-process.
Redis bus How workers see events. You run Redis; Astrae does not.
Duplicate delivery After a worker crash. Make side effects safe to repeat.
RedisPool.shared(url) One pool per URL in this Python process. Not across cluster children.
Pool defaults RESP2 (no HELLO), 2s command timeout, no retries, no idle PINGs.
Timeout circuit Cache writes and waiter lookups fail fast. Prefix commands still run.
Bus.publish / subscribe / close Bus surface.
RedisBus Partitions, worker leases, acks.
GatewayWorker.emit / events Publish / consume gateway events.
DeliveryLog Suppress repeat side effects for a delivery key. Match retention to your retry window.
open_bus(ipc, pool=...) Select bus from IPC config. Unconfigured local client → in-process.
Role monolith, gateway, or worker. Worker does not create sockets.

Cache

Name Purpose
CacheConfig Per-namespace CachePolicy.
CachePolicy enabled, size, ttl, optional fields. None means no bound, not "use the default".
CacheConfig.none() Disable every namespace.
CacheConfig.policy(name) Named policy.
Cache.build(pool, config) Memory adapter with no pool; Redis with one.
start / ingest / dispatch / flush / stop / clear Lifecycle.
Namespace ops get, model, of, all, count, contains.
Redis backend Normalized records and relationship indexes.
Memory backend Process-local entries.
MutationBuffer Batches set/patch/delete/clear/bulk before writes.
Full write queue Drop the update. Do not block gateway dispatch.
Command dispatch Reads the GUILD_CREATE guild blob. Does not scan emoji/sticker/member relations unless the callback uses them.

Cache is event-derived. It is not durable storage.

Identify and health

Name Purpose
IdentifyStore File-backed session/identify state. Optimization, not a source of truth.
report_service / service_states Component health probes.
Redis / database probes Connectivity at that moment. Not future availability.
PostHog / Tracelet Show in the cluster console after setup_posthog() / setup_tracelet().

Scheduling and observability

Name Purpose
@loop Periodic callback. Register with the client.
Scheduler Cron plus named locks. Separate from @loop.
LoopMonitor On. Stalls past 0.25s dump stacks, logs, metrics, dashboard. loop_monitor=False turns it off.
METRICS / Metrics Process-global registry. inc / set_gauge / observe.
snapshot() JSON.
render() Prometheus text. Process-local. Scrape every process.
Cluster 0 dashboard Merges Redis telemetry. Prometheus does not.
Cache stats That backend's counts. Not "how many guilds Discord gave you."
GcFreezer Aggressive collect/trim/freeze. Skips while chunks or the write queue are live.
gc_freeze=False Disable. GcFreezer() is freeze-only.
check_late Flag events that sat too long before dispatch.