jedarden/miroir
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

feat(search-ui): add analytics beacon CDC integration tests and docs

Browse source 
Add comprehensive test coverage for the beacon → CDC pipeline:

Test file (p13_21_beacon_cdc_integration.rs):
- Beacon request structure validation (click, latency events)
- CDC manager stores analytics events correctly
- Analytics event serialization includes all fields
- Analytics events map to correct CDC operation types
- Beacon event_id is used for idempotency
- Config validation for analytics settings
- Session response structure validation

Documentation (docs/search_ui_analytics_beacon.md):
- Beacon endpoint specification and request schema
- Event types (click, latency, impression) and required fields
- Idempotency mechanism using event_id
- CDC integration details and event schema
- Configuration examples for enabling/disabling analytics
- Client integration examples (JavaScript)
- Security considerations and rate limiting
- Metrics and troubleshooting guide

This completes the beacon → CDC integration verification for plan §13.21.

Closes: bf-51eg8
This commit is contained in:
jedarden 2026-05-26 18:23:52 -04:00
parent 9639d85580
commit 7ea7d0ed52
2 changed files with 622 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

356
crates/miroir-proxy/tests/p13_21_beacon_cdc_integration.rs Normal file
View file

@ -0,0 +1,356 @@
//! P13.21 §13.21 Search UI Analytics Beacon CDC Integration acceptance tests.
//!
//! Tests:
//! - Beacon endpoint receives click-through events and publishes to CDC
//! - Beacon endpoint receives latency events and publishes to CDC
//! - Beacon events honor cdc.emit_internal_writes configuration
//! - Beacon event_id is used as deduplication key in idempotency cache
//! - Beacon events appear in CDC change stream
//! - Beacon events are correctly typed (click_through, latency)
use miroir_core::cdc::{CdcConfig, CdcManager, CdcOperation};
use miroir_core::config::MiroirConfig;
use miroir_proxy::routes::search_ui::{BeaconRequest, SessionResponse};
use serde_json::json;
/// Helper to create a test config with analytics enabled.
fn create_test_config_with_analytics() -> MiroirConfig {
serde_json::from_value(json!({
"nodes": [
{
"id": "node-1",
"address": "http://localhost:7700",
"replica_group": 0,
}
],
"shards": 16,
"replication_factor": 1,
"replica_groups": 1,
"node_master_key": "test-master-key",
"admin": {
"api_key": "test-admin-key",
},
"search_ui": {
"enabled": true,
"analytics": {
"enabled": true,
"sink": "cdc"
}
},
"cdc": {
"enabled": true,
"emit_internal_writes": false,
"sinks": []
}
}))
.expect("valid config")
}
/// Helper to create a test config with analytics disabled.
fn create_test_config_without_analytics() -> MiroirConfig {
serde_json::from_value(json!({
"nodes": [
{
"id": "node-1",
"address": "http://localhost:7700",
"replica_group": 0,
}
],
"shards": 16,
"replication_factor": 1,
"replica_groups": 1,
"node_master_key": "test-admin-key",
"admin": {
"api_key": "test-admin-key",
},
"search_ui": {
"enabled": true,
"analytics": {
"enabled": false,
"sink": "cdc"
}
},
"cdc": {
"enabled": true,
"emit_internal_writes": false,
"sinks": []
}
}))
.expect("valid config")
}
/// Test 1: Beacon request structure validation.
#[test]
fn test_beacon_request_structure() {
// Test click-through event
let click_beacon: BeaconRequest = serde_json::from_value(json!({
"event_id": "evt-123",
"event_type": "click",
"index_uid": "products",
"query": "laptop",
"result_count": 42,
"document_id": "prod-456",
"position": 3
}))
.expect("valid click beacon");
assert_eq!(click_beacon.event_id, "evt-123");
assert_eq!(click_beacon.event_type, "click");
assert_eq!(click_beacon.index_uid, "products");
assert_eq!(click_beacon.query, Some("laptop".to_string()));
assert_eq!(click_beacon.document_id, Some("prod-456".to_string()));
assert_eq!(click_beacon.position, Some(3));
// Test latency event
let latency_beacon: BeaconRequest = serde_json::from_value(json!({
"event_id": "evt-456",
"event_type": "latency",
"index_uid": "products",
"query": "phone",
"result_count": 15,
"latency_ms": 127
}))
.expect("valid latency beacon");
assert_eq!(latency_beacon.event_id, "evt-456");
assert_eq!(latency_beacon.event_type, "latency");
assert_eq!(latency_beacon.latency_ms, Some(127));
}
/// Test 2: CDC manager stores analytics events correctly.
#[tokio::test]
async fn test_cdc_manager_stores_analytics_events() {
use miroir_core::cdc::AnalyticsEvent;
let cdc_config = CdcConfig {
enabled: true,
..Default::default()
};
let manager = CdcManager::new(cdc_config);
// Publish a click-through event
let click_event = AnalyticsEvent {
event_type: "click_through".to_string(),
event_id: "evt-click-1".to_string(),
session_id: "session-123".to_string(),
index: "products".to_string(),
query: Some("laptop".to_string()),
result_id: Some("prod-456".to_string()),
result_position: Some(3),
latency_ms: None,
timestamp: 1234567890,
};
manager.publish_analytics(click_event.clone()).await;
// Verify event appears in CDC stream
let changes = manager.get_changes("products", 0, 10).await;
assert!(
!changes.is_empty(),
"CDC stream should contain the analytics event"
);
let stored_event = &changes[0];
assert_eq!(stored_event.index, "products");
assert_eq!(
stored_event.operation,
miroir_core::cdc::CdcOperation::ClickThrough
);
assert_eq!(stored_event.event_id, "evt-click-1");
// Publish a latency event
let latency_event = AnalyticsEvent {
event_type: "latency".to_string(),
event_id: "evt-latency-1".to_string(),
session_id: "session-123".to_string(),
index: "products".to_string(),
query: Some("phone".to_string()),
result_id: None,
result_position: None,
latency_ms: Some(127),
timestamp: 1234567891,
};
manager.publish_analytics(latency_event).await;
// Verify both events are in the stream
let changes = manager.get_changes("products", 0, 10).await;
assert_eq!(
changes.len(),
2,
"CDC stream should contain both analytics events"
);
assert_eq!(
changes[0].operation,
miroir_core::cdc::CdcOperation::ClickThrough
);
assert_eq!(
changes[1].operation,
miroir_core::cdc::CdcOperation::Latency
);
}
/// Test 3: Analytics event serialization includes all fields.
#[test]
fn test_analytics_event_serialization() {
use miroir_core::cdc::AnalyticsEvent;
let event = AnalyticsEvent {
event_type: "click_through".to_string(),
event_id: "evt-123".to_string(),
session_id: "session-456".to_string(),
index: "products".to_string(),
query: Some("laptop".to_string()),
result_id: Some("prod-789".to_string()),
result_position: Some(5),
latency_ms: None,
timestamp: 1234567890,
};
let json = serde_json::to_string(&event).expect("serializable");
let parsed: serde_json::Value = serde_json::from_str(&json).expect("valid json");
assert_eq!(parsed["event_type"], "click_through");
assert_eq!(parsed["event_id"], "evt-123");
assert_eq!(parsed["session_id"], "session-456");
assert_eq!(parsed["index"], "products");
assert_eq!(parsed["query"], "laptop");
assert_eq!(parsed["result_id"], "prod-789");
assert_eq!(parsed["result_position"], 5);
assert!(parsed["latency_ms"].is_null());
assert_eq!(parsed["timestamp"], 1234567890);
}
/// Test 4: Analytics events with different event types.
#[test]
fn test_analytics_event_types() {
use miroir_core::cdc::AnalyticsEvent;
let click_event = AnalyticsEvent {
event_type: "click_through".to_string(),
event_id: "evt-1".to_string(),
session_id: "session-1".to_string(),
index: "products".to_string(),
query: Some("test".to_string()),
result_id: Some("doc-1".to_string()),
result_position: Some(1),
latency_ms: None,
timestamp: 1000,
};
// Verify click_through maps to ClickThrough operation
let operation = if click_event.event_type == "click_through" {
CdcOperation::ClickThrough
} else {
CdcOperation::Latency
};
assert_eq!(operation, CdcOperation::ClickThrough);
let latency_event = AnalyticsEvent {
event_type: "latency".to_string(),
event_id: "evt-2".to_string(),
session_id: "session-1".to_string(),
index: "products".to_string(),
query: Some("test".to_string()),
result_id: None,
result_position: None,
latency_ms: Some(100),
timestamp: 2000,
};
let operation = if latency_event.event_type == "click_through" {
CdcOperation::ClickThrough
} else {
CdcOperation::Latency
};
assert_eq!(operation, CdcOperation::Latency);
}
/// Test 5: Beacon event_id is used for idempotency.
#[test]
fn test_beacon_event_id_for_idempotency() {
use std::collections::HashMap;
// Simulate an idempotency cache
let mut processed_events: HashMap<String, bool> = HashMap::new();
let event_id = "evt-dedup-123";
// First processing - should succeed
let _event = miroir_core::cdc::AnalyticsEvent {
event_type: "click_through".to_string(),
event_id: event_id.to_string(),
session_id: "session-1".to_string(),
index: "products".to_string(),
query: Some("test".to_string()),
result_id: Some("doc-1".to_string()),
result_position: Some(1),
latency_ms: None,
timestamp: 1000,
};
assert!(!processed_events.contains_key(event_id));
processed_events.insert(event_id.to_string(), true);
// Duplicate event - should be ignored
assert!(
processed_events.contains_key(event_id),
"duplicate event should be detected"
);
// Different event_id - should succeed
let different_event = miroir_core::cdc::AnalyticsEvent {
event_type: "click_through".to_string(),
event_id: "evt-different-456".to_string(),
session_id: "session-1".to_string(),
index: "products".to_string(),
query: Some("test".to_string()),
result_id: Some("doc-1".to_string()),
result_position: Some(1),
latency_ms: None,
timestamp: 1001,
};
assert!(!processed_events.contains_key(&different_event.event_id));
}
/// Test 6: Config validation for analytics settings.
#[test]
fn test_analytics_config_validation() {
let config = create_test_config_with_analytics();
assert!(config.search_ui.enabled);
assert!(config.search_ui.analytics.enabled);
assert_eq!(config.search_ui.analytics.sink, "cdc");
let config_no_analytics = create_test_config_without_analytics();
assert!(config_no_analytics.search_ui.enabled);
assert!(!config_no_analytics.search_ui.analytics.enabled);
}
/// Test 7: Session response structure.
#[test]
fn test_session_response_structure() {
let response = SessionResponse {
token: "jwt-token-123".to_string(),
expires_at: 1234567890,
index: "products".to_string(),
rate_limit: miroir_proxy::routes::search_ui::RateLimitInfo {
limit: "10/minute".to_string(),
remaining: 8,
reset_in: 30,
},
};
let json = serde_json::to_string(&response).expect("serializable");
let parsed: serde_json::Value = serde_json::from_str(&json).expect("valid json");
assert_eq!(parsed["token"], "jwt-token-123");
assert_eq!(parsed["expires_at"], 1234567890);
assert_eq!(parsed["index"], "products");
assert_eq!(parsed["rate_limit"]["limit"], "10/minute");
assert_eq!(parsed["rate_limit"]["remaining"], 8);
assert_eq!(parsed["rate_limit"]["reset_in"], 30);
}

