ObanPowertools

Copy Markdown View Source

Oban Powertools is a host-owned operations layer for Oban-backed Phoenix applications. The library owns internal runtime helpers, native pages, and bridge adapters. The host app owns router scope, browser pipeline, auth, display policy, runtime config, and seeded operator data.

Oban Powertools ships a unified native /ops/jobs control plane at /ops/jobs. oban_web is optional; when installed, Powertools mounts a nested read-only Oban Web bridge at /ops/jobs/oban for additional inspection. The native pages are Powertools-native surfaces for Audited action, while the bridge remains Inspection only. The diagnosis-first overview, cross-surface audit follow-up, and bounded native actions all belong to that same native control plane story.

0.x stability window: This library is published at 0.x on Hex. There is no API freeze yet — public surfaces may change before 1.0. The internal v1.x planning milestone numbers (v1.5, v1.6, etc.) track shipped tranches of work and do not map to published Hex versions. Adopt ~> 0.5 and expect occasional breaking changes until 1.0.

60-Second Install

Start from a fresh Phoenix host, then add Oban Powertools. The default paved road is the native shell at /ops/jobs, and oban_web stays optional for the nested read-only bridge at /ops/jobs/oban.

mix phx.new my_app --database postgres

def deps do
  [
    {:oban_powertools, "~> 0.5"},
    {:oban_web, "~> 2.10", optional: true}
  ]
end

Run the installer after adding the dependency:

mix oban_powertools.install

The installer generates migrations, a host auth seam, and a host display-policy seam: MyAppWeb.ObanPowertoolsAuth and MyAppWeb.ObanPowertoolsDisplayPolicy.

config :oban_powertools,
  repo: MyApp.Repo,
  auth_module: MyAppWeb.ObanPowertoolsAuth,
  display_policy: MyAppWeb.ObanPowertoolsDisplayPolicy

The host owns those modules. They are starter seams, not production-ready policy implementations.

Run the generated migrations, then mount the Powertools route tree inside a host-owned browser scope:

scope "/ops/jobs" do
  pipe_through(:browser)

  require ObanPowertools.Web.Router
  ObanPowertools.Web.Router.oban_powertools_routes("/oban")
end

Native Powertools pages then mount at /ops/jobs, and the optional oban_web bridge mounts at /ops/jobs/oban when oban_web is installed.

Before calling day-0 setup complete, make the generated host pass the bounded proof threshold:

mix compile
mix ecto.migrate
mix phx.server

mix ecto.reset is the equivalent reset path when you want a clean local proof run. The first successful operator session starts only after that compile, migrate or reset, and boot check has passed and a real native mutation succeeds.

Support Truth

  • supported: the native /ops/jobs shell is the supported operator surface, and native Powertools pages are the supported mutation surface.
  • supported: Powertools-native surfaces own diagnosis-first wording, legal next action, venue, and durable audit evidence.
  • supported: the canonical forensics handoff path is /ops/jobs -> /ops/jobs/forensics -> ownership-labeled next path -> /ops/jobs/audit.
  • supported: the optional /ops/jobs/oban bridge is supported only as a narrower read-only inspection annex and stays explicitly Inspection only.
  • supported: forensics labels are explicit support-truth boundaries; partial evidence, history unavailable, and unknown mean operators should treat certainty as bounded.
  • host-owned: downstream escalation and provider delivery outcomes remain host-owned follow-up.
  • supported: one singular upgrade lane is supported for hosts that already have Postgres/Ecto, repo, auth_module, /ops/jobs, and Powertools migrations in place and still need to add display_policy.
  • tested: the repo proves the fresh-host install lane, the native-first fixture lane, the first-session lane, the optional bridge render lane, the docs-contract lane, and the supported upgrade lane. Broader legacy workflow compatibility for waiting, retrying, cancelling, and recovery evidence is repo-local tested proof, not an expansion of the supported host lane.
  • best-effort: best-effort outside tested lanes applies to semver-allowed combinations, bridge-enabled or diverged source hosts, bespoke shells, and unusual proxy or session setups.
  • host-owned: the host owns router scope, browser pipeline, auth, actor/session lookup, display policy, runtime config, reverse-proxy and WebSocket behavior, seeded operator data, and whether the bridge is exposed in production.
  • intentionally unsupported: using the bridge as a mutation surface, hidden fallback behavior when required config is missing, non-Postgres support, and broader compatibility claims outside verified lanes.

Guides

  • Installation covers the exact host-owned setup path, including ObanPowertoolsAuth, ObanPowertoolsDisplayPolicy, and the compile/migrate/boot threshold.
  • First Operator Session walks from install to the canonical ops-demo -> pause_cron_entry on nightly_sync proof, forensic confirmation, audit follow-up, and the read-only bridge.
  • Forensics And Runbook Handoffs is the canonical v1.4 journey and ownership contract for /ops/jobs/forensics and /ops/jobs/audit.
  • Example App Walkthrough points to the canonical fixture at examples/phoenix_host.
  • Workers And Idempotency shows how to build typed workers and what enqueue/2 guarantees.
  • Limits And Explain covers limiter declarations, blocked outcomes, and blocker inspection.
  • Workflows explains the durable DAG builder, dependency release, and current runtime semantics.
  • Lifeline And Repairs covers heartbeat projection, incident diagnosis, repair preview, and audited execution.
  • Policy Integration Patterns shows how the host auth and display seams should be shaped in a real Phoenix app.
  • Optional Oban Web Bridge defines the bounded /ops/jobs/oban read-only annex for generic inspection only.
  • Support Truth And Ownership Boundaries expands the shared supported/tested/best-effort/host-owned/intentionally unsupported vocabulary.

Canonical Example Host

The canonical curated host fixture lives at examples/phoenix_host. It is the public reference path for mix phx.new plus mix oban_powertools.install, not a fully generated demo app. The tracked source tree is the config, lib, migrations, seeds, static assets, and focused tests that keep the documented host contract reviewable. Local build artifacts and vendored dependencies are not part of that public contract. examples/phoenix_host_upgrade_source exists separately only as the frozen source fixture for the supported upgrade lane.