re-uploading work
This commit is contained in:
289
docs/guides/QUICKREF-timer-happy-path.md
Normal file
289
docs/guides/QUICKREF-timer-happy-path.md
Normal file
@@ -0,0 +1,289 @@
|
||||
# Quick Reference: Timer Echo Happy Path Test
|
||||
|
||||
This guide provides a quick reference for testing the core happy-path scenario in Attune: an interval timer running every second to execute `echo "Hello, World!"`.
|
||||
|
||||
## Overview
|
||||
|
||||
This test verifies the complete event-driven flow with unified runtime detection:
|
||||
|
||||
```
|
||||
Timer Sensor → Event → Rule Match → Enforcement → Execution → Worker → Shell Action
|
||||
```
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Docker and Docker Compose installed
|
||||
- All Attune services running in containers
|
||||
- Core pack loaded with timer triggers and echo action
|
||||
|
||||
## Quick Test (Automated)
|
||||
|
||||
Run the automated test script:
|
||||
|
||||
```bash
|
||||
cd attune
|
||||
./scripts/test-timer-echo-docker.sh
|
||||
```
|
||||
|
||||
This script will:
|
||||
1. ✓ Check Docker services are healthy
|
||||
2. ✓ Authenticate with API
|
||||
3. ✓ Verify runtime detection (Shell runtime available)
|
||||
4. ✓ Verify core pack is loaded
|
||||
5. ✓ Create a 1-second interval timer trigger instance
|
||||
6. ✓ Create a rule linking timer to echo action
|
||||
7. ✓ Wait 15 seconds and verify executions
|
||||
8. ✓ Display results and cleanup
|
||||
|
||||
**Expected output:**
|
||||
```
|
||||
=== HAPPY PATH TEST PASSED ===
|
||||
|
||||
The complete event flow is working:
|
||||
Timer Sensor → Event → Rule → Enforcement → Execution → Worker → Shell Action
|
||||
```
|
||||
|
||||
## Manual Test Steps
|
||||
|
||||
### 1. Start Services
|
||||
|
||||
```bash
|
||||
docker-compose up -d
|
||||
docker-compose ps # Verify all services are running
|
||||
```
|
||||
|
||||
### 2. Check Runtime Detection
|
||||
|
||||
```bash
|
||||
# Get auth token
|
||||
export TOKEN=$(curl -s -X POST http://localhost:8080/auth/login \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"username":"admin","password":"admin"}' | jq -r '.data.access_token')
|
||||
|
||||
# Verify runtimes detected
|
||||
curl -H "Authorization: Bearer $TOKEN" \
|
||||
http://localhost:8080/api/v1/runtimes | jq '.data[] | {name, enabled}'
|
||||
```
|
||||
|
||||
**Expected:** Shell runtime should be present and enabled.
|
||||
|
||||
### 3. Verify Core Pack
|
||||
|
||||
```bash
|
||||
curl -H "Authorization: Bearer $TOKEN" \
|
||||
http://localhost:8080/api/v1/packs/core | jq '.data | {id, ref, name}'
|
||||
```
|
||||
|
||||
**Expected:** Core pack with actions and triggers loaded.
|
||||
|
||||
### 4. Create Trigger Instance
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8080/api/v1/trigger-instances \
|
||||
-H "Authorization: Bearer $TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"trigger_type_ref": "core.intervaltimer",
|
||||
"ref": "test.timer_1s",
|
||||
"description": "1-second interval timer",
|
||||
"enabled": true,
|
||||
"parameters": {
|
||||
"unit": "seconds",
|
||||
"interval": 1
|
||||
}
|
||||
}' | jq '.data | {id, ref}'
|
||||
```
|
||||
|
||||
### 5. Create Rule
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8080/api/v1/rules \
|
||||
-H "Authorization: Bearer $TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"ref": "test.timer_echo",
|
||||
"pack_ref": "core",
|
||||
"name": "Timer Echo Test",
|
||||
"description": "Echoes Hello World every second",
|
||||
"enabled": true,
|
||||
"trigger_instance_ref": "test.timer_1s",
|
||||
"action_ref": "core.echo",
|
||||
"action_parameters": {
|
||||
"message": "Hello, World!"
|
||||
}
|
||||
}' | jq '.data | {id, ref}'
|
||||
```
|
||||
|
||||
### 6. Monitor Executions
|
||||
|
||||
Wait 10-15 seconds, then check for executions:
|
||||
|
||||
```bash
|
||||
curl -H "Authorization: Bearer $TOKEN" \
|
||||
http://localhost:8080/api/v1/executions?limit=10 | \
|
||||
jq '.data[] | {id, status, action_ref, created}'
|
||||
```
|
||||
|
||||
**Expected:** Multiple executions with `status: "succeeded"` and `action_ref: "core.echo"`.
|
||||
|
||||
### 7. Check Service Logs
|
||||
|
||||
```bash
|
||||
# Sensor service (timer firing)
|
||||
docker logs attune-sensor --tail 50 | grep -i "timer\|interval"
|
||||
|
||||
# Executor service (scheduling)
|
||||
docker logs attune-executor --tail 50 | grep -i "execution\|schedule"
|
||||
|
||||
# Worker service (runtime detection and action execution)
|
||||
docker logs attune-worker --tail 50 | grep -i "runtime\|shell\|echo"
|
||||
```
|
||||
|
||||
**Expected log entries:**
|
||||
|
||||
**Sensor:**
|
||||
```
|
||||
Timer trigger fired: core.intervaltimer
|
||||
Event created: id=123
|
||||
```
|
||||
|
||||
**Executor:**
|
||||
```
|
||||
Processing enforcement: id=456
|
||||
Execution scheduled: id=789
|
||||
```
|
||||
|
||||
**Worker:**
|
||||
```
|
||||
Runtime detected: Shell
|
||||
Executing action: core.echo
|
||||
Action completed successfully
|
||||
```
|
||||
|
||||
### 8. Cleanup
|
||||
|
||||
```bash
|
||||
# Disable the rule
|
||||
curl -X PUT http://localhost:8080/api/v1/rules/test.timer_echo \
|
||||
-H "Authorization: Bearer $TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"enabled": false}'
|
||||
|
||||
# Delete the rule (optional)
|
||||
curl -X DELETE http://localhost:8080/api/v1/rules/test.timer_echo \
|
||||
-H "Authorization: Bearer $TOKEN"
|
||||
|
||||
# Delete trigger instance (optional)
|
||||
curl -X DELETE http://localhost:8080/api/v1/trigger-instances/test.timer_1s \
|
||||
-H "Authorization: Bearer $TOKEN"
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### No Executions Created
|
||||
|
||||
**Check 1: Is the sensor service running?**
|
||||
```bash
|
||||
docker logs attune-sensor --tail 100
|
||||
```
|
||||
Look for: "Started monitoring trigger instances" or "Timer trigger fired"
|
||||
|
||||
**Check 2: Are events being created?**
|
||||
```bash
|
||||
curl -H "Authorization: Bearer $TOKEN" \
|
||||
http://localhost:8080/api/v1/events?limit=10 | jq '.data | length'
|
||||
```
|
||||
|
||||
**Check 3: Are enforcements being created?**
|
||||
```bash
|
||||
curl -H "Authorization: Bearer $TOKEN" \
|
||||
http://localhost:8080/api/v1/enforcements?limit=10 | jq '.data | length'
|
||||
```
|
||||
|
||||
**Check 4: Is the rule enabled?**
|
||||
```bash
|
||||
curl -H "Authorization: Bearer $TOKEN" \
|
||||
http://localhost:8080/api/v1/rules/test.timer_echo | jq '.data.enabled'
|
||||
```
|
||||
|
||||
### Executions Failed
|
||||
|
||||
**Check worker logs for errors:**
|
||||
```bash
|
||||
docker logs attune-worker --tail 100 | grep -i "error\|failed"
|
||||
```
|
||||
|
||||
**Check execution details:**
|
||||
```bash
|
||||
EXEC_ID=$(curl -s -H "Authorization: Bearer $TOKEN" \
|
||||
http://localhost:8080/api/v1/executions?limit=1 | jq -r '.data[0].id')
|
||||
|
||||
curl -H "Authorization: Bearer $TOKEN" \
|
||||
http://localhost:8080/api/v1/executions/$EXEC_ID | jq '.data'
|
||||
```
|
||||
|
||||
**Common issues:**
|
||||
- Runtime not detected: Check worker startup logs for "Runtime detected: Shell"
|
||||
- Action script not found: Verify packs mounted at `/opt/attune/packs` in worker container
|
||||
- Permission denied: Check file permissions on `packs/core/actions/echo.sh`
|
||||
|
||||
### Runtime Not Detected
|
||||
|
||||
**Check runtime configuration in database:**
|
||||
```bash
|
||||
docker exec -it postgres psql -U attune -d attune \
|
||||
-c "SELECT name, enabled, distributions FROM attune.runtime WHERE name ILIKE '%shell%';"
|
||||
```
|
||||
|
||||
**Check worker configuration:**
|
||||
```bash
|
||||
docker exec -it attune-worker env | grep ATTUNE
|
||||
```
|
||||
|
||||
**Verify Shell runtime verification:**
|
||||
```bash
|
||||
# This should succeed on the worker container
|
||||
docker exec -it attune-worker /bin/bash -c "echo 'Runtime test'"
|
||||
```
|
||||
|
||||
## Configuration Files
|
||||
|
||||
**Docker config:** `config.docker.yaml`
|
||||
- Database: `postgresql://attune:attune@postgres:5432/attune`
|
||||
- Message Queue: `amqp://attune:attune@rabbitmq:5672`
|
||||
- Packs: `/opt/attune/packs`
|
||||
- Schema: `attune`
|
||||
|
||||
**Core pack location (in containers):**
|
||||
- Actions: `/opt/attune/packs/core/actions/`
|
||||
- Triggers: `/opt/attune/packs/core/triggers/`
|
||||
- Sensors: `/opt/attune/packs/core/sensors/`
|
||||
|
||||
## Success Criteria
|
||||
|
||||
✅ **Shell runtime detected** by worker service
|
||||
✅ **Core pack loaded** with echo action and timer trigger
|
||||
✅ **Events generated** by sensor every second
|
||||
✅ **Enforcements created** by rule matching
|
||||
✅ **Executions scheduled** by executor service
|
||||
✅ **Actions executed** by worker service using Shell runtime
|
||||
✅ **Executions succeed** with "Hello, World!" output
|
||||
|
||||
## Next Steps
|
||||
|
||||
After verifying the happy path:
|
||||
|
||||
1. **Test Python runtime**: Create a Python action and verify runtime detection
|
||||
2. **Test Node.js runtime**: Create a Node.js action and verify runtime detection
|
||||
3. **Test workflows**: Chain multiple actions together
|
||||
4. **Test pack environments**: Verify pack-specific dependency isolation
|
||||
5. **Test error handling**: Trigger failures and verify retry logic
|
||||
6. **Test concurrency**: Create multiple rules firing simultaneously
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Unified Runtime Detection](../QUICKREF-unified-runtime-detection.md)
|
||||
- [Pack Runtime Environments](../pack-runtime-environments.md)
|
||||
- [Worker Service Architecture](../architecture/worker-service.md)
|
||||
- [Sensor Service Architecture](../architecture/sensor-service.md)
|
||||
- [Timer Sensor Quickstart](./timer-sensor-quickstart.md)
|
||||
Reference in New Issue
Block a user