drasi-reaction-http 0.1.12

# HTTP Reaction

HTTP Reaction is a plugin component for Drasi that sends HTTP webhooks when query results change. It enables real-time notifications to external HTTP endpoints whenever continuous queries detect additions, updates, or deletions in the result set.

## Overview

The HTTP Reaction component monitors continuous query results and automatically sends HTTP requests to configured endpoints when data changes occur. It supports:

- **Multiple HTTP Methods**: GET, POST, PUT, DELETE, PATCH
- **Flexible Routing**: Different endpoints for different queries and operation types
- **Template-Based Requests**: Handlebars templates for dynamic URL, body, and header generation
- **Authentication**: Built-in Bearer token authentication support
- **Operation-Specific Handling**: Separate configurations for ADD, UPDATE, and DELETE operations
- **Priority Queue Processing**: Processes changes in timestamp order to ensure correct sequencing

## Use Cases

- **Real-time Notifications**: Alert external systems when data changes
- **Workflow Automation**: Trigger automated workflows based on query result changes
- **Data Synchronization**: Keep external systems in sync with Drasi query results
- **Event-Driven Architecture**: Integrate Drasi with event-driven applications
- **Monitoring and Alerting**: Send alerts when specific conditions are detected

## Configuration

### Builder Pattern (Recommended)

The builder pattern provides a fluent API for programmatic configuration:

```rust
use drasi_reaction_http::HttpReaction;

let reaction = HttpReaction::builder("my-http-reaction")
    .with_base_url("https://api.example.com")
    .with_token("your-secret-token")
    .with_timeout_ms(10000)
    .with_query("temperature-alerts")
    .with_query("pressure-alerts")
    .build()?;
```

### Config Struct Approach

For more complex configurations with custom routing:

```rust
use drasi_reaction_http::{HttpReaction, HttpReactionConfig, QueryConfig, CallSpec};
use std::collections::HashMap;

let mut routes = HashMap::new();
routes.insert("temperature-alerts".to_string(), QueryConfig {
    added: Some(CallSpec {
        url: "/alerts/temperature/new".to_string(),
        method: "POST".to_string(),
        body: r#"{"alert": "High temperature", "data": {{json after}}}"#.to_string(),
        headers: HashMap::new(),
    }),
    updated: Some(CallSpec {
        url: "/alerts/temperature/update".to_string(),
        method: "PUT".to_string(),
        body: r#"{"before": {{json before}}, "after": {{json after}}}"#.to_string(),
        headers: HashMap::new(),
    }),
    deleted: Some(CallSpec {
        url: "/alerts/temperature/resolved".to_string(),
        method: "DELETE".to_string(),
        body: String::new(),
        headers: HashMap::new(),
    }),
});

let config = HttpReactionConfig {
    base_url: "https://api.example.com".to_string(),
    token: Some("your-secret-token".to_string()),
    timeout_ms: 5000,
    routes,
};

let reaction = HttpReaction::new(
    "my-http-reaction",
    vec!["temperature-alerts".to_string()],
    config,
);
```

## Configuration Options

### HttpReactionConfig

| Name | Description | Type | Default | Required |
|------|-------------|------|---------|----------|
| `base_url` | Base URL for all HTTP requests. Can be overridden with absolute URLs in CallSpec. | String | `"http://localhost"` | No |
| `token` | Bearer token for authentication. Automatically adds `Authorization: Bearer <token>` header. | Option\<String\> | None | No |
| `timeout_ms` | Request timeout in milliseconds. | u64 | 5000 | No |
| `routes` | Query-specific routing configurations. Keys are query IDs. | HashMap\<String, QueryConfig\> | Empty | No |

### QueryConfig

Defines HTTP call specifications for each operation type within a query.

| Name | Description | Type | Required |
|------|-------------|------|----------|
| `added` | HTTP call specification for ADD operations (new rows). | Option\<CallSpec\> | No |
| `updated` | HTTP call specification for UPDATE operations (modified rows). | Option\<CallSpec\> | No |
| `deleted` | HTTP call specification for DELETE operations (removed rows). | Option\<CallSpec\> | No |

### CallSpec

Specification for an individual HTTP call.

| Name | Description | Type | Default | Required |
|------|-------------|------|---------|----------|
| `url` | URL path (appended to base_url) or absolute URL. Supports Handlebars templates. | String | - | Yes |
| `method` | HTTP method: GET, POST, PUT, DELETE, or PATCH (case-insensitive). | String | - | Yes |
| `body` | Request body as a Handlebars template. If empty, sends raw JSON data. | String | Empty | No |
| `headers` | Additional HTTP headers. Values support Handlebars templates. | HashMap\<String, String\> | Empty | No |

### Builder Methods

