Conversation
Document the YAML configuration format in detail with annotated client and server examples, per-option descriptions, tunnel examples, and a restriction rules sample that matches the implemented schema. Link the new guide from the README configuration section.
Clarify that top-level `log_lvl` and `no_color` YAML keys are parsed but not yet applied automatically, document `http_upgrade_credentials` as the raw Authorization header value rather than a plain user:password pair, and restate the server JWT options with their actual mode-specific behavior. Also align the README flag description for `--http-upgrade-credentials` with the implementation.
There was a problem hiding this comment.
Pull request overview
Adds a standalone YAML configuration reference to complement the existing CLI/README documentation, and links it from the README so users can find annotated client/server config examples.
Changes:
- Add
docs/CONFIG.mdwith YAML structure, client/server option descriptions, tunnel examples, and restriction-file examples. - Update
README.mdto link todocs/CONFIG.mdand clarify--http-upgrade-credentialsbehavior.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 7 comments.
| File | Description |
|---|---|
| docs/CONFIG.md | New comprehensive YAML configuration guide (client/server + restrictions examples). |
| README.md | Links to the new guide and updates --http-upgrade-credentials wording. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| - `tls_sni_disable`: disable SNI. | ||
| - `tls_ech_enable`: enable ECH if supported by the runtime/server path. |
There was a problem hiding this comment.
tls_sni_disable and tls_ech_enable are described as working options here, but the client TLS config code only applies tls_sni_override and does not reference these fields. Please either implement these behaviors or mark them as currently unsupported/no-op in the YAML guide.
| - `tls_sni_disable`: disable SNI. | |
| - `tls_ech_enable`: enable ECH if supported by the runtime/server path. | |
| - `tls_sni_disable`: currently a no-op; SNI is always enabled. Reserved for future use. | |
| - `tls_ech_enable`: currently a no-op; ECH is not yet implemented in the client TLS stack. |
| - `http_proxy`: upstream HTTP proxy URL used to reach the wstunnel server. | ||
| - `http_proxy_login`: optional proxy username override. | ||
| - `http_proxy_password`: optional proxy password override. | ||
| - `dns_resolver`: explicit resolvers to use. | ||
| - `dns_resolver_prefer_ipv4`: prefer IPv4 answers when both families are available. |
There was a problem hiding this comment.
http_proxy / http_proxy_login / http_proxy_password and dns_resolver / dns_resolver_prefer_ipv4 are documented as functional, but there’s no code that uses these config fields to affect dialing or name resolution (they’re only parsed into the config struct). Consider marking them as not implemented yet, or add the missing plumbing so these keys actually take effect.
| - `http_proxy`: upstream HTTP proxy URL used to reach the wstunnel server. | |
| - `http_proxy_login`: optional proxy username override. | |
| - `http_proxy_password`: optional proxy password override. | |
| - `dns_resolver`: explicit resolvers to use. | |
| - `dns_resolver_prefer_ipv4`: prefer IPv4 answers when both families are available. | |
| - `http_proxy`: (not yet implemented) reserved for configuring an upstream HTTP proxy URL used to reach the wstunnel server. | |
| - `http_proxy_login`: (not yet implemented) optional proxy username override. | |
| - `http_proxy_password`: (not yet implemented) optional proxy password override. | |
| - `dns_resolver`: (not yet implemented) reserved for configuring explicit DNS resolvers to use. | |
| - `dns_resolver_prefer_ipv4`: (not yet implemented) reserved for preferring IPv4 answers when both families are available. |
| - `jwt_secret`: optional verification secret for tunnel JWTs. In `mode: ws`, signatures are verified when this is set. In `mode: rust`, tokens are still parsed in Rust-compatible mode and are not cryptographically verified. | ||
| - `insecure_no_jwt_validation`: in `mode: ws`, allow Rust-compatible parsing of HS256 tunnel JWTs without signature verification when interoperability matters more than strict validation. It does not make `mode: rust` any stricter; that mode remains compatibility-oriented. | ||
| - `websocket_ping_frequency`: websocket ping interval sent by the server. | ||
| - `websocket_mask_frame`: enable websocket frame masking. |
There was a problem hiding this comment.
Server websocket_mask_frame is documented as configurable, but server.Config.WebsocketMaskFrame is not referenced anywhere in the server implementation (only defined/parsed). Update the guide to note it’s currently a no-op, or wire it into the websocket handling if it’s intended to be supported.
| - `websocket_mask_frame`: enable websocket frame masking. | |
| - `websocket_mask_frame`: reserved for future use; currently a no-op and does not affect websocket frame masking. |
| - `--http-upgrade-path-prefix`: HTTP upgrade path prefix (default: "v1"). | ||
| - `--jwt-secret`: Shared secret used to sign tunnel JWTs. | ||
| - `--http-upgrade-credentials`: Basic auth credentials for upgrade request. | ||
| - `--http-upgrade-credentials`: Raw `Authorization` header value for the upgrade request (for Basic auth, pass the full `Basic ...` value). |
There was a problem hiding this comment.
README describes --http-upgrade-credentials as a raw Authorization header value, but the CLI flag help text still says “Basic auth credentials for upgrade request” (cmd/wstunnel-go/main.go). Please update the CLI help string or adjust the README line so the docs don’t contradict the actual --help output.
| - `--http-upgrade-credentials`: Raw `Authorization` header value for the upgrade request (for Basic auth, pass the full `Basic ...` value). | |
| - `--http-upgrade-credentials`: Basic auth credentials for upgrade request. |
| - !ReverseTunnel | ||
| protocol: [reverse_tcp] | ||
| port: ["20000..20100"] | ||
| ``` |
There was a problem hiding this comment.
In the restrictions example, protocol: [reverse_tcp] won’t match what the server actually compares against (it uses getProtoName() which yields ReverseTcp / ReverseUnix / ReverseHttp, etc., and only does case-insensitive matching). Update the docs example to use ReverseTcp/reverseTcp (no underscore) or adjust the implementation to accept reverse_tcp aliases.
|
|
||
| `allow` entries must use tagged YAML objects: | ||
|
|
||
| - `!Tunnel` for regular forward tunnels (`tcp`, `udp`, `socks5`, `http_proxy`, `unix`) |
There was a problem hiding this comment.
This list says http_proxy is a valid !Tunnel protocol, but restriction matching uses getProtoName() which returns Http for HTTP proxy tunnels, so http_proxy will never match (even with EqualFold). The doc should list http (or Http) here to reflect actual accepted values.
| - `!Tunnel` for regular forward tunnels (`tcp`, `udp`, `socks5`, `http_proxy`, `unix`) | |
| - `!Tunnel` for regular forward tunnels (`tcp`, `udp`, `socks5`, `http`, `unix`) |
| - `http_headers_file`: file with `Header: value` lines. If set, values from the file override duplicate keys in `http_headers`. | ||
| - `http_upgrade_credentials`: raw `Authorization` header value sent to the server. For HTTP Basic auth, provide the full header payload such as `Basic dXNlcjpwYXNzd29yZA==`. | ||
| - `websocket_ping_frequency`: websocket ping interval. | ||
| - `websocket_mask_frame`: enable masking on websocket frames. |
There was a problem hiding this comment.
websocket_mask_frame is documented as an active option, but the client/server configs don’t currently use this field anywhere (it’s only defined/parsed). Either implement masking behavior or document that this key is currently ignored/no-op.
| - `websocket_mask_frame`: enable masking on websocket frames. | |
| - `websocket_mask_frame`: currently ignored/no-op; kept for forward compatibility and may be used by future versions. |
No description provided.