jsruntime

Documentation

Index

• type ErrorCode
• type ExecutionContext
• type ExecutionOptions
• type JsError
  • func NewJsError(code ErrorCode, message string) *JsError
  • func NewJsErrorWithStack(code ErrorCode, message, stack string) *JsError
  • func (e *JsError) Error() string
• type Pool
  • func NewPool(size int) (*Pool, error)
  • func (p *Pool) Acquire(ctx context.Context) (*goja.Runtime, error)
  • func (p *Pool) Available() int
  • func (p *Pool) Close() error
  • func (p *Pool) Release(vm *goja.Runtime) error
  • func (p *Pool) Resize(newSize int) error
  • func (p *Pool) Size() int
• type Result
  • func Execute(ctx context.Context, caller ToolCaller, code string, opts ExecutionOptions) *Result
  • func NewErrorResult(err *JsError) *Result
  • func NewSuccessResult(value interface{}) *Result
• type ToolCallRecord
• type ToolCaller

Types

type ErrorCode

type ErrorCode string

ErrorCode represents specific JavaScript execution error types

const (
	// ErrorCodeSyntaxError indicates invalid JavaScript syntax
	ErrorCodeSyntaxError ErrorCode = "SYNTAX_ERROR"

	// ErrorCodeRuntimeError indicates JavaScript runtime exception
	ErrorCodeRuntimeError ErrorCode = "RUNTIME_ERROR"

	// ErrorCodeTimeout indicates execution exceeded timeout limit
	ErrorCodeTimeout ErrorCode = "TIMEOUT"

	// ErrorCodeMaxToolCallsExceeded indicates max_tool_calls limit reached
	ErrorCodeMaxToolCallsExceeded ErrorCode = "MAX_TOOL_CALLS_EXCEEDED"

	// ErrorCodeServerNotAllowed indicates call_tool attempted to call disallowed server
	ErrorCodeServerNotAllowed ErrorCode = "SERVER_NOT_ALLOWED"

	// ErrorCodeSerializationError indicates result cannot be JSON-serialized
	ErrorCodeSerializationError ErrorCode = "SERIALIZATION_ERROR"
)

type ExecutionContext

type ExecutionContext struct {
	ExecutionID  string
	StartTime    time.Time
	EndTime      *time.Time
	Status       string // "running", "success", "error", "timeout"
	ToolCalls    []ToolCallRecord
	ResultValue  interface{}
	ErrorDetails *JsError
	// contains filtered or unexported fields
}

ExecutionContext tracks the state of a single JavaScript execution

type ExecutionOptions

type ExecutionOptions struct {
	Input          map[string]interface{} // Input data accessible as global `input` variable
	TimeoutMs      int                    // Execution timeout in milliseconds
	MaxToolCalls   int                    // Maximum number of call_tool() invocations (0 = unlimited)
	AllowedServers []string               // Whitelist of allowed server names (empty = all allowed)
	ExecutionID    string                 // Unique execution ID for logging (auto-generated if empty)
}

ExecutionOptions contains optional parameters for JavaScript execution

type JsError

type JsError struct {
	Message string    `json:"message"`
	Stack   string    `json:"stack,omitempty"`
	Code    ErrorCode `json:"code"`
}

JsError represents a JavaScript execution error with message, stack trace, and error code

func NewJsError

func NewJsError(code ErrorCode, message string) *JsError

NewJsError creates a new JsError with the given code and message

func NewJsErrorWithStack

func NewJsErrorWithStack(code ErrorCode, message, stack string) *JsError

NewJsErrorWithStack creates a new JsError with code, message, and stack trace

func (*JsError) Error

func (e *JsError) Error() string

Error implements the error interface

type Pool

type Pool struct {
	// contains filtered or unexported fields
}

Pool manages a pool of reusable JavaScript runtime instances for concurrent execution

func NewPool

func NewPool(size int) (*Pool, error)

NewPool creates a new JavaScript runtime pool with the specified size

func (*Pool) Acquire

func (p *Pool) Acquire(ctx context.Context) (*goja.Runtime, error)

Acquire obtains a runtime instance from the pool Blocks until an instance is available or context is cancelled

func (*Pool) Available

func (p *Pool) Available() int

Available returns the number of available instances in the pool

func (*Pool) Close

func (p *Pool) Close() error

Close closes the pool and releases all resources

func (*Pool) Release

func (p *Pool) Release(vm *goja.Runtime) error

Release returns a runtime instance to the pool

func (*Pool) Resize

func (p *Pool) Resize(newSize int) error

Resize adjusts the pool size (for hot configuration reload) If newSize > current size, adds new instances If newSize < current size, instances will be removed as they're released

func (*Pool) Size

func (p *Pool) Size() int

Size returns the configured pool size

type Result

type Result struct {
	// Ok indicates success (true) or error (false)
	Ok bool `json:"ok"`

	// Value contains the JavaScript return value if Ok=true (must be JSON-serializable)
	Value interface{} `json:"value,omitempty"`

	// Error contains error details if Ok=false
	Error *JsError `json:"error,omitempty"`
}

Result represents the outcome of JavaScript execution

func Execute

func Execute(ctx context.Context, caller ToolCaller, code string, opts ExecutionOptions) *Result

Execute runs JavaScript code in a sandboxed environment with tool call capabilities

func NewErrorResult

func NewErrorResult(err *JsError) *Result

NewErrorResult creates a Result with ok=false and the given error

func NewSuccessResult

func NewSuccessResult(value interface{}) *Result

NewSuccessResult creates a Result with ok=true and the given value

type ToolCallRecord

type ToolCallRecord struct {
	ServerName  string                 `json:"server_name"`
	ToolName    string                 `json:"tool_name"`
	Arguments   map[string]interface{} `json:"arguments"`
	StartTime   time.Time              `json:"start_time"`
	DurationMs  int64                  `json:"duration_ms"`
	Success     bool                   `json:"success"`
	Result      interface{}            `json:"result,omitempty"`
	ErrorDetail interface{}            `json:"error_details,omitempty"`
}

ToolCallRecord represents a single call_tool() invocation

type ToolCaller

type ToolCaller interface {
	CallTool(ctx context.Context, serverName, toolName string, args map[string]interface{}) (interface{}, error)
}

ToolCaller is an interface for calling upstream MCP tools