go-netops/specs/unifi/RFC.md

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.