Toa: Composable Application Runtime

Highly opinionated execution environment for low-code, eventually consistent, optionally distributed systems.

§Chapter I. Foundations

The ideas: the problem Toa solves and the principles behind its design.

1. Product–Platform Separation — business logic and the machinery around it; operations and declarations; what low-code means in Toa.
2. The Big Picture — components as logical boundaries, compositions as physical ones; the Context; why distribution is a property of deployment.
3. The Component — entity state and its exclusive ownership; operations and their phases; the operation context; events and receivers.
4. The Prototype — inherited state, operations, and events; the generic prototype; refinement and forwarding.
5. Eventual Consistency — one atomic change at a time; agreement between components through events; what the runtime guarantees and what the application models.

§Chapter II. Basics

The vocabulary of application code: what a component is made of and how its parts meet.

1. State — the schema; system properties; guards; associated entities; deletion.
2. Operations — transitions: creation, optimistic concurrency control, discarded changes; computations and effects; scopes; safety; the rules of a genuine operation; the unmanaged escape hatch.
3. Calls — logical addresses; input/query segregation; selecting state; local calls.
4. Replies — output; errors as answers; exceptions as failures; what a caller receives.
5. Events — events as consequences of committed changes; conditions, payloads, and trailers; receivers; events from outside the application.
6. Context — the only door out of an operation; calls, configuration, and aspects; why everything passes through it.

§Chapter III. Reliability

What the runtime promises when something fails, and what it leaves to the application.

1. Delivery — distributed exception handling: a failure reaches whoever is waiting, or is tried again and then kept; why an operation may run more than once.
2. Transactional Outbox — a state change and its events commit together; recovery of what failed to publish; at-least-once, unordered.
3. Transactional Inbox — the identity of a call; a repeated call changes state once; the limits of that promise.
4. Tasks — calls carried as events are, which nobody waits for; what an accepted task can count on and what it asks of the operation.
5. Continuity — an effect that picks up where it failed; steps and their answers.
6. Call Chains — the path a call carries; refused cycles; readonly chains.

§Chapter IV. Time and Flow

Work that does not fit a single request and a single reply.

1. Cadence — pulses and schedules a component gives itself; calls handed over to be made later; what each promises; time across regions.
2. Collection Streams — reading a collection of any size, and then only what changed in it.
3. Streamed Calls — replies and input that flow instead of being carried whole; what streamed input gives up.
4. Stateful Operations — calls addressed to one process; process memory; keeping the exception small.

§Chapter V. The Edge

How an application meets the world outside it.

1. Resources — the gateway; operations exposed as a tree of resources; directives; what a route narrows.
2. Identity and Access — identities and credentials; authentication; authorization declared on the tree; why operations do not check permissions.
3. Realtime — events routed to keys; streams served as resources; what a reader can rely on.
4. Procedures and Tools — the same routes as procedures and as tools a model calls, under the same rules.
5. Files — storages and entries; uploads without operations; workflows.

§Chapter VI. Platform Services

What the runtime provides beside the execution model.

1. Extensions — aspects, services, and components an extension brings; manifests and annotations; the supplied extensions.
2. Configuration — configuration as a contract; layers of values; secrets; changes while running.
3. Telemetry — traces, logs, and metrics; what the platform observes and what the application adds.
4. Introspection — the declared and observed topology of a running application.
5. Shared Decisions — what the replicas of a component decide together: partitioning, locking, metering.
6. Connectors — bridges, storages, and bindings as replaceable parts; capabilities and the guarantees that depend on them.

§Chapter VII. Running

The application as something that is deployed and operated.

1. Environments — one source, several places to run it; variation declared in the Context.
2. Compositions — the unit of deployment and scale; what grouping decides; services; what is left out.
3. Contracts — what a component knows about another; versions; what a rolling upgrade requires.
4. Deployment — what a process needs; the supplied tooling; images, secrets, and migrations.
5. Regions — deployments of one application converging on the same state; conflicts and their cost.
6. Halt — stopping a deployment at a moment when nothing is owed.