Take control over your live stream video by running it yourself. Streaming + chat out of the box.
HTML activitypubbroadcastingchatdecentralizedfederationfediversegolanghacktoberfesthlslivelivestreamowncastrtmpself-hostedstreaming-videovideo
feat(plugins): add ticker/timer/scheduling support to plugins
Gabe Kangasea43be423cc3
diff --git a/go.mod b/go.modindex 1c159a19b2..0fd833c6f2 100644--- a/go.mod+++ b/go.mod@@ -36,6 +36,7 @@ require (github.com/sirupsen/logrus v1.9.4github.com/stretchr/testify v1.11.1github.com/teris-io/shortid v0.0.0-20220617161101-71ec9f2aa569+ github.com/tetratelabs/wazero v1.9.0github.com/yuin/goldmark v1.7.13github.com/yuin/goldmark-emoji v1.0.6golang.org/x/crypto v0.52.0@@ -83,7 +84,6 @@ require (github.com/prometheus/procfs v0.20.1 // indirectgithub.com/sethvargo/go-retry v0.3.0 // indirectgithub.com/tetratelabs/wabin v0.0.0-20230304001439-f6f874872834 // indirect- github.com/tetratelabs/wazero v1.9.0 // indirectgithub.com/tklauser/go-sysconf v0.3.15 // indirectgithub.com/tklauser/numcpus v0.10.0 // indirectgithub.com/yusufpapurcu/wmi v1.2.4 // indirectdiff --git a/pluginhost/pluginhost.go b/pluginhost/pluginhost.goindex b5c05b718f..577ff3fe62 100644--- a/pluginhost/pluginhost.go+++ b/pluginhost/pluginhost.go@@ -94,6 +94,8 @@ type Host struct {// buttons at runtime (e.g. an admin page that lets the streamer// rename buttons without rebuilding the plugin).kv kv.Store+ // tickCancel stops the once-a-second tick goroutine when the host stops.+ tickCancel context.CancelFunc}// runtimeActionsConfigKey is the reserved key inside a plugin's own@@ -108,6 +110,9 @@ func (p *Host) Handler() http.Handler { return p.server }// Stop closes all loaded plugins.func (p *Host) Stop(ctx context.Context) {+ if p.tickCancel != nil {+ p.tickCancel()+ }p.manager.Stop(ctx)}@@ -327,6 +332,38 @@ func New(ctx context.Context, deps Deps) (*Host, error) {deps.Events.AddListener(newPluginEventListener(pluginDispatcher))deps.Events.AddFilter(newPluginChatFilter(pluginDispatcher))+ // 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's+ // timers on unload is wired through the manager's onUnload hook.+ timerHub := plugins.NewTimerHub(func(slug string) *plugins.Loaded {+ for _, l := range manager.Snapshot() {+ if l.Manifest.Slug == slug {+ return l+ }+ }+ return nil+ })+ env.Timer = timerHub+ manager.SetOnUnload(timerHub.CancelForPlugin)++ // Fire a once-a-second tick to plugins that subscribe (onTick), and which+ // also drives nothing else — host-scheduled timers run independently. The+ // goroutine is stopped when the host stops.+ tickCtx, tickCancel := context.WithCancel(context.Background())+ go func() {+ t := time.NewTicker(time.Second)+ defer t.Stop()+ for {+ select {+ case <-tickCtx.Done():+ return+ case <-t.C:+ pluginDispatcher.Notify(tickCtx, plugins.EventTick, plugins.TickEvent{Now: time.Now().UnixMilli()})+ }+ }+ }()+server := plugins.NewLiveServer(manager.Snapshot)server.SSE = sseHubserver.IsAuthenticated = env.IsAuthenticated@@ -340,6 +377,7 @@ func New(ctx context.Context, deps Deps) (*Host, error) {configRepository: deps.ConfigRepository,requireAdminAuth: deps.RequireAdminAuth,kv: env.KV,+ tickCancel: tickCancel,}, nil}diff --git a/services/plugins/events.go b/services/plugins/events.goindex 9d4837fa1c..c842b14528 100644--- a/services/plugins/events.go+++ b/services/plugins/events.go@@ -24,6 +24,16 @@ const (EventSSEConnect = "sse.connect"EventSSEDisconnect = "sse.disconnect"+ // EventTick fires to every plugin that subscribes (defines onTick) once a+ // second, for periodic work. Payload is a TickEvent.+ EventTick = "tick"++ // EventTimerFire is delivered to a plugin when one of its host-scheduled+ // timers elapses (see TimerHub). Payload is a TimerFireEvent. Internal:+ // the guest SDK maps the id back to the author's callback, so plugins+ // don't subscribe to or handle this directly.+ EventTimerFire = "timer.fire"+// Fediverse events. Engagement (follow/like/repost) carries only// actor + target metadata; mention/reply also carry the post content// so plugins can act on what was actually said.diff --git a/services/plugins/hostfns.go b/services/plugins/hostfns.goindex 0f1638115f..b6f6337abd 100644--- a/services/plugins/hostfns.go+++ b/services/plugins/hostfns.go@@ -231,6 +231,20 @@ type SSEConnectionEvent struct {User *HostUser `json:"user,omitempty"`}+// TickEvent is the payload for the once-a-second tick event, delivered to+// plugins that subscribe (define onTick). Now is the host's wall-clock time in+// unix milliseconds at the moment the tick fired.+type TickEvent struct {+ Now int64 `json:"now"`+}++// TimerFireEvent is the payload delivered (via the timer.fire event) when a+// host-scheduled timer elapses. ID is the timer's id, which the guest SDK maps+// back to the author's callback.+type TimerFireEvent struct {+ ID uint64 `json:"id"`+}+// HostEnv is everything host functions need to do their job. Function-pointer// fields are wired by the host (the production Owncast binary, the demo// binary, or the test runner); each host function reads them lazily at call@@ -291,6 +305,11 @@ type HostEnv struct {// the long-lived connections. Optional; nil → owncast.sse.send is a// no-op even if the plugin declared http.sse.SSE *SSEHub+ // Timer schedules host-driven callbacks (owncast.timer.*). Ambient: every+ // plugin gets the host functions, since a plugin can't setTimeout in the+ // sandbox. Optional; nil → owncast_timer_set reports success but never+ // fires (used by the test harness, which simulates fires via events).+ Timer *TimerHub}// BuildHostFunctions returns the list of extism host functions a single@@ -365,6 +384,12 @@ func BuildHostFunctions(env *HostEnv, manifest *Manifest) []extism.HostFunctionif granted[PermHttpSSE] {fns = append(fns, hostSSESend(env, manifest.Slug))}++ // Timers are ambient (no permission): a plugin can't setTimeout in the+ // sandbox, so scheduling is a baseline capability. The act of scheduling+ // is benign — whatever the callback does still needs its own permissions —+ // and TimerHub's per-plugin caps bound abuse.+ fns = append(fns, hostTimerSet(env, manifest.Slug), hostTimerClear(env, manifest.Slug))if granted[PermUIModify] {fns = append(fns,hostAddActions(env, manifest),@@ -442,6 +467,59 @@ func hostSSESend(env *HostEnv, pluginName string) extism.HostFunction {return fn}+// hostTimerSet backs owncast.timer.setTimeout / setInterval. The guest passes a+// guest-allocated id, the delay in milliseconds, and whether it repeats. The+// host arms a timer that, on fire, calls the plugin's on_event with a+// timer.fire event carrying the id. Returns 1 on success, 0 if the plugin is+// at its pending-timer cap. A nil Timer (test harness) reports success so the+// guest keeps its callback; fires are then simulated via events.+func hostTimerSet(env *HostEnv, pluginName string) extism.HostFunction {+ fn := extism.NewHostFunctionWithStack(+ "owncast_timer_set",+ func(ctx context.Context, p *extism.CurrentPlugin, stack []uint64) {+ id := stack[0]+ // Clamp the requested delay to a sane ceiling before narrowing to+ // int64 — bounds the duration math and keeps the conversion in range.+ rawDelayMs := stack[1]+ if rawDelayMs > maxTimerDelayMs {+ rawDelayMs = maxTimerDelayMs+ }+ delayMs := int64(rawDelayMs)+ repeat := stack[2] == 1+ if env.Timer == nil {+ stack[0] = 1+ return+ }+ if env.Timer.Schedule(pluginName, id, delayMs, repeat) {+ stack[0] = 1+ } else {+ stack[0] = 0+ }+ },+ []extism.ValueType{extism.ValueTypeI64, extism.ValueTypeI64, extism.ValueTypeI32},+ []extism.ValueType{extism.ValueTypeI32},+ )+ fn.SetNamespace("extism:host/user")+ return fn+}++// hostTimerClear backs owncast.timer.clear(id), cancelling a pending timer.+func hostTimerClear(env *HostEnv, pluginName string) extism.HostFunction {+ fn := extism.NewHostFunctionWithStack(+ "owncast_timer_clear",+ func(ctx context.Context, p *extism.CurrentPlugin, stack []uint64) {+ id := stack[0]+ if env.Timer != nil {+ env.Timer.Clear(pluginName, id)+ }+ },+ []extism.ValueType{extism.ValueTypeI64},+ []extism.ValueType{},+ )+ fn.SetNamespace("extism:host/user")+ return fn+}+func hostFediversePost(env *HostEnv, pluginName string) extism.HostFunction {fn := extism.NewHostFunctionWithStack("owncast_fediverse_post",diff --git a/services/plugins/manager.go b/services/plugins/manager.goindex af44d8bbbd..c102e09c4b 100644--- a/services/plugins/manager.go+++ b/services/plugins/manager.go@@ -19,6 +19,7 @@ import (extism "github.com/extism/go-sdk""github.com/gobwas/glob"log "github.com/sirupsen/logrus"+ "github.com/tetratelabs/wazero")// Loaded represents a successfully-loaded plugin. The sidecar manifest is the@@ -202,6 +203,23 @@ type Manager struct {scanInterval time.Durationcancel context.CancelFunc // stops the scan loopscanCh chan struct{} // pings to force a scan (testing / admin trigger)++ // onUnload, if set, is called with a plugin's slug just before its+ // instance is closed (disable, reload, disk-removal, or host stop), so+ // host subsystems can release per-plugin resources. Timers use it to+ // cancel a plugin's pending callbacks.+ onUnload func(slug string)+}++// SetOnUnload registers a callback invoked with a plugin's slug right before+// its instance is closed. Used to cancel per-plugin host resources (timers).+func (m *Manager) SetOnUnload(fn func(slug string)) { m.onUnload = fn }++// notifyUnload fires the onUnload hook for a plugin about to be closed.+func (m *Manager) notifyUnload(l *Loaded) {+ if m.onUnload != nil && l != nil && l.Manifest != nil {+ m.onUnload(l.Manifest.Slug)+ }}// DiscoveredEntry is the public view of a discovered plugin: what the@@ -365,6 +383,7 @@ func (m *Manager) Stop(ctx context.Context) {m.mu.Lock()defer m.mu.Unlock()for _, l := range m.loaded {+ m.notifyUnload(l)l.Close(ctx)}m.loaded = map[string]*Loaded{}@@ -579,6 +598,7 @@ func (m *Manager) Disable(ctx context.Context, name string) error {fmt.Fprintf(os.Stderr, "persist enabled set: %v\n", err)}if loaded != nil {+ m.notifyUnload(loaded)loaded.Close(ctx)}return nil@@ -606,6 +626,7 @@ func (m *Manager) Uninstall(ctx context.Context, name string) error {m.mu.Unlock()if loaded != nil {+ m.notifyUnload(loaded)loaded.Close(ctx)}@@ -665,6 +686,7 @@ func (m *Manager) Reload(ctx context.Context, name string) error {delete(m.loaded, name)m.mu.Unlock()if loaded != nil {+ m.notifyUnload(loaded)loaded.Close(ctx)}@@ -841,6 +863,7 @@ func (m *Manager) scan(ctx context.Context) error {delete(m.loaded, name)m.mu.Unlock()if loaded != nil {+ m.notifyUnload(loaded)loaded.Close(ctx)}}@@ -1106,7 +1129,13 @@ func loadFromBytes(ctx context.Context, env *HostEnv, manifestBytes, wasmBytes [break}}- p, err := extism.NewPlugin(ctx, extismManifest, extism.PluginConfig{EnableWasi: true}, hostFns)+ // Give the guest the real host wall clock and monotonic clock so Date and+ // performance.now() reflect actual time. Wazero's default ModuleConfig+ // uses a frozen deterministic clock (Date.now() would otherwise return a+ // fixed 2022 epoch). Nanosleep is deliberately NOT wired: a plugin must+ // not be able to block inside a call and burn its call-timeout budget.+ moduleConfig := wazero.NewModuleConfig().WithSysWalltime().WithSysNanotime()+ p, err := extism.NewPlugin(ctx, extismManifest, extism.PluginConfig{EnableWasi: true, ModuleConfig: moduleConfig}, hostFns)if err != nil {return nil, fmt.Errorf("instantiate wasm: %w", err)}diff --git a/services/plugins/plugin-contract.json b/services/plugins/plugin-contract.jsonindex ad020997e8..c42386a20d 100644--- a/services/plugins/plugin-contract.json+++ b/services/plugins/plugin-contract.json@@ -52,6 +52,8 @@"owncast_storage_upload","owncast_stream_broadcaster","owncast_stream_current",+ "owncast_timer_clear",+ "owncast_timer_set","owncast_user_get","owncast_user_set_enabled","owncast_users_list",@@ -140,6 +142,12 @@"videoBitrate": "int","width": "int"},+ "TickEvent": {+ "now": "int64"+ },+ "TimerFireEvent": {+ "id": "uint64"+ },"UploadResult": {"url": "string"},diff --git a/services/plugins/timer.go b/services/plugins/timer.gonew file mode 100644index 0000000000..81402a1728--- /dev/null+++ b/services/plugins/timer.go@@ -0,0 +1,185 @@+package plugins++import (+ "context"+ "encoding/json"+ "fmt"+ "os"+ "sync"+ "time"+)++// DefaultMaxTimersPerPlugin caps how many timers a single plugin may have+// pending at once. Like the SSE connection cap, it's per-plugin so one plugin+// can't exhaust host resources at the expense of others.+const DefaultMaxTimersPerPlugin = 64++// DefaultMinTimerDelay is the floor for a timer delay/interval. Requests below+// it are clamped up, so a plugin can't spin the host with a near-zero interval.+const DefaultMinTimerDelay = 100 * time.Millisecond++// maxTimerDelayMs is the ceiling for a requested delay, in milliseconds (24h).+// Longer is pointless for in-memory timers (they don't survive a restart) and+// guards the time.Duration math from overflow. Also keeps the host-function's+// uint64→int64 delay conversion provably in range.+const maxTimerDelayMs = 24 * 60 * 60 * 1000++// timerEntry is one scheduled timer for a plugin.+type timerEntry struct {+ slug string+ id uint64+ delay time.Duration+ repeat bool+ t *time.Timer+ cancelled bool+}++// TimerHub schedules host-driven callbacks for plugins. Plugins can't use+// setTimeout (no event loop in the wasm sandbox), so they ask the host to call+// them back: the guest registers a timer via owncast_timer_set, and when it+// fires the host calls the plugin's on_event export with a timer.fire event+// carrying the id. The guest SDK maps the id back to the author's callback.+//+// Timers are in-memory and per-plugin; they're cancelled when the plugin+// unloads and do not survive a host restart.+type TimerHub struct {+ mu sync.Mutex+ timers map[string]map[uint64]*timerEntry // slug -> id -> entry+ counts map[string]int+ maxPerPlugin int+ minDelay time.Duration++ // resolve maps a plugin slug to its currently-loaded instance so a firing+ // timer can call back into it. Returns nil if the plugin is gone, in which+ // case the fire is dropped. Injected by the host.+ resolve func(slug string) *Loaded+}++// NewTimerHub constructs an empty hub with the default caps. resolve maps a+// plugin slug to its loaded instance (nil-safe) for firing callbacks.+func NewTimerHub(resolve func(slug string) *Loaded) *TimerHub {+ return &TimerHub{+ timers: make(map[string]map[uint64]*timerEntry),+ counts: make(map[string]int),+ maxPerPlugin: DefaultMaxTimersPerPlugin,+ minDelay: DefaultMinTimerDelay,+ resolve: resolve,+ }+}++// Schedule arms a timer for (slug, id). delayMs is clamped up to the minimum+// delay. repeat=true reschedules after each fire (the next tick is armed only+// once the callback returns, so a slow callback can't cause pile-up).+// Re-using an id replaces the existing timer. Returns false if the plugin is+// already at its pending-timer cap.+func (h *TimerHub) Schedule(slug string, id uint64, delayMs int64, repeat bool) bool {+ delay := time.Duration(delayMs) * time.Millisecond+ if delay < h.minDelay {+ delay = h.minDelay+ }++ h.mu.Lock()+ defer h.mu.Unlock()++ if existing := h.timers[slug][id]; existing != nil {+ // Re-set: cancel the old entry first (doesn't count against the cap).+ existing.cancelled = true+ if existing.t != nil {+ existing.t.Stop()+ }+ delete(h.timers[slug], id)+ h.counts[slug]--+ } else if h.counts[slug] >= h.maxPerPlugin {+ return false+ }++ e := &timerEntry{slug: slug, id: id, delay: delay, repeat: repeat}+ if h.timers[slug] == nil {+ h.timers[slug] = make(map[uint64]*timerEntry)+ }+ h.timers[slug][id] = e+ h.counts[slug]+++ e.t = time.AfterFunc(delay, func() { h.fire(e) })+ return true+}++// Clear cancels a single timer. A no-op if the id isn't pending.+func (h *TimerHub) Clear(slug string, id uint64) {+ h.mu.Lock()+ defer h.mu.Unlock()+ e := h.timers[slug][id]+ if e == nil {+ return+ }+ e.cancelled = true+ if e.t != nil {+ e.t.Stop()+ }+ h.removeLocked(e)+}++// CancelForPlugin cancels every pending timer for a plugin. Called when the+// plugin is disabled, reloaded, removed, or the host stops.+func (h *TimerHub) CancelForPlugin(slug string) {+ h.mu.Lock()+ defer h.mu.Unlock()+ for _, e := range h.timers[slug] {+ e.cancelled = true+ if e.t != nil {+ e.t.Stop()+ }+ }+ delete(h.timers, slug)+ delete(h.counts, slug)+}++// removeLocked drops an entry and decrements the plugin's count. Caller holds mu.+func (h *TimerHub) removeLocked(e *timerEntry) {+ if m := h.timers[e.slug]; m != nil {+ if _, ok := m[e.id]; ok {+ delete(m, e.id)+ h.counts[e.slug]--+ if len(m) == 0 {+ delete(h.timers, e.slug)+ delete(h.counts, e.slug)+ }+ }+ }+}++// fire delivers one timer.fire to the plugin, then reschedules (repeat) or+// removes (one-shot) the entry. The callback runs outside the hub lock; the+// reschedule happens only after it returns, so a slow callback can't pile up.+func (h *TimerHub) fire(e *timerEntry) {+ h.mu.Lock()+ cancelled := e.cancelled+ h.mu.Unlock()+ if cancelled {+ return+ }++ if h.resolve != nil {+ if loaded := h.resolve(e.slug); loaded != nil {+ envelope, err := json.Marshal(Envelope{+ EventType: EventTimerFire,+ Payload: TimerFireEvent{ID: e.id},+ })+ if err == nil {+ if err := callOnEvent(context.Background(), loaded, envelope); err != nil {+ fmt.Fprintf(os.Stderr, "plugin %s: timer %d fire failed: %v\n", e.slug, e.id, err)+ }+ }+ }+ }++ h.mu.Lock()+ defer h.mu.Unlock()+ if e.cancelled {+ return+ }+ if e.repeat {+ e.t = time.AfterFunc(e.delay, func() { h.fire(e) })+ } else {+ h.removeLocked(e)+ }+}diff --git a/services/plugins/timer_test.go b/services/plugins/timer_test.gonew file mode 100644index 0000000000..7ba7df76a2--- /dev/null+++ b/services/plugins/timer_test.go@@ -0,0 +1,116 @@+package plugins++import (+ "sync/atomic"+ "testing"+ "time"+)++// fireCounter builds a TimerHub whose resolve records each fire and returns nil+// (so the callOnEvent path is skipped — we only assert that timers fire on+// schedule). minDelay is shrunk so timing tests run fast.+func fireCounter() (*TimerHub, *int64) {+ var n int64+ h := NewTimerHub(func(slug string) *Loaded {+ atomic.AddInt64(&n, 1)+ return nil+ })+ h.minDelay = time.Millisecond+ return h, &n+}++func TestTimerHubFiresOnceThenRemoves(t *testing.T) {+ h, n := fireCounter()+ if !h.Schedule("p", 1, 5, false) {+ t.Fatal("schedule should succeed")+ }+ time.Sleep(60 * time.Millisecond)+ if got := atomic.LoadInt64(n); got != 1 {+ t.Fatalf("expected exactly 1 fire, got %d", got)+ }+ h.mu.Lock()+ pending := h.counts["p"]+ h.mu.Unlock()+ if pending != 0 {+ t.Errorf("one-shot should be removed after firing, %d still pending", pending)+ }+}++func TestTimerHubRepeatsUntilCleared(t *testing.T) {+ h, n := fireCounter()+ h.Schedule("p", 1, 5, true)+ time.Sleep(70 * time.Millisecond)+ h.Clear("p", 1)+ time.Sleep(30 * time.Millisecond)+ after := atomic.LoadInt64(n)+ if after < 2 {+ t.Fatalf("interval should fire repeatedly, got %d", after)+ }+ time.Sleep(40 * time.Millisecond)+ if again := atomic.LoadInt64(n); again != after {+ t.Errorf("interval kept firing after Clear: %d -> %d", after, again)+ }+}++func TestTimerHubClearBeforeFire(t *testing.T) {+ var n int64+ h := NewTimerHub(func(string) *Loaded { atomic.AddInt64(&n, 1); return nil })+ // Keep the default 100ms floor so we can cancel before it fires.+ h.Schedule("p", 1, 100, false)+ h.Clear("p", 1)+ time.Sleep(160 * time.Millisecond)+ if atomic.LoadInt64(&n) != 0 {+ t.Error("a cleared timer must not fire")+ }+}++func TestTimerHubClampsDelayToMinimum(t *testing.T) {+ var n int64+ h := NewTimerHub(func(string) *Loaded { atomic.AddInt64(&n, 1); return nil })+ // Default minDelay is 100ms; a 0ms request must be clamped up, not fire now.+ h.Schedule("p", 1, 0, false)+ time.Sleep(40 * time.Millisecond)+ if atomic.LoadInt64(&n) != 0 {+ t.Error("0ms delay should be clamped up to the minimum, not fire immediately")+ }+ time.Sleep(120 * time.Millisecond)+ if atomic.LoadInt64(&n) != 1 {+ t.Error("timer should fire once after the clamped minimum delay")+ }+}++func TestTimerHubPerPluginCap(t *testing.T) {+ h := NewTimerHub(func(string) *Loaded { return nil })+ h.maxPerPlugin = 2+ // Long delays so nothing fires during the test.+ if !h.Schedule("p", 1, 100000, false) || !h.Schedule("p", 2, 100000, false) {+ t.Fatal("first two timers should fit under the cap")+ }+ if h.Schedule("p", 3, 100000, false) {+ t.Error("third timer should be rejected by the per-plugin cap")+ }+ // Re-using an existing id replaces it and doesn't count against the cap.+ if !h.Schedule("p", 1, 100000, false) {+ t.Error("re-setting an existing id should succeed")+ }+ // A different plugin is unaffected by p's cap.+ if !h.Schedule("q", 1, 100000, false) {+ t.Error("another plugin should not be limited by p's cap")+ }+ h.CancelForPlugin("p")+ h.CancelForPlugin("q")+}++func TestTimerHubCancelForPlugin(t *testing.T) {+ h, _ := fireCounter()+ h.Schedule("p", 1, 100000, true)+ h.Schedule("p", 2, 100000, true)+ h.CancelForPlugin("p")+ h.mu.Lock()+ remaining := len(h.timers["p"])+ count := h.counts["p"]+ h.mu.Unlock()+ if remaining != 0 || count != 0 {+ t.Errorf("CancelForPlugin should drop all timers, got %d entries / count %d", remaining, count)+ }+}