trishul-snmp

v0.2.0 Implementation Prep

Last updated: 2026-05-08

This document is the implementation-readiness plan for trishul-snmp 0.2.0. It is intentionally pre-code and pre-release. Current shipped API documentation remains in Python API, CLI Reference, and Architecture.

---

1. Target outcome

0.2.0 should expand tsnmp from a polling-only SNMPv2c manager runtime into a broader runtime package with:

• outbound SNMPv2c trap send
• outbound SNMPv2c inform send
• inbound trap/inform listener support
• notification event/decode/render support
• a narrow read-only simulator/responder

This remains a pragmatic runtime expansion, not a full agent platform and not an SNMPv3 release.

---

2. Scope boundary

In scope:

• additive notification-aware MIB metadata retention
• SNMPv2c notification send and receive
• Python API first, CLI second
• offline notification decode
• bundle-backed notification enrichment
• narrow read-only responder/simulator support for GET, GET_NEXT, and GET_BULK

Out of scope:

• SNMPv3 delivery
• writable responder behavior or SET
• full agent framework
• VACM/USM/security model work
• raw MIB ingestion
• compiler workflows inside tsnmp
• pysnmp compatibility shims

---

3. Issue map and dependency order

Order	Issue	Focus	Notes
1	#2	Foundation and metadata retention	Mandatory first slice.
2	#4	Outbound trap/inform send APIs	Lowest-risk feature slice after foundation.
3	#3	Inbound listener/server transport	Reuses the same wire and transport work.
4	#5	Notification event/render/decode/CLI tooling	Follows once send/listen primitives exist.
5	#6	Narrow responder/simulator layer	Depends on inbound/server transport.
track	#7	Umbrella tracker	Mirrors milestone progress.

Recommended coding order:

1. #2
2. #4
3. #3
4. #5
5. #6

#4 and #3 can overlap after #2, but send-side support is the cleaner first feature slice.

---

4. Implementation rules

• Keep lower layers role-neutral. Do not hard-code manager-only or community-only assumptions into generic transport code.
• Keep message envelope/version/security concerns separable from PDU and varbind logic.
• Keep bundle changes additive. Older module JSON must remain loadable when new notification fields are absent.
• Prefer extending existing modules first. Add new helper modules only when duplication is already real.
• Keep Python API design primary. CLI commands should follow the package API, not define it.

---

5. Preferred package evolution

The current top-level shape is sound. 0.2.0 should extend it rather than replace it.

Area	Likely files touched	Expected change
Public exports	trishul_snmp/__init__.py, trishul_snmp/types.py	Export new notification/listener/responder models once stable.
MIB metadata	trishul_snmp/mib/models.py, trishul_snmp/mib/registry.py, trishul_snmp/mib/render.py	Retain description, retain notification members, add notification-aware render helpers.
Bundle loading	trishul_snmp/mib/loader.py	Stay backward-compatible with older module JSON.
Wire codec	trishul_snmp/wire/pdu.py, trishul_snmp/wire/message.py	Add SNMPv2-TRAP and INFORM-REQUEST support without forking codec paths.
UDP transport	trishul_snmp/transport/udp.py, trishul_snmp/transport/dispatcher.py	Keep connected client path, add bound receive/server path, reuse request correlation where practical.
New notification API	trishul_snmp/notify/	Outbound notifier, listener API, and notification event helpers.
New responder API	trishul_snmp/responder/	Narrow read-only simulator/responder layer.
CLI	trishul_snmp/cli/main.py, trishul_snmp/cli/common.py, trishul_snmp/cli/output.py	Add notification commands only after Python API shape is stable.
Tests	tests/	Add dedicated notification/listener/responder coverage and reuse loopback UDP fixtures.

Preferred new package names:

• notify/ for outbound send and inbound notification listening
• responder/ for the narrow simulator/read-only responder

Avoid introducing a broad core/ or utils/ package unless the shared code is already large enough to justify it.

---

6. Public API targets to code against

These are the recommended names to lock before feature code starts:

• V2cNotifier
• V2cNotificationListener
• NotificationEvent
• V2cResponder

Recommended API direction:

• notifier methods:
  • send_trap(...)
  • send_inform(...)
• listener consumption:
  • async iterator first
  • thin callback wrappers only if still useful after the iterator API exists
• responder usage:
  • explicit object source registration or callback-backed resolution
  • read-only request handling only

Recommended behavior defaults:

