re-uploading work
This commit is contained in:
361
packs/core/README.md
Normal file
361
packs/core/README.md
Normal file
@@ -0,0 +1,361 @@
|
||||
# Attune Core Pack
|
||||
|
||||
The **Core Pack** is the foundational system pack for Attune, providing essential automation components including timer triggers, HTTP utilities, and basic shell actions.
|
||||
|
||||
## Overview
|
||||
|
||||
The core pack is automatically installed with Attune and provides the building blocks for creating automation workflows. It includes:
|
||||
|
||||
- **Timer Triggers**: Interval-based, cron-based, and one-shot datetime timers
|
||||
- **HTTP Actions**: Make HTTP requests to external APIs
|
||||
- **Shell Actions**: Execute basic shell commands (echo, sleep, noop)
|
||||
- **Built-in Sensors**: System sensors for monitoring time-based events
|
||||
|
||||
## Components
|
||||
|
||||
### Actions
|
||||
|
||||
#### `core.echo`
|
||||
Outputs a message to stdout.
|
||||
|
||||
**Parameters:**
|
||||
- `message` (string, required): Message to echo
|
||||
- `uppercase` (boolean, optional): Convert message to uppercase
|
||||
|
||||
**Example:**
|
||||
```yaml
|
||||
action: core.echo
|
||||
parameters:
|
||||
message: "Hello, Attune!"
|
||||
uppercase: false
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### `core.sleep`
|
||||
Pauses execution for a specified duration.
|
||||
|
||||
**Parameters:**
|
||||
- `seconds` (integer, required): Number of seconds to sleep (0-3600)
|
||||
- `message` (string, optional): Optional message to display before sleeping
|
||||
|
||||
**Example:**
|
||||
```yaml
|
||||
action: core.sleep
|
||||
parameters:
|
||||
seconds: 30
|
||||
message: "Waiting 30 seconds..."
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### `core.noop`
|
||||
Does nothing - useful for testing and placeholder workflows.
|
||||
|
||||
**Parameters:**
|
||||
- `message` (string, optional): Optional message to log
|
||||
- `exit_code` (integer, optional): Exit code to return (default: 0)
|
||||
|
||||
**Example:**
|
||||
```yaml
|
||||
action: core.noop
|
||||
parameters:
|
||||
message: "Testing workflow structure"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### `core.http_request`
|
||||
Make HTTP requests to external APIs with full control over headers, authentication, and request body.
|
||||
|
||||
**Parameters:**
|
||||
- `url` (string, required): URL to send the request to
|
||||
- `method` (string, optional): HTTP method (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS)
|
||||
- `headers` (object, optional): HTTP headers as key-value pairs
|
||||
- `body` (string, optional): Request body for POST/PUT/PATCH
|
||||
- `json_body` (object, optional): JSON request body (alternative to `body`)
|
||||
- `query_params` (object, optional): URL query parameters
|
||||
- `timeout` (integer, optional): Request timeout in seconds (default: 30)
|
||||
- `verify_ssl` (boolean, optional): Verify SSL certificates (default: true)
|
||||
- `auth_type` (string, optional): Authentication type (none, basic, bearer)
|
||||
- `auth_username` (string, optional): Username for basic auth
|
||||
- `auth_password` (string, secret, optional): Password for basic auth
|
||||
- `auth_token` (string, secret, optional): Bearer token
|
||||
- `follow_redirects` (boolean, optional): Follow HTTP redirects (default: true)
|
||||
- `max_redirects` (integer, optional): Maximum redirects to follow (default: 10)
|
||||
|
||||
**Output:**
|
||||
- `status_code` (integer): HTTP status code
|
||||
- `headers` (object): Response headers
|
||||
- `body` (string): Response body as text
|
||||
- `json` (object): Parsed JSON response (if applicable)
|
||||
- `elapsed_ms` (integer): Request duration in milliseconds
|
||||
- `url` (string): Final URL after redirects
|
||||
- `success` (boolean): Whether request was successful (2xx status)
|
||||
|
||||
**Example:**
|
||||
```yaml
|
||||
action: core.http_request
|
||||
parameters:
|
||||
url: "https://api.example.com/users"
|
||||
method: "POST"
|
||||
json_body:
|
||||
name: "John Doe"
|
||||
email: "john@example.com"
|
||||
headers:
|
||||
Content-Type: "application/json"
|
||||
auth_type: "bearer"
|
||||
auth_token: "${secret:api_token}"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Triggers
|
||||
|
||||
#### `core.intervaltimer`
|
||||
Fires at regular intervals based on time unit and interval.
|
||||
|
||||
**Parameters:**
|
||||
- `unit` (string, required): Time unit (seconds, minutes, hours)
|
||||
- `interval` (integer, required): Number of time units between triggers
|
||||
|
||||
**Payload:**
|
||||
- `type`: "interval"
|
||||
- `interval_seconds`: Total interval in seconds
|
||||
- `fired_at`: ISO 8601 timestamp
|
||||
- `execution_count`: Number of times fired
|
||||
- `sensor_ref`: Reference to the sensor
|
||||
|
||||
**Example:**
|
||||
```yaml
|
||||
trigger: core.intervaltimer
|
||||
config:
|
||||
unit: "minutes"
|
||||
interval: 5
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### `core.crontimer`
|
||||
Fires based on cron schedule expressions.
|
||||
|
||||
**Parameters:**
|
||||
- `expression` (string, required): Cron expression (6 fields: second minute hour day month weekday)
|
||||
- `timezone` (string, optional): Timezone (default: UTC)
|
||||
- `description` (string, optional): Human-readable schedule description
|
||||
|
||||
**Payload:**
|
||||
- `type`: "cron"
|
||||
- `fired_at`: ISO 8601 timestamp
|
||||
- `scheduled_at`: When trigger was scheduled to fire
|
||||
- `expression`: The cron expression
|
||||
- `timezone`: Timezone used
|
||||
- `next_fire_at`: Next scheduled fire time
|
||||
- `execution_count`: Number of times fired
|
||||
- `sensor_ref`: Reference to the sensor
|
||||
|
||||
**Cron Format:**
|
||||
```
|
||||
┌───────── second (0-59)
|
||||
│ ┌─────── minute (0-59)
|
||||
│ │ ┌───── hour (0-23)
|
||||
│ │ │ ┌─── day of month (1-31)
|
||||
│ │ │ │ ┌─ month (1-12)
|
||||
│ │ │ │ │ ┌ day of week (0-6, 0=Sunday)
|
||||
│ │ │ │ │ │
|
||||
* * * * * *
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
- `0 0 * * * *` - Every hour
|
||||
- `0 0 0 * * *` - Every day at midnight
|
||||
- `0 */15 * * * *` - Every 15 minutes
|
||||
- `0 30 8 * * 1-5` - 8:30 AM on weekdays
|
||||
|
||||
---
|
||||
|
||||
#### `core.datetimetimer`
|
||||
Fires once at a specific date and time.
|
||||
|
||||
**Parameters:**
|
||||
- `fire_at` (string, required): ISO 8601 timestamp when timer should fire
|
||||
- `timezone` (string, optional): Timezone (default: UTC)
|
||||
- `description` (string, optional): Human-readable description
|
||||
|
||||
**Payload:**
|
||||
- `type`: "one_shot"
|
||||
- `fire_at`: Scheduled fire time
|
||||
- `fired_at`: Actual fire time
|
||||
- `timezone`: Timezone used
|
||||
- `delay_ms`: Delay between scheduled and actual fire time
|
||||
- `sensor_ref`: Reference to the sensor
|
||||
|
||||
**Example:**
|
||||
```yaml
|
||||
trigger: core.datetimetimer
|
||||
config:
|
||||
fire_at: "2024-12-31T23:59:59Z"
|
||||
description: "New Year's countdown"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Sensors
|
||||
|
||||
#### `core.interval_timer_sensor`
|
||||
Built-in sensor that monitors time and fires interval timer triggers.
|
||||
|
||||
**Configuration:**
|
||||
- `check_interval_seconds` (integer, optional): How often to check triggers (default: 1)
|
||||
|
||||
This sensor automatically runs as part of the Attune sensor service and manages all interval timer trigger instances.
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
The core pack supports the following configuration options:
|
||||
|
||||
```yaml
|
||||
# config.yaml
|
||||
packs:
|
||||
core:
|
||||
max_action_timeout: 300 # Maximum action timeout in seconds
|
||||
enable_debug_logging: false # Enable debug logging
|
||||
```
|
||||
|
||||
## Dependencies
|
||||
|
||||
### Python Dependencies
|
||||
- `requests>=2.28.0` - For HTTP request action
|
||||
- `croniter>=1.4.0` - For cron timer parsing (future)
|
||||
|
||||
### Runtime Dependencies
|
||||
- Shell (bash/sh) - For shell-based actions
|
||||
- Python 3.8+ - For Python-based actions and sensors
|
||||
|
||||
## Installation
|
||||
|
||||
The core pack is automatically installed with Attune. No manual installation is required.
|
||||
|
||||
To verify the core pack is loaded:
|
||||
|
||||
```bash
|
||||
# Using CLI
|
||||
attune pack list | grep core
|
||||
|
||||
# Using API
|
||||
curl http://localhost:8080/api/v1/packs/core
|
||||
```
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Example 1: Echo Every 10 Seconds
|
||||
|
||||
Create a rule that echoes "Hello, World!" every 10 seconds:
|
||||
|
||||
```yaml
|
||||
ref: core.hello_world_rule
|
||||
trigger: core.intervaltimer
|
||||
trigger_config:
|
||||
unit: "seconds"
|
||||
interval: 10
|
||||
action: core.echo
|
||||
action_params:
|
||||
message: "Hello, World!"
|
||||
uppercase: false
|
||||
```
|
||||
|
||||
### Example 2: HTTP Health Check Every 5 Minutes
|
||||
|
||||
Monitor an API endpoint every 5 minutes:
|
||||
|
||||
```yaml
|
||||
ref: core.health_check_rule
|
||||
trigger: core.intervaltimer
|
||||
trigger_config:
|
||||
unit: "minutes"
|
||||
interval: 5
|
||||
action: core.http_request
|
||||
action_params:
|
||||
url: "https://api.example.com/health"
|
||||
method: "GET"
|
||||
timeout: 10
|
||||
```
|
||||
|
||||
### Example 3: Daily Report at Midnight
|
||||
|
||||
Generate a report every day at midnight:
|
||||
|
||||
```yaml
|
||||
ref: core.daily_report_rule
|
||||
trigger: core.crontimer
|
||||
trigger_config:
|
||||
expression: "0 0 0 * * *"
|
||||
timezone: "UTC"
|
||||
description: "Daily at midnight"
|
||||
action: core.http_request
|
||||
action_params:
|
||||
url: "https://api.example.com/reports/generate"
|
||||
method: "POST"
|
||||
```
|
||||
|
||||
### Example 4: One-Time Reminder
|
||||
|
||||
Set a one-time reminder for a specific date and time:
|
||||
|
||||
```yaml
|
||||
ref: core.meeting_reminder
|
||||
trigger: core.datetimetimer
|
||||
trigger_config:
|
||||
fire_at: "2024-06-15T14:00:00Z"
|
||||
description: "Team meeting reminder"
|
||||
action: core.echo
|
||||
action_params:
|
||||
message: "Team meeting starts in 15 minutes!"
|
||||
```
|
||||
|
||||
## Development
|
||||
|
||||
### Adding New Actions
|
||||
|
||||
1. Create action metadata file: `actions/<action_name>.yaml`
|
||||
2. Create action implementation: `actions/<action_name>.sh` or `actions/<action_name>.py`
|
||||
3. Make script executable: `chmod +x actions/<action_name>.sh`
|
||||
4. Update pack manifest if needed
|
||||
5. Test the action
|
||||
|
||||
### Testing Actions Locally
|
||||
|
||||
Test actions directly by setting environment variables:
|
||||
|
||||
```bash
|
||||
# Test echo action
|
||||
export ATTUNE_ACTION_MESSAGE="Test message"
|
||||
export ATTUNE_ACTION_UPPERCASE=true
|
||||
./actions/echo.sh
|
||||
|
||||
# Test HTTP request action
|
||||
export ATTUNE_ACTION_URL="https://httpbin.org/get"
|
||||
export ATTUNE_ACTION_METHOD="GET"
|
||||
python3 actions/http_request.py
|
||||
```
|
||||
|
||||
## Contributing
|
||||
|
||||
The core pack is part of the Attune project. Contributions are welcome!
|
||||
|
||||
1. Follow the existing code style and structure
|
||||
2. Add tests for new actions/sensors
|
||||
3. Update documentation
|
||||
4. Submit a pull request
|
||||
|
||||
## License
|
||||
|
||||
The core pack is licensed under the same license as Attune.
|
||||
|
||||
## Support
|
||||
|
||||
- Documentation: https://docs.attune.io/packs/core
|
||||
- Issues: https://github.com/attune-io/attune/issues
|
||||
- Discussions: https://github.com/attune-io/attune/discussions
|
||||
Reference in New Issue
Block a user