73 lines
3.2 KiB
Markdown
73 lines
3.2 KiB
Markdown
# AGENTS.md
|
|
|
|
Project-level instructions for working in this repository. Read this before
|
|
touching the filesystem.
|
|
|
|
## What this is
|
|
|
|
Go helper packages for talking to a [Wingbits](https://wingbits.com) ADS-B
|
|
station (e.g. the MGW310) and decoding the readsb / tar1090 JSON files it serves.
|
|
|
|
Module: `gitea.libretechconsulting.com/rmcguire/wingbits` (Go 1.26).
|
|
|
|
## Layout
|
|
|
|
```
|
|
pkg/types/readsb # decode types for aircraft/receiver/stats/outline + aircraft filters
|
|
pkg/types/wingbits # decode types for diagnostics/metrics/status (+ Prometheus text parser)
|
|
pkg/client # HTTP Client: query + stream every endpoint, returns the types above
|
|
cmd/wingbits # flag-driven CLI for one-off queries (test/utility tool)
|
|
```
|
|
|
|
Rules of the split:
|
|
|
|
- `pkg/types/*` is **decode-only**. No HTTP, no I/O beyond `encoding/json` and the
|
|
Prometheus text parser. These packages must not import `pkg/client`.
|
|
- `pkg/client` owns all transport/request logic and depends on both type packages.
|
|
- Keep the two type packages independent of each other.
|
|
|
|
## Station topology (important for endpoint routing)
|
|
|
|
A station exposes two HTTP roots; both are plaintext HTTP on the test unit:
|
|
|
|
| Root | Default port | Serves |
|
|
|-----------|--------------|---------------------------------------------------------------|
|
|
| Wingbits | `:8088` | `/network/diagnostics`, `/metrics`, `/tailscale/status`, and readsb files under `/readsb/` |
|
|
| tar1090 | `:8504` | readsb files under `/data/`, plus `/data/outline.json` |
|
|
|
|
`outline.json` is **only** served by the tar1090 root. When a tar1090 endpoint is
|
|
configured it overrides the Wingbits root for all readsb files.
|
|
|
|
## Testing
|
|
|
|
```
|
|
go test ./...
|
|
```
|
|
|
|
Tests decode captured fixtures in each package's `testdata/` directory and drive
|
|
the client against an `httptest` server. `pkg/client` reuses the fixtures from
|
|
`pkg/types/*/testdata` (a single source of truth — do not duplicate them).
|
|
|
|
The live reference unit is an **MGW310 at `192.168.0.127`** (also
|
|
`miner.mcguire.local`), plaintext HTTP on all ports. Re-capture fixtures from it
|
|
with `curl` when fields change; never hand-edit `testdata/` payloads.
|
|
|
|
## Coding standards
|
|
|
|
- Go only. Keep functions within ~25 lines; decompose helpers as needed.
|
|
- Every package has a package comment (Go convention) in one of its files.
|
|
- Comment only the non-obvious. Field docs on the decode structs are intentional
|
|
— they capture readsb/Wingbits semantics that aren't evident from the name.
|
|
- The known JSON quirks to preserve when editing decode types:
|
|
- `alt_baro` may be the string `"ground"` instead of a number → `readsb.AltBaro`.
|
|
- readsb timestamps are fractional-second Unix floats → `readsb.UnixTime`.
|
|
- `outline.json` points are `[lat, lon, altFeet]` tuples → `readsb.RangePoint`.
|
|
|
|
## Changelog
|
|
|
|
`CHANGELOG.md` follows [Keep a Changelog](https://keepachangelog.com/) and
|
|
SemVer. Record every user-facing change under `## [Unreleased]` as part of the
|
|
change itself — don't defer it to release time. When tagging a release, rename
|
|
`[Unreleased]` to the new version with the date and add a fresh empty
|
|
`[Unreleased]` section plus its compare link at the bottom.
|