mirror of
https://github.com/unpoller/unpoller.git
synced 2026-03-31 06:24:21 -04:00
969445fade
- Add .cursorrules for Cursor AI - Add CLAUDE.md for Claude Code - Add AGENTS.md for universal AI agent context - Add .github/copilot-instructions.md for GitHub Copilot These files provide comprehensive context about the UnPoller project architecture, coding standards, and development patterns to help AI coding assistants understand and work with the codebase effectively.
128 lines
3.2 KiB
Markdown
128 lines
3.2 KiB
Markdown
# UnPoller - GitHub Copilot Instructions
|
|
|
|
## Project Overview
|
|
|
|
UnPoller is a Go application that collects metrics and events from UniFi network controllers and exports them to monitoring backends (InfluxDB, Prometheus, Loki, DataDog, MySQL). The application uses a plugin-based architecture with a generic core.
|
|
|
|
## Architecture
|
|
|
|
### Plugin System
|
|
- **Core Library** (`pkg/poller/`): Generic plugin system with input/output interfaces
|
|
- **Input Plugins**: Collect data (e.g., `pkg/inputunifi/`)
|
|
- **Output Plugins**: Export data to backends (e.g., `pkg/influxunifi/`, `pkg/promunifi/`)
|
|
- **Plugin Discovery**: Automatic via blank imports in `main.go`
|
|
|
|
### Key Interfaces
|
|
|
|
**Input Interface**:
|
|
```go
|
|
type Input interface {
|
|
GetMetrics() (*Metrics, error)
|
|
GetEvents() (*Events, error)
|
|
}
|
|
```
|
|
|
|
**Output Interface**:
|
|
```go
|
|
type Output interface {
|
|
WriteMetrics(*Metrics) error
|
|
WriteEvents(*Events) error
|
|
}
|
|
```
|
|
|
|
## Code Style
|
|
|
|
### Go Conventions
|
|
- Go 1.25.5+
|
|
- Use `gofmt` formatting
|
|
- Follow `.golangci.yaml` linting rules
|
|
- Enabled linters: `nlreturn`, `revive`, `tagalign`, `testpackage`, `wsl_v5`
|
|
|
|
### Naming
|
|
- Packages: `lowercase`
|
|
- Exported: `PascalCase`
|
|
- Unexported: `camelCase`
|
|
- Errors: Always `err`, check immediately
|
|
|
|
### Error Handling
|
|
```go
|
|
if err != nil {
|
|
return fmt.Errorf("context: %w", err)
|
|
}
|
|
```
|
|
|
|
### Configuration
|
|
All config structs must include format tags:
|
|
```go
|
|
type Config struct {
|
|
Field string `json:"field" toml:"field" xml:"field" yaml:"field"`
|
|
}
|
|
```
|
|
|
|
Environment variables use `UP_` prefix.
|
|
|
|
## Common Patterns
|
|
|
|
### Plugin Registration
|
|
```go
|
|
func init() {
|
|
poller.RegisterInput(&Input{})
|
|
// or
|
|
poller.RegisterOutput(&Output{})
|
|
}
|
|
```
|
|
|
|
### Device Type Reporting
|
|
Each output plugin has device-specific functions:
|
|
- `UAP()` - Access Points
|
|
- `USG()` - Security Gateways
|
|
- `USW()` - Switches
|
|
- `UDM()` - Dream Machines
|
|
- `UXG()` - Next-Gen Gateways
|
|
- `UBB()` - Building Bridges
|
|
- `UCI()` - Industrial devices
|
|
- `PDU()` - Power Distribution Units
|
|
|
|
### Adding New Plugin
|
|
1. Create package in `pkg/`
|
|
2. Implement `Input` or `Output` interface
|
|
3. Register in `init()`
|
|
4. Add blank import to `main.go`
|
|
5. Add config struct with tags
|
|
6. Create `README.md`
|
|
|
|
## Dependencies
|
|
|
|
### Core
|
|
- `github.com/unpoller/unifi/v5` - UniFi API (local: `/Users/briangates/unifi`)
|
|
- `golift.io/cnfg` - Configuration
|
|
- `golift.io/cnfgfile` - Config parsing
|
|
- `github.com/spf13/pflag` - CLI flags
|
|
|
|
### Outputs
|
|
- InfluxDB: `github.com/influxdata/influxdb1-client`, `github.com/influxdata/influxdb-client-go/v2`
|
|
- Prometheus: `github.com/prometheus/client_golang`
|
|
- DataDog: `github.com/DataDog/datadog-go/v5`
|
|
- Loki: Custom HTTP client
|
|
|
|
## Important Notes
|
|
|
|
- `pkg/poller` core is generic - no UniFi/backend knowledge
|
|
- Support Windows, macOS, Linux, BSD
|
|
- Configuration: TOML (default), JSON, YAML, env vars
|
|
- Always check and return errors
|
|
- Use `context.Context` for cancellable operations
|
|
- Tests in `_test` packages
|
|
- Use `github.com/stretchr/testify` for assertions
|
|
|
|
## When Writing Code
|
|
|
|
1. Follow existing plugin patterns
|
|
2. Keep core library generic
|
|
3. Check all errors
|
|
4. Document exported functions
|
|
5. Write tests in `_test` packages
|
|
6. Consider cross-platform compatibility
|
|
7. Use structured logging
|
|
8. Respect timeouts and deadlines
|