docs(hmr): document hmr.protocol setting

[stanhu]

I wasn't sure if protocol should be http / https or ws / or wss. This commit documents that it should be the latter.

What is the purpose of this pull request?

• Bug fix
• New Feature
• Documentation update
• Other

Before submitting the PR, please make sure you do the following

• Read the Contributing Guidelines, especially the Pull Request Guidelines.
• Check that there isn't already a PR that solves the problem the same way to avoid creating a duplicate.
• Provide a description in this PR that addresses what the PR is solving, or reference the issue that it solves (e.g. fixes #123).
• Update the corresponding documentation if needed.
• Ideally, include relevant tests that fail without this PR but pass with it.

[bolt-new-by-stackblitz]

Run & review this pull request in StackBlitz Codeflow.

[sapphi-red]

Thanks!

BTW soon we will be able to pass http and https as well (whatwg/websockets#45).

[stanhu]

@sapphi-red Interesting, thanks! I was doing some testing with Vite HMR and trying to set the Content Security Policy, but I noticed sometimes even though wss://hmr.example.com/vite-dev were allowed, I'd see a block on https://hmr.example.com/vite-dev. Does Vite fall back to HTTPS if the Websocket doesn't work?

[sapphi-red]

When the Vite server is stopped, the script injected by Vite sends a request periodically to the same path to reload the page when the Vite server is started again. I think those requests are the ones that are blocked.

[stanhu]

In my test, I have this config:

{
  "enabled": true,
  "host": "127.0.0.1",
  "port": 3038,
  "hmr": {
    "clientPort": 3443,
    "host": "host.docker.internal",
    "protocol": "wss"
  }
}

Thus, the Vite server should be accessed via http://127.0.0.1:3038, but the HMR endpoint should be wss://host.docker.internal:3443.

I have a headless Chrome test that spins up on an arbitrary port (55498 below), and it uses a proxy server to block all external network access. When host.docker.internal is not in the proxy bypass list, I see the following errors, which suggests the Vite client for some reason is trying to use https instead of wss. Note that wss://host.docker.internal is in the Content Security Policy:

         http://127.0.0.1:55498/vite-dev/@vite/client 663 Refused to connect to 'https://host.docker.internal:3443/vite-dev/' because it violates the following Content Security Policy directive: "connect-src 'self' http://localhost:* ws://localhost:* wss://localhost:* ws://host.docker.internal:* wss://host.docker.internal:* localhost".

            http://127.0.0.1:55498/vite-dev/@vite/client 663 Refused to connect to 'https://host.docker.internal:3443/vite-dev/' because it violates the document's Content Security Policy.

This error seems to go away if I enter host.docker.internal into the proxy bypass list. I'm not sure if this is because Vite is attempting to fall back to HTTPS, or if Chrome is trying to proxy the Websocket connection through HTTPS for some reason. I didn't see the error messages listed here:

vite/packages/vite/src/client/client.ts

Lines 43 to 53 in 8dc1b73

	const currentScriptHostURL = new URL(import.meta.url)
	const currentScriptHost =
	currentScriptHostURL.host +
	currentScriptHostURL.pathname.replace(/@vite\/client$/, '')
	console.error(
	'[vite] failed to connect to websocket.\n' +
	'your current setup:\n' +
	` (browser) ${currentScriptHost} <--[HTTP]--> ${serverHost} (server)\n` +
	` (browser) ${socketHost} <--[WebSocket (failing)]--> ${directSocketHost} (server)\n` +
	'Check out your Vite / network configuration and https://vitejs.dev/config/server-options.html#server-hmr .',
	)

[stanhu]

Ah, I see that the ping here attempts to use https:

vite/packages/vite/src/client/client.ts

Lines 320 to 327 in 899d9b1

	const pingHostProtocol = socketProtocol === 'wss' ? 'https' : 'http'
	const ping = async () => {
	// A fetch on a websocket URL will return a successful promise with status 400,
	// but will reject a networking error.
	// When running on middleware mode, it returns status 426, and an cors error happens if mode is not no-cors
	try {
	await fetch(`${pingHostProtocol}://${hostAndPath}`, {

[stanhu]

BTW soon we will be able to pass http and https as well (whatwg/websockets#45).

Obviously the code above would need to be changed if http or https were used. Otherwise the ping would attempt to use http when socketProtocol were https.

[sapphi-red]

Ah, yeah, that code needs to be changed to socketProtocol === 'wss' || socketProtocol === 'https' to support http/https.

[stanhu]

@sapphi-red Do you know how to update https://vitejs.dev/config/server-options#server-hmr? I'm not seeing these changes there.

[sapphi-red]

@stanhu It'll be updated when we trigger it manually, it's now updated.