testing-portal-tunnel-dashboard
How to drive the portal-tunnel agent dashboard bubbletea TUI end-to-end without a live agent or relay, using a stub control server plus a fabricated agent-endpoint.json.
gosuda · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add gosuda/portal-tunnel --skill testing-portal-tunnel-dashboard技能说明
name: testing-portal-tunnel-dashboard description: How to drive the portal-tunnel agent dashboard bubbletea TUI end-to-end without a live agent or relay, using a stub control server plus a fabricated agent-endpoint.json.
Testing the portal-tunnel agent dashboard TUI standalone
The portal-tunnel agent dashboard TUI looks like it needs a running agent, but it only needs two things: a state dir containing agent-endpoint.json, and an HTTP server at the endpoint's control_addr that speaks the control API envelope.
How the dashboard gets its data
portal-tunnel agent dashboard --state-dir DIRreadsDIR/agent-endpoint.json(cmd/portal-tunnel/agent/control.go,endpointFilename = "agent-endpoint.json").- The file is
{"control_addr":"HOST:PORT","token":"TOKEN"}. - Every poll tick it issues
GET http://<control_addr>/agent/statuswithAuthorization: Bearer <token>(types.PathAgentStatus). - Responses must use the repo's API envelope:
{"ok": true, "data": <AgentStatusResponse>}. Returning the raw status object without the envelope yields "Agent unavailable: api response is not ok" in the TUI. AgentStatusResponse/AgentTunnelStatusshapes live incmd/portal-tunnel/agent/api_types.go(tunnels[].metadataistypes.LeaseMetadata).
Recipe
go build -o /tmp/portal-tunnel ./cmd/portal-tunnel- Write a stub HTTP server that answers
GET /agent/statuswith{"ok":true,"data":{...}}containing a fabricated tunnel (id, name, state "running", target_addr, max_active_relays, metadata, relays[]). Other paths can return an error — the TUI only shows them if you trigger an action. mkdir -p /tmp/dash-state && printf '{"control_addr":"127.0.0.1:PORT","token":"tk"}' > /tmp/dash-state/agent-endpoint.json- Launch on the KDE desktop:
DISPLAY=:0 konsole -e /tmp/portal-tunnel agent dashboard --state-dir /tmp/dash-state, thenwmctrl -r "portal-tunnel" -b add,maximized_vert,maximized_horz(height matters — settings/add-tunnel rows are clipped to pane height). - The TUI self-populates on the next poll tick — no restart needed when the stub comes up.
Driving the TUI
- Mouse clicks work (
tea.WithMouseCellMotion): clickable regions include section titles, buttons, tunnel/relay rows, and full-width input rows. Clicking an input row focuses that field viaagentDashboardActionFocus{Settings,AddTunnel}Field. - Keys: left/right cycle panes; tab/down & shift+tab/up cycle fields within add-tunnel and settings panes;
esccancels add-tunnel input;ctrl+cquits. - "Add Tunnel" button toggles the form locally (
m.addingTunnel) — the 11-row form renders without any backend round-trip. - Settings input rows only render when
status.tunnelsis non-empty and a tunnel is selected — the fabricated status must contain at least one tunnel.
Verifying provider input validation without credentials
The six portal/acme/* providers (cloudflare, gcloud, hetzner, njalla, route53, vultr) validate method inputs in internal/dnsrecord before hitting the network, and all have exported constructors. A throwaway Go module with replace github.com/gosuda/portal-tunnel/v2 => <repo> can call e.g. p.EnsureARecord(ctx, "", "1.2.3.4") and assert exact error strings ("record name is required", invalid ipv4 address: "...", etc.).
Two providers gate before or right after the input checks:
- cloudflare checks
p.tokenbefore validating inputs — construct with any nonempty token (cloudflare.New("tk")) or you getcloudflare token is requiredinstead of the input error. - gcloud validates inputs first, then resolves credentials — an invalid input still yields the input error, but the next failure is
load gcloud credentialson a machine without ambient ADC, orgcloud project id is requiredwhen credentials resolve but carry no project.
Set AWS_EC2_METADATA_DISABLED=true so route53 credential resolution fails fast instead of probing IMDS. Optional stronger check (hits real APIs — skip for offline runs): with a syntactically valid input + fake token, hetzner, njalla, and vultr reach their real HTTP APIs and return 401s — proof inputs traversed the full path.
Repo conventions worth knowing
- AGENTS.md: run tests only when explicitly requested; CI commands are
make vet,make lint,make test. make lintneeds golangci-lint + gojgp; both install viamake installinto~/go/bin(add/usr/local/go/binand~/go/binto PATH).- Scoped testing preferred:
go test -v -count=1 ./portal/acme/internal/dnsrecord/+go test -v -count=1 ./sdk/ -run 'TestMITMProbeDialAddress'rather than the whole suite.
Devin Secrets Needed
None for the above. Real end-to-end DNS provider testing would need live provider credentials/zones (cloudflare token, AWS keys, hetzner/njalla/vultr tokens, GCP service account) plus a test domain — request only if a future change requires true provider round-trips.