Let plugins return binary HTTP responses

[gabek]

This adds byte response bodies to the JavaScript and Python SDKs for owncast/owncast#5189.

• Accept Uint8Array in JavaScript and bytes or bytearray in Python.
• Encode bytes on the JSON wire and add exact binary assertions to HTTP scenarios.
• Cover both SDKs with invalid UTF-8 response scenarios.
• Document the Owncast v0.3.1 requirement because older hosts do not support binary response bodies.

I ran go test ./... in host-runtime, then ran the JavaScript and Python binary scenarios through the rebuilt host test binary. Both passed.

[Copilot]

🟡 Changes recommended

The Python SDK can currently forward dict responses containing both body and bodyBase64, violating the documented wire-protocol mutual-exclusion rule.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

This PR extends the Owncast plugin SDKs and test harness to support binary HTTP response bodies by encoding raw bytes on the JSON wire via a new bodyBase64 field (per owncast/owncast#5188), and documents the Owncast v0.3.1+ host requirement for this behavior.

Changes:

• JavaScript SDK: allow OutgoingHttpResponse.body to be Uint8Array and emit bodyBase64 on the wire when present.
• Python SDK: accept bytes/bytearray HTTP bodies and encode them to bodyBase64.
• Host test runner + example scenarios: add bodyBase64 assertions for exact binary matching, including invalid UTF-8 round-trips, plus protocol/author docs updates.

File summaries

File	Description
sdks/python/README.md	Documents Python HTTP handlers returning bytes (needs mention of bytearray too).
sdks/python/owncast_plugin/init.py	Encodes bytes/bytearray HTTP bodies into bodyBase64 for the wire.
sdks/js/index.js	Adds base64 encoding for Uint8Array HTTP bodies and emits bodyBase64.
sdks/js/index.d.ts	Updates TS types/docs: body?: string | Uint8Array.
host-runtime/plugin/testing/scenario.go	Adds bodyBase64 to HTTP expectation schema.
host-runtime/plugin/testing/runner.go	Adds exact binary assertions for HTTP responses via bodyBase64.
examples/python/all-permissions-test/src/plugin.py	Returns raw bytes from HTTP handler to exercise binary response path.
examples/python/all-permissions-test/tests/binary.test.json	Updates scenario to assert binary HTTP response with bodyBase64.
examples/js/all-permissions-test/src/plugin.js	Adds an endpoint that returns binary bytes (Uint8Array) with octet-stream content type.
examples/js/all-permissions-test/tests/binary.test.json	New JS scenario asserting raw binary HTTP response via bodyBase64.
docs/WIRE_PROTOCOL.md	Defines bodyBase64 and the mutual-exclusion rule vs body; documents v0.3.1+ requirement.
docs/PLUGIN_AUTHOR_GUIDE.md	Documents returning bytes from JS/Python and adds bodyBase64 to HTTP test expectations; updates envelope cap to 16 MiB.

Review details

• Files reviewed: 11/12 changed files
• Comments generated: 3
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[gabek]

@copilot review

[Copilot]

@copilot review

Addressed a follow-up docs mismatch in f23b416 so the guide now makes the JavaScript onHttpRequest return shape explicit and leaves direct string/bytes returns documented as Python-only.