# 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