feat(live-runner): session-owned payment lifecycle for streamed sessions

[rickstaa]

Draft for review and comparison against Josh's ja/live-runner branch.

What this adds

Streamed live-runner sessions (trickle / websocket) must keep paying for as long as the session is open. After the reservation 402, go-livepeer holds the session as a prepaid balance: ReserveLiveRunnerSession (server/ai_http.go) spawns a server-side ticker (-livePaymentInterval, 5s default) that debits the balance and silently releases the session once it runs dry. There is no further 402; the client must keep crediting out of band via POST /payment. Unlike call_runner (request/response, where the orchestrator pulls payment via a 402 inline), a held-open transport has no request to attach payment to, so the client pushes on a cadence below the server tick.

This makes LiveRunnerSession own that lifecycle so callers do not hand-manage a background task.

Commits

• 3b60852 surface payment session and add run_session_payments (the interval payment loop).
• 37ee769 make the session own start/stop of that loop.
• 81ee7be handle the 482 skip-payment gate and anchor the interval to the server tick.

Changes

• LiveRunnerSession (still @dataclass(frozen=True)) gains start_payments(), aclose(), and async context manager support. _payment_task is stored via object.__setattr__, mirroring Lv2vJob.start_payment_sender / close. start_payments is idempotent, a no-op offchain, and warns instead of raising when called without a running loop.
• run_session_payments pays immediately before the first sleep (a cold start can leave a long gap after the reservation payment), treats HTTP 482 / SkipPaymentCycle as a healthy "balance current" gate (debug, keep looping) rather than a failure, and logs and retries other per-cycle failures instead of dying.
• reserve_session threads payment_interval through to the session (default 3s, margin under the 5s server tick).

Design notes vs lv2v and scope

• Uses the transport-agnostic interval driver rather than lv2v's per-output-segment sender. The general live-runner path has no single output stream to meter, can create multiple app-defined trickle channels, and must also cover websocket (no segments). The orchestrator meters by time anyway (LivePaymentProcessor on livePaymentInterval), so interval push aligns more directly with the server than per-segment does.
• Payment delivery is out of band (send_payment POSTs to {orch}/payment), so one interval loop funds any held-open transport.

Usage

# automatic lifecycle
async with await reserve_session(app=APP, signer_url=signer) as session:
    channels = await create_trickle_channels(session.session_id, [...])
    # publish/subscribe; payments start on enter, stop on exit

# or manual (lv2v parity)
session = await reserve_session(app=APP, signer_url=signer)
session.start_payments()
try:
    ...
finally:
    await session.aclose()

Tests

tests/test_live_runner_payments.py (9 cases): offchain no-op, immediate first payment, survives a transient payment error, treats a skip cycle as paid-up, idempotency, no-loop skip, aclose, async context manager. Full suite: 18 passed, ruff clean.

Scope and altitude (intentionally left for Josh)

This PR is faithful to the payment-loop mechanics in scope (LivepeerClient._payment_loop) and lv2v (Lv2vJob), and to the go-livepeer server model. It is intentionally scoped to the payment lifecycle and leaves the larger object-shape decisions open:

1. Object home. scope's LivepeerClient.connect() owns three connection-lifetime loops together: _payment_loop, _events_loop, _ping_loop. Here only payments live on the (thin) LiveRunnerSession. If the SDK should grow a scope-style LiveRunnerClient that owns payments, events, and heartbeat over one connection lifecycle, these methods move into it unchanged. Open question: is payment lifecycle on LiveRunnerSession the intended surface, or a stepping stone to a unified client?
2. Silent-drop detection. The orchestrator releases an underfunded session with no error on the payment path; the way to learn that is the events channel (scope's _events_loop). Not handled here. A client true to scope would watch events and fail fast instead of discovering the drop via dead media.
3. Surface the cadence. The interval is currently a client-side default (3s) chosen to sit under the server's 5s livePaymentInterval. The reservation challenge does not surface that value (only payment_params / orchestrator / manifest_id), so the client guesses. Surfacing livePaymentInterval in the challenge would let the client self-tune, which is an orchestrator-side change.
4. Async context manager. The async with sugar is an addition beyond scope and lv2v (both use explicit start/close); kept because reserve_session is async-native. Drop it if you prefer to match the existing explicit pattern.
5. Demand-driven streamed payments (bigger). A true "pay when the orchestrator requests" model (like the 402 path, but off the media hot path, via a payment-due signal over the control or events channel, since a mid-stream 402 on trickle segments adds jitter and is impossible over websocket) would let the interval disappear entirely for streamed sessions. That is a go-livepeer protocol change, not an SDK one.

Relates to ENG-130. Keeping this as a draft for Josh to take the object-shape pieces.

🤖 Generated with Claude Code

[linear-code]

ENG-130

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: b5866795-03c9-4df6-9ba6-206ecbcf4bc6

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch rs/live-runner-session-payments

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[j0sh]

Thanks for this @rickstaa . I spent some time reviewing this, comparing to how Scope does it and filling in some gaps (in the runner implementation, not your code).

From Claude:

1. Session liveness in the payment loop

The loop currently has no notion of whether the session it's funding still exists, and only stops if aclose is called. There's no other signal from the orchestrator unless the client makes an outbound app request (and 404s there aren't necessarily intercepted by the runner client). The generic /payment endpoint isn't tied to a concrete live-runner session, so it just credits a balance and returns 200 even if a session does not exist.

See livepeer/go-livepeer@e545b98 for a workaround on the go-livepeer-side: it adds a payment endpoint scoped to the session that returns a 404 if the session doesn't exist.

The loop should point to that endpoint and, on a 404, stop sending payments (and surface it as "session released").

To more easily construct the payment URL on the client, a base control URL was added in livepeer/go-livepeer@81f24cf ... take the control_url with a /payment path appended to it. The session stop endpoint can get the same control_url-based treatment, but that needn't happen in this PR.

2. send_payment doesn't disable cert verification like the rest of the SDK

LivePaymentSession.send_payment POSTs via a default aiohttp.ClientSession (normal TLS verification), while every async JSON helper forces TCPConnector(ssl=False) and the sync lv2v sender uses an unverified context. For consistency it might be best to match the existing behavior. The SDK already has the right primitive: _post_empty in live_runner.py does exactly this (POST empty body, raise on >= 400) with TCPConnector(ssl=False). Suggest hoisting _post_empty into http.py (next to post_json, and to avoid the live_runner ← remote_signer import cycle) and routing the payment POST through it. This also gives a single place to distinguish the 404/403 status codes needed.

We can have the SDK verify TLS by default if TOFU is disabled (which it should be for the live runner) but that's a larger change outside the scope of this PR.

3. Symmetrical stop_payments() (optional)

Soft suggestion: it might be nice to have a small stop_payments() that cancels only the payments loop without stopping the session, as a symmetrical complement to start_payment. This might be handy for tests and any "drain / hand off funding" flow. Session tear-down via close already stops payments so this is purely optional.