core/go-netops
8
0
Fork 0
Code Issues 4 Pull requests Projects Releases Packages Wiki Activity Actions 4

docs(specs): add unifi RFC

Browse source
This commit is contained in:
Virgil 2026-03-27 22:02:18 +00:00
parent 590bfa9968
commit b034ee8854
1 changed files with 98 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

98
specs/unifi/RFC.md Normal file
View file

@ -0,0 +1,98 @@
# unifi
**Import:** `forge.lthn.ai/core/go-netops/unifi`
**Files:** 11
## Types
### `Client`
Wraps the underlying `*github.com/unpoller/unifi/v5.Unifi` client together with the controller URL used to construct it. The struct has no exported fields.
Methods:
- `API() *uf.Unifi`: Returns the underlying SDK client stored on the wrapper.
- `URL() string`: Returns the controller URL captured when the client was constructed.
- `GetClients(filter ClientFilter) ([]*uf.Client, error)`: Resolves the site scope with `GetSites`, fetches clients from the SDK, and optionally filters the result by wired or wireless state using `uf.Client.IsWired.Val`.
- `GetDevices(siteName string) (*uf.Devices, error)`: Resolves the site scope and returns the raw `*uf.Devices` container from the SDK.
- `GetDeviceList(siteName, deviceType string) ([]DeviceInfo, error)`: Flattens the `UAPs`, `USWs`, `USGs`, `UDMs`, and `UXGs` slices from `*uf.Devices` into `DeviceInfo` values. `deviceType` accepts `uap`, `usw`, `usg`, `udm`, or `uxg`; an empty value includes every supported device group.
- `GetNetworks(siteName string) ([]NetworkConf, error)`: Calls the controller endpoint `/api/s/{site}/rest/networkconf`, defaults an empty site name to `default`, unmarshals the JSON `data` payload, and returns the resulting `[]NetworkConf`.
- `GetRoutes(siteName string) ([]Route, error)`: Calls the controller endpoint `/api/s/{site}/stat/routing`, defaults an empty site name to `default`, path-escapes the site name, unmarshals the JSON `data` payload, and returns the resulting `[]Route`.
- `GetSites() ([]*uf.Site, error)`: Returns the sites exposed by the controller through the underlying SDK client.
### `ClientFilter`
Controls which clients `(*Client).GetClients` returns.
Fields:
- `Site string`: Site name filter. An empty value means all sites returned by `GetSites`.
- `Wired bool`: Whether wired clients should be included when connection-type filtering is active.
- `Wireless bool`: Whether wireless clients should be included when connection-type filtering is active.
### `DeviceInfo`
Flat representation of a UniFi infrastructure device returned by `(*Client).GetDeviceList`.
Fields:
- `Name string`: Device name from the controller.
- `IP string`: Device IP address.
- `Mac string`: Device MAC address.
- `Model string`: UniFi hardware model identifier.
- `Version string`: Firmware version string.
- `Type string`: Device family tag set by this package as `uap`, `usw`, `usg`, `udm`, or `uxg`.
- `Status int`: Raw device state converted with `State.Int()`. The code comment marks `1` as online.
### `NetworkConf`
Direct mapping of a UniFi `networkconf` entry returned by the controller API.
Fields:
- `ID string`: Raw network identifier from `_id`.
- `Name string`: Network name.
- `Purpose string`: Network purpose from `purpose`, such as `wan`, `corporate`, or `remote-user-vpn`.
- `IPSubnet string`: CIDR subnet string from `ip_subnet`.
- `VLAN int`: VLAN ID from `vlan`. `0` means untagged.
- `VLANEnabled bool`: Whether VLAN tagging is enabled.
- `Enabled bool`: Whether the network entry is enabled.
- `NetworkGroup string`: Network group from `networkgroup`, such as `LAN`, `WAN`, or `WAN2`.
- `NetworkIsolationEnabled bool`: Whether network isolation is enabled.
- `InternetAccessEnabled bool`: Whether internet access is enabled for the network.
- `IsNAT bool`: Whether NAT is enabled.
- `DHCPEnabled bool`: Whether the controller DHCP server is enabled for the network.
- `DHCPStart string`: DHCP range start address.
- `DHCPStop string`: DHCP range end address.
- `DHCPDNS1 string`: Primary DHCP DNS server.
- `DHCPDNS2 string`: Secondary DHCP DNS server.
- `DHCPDNSEnabled bool`: Whether custom DHCP DNS servers are enabled.
- `MDNSEnabled bool`: Whether mDNS is enabled.
- `FirewallZoneID string`: Firewall zone identifier from `firewall_zone_id`.
- `GatewayType string`: Gateway type from `gateway_type`.
- `VPNType string`: VPN type from `vpn_type`.
- `WANType string`: WAN type from `wan_type`, such as `pppoe`, `dhcp`, or `static`.
- `WANNetworkGroup string`: WAN network-group value from `wan_networkgroup`.
### `Route`
Single routing-table entry returned by the controller gateway routing endpoint.
Fields:
- `Network string`: Route prefix in CIDR form from `pfx`.
- `NextHop string`: Next-hop address or interface from `nh`.
- `Interface string`: Interface name from `intf`.
- `Type string`: Raw route type code from `type`.
- `Distance int`: Administrative distance.
- `Metric int`: Route metric.
- `Uptime int`: Route uptime in seconds.
- `Selected bool`: Whether the route is installed in the forwarding table, taken from `fib`.
This package exports no interfaces or type aliases.
## Functions
### `New(url, user, pass, apikey string, insecure bool) (*Client, error)`
Creates a UniFi client from explicit controller settings. It builds a `uf.Config`, creates the underlying SDK client, replaces its HTTP client with one that enforces TLS 1.2, and sets `InsecureSkipVerify` from `insecure`.
### `NewFromConfig(flagURL, flagUser, flagPass, flagAPIKey string, flagInsecure *bool) (*Client, error)`
Resolves controller settings through `ResolveConfig`, requires either a username or an API key to be present, and then delegates to `New`.
### `ResolveConfig(flagURL, flagUser, flagPass, flagAPIKey string, flagInsecure *bool) (url, user, pass, apikey string, insecure bool, err error)`
Builds the effective controller configuration in three layers: config-file values from `forge.lthn.ai/core/config`, environment overrides from `UNIFI_URL`, `UNIFI_USER`, `UNIFI_PASS`, `UNIFI_APIKEY`, and `UNIFI_INSECURE`, then non-empty flag overrides plus a non-nil `flagInsecure`. If no URL is resolved, it falls back to `DefaultURL`. If `config.New()` fails, the function still returns values from env, flags, and the default URL without surfacing that config-load error.
### `RouteTypeName(code string) string`
Maps UniFi route type codes to human-readable names: `S` to `static`, `C` to `connected`, `K` to `kernel`, `B` to `bgp`, and `O` to `ospf`. Any other code is returned unchanged.
### `SaveConfig(url, user, pass, apikey string, insecure *bool) error`
Persists non-empty controller settings to the standard config store. The function writes only the values that were provided, writes the insecure flag only when the pointer is non-nil, and commits the config file after all updates succeed.