Skip to content

Take control over your live stream video by running it yourself. Streaming + chat out of the box.

Add logging host functions for plugins (#5099)

Gabe Kangas096693b4ceb2
diff --git a/THIRD-PARTY-LICENSES.txt b/THIRD-PARTY-LICENSES.txt
index bf37bb0435..d6819b579e 100644
--- a/THIRD-PARTY-LICENSES.txt
+++ b/THIRD-PARTY-LICENSES.txt
@@ -209,8 +209,8 @@ Go module: github.com/nareix/[email protected]
Source: https://pkg.go.dev/github.com/nareix/[email protected]
LICENSE TEXT NOT FOUND: No license is published with this version or in the upstream repository. Redistribution permission is unresolved.
-Go module: github.com/oapi-codegen/[email protected]
- Source: https://pkg.go.dev/github.com/oapi-codegen/[email protected]
+Go module: github.com/oapi-codegen/[email protected]
+ Source: https://pkg.go.dev/github.com/oapi-codegen/[email protected]
LICENSE: SHA256 50e6751797c50dedd75ef1b8a0d9e42f5f8472e9fbce91f34718e9f97b0c780a
Go module: github.com/oschwald/[email protected]
@@ -8523,7 +8523,7 @@ Used by: Go module: github.com/aws/aws-sdk-go-v2/service/internal/[email protected]
Used by: Go module: github.com/aws/aws-sdk-go-v2/service/[email protected] (LICENSE.txt)
Used by: Go module: github.com/aws/[email protected] (LICENSE.txt)
Used by: Go module: github.com/nakabonne/[email protected] (LICENSE)
-Used by: Go module: github.com/oapi-codegen/[email protected] (LICENSE)
+Used by: Go module: github.com/oapi-codegen/[email protected] (LICENSE)
Used by: Go module: github.com/prometheus/[email protected] (LICENSE)
Used by: Go module: github.com/prometheus/[email protected] (LICENSE)
Used by: Go module: github.com/prometheus/[email protected] (LICENSE)
diff --git a/pluginhost/logging_test.go b/pluginhost/logging_test.go
new file mode 100644
index 0000000000..8a6258a3e6
--- /dev/null
+++ b/pluginhost/logging_test.go
@@ -0,0 +1,55 @@
+package pluginhost
+
+import (
+ "strings"
+ "testing"
+
+ log "github.com/sirupsen/logrus"
+ logtest "github.com/sirupsen/logrus/hooks/test"
+
+ "github.com/owncast/owncast/services/plugins"
+)
+
+func TestPluginLoggingPreservesLevelAndIdentity(t *testing.T) {
+ originalLevel := log.GetLevel()
+ log.SetLevel(log.InfoLevel)
+ defer log.SetLevel(originalLevel)
+
+ hook := logtest.NewGlobal()
+ defer hook.Reset()
+ log.Info("unrelated log entry")
+
+ env := &plugins.HostEnv{}
+ wirePluginLoggingHostFn(env)
+
+ cases := []struct {
+ level plugins.PluginLogLevel
+ want log.Level
+ }{
+ {plugins.PluginLogInfo, log.InfoLevel},
+ {plugins.PluginLogWarning, log.WarnLevel},
+ {plugins.PluginLogError, log.ErrorLevel},
+ }
+ for _, tc := range cases {
+ env.Log("weather-alerts", tc.level, "forecast changed")
+ }
+
+ allEntries := hook.AllEntries()
+ entries := allEntries[:0]
+ for _, entry := range allEntries {
+ if strings.HasPrefix(entry.Message, "plugin weather-alerts:") {
+ entries = append(entries, entry)
+ }
+ }
+ if len(entries) != len(cases) {
+ t.Fatalf("log entries = %d, want %d", len(entries), len(cases))
+ }
+ for i, tc := range cases {
+ if entries[i].Level != tc.want {
+ t.Errorf("entry %d level = %s, want %s", i, entries[i].Level, tc.want)
+ }
+ if entries[i].Message != "plugin weather-alerts: forecast changed" {
+ t.Errorf("entry %d message = %q", i, entries[i].Message)
+ }
+ }
+}
diff --git a/pluginhost/pluginhost.go b/pluginhost/pluginhost.go
index 6c277c29bf..1ecb740146 100644
--- a/pluginhost/pluginhost.go
+++ b/pluginhost/pluginhost.go
@@ -1267,10 +1267,24 @@ func (s *configEnabledStore) Save(d plugins.StoreData) error {
return s.datastore.SetString(pluginsApprovedPermsConfigKey, string(encoded))
}
+func wirePluginLoggingHostFn(env *plugins.HostEnv) {
+ env.Log = func(pluginName string, level plugins.PluginLogLevel, message string) {
+ switch level {
+ case plugins.PluginLogWarning:
+ log.Warnf("plugin %s: %s", pluginName, message)
+ case plugins.PluginLogError:
+ log.Errorf("plugin %s: %s", pluginName, message)
+ default:
+ log.Infof("plugin %s: %s", pluginName, message)
+ }
+ }
+}
+
// wirePluginHostEnv connects each HostEnv host-function pointer to the
// corresponding Owncast service call. Closures read services lazily so they
// observe current config/state on every call.
func wirePluginHostEnv(env *plugins.HostEnv, deps Deps) {
+ wirePluginLoggingHostFn(env)
chatbots := newPluginChatbotProvisioner(deps.UserRepository, deps.Datastore)
wireChatSendHostFns(env, deps, chatbots)
wireChatReadHostFns(env, deps)
diff --git a/services/plugins/engines/javascript/engine.wasm b/services/plugins/engines/javascript/engine.wasm
index d98aedb56e..6b7f85cec6 100644
Binary files a/services/plugins/engines/javascript/engine.wasm and b/services/plugins/engines/javascript/engine.wasm differ
diff --git a/services/plugins/engines/python/engine.wasm b/services/plugins/engines/python/engine.wasm
index 514792d2da..7069410df9 100644
Binary files a/services/plugins/engines/python/engine.wasm and b/services/plugins/engines/python/engine.wasm differ
diff --git a/services/plugins/hostfns.go b/services/plugins/hostfns.go
index ed75f227b3..4495413c31 100644
--- a/services/plugins/hostfns.go
+++ b/services/plugins/hostfns.go
@@ -8,6 +8,7 @@ import (
"net/http"
"os"
"strings"
+ "unicode"
extism "github.com/extism/go-sdk"
"github.com/owncast/owncast/services/plugins/kv"
@@ -340,12 +341,29 @@ type TimerFireEvent struct {
ID uint64 `json:"id"`
}
+// MaxPluginLogMessageBytes caps one plugin-authored log entry. Logging is
+// ambient, so every plugin gets it without a permission grant.
+const MaxPluginLogMessageBytes = 4 << 10
+
+const pluginLogTruncationSuffix = " [truncated]"
+
+// PluginLogLevel is the fixed set of severities a plugin can send to the
+// Owncast log.
+type PluginLogLevel uint8
+
+const (
+ PluginLogInfo PluginLogLevel = iota
+ PluginLogWarning
+ PluginLogError
+)
+
// 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
// time so that fields wired post-load (Emit) work correctly.
type HostEnv struct {
KV kv.Store
+ Log func(pluginName string, level PluginLogLevel, message string)
OnChat func(ChatSendRequest)
Emit func(ctx context.Context, eventType string, payload any)
StreamCurrent func() StreamInfo
@@ -451,9 +469,10 @@ type HostEnv struct {
func BuildHostFunctions(env *HostEnv) []extism.HostFunction {
// Capacity hint for the full host-function set built below; an off-by-a-few
// estimate just trades one reallocation, so it needn't track exactly.
- fns := make([]extism.HostFunction, 0, 48)
+ fns := make([]extism.HostFunction, 0, 49)
fns = append(fns, hostKVGet(), hostKVSet())
+ fns = append(fns, loggingHostFunctions(env)...)
// Chat send fns resolve both slug and chat display name at call time:
// slug routes to the right bot user, display name is what chat viewers
// see.
@@ -533,6 +552,56 @@ func storageHostFunctions(env *HostEnv) []extism.HostFunction {
}
}
+// loggingHostFunctions returns the ambient logging functions. Separate
+// functions keep invalid severity values out of the wire protocol.
+func loggingHostFunctions(env *HostEnv) []extism.HostFunction {
+ return []extism.HostFunction{
+ hostLog(env, "owncast_log_info", PluginLogInfo),
+ hostLog(env, "owncast_log_warning", PluginLogWarning),
+ hostLog(env, "owncast_log_error", PluginLogError),
+ }
+}
+
+func hostLog(env *HostEnv, fnName string, level PluginLogLevel) extism.HostFunction {
+ fn := extism.NewHostFunctionWithStack(
+ fnName,
+ func(ctx context.Context, p *extism.CurrentPlugin, stack []uint64) {
+ id, ok := resolveCaller(ctx, fnName, "")
+ if !ok {
+ return
+ }
+ message, err := p.ReadString(stack[0])
+ if err != nil || env.Log == nil {
+ return
+ }
+ env.Log(id.slug, level, sanitizePluginLogMessage(message))
+ },
+ []extism.ValueType{extism.ValueTypePTR},
+ []extism.ValueType{},
+ )
+ fn.SetNamespace("extism:host/user")
+ return fn
+}
+
+func sanitizePluginLogMessage(message string) string {
+ truncated := len(message) > MaxPluginLogMessageBytes
+ if truncated {
+ bodyBytes := MaxPluginLogMessageBytes - len(pluginLogTruncationSuffix)
+ message = message[:bodyBytes]
+ }
+ message = strings.ToValidUTF8(message, "")
+ message = strings.Map(func(r rune) rune {
+ if unicode.IsControl(r) {
+ return ' '
+ }
+ return r
+ }, message)
+ if truncated {
+ return message + pluginLogTruncationSuffix
+ }
+ return message
+}
+
// readSQLRequest pulls the plugin's JSON SQL request out of guest memory and
// hands it to the shared validator.
func readSQLRequest(p *extism.CurrentPlugin, ptr uint64) (SQLRequest, error) {
diff --git a/services/plugins/plugin-contract.json b/services/plugins/plugin-contract.json
index 979b5c707a..95337d696c 100644
--- a/services/plugins/plugin-contract.json
+++ b/services/plugins/plugin-contract.json
@@ -45,6 +45,9 @@
"owncast_kick_client",
"owncast_kv_get",
"owncast_kv_set",
+ "owncast_log_error",
+ "owncast_log_info",
+ "owncast_log_warning",
"owncast_notify_browser_push",
"owncast_notify_discord",
"owncast_notify_fediverse",
diff --git a/services/plugins/safeguards_test.go b/services/plugins/safeguards_test.go
index d7ee87ecff..787ce21054 100644
--- a/services/plugins/safeguards_test.go
+++ b/services/plugins/safeguards_test.go
@@ -42,6 +42,25 @@ func loadStress(t *testing.T) (*Loaded, func()) {
return loaded, func() { loaded.Close(ctx) }
}
+func TestSanitizePluginLogMessage(t *testing.T) {
+ t.Run("normalizes control and invalid bytes", func(t *testing.T) {
+ got := sanitizePluginLogMessage("line\n\xfftwo")
+ if got != "line two" {
+ t.Fatalf("sanitized message = %q, want %q", got, "line two")
+ }
+ })
+
+ t.Run("bounds work before normalization", func(t *testing.T) {
+ got := sanitizePluginLogMessage(strings.Repeat("\n", MaxPluginLogMessageBytes*1024))
+ if len(got) != MaxPluginLogMessageBytes {
+ t.Fatalf("sanitized message bytes = %d, want %d", len(got), MaxPluginLogMessageBytes)
+ }
+ if !strings.HasSuffix(got, pluginLogTruncationSuffix) {
+ t.Fatalf("sanitized message does not end with %q", pluginLogTruncationSuffix)
+ }
+ })
+}
+
// --- Filter safeguards ---
func TestSafeguard_FilterHugeOutputRejected(t *testing.T) {
diff --git a/services/plugins/shared_engine_test.go b/services/plugins/shared_engine_test.go
index aaeb720a4d..8a5e6de719 100644
--- a/services/plugins/shared_engine_test.go
+++ b/services/plugins/shared_engine_test.go
@@ -4,6 +4,7 @@ import (
"context"
"encoding/json"
"fmt"
+ "reflect"
"runtime"
"strings"
"sync"
@@ -121,6 +122,59 @@ module.exports = definePlugin({
}
}
+func TestSharedEngineLoggingIsAmbientAndPreservesIdentity(t *testing.T) {
+ ctx := context.Background()
+ compiledEngines.resetForTest(ctx)
+ t.Cleanup(func() { compiledEngines.resetForTest(ctx) })
+
+ type logEntry struct {
+ plugin string
+ level PluginLogLevel
+ message string
+ }
+ var entries []logEntry
+ env := &HostEnv{
+ Log: func(plugin string, level PluginLogLevel, message string) {
+ entries = append(entries, logEntry{plugin: plugin, level: level, message: message})
+ },
+ }
+
+ js := loadShared(t, ctx, env, RuntimeJavaScript, "js-logger", `
+const { definePlugin, owncast } = require("@owncast/plugin-sdk");
+owncast.log.info("ready");
+owncast.log.warning("needs attention");
+owncast.log.error("failed");
+owncast.log.info("x".repeat(5000));
+owncast.log.info("line one\nline two\u001b[31m");
+module.exports = definePlugin({});`, nil)
+ defer js.Close(ctx)
+
+ py := loadShared(t, ctx, env, RuntimePython, "py-logger", `
+owncast.log.info("ready")
+owncast.log.warning("needs attention")
+owncast.log.error("failed")
+`, nil)
+ defer py.Close(ctx)
+
+ want := []logEntry{
+ {plugin: "js-logger", level: PluginLogInfo, message: "ready"},
+ {plugin: "js-logger", level: PluginLogWarning, message: "needs attention"},
+ {plugin: "js-logger", level: PluginLogError, message: "failed"},
+ {
+ plugin: "js-logger",
+ level: PluginLogInfo,
+ message: strings.Repeat("x", MaxPluginLogMessageBytes-len(pluginLogTruncationSuffix)) + pluginLogTruncationSuffix,
+ },
+ {plugin: "js-logger", level: PluginLogInfo, message: "line one line two [31m"},
+ {plugin: "py-logger", level: PluginLogInfo, message: "ready"},
+ {plugin: "py-logger", level: PluginLogWarning, message: "needs attention"},
+ {plugin: "py-logger", level: PluginLogError, message: "failed"},
+ }
+ if !reflect.DeepEqual(entries, want) {
+ t.Fatalf("log entries = %+v, want %+v", entries, want)
+ }
+}
+
// TestDispatchCloseRace exercises the C1 lifecycle race: tearing a plugin down
// (Loaded.Close) while events are concurrently dispatched to it must neither
// data-race on the instance pointer nor nil-deref. Run under -race to catch the