test(examples): add compile-checked usage examples

The README code blocks had no compile guarantee, so API changes could silently
rot them. Keep the examples as real files, type-checked in CI.

- examples/client.cr: high-level Client (get / multi-get / walks / typed set /
  notifications / v3)
- examples/v2c_raw.cr, v3_raw.cr: raw-socket exchanges with response-id and
  error-status validation
- mise: dev:examples runs crystal build --no-codegen on examples/*.cr
- ci: type-check the examples in the docs job

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: n-rodriguez

.github/workflows/ci.yml

@@ -67,6 +67,9 @@ jobs:
       - name: Build API docs
         run: mise dev:docs
 
+      - name: Type-check the README examples
+        run: mise dev:examples
+
   test_linux:
     runs-on: ubuntu-latest
     steps:

examples/client.cr

@@ -0,0 +1,55 @@
+# High-level client usage — one `SNMP::Client` per fiber.
+# In your project: require "snmp"
+require "../src/snmp"
+
+# ---- v2c ----
+client = SNMP::Client.new("localhost", community: "public")
+
+# Single get: the shortcut accessors read the first varbind
+message = client.get("1.3.6.1.2.1.1.4.0")
+puts message.value.get_string
+
+# Multi-varbind get: one round-trip for several OIDs
+message = client.get(["1.3.6.1.2.1.1.1.0", "1.3.6.1.2.1.1.5.0"])
+message.varbinds.each { |varbind| puts "#{varbind.oid} => #{varbind.value.get_string}" }
+
+# Walk a subtree (GetNext based); the block form streams
+client.walk("1.3.6.1.2.1.1.9.1.3") do |msg|
+  puts "#{msg.oid} => #{msg.value.get_string}"
+end
+
+# Bulk walk (GetBulk based, fewer round-trips); yields each VarBind
+client.bulk_walk("1.3.6.1.2.1.2.2.1.2", max_repetitions: 25) do |varbind|
+  puts "#{varbind.oid} => #{varbind.value.get_string}"
+end
+
+# Set values — Crystal primitives or typed SNMP values
+client.set("1.3.6.1.2.1.1.6.0", "server room")
+client.set("1.3.6.1.2.1.1.3.0", SNMP::TimeTicks.new(12_345_u32))
+
+# Multi-varbind set: one SetRequest for several assignments
+client.set({
+  "1.3.6.1.2.1.1.5.0" => "hostname",
+  "1.3.6.1.2.1.1.6.0" => "the location",
+})
+
+# Send notifications (community sessions)
+client.send_trap_v2("1.3.6.1.4.1.8072.2.3.0.1", uptime: 12_345)
+response = client.send_inform("1.3.6.1.4.1.8072.2.3.0.1")
+puts response.request # Response (the inform acknowledgement)
+
+# Release the reused UDP socket when done (reconnects transparently if reused)
+client.close
+
+# ---- v3 ----
+# The client drives engine discovery, HMAC verification, the RFC 3414 time
+# window, and auto-resyncs/retries once on a usmStats Report.
+security = SNMP::V3::Security.new(
+  "usr-sha-aes",
+  auth_protocol: SNMP::V3::Security::AuthProtocol::SHA256,
+  auth_password: "authkey1",
+  priv_protocol: SNMP::V3::Security::PrivacyProtocol::AES256,
+  priv_password: "privkey1"
+)
+v3_client = SNMP::Client.new("localhost", SNMP::V3::Session.new(security))
+puts v3_client.get("1.3.6.1.2.1.1.4.0").value.get_string

examples/v2c_raw.cr

@@ -0,0 +1,23 @@
+# Raw-socket v2c exchange, for when you manage the transport yourself.
+# In your project: require "snmp"
+require "../src/snmp"
+
+# Connect to the agent
+socket = UDPSocket.new
+socket.connect("localhost", 161)
+socket.sync = false
+socket.read_timeout = 3.seconds
+
+# Build and send the request
+session = SNMP::Session.new(community: "public")
+request = session.get("1.3.6.1.2.1.1.4.0")
+socket.write_bytes request
+socket.flush
+
+# Parse the response, verifying it answers *this* request
+response = session.parse(socket.read_bytes(ASN1::BER))
+raise "response-id mismatch" unless response.request_id == request.request_id
+raise "agent error: #{response.error_status}" unless response.error_status.no_error?
+
+puts response.value.get_string
+socket.close

examples/v3_raw.cr

@@ -0,0 +1,38 @@
+# Raw-socket SNMPv3 exchange: engine discovery, auth+priv, response validation.
+# In your project: require "snmp"
+require "../src/snmp"
+
+# Connect to the agent
+socket = UDPSocket.new
+socket.connect("localhost", 161)
+socket.sync = false
+socket.read_timeout = 3.seconds
+
+# Session with authentication and privacy (see AuthProtocol / PrivacyProtocol
+# for the supported algorithms, incl. SHA-2 and AES-256)
+session = SNMP::V3::Session.new(
+  "usr-md5-aes", "authkey1", "privkey1",
+  priv_protocol: SNMP::V3::Security::PrivacyProtocol::AES
+)
+
+# Discover the engine id / boots / time (required before authenticated requests;
+# also drives periodic revalidation of the RFC 3414 time window)
+if session.must_revalidate?
+  socket.write_bytes session.engine_validation_probe
+  socket.flush
+  session.validate socket.read_bytes(ASN1::BER)
+end
+
+# Build the request, then prepare it (encrypt + sign) for transmission
+request = session.get("1.3.6.1.2.1.1.4.0")
+socket.write_bytes session.prepare(request)
+socket.flush
+
+# Parse the response: the HMAC is verified and the time window enforced.
+# Still check that it answers *this* request before trusting the values.
+response = session.parse(socket.read_bytes(ASN1::BER))
+raise "response-id mismatch" unless response.request_id == request.request_id
+raise "agent error: #{response.error_status}" unless response.error_status.no_error?
+
+puts response.value.get_string
+socket.close

mise.toml

@@ -54,6 +54,15 @@ env = { CRYSTAL_WORKERS = "4" }
 description = "Build the API docs (fails on doc-comment / compile errors)"
 run = "crystal docs"
 
+[tasks."dev:examples"]
+description = "Type-check the README examples (keeps the docs honest)"
+run = """
+for f in examples/*.cr; do
+  echo "==> $f"
+  crystal build --no-codegen "$f"
+done
+"""
+
 [tasks."dev:check"]
 description = "Format-check, lint and test in one shot"
 run = "mise dev:format-check && mise dev:ameba && mise dev:spec && mise dev:spec-mt"