feat: add bounded SNMP walk

[larimonious]

Summary

Add bounded numeric SNMPv2c GETNEXT walks to the explicitly imported std/netmon module and release the slice as v0.5.3.

This PR is stacked on #171 (docs/std-netmon-mib-catalogs). Its code remains numeric-only; MIB catalog parsing/resolution is deliberately deferred to the next implementation slice.

API

snmp_walk(target: String, auth: Map, oid: String, opts?: Map) -> Result<Map, String>

The closed options map adds:

• max_results: default 256, hard maximum 2,048
• on_limit: "error" (default) or "partial"

Preflight enforces:

(max_results + 1) * (retries + 1) <= 4,096

The extra logical request is the mandatory look-ahead used to distinguish exact completion from true truncation.

Safety and protocol contract

• Reuses v0.5.2's opaque Secret community, literal-IP target policy, process gate, private-target dual opt-in, connected UDP transport, and 8 KiB packet ceilings.
• One operation-wide monotonic deadline covers every cursor, retry, stale-response drain, decode, normalization step, look-ahead, and final result construction.
• Enforces strictly increasing ordinary-value OIDs and exact terminal-exception cursor correlation.
• Requires exactly one correlated response varbind per logical request.
• Ignores same-agent stale request IDs only inside the current connected attempt; they still consume deadline and cumulative receive-byte budget.
• Caps transmitted datagrams at 4,096, cumulative received bytes at 8 MiB, and conservative normalized output at 4 MiB.
• Counts every received datagram before per-packet rejection, including conservative handling for platform oversized-datagram errors.
• Returns explicit successful stop reasons for subtree exit and protocol exceptions.
• Returns Err(String) without prior-row telemetry for transport, protocol, ordering, deadline, packet, cumulative-byte, and output-budget failures.
• Rejects malformed error_status=0 / nonzero error_index combinations for GET and WALK.

Result shape

Successful results contain exactly:

• target
• address
• port
• version
• root_oid
• duration_ms
• requests
• attempts
• complete
• stop_reason
• values

stop_reason is one of out_of_subtree, end_of_mib_view, no_such_object, no_such_instance, or max_results.

Tests

• Independent UDP GETNEXT fixture validating outbound tag, cursor progression, and community canary.
• Ordered rows, empty walks, subtree exit, protocol exceptions, exact-limit completion, and true truncation.
• Equal/repeated/descending OIDs and mismatched terminal exception OIDs.
• Wrong version/community/PDU/request ID, malformed/trailing BER, multiple varbinds, agent errors, and oversized packets.
• Forged-source rejection and delayed stale request-ID handling.
• Valid row followed by protocol failure proves no partial telemetry escapes.
• Transport-level cumulative receive accounting and exact conservative output-boundary seams.
• Existing snmp_get regression coverage, including malformed status/index combinations.
• Typechecker argument-type and arity coverage.

Validation

• cargo fmt --all
• Netmon unit tests: 13/13
• WALK integration tests: 14/14
• Existing GET integration tests: 8/8
• Typechecker WALK tests: 2/2
• cargo nextest run --locked --no-fail-fast: 1,952/1,952
• Doctests: pass
• Generated and validated docs: 480 functions across 26 modules
• No-traffic example: pass
• Targeted new clippy::op_ref warnings: clean
• git diff --check: pass
• Two independent exact-staged-diff security/implementation adjudications: PASS

Repo-wide clippy -D warnings remains blocked locally by existing warnings outside this diff; this PR does not expand that debt.

[greptile-apps]

Greptile Summary

Adds a bounded numeric SNMPv2c GETNEXT walk API.

• Registers and type-checks snmp_walk with optional walk-specific limits.
• Implements strict response correlation, OID progression, completion detection, retries, deadlines, and byte ceilings.
• Adds protocol, transport, boundary, and type-checker coverage.
• Updates documentation, examples, release notes, and the package version to v0.5.3.

Confidence Score: 5/5

The PR appears safe to merge with no actionable correctness or security defects identified.

The new API’s registration, static signature, protocol handling, limit look-ahead, deadline enforcement, resource accounting, and documented result contract remain internally consistent and are covered across their principal boundary conditions.

Important Files Changed

Filename	Overview
src/stdlib/netmon.rs	Implements bounded walks, option validation, transport controls, response processing, completion semantics, and result construction without an identified actionable defect.
src/stdlib/netmon_codec.rs	Adds canonical GETNEXT encoding and stale-request classification while retaining BER, version, community, PDU, and status validation.
src/typechecker.rs	Adds a snmp_walk signature whose required and optional arguments agree with runtime registration.
tests/std_netmon_walk_tests.rs	Provides broad integration coverage for progression, completion boundaries, malformed responses, stale datagrams, limits, and policy checks.
docs/STDLIB_REFERENCE.md	Documents the new API and its result, completion, security, and resource-bound contracts consistently with the implementation.

Sequence Diagram

sequenceDiagram
    participant Program as NTNT Program
    participant Walk as snmp_walk
    participant Agent as SNMP Agent
    Program->>Walk: target, auth, root OID, options
    loop Until completion or limit
        Walk->>Agent: GETNEXT(cursor)
        Agent-->>Walk: Correlated response varbind
        Walk->>Walk: Validate response, OID order, budgets, deadline
        alt Terminal exception
            Walk-->>Program: Complete result with terminal reason
        else Outside subtree
            Walk-->>Program: Complete result: out_of_subtree
        else Look-ahead exceeds max_results
            Walk-->>Program: Error or partial max_results result
        else Ordinary in-subtree value
            Walk->>Walk: Normalize value and advance cursor
        end
    end

Loading

_{Reviews (1): Last reviewed commit: "feat: add bounded SNMP walk" | Re-trigger Greptile}