docs: add production documentation and README

Co-Authored-By: Charon <charon@lethean.io>

2026-02-20 15:22:57 +00:00

3.2 KiB

Raw Blame History

Development

Module: forge.lthn.ai/core/go-netops

Prerequisites

Tool	Version	Notes
Go	1.25+	Module uses `go 1.25.5`
core/go	local	`replace` directive in go.mod

The go.mod contains a replace directive pointing at ../go for the forge.lthn.ai/core/go dependency. Ensure the core/go repository is checked out alongside this one (the standard workspace layout handles this).

Build and Test

# Run all tests
go test ./...

# Race detector (required before commit)
go test -race ./...

# Verbose output
go test -v ./...

# Single test
go test -v -run TestResolveConfig ./unifi/

# Coverage
go test -cover ./...

# Vet
go vet ./...

Test Patterns

Tests use net/http/httptest to mock the UniFi controller API. The mock server returns minimal JSON responses ({"meta":{"rc":"ok"}, "data": []}) sufficient for the unpoller SDK to initialise without error.

Config Tests

Config tests isolate the environment by:

Clearing all UNIFI_* and CORE_CONFIG_UNIFI_* environment variables
Using t.Setenv for scoped variable injection
Using t.TempDir() as HOME to avoid polluting real config

What Is Tested

Area	Coverage	Notes
Client creation	Yes	`New`, insecure true/false, invalid URL
Config resolve	Yes	Defaults, env vars, flags, priority order
NewFromConfig	Yes	Success path, missing credentials
SaveConfig	Yes	Round-trip save and re-resolve

What Is Not Tested

The query methods (GetClients, GetDevices, GetDeviceList, GetNetworks, GetRoutes, GetSites) require a live or fully-mocked UniFi controller and are not covered by unit tests. Current coverage is 39%.

Coverage

ok  forge.lthn.ai/core/go-netops/unifi  coverage: 39.0% of statements

Coverage is concentrated on the config resolution and client construction paths. The query methods delegate to the unpoller SDK and would require integration tests against a real or emulated controller to cover meaningfully.

Coding Standards

Language: UK English throughout (comments, docs, commit messages)
Formatting: gofmt (enforced by Go toolchain)
Linting: go vet ./... must pass before commit
Race detector: go test -race ./... must pass before commit
Commit convention: Conventional Commits
```
type(scope): description
```
Examples: feat(unifi): add VLAN filtering, fix(config): handle empty API key

Co-Author: All commits include:

Co-Authored-By: Virgil <virgil@lethean.io>

Dependencies

Module	Role
`forge.lthn.ai/core/go`	Framework (config, logging)
`github.com/unpoller/unifi/v5`	UniFi controller SDK
`github.com/stretchr/testify`	Test assertions

Licence

EUPL-1.2

3.2 KiB Raw Blame History