# FunctionService Integration with Artifact-Task-Instance Architecture

## Overview / 概述

This document describes how FunctionService integrates with the new Artifact-Task-Instance architecture, including architectural changes, implementation details, and migration strategies.

## Architecture Changes / 架构变更

### Previous Architecture / 原有架构

```rust
pub struct FunctionServiceImpl {
    start_time: SystemTime,
    active_executions: Arc<RwLock<HashMap<String, ExecutionHandle>>>,
}
```

### New Architecture / 新架构

```rust
pub struct FunctionServiceImpl {
    start_time: SystemTime,
    execution_manager: TaskExecutionManager,
    instance_pool: InstancePool,
    stats: Arc<RwLock<FunctionServiceStats>>,
}
```

### Initialization Contract / 初始化约定

- `FunctionServiceImpl::new` requires `Arc<SpearletConfig>` to propagate full node configuration into all runtimes via `RuntimeConfig.spearlet_config`.
- Example:

```rust
let service = FunctionServiceImpl::new(Arc::new(SpearletConfig::default())).await?;
```

## Core Component Integration / 核心组件集成

### 1. TaskExecutionManager Integration

TaskExecutionManager manages the lifecycle of tasks:

- **Task Creation / 任务创建**: Create new tasks from ArtifactSpec
- **Execution Management / 执行管理**: Coordinate task execution flow
- **Status Tracking / 状态跟踪**: Track task execution status

```rust
// Create execution manager / 创建执行管理器
let runtime_manager = Arc::new(RuntimeManager::new());
let manager_config = TaskExecutionManagerConfig::default();
let execution_manager = TaskExecutionManager::new(manager_config, runtime_manager).await?;
```

### 2. InstancePool Integration

InstancePool manages runtime instances:

- **Instance Scheduling / 实例调度**: Use InstanceScheduler for load balancing
- **Resource Management / 资源管理**: Manage instance lifecycle
- **Performance Optimization / 性能优化**: Instance reuse and warm-up

```rust
// Create instance pool / 创建实例池
let pool_config = InstancePoolConfig::default();
let scheduler = Arc::new(InstanceScheduler::new(SchedulingPolicy::RoundRobin));
let instance_pool = InstancePool::new(pool_config, scheduler).await?;
```

### 3. Enhanced Statistics

New statistics structure provides more detailed monitoring data:

```rust
pub struct FunctionServiceStats {
    pub task_count: i32,
    pub execution_count: i32,
    pub running_executions: i32,
    pub artifact_count: i32,        // New
    pub instance_count: i32,        // New
    pub successful_executions: i32, // New
    pub failed_executions: i32,     // New
    pub average_response_time_ms: f64, // New
}
```

## Function Invocation Flow / 函数调用流程

### 1. Artifact Creation

```rust
fn create_artifact_from_proto(proto_spec: &ArtifactSpec) -> Result<Artifact, ExecutionError> {
    let execution_spec = ExecutionArtifactSpec {
        name: proto_spec.artifact_id.clone(),
        version: proto_spec.version.clone(),
        description: "Generated from proto".to_string(),
        runtime_type: proto_spec.artifact_type.clone(),
        runtime_config: serde_json::Value::Null,
        environment: std::collections::HashMap::new(),
        resource_limits: Default::default(),
        invocation_type: InvocationType::NewTask,
        max_execution_timeout_ms: 30000,
        labels: proto_spec.metadata.clone(),
    };
    
    Artifact::new(execution_spec)
}
```

### 2. Task Execution

