Imported from dvaerum/snmp-trap-event-handler (AGENTS.md). Install upstream with npx skills add dvaerum/snmp-trap-event-handler. Copyright stays with the author.

AGENTS.md

Guidance for AI coding agents working in this repository.

Project Overview

Rust SNMP trap event handler — receives SNMP traps, parses them, executes configurable hooks, and optionally broadcasts events via SSE. Two independent crates in crates/, no workspace root Cargo.toml.

Stack: Rust, Tokio, serde, anyhow, tracing, snmp-parser. Nix flake for builds, NixOS module for deployment.

Build / Lint / Test Commands

All cargo commands must run from within the crate directory.

# Primary crate
cd crates/snmp-trap-event-handler
cargo build
cargo test                        # all tests
cargo test test_format_mac        # single test by name substring
cargo test config::tests          # all tests in a module
cargo clippy -- -D warnings       # lint (treat warnings as errors)
cargo fmt                         # format
cargo fmt --check                 # check formatting (CI)

# Run with config (use --release to avoid stack overflow on SNMP queries)
cargo run --release -- -c ../../examples/config.example.json
RUST_LOG=debug cargo run --release -- -c ../../examples/config.example.json

# Secondary crate
cd crates/updated-kea-cli
cargo test

# Nix (from repo root)
nix build
nix flake check                   # runs all checks

Code Style

Formatting

Default rustfmt (no .rustfmt.toml). 4-space indentation. Run cargo fmt before committing.

Import Ordering

Group imports in this order, each group alphabetized internally:

1. External crates (anyhow, serde, tokio, tracing, …)
2. Standard library (std::collections, std::net, …)
3. Crate-local (crate::config, crate::hook_executor, …)

use anyhow::{Context, Result};
use snmp_parser::{parse_snmp_v2c, SnmpPdu};
use std::collections::HashMap;
use std::net::SocketAddr;
use tokio::sync::broadcast;
use tracing::{debug, error, info, warn};

use crate::config::Config;
use crate::hook_executor::TrapEvent;

Naming

Module Organization

• Each module is a directory with mod.rs (not module_name.rs style).
• Items are private by default; add pub only when needed across modules.
• #[allow(dead_code)] is acceptable for fields kept for planned use.

Error Handling

• Use anyhow::Result<T> for fallible functions.
• Add context with .with_context(|| format!("…")) or .context("…").
• Use anyhow::bail!("…") for early error returns.
• Never unwrap() in production code. Use expect("reason") only for true invariants.
• In tests, unwrap() is fine.

let contents = std::fs::read_to_string(path)
    .with_context(|| format!("Failed to read config: {}", path.display()))?;

Async Patterns

• Runtime: #[tokio::main] on main, #[tokio::test] on async tests.
• Shared state: Arc<RwLock<T>> (tokio's async RwLock).
• Concurrency: tokio::spawn for independent tasks, tokio::select! for racing.
• Timeouts: tokio::time::timeout wrapping async operations.

Logging

Use tracing macros: debug!, info!, warn!, error!.

use tracing::{debug, info, warn, error};

debug!("Parsed SNMPv2c: version={}", snmp_msg.version);
info!("Starting trap handler on {}", addr);
warn!("Unknown trap OID {} from {}", oid, source);
error!("Hook execution failed for '{}': {}", name, e);

Serde / Config Patterns

• Derive Deserialize, Serialize on config types; add Debug, Clone.
• Use #[serde(default = "fn_name")] for defaults, not Default impl.
• Use #[serde(skip_serializing_if = "Option::is_none")] for optional fields.
• Validate config in a validate() method called from load().

#[derive(Debug, Clone, Deserialize, Serialize)]
pub struct SnmpClient {
    pub community: String,
    #[serde(default = "default_timeout")]
    pub timeout_ms: u64,
}
fn default_timeout() -> u64 { 5000 }

Types

• Arc<T> for shared ownership across async tasks.
• HashMap<K, V> for key-value maps; VecDeque<T> for ring buffers.
• tokio::sync::broadcast for event fan-out (SSE).
• Derive Clone on types passed between async tasks.

Tests

Tests live in #[cfg(test)] mod tests at the bottom of each source file.

#[cfg(test)]
mod tests {
    use super::*;

    fn create_test_event(trap_type: &str) -> TrapEvent { /* … */ }

    #[test]
    fn test_format_mac_address_6_bytes() {
        let result = format_mac_address(&val);
        assert_eq!(result, Some("aa:bb:cc:dd:ee:ff".to_string()));
    }

    #[tokio::test]
    async fn test_store_and_get_sources() {
        let store = TrapStore::new(100, vec![]);
        store.store(create_test_event("linkup", "10.0.0.1:162")).await;
        assert_eq!(store.get_sources().await.len(), 1);
    }
}

Conventions:

• Name tests test_<what>_<scenario>.
• Use helper functions (create_test_*) for reusable test data.
• assert_eq! for values, assert!(matches!(…)) for enum variants, assert!(result.is_err()) for failures.

Comments

• /// doc comments on public structs, enums, and functions.
• //! module-level doc comments at top of mod.rs.
• Inline // comments for non-obvious logic only.

Workflow

Always commit after making changes. Create a commit with a descriptive message summarizing the changes whenever you add or modify code, docs, or tests.

Architecture Quick Reference

Data flow: UDP trap → parse SNMPv1/v2c → match handler → immediate hooks → SNMP queries → broadcast SSE → store → waiting hooks

Key modules in crates/snmp-trap-event-handler/src/:

Nix Commands

# Development shell
nix develop

# Build packages
nix build                    # Main snmp-trap-event-handler
nix build .#updated-kea-cli # Build Kea CLI tool

# Run checks (including all tests)
nix flake check

Additional Development Commands

# Test SNMP connectivity
cargo run --release --example query_device -- <device_ip> <community>

# Test REST API endpoints (with API enabled in config)
curl http://localhost:4002/health              # Health check
curl http://localhost:4002/sources              # List all trap sources
curl http://localhost:4002/history/<source_ip>  # Get trap history
curl http://localhost:4002/info/<source_ip>     # Get current state
curl -N http://localhost:4002/events            # SSE event stream

# Test trap sending
./scripts/send-test-trap.py <target_ip> <port>

Common Development Workflows

Adding a New Known Trap Type

1. Create a new module in known_traps/ (e.g., vendor_trap.rs)
2. Define constants: NAME, ENTERPRISE_OID, and mappings struct
3. Add the definition to KNOWN_TRAPS array in known_traps/mod.rs
4. Add name to KNOWN_TRAP_NAMES array
5. Update examples/config.example.json
6. Add tests

Adding a Hook

1. Create script in examples/hooks/
2. Make executable (chmod +x)
3. Add to config under appropriate handler's hooks array
4. Test with manual env vars: TRAP_MAC_ADDRESS=aa:bb:cc:dd:ee:ff TRAP_ACTION=learned ./script.sh

Adding a New Template Variable

1. Define in TrapData struct in trap_handler/mod.rs
2. Add substitution in hook_executor/mod.rs (substitute_template_vars)
3. Add to env vars in hook_executor/mod.rs (build_env_vars)

Adding a Predefined Query Set

1. Define static array of PredefinedQuery in snmp_queries/predefined.rs
2. Add entry to PREDEFINED_SETS registry
3. Add tests for the new set