reqon-dsl 0.2.0

package/docusaurus/docs/scheduling/cron.md

@@ -0,0 +1,305 @@
+---
+sidebar_position: 2
+---
+
+# Cron Expressions
+
+Reqon supports full cron expression syntax for precise scheduling.
+
+## Syntax
+
+```vague
+schedule: cron "minute hour day month weekday"
+```
+
+## Field Reference
+
+| Field | Values | Special Characters |
+|-------|--------|-------------------|
+| Minute | 0-59 | * , - / |
+| Hour | 0-23 | * , - / |
+| Day of Month | 1-31 | * , - / |
+| Month | 1-12 | * , - / |
+| Day of Week | 0-6 (0=Sunday) | * , - / |
+
+## Special Characters
+
+| Character | Meaning | Example |
+|-----------|---------|---------|
+| `*` | Any value | `* * * * *` = every minute |
+| `,` | Value list | `0,30 * * * *` = minute 0 and 30 |
+| `-` | Range | `0 9-17 * * *` = 9am to 5pm |
+| `/` | Step | `*/15 * * * *` = every 15 minutes |
+
+## Common Patterns
+
+### Every Minute
+
+```vague
+schedule: cron "* * * * *"
+```
+
+### Every Hour
+
+```vague
+// At minute 0
+schedule: cron "0 * * * *"
+```
+
+### Every N Minutes
+
+```vague
+// Every 5 minutes
+schedule: cron "*/5 * * * *"
+
+// Every 15 minutes
+schedule: cron "*/15 * * * *"
+
+// Every 30 minutes
+schedule: cron "*/30 * * * *"
+```
+
+### Every N Hours
+
+```vague
+// Every 2 hours
+schedule: cron "0 */2 * * *"
+
+// Every 6 hours
+schedule: cron "0 */6 * * *"
+
+// Every 12 hours
+schedule: cron "0 */12 * * *"
+```
+
+### Daily
+
+```vague
+// At midnight
+schedule: cron "0 0 * * *"
+
+// At 6am
+schedule: cron "0 6 * * *"
+
+// At 9am
+schedule: cron "0 9 * * *"
+
+// At 11pm
+schedule: cron "0 23 * * *"
+```
+
+### Multiple Times Per Day
+
+```vague
+// At 9am and 5pm
+schedule: cron "0 9,17 * * *"
+
+// At midnight, 8am, 4pm
+schedule: cron "0 0,8,16 * * *"
+```
+
+### Weekly
+
+```vague
+// Every Sunday at midnight
+schedule: cron "0 0 * * 0"
+
+// Every Monday at 9am
+schedule: cron "0 9 * * 1"
+
+// Every Friday at 5pm
+schedule: cron "0 17 * * 5"
+```
+
+### Weekdays Only
+
+```vague
+// Weekdays at 9am
+schedule: cron "0 9 * * 1-5"
+
+// Weekdays every hour during business hours
+schedule: cron "0 9-17 * * 1-5"
+```
+
+### Weekends Only
+
+```vague
+// Weekends at noon
+schedule: cron "0 12 * * 0,6"
+```
+
+### Monthly
+
+```vague
+// First of month at midnight
+schedule: cron "0 0 1 * *"
+
+// First of month at 6am
+schedule: cron "0 6 1 * *"
+
+// 15th of month at noon
+schedule: cron "0 12 15 * *"
+
+// Last day approach: run on 28th
+schedule: cron "0 0 28 * *"
+```
+
+### Quarterly
+
+```vague
+// First day of quarter at 6am
+schedule: cron "0 6 1 1,4,7,10 *"
+```
+
+### Yearly
+
+```vague
+// January 1st at midnight
+schedule: cron "0 0 1 1 *"
+
+// First Monday of year (approximate)
+schedule: cron "0 9 1-7 1 1"
+```
+
+## Complex Examples
+
+### Business Hours Only
+
+```vague
+// Every 30 minutes, 9am-5pm, weekdays
+schedule: cron "*/30 9-17 * * 1-5"
+```
+
+### Night Batch Jobs
+
+```vague
+// At 2am every day
+schedule: cron "0 2 * * *"
+```
+
+### Multiple Specific Times
+
+```vague
+// 8am, 12pm, 6pm every day
+schedule: cron "0 8,12,18 * * *"
+```
+
+### End of Month (Approximation)
+
+```vague
+// 28th of every month
+schedule: cron "0 0 28 * *"
+```
+
+## Timezone Handling
+
+Cron expressions use the system timezone by default.
+
+### Specify Timezone
+
+```vague
+mission TimezoneSync {
+  schedule: cron "0 9 * * *"
+  timezone: "America/New_York"
+}
+```
+
+### UTC
+
+```vague
+mission UTCSync {
+  schedule: cron "0 9 * * *"
+  timezone: "UTC"
+}
+```
+
+## Testing Cron Expressions
+
+### Dry Run
+
+```bash
+reqon ./mission.vague --dry-run
+# Shows: Next run at: 2024-01-20 09:00:00
+```
+
+### Validate Expression
+
+```bash
+reqon --validate-cron "0 9 * * *"
+# Valid cron expression
+# Next 5 runs:
+#   2024-01-20 09:00:00
+#   2024-01-21 09:00:00
+#   2024-01-22 09:00:00
+#   2024-01-23 09:00:00
+#   2024-01-24 09:00:00
+```
+
+## Best Practices
+
+### Avoid Midnight
+
+Many systems run jobs at midnight, causing load spikes:
+
+```vague
+// Instead of 0 0 * * *
+schedule: cron "0 3 * * *"  // 3am
+```
+
+### Spread Load
+
+Stagger related jobs:
+
+```vague
+mission SyncCustomers {
+  schedule: cron "0 * * * *"  // On the hour
+}
+
+mission SyncOrders {
+  schedule: cron "15 * * * *"  // 15 past
+}
+
+mission SyncProducts {
+  schedule: cron "30 * * * *"  // 30 past
+}
+```
+
+### Consider Execution Time
+
+Account for job duration:
+
+```vague
+// If job takes 10 minutes, don't schedule every 5
+schedule: cron "*/15 * * * *"  // Every 15 minutes
+
+// Or use skipIfRunning
+skipIfRunning: true
+```
+
+## Troubleshooting
+
+### Wrong Times
+
+Check timezone settings:
+
+```bash
+date  # System time
+TZ=UTC date  # UTC time
+```
+
+### Missed Runs
+
+If daemon was down, jobs don't backfill. Consider:
+
+```vague
+retryOnFailure: { maxAttempts: 3 }
+```
+
+### Expression Errors
+
+Validate syntax:
+
+```bash
+reqon --validate-cron "invalid"
+# Error: Invalid cron expression
+```

