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:
- Direct hosts.
localhost,127.0.0.1(and the rest of127.*),::1and*.localhostare always sent directly. So is every host in theNO_PROXYenvironment variable, which accepts exact hosts, domain suffixes such as.corp.example,host:portentries and*. - HTTPS targets are tunnelled through the proxy with HTTP
CONNECT, so the proxy never sees the request contents. Certificate verification (and# @insecure) applies to the target server as usual. - HTTP targets are sent to the proxy as ordinary absolute-URL requests.
- Proxy URL schemes.
http://andhttps://proxy URLs are supported. SOCKS proxies (socks5://) are not.
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:
- 301, 302 and 303 continue with a
GETand no body (aHEADstays aHEAD). - 307 and 308 keep the original method and body.
- The
Authorizationheader is dropped when a redirect goes to a different host or port, so a token for one service does not leak to another.
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
- Header names keep your casing.
X-API-Keygoes out asX-API-Key, not lower-cased. That matters for the occasional legacy server or signature scheme that compares header names exactly. - Compressed responses are decoded. Plainwire asks for
gzip, deflate, brunless you set your ownAccept-Encoding, and decompresses the body for display. The size shown is the number of body bytes on the wire, that is the compressed size, which is what a# @assert sizecheck compares against too.
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
ECONNREFUSED: nothing is listening at that host and port. Check that the server is running and the port is right. If the server listens only on IPv4, try127.0.0.1instead oflocalhost.ENOTFOUND: the hostname did not resolve. Look for a typo, an unset{{baseUrl}}(pick an environment), or a VPN that is not connected.Timed out after 60000 ms: the whole exchange, including redirects and the body, took longer thanplainwire.timeoutMs(60000 by default;0means no timeout). Raise it for slow endpoints, or check whether a proxy is needed.- Certificate errors: see self-signed and invalid certificates above.
Proxy CONNECT to host:443 failed: 407: the proxy needs credentials. Put them in the proxy URL:http://user:pass@proxy:8080.
Settings reference
| Setting or comment | Default | Effect |
|---|---|---|
# @insecure | Skip certificate verification for one request | |
plainwire.rejectUnauthorized | true | false skips certificate verification for all requests |
plainwire.proxy | empty | HTTP proxy URL; falls back to http.proxy, then HTTPS_PROXY / HTTP_PROXY |
# @no-redirect | Do not follow redirects for one request | |
plainwire.followRedirects | true | false stops following redirects everywhere |
plainwire.timeoutMs | 60000 | Timeout for the whole request in milliseconds; 0 disables it |
For the rest of the file format, see the .http syntax cheat sheet.