Self-signed certificates, proxies and localhost in a VS Code API client

Local development servers often use HTTPS with a certificate nobody signed, sit on an unusual port, or can only be reached through a company proxy. From version 0.2.0, Plainwire sends requests with Node’s own http and https modules from the VS Code extension host, which lets it handle all three cases and gives you direct control over TLS checks, proxies, redirects and headers. Each option is either one comment line in a .http file or one VS Code setting.

Everything on this page needs Plainwire 0.2.0 or newer. Install the .vsix from the latest GitHub release (see install steps).

Self-signed and invalid certificates

By default Plainwire verifies TLS certificates, just as a browser does. A dev server with a self-signed certificate, a certificate from a local CA your system does not trust, an expired certificate or one issued for a different hostname fails with an error such as:

Request failed: DEPTH_ZERO_SELF_SIGNED_CERT: self-signed certificate.
Set "plainwire.rejectUnauthorized": false to accept it (or add # @insecure above the request).

Other common variants are unable to verify the first certificate, self-signed certificate in certificate chain, certificate has expired and a hostname mismatch. Each one carries the same hint.

Per request: # @insecure

Add # @insecure above the request line. Only that request skips certificate verification; every other request in the file is still checked.

### Local API with a self-signed certificate
# @insecure
GET https://localhost:5001/api/health
Accept: application/json

Everywhere: plainwire.rejectUnauthorized

To turn verification off for every request, put this in your user or workspace settings.json:

{
  "plainwire.rejectUnauthorized": false
}

Security note. Turning off verification means Plainwire will accept any certificate, including one presented by someone intercepting the connection. Only do it for hosts you control, such as localhost or a dev box on your own network. Prefer # @insecure on the specific request over the global setting, so a request to a real API is never sent unverified by accident, and never commit "plainwire.rejectUnauthorized": false to a shared workspace configuration.

Any port works

Tools built on the fetch() API, including Node’s built-in fetch, refuse to connect to a list of “bad ports” defined by the WHATWG Fetch standard, for example 6000, 6665–6669 and 10080. The rule protects browsers from being used against non-HTTP services, but it also blocks a local service that happens to listen there. Plainwire does not use fetch, so a request to any port is sent as written:

GET http://localhost:6000/status

###
GET http://127.0.0.1:10080/metrics

Proxies

Set an HTTP proxy, with credentials if it needs them:

{
  "plainwire.proxy": "http://user:pass@proxy.corp.example:8080"
}

If plainwire.proxy is empty, Plainwire uses VS Code’s own http.proxy setting, and if that is empty too, the HTTPS_PROXY or HTTP_PROXY environment variable (lower-case spellings also work). In practice:

NO_PROXY=localhost,.corp.example,build-server:8443

Environment variables are read from the VS Code process, so set them before you start VS Code (for example in the shell you launch code from).

Redirects

Redirects are followed automatically, up to 10 in a row. The rules follow common HTTP client behaviour:

To see the redirect itself (its status and Location header), turn following off for one request with # @no-redirect, or for all requests with "plainwire.followRedirects": false:

### Check where the login page sends us
# @no-redirect
# @assert status == 302
# @assert header location startsWith /dashboard
GET https://localhost:5001/login
Cookie: session={{session}}

The # @assert lines are response checks; see API tests in .http files.

Headers and compression

GET https://localhost:5001/api/report
X-API-Key: {{$dotenv API_KEY}}
Accept-Encoding: identity

Sending Accept-Encoding: identity, as above, asks the server for an uncompressed body, so the size shown is the full body size.

Troubleshooting

Settings reference

Setting or commentDefaultEffect
# @insecureSkip certificate verification for one request
plainwire.rejectUnauthorizedtruefalse skips certificate verification for all requests
plainwire.proxyemptyHTTP proxy URL; falls back to http.proxy, then HTTPS_PROXY / HTTP_PROXY
# @no-redirectDo not follow redirects for one request
plainwire.followRedirectstruefalse stops following redirects everywhere
plainwire.timeoutMs60000Timeout for the whole request in milliseconds; 0 disables it

For the rest of the file format, see the .http syntax cheat sheet.