HydraIssues

Background

Hydraneck currently talks to MikroTik routers via the binary RouterOS API (github.com/go-routeros/routeros/v3, port 8728/8729) in pkg/mikrotik/client.go. This works but has two limitations as we move toward agent-driven operation and live event debugging:

1. Binary API responses are flat strings parsed by hand — awkward to surface as typed agent tools and hard to debug without the Go binary.
2. We hit a real debugging gap during the streaming event last Friday — no live view of WAN bandwidth, queue drops, or firewall log events from the venue router.

Decision

Hybrid approach:

• REST API (default) for all typed operations agents and the web UI use: DHCP leases, WireGuard peer config, one-shot bandwidth, ping, RouterOS version. Standard net/http + JSON. Drop-in replacement for the current pkg/mikrotik/client.go. Drops the go-routeros dependency from the default code path.
• Binary API (debug-only subpackage) for subscription/streaming commands that REST cannot deliver: /interface/monitor-traffic (live deltas), /log/print follow=yes, /tool/torch, queue stat streams. Lives in pkg/mikrotik/debug and exposed via Server-Sent Events from hydraneck (/api/venue/{id}/router/tail, /api/venue/{id}/router/bandwidth/stream, etc.). Used by the web UI and by explicit agent debug sessions — not part of the default agent tool surface.

Why both, not REST-only

REST is one-shot. Polling REST every 1-2s smears microbursts and misses the kind of sub-second events that cause stream stutters. The binary API supports server-pushed deltas for the commands above, which is the right shape for a live-tail debug view during an event.

Binary API code stays small and isolated to pkg/mikrotik/debug, so it does not bleed into the typed surface that agents see.

Requirements

• RouterOS v7.1+ on every venue MikroTik (REST was introduced in 7.1). To be enforced by hydraneck scan reporting per-router version; venues on v6 must upgrade before onboarding.
• Network admin must grant hydraneck read access to:
  • HTTPS / www-ssl service on the router (for REST, port 443 by default — confirm per venue)
  • TCP 8728 (plain) or 8729 (TLS) for the binary API debug taps
  • Both restricted to hydraneck's source IP

Out of scope

• Existing typed Go interfaces (router.Router, BandwidthMonitor) stay unchanged. Only the implementation underneath swaps from binary to REST for the default path.
• No agent-facing API contract changes.
• Omada client (pkg/omada/) is unaffected.

Files affected (when implementation lands)

• pkg/mikrotik/client.go — rewrite to use REST
• pkg/mikrotik/wireguard.go — rewrite to use REST
• pkg/mikrotik/debug/ — new subpackage for binary-API streams
• pkg/api/ — add SSE endpoints for live debug
• internal/cli/scan.go — surface RouterOS version, flag <v7.1
• go.mod — go-routeros stays (debug package); no new deps for REST