From 590bfa9968548df34b4c129b22f1b860b1aa4cd3 Mon Sep 17 00:00:00 2001 From: Virgil Date: Fri, 27 Mar 2026 20:18:49 +0000 Subject: [PATCH] docs(specs): add package API docs Co-Authored-By: Virgil --- specs/cmd/unifi.md | 12 ++++++ specs/unifi.md | 98 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 110 insertions(+) create mode 100644 specs/cmd/unifi.md create mode 100644 specs/unifi.md diff --git a/specs/cmd/unifi.md b/specs/cmd/unifi.md new file mode 100644 index 0000000..581e234 --- /dev/null +++ b/specs/cmd/unifi.md @@ -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. diff --git a/specs/unifi.md b/specs/unifi.md new file mode 100644 index 0000000..142528f --- /dev/null +++ b/specs/unifi.md @@ -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. -- 2.45.3