Security & Execution Limits

KodiScript provides built-in mechanisms to protect your application from infinite loops, overly complex scripts, and long-running execution. This is essential when executing untrusted code or allowing user-defined scripts.

Instruction Counter (Max Operations)

You can limit the number of operations (instructions) a script executes. This is a deterministic way to prevent infinite loops.

Usage

result := kodi.New(script).
    WithMaxOperations(10000).
    Execute()

val result = KodiScript.builder(script)
    .withMaxOperations(10000)
    .execute()

final result = KodiScript.builder(script)
    .withMaxOperations(10000)
    .execute();

const result = KodiScript.builder(script)
    .withMaxOperations(10000)
    .execute();

$result = KodiScript::builder($script)
    ->withMaxOperations(10000)
    ->execute();

If the limit is exceeded, execution stops immediately and an error is returned (e.g., MaxOperationsExceeded).

Time-based Timeout

You can also set a maximum duration for script execution. This is useful for ensuring latency SLAs.

Usage

result := kodi.New(script).
    WithTimeout(5 * time.Second).
    Execute()

// milliseconds
val result = KodiScript.builder(script)
    .withTimeout(5000)
    .execute()

final result = KodiScript.builder(script)
    .withTimeout(Duration(seconds: 5))
    .execute();

// milliseconds
const result = KodiScript.builder(script)
    .withTimeout(5000)
    .execute();

// milliseconds
$result = KodiScript::builder($script)
    ->withTimeout(5000)
    ->execute();

If the timeout is exceeded, execution stops and a TimeoutError (or equivalent) is returned.

Best Practices

• Always set limits when running untrusted code.
• Combine both: Use maxOps for deterministic protection against logic errors (loops) and timeout as a failsafe for heavy computation.
• Handle errors: Always check if the result contains errors indicating a limit was reached.