go-netops/docs/history.md

History

Module: forge.lthn.ai/core/go-netops

Origin

go-netops was extracted from the core/go monorepo as part of the February 2026 workspace split. The UniFi integration was originally developed inside core/go/pkg/unifi/ to support the core unifi CLI commands for querying network infrastructure — devices, clients, networks, routes, and sites.

The extraction moved the package into its own repository to follow the same pattern as other core/go-* packages (go-ws, go-p2p, go-store, go-ratelimit, etc.), each with their own module path, test suite, and release cycle.

Initial Extraction

Commit: fabf31f — feat: extract UniFi network controller package from core/go

What was included in the extraction:

• client.go — Client struct wrapping unpoller/unifi, New constructor with TLS config
• clients.go — GetClients with ClientFilter (site, wired/wireless filtering)
• config.go — Three-tier config resolution (NewFromConfig, ResolveConfig, SaveConfig), config constants, package-level documentation
• devices.go — GetDevices (raw SDK), GetDeviceList (flat DeviceInfo slice), support for UAP, USW, USG, UDM, UXG device types
• networks.go — GetNetworks via raw controller API, NetworkConf struct with VLAN, DHCP, DNS, firewall zone, NAT, and WAN fields
• routes.go — GetRoutes via raw controller API, Route struct, RouteTypeName helper
• sites.go — GetSites wrapper
• client_test.go — Client creation tests with httptest mock
• config_test.go — Config resolution, persistence, and priority tests

Total: 707 lines of Go across 9 files.

Known Limitations

• Coverage at 39% — query methods (GetClients, GetDevices, GetNetworks, GetRoutes, GetSites) are not unit-tested; they delegate to the unpoller SDK and would require a live or fully-emulated controller
• No write operations — the package is read-only; no device provisioning, client blocking, or network mutation
• No pagination — all queries return complete result sets; large deployments with thousands of clients may need pagination support
• Site name matching — getSitesForFilter matches on Name only, not SiteName or ID; controllers with duplicate site display names may behave unexpectedly
• NetworkConf and Route use custom structs with raw JSON parsing rather than SDK types, because the unpoller SDK does not wrap these endpoints

Future

• Integration test suite against a containerised UniFi controller mock
• Write operations for device provisioning and client management
• Event streaming via WebSocket for real-time network state
• Pagination support for large deployments