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

docs(specs): add package API docs

Browse source 
Co-Authored-By: Virgil <virgil@lethean.io>
This commit is contained in:
Virgil 2026-03-27 20:18:49 +00:00
parent 008b1498ab
commit 590bfa9968
2 changed files with 110 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

12
specs/cmd/unifi.md Normal file
View file

@ -0,0 +1,12 @@
# unifi
**Import:** `forge.lthn.ai/core/go-netops/cmd/unifi`
**Files:** 7
## Types
This package exports no structs, interfaces, or type aliases.
## Functions
### `AddUniFiCommands(root *cli.Command)`
Registers the top-level `unifi` CLI command on `root` and attaches the package's `config`, `clients`, `devices`, `networks`, `routes`, and `sites` subcommands.

98
specs/unifi.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 create 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 requested 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 filter 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` directly, 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` directly, 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 how `(*Client).GetClients` scopes and filters client results.
Fields:
- `Site string`: Site name to query. An empty value means all sites returned by `GetSites`.
- `Wired bool`: When true, include wired clients.
- `Wireless bool`: When true, include wireless clients.
### `DeviceInfo`
Flat infrastructure-device view 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 populated by this package as `uap`, `usw`, `usg`, `udm`, or `uxg`.
- `Status int`: Raw device state converted with `State.Int()`. The code treats `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 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`: Raw network group value such as `LAN`, `WAN`, or `WAN2`.
- `NetworkIsolationEnabled bool`: Whether UniFi 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`: Raw firewall zone identifier.
- `GatewayType string`: Raw gateway type value.
- `VPNType string`: Raw VPN type value for VPN networks.
- `WANType string`: WAN type such as `pppoe`, `dhcp`, or `static`.
- `WANNetworkGroup string`: Raw 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` when `insecure` is true.
### `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.