| Method | Description | Parameters |
|--------|-------------|------------|
| `builder(id)` | Create a new builder | `id: impl Into<String>` |
| `with_base_url(url)` | Set the base URL | `url: impl Into<String>` |
| `with_token(token)` | Set authentication token | `token: impl Into<String>` |
| `with_timeout_ms(ms)` | Set request timeout | `ms: u64` |
| `with_query(id)` | Add a query to subscribe to | `id: impl Into<String>` |
| `with_queries(ids)` | Set all queries to subscribe to | `ids: Vec<String>` |
| `with_route(id, config)` | Add a route configuration | `id: impl Into<String>`, `config: QueryConfig` |
| `with_priority_queue_capacity(capacity)` | Set priority queue capacity | `capacity: usize` |
| `with_auto_start(auto_start)` | Enable/disable auto-start | `auto_start: bool` |
| `build()` | Build the HttpReaction instance | Returns `anyhow::Result<HttpReaction>` |

## Output Schema

The HTTP Reaction sends JSON payloads to configured endpoints. The exact format depends on whether a custom body template is specified.

### Default Payload Format

When no custom body template is provided, the reaction sends the raw data:

**ADD Operation:**
```json
{
  "type": "ADD",
  "data": {
    "field1": "value1",
    "field2": "value2"
  }
}
```

**UPDATE Operation:**
```json
{
  "type": "UPDATE",
  "before": {
    "field1": "old_value1",
    "field2": "old_value2"
  },
  "after": {
    "field1": "new_value1",
    "field2": "new_value2"
  },
  "data": {
    "field1": "new_value1",
    "field2": "new_value2"
  }
}
```

**DELETE Operation:**
```json
{
  "type": "DELETE",
  "data": {
    "field1": "value1",
    "field2": "value2"
  }
}
```

### Template Variables

When using Handlebars templates in the body, the following variables are available:

| Variable | Description | Available Operations |
|----------|-------------|---------------------|
| `after` | The new/current state of the data | ADD, UPDATE |
| `before` | The previous state of the data | UPDATE, DELETE |
| `data` | The data field (equivalent to `after` for ADD/UPDATE) | UPDATE |
| `query_name` | The ID of the query that triggered the change | ALL |
| `operation` | The operation type: "ADD", "UPDATE", or "DELETE" | ALL |

### HTTP Request Details

**Headers:**
- `Content-Type: application/json` (always set)
- `Authorization: Bearer <token>` (if token is configured)
- Any custom headers defined in CallSpec

**URL Construction:**
- If CallSpec.url starts with `http://` or `https://`, it's used as-is
- Otherwise, it's appended to the base_url: `{base_url}{CallSpec.url}`

## Usage Examples

### Example 1: Basic Webhook

Simple webhook that POSTs all changes to a single endpoint:

```rust
use drasi_reaction_http::HttpReaction;

let reaction = HttpReaction::builder("webhook-reaction")
    .with_base_url("https://webhook.site/your-unique-id")
    .with_query("my-query")
    .build()?;
```

This uses the default configuration which sends all ADD, UPDATE, and DELETE operations to `/changes/my-query`.

### Example 2: Authenticated API Integration

Send changes to an authenticated API with custom timeout:

```rust
use drasi_reaction_http::HttpReaction;

let reaction = HttpReaction::builder("api-integration")
    .with_base_url("https://api.myservice.com")
    .with_token("sk_live_abc123def456")
    .with_timeout_ms(30000)  // 30 second timeout
    .with_queries(vec![
        "user-registrations".to_string(),
        "order-updates".to_string(),
    ])
    .build()?;
```

### Example 3: Custom Routes with Templates

Different endpoints for different operations with custom payloads:

```rust
use drasi_reaction_http::{HttpReaction, HttpReactionConfig, QueryConfig, CallSpec};
use std::collections::HashMap;

let mut routes = HashMap::new();
routes.insert("sensor-alerts".to_string(), QueryConfig {
    added: Some(CallSpec {
        url: "/alerts".to_string(),
        method: "POST".to_string(),
        body: r#"{
            "type": "alert",
            "severity": "high",
            "sensor_id": "{{after.sensor_id}}",
            "temperature": {{after.temperature}},
            "timestamp": "{{after.timestamp}}"
        }"#.to_string(),
        headers: HashMap::new(),
    }),
    updated: Some(CallSpec {
        url: "/alerts/{{after.alert_id}}".to_string(),
        method: "PUT".to_string(),
        body: r#"{
            "sensor_id": "{{after.sensor_id}}",
            "temperature": {{after.temperature}},
            "previous_temperature": {{before.temperature}}
        }"#.to_string(),
        headers: HashMap::new(),
    }),
    deleted: Some(CallSpec {
        url: "/alerts/{{before.alert_id}}".to_string(),
        method: "DELETE".to_string(),
        body: String::new(),
        headers: HashMap::new(),
    }),
});

let config = HttpReactionConfig {
    base_url: "https://monitoring.example.com".to_string(),
    token: Some("api-key-xyz".to_string()),
    timeout_ms: 10000,
    routes,
};

let reaction = HttpReaction::new("sensor-monitor", vec!["sensor-alerts".to_string()], config);
```

