Conector Script

Descripción General

El conector Script ejecuta un script Lua contra cada carga entrante, devolviendo una nueva carga como una tabla Lua. El script se ejecuta en un sandbox endurecido que bloquea la E/S de archivos, el control de procesos, la carga dinámica de código y la introspección de depuración.

Tipo de Conector: MeddleScript

Configuración

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

La carga se enlaza a la tabla global payload. El script debe devolver o bien una tabla (se convierte en la nueva carga) o nil (la carga de entrada se reenvía sin cambios).

Parámetros de Configuración

• runtime (obligatorio): Sólo se admite lua
• script (obligatorio): Código fuente Lua, compilado una vez al inicio
• timeout: Timeout de ejecución por carga en milisegundos (0 u omitido deshabilita el timeout)

Sandbox

El sandbox de Lua permite un conjunto curado de bibliotecas estándar y deniega explícitamente el resto.

Bibliotecas permitidas:

• base (subconjunto — ver funciones denegadas abajo)
• table
• string
• math
• coroutine

Funciones de nivel superior denegadas (llamarlas lanza un error de acceso prohibido):

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

Bibliotecas denegadas (cualquier acceso — lectura o escritura — lanza un error de acceso prohibido):

• os
• io
• debug
• package
• channel

La metatabla del sandbox está bloqueada, por lo que los scripts de usuario no pueden inspeccionarla ni reemplazarla.

Mapeo de Tipos

Las conversiones Go-a-Lua y Lua-a-Go se aplican automáticamente:

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

La tabla Lua devuelta se convierte de nuevo en un DataPayload (map[string]any). Los números regresan como float64, independientemente de cómo se usaran en Lua.

Casos de Uso

1. Derivación de campos personalizada que va más allá de los tipos de expresión de Transform
2. Reescritura condicional de la carga con control de flujo arbitrario
3. Conversión de unidades, formato de cadenas o cadenas matemáticas simples
4. Enriquecimiento ligero sin arrancar un servicio separado

Ejemplo: Campos Derivados

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

Añade una lectura en Fahrenheit y una bandera booleana a cada carga.

Ejemplo: Descarte Condicional

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

Devolver nil causa que la carga de entrada se reenvíe sin cambios. Para realmente descartar una carga, devuelve una tabla vacía o usa un Filter descendente.

Ejemplo: Manipulación de Cadenas

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

Mejores Prácticas

• Establece un timeout distinto de cero para acotar el uso de CPU por carga (100–500 ms es típico)
• Prefiere Transform para extracción simple de campos; recurre a Script sólo cuando necesites lógica real
• Mantén los scripts cortos y puros — se ejecutan en cada carga
• Evita construir tablas intermedias grandes; el sandbox usa un tamaño de registro finito
• Prueba los símbolos prohibidos por adelantado — un error de Lua del sandbox aparece como un error de ejecución del script y la carga no se emite

Conectores Relacionados

• Transform - JSONPath, plantilla y expresiones estáticas
• Trigger - Lógica condicional basada en MXL
• Reshape - Renombrar y remapear campos