execution.py

Overview

The execution.py file provides core functionality to execute user-submitted code snippets in a secure, isolated environment using Docker containers. It supports asynchronous execution of Python and Node.js code, managing container allocation, code preparation, execution, result collection, and cleanup.

This file handles:

• Allocating and releasing execution containers.

• Preparing user code and runner scripts inside a temporary sandbox directory.

• Packaging and transferring code into containers.

• Executing the code inside containers with resource/time limits.

• Capturing and analyzing execution results, including error classification.

• Cleaning up temporary resources post-execution.

It is a critical component of the InfiniFlow system's code execution pipeline, enabling safe and scalable dynamic code evaluation.

Classes and Functions

1. async def execute_code(req: CodeExecutionRequest) -> CodeExecutionResult

Purpose

Asynchronously executes given code in a Docker container sandbox according to the specified programming language and input arguments.

Parameters

• req (CodeExecutionRequest): A dataclass instance containing:

  • language (SupportLanguage): The programming language of the submitted code.

  • code_b64 (str): Base64-encoded source code to execute.

  • arguments (Optional[dict]): Optional JSON-serializable arguments to pass to the code's main function.

Returns

• CodeExecutionResult: Result object containing the execution status, output, error messages, exit code, and optional metadata like execution time or error classification.

Description

• Allocates a Docker container for the requested language.

• Creates a secure temporary working directory (/tmp/sandbox_<uuid>).

• Decodes and writes the user's source code and a generated runner script that wraps the main function call.

• Packs these files into a tarball and transfers them into the container workspace.

• Executes the runner script inside the container with a timeout enforced.

• Captures stdout, stderr, and exit codes.

• Analyzes results and classifies errors via analyze_error_result.

• Cleans up temporary files and releases the container.

• Handles runtime exceptions and resource limits gracefully.

Usage Example

from models.schemas import CodeExecutionRequest
from models.enums import SupportLanguage

req = CodeExecutionRequest(
    language=SupportLanguage.PYTHON,
    code_b64=base64.b64encode(b"def main(x): return x * 2").decode(),
    arguments={"x": 5}
)

result = await execute_code(req)
print(result.stdout)  # Expected output: "10"

2. def analyze_error_result(stderr: str, exit_code: int) -> CodeExecutionResult

Purpose

Analyzes stderr output and exit code from the containerized code execution to classify the error type and provide a structured response.

Parameters

• stderr (str): Standard error output captured from the code execution.

• exit_code (int): Process exit code from the execution.

Returns

• CodeExecutionResult: A result instance with appropriate status and error classification based on known error patterns.

Description

• Checks for known error strings such as:

  • "Permission denied" → Unauthorized file access.

  • "Operation not permitted" → Disallowed system call.

  • "MemoryError" → Memory limit exceeded.

• Defaults to a generic program error with NONZERO_EXIT runtime error type if no known patterns matched.

Usage Example

stderr = "Permission denied: cannot open file"
exit_code = 1
result = analyze_error_result(stderr, exit_code)
print(result.status)  # ResultStatus.UNAUTHORIZED_ACCESS

Important Implementation Details

• Container Management: Uses asynchronous functions allocate_container_blocking and release_container from core.container to manage container resources safely.

• Sandbox Environment: Each execution uses a uniquely named temporary directory (/tmp/sandbox_<uuid>) with restrictive permissions (700) to isolate code files.

• Runner Scripts: Dynamically generates language-specific runner scripts (runner.py for Python, runner.js for Node.js) that load the user code and invoke its main function with input arguments parsed from JSON.

• Docker File Transfer: Uses tar via subprocess to archive code and runner files, streams the archive into the container to /workspace/<task_id>.

• Execution Command:

  • Runs the code inside the container with a timeout enforced by the timeout command to prevent runaway execution.

  • Passes JSON serialized arguments as command-line parameters.

  • For Python, uses -I -B flags to isolate the environment and disable bytecode generation.

  • For Node.js, no extra flags are used.

• Error Handling and Logging:

  • Logs detailed execution info, including decoded code content, exit codes, and outputs.

  • Handles Docker exec errors, timeouts, and unexpected exceptions gracefully.

  • Classifies errors into meaningful categories for client feedback.

• Cleanup:

  • Deletes workspace directories inside the container and local temporary files asynchronously.

  • Ensures container release even on error or timeout.

Interaction with Other System Components

• Core Container Management (core.container): Requests and releases Docker containers from a managed pool.

• Configuration (core.config): Reads global timeout settings.

• Logging (core.logger): Emits detailed logs for execution tracing and debugging.

• Models and Schemas (models.enums, models.schemas): Uses enums for language types, result statuses, and error classifications; uses schema classes for request/response data structures.

• Utility Functions (utils.common): Uses async_run_command to run shell commands asynchronously with timeout support.

• Docker: Relies on Docker CLI commands for container interaction, file transfer, and code execution sandboxing.

This file acts as a bridge between the user-facing code submission interface and the underlying containerized execution infrastructure.

Mermaid Diagram: Class and Function Structure

classDiagram
    class execution.py {
        <<module>>
        +async execute_code(req: CodeExecutionRequest) CodeExecutionResult
        +analyze_error_result(stderr: str, exit_code: int) CodeExecutionResult
    }

Summary

The execution.py file is a robust, asynchronous code execution engine integral to InfiniFlow's runtime environment. It carefully orchestrates container allocation, secure code preparation, execution with argument passing, result collection, error classification, and resource cleanup. Supporting multiple languages (currently Python and Node.js), it ensures safe and scalable code evaluation utilizing Docker container isolation and detailed error handling.

This module interacts closely with container management, configuration, logging, and utility components to provide a seamless and secure execution experience.