Steward is an Oban plugin providing resource-oriented reconciliation of scheduled jobs against a dynamically calculated specification.
Steward is inspired by Kubernetes controllers and borrows some terminology and ideas from business rule engines, while staying unintrusive on your codebase.
Alpha {: .warning}
Steward is in an early stage of development. Expect bugs and breaking changes to its API and database schema between minor versions until 1.0.
How it works
Steward separates job trigger logic from domain operations to reduce redundancy and coupling in your domain logic.
Instead of queueing or scheduling jobs in operations, workers evaluate their preconditions themselves, deciding if and when they need to be run. Steward reconciles these workers periodically or on demand, enqueueing or updating Oban jobs as needed to keep them in sync with the calculated spec.
To keep the computational effort low, Steward shards the reconciliation loop and resulting Oban jobs by resource objects, which typically correspond to domain (process) entities. Entities are grouped by a controller which defines the set of workers to reconcile and serves as centralized boilerplate. Reconciliation of a single object is performed…
- after every job invocation (if job enters terminal state)
- periodically (see the
:reconcile_intervaloption ofSteward.Controller) - or on demand (see
Steward.Controller.schedule_resource!/2)
Installation
Requirements
- Elixir 1.16 or later
- Oban 2.22 or later, tested with the
Oban.Engines.Basicengine - PostgreSQL 12 or later. Steward relies on Postgres features (
jsonbcontainment,FOR UPDATE SKIP LOCKED), so Oban's SQLite and MySQL engines are not supported.
Dependency
Add steward to your dependencies:
def deps do
[
{:steward, "~> 0.1"}
]
end
Database migration
Steward stores resources in a dedicated, versioned table. See Steward.Migrations for options
and how to upgrade to newer versions.
$ mix ecto.gen.migration add_steward
defmodule MyApp.Repo.Migrations.AddSteward do
use Ecto.Migration
def up, do: Steward.Migrations.up(version: 1)
def down, do: Steward.Migrations.down(version: 1)
end
Index on oban_jobs
Oban jobs managed by Steward are tracked by attributes in their meta field. To ensure
performant lookups of these jobs, we recommend adding a dedicated index on the oban_jobs table.
See Steward.Migrations.add_index_to_oban_jobs/1 for options.
defmodule MyApp.Repo.Migrations.AddStewardIndexToObanJobs do
use Ecto.Migration
@disable_ddl_transaction true
@disable_migration_lock true
def up, do: Steward.Migrations.add_index_to_oban_jobs(concurrently: true)
def down, do: Steward.Migrations.remove_index_from_oban_jobs(concurrently: true)
end
Configuration
Steward module
Serves as Steward's resource repository, defining which Ecto.Repo and table details to
use to access resources. Define a module in your application as follows:
defmodule MyApp.Steward do
use Steward, repo: MyApp.Repo
end
See Steward.Config for available options.
Oban plugin
Your newly defined resource repository implements Oban's plugin interface. Install and configure Oban as usual. Steward can run on your existing Oban instance and will gladly ignore foreign jobs, or you can provide it with its own dedicated instance (recommended, see Oban's docs on instance isolation).
config :my_app, Oban,
repo: MyApp.Repo,
queues: [default: 10],
plugins: [
MyApp.Steward
]
All of Steward's active components will only run on Oban's peer leader node.
Oban.Pruner {: .warning}
If you enable Oban's pruner with its
:pruneroption, make sure you do not rely on Steward's job uniqueness in your workers. Instead, we advise that your worker'sc:Steward.Worker.perform/2implementation mutates application state in a way thatc:Steward.Worker.spec/3preconditions are invalidated.
Usage
Defining a controller
A controller defines the set of workers to reconcile for a resource type and implements type-specific callbacks used in the reconciliation and in workers.
defmodule MyApp.OrderController do
use Steward.Controller,
steward: MyApp.Steward,
reconcile_interval: :timer.hours(24)
@impl Steward.Controller
def workers, do: [MyApp.Steward.FulfillOrderWorker]
@impl Steward.Controller
def load(%Steward.Resource{} = resource) do
case MyApp.Orders.get!(resource.id) do
# Returning :cancel stops reconciliation of the resource object.
%{state: :cancelled} -> :cancel
# Fill the virtual `object` field with arbitrary data.
order -> {:ok, %{resource | object: order}}
end
end
end
See Steward.Controller for more information.
Defining a worker
defmodule MyApp.Steward.FulfillOrderWorker do
use Steward.Worker, queue: :default, max_attempts: 5
@impl Steward.Worker
def spec(spec, %{object: order} = _resource, _existing_resource_jobs) do
if order.fulfilled do
spec
else
schedule(spec, %{some: :arg}, scheduled_at: DateTime.add(order.inserted_at, 2, :day))
end
end
@impl Steward.Worker
def perform(_oban_job, %{object: order}) do
# Invalidates the order.fulfilled precondition in spec/3.
MyApp.Orders.mark_fulfilled!(order)
:ok
end
end
See Steward.Worker for more information.
Testing
Oban doesn't run plugins in its :manual and :inline testing modes, so Steward's
reconciliation loop won't run in your tests. Trigger it with Steward.Testing.reconcile/2:
test "fulfills the order" do
order = MyApp.Orders.create!()
{:ok, _} = MyApp.OrderController.create_resource(%{id: order.id})
{:ok, 1} = Steward.Testing.reconcile(MyApp.Oban, MyApp.Steward)
assert_enqueued worker: MyApp.Steward.FulfillOrderWorker
end
See Steward.Testing for more information.
Copyright and License
Copyright © 2026, Marko Switzerland AG.
You may use and redistribute Steward and its source code under the Apache 2.0 License, see the LICENSE file for details or visit:
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.