Take control over your live stream video by running it yourself. Streaming + chat out of the box.
HTML activitypubbroadcastingchatdecentralizedfederationfediversegolanghacktoberfesthlslivelivestreamowncastrtmpself-hostedstreaming-videovideo
feat(plugins): add support for commands w/ !help overview
Gabe Kangas5569ad3fa887
diff --git a/pluginhost/pluginevents.go b/pluginhost/pluginevents.goindex 4ba7b335de..0a675117ad 100644--- a/pluginhost/pluginevents.go+++ b/pluginhost/pluginevents.go@@ -125,6 +125,49 @@ func filteredBody(final any, fallback string) string {return fallback}+// moderatorScope is the user scope that grants moderator privileges; mod-only+// commands are hidden from non-moderators in the help listing.+const moderatorScope = "MODERATOR"++// newHelpResponder returns a dispatcher.Listener that answers the unified+// `!help` chat command. The host owns !help (no plugin implements it): it+// aggregates command metadata across all loaded plugins — which no single+// sandboxed plugin could see — and posts the list as a system message via+// `post`. snapshot yields the current loaded plugins; post sends a system+// chat message.+func newHelpResponder(snapshot func() []*plugins.Loaded, post func(text string)) dispatcher.Listener {+ return func(ctx context.Context, e dispatcher.Event) {+ webhookEvent, ok := e.Payload.(webhooks.WebhookEvent)+ if !ok || webhookEvent.Type != models.MessageSent {+ return+ }+ data, ok := webhookEvent.EventData.(*webhooks.WebhookChatMessage)+ if !ok || data == nil {+ return+ }+ // Ignore bot/system posts (e.g. the help message itself, or a plugin's+ // chat.send) so !help can't be triggered by non-human messages.+ if data.User != nil && data.User.IsBot {+ return+ }+ if !plugins.IsHelpCommand(data.RawBody) {+ return+ }+ isMod := false+ if data.User != nil {+ for _, s := range data.User.Scopes {+ if s == moderatorScope {+ isMod = true+ break+ }+ }+ }+ if text := plugins.BuildHelpMessage(snapshot(), isMod); text != "" {+ post(text)+ }+ }+}+// newPluginEventListener returns a dispatcher.Listener that translates each// Owncast event (carried as a webhooks.WebhookEvent) into the plugin SDK's// payload shape and dispatches it to subscribed plugins. Dispatch runs on itsdiff --git a/pluginhost/pluginhost.go b/pluginhost/pluginhost.goindex ccdeb8d60b..05a0b5302e 100644--- a/pluginhost/pluginhost.go+++ b/pluginhost/pluginhost.go@@ -396,6 +396,15 @@ func New(ctx context.Context, deps Deps) (*Host, error) {deps.Events.AddListener(newPluginEventListener(pluginDispatcher))deps.Events.AddFilter(newPluginChatFilter(pluginDispatcher))+ // Host-owned `!help`: list every plugin's chat commands (no single plugin+ // can see across the sandbox, so the host aggregates and answers). Posts a+ // system message — works even when no plugin holds chat.send.+ deps.Events.AddListener(newHelpResponder(manager.Snapshot, func(text string) {+ if err := deps.Chat.SendSystemMessage(text, false); err != nil {+ log.Errorln("plugin !help:", err)+ }+ }))+// Host-driven timers: plugins can't setTimeout in the sandbox, so// owncast.timer.* asks the host to schedule callbacks. The hub resolves a// plugin slug to its live instance to call back; cancelling a plugin'sdiff --git a/services/plugins/engines/javascript/engine.wasm b/services/plugins/engines/javascript/engine.wasmindex 087697ad94..0af7d7a11f 100644Binary files a/services/plugins/engines/javascript/engine.wasm and b/services/plugins/engines/javascript/engine.wasm differdiff --git a/services/plugins/engines/python/engine.wasm b/services/plugins/engines/python/engine.wasmindex cbb108fdf9..66b2e9d38c 100644Binary files a/services/plugins/engines/python/engine.wasm and b/services/plugins/engines/python/engine.wasm differdiff --git a/services/plugins/manager.go b/services/plugins/manager.goindex 583e250b87..893d8a48bc 100644--- a/services/plugins/manager.go+++ b/services/plugins/manager.go@@ -1277,6 +1277,10 @@ func loadFromBytes(ctx context.Context, env *HostEnv, manifestBytes, artifactBytreturn nil, err}manifest.Subscriptions = runtime.Subscriptions+ // Command metadata is derived by the SDK and reported via register() (like+ // subscriptions); the host aggregates it for !help. Informational only, so+ // it isn't part of AgreesWith's security checks.+ manifest.Commands = runtime.Commandsvar adminGlobs []glob.Globvar adminPaths []stringdiff --git a/services/plugins/manifest.go b/services/plugins/manifest.goindex 3cdd3ab84b..c863af73a1 100644--- a/services/plugins/manifest.go+++ b/services/plugins/manifest.go@@ -27,6 +27,18 @@ type Subscriptions struct {Filter []Subscription `json:"filter,omitempty"`}+// CommandInfo is one chat command a plugin advertises for the unified !help.+// Reported by the SDK in register() output; purely informational (the plugin's+// own router does the actual matching).+type CommandInfo struct {+ Name string `json:"name"`+ Prefix string `json:"prefix,omitempty"`+ Description string `json:"description,omitempty"`+ Usage string `json:"usage,omitempty"`+ Aliases []string `json:"aliases,omitempty"`+ ModOnly bool `json:"modOnly,omitempty"`+}+type ConfigField struct {Type string `json:"type"`Default any `json:"default,omitempty"`@@ -61,16 +73,21 @@ type Manifest struct {// hyphenated, matches slugPattern. Authors can pin it via the// JSON `slug` field; if empty, it's auto-derived from// DisplayName at parse time by slugify.- Slug string `json:"slug,omitempty"`- Version string `json:"version"`- Description string `json:"description,omitempty"`- Bot BotConfig `json:"bot,omitempty"`- Subscriptions Subscriptions `json:"subscriptions"`- Permissions []string `json:"permissions,omitempty"`- Config map[string]ConfigField `json:"config,omitempty"`- Admin AdminConfig `json:"admin,omitempty"`- Actions []ActionButton `json:"actions,omitempty"`- Network NetworkConfig `json:"network,omitempty"`+ Slug string `json:"slug,omitempty"`+ Version string `json:"version"`+ Description string `json:"description,omitempty"`+ Bot BotConfig `json:"bot,omitempty"`+ Subscriptions Subscriptions `json:"subscriptions"`+ // Commands is the plugin's chat-command metadata, derived by the SDK from+ // its defineCommands/plugin.commands table and reported via register() (not+ // authored in the sidecar manifest). The host aggregates these across+ // plugins to answer a unified !help.+ Commands []CommandInfo `json:"commands,omitempty"`+ Permissions []string `json:"permissions,omitempty"`+ Config map[string]ConfigField `json:"config,omitempty"`+ Admin AdminConfig `json:"admin,omitempty"`+ Actions []ActionButton `json:"actions,omitempty"`+ Network NetworkConfig `json:"network,omitempty"`// Styles is a list of CSS files the plugin contributes to the// viewer page (the public streaming page). Each entry is a path// relative to the plugin's own URL namespace: bare paths likediff --git a/services/plugins/shared_engine_test.go b/services/plugins/shared_engine_test.goindex c289fc8ae8..1547596789 100644--- a/services/plugins/shared_engine_test.go+++ b/services/plugins/shared_engine_test.go@@ -229,6 +229,55 @@ module.exports = definePlugin({}}+// TestSharedEngineReportsCommands verifies command metadata declared in a+// plugin's command table flows SDK → engine register() → host manifest, so the+// host can build !help.+func TestSharedEngineReportsCommands(t *testing.T) {+ ctx := context.Background()+ compiledEngines.resetForTest(ctx)+ t.Cleanup(func() { compiledEngines.resetForTest(ctx) })++ env, _, _ := captureEnv()++ jsScript := `+const { definePlugin } = require("@owncast/plugin-sdk");+module.exports = definePlugin({+ commands: { uptime: { description: "Stream uptime", run: () => {} } },+});`+ js := loadShared(t, ctx, env, RuntimeJavaScript, "js-cmds", jsScript, []string{})+ defer js.Close(ctx)+ assertHasCommand(t, js, "uptime", "Stream uptime")++ pyScript := `+plugin.commands({"uptime": {"description": "Stream uptime", "run": lambda ctx: None}})+`+ py := loadShared(t, ctx, env, RuntimePython, "py-cmds", pyScript, []string{})+ defer py.Close(ctx)+ assertHasCommand(t, py, "uptime", "Stream uptime")++ // And the host can render a unified help listing from it.+ help := BuildHelpMessage([]*Loaded{js, py}, false)+ if !strings.Contains(help, "`!uptime`") || !strings.Contains(help, "Stream uptime") {+ t.Errorf("help should list the reported command:\n%s", help)+ }+}++func assertHasCommand(t *testing.T, l *Loaded, name, desc string) {+ t.Helper()+ for _, c := range l.Manifest.Commands {+ if c.Name == name {+ if c.Description != desc {+ t.Errorf("%s: command %q description = %q, want %q", l.Manifest.Slug, name, c.Description, desc)+ }+ if c.Prefix != "!" {+ t.Errorf("%s: command %q prefix = %q, want \"!\"", l.Manifest.Slug, name, c.Prefix)+ }+ return+ }+ }+ t.Errorf("%s: register() did not report command %q; got %+v", l.Manifest.Slug, name, l.Manifest.Commands)+}+func TestSharedEnginePythonRegister(t *testing.T) {ctx := context.Background()compiledEngines.resetForTest(ctx)