57 lines
2.7 KiB
Markdown
57 lines
2.7 KiB
Markdown
|
# 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
|