Struct ClientBuilder 

pub struct ClientBuilder { /* private fields */ }

Builder for constructing SNMP clients.

This is the single entry point for client construction. It supports all SNMP versions (v1, v2c, v3) through the Auth enum.

Example

use async_snmp::{Auth, ClientBuilder};
use std::time::Duration;

// Simple v2c client
let client = ClientBuilder::new("192.168.1.1:161", Auth::v2c("public"))
    .connect().await?;

// v3 client with authentication
let client = ClientBuilder::new("192.168.1.1:161",
    Auth::usm("admin").auth(async_snmp::AuthProtocol::Sha256, "password"))
    .timeout(Duration::from_secs(10))
    .retries(5)
    .connect().await?;

Implementations

impl ClientBuilder

pub fn new(target: impl Into<String>, auth: impl Into<Auth>) -> Self

Create a new client builder.

Arguments

• target - The target address (e.g., “192.168.1.1:161”)
• auth - Authentication configuration (community or USM)

Example

use async_snmp::{Auth, ClientBuilder};

// Using Auth::default() for v2c with "public" community
let builder = ClientBuilder::new("192.168.1.1:161", Auth::default());

// Using Auth::v1() for SNMPv1
let builder = ClientBuilder::new("192.168.1.1:161", Auth::v1("private"));

// Using Auth::usm() for SNMPv3
let builder = ClientBuilder::new("192.168.1.1:161",
    Auth::usm("admin").auth(async_snmp::AuthProtocol::Sha256, "password"));

pub fn timeout(self, timeout: Duration) -> Self

Set the request timeout (default: 5 seconds).

This is the time to wait for a response before retrying or failing. The total time for a request may be timeout * (retries + 1).

Example

use async_snmp::{Auth, ClientBuilder};
use std::time::Duration;

let builder = ClientBuilder::new("192.168.1.1:161", Auth::v2c("public"))
    .timeout(Duration::from_secs(10));

pub fn retries(self, retries: u32) -> Self

Set the number of retries (default: 3).

The client will retry failed requests up to this many times before returning an error. Set to 0 to disable retries.

Example

use async_snmp::{Auth, ClientBuilder};

// Increase retries for unreliable networks
let builder = ClientBuilder::new("192.168.1.1:161", Auth::v2c("public"))
    .retries(5);

// Disable retries for fast failure detection
let builder = ClientBuilder::new("192.168.1.1:161", Auth::v2c("public"))
    .retries(0);

pub fn max_oids_per_request(self, max: usize) -> Self

Set the maximum OIDs per request (default: 10).

Requests with more OIDs than this limit are automatically split into multiple batches. Some devices have lower limits on the number of OIDs they can handle in a single request.

Example

use async_snmp::{Auth, ClientBuilder};

// For devices with limited request handling capacity
let builder = ClientBuilder::new("192.168.1.1:161", Auth::v2c("public"))
    .max_oids_per_request(5);

// For high-capacity devices, increase to reduce round-trips
let builder = ClientBuilder::new("192.168.1.1:161", Auth::v2c("public"))
    .max_oids_per_request(50);

pub fn max_repetitions(self, max: u32) -> Self

Set max-repetitions for GETBULK operations (default: 25).

Controls how many rows are requested per GETBULK PDU during walk operations. Higher values reduce round-trips but increase response size.

Example

use async_snmp::{Auth, ClientBuilder};

// Reduce max-repetitions for devices with limited buffer sizes
let builder = ClientBuilder::new("192.168.1.1:161", Auth::v2c("public"))
    .max_repetitions(10);

// Increase for faster walks over reliable networks
let builder = ClientBuilder::new("192.168.1.1:161", Auth::v2c("public"))
    .max_repetitions(50);

pub fn walk_mode(self, mode: WalkMode) -> Self

Override walk behavior for devices with buggy GETBULK (default: Auto).

• WalkMode::Auto: Use GETNEXT for v1, GETBULK for v2c/v3
• WalkMode::GetNext: Always use GETNEXT (slower but more compatible)
• WalkMode::GetBulk: Always use GETBULK (faster, errors on v1)

Example

use async_snmp::{Auth, ClientBuilder, WalkMode};

// Force GETNEXT for devices with broken GETBULK implementation
let builder = ClientBuilder::new("192.168.1.1:161", Auth::v2c("public"))
    .walk_mode(WalkMode::GetNext);

// Force GETBULK for faster walks (only v2c/v3)
let builder = ClientBuilder::new("192.168.1.1:161", Auth::v2c("public"))
    .walk_mode(WalkMode::GetBulk);

