Advanced Topics

Performance Optimization

Field Access Optimization

The system caches API responses per-torrent to minimize calls:

# First access to trackers.url: API call made and cached
if torrent["trackers.url"] contains "example.com":
    ...

# Second access to trackers.url: Uses cached data (no API call)
if torrent["trackers.url"] contains "private":
    ...

Best practices:

1. Access fields in order of expense:

   # Check cheap fields first
   all:
     - field: info.category    # Free
       operator: "=="
       value: "Movies"
     - field: files.name        # Expensive, but only if category matches
       operator: matches
       value: '.*\.mkv$'

2. Reuse field references:

   # BAD: Multiple string operations
   any:
     - field: info.name
       operator: contains
       value: "1080p"
     - field: info.name
       operator: contains
       value: "2160p"
   
   # GOOD: Single regex
   any:
     - field: info.name
       operator: matches
       value: '(?i).*(1080p|2160p).*'

Rule Ordering

Rules execute top-to-bottom. Order matters for performance:

# GOOD: Specific rules first, then general
- name: "High-priority: Private trackers"
  stop_on_match: true
  conditions:
    all:
      - field: trackers.url
        operator: contains
        value: "privatehd.to"

- name: "General cleanup"
  conditions:
    # This only runs if private tracker rule didn't match

Security Best Practices

Credential Management

Never hardcode credentials in config files:

# BAD
qbittorrent:
  username: admin
  password: MyPassword123

# GOOD
qbittorrent:
  username: ${QB_USERNAME}
  password: ${QB_PASSWORD}

Set environment variables:

export QB_USERNAME="admin"
export QB_PASSWORD="secure_password"

File Permissions

Protect config files containing credentials:

# Restrict access to config files
chmod 600 ~/.config/qbt-rules/config.yml
chown $USER:$USER ~/.config/qbt-rules/config.yml

Network Security

For qBittorrent webhook integration:

1. Restrict command execution: Ensure qBittorrent process can only execute qbt-rules
2. Validate config access: Ensure qBittorrent can only access its own config directory
3. Use environment variables: Pass credentials via environment, not config files
4. Monitor logs: Check qBittorrent logs for unauthorized webhook executions

Integration Patterns

Integration with Sonarr/Radarr

Scenario: Auto-categorize torrents added by Sonarr/Radarr

1. Configure qBittorrent webhook:

   • Open qBittorrent → Tools → Options → Downloads
   • Set "Run external program on torrent added":

   qbt-rules --trigger on_added --hash "%I"

2. Create categorization rules:

   - name: "Categorize Sonarr downloads"
     conditions:
       trigger: on_added
       all:
         - field: info.category
           operator: "=="
           value: "tv-sonarr"
     actions:
       - type: add_tag
         params:
           tag: "sonarr"

Integration with External Scripts

Scenario: Run custom script after specific condition

While the system doesn't directly support script execution, you can:

1. Tag torrents with automation rules
2. Monitor tags with external script:

   #!/bin/bash
   # Watch for "process-me" tag
   TAGGED=$(curl -s http://localhost:8080/api/v2/torrents/info | \
     jq -r '.[] | select(.tags | contains("process-me")) | .hash')
   
   for hash in $TAGGED; do
     # Run your custom logic
     ./process-torrent.sh "$hash"
   done

Integration with Notification Services

Scenario: Send notifications when rules match

Implement custom action type (requires code modification):

# lib/actions.py
def send_notification(torrent, params):
    import requests
    message = params.get("message", "Rule matched")
    requests.post("https://ntfy.sh/qbittorrent",
                  data=message.encode('utf-8'))

Then use in rules:

actions:
  - type: send_notification
    params:
      message: "Torrent {info.name} completed!"

Extending the System

Adding Custom Operators

Edit src/qbt_rules/engine.py to add new comparison operators:

def evaluate_condition(torrent, condition):
    # ... existing code ...

    elif operator == "starts_with":
        return str(field_value).startswith(str(value))
    elif operator == "ends_with":
        return str(field_value).endswith(str(value))

Then use in rules:

- field: info.name
  operator: starts_with
  value: "Ubuntu"

Note: If you extend the codebase, install in editable mode:

pip install -e .

Adding Custom Actions

Edit src/qbt_rules/actions.py:

def set_priority(api, torrent_hash, params):
    """Set torrent priority"""
    priority = params.get("priority", "normal")
    # Implement priority logic
    api.post(f"/api/v2/torrents/setPriority",
             data={"hashes": torrent_hash, "priority": priority})

Register in action mapping:

ACTION_MAP = {
    # ... existing actions ...
    "set_priority": set_priority,
}

Use in rules:

actions:
  - type: set_priority
    params:
      priority: "high"

Using Custom Triggers (v0.3.0+)

New in v0.3.0: Define custom trigger names without code changes!

Simply use --trigger with any name you want:

# Define custom triggers
qbt-rules --trigger hourly
qbt-rules --trigger weekend
qbt-rules --trigger low-bandwidth
qbt-rules --trigger maintenance

Then filter rules by your custom trigger:

- name: "Weekend high-bandwidth downloads"
  conditions:
    trigger: weekend
    all:
      - field: info.size
        operator: larger_than
        value: "50GB"
  actions:
    - type: force_start

- name: "Hourly cleanup"
  conditions:
    trigger: [hourly, manual]  # Runs on multiple triggers
    all:
      - field: info.ratio
        operator: ">="
        value: 2.0
  actions:
    - type: delete_torrent
      params:
        keep_files: true

Cron examples:

# Run hourly cleanup every hour
0 * * * * qbt-rules --trigger hourly

# Run weekend rules on Saturday/Sunday
0 0 * * 6,0 qbt-rules --trigger weekend

# Run maintenance at 3 AM
0 3 * * * qbt-rules --trigger maintenance

Scaling Strategies

Horizontal Scaling

Run multiple instances with different config directories:

Instance 1 - Categorization (runs frequently):

# Cron: Every 15 minutes
*/15 * * * * qbt-rules --trigger scheduled --config-dir /config/categorization

Instance 2 - Cleanup (runs daily):

# Cron: Daily at 3 AM
0 3 * * * qbt-rules --trigger scheduled --config-dir /config/cleanup

Instance 3 - Webhooks (qBittorrent configuration):

# In qBittorrent → Tools → Options → Downloads
qbt-rules --trigger on_added --hash "%I"
qbt-rules --trigger on_completed --hash "%I"

Batch Processing

For very large torrent libraries (10,000+), implement batch processing:

# Process torrents in chunks of 100
BATCH_SIZE = 100
for i in range(0, len(all_torrents), BATCH_SIZE):
    batch = all_torrents[i:i+BATCH_SIZE]
    engine.execute(api, batch)
    time.sleep(1)  # Rate limiting