### Example 4: Using the json Helper

The `json` Handlebars helper serializes complex objects:

```rust
use drasi_reaction_http::{QueryConfig, CallSpec};
use std::collections::HashMap;

let call_spec = CallSpec {
    url: "/webhook".to_string(),
    method: "POST".to_string(),
    body: r#"{
        "event": "{{operation}}",
        "query": "{{query_name}}",
        "data": {{json after}}
    }"#.to_string(),
    headers: HashMap::new(),
};
```

This ensures the entire `after` object is properly JSON-serialized.

### Example 5: Custom Headers

Add custom headers with templating:

```rust
use drasi_reaction_http::{CallSpec};
use std::collections::HashMap;

let mut headers = HashMap::new();
headers.insert("X-Event-Type".to_string(), "{{operation}}".to_string());
headers.insert("X-Query-ID".to_string(), "{{query_name}}".to_string());
headers.insert("X-Custom-Header".to_string(), "static-value".to_string());

let call_spec = CallSpec {
    url: "/events".to_string(),
    method: "POST".to_string(),
    body: r#"{{json after}}"#.to_string(),
    headers,
};
```

### Example 6: Integration with DrasiLib

Full example showing integration with DrasiLib:

```rust
use drasi_lib::DrasiLib;
use drasi_reaction_http::HttpReaction;

// Create Drasi instance
let drasi = DrasiLib::new("my-app").await?;

// Create and add HTTP reaction
let reaction = HttpReaction::builder("webhook")
    .with_base_url("https://api.example.com")
    .with_token("secret-token")
    .with_query("my-continuous-query")
    .build()?;

drasi.add_reaction(reaction).await?;

// Start the reaction
drasi.start_reaction("webhook").await?;
```

## Advanced Features

### Priority Queue Processing

The HTTP Reaction uses a priority queue to process changes in timestamp order. This ensures that changes are sent to webhooks in the correct sequence, even if they arrive out of order.

You can customize the priority queue capacity:

```rust
let reaction = HttpReaction::builder("my-reaction")
    .with_base_url("https://api.example.com")
    .with_priority_queue_capacity(1000)  // Custom capacity
    .build()?;
```

### Default Routing Behavior

If no route configuration is provided for a query, the HTTP Reaction uses a default configuration that:
- POSTs all ADD operations to `/changes/{query_id}`
- POSTs all UPDATE operations to `/changes/{query_id}`
- POSTs all DELETE operations to `/changes/{query_id}`

This allows you to quickly set up basic webhooks without detailed configuration.

### Query ID Matching

The HTTP Reaction supports flexible query ID matching:
- Exact match: `"my-query"` matches query ID `"my-query"`
- Suffix match: If query ID is `"source.my-query"`, it will match routes for `"my-query"`

This is useful when queries are namespaced by source.

### Error Handling

The HTTP Reaction logs errors but continues processing:
- Failed HTTP requests are logged as warnings with status code and response body
- Processing errors are logged as errors but don't stop the reaction
- The reaction continues processing subsequent changes even if individual requests fail

## Performance Considerations

- **Timeout Configuration**: Set appropriate timeouts based on your endpoint's expected response time
- **Priority Queue Capacity**: Adjust based on expected change volume and processing speed
- **Concurrent Processing**: The reaction processes changes sequentially within each query to maintain order
- **HTTP Client**: Uses a shared reqwest client with connection pooling for efficiency

## Dependencies

The HTTP Reaction requires the following dependencies:

- `drasi-lib` - Core Drasi library for plugin integration
- `reqwest` - HTTP client library
- `handlebars` - Template engine for dynamic content
- `serde` / `serde_json` - JSON serialization
- `tokio` - Async runtime
- `anyhow` - Error handling

## Plugin Packaging

This reaction is compiled as a dynamic plugin (cdylib) that can be loaded by drasi-server at runtime.

**Key files:**
- `Cargo.toml` — includes `crate-type = ["lib", "cdylib"]`
- `src/descriptor.rs` — implements `ReactionPluginDescriptor` with kind `"http"`, configuration DTO, and OpenAPI schema generation
- `src/lib.rs` — invokes `drasi_plugin_sdk::export_plugin!` to export the plugin entry point

**Building:**
```bash
cargo build -p drasi-reaction-http
```

The compiled `.so` (Linux) / `.dylib` (macOS) / `.dll` (Windows) is placed in `target/debug/` and can be copied to the server's `plugins/` directory.

For more details on the plugin descriptor pattern and configuration DTOs, see the [Reaction Developer Guide](../README.md#packaging-as-a-dynamic-plugin).

## License

Copyright 2025 The Drasi Authors.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.