Scriptコネクタ

概要

Scriptコネクタは、すべての受信ペイロードに対してLuaスクリプトを実行し、新しいペイロードをLuaテーブルとして返します。スクリプトは、ファイルI/O、プロセス制御、動的コード読み込み、デバッグ内省をブロックする強化されたサンドボックスで実行されます。

コネクタタイプ: MeddleScript

設定

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

ペイロードはグローバルなpayloadテーブルにバインドされます。スクリプトはテーブル（新しいペイロードになる）またはnil（入力ペイロードが変更されずに転送される）のいずれかを返す必要があります。

設定パラメータ

runtime（必須）：luaのみサポート
script（必須）：Luaソースコード。起動時に一度コンパイルされる
timeout: ミリ秒単位のペイロードごとの実行タイムアウト（0または省略でタイムアウト無効）

サンドボックス

Luaサンドボックスは、厳選された標準ライブラリのセットを許可し、その他を明示的に拒否します。

許可されたライブラリ:

base（サブセット — 下記の拒否された関数を参照）
table
string
math
coroutine

拒否されたトップレベル関数（呼び出すと禁止アクセスエラーが発生）：

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

拒否されたライブラリ（読み取りまたは書き込みのいずれのアクセスでも禁止アクセスエラーが発生）：

os
io
debug
package
channel

サンドボックスのメタテーブルはロックされているため、ユーザースクリプトはそれを内省したり置き換えたりすることはできません。

型マッピング

GoからLuaおよびLuaからGoへの変換は自動的に適用されます：

Go型	Lua型
`string`	`string`
`float64` / `float32` / `int*`	`number`
`bool`	`boolean`
`map[string]any`	`table`
`nil`	`nil`
（その他）	`string`（`fmt.Sprintf`によるフォールバック）

返されたLuaテーブルはDataPayload（map[string]any）に戻されます。数値はLuaでの使用方法に関係なくfloat64として戻されます。

ユースケース

Transformの式型を超えるカスタムフィールド導出
任意の制御フローによる条件付きペイロード書き換え
単位変換、文字列フォーマット、シンプルな数式チェーン
別のサービスを立ち上げることなくの軽量な拡充

例: 派生フィールド

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

各ペイロードに華氏読み取り値とブール値フラグを追加します。

例: 条件付きドロップ

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

nilを返すと、入力ペイロードが変更されずに転送されます。実際にペイロードをドロップするには、空のテーブルを返すか、ダウンストリームでFilterを使用します。

例: 文字列操作

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

ベストプラクティス

ペイロードあたりのCPU使用量を制限するために非ゼロのtimeoutを設定（100〜500 msが典型的）
単純なフィールド抽出にはTransformを優先。本当のロジックが必要な場合のみScriptに頼る
スクリプトを短く純粋に保つ — すべてのペイロードで実行されます
大きな中間テーブルの構築を避ける。サンドボックスは有限のレジストリサイズを使用します
禁止されたシンボルを事前にテストする — サンドボックスからのLuaエラーはスクリプト実行エラーとして表面化し、ペイロードは発行されません