feat(events): document host-namespaced custom events - #15
Closed
gabek wants to merge 2 commits into
Closed
Conversation
There was a problem hiding this comment.
Pull request overview
This PR documents and propagates the semantics that plugin-emitted custom events are host-namespaced: plugins pass an event suffix to owncast.events.emit(...), and the host dispatches it to subscribers as <emitter-slug>.<suffix>. It updates SDK docs/types, scaffolder templates, author docs, and the relay/announcer examples to reflect the fully-qualified subscription name.
Changes:
- Clarify custom-event namespacing in the JS + Python SDK docs/types (emit takes a suffix; subscribers use
<slug>.<suffix>). - Update scaffolder templates and agent skills guidance to teach the fully-qualified subscription names.
- Update relay/announcer examples + scenario expectations to subscribe to
relay.announcement.broadcast(and associated docs).
Reviewed changes
Copilot reviewed 27 out of 28 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| sdks/python/owncast_plugin/template/src/plugin.py | Template example updated to show subscribing to a sender-qualified custom event name. |
| sdks/python/owncast_plugin/template/AGENTS.md | Author/agent guidance updated to describe suffix emission and slug-prefixed delivery. |
| sdks/python/owncast_plugin/template/.agents/skills/create-owncast-plugin-py/SKILL.md | Skill guidance updated for suffix emission + fully-qualified subscriptions. |
| sdks/python/owncast_plugin/init.py | Python SDK docstring updated for events.emit to explain host namespacing behavior. |
| sdks/js/index.js | JS SDK inline docs updated to explain host prefixing of emitted events. |
| sdks/js/index.d.ts | Type docs updated to specify fully-qualified event keys for on handlers and suffix emission semantics. |
| sdks/js/create-owncast-plugin/template/src/plugin.js | JS template example updated to show subscribing to a sender-qualified custom event name. |
| sdks/js/create-owncast-plugin/template/AGENTS.md | Scaffolder AGENTS guidance updated to describe suffix emission and slug-prefixed delivery. |
| sdks/js/create-owncast-plugin/template/.agents/skills/create-owncast-plugin-js/SKILL.md | Skill guidance updated for suffix emission + fully-qualified subscriptions. |
| README.md | Repo-level docs updated to describe the relay→announcer event behavior and note host pin implications. |
| examples/python/relay/README.md | Relay example docs updated to explain host delivery as relay.announcement.broadcast. |
| examples/python/relay/INSTRUCTIONS.md | Relay instructions updated to describe host-prefixed delivery to subscribers. |
| examples/python/README.md | Examples index updated to reference the prefixed event name used by announcer. |
| examples/python/announcer/src/plugin.py | Announcer updated to subscribe to relay.announcement.broadcast. |
| examples/python/announcer/README.md | Announcer docs updated to explain the host-added relay. prefix. |
| examples/python/announcer/plugin.manifest.json | Announcer description updated to reference the prefixed event name. |
| examples/python/announcer/INSTRUCTIONS.md | Announcer instructions updated for prefixed delivery semantics. |
| examples/python/announcer/tests/announcer.test.json | Scenario expectations updated to relay.announcement.broadcast. |
| examples/js/relay/README.md | Relay example docs updated to explain host delivery as relay.announcement.broadcast. |
| examples/js/relay/INSTRUCTIONS.md | Relay instructions updated to describe host-prefixed delivery to subscribers. |
| examples/js/README.md | Examples index updated to reference the prefixed event name used by announcer. |
| examples/js/announcer/src/plugin.js | Announcer updated to subscribe to relay.announcement.broadcast. |
| examples/js/announcer/README.md | Announcer docs updated to explain the host-added relay. prefix. |
| examples/js/announcer/plugin.manifest.json | Announcer description updated to reference the prefixed event name. |
| examples/js/announcer/INSTRUCTIONS.md | Announcer instructions updated for prefixed delivery semantics. |
| examples/js/announcer/tests/announcer.test.json | Scenario expectations updated to relay.announcement.broadcast. |
| docs/WIRE_PROTOCOL.md | Wire protocol updated to explicitly define emit input as a suffix and describe host-side slug resolution/prefixing. |
| docs/PLUGIN_AUTHOR_GUIDE.md | Author guide updated with suffix-emission and fully-qualified subscription examples. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| timestamp. The host delivers it as `relay.announcement.broadcast`, which other | ||
| plugins (see `../announcer`) can subscribe to. | ||
|
|
||
| **Demonstrates:** plugin → plugin communication via `owncast.events.emit(type, payload)`, the `events.emit` permission. Pairs with `announcer/` to show one full custom-event round trip. |
| timestamp. The host delivers it as `relay.announcement.broadcast`, which other | ||
| plugins (see `../announcer`) can subscribe to. | ||
|
|
||
| **Demonstrates:** plugin → plugin communication via `owncast.events.emit(type, payload)`, the `events.emit` permission. Pairs with `announcer/` to show one full custom-event round-trip. |
Comment on lines
+572
to
+574
| The host prefixes ``event_type`` with this plugin's slug, so | ||
| subscribers receive ``<your-slug>.<event_type>`` and no other plugin | ||
| can emit under your namespace. Requires the ``events.emit`` permission. |
Member
Author
|
Closing with owncast/owncast#5117. The SDK documentation will be recreated after issue #5093 and the runtime design are settled. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Documents the host-side custom event namespacing added in owncast/owncast#5117 (issue owncast/owncast#5093).
The host prefixes every emitted event name with the emitting plugin's slug, so
relayemittingannouncement.broadcastis delivered asrelay.announcement.broadcast. Authors pass a suffix toemitand subscribe using the sender's fully qualified name.Changes
owncast.events.emitdocs, JS types, and the Python docstring describe the suffix-in / prefixed-out contract, including the host dropping a composed name that would equal a built-in event.relay.announcement.broadcast.Merge order
Do not merge before a released Owncast build carries owncast/owncast#5117 and
host-runtime/go.modis bumped to it. Until then the pinned runtime dispatches the raw suffix, so:examples/{js,python}/relay/__tests__/relay.test.jsonstill expects the unprefixedannouncement.broadcast.Both are recorded under Open items in the README, along with the pin-bump checklist.
Verification
owncast-plugin buildplusowncast-plugin-testfor relay (2/2) and announcer (1/1).owncast-plugin-py testfor relay (2/2) and announcer (1/1).