feat(desktop): open ports over https via ports.json protocol field

Closed
EV
3mo ago
+146-36

What

Adds an optional protocol field ("http" | "https") to each entry in a
workspace's .superset/ports.json. When set to "https", the sidebar's
port-open action opens https://localhost:PORT instead of http://.

{
  "ports": [
    { "port": 3000, "label": "Frontend Dev Server", "protocol": "https" },
    { "port": 8080, "label": "API Server" }
  ]
}

Why

Port open actions were hardcoded to http://localhost:PORT
(usePortOpenActions.ts, MergedPortBadge.tsx). Dev servers running behind a
local TLS cert (e.g. mkcert) 301/refuse on http://, so opening them from
the sidebar lands on a broken page and you have to retype the URL with
https://. There was no config or preference to control the scheme.

This rides the same rails the existing label field already uses, so it's
purely additive and backward compatible — omit protocol and behavior is
unchanged (defaults to http).

How

protocol is resolved from ports.json alongside label and travels the two
existing paths that carry label to the renderer:

  • Query path: parseStaticPortsConfig → static-port label caches (desktop
    • host-service) → ports.getAll enrichment → EnrichedPort /
      DashboardSidebarPort.
  • Event path: host-service port:changed broadcast → workspace-client
    PortChangedPayload → applyPortEventsToHostPortsResult.

Both the v2 sidebar (usePortOpenActions) and the v1 sidebar
(MergedPortBadge) then build the URL as
`${port.protocol ?? "http"}://localhost:${port.port}`.

The label caches' Map<number, string> (port → label) becomes
Map<number, StaticPortLabel> so the same lookup yields both label and
protocol.

Validation

parseStaticPortsConfig rejects any protocol that isn't exactly "http" or
"https" with ports[N].protocol must be "http" or "https", consistent with
the existing per-field error messages. Malformed files are still ignored
wholesale (unchanged behavior).

Testing

  • bun run typecheck
  • bun run lint
  • bun run test — added cases:
    • static-ports loader: loads https/http, omits when absent, rejects an
      invalid protocol.
    • applyPortEventsToHostPortsResult: carries protocol from an add event
      onto the port row.

Notes

  • Backward compatible: entries without protocol serialize and behave exactly
    as before (toEqual on existing loader fixtures is unchanged).
  • Docs updated: apps/docs/content/docs/ports.mdx.
  • Happy to split or convert to an issue-first discussion if you'd prefer — kept
    it to one focused change per the contributing guide.
Open in Stage

Summary by cubic

Add optional HTTPS support for sidebar port-open actions via a new protocol field in .superset/ports.json. Defaults to HTTP, so existing configs work unchanged.

  • New Features
    • Add protocol ("http" | "https") to .superset/ports.json; when set to "https", ports open at https://localhost:PORT.
    • Thread protocol through label cache, host port:changed events, TRPC, and renderer; exposed on EnrichedPort and PortChangedPayload.
    • Update open actions in usePortOpenActions and MergedPortBadge to use protocol ?? "http".
    • Validate values in @superset/port-scanner; tests and docs updated.

Summary by CodeRabbit

  • New Features
    • Added optional per-port protocol settings for http or https.
    • Port listings and live updates now retain and display protocol information.
    • Opening a port now uses its configured protocol, defaulting to HTTP.
  • Bug Fixes
    • Improved handling of missing or invalid protocol values.
  • Documentation
    • Updated port configuration guidance with protocol examples and HTTPS behavior.
  • Tests
    • Added coverage for valid, missing, and invalid protocol configurations.