• send_trap() is fire-and-forget
• send_inform() waits for a matching response or timeout
• listener auto-acknowledges inbound informs by default
• trap/inform helpers auto-populate standard SNMPv2 notification varbinds unless explicitly overridden

---

7. Milestone-by-milestone coding slices

7.1 #2 Foundation and metadata retention

Primary code touch points:

• trishul_snmp/mib/models.py
• trishul_snmp/mib/registry.py
• trishul_snmp/mib/render.py
• trishul_snmp/manager/operations.py
• trishul_snmp/transport/dispatcher.py

Required outcomes:

• retain description: str | None on normalized objects and notifications
• retain notification members: tuple[str, ...] | None
• keep loading tolerant when those fields are absent
• identify the minimum shared helpers needed for outbound notify and inbound inform correlation

Do not do in this slice:

• no public notifier API
• no listener API
• no responder API

7.2 #4 Outbound trap/inform send

Primary code touch points:

• trishul_snmp/wire/pdu.py
• trishul_snmp/wire/message.py
• trishul_snmp/transport/dispatcher.py
• trishul_snmp/notify/

Required outcomes:

• add notification-capable PDU tags
• send numeric notifications without a bundle
• send symbolic notifications with a loaded bundle
• match inform responses correctly

7.3 #3 Inbound listener/server transport

Primary code touch points:

• trishul_snmp/transport/udp.py
• trishul_snmp/notify/

Required outcomes:

• explicit bind host/port lifecycle
• source address capture
• community allowlist support
• trap decode and inform decode
• automatic inform acknowledgement

7.4 #5 Notification event/render/decode/CLI tooling

Primary code touch points:

• trishul_snmp/types.py or trishul_snmp/notify/events.py
• trishul_snmp/mib/render.py
• trishul_snmp/cli/main.py
• trishul_snmp/cli/output.py

Required outcomes:

• public event model preserving raw varbind order
• enriched notification names and member mapping when a bundle exists
• useful raw decode with no bundle
• offline decode entry point
• CLI commands for notification send/listen/decode

7.5 #6 Narrow read-only responder/simulator

Primary code touch points:

• trishul_snmp/responder/
• shared inbound transport from transport/
• loopback integration scaffolding in tests/test_udp_integration.py

Required outcomes:

• handle GET, GET_NEXT, and GET_BULK
• support simple in-memory or callback-backed data sources
• keep subtree semantics good enough for tests, fixtures, and demos

Do not do in this slice:

• no SET
• no persistence
• no writable instrumentation

---

8. Test plan

Recommended new coverage layout:

• tests/test_notification_wire.py
• tests/test_notification_send.py
• tests/test_notification_listener.py
• tests/test_notification_render.py
• tests/test_responder.py

Also extend:

• tests/test_bundle_loading.py for backward-compatible metadata retention
• tests/test_udp_integration.py for shared loopback transport coverage
• tests/test_cli.py and tests/test_cli_output.py for notification commands

Minimum acceptance coverage:

• trap/inform PDU encode/decode
• inform request/response correlation
• listener receive and shutdown behavior
• raw and enriched notification event rendering
• offline decode path
• responder loopback flows for GET, GET_NEXT, and GET_BULK

---

9. Decisions to lock before coding starts

These should be treated as pre-implementation decisions, not late cleanups:

1. Use notify/ and responder/ as the new top-level packages.
2. Use V2cNotifier, V2cNotificationListener, and V2cResponder as the public class names.
3. Keep listener delivery async iterator-first.
4. Keep responder scope explicitly read-only and simulator-oriented.
5. Keep compiled JSON as the only enrichment input. No raw MIB ingestion work enters 0.2.0.
6. Keep bundle changes additive and optional. Notification correctness must not depend on sidecars.
7. Keep CLI work secondary to the Python package API.

---

10. Release bar for 0.2.0

0.2.0 should not ship unless all of the following are true:

• metadata retention lands without breaking existing bundle loading
• trap send works
• inform send works
• listener receives trap and inform PDUs
• inbound informs are acknowledged correctly
• offline decode works
• bundle-backed notification enrichment works
• responder handles GET, GET_NEXT, and GET_BULK
• docs and examples are updated
• loopback integration tests cover listener and responder flows

---

11. First implementation chat starting point

Start with #2 only.

That first coding slice should:

• extend normalized MIB models
• preserve backward compatibility for older JSON
• identify the minimum shared helper extraction needed for inform correlation and shared varbind shaping

If that lands cleanly, move next to #4 rather than trying to open send, listen, render, and responder work in parallel.

This site is open source. Improve this page.