pub fn oid_ordering(self, ordering: OidOrdering) -> Self

Set OID ordering behavior for walk operations (default: Strict).

• OidOrdering::Strict: Require strictly increasing OIDs. Most efficient.
• OidOrdering::AllowNonIncreasing: Allow non-increasing OIDs with cycle detection. Uses O(n) memory to track seen OIDs.

Use AllowNonIncreasing for buggy agents that return OIDs out of order.

Warning: AllowNonIncreasing uses O(n) memory. Always pair with max_walk_results to bound memory usage.

Example

use async_snmp::{Auth, ClientBuilder, OidOrdering};

// Use relaxed ordering with a safety limit
let builder = ClientBuilder::new("192.168.1.1:161", Auth::v2c("public"))
    .oid_ordering(OidOrdering::AllowNonIncreasing)
    .max_walk_results(10_000);

pub fn max_walk_results(self, limit: usize) -> Self

Set maximum results from a single walk operation (default: unlimited).

Safety limit to prevent runaway walks. Walk terminates normally when limit is reached.

Example

use async_snmp::{Auth, ClientBuilder};

// Limit walks to at most 10,000 results
let builder = ClientBuilder::new("192.168.1.1:161", Auth::v2c("public"))
    .max_walk_results(10_000);

pub fn engine_cache(self, cache: Arc<EngineCache>) -> Self

Set shared engine cache (V3 only, for high-throughput polling).

Allows multiple clients to share discovered engine state, reducing the number of discovery requests. This is particularly useful when polling many devices with SNMPv3.

Example

use async_snmp::{Auth, AuthProtocol, ClientBuilder, EngineCache};
use std::sync::Arc;

// Create a shared engine cache
let cache = Arc::new(EngineCache::new());

// Multiple clients can share the same cache
let builder1 = ClientBuilder::new("192.168.1.1:161",
    Auth::usm("admin").auth(AuthProtocol::Sha256, "password"))
    .engine_cache(cache.clone());

let builder2 = ClientBuilder::new("192.168.1.2:161",
    Auth::usm("admin").auth(AuthProtocol::Sha256, "password"))
    .engine_cache(cache.clone());

pub fn context_engine_id(self, engine_id: impl Into<Vec<u8>>) -> Self

Override the context engine ID (V3 only).

By default, the context engine ID is the same as the authoritative engine ID discovered during engine discovery. Use this to override for:

• Proxy scenarios where requests route through an intermediate agent
• Devices that require a specific context engine ID
• Pre-configured engine IDs from device documentation

The engine ID should be provided as raw bytes (not hex-encoded).

pub async fn connect(self) -> Result<Client<UdpTransport>, Error>

Connect via UDP (default).

Creates a new UDP socket and connects to the target address. This is the recommended connection method for most use cases due to UDP’s lower overhead compared to TCP.

For high-throughput scenarios with many targets, consider using SharedUdpTransport with build().

Errors

Returns an error if the configuration is invalid or the connection fails.

Example

use async_snmp::{Auth, ClientBuilder};

let client = ClientBuilder::new("192.168.1.1:161", Auth::v2c("public"))
    .connect()
    .await?;

pub async fn connect_tcp(self) -> Result<Client<TcpTransport>, Error>

Connect via TCP.

Establishes a TCP connection to the target. Use this when:

• UDP is blocked by firewalls
• Messages exceed UDP’s maximum datagram size
• Reliable delivery is required

Note that TCP has higher overhead than UDP due to connection setup and per-message framing.

Errors

Returns an error if the configuration is invalid or the connection fails.

Example

use async_snmp::{Auth, ClientBuilder};

let client = ClientBuilder::new("192.168.1.1:161", Auth::v2c("public"))
    .connect_tcp()
    .await?;

pub fn build<T: Transport>(self, transport: T) -> Result<Client<T>, Error>

Build a client with a custom transport.

Use this method when you need:

• A shared UDP transport for high-throughput polling of many targets
• A custom transport implementation
• To reuse an existing transport

Errors

Returns an error if the configuration is invalid.

Example

use async_snmp::{Auth, ClientBuilder, SharedUdpTransport};

// Create a shared transport for polling many targets
let shared = SharedUdpTransport::bind("0.0.0.0:0").await?;

// Create a handle for a specific target
let handle = shared.handle("192.168.1.1:161".parse().unwrap());

// Build client with the shared transport handle
let client = ClientBuilder::new("192.168.1.1:161", Auth::v2c("public"))
    .build(handle)?;