fix: fail fast on signer HTTP 483 insufficient balance

[eliteprox]

Summary

• Map signer HTTP 483 to a new InsufficientBalance error
• Fail fast (no orchestrator fallback) in LV2V and BYOC/training payment paths when balance/allowance is exhausted

Test plan

• pytest tests/test_insufficient_balance.py -q
• Confirm a real signer 483 during LV2V start raises InsufficientBalance immediately (no second orch attempt)

Response from signer when -remoteSignerWebhookUrl returns 402 status code

ERROR: Signer returned HTTP 483 (insufficient balance) (url=https://pymthouse-production.up.railway.app/generate-live-payment); body='Starter allowance exhausted'

[coderabbitai]

📝 Walkthrough

Walkthrough

The gateway adds InsufficientBalance handling for signer HTTP 483 responses, stops orchestrator fallback for this error, introduces package logging configuration, expands public exports, and updates the frame-writing example and tests.

Changes

Gateway behavior and runtime setup

Layer / File(s)	Summary
Insufficient balance contract and HTTP mapping src/livepeer_gateway/errors.py, src/livepeer_gateway/orchestrator.py, tests/test_insufficient_balance.py	HTTP 483 responses now raise InsufficientBalance while preserving the response message.
Immediate payment failure propagation src/livepeer_gateway/lv2v.py, src/livepeer_gateway/byoc.py, tests/test_insufficient_balance.py	LV2V and BYOC payment flows re-raise InsufficientBalance without recording rejection or trying another orchestrator; LV2V fallback behavior is tested.
Package logging configuration and exports src/livepeer_gateway/logging_config.py, src/livepeer_gateway/__init__.py, examples/write_frames.py	Logging level resolution, package logging setup, expanded exports, import-time log-level application, and example startup configuration are added.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Suggested reviewers: j0sh

Sequence Diagram(s)

sequenceDiagram
  participant Signer
  participant request_json
  participant payment_session
  participant start_lv2v
  participant OrchestratorCandidates
  Signer-->>request_json: HTTP 483 response
  request_json-->>payment_session: InsufficientBalance
  payment_session-->>start_lv2v: propagate exception
  start_lv2v-->>OrchestratorCandidates: stop fallback

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: mapping signer HTTP 483 to insufficient balance and failing fast.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/livepeer_gateway/byoc.py`:
- Around line 402-403: Update _create_byoc_payment to detect HTTP 483 responses
and raise InsufficientBalance while preserving the response details; continue
wrapping other HTTPError cases as LivepeerGatewayError. This enables the
InsufficientBalance handlers at src/livepeer_gateway/byoc.py lines 402-403 and
688-689 to execute; both sites require no direct change.

In `@src/livepeer_gateway/logging_config.py`:
- Around line 12-31: Update _resolve_level so an omitted level and unset
LOG_LEVEL resolve to logging.NOTSET, allowing the package logger to inherit the
parent/root logger level instead of forcing INFO on import. Preserve explicit
argument and environment values, and keep configure_logging’s explicit setup
default at INFO by applying that default before calling _resolve_level when no
level is provided.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 996bc0a7-917e-4f18-b969-35cfdef75a07

📥 Commits

Reviewing files that changed from the base of the PR and between cc31b56 and ba5cb4c.

📒 Files selected for processing (8)

• examples/write_frames.py
• src/livepeer_gateway/__init__.py
• src/livepeer_gateway/byoc.py
• src/livepeer_gateway/errors.py
• src/livepeer_gateway/logging_config.py
• src/livepeer_gateway/lv2v.py
• src/livepeer_gateway/orchestrator.py
• tests/test_insufficient_balance.py

[eliteprox]

@j0sh Do you think it's alright to reuse HTTP 483 here for the balance gate? It allows identity-webhook to signal payment required. The clearinghouse returns a 402 status code internally, but only the webhook sees it and it seems that go-livepeer expects specific status codes back