package/docusaurus/docs/scheduling/daemon-mode.md

@@ -0,0 +1,317 @@
+---
+sidebar_position: 4
+---
+
+# Daemon Mode
+
+Daemon mode runs Reqon as a long-running service, executing scheduled missions automatically.
+
+## Starting the Daemon
+
+```bash
+reqon ./missions/ --daemon
+```
+
+## How It Works
+
+1. Daemon loads all missions from the specified path
+2. Parses schedule configurations
+3. Runs missions according to their schedules
+4. Continues until stopped
+
+## Command Options
+
+```bash
+reqon ./missions/ --daemon [options]
+
+Options:
+  --auth <file>        Credentials file
+  --verbose            Enable detailed logging
+  --check-interval     How often to check schedules (default: 1000ms)
+```
+
+## Example Setup
+
+### Mission Files
+
+```
+missions/
+├── sync-customers.vague
+├── sync-orders.vague
+└── daily-report.vague
+```
+
+### sync-customers.vague
+
+```vague
+mission SyncCustomers {
+  schedule: every 15 minutes
+
+  source API { auth: bearer, base: "https://api.example.com" }
+  store customers: file("customers")
+
+  action Sync {
+    get "/customers" { since: lastSync }
+    store response -> customers { key: .id, upsert: true }
+  }
+
+  run Sync
+}
+```
+
+### Running
+
+```bash
+reqon ./missions/ --daemon --auth ./credentials.json --verbose
+```
+
+## Process Management
+
+### Foreground
+
+```bash
+reqon ./missions/ --daemon
+```
+
+Press Ctrl+C to stop.
+
+### Background (Linux)
+
+```bash
+nohup reqon ./missions/ --daemon > reqon.log 2>&1 &
+```
+
+### Systemd Service
+
+Create `/etc/systemd/system/reqon.service`:
+
+```ini
+[Unit]
+Description=Reqon Data Sync Daemon
+After=network.target
+
+[Service]
+Type=simple
+User=reqon
+WorkingDirectory=/opt/reqon
+ExecStart=/usr/bin/npx reqon ./missions/ --daemon --auth ./credentials.json
+Restart=on-failure
+RestartSec=10
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Enable and start:
+
+```bash
+sudo systemctl enable reqon
+sudo systemctl start reqon
+```
+
+### Docker
+
+Dockerfile:
+
+```dockerfile
+FROM node:20-alpine
+
+WORKDIR /app
+COPY package*.json ./
+RUN npm install
+
+COPY . .
+
+CMD ["npx", "reqon", "./missions/", "--daemon"]
+```
+
+docker-compose.yml:
+
+```yaml
+version: '3'
+services:
+  reqon:
+    build: .
+    volumes:
+      - ./missions:/app/missions
+      - ./credentials.json:/app/credentials.json
+      - reqon-data:/app/.vague-data
+    environment:
+      - NODE_ENV=production
+    restart: unless-stopped
+
+volumes:
+  reqon-data:
+```
+
+## Graceful Shutdown
+
+Reqon handles SIGINT and SIGTERM:
+
+1. Stops accepting new runs
+2. Waits for in-progress missions to complete
+3. Saves state
+4. Exits cleanly
+
+```bash
+# Graceful stop
+kill -TERM $(pgrep -f "reqon.*daemon")
+
+# Or with systemd
+systemctl stop reqon
+```
+
+## Health Checks
+
+### Status Endpoint
+
+Enable HTTP health endpoint:
+
+```bash
+reqon ./missions/ --daemon --health-port 8080
+```
+
+Check health:
+
+```bash
+curl http://localhost:8080/health
+# {"status":"ok","uptime":3600,"missionsLoaded":3}
+```
+
+### File-Based Health
+
+```vague
+mission HealthCheck {
+  schedule: every 1 minute
+
+  action Check {
+    store { status: "ok", timestamp: now() } -> health
+  }
+}
+```
+
+Monitor the health store file.
+
+## Logging
+
+### Log Levels
+
+```bash
+# Default logging
+reqon ./missions/ --daemon
+
+# Verbose logging
+reqon ./missions/ --daemon --verbose
+
+# Environment variable
+REQON_LOG_LEVEL=debug reqon ./missions/ --daemon
+```
+
+### Log Output
+
+```
+[2024-01-20 09:00:00] [INFO] Starting Reqon daemon
+[2024-01-20 09:00:00] [INFO] Loaded 3 missions
+[2024-01-20 09:00:00] [INFO] SyncCustomers: Next run at 09:15:00
+[2024-01-20 09:00:00] [INFO] SyncOrders: Next run at 09:05:00
+[2024-01-20 09:00:00] [INFO] DailyReport: Next run at 2024-01-21 00:00:00
+[2024-01-20 09:05:00] [INFO] SyncOrders: Starting run
+[2024-01-20 09:05:02] [INFO] SyncOrders: Completed (2.1s)
+```
+
+### Structured Logging
+
+```bash
+REQON_LOG_FORMAT=json reqon ./missions/ --daemon
+```
+
+```json
+{"timestamp":"2024-01-20T09:00:00Z","level":"info","message":"Starting run","mission":"SyncCustomers"}
+```
+
+## Monitoring
+
+### Metrics
+
+Export metrics with `--metrics-port`:
+
+```bash
+reqon ./missions/ --daemon --metrics-port 9090
+```
+
+Prometheus format:
+
+```
+# HELP reqon_mission_runs_total Total mission runs
+reqon_mission_runs_total{mission="SyncCustomers",status="success"} 142
+reqon_mission_runs_total{mission="SyncCustomers",status="failure"} 3
+
+# HELP reqon_mission_duration_seconds Mission run duration
+reqon_mission_duration_seconds{mission="SyncCustomers",quantile="0.5"} 2.1
+```
+
+### Alerting
+
+Create alerting rules:
+
+```yaml
+groups:
+  - name: reqon
+    rules:
+      - alert: ReqonMissionFailing
+        expr: rate(reqon_mission_runs_total{status="failure"}[5m]) > 0.1
+        for: 10m
+        labels:
+          severity: warning
+        annotations:
+          summary: "Mission {{ $labels.mission }} is failing"
+```
+
+## Best Practices
+
+### Use Separate Credentials
+
+```bash
+# Production credentials
+reqon ./missions/ --daemon --auth ./prod-credentials.json
+```
+
+### Run as Non-Root
+
+```bash
+# Create dedicated user
+useradd -r -s /bin/false reqon
+
+# Run as that user
+sudo -u reqon reqon ./missions/ --daemon
+```
+
+### Persistent Storage
+
+Ensure `.vague-data` is on persistent storage:
+
+```yaml
+volumes:
+  - /var/lib/reqon:/app/.vague-data
+```
+
+### Health Monitoring
+
+Always enable health checks:
+
+```bash
+reqon ./missions/ --daemon --health-port 8080
+```
+
+### Log Rotation
+
+```bash
+# Use logrotate
+/var/log/reqon/*.log {
+    daily
+    rotate 7
+    compress
+    missingok
+    notifempty
+}
+```