Provider overview

This section is for people adding a database, broker, or native worker integration to Runlane. If you only want to deploy Runlane, use choose a lane.

Start with the lane

A lane connects Runlane to infrastructure:

storage + delivery = lane

Every lane has storage. Delivery has two forms:

+--------- lane ---------+
| Storage                |
| - run state            |
| - atomic changes       |
|                        |
| Delivery               |
| - poll storage         |
| - transport wakeups    |
+------------------------+

Polling is a delivery mode, not a transport. A Postgres polling lane needs only Postgres. A Postgres and SQS lane uses Postgres for state and SQS for wakeups.

See the shipped combinations

memory + polling
  -> lane-local

Postgres + polling
  -> lane-postgres-polling

Postgres + SQS
  -> lane-postgres-sqs

These packages use the @runlane/ scope. Runlane currently ships production providers for Postgres storage and SQS transport.

Redis is an example of a storage provider you could build; it is not shipped today. The storage contract needs atomic changes across every key in one Runlane transition. A normally sharded Redis Cluster cannot provide that. A single-slot Redis topology may work, but it gives up normal cluster sharding.

Another broker can be a transport provider if it can publish Runlane's bytes and deliver them to a Runlane worker. The broker never becomes the source of truth.

Decide what you are building

Most provider packages own one infrastructure boundary. A lane package wires compatible pieces together:

storage ----+
            +--> lane --> createRunlane()
delivery ---+

Keep provider code mechanical

Providers store records, run transactions, publish bytes, receive messages, and map native failures. Runlane core decides whether a run should start, retry, wait, cancel, or finish.

Import public contracts, schemas, codecs, enums, and defaults from @runlane/contracts. Do not copy stable values into the provider.

Build in this order

1. Choose storage or delivery. Do not build both at once unless the infrastructure requires it.
2. Implement the smallest public contract.
3. Declare the real durability, ordering, clock, and size limits.
4. Add startup, shutdown, and native error mapping.
5. Run the shared conformance tests.
6. Test the real service, including failure and shutdown.
7. Compose the tested provider into a lane.