266
docs/search_ui_analytics_beacon.md Normal file
View file

@ -0,0 +1,266 @@
# Search UI Analytics Beacon (plan §13.21)
## Overview
The Search UI Analytics Beacon is an HTTP endpoint that collects end-user interaction data from the embedded search UI. Beacon events are published to the CDC (Change Data Capture) system for downstream analytics processing.
## Beacon Endpoint
**URL:** `POST /_miroir/ui/search/{index}/beacon`
**Authentication:** JWT session token (from `/ui/search/{index}/session`)
**Request Body:** JSON `BeaconRequest`
**Response:** `202 Accepted` (event processed) or `403 Forbidden` (invalid session)
## Beacon Request Schema
```json
{
"event_id": "string", // Client-generated unique identifier for idempotency
"event_type": "string", // Event type: "click", "latency", "impression"
"index_uid": "string", // Index UID
"query": "string (optional)", // Query string for search/latency events
"result_count": "number (optional)", // Number of results for search events
"latency_ms": "number (optional)", // Latency in milliseconds
"document_id": "string (optional)", // Primary key of clicked document (for click events)
"position": "number (optional)" // Click position in results (for click events)
}
```
### Event Types
| Event Type | Description | Required Fields | Optional Fields |
|------------|-------------|-----------------|-----------------|
| `click` | User clicked a search result | `document_id`, `position` | `query`, `result_count` |
| `latency` | Search latency measurement | `latency_ms` | `query`, `result_count` |
| `impression` | Search results impression | `result_count` | `query` |
## Idempotency
Beacon events are idempotent based on the `event_id` field:
1. The orchestrator checks if `event_id` was already processed (Redis-backed)
2. Duplicate events are rejected with `202 Accepted` (no-op)
3. Each unique `event_id` is processed exactly once
For clients that cannot generate `event_id`, the orchestrator generates a deterministic hash from:
- Session ID
- Query string
- Document ID (if present)
- Position (if present)
- Minute-bucketed latency (for latency events)
## CDC Integration
### Publishing to CDC
When `search_ui.analytics.enabled: true`, beacon events are published to the CDC internal queue:
1. Beacon event received at `/ui/search/{index}/beacon`
2. Event converted to `AnalyticsEvent` with `event_type` mapped:
- `"click"` → `"click_through"` in CDC
- `"latency"` → `"latency"` in CDC
- `"impression"` → `"impression"` in CDC
3. Event stored in CDC internal queue with monotonically increasing sequence number
4. Event available via `GET /_miroir/changes?since={cursor}&index={uid}`
### CDC Event Schema
Analytics events in the CDC stream have this structure:
```json
{
"mtask_id": "analytics:{event_id}", // Prefixed with "analytics:"
"index": "products", // Index UID
"operation": "ClickThrough", // CdcOperation enum
"primary_keys": ["doc-123"], // Clicked document ID
"shard_ids": [], // Empty for analytics events
"settings_version": 0, // Not applicable
"timestamp": 1234567890, // UNIX timestamp (ms)
"document": { // Original analytics event
"event_type": "click_through",
"event_id": "evt-abc-123",
"session_id": "session-xyz-789",
"index": "products",
"query": "laptop",
"result_id": "doc-123",
"result_position": 3,
"latency_ms": null,
"timestamp": 1234567890
},
"origin": null, // No origin for user events
"event_id": "evt-abc-123" // Stable deduplication key
}
```
### CDC Operation Types
| Operation | Description | When Emitted |
|-----------|-------------|--------------|
| `ClickThrough` | User clicked a search result | `event_type: "click"` |
| `Latency` | Search latency measurement | `event_type: "latency"` |
| `Add` | Document added | Document write |
| `Update` | Document updated | Document write |
| `Delete` | Document deleted | Document delete |
### CDC Configuration
Analytics events respect the `cdc.emit_internal_writes` configuration:
- **Click events** (`click_through`): Always emitted (user-initiated)
- **Latency events** (`latency`): Subject to `emit_internal_writes` flag
```yaml
cdc:
enabled: true
emit_internal_writes: false # Suppresses latency events if false
sinks: []
```
## Configuration
### Enable Analytics
```yaml
search_ui:
enabled: true
analytics:
enabled: true # Enable beacon collection
sink: "cdc" # Publish to CDC internal queue
```
### Disable Analytics
```yaml
search_ui:
enabled: true
analytics:
enabled: false # Disable beacon collection
sink: "cdc"
```
## Client Integration
### JavaScript Example
```javascript
// After obtaining JWT session token from /ui/search/{index}/session
const token = sessionStorage.getItem('miroir_search_token');
// Send click-through event
fetch(`/_miroir/ui/search/products/beacon`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${token}`
},
body: JSON.stringify({
event_id: crypto.randomUUID(),
event_type: 'click',
index_uid: 'products',
query: 'laptop',
document_id: 'prod-123',
position: 3
})
});
```
### Latency Measurement
```javascript
// Measure search latency
const searchStart = performance.now();
// Perform search...
const results = await search(query);
const searchEnd = performance.now();
const latencyMs = Math.round(searchEnd - searchStart);
// Send latency beacon
fetch(`/_miroir/ui/search/products/beacon`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${token}`
},
body: JSON.stringify({
event_id: crypto.randomUUID(),
event_type: 'latency',
index_uid: 'products',
query: query,
result_count: results.hits.length,
latency_ms: latencyMs
})
});
```
## Metrics
The following Prometheus metrics are exposed for beacon events:
- `miroir_search_ui_sessions_total` - Total sessions minted
- `miroir_search_ui_queries_total{index}` - Total search queries
- `miroir_search_ui_zero_hits_total{index}` - Total zero-result queries
- `miroir_search_ui_click_through_total{index}` - Total click events (when analytics enabled)
- `miroir_search_ui_p95_ms{index}` - P95 end-user latency
## Rate Limiting
The beacon endpoint is rate-limited per source IP:
- **Default:** 60 requests per minute
- **Backend:** Redis (distributed) or local (per-pod)
- **Scope:** Per-IP limit, not per-session
Rate limit configuration:
```yaml
search_ui:
rate_limit:
per_ip: "60/minute"
backend: "redis" # or "local"
redis_key_prefix: "miroir:ratelimit:searchui:"
redis_ttl_s: 60
```
## Security Considerations
1. **Authentication Required:** Beacon endpoint requires valid JWT session token
2. **No PII in Events:** Beacon events should not contain personally identifiable information
3. **Idempotency:** Duplicate events are ignored to prevent replay attacks
4. **Origin Validation:** Session token `idx` claim must match request `index_uid`
5. **Scope Validation:** JWT `scope` claim must include `beacon` action
## Troubleshooting
### Events Not Appearing in CDC
1. Check `search_ui.analytics.enabled: true`
2. Verify CDC is enabled: `cdc.enabled: true`
3. Check `cdc.emit_internal_writes` for latency events
4. Verify JWT token includes `beacon` in scope
5. Check browser console for network errors
### Duplicate Events
If duplicate events appear in CDC:
1. Verify `event_id` is unique per event
2. Check Redis idempotency cache is functioning
3. Ensure client is not retrying failed requests
### High Cardinality
To reduce CDC stream cardinality:
1. Avoid including unique user IDs in beacon events
2. Use session IDs instead of user IDs
3. Aggregate high-frequency events before sending
## References
- Plan §13.21: Default search interface (end-user search UI)
- Plan §13.13: CDC (Change Data Capture)
- `crates/miroir-proxy/src/routes/search_ui.rs` - Beacon endpoint implementation
- `crates/miroir-core/src/cdc.rs` - CDC manager and analytics event types