JavaScript Runtime

Status: Draft Created: 2024-12-21

Overview

The JavaScript Runtime feature enables IOTA SDK users to extend platform functionality through user-defined JavaScript code execution in a secure, multi-tenant sandboxed environment.

mindmap
  root((JS Runtime))
    Script Types
      Scheduled (Cron)
      HTTP Endpoints
      Event-Triggered
      One-Off
      Embedded
    Core Features
      Goja VM Engine
      Multi-tenant Isolation
      Resource Limits
      Version Control
    APIs
      Database Access
      HTTP Client
      Cache
      Events
      Logging

Documents

Document	Purpose	Status
Business	Business requirements and use cases	Draft
Decisions	Technology and architecture decisions	Draft
Technical	System design and implementation	Ready
Data Model	Database schema and entities	Draft
API Schema	HTMX endpoints and SDK APIs	Draft
UX	User interface and workflows	Draft

Architecture Overview

graph TB
    subgraph "IOTA SDK"
        subgraph "JS Runtime Module"
            UI[Web UI<br/>Monaco Editor]
            SVC[Services]
            DOM[Domain]
            REPO[Repositories]
        end

        subgraph "Execution Engine"
            POOL[VM Pool]
            SCHED[Scheduler]
            EVENTS[Event Handler]
        end

        EB[EventBus]
        DB[(PostgreSQL)]
    end

    UI --> SVC
    SVC --> DOM
    DOM --> REPO
    REPO --> DB

    SCHED --> SVC
    EVENTS --> SVC
    EB --> EVENTS
    SVC --> POOL

    style POOL fill:#10b981,stroke:#047857,color:#fff
    style UI fill:#3b82f6,stroke:#1e40af,color:#fff

Quick Links

Problem Statement: business.md#problem-statement
Use Cases: business.md#use-cases
Technology Decisions: decisions.md#decisions
Domain Model: data-model.md
Security Model: technical.md#security-considerations

Core Infrastructure:

#411 - JavaScript Runtime Core
#412 - VM Pooling & Resource Management
#413 - Script Versioning & Audit Trail
#148 - Monaco Editor Integration

Trigger Mechanisms:

#414 - Scheduled Scripts (Cron)
#415 - HTTP Endpoint Scripts
#416 - Event-Triggered Scripts
#417 - One-Off Script Execution

API & Bindings:

#418 - Standard Library API
#419 - Database Access API
#420 - HTTP Client API

Open Questions

From business.md: Pricing model for script execution quotas (free tier, paid tiers)
From decisions.md: VM pool sizing strategy (per-tenant vs global pool)
From decisions.md: Event retry backoff parameters (exponential base, max attempts)
From technical: HTTP endpoint path conflict resolution strategy
From security: Rate limiting per tenant (requests/minute, concurrent executions)

Next Steps

Review Business Requirements for use cases
See Technical Spec for implementation details
Check Data Model for database schema