attune/docs/guides/QUICKREF-timer-happy-path.md

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:

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

docker-compose up -d
docker-compose ps  # Verify all services are running

2. Check Runtime Detection

# 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

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

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

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:

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

# 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

# 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?

docker logs attune-sensor --tail 100

Look for: "Started monitoring trigger instances" or "Timer trigger fired"

Check 2: Are events being created?

curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8080/api/v1/events?limit=10 | jq '.data | length'

Check 3: Are enforcements being created?

curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8080/api/v1/enforcements?limit=10 | jq '.data | length'

Check 4: Is the rule enabled?

curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8080/api/v1/rules/test.timer_echo | jq '.data.enabled'

Executions Failed

Check worker logs for errors:

docker logs attune-worker --tail 100 | grep -i "error\|failed"

Check execution details:

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:

docker exec -it postgres psql -U attune -d attune \
  -c "SELECT name, enabled, distributions FROM attune.runtime WHERE name ILIKE '%shell%';"

Check worker configuration:

docker exec -it attune-worker env | grep ATTUNE

Verify Shell runtime verification:

# 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
• Pack Runtime Environments
• Worker Service Architecture
• Sensor Service Architecture
• Timer Sensor Quickstart