feat: dual-mode runtime for Flash Deployed Apps and Live Serverless

[deanq]

Prerequisite: runpod/tetra-rp#140

Summary

Implements dual-mode runtime support enabling worker-tetra Docker images to serve both Live Serverless and Flash Deployed Apps through a unified handler architecture.

Please see docs/Runtime_Execution_Paths.md

Implementation

Deployment Mode Detection

• Flash Detection: Checks for FLASH_IS_MOTHERSHIP, FLASH_MOTHERSHIP_ID, or FLASH_RESOURCE_NAME environment variables
• Live Serverless: Has RUNPOD_* vars but NO FLASH_* vars → skips artifact unpacking
• Local Development: No RUNPOD_* vars → skips artifact unpacking

Handler Integration

• Both handler.py and lb_handler.py call maybe_unpack() at module-level initialization
• Thread-safe extraction with double-checked locking pattern
• Idempotent: multiple calls only extract once

Request Routing

• Live Serverless: Request includes function_code or class_code → Dynamic execution
• Flash Deployed: Request omits code fields → Manifest-based routing to pre-deployed code
• Single RemoteExecutor handles both modes automatically

Flash Function Execution

• O(1) function lookup via flash_manifest.json registry
• Dynamic import from /app directory
• Handles both sync and async functions
• Same cloudpickle serialization as Live Serverless

Changes

Core Implementation

• src/unpack_volume.py: Updated _should_unpack_from_volume() to distinguish Flash from Live Serverless
• src/handler.py: Added maybe_unpack() call at module-level
• src/lb_handler.py: Added maybe_unpack() call at module-level
• src/remote_executor.py: Added Flash detection logic and _execute_flash_function() method

Testing

• Unit Tests: Added 15+ tests for Flash detection and execution logic
• Integration Tests: Added 7 tests for dual-mode coexistence
• Coverage: All existing 474+ tests pass, coverage maintained

Documentation

• docs/Runtime_Execution_Paths.md: New documentation for dual-mode architecture

Backward Compatibility

✅ Fully backward compatible - All existing Live Serverless requests continue working unchanged:

• Requests with function_code use existing dynamic execution path
• No protocol changes required
• Local development unaffected

Verification

Deployment Modes Tested

• ✅ Local dev (no unpacking)
• ✅ Live Serverless (no unpacking, RUNPOD_* only)
• ✅ Flash Mothership (unpacking, FLASH_IS_MOTHERSHIP=true)
• ✅ Flash Child (unpacking, FLASH_MOTHERSHIP_ID set)

Test Results

• All 474+ existing tests pass
• 7 new integration tests pass
• 15+ new unit tests pass
• Code formatting, linting, and type checks pass

Related

• Implements AE-1348
• Builds on volume unpacking system from PR feat: unpack app tarballs from shadow volumes #49
• Enables Flash deployment pipeline (tetra-rp)

Test Plan

Manual Testing:

# In Flash deployment (FLASH_* env vars set)
ls /app/  # Should see extracted artifacts
python -c "import sys; print('/app' in sys.path)"  # Should be True

# Test both modes
curl -X POST /execute -d '{"function_code": "def f(): return 1"}'  # Live Serverless
curl -X POST /execute -d '{"function_name": "my_flash_func"}'      # Flash Deployed

CI/CD:

• All automated tests run on PR
• Docker images build successfully
• Handler tests validate both execution modes

[Copilot]

Pull request overview

This PR implements dual-mode runtime support enabling worker-tetra Docker images to serve both Live Serverless and Flash Deployed Apps through a unified handler architecture. The implementation adds automatic deployment mode detection based on environment variables and routes requests to the appropriate execution path without requiring protocol changes.

Changes:

• Enhanced deployment mode detection to distinguish Flash deployments from Live Serverless based on FLASH_* environment variables
• Added Flash function execution path in RemoteExecutor with manifest-based routing
• Integrated maybe_unpack() calls in both handlers to support Flash artifact extraction
• Made function_code optional in FunctionRequest to support Flash deployments
• Added comprehensive test coverage for dual-mode coexistence and Flash execution

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tetra-rp	Updated subproject commit reference
tests/unit/test_unpack_volume.py	Updated tests to validate Flash-specific environment variable detection and distinguish Flash from Live Serverless
tests/unit/test_remote_executor.py	Added tests for Flash detection logic, routing, and execution including manifest loading and error handling
tests/unit/test_remote_execution.py	Made function_code optional in FunctionRequest validation to support Flash deployments
tests/integration/test_flash_integration.py	Added integration tests for dual-mode coexistence, Flash execution paths, and backward compatibility
src/unpack_volume.py	Enhanced _should_unpack_from_volume() to detect Flash deployments via FLASH_* environment variables
src/remote_executor.py	Added Flash detection and execution logic with _execute_flash_function() and _load_flash_manifest() methods
src/lb_handler.py	Added module-level maybe_unpack() call for Flash artifact extraction
src/handler.py	Added module-level maybe_unpack() call for Flash artifact extraction
docs/Runtime_Execution_Paths.md	Added comprehensive documentation for dual-mode architecture and execution flows

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.