re-uploading work
This commit is contained in:
237
work-summary/sessions/2026-01-27-manual-execution-feature.md
Normal file
237
work-summary/sessions/2026-01-27-manual-execution-feature.md
Normal file
@@ -0,0 +1,237 @@
|
||||
# Manual Execution Feature Implementation
|
||||
|
||||
**Date:** 2026-01-27
|
||||
**Status:** ✅ Complete
|
||||
**Feature:** Direct action execution via API without triggers/rules
|
||||
|
||||
## Overview
|
||||
|
||||
Implemented the ability to execute actions directly via the API without requiring a trigger, sensor, or rule. This enables manual testing, ad-hoc task execution, and API-driven workflows.
|
||||
|
||||
## Problem Statement
|
||||
|
||||
Previously, the only way to execute an action in Attune was through the event-driven automation flow:
|
||||
|
||||
```
|
||||
Sensor → Trigger → Event → Rule → Enforcement → Execution
|
||||
```
|
||||
|
||||
There was no way to directly execute an action with parameters via the API. The E2E test `test_execute_action_directly` was skipped with the reason: "Manual execution API not yet implemented."
|
||||
|
||||
## Solution
|
||||
|
||||
### API Endpoint
|
||||
|
||||
Implemented `POST /api/v1/executions/execute` endpoint:
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"action_ref": "slack.post_message",
|
||||
"parameters": {
|
||||
"channel": "#alerts",
|
||||
"message": "Manual test"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Response (201 Created):**
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"id": 123,
|
||||
"action_ref": "slack.post_message",
|
||||
"status": "Requested",
|
||||
"config": {
|
||||
"channel": "#alerts",
|
||||
"message": "Manual test"
|
||||
},
|
||||
"parent": null,
|
||||
"enforcement": null,
|
||||
"created": "2026-01-27T17:00:00Z",
|
||||
"updated": "2026-01-27T17:00:00Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Implementation Details
|
||||
|
||||
**Files Modified:**
|
||||
|
||||
1. **`crates/api/src/dto/execution.rs`** - Added `CreateExecutionRequest` DTO
|
||||
```rust
|
||||
pub struct CreateExecutionRequest {
|
||||
pub action_ref: String,
|
||||
pub parameters: Option<JsonValue>,
|
||||
}
|
||||
```
|
||||
|
||||
2. **`crates/api/src/routes/executions.rs`** - Added `create_execution` handler
|
||||
- Validates action exists using `ActionRepository::find_by_ref()`
|
||||
- Creates execution with `ExecutionRepository::create()`
|
||||
- Sets status to `ExecutionStatus::Requested`
|
||||
- Publishes `ExecutionRequestedPayload` to RabbitMQ
|
||||
- Returns 201 Created with execution details
|
||||
|
||||
3. **`crates/api/src/dto/mod.rs`** - Exported new DTO
|
||||
|
||||
4. **`tests/test_e2e_basic.py`** - Enabled and implemented test
|
||||
- Removed `@pytest.mark.skip` decorator
|
||||
- Implemented full test: create action → execute → verify
|
||||
- Fixed test fixture to handle pack already exists (409 Conflict)
|
||||
|
||||
### Flow
|
||||
|
||||
1. **API receives request** → Validates action exists
|
||||
2. **Create execution record** → Status: `Requested`, no enforcement/parent
|
||||
3. **Publish to queue** → `ExecutionRequestedPayload` on `attune.executions` exchange
|
||||
4. **Return response** → 201 Created with execution ID and details
|
||||
5. **Executor picks up** → (existing executor service handles the queued execution)
|
||||
|
||||
### Key Technical Decisions
|
||||
|
||||
1. **Status = Requested** - Uses existing enum variant for queued executions
|
||||
2. **No enforcement/parent** - Manual executions are top-level, not tied to rules
|
||||
3. **Optional MQ** - Gracefully handles when publisher is not configured
|
||||
4. **Repository pattern** - Uses `Create` trait for consistent database access
|
||||
5. **Separate endpoint** - Used `/executions/execute` instead of `POST /executions` to avoid route conflicts
|
||||
|
||||
## Testing
|
||||
|
||||
### E2E Test Results
|
||||
|
||||
```bash
|
||||
cd tests && ./venvs/e2e/bin/pytest test_e2e_basic.py -v
|
||||
```
|
||||
|
||||
**All 6 tests passing:**
|
||||
- ✅ `test_api_health`
|
||||
- ✅ `test_authentication`
|
||||
- ✅ `test_pack_registration`
|
||||
- ✅ `test_create_simple_action`
|
||||
- ✅ `test_create_automation_rule`
|
||||
- ✅ `test_execute_action_directly` **(NEW - previously skipped)**
|
||||
|
||||
### Test Coverage
|
||||
|
||||
The new test verifies:
|
||||
1. Action creation succeeds
|
||||
2. Manual execution request accepted (201 Created)
|
||||
3. Execution has correct action_ref and parameters
|
||||
4. Execution status is valid (`requested`, `scheduling`, `scheduled`, `running`)
|
||||
5. Execution can be retrieved by ID
|
||||
|
||||
## Use Cases
|
||||
|
||||
1. **Manual Testing**
|
||||
- Execute actions during development
|
||||
- Test action behavior with different parameters
|
||||
- Debug action failures
|
||||
|
||||
2. **Ad-hoc Operations**
|
||||
- Administrative tasks without creating rules
|
||||
- One-off notifications or alerts
|
||||
- Emergency response actions
|
||||
|
||||
3. **API-Driven Workflows**
|
||||
- External systems trigger actions directly
|
||||
- REST API integrations
|
||||
- Scheduled jobs from external schedulers
|
||||
|
||||
4. **Action Development**
|
||||
- Quick feedback loop during action development
|
||||
- Test parameter validation
|
||||
- Verify action outputs
|
||||
|
||||
## API Documentation
|
||||
|
||||
**Endpoint:** `POST /api/v1/executions/execute`
|
||||
|
||||
**Authentication:** Required (Bearer token)
|
||||
|
||||
**Request Body:**
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `action_ref` | string | Yes | Action reference (e.g., "pack.action") |
|
||||
| `parameters` | object | No | Action parameters as JSON object |
|
||||
|
||||
**Response Codes:**
|
||||
- `201 Created` - Execution created and queued
|
||||
- `400 Bad Request` - Invalid request body
|
||||
- `401 Unauthorized` - Missing or invalid token
|
||||
- `404 Not Found` - Action not found
|
||||
- `500 Internal Server Error` - Server error
|
||||
|
||||
**OpenAPI:** Auto-documented via utoipa
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
1. **Synchronous execution** - Wait for execution to complete before returning
|
||||
2. **Execution callbacks** - Webhook notifications when execution completes
|
||||
3. **Batch execution** - Execute multiple actions in one request
|
||||
4. **Execution templates** - Save common execution configurations
|
||||
5. **Execution scheduling** - Schedule manual executions for future time
|
||||
|
||||
## Impact
|
||||
|
||||
**Before:**
|
||||
- ✅ Event-driven automation (sensor → trigger → rule → action)
|
||||
- ❌ No manual action execution
|
||||
- ❌ No API-driven workflows
|
||||
- ⏭️ Test skipped (1 of 6)
|
||||
|
||||
**After:**
|
||||
- ✅ Event-driven automation (existing)
|
||||
- ✅ Manual action execution (new)
|
||||
- ✅ API-driven workflows (new)
|
||||
- ✅ All tests passing (6 of 6)
|
||||
|
||||
## Documentation Updates
|
||||
|
||||
- ✅ `CHANGELOG.md` - Feature announcement with examples
|
||||
- ✅ `work-summary/2026-01-27-manual-execution-feature.md` - This document
|
||||
- ✅ Test documentation in `test_e2e_basic.py` - Updated class docstring
|
||||
|
||||
## Related Work
|
||||
|
||||
- **Sensor Service Fix** - Fixed repository pattern issues that would have affected this feature
|
||||
- **Webhook Schema** - Consolidated schema working correctly with all execution types
|
||||
- **E2E Testing** - Full test coverage ensures feature works end-to-end
|
||||
|
||||
## Verification Commands
|
||||
|
||||
```bash
|
||||
# Rebuild API service
|
||||
cargo build -p attune-api
|
||||
|
||||
# Restart API service
|
||||
pkill attune-api
|
||||
./target/debug/attune-api > /tmp/attune-api.log 2>&1 &
|
||||
|
||||
# Run E2E tests
|
||||
cd tests
|
||||
./venvs/e2e/bin/pytest test_e2e_basic.py -v
|
||||
|
||||
# Test manual execution directly
|
||||
curl -X POST http://localhost:8080/api/v1/executions/execute \
|
||||
-H "Authorization: Bearer $TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"action_ref": "test_pack.echo",
|
||||
"parameters": {"message": "Hello World"}
|
||||
}'
|
||||
```
|
||||
|
||||
## Success Metrics
|
||||
|
||||
- ✅ API endpoint implemented and documented
|
||||
- ✅ Execution creation working correctly
|
||||
- ✅ Message queue integration functional
|
||||
- ✅ All E2E tests passing (6/6)
|
||||
- ✅ Test previously skipped now enabled and passing
|
||||
- ✅ Zero compilation errors
|
||||
- ✅ API service successfully restarted
|
||||
|
||||
---
|
||||
|
||||
**Conclusion:** The manual execution feature is fully implemented, tested, and ready for production use. Users can now execute actions directly via the API without requiring the full automation setup, enabling faster testing and more flexible workflows.
|
||||
Reference in New Issue
Block a user