```rust
async fn invoke_function(
    &self,
    request: Request<InvokeFunctionRequest>,
) -> Result<Response<InvokeFunctionResponse>, Status> {
    let req = request.into_inner();
    
    // 1. Create Artifact
    let artifact = self.create_artifact_from_proto(&req.artifact_spec)?;
    
    // 2. Execute through TaskExecutionManager
    let invoke = InvokeRequest {
        invocation_id: req.invocation_id,
        execution_id: req.execution_id,
        task_id: req.task_id,
        function_name: req.function_name,
        input: req.input,
        headers: req.headers,
        environment: req.environment,
        timeout_ms: req.timeout_ms,
        session_id: req.session_id,
        mode: req.mode,
        force_new_instance: req.force_new_instance,
        metadata: req.metadata,
    };

    let execution_response = self.execution_manager.submit_invocation(invoke).await?;
    
    // 3. Convert response
    let response = self.execution_response_to_proto(execution_response)?;
    
    Ok(Response::new(response))
}
```

## Error Handling / 错误处理

The new architecture provides unified error handling:

```rust
pub enum ExecutionError {
    ArtifactError(String),
    TaskError(String),
    InstanceError(String),
    RuntimeError(String),
    ConfigurationError(String),
}
```

## Performance Optimizations / 性能优化

### 1. Instance Reuse
- Instance pool maintains hot instances to reduce cold start time
- Smart scheduling algorithms optimize resource utilization

### 2. Asynchronous Execution
- Fully asynchronous architecture improves concurrent processing capability
- Non-blocking I/O operations

### 3. Memory Management
- Arc and RwLock optimize memory sharing
- Smart caching strategies

## Monitoring and Observability / 监控和观测

### 1. Metrics Collection
- Task execution time
- Success/failure rates
- Instance utilization
- Memory usage

### 2. Logging
```rust
use tracing::{info, warn, error, debug, trace};

// Structured logging
info!(
    task_id = %task_id,
    execution_time_ms = execution_time,
    "Task execution completed"
);
```

### 3. Health Checks
```rust
async fn get_health(&self) -> Result<Response<GetHealthResponse>, Status> {
    let stats = self.get_stats().await?;
    
    let health_details = HealthDetails {
        service_name: "spearlet-function-service".to_string(),
        version: env!("CARGO_PKG_VERSION").to_string(),
        uptime_seconds: self.start_time.elapsed()?.as_secs() as i64,
        active_tasks: 10, // Get from execution_manager
        memory_usage_mb: 0, // To be implemented
        cpu_usage_percent: 0.0, // To be implemented
    };
    
    Ok(Response::new(GetHealthResponse {
        healthy: true,
        details: Some(health_details),
    }))
}
```

## Migration Considerations / 迁移注意事项

### 1. Backward Compatibility
- Keep gRPC interface unchanged
- Progressive migration strategy

### 2. Configuration Updates
- Add TaskExecutionManagerConfig
- Add InstancePoolConfig
- Update RuntimeConfig to include `spearlet_config: Option<SpearletConfig>` for full config propagation

### 4. WASM Artifact Download Path / WASM 制品下载路径

- WASM runtime supports `smsfile://<file_id>` scheme.
- It resolves `SpearletConfig.sms_grpc_addr` from `RuntimeConfig.spearlet_config` and uses:

```rust
pub async fn fetch_sms_file(sms_http_addr: &str, path: &str) -> ExecutionResult<Vec<u8>>
```

### 3. Testing Strategy
- Unit tests cover new components
- Integration tests verify end-to-end flow
- Performance tests ensure no regression

## Future Extensions / 未来扩展

### 1. Distributed Execution
- Support cross-node task scheduling
- Distributed instance pool

### 2. Advanced Scheduling
- Load-based intelligent scheduling
- Priority queues

### 3. Auto-scaling
- Automatically adjust instance count based on load
- Predictive scaling

## Summary / 总结

The new Artifact-Task-Instance architecture provides FunctionService with:

1. **Better Modularity / 更好的模块化**: Clear separation of responsibilities
2. **Enhanced Observability / 增强的可观测性**: Detailed monitoring and logging
3. **Improved Performance / 提升的性能**: Optimized resource management
4. **Better Scalability / 更强的扩展性**: Support for future feature extensions

This architecture establishes a solid foundation for building high-performance, scalable function execution services.
