Connettore Script

Panoramica

Il connettore Script esegue uno script Lua contro ogni payload in ingresso, restituendo un nuovo payload come tabella Lua. Lo script gira in un sandbox rinforzato che blocca I/O su file, controllo dei processi, caricamento dinamico di codice e introspezione di debug.

Tipo Connettore: MeddleScript

Configurazione

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

Il payload è collegato alla tabella globale payload. Lo script deve restituire una tabella (diventa il nuovo payload) o nil (il payload di input viene inoltrato invariato).

Parametri di Configurazione

• runtime (richiesto): Solo lua è supportato
• script (richiesto): Codice sorgente Lua, compilato una volta all’avvio
• timeout: Timeout di esecuzione per payload in millisecondi (0 o omesso disabilita il timeout)

Sandbox

Il sandbox Lua consente un insieme curato di librerie standard e nega esplicitamente le altre.

Librerie consentite:

• base (sottoinsieme — vedi funzioni negate sotto)
• table
• string
• math
• coroutine

Funzioni di primo livello negate (chiamandole solleva un errore di accesso vietato):

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

Librerie negate (qualsiasi accesso — lettura o scrittura — solleva un errore di accesso vietato):

• os
• io
• debug
• package
• channel

Il metatable del sandbox è bloccato, quindi gli script utente non possono ispezionarlo o sostituirlo.

Mappatura dei Tipi

Le conversioni Go-Lua e Lua-Go sono applicate automaticamente:

Tipo Go	Tipo Lua
string	string
float64 / float32 / int*	number
bool	boolean
map[string]any	table
nil	nil
(altro)	string (fallback tramite fmt.Sprintf)

La tabella Lua restituita viene riconvertita in un DataPayload (map[string]any). I numeri tornano come float64, indipendentemente da come sono stati usati in Lua.

Casi d’Uso

1. Derivazione personalizzata di campi che va oltre i tipi di espressione di Transform
2. Riscrittura condizionale del payload con flusso di controllo arbitrario
3. Conversione di unità, formattazione di stringhe o semplici catene matematiche
4. Arricchimento leggero senza avviare un servizio separato

Esempio: Campi Derivati

{
  "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"
  }
}

Aggiunge una lettura Fahrenheit e un flag booleano a ogni payload.

Esempio: Drop Condizionale

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

Restituire nil fa sì che il payload di input venga inoltrato invariato. Per scartare effettivamente un payload, restituisci una tabella vuota o usa un Filter a valle.

Esempio: Manipolazione di Stringhe

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

Migliori Pratiche

• Imposta un timeout non zero per limitare l’uso di CPU per payload (100–500 ms è tipico)
• Preferisci Transform per semplice estrazione di campi; usa Script solo quando hai bisogno di logica reale
• Mantieni gli script brevi e puri — vengono eseguiti su ogni payload
• Evita di costruire tabelle intermedie grandi; il sandbox utilizza una dimensione di registro finita
• Testa anticipatamente i simboli proibiti — un errore Lua dal sandbox emerge come errore di esecuzione dello script e il payload non viene emesso

Connettori Correlati

• Transform - JSONPath, template ed espressioni statiche
• Trigger - Logica condizionale basata su MXL
• Reshape - Rinomina e rimappa campi