Script-Konnektor

Übersicht

Der Script-Konnektor führt ein Lua-Skript gegen jede eingehende Payload aus und gibt eine neue Payload als Lua-Tabelle zurück. Das Skript läuft in einer gehärteten Sandbox, die Datei-I/O, Prozesskontrolle, dynamisches Code-Laden und Debug-Introspektion blockiert.

Konnektor-Typ: MeddleScript

Konfiguration

{
  "type": "MeddleScript",
  "config": {
    "runtime": "lua",
    "timeout": 100,
    "script": "payload.temperature_f = payload.temperature_c * 9 / 5 + 32\nreturn payload"
  }
}

Die Payload wird an die globale payload-Tabelle gebunden. Das Skript muss entweder eine Tabelle (wird zur neuen Payload) oder nil (die Eingabe-Payload wird unverändert weitergeleitet) zurückgeben.

Konfigurationsparameter

runtime (erforderlich): Nur lua wird unterstützt
script (erforderlich): Lua-Quellcode, einmal beim Start kompiliert
timeout: Pro-Payload-Ausführungstimeout in Millisekunden (0 oder weggelassen deaktiviert das Timeout)

Sandbox

Die Lua-Sandbox erlaubt einen kuratierten Satz von Standardbibliotheken und verweigert den Rest explizit.

Erlaubte Bibliotheken:

base (Teilmenge — siehe verweigerte Funktionen unten)
table
string
math
coroutine

Verweigerte Top-Level-Funktionen (das Aufrufen löst einen Forbidden-Access-Fehler aus):

dofile, loadfile, load, loadstring
require, module
getfenv, setfenv
collectgarbage, newproxy, _printregs
print

Verweigerte Bibliotheken (jeder Zugriff — lesen oder schreiben — löst einen Forbidden-Access-Fehler aus):

os
io
debug
package
channel

Die Sandbox-Metatable ist gesperrt, sodass Benutzerskripte sie nicht introspizieren oder ersetzen können.

Typenzuordnung

Go-zu-Lua- und Lua-zu-Go-Konvertierungen werden automatisch angewendet:

Go-Typ	Lua-Typ
`string`	`string`
`float64` / `float32` / `int*`	`number`
`bool`	`boolean`
`map[string]any`	`table`
`nil`	`nil`
(andere)	`string` (Fallback über `fmt.Sprintf`)

Die zurückgegebene Lua-Tabelle wird zurück in eine DataPayload (map[string]any) konvertiert. Zahlen kommen als float64 zurück, unabhängig davon, wie sie in Lua verwendet wurden.

Anwendungsfälle

Benutzerdefinierte Feldableitung, die über die Ausdruckstypen von Transform hinausgeht
Bedingtes Payload-Umschreiben mit beliebigem Kontrollfluss
Einheitenumrechnung, String-Formatierung oder einfache mathematische Ketten
Leichtgewichtige Anreicherung ohne einen separaten Dienst aufzubauen

Beispiel: Abgeleitete Felder

{
  "type": "MeddleScript",
  "config": {
    "runtime": "lua",
    "timeout": 200,
    "script": "payload.temperature_f = payload.temperature_c * 9 / 5 + 32\npayload.is_hot = payload.temperature_c > 30\nreturn payload"
  }
}

Fügt jeder Payload eine Fahrenheit-Messung und ein boolesches Flag hinzu.

Beispiel: Bedingtes Verwerfen

{
  "type": "MeddleScript",
  "config": {
    "runtime": "lua",
    "timeout": 100,
    "script": "if payload.status == \"test\" then\n  return nil\nend\nreturn payload"
  }
}

Das Zurückgeben von nil bewirkt, dass die Eingabe-Payload unverändert weitergeleitet wird. Um eine Payload tatsächlich zu verwerfen, geben Sie eine leere Tabelle zurück oder verwenden Sie einen nachgelagerten Filter.

Beispiel: String-Manipulation

{
  "type": "MeddleScript",
  "config": {
    "runtime": "lua",
    "script": "payload.normalized_id = string.upper(string.gsub(payload.raw_id, \"-\", \"_\"))\nreturn payload"
  }
}

Best Practices

Setzen Sie einen timeout ungleich Null, um die CPU-Nutzung pro Payload zu begrenzen (100–500 ms ist typisch)
Bevorzugen Sie Transform für einfache Feldextraktion; greifen Sie zu Script nur, wenn Sie echte Logik benötigen
Halten Sie Skripte kurz und rein — sie laufen bei jeder Payload
Vermeiden Sie den Aufbau großer Zwischentabellen; die Sandbox verwendet eine endliche Registry-Größe
Testen Sie verbotene Symbole im Voraus — ein Lua-Fehler aus der Sandbox erscheint als Skript-Ausführungsfehler und die Payload wird nicht ausgegeben