reqon-dsl 0.2.0 → 0.3.0

package/docusaurus/docs/scheduling/cron.md

@@ -1,305 +0,0 @@
----
-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

@@ -1,317 +0,0 @@
----
-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
-}
-```