feat(api): read-only JSON API for automation and AI agents

[thiagoesteves]

What

Adds Observer.Web.Router.observer_api/2: an opt-in, read-only JSON API over the same collectors the dashboard renders, aimed at automation and AI agents (the direction observer_cli 2.0 just validated with its JSON output).

• GET / - endpoints + visible nodes
• GET /system?node= - runtime info, VM limits, allocator utilization
• GET /processes?node=&sort_by=reductions|memory|message_queue_len&limit= - etop-style ranking (limit capped at 1000)
• GET /ets?node= - table metadata (size, memory, owner, protection)
• GET /apps?node= - running applications

The mount is deliberately separate from the dashboard (no session/LiveView) so hosts place it inside their own API auth pipeline:

scope "/" do
  pipe_through [:api, :my_api_auth]
  observer_api "/observer/api"
end

Security notes

• Access resolves through the same Observer.Web.Resolver behaviour; {:forbidden, _} renders a 403. All endpoints are read-only, so :all and :read_only are both accepted.
• ?node= values only resolve against currently known cluster nodes - crafted values never reach RPC and never allocate atoms; sort/limit params are whitelisted and bounded.
• Pids/references are serialized via inspect; unreachable nodes render a 502 instead of crashing.

Why

Part of the roadmap derived from comparing ObserverWeb against OTP observer, observer_cli and Phoenix LiveDashboard: a machine-readable surface makes ObserverWeb the richest BEAM data source an agent can query, reusing collectors that already exist.

Risk assessment

• Impact: additive opt-in macro; hosts that don't mount it see zero change.
• Blast radius: new Observer.Web.Api plug + router macro; collectors and dashboard untouched.
• Regression risk: low - suite green (405 tests, 96.0% coverage), credo/sobelow/dialyzer/format clean.
• Rollback plan: revert the commit; hosts drop the observer_api mount.

Checklist

• mix test green (405 tests)
• mix coveralls 96.0% (threshold 95%)
• mix credo --strict, mix sobelow, mix dialyzer, mix format --check-formatted clean
• Small focused diff, no leftover debug output

🤖 Generated with Claude Code