browser

type Action ¶

type Action int

Action is the connection-ladder outcome for a given Probe.

const (
	Attach           Action = iota // attach to Probe.Endpoint (Path B)
	Launch                         // launch a managed Chrome (Path A fallback)
	InstructToggle                 // Chrome is running but not debug-enabled — guide the launch flag / chrome://inspect
	InstructNoLaunch               // nothing debug-enabled and --no-launch — print the launch command
	ConsentPending                 // open port, hanging upgrade — Chrome is holding its consent prompt
)

func DecideConnection(p Probe) Action

func (a Action) String() string

type Endpoint ¶ added in v0.2.0

type Endpoint struct {
	// URL is the ws:// (port-file path) or http:// (explicit --port) endpoint,
	// or "" when none was found.
	URL string
	// PortFile is the DevToolsActivePort file URL came from, "" when an
	// explicit --port was used (there is no file in that case).
	PortFile string
	// Err is set when a port file was found and could not be read or parsed —
	// distinct from "no endpoint", because the remedy is different.
	Err error
}

Endpoint is where a command should try to reach Chrome, and how that was decided. It exists because two callers have to agree on it: chrome.Connect, which attaches, and `doctor`, which diagnoses. doctor used to read the port file directly and ignore --port entirely, so `doctor --port 9333` probed a different browser than the one the flag named and reported IT healthy.

func FindEndpoint(portFileOverride string, port int) Endpoint

type Probe ¶

type Probe struct {
	// Endpoint is where Chrome was looked for: a ws:// URL from
	// DevToolsActivePort, an http:// one from --port, or "" if neither
	// resolved. It was called PortFileWS, which was untrue of half the values
	// it holds.
	//
	// The ladder does not read it: WS already implies it, since an upgrade can
	// only be attempted against an endpoint. It is here because a Probe is a
	// record of what was observed, and "where" is part of that.
	Endpoint      string
	WS            WSState // what one WebSocket upgrade against Endpoint did
	ChromeRunning bool    // is a Chrome process running (possibly without debug)?
	NoLaunch      bool    // the --no-launch flag
}

Probe captures the observable connection state the ladder decides on.

type WSState ¶ added in v0.2.0

type WSState int

WSState is what one WebSocket upgrade against Chrome's browser-level debug endpoint actually did. It is three-way, and that is the whole point.

While consent for a fresh attach is pending, Chrome does not refuse the connection: it accepts the TCP connect, then holds the upgrade open and says nothing until the user answers a browser-modal dialog. There is no error to classify — only silence. A boolean "reachable" collapses that silence into the same value as a refused port, so the tool cannot tell "nothing is listening" (a real failure, and fast) from "Chrome is waiting for a human" (not a failure at all, and slow by nature). Splitting them is what lets a refused endpoint keep failing in milliseconds while a pending one is waited out for minutes.

Note that Chrome's HTTP JSON API is NOT a substitute signal: on the chrome://inspect toggle path GET /json/version answers 404 whether or not consent has been granted. Only the upgrade distinguishes the states.

const (
	// WSRefused: nothing accepted the connection, or something answered the
	// upgrade with anything other than 101 (a stale port file, a different
	// server on the port). A real failure.
	WSRefused WSState = iota
	// WSPending: the port accepted and the upgrade never completed. This is the
	// consent signature.
	WSPending
	// WSReady: the upgrade completed — the endpoint is live and consented.
	WSReady
)

func (s WSState) String() string