Skip to content

docs: refactor sample config and add docsctrings to packages #26

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
xenOs76 merged 1 commit into from
Apr 27, 2026
Merged

docs: refactor sample config and add docsctrings to packages #26

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 1 addition & 3 deletions .github/workflows/release.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,13 +9,11 @@ permissions:
contents: write

jobs:

goreleaser:

runs-on: ubuntu-latest
strategy:
matrix:
go-version: ['1.25']
go-version: ["1.25"]

env:
DOCKER_CLI_EXPERIMENTAL: "enabled"
Expand Down
89 changes: 45 additions & 44 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,9 @@ balancer, reverse proxy, Ingress Gateway, CloudFront distribution.

Check the help:

<details>
<summary>View General Help (`https-wrench -h`)</summary>

```plain
❯ https-wrench -h

Expand Down Expand Up @@ -56,10 +59,15 @@ Flags:
Use "https-wrench [command] --help" for more information about a command.
```

</details>

### HTTPS Wrench requests

Get the help:

<details>
<summary>View Requests Help (`https-wrench requests -h`)</summary>

```plain
❯ https-wrench requests -h

Expand Down Expand Up @@ -92,6 +100,8 @@ Global Flags:
--version Display the version
```

</details>

Generate a sample config file:

```shell
Expand All @@ -101,50 +111,7 @@ https-wrench requests --show-sample-config > https-wrench-sample-config.yaml
<details>
<summary>Sample configuration file</summary>

```yaml
---
debug: false
verbose: true
requests:
- name: httpBunComGet

transportOverrideUrl: https://cat.httpbun.com:443
clientTimeout: 3

requestDebug: false
responseDebug: false

printResponseBody: true
printResponseHeaders: true

userAgent: wrench-custom-ua

requestHeaders:
- key: x-custom-header
value: custom-header-value
- key: x-api-key
value: api-value

responseHeadersFilter:
- X-Powered-By
- Via
- Content-Type

hosts:
- name: httpbun.com
uriList:
- /headers
- /status/302
- /status/404
- /status/503

- name: httpBunComCerts

printResponseCertificates: true

hosts:
- name: httpbun.com
```
A comprehensive sample configuration file can be found in the repository at [`cmd/embedded/config-example.yaml`](./cmd/embedded/config-example.yaml).

</details>

Expand All @@ -158,6 +125,9 @@ https-wrench requests --config https-wrench-sample-config.yaml

Get the help:

<details>
<summary>View Certinfo Help (`https-wrench certinfo -h`)</summary>

```plain
❯ https-wrench certinfo -h

Expand Down Expand Up @@ -205,6 +175,8 @@ Global Flags:
--version Display the version
```

</details>

Get info about a certificate and a key and see if their public keys match:

```shell
Expand Down Expand Up @@ -249,6 +221,9 @@ been used to generate the certificate:

## How to install

<details>
<summary>Go install</summary>

### Go install

HTTPS Wrench is "go gettable", so it can be installed with the following
Expand All @@ -258,12 +233,20 @@ command:
go install github.com/xenos76/https-wrench@latest
```

</details>
<details>
<summary>Manual download</summary>

### Manual download

Release binaries and DEB, RPM, APK packages can be downloaded from the
[repo's releases section](https://github.com/xenOs76/https-wrench/releases).\
Binaries and packages are built for Linux and MacOS, `amd64` and `arm64`.

</details>
<details>
<summary>APT</summary>

### APT

Configure the repo the following way:
Expand All @@ -278,6 +261,10 @@ then:
sudo apt-get update && sudo apt-get install -y https-wrench
```

</details>
<details>
<summary>YUM</summary>

### YUM

Configure the repo the following way:
Expand All @@ -297,6 +284,10 @@ then:
sudo yum install https-wrench
```

</details>
<details>
<summary>Docker image</summary>

### Docker image

Generate the config:
Expand All @@ -313,6 +304,10 @@ Run the `requests` command:
docker run -v $(pwd)/sample-wrench.yaml:/https-wrench.yaml --rm ghcr.io/xenos76/https-wrench:latest --config /https-wrench.yaml requests
```

</details>
<details>
<summary>Homebrew</summary>

### Homebrew

Add Os76 Homebrew repository:
Expand All @@ -327,6 +322,10 @@ Install `https-wrench`:
brew install --casks https-wrench
```

</details>
<details>
<summary>Nix/NUR</summary>

### Nix/NUR

Nix users can use the following Nur repository to access `https-wrench`:
Expand Down Expand Up @@ -395,3 +394,5 @@ Or use a `flake.nix` like the one from the
NixOS users could use a
[flake like this](https://raw.githubusercontent.com/xenOs76/nixos-configs/refs/heads/main/flake.nix)
to fetch the package.

</details>
92 changes: 65 additions & 27 deletions cmd/embedded/config-example.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,53 +1,91 @@
# yaml-language-server: $schema=https://raw.githubusercontent.com/xenOs76/https-wrench/refs/heads/main/https-wrench.schema.json
# vim: set ts=2 sw=2 tw=0 fo=cnqoj
---
#
# HTTPS Wrench - sample configuration file
#

# debug: Enables global debug mode to print additional diagnostic information.
debug: false

# verbose: Enables verbose output, showing more details during execution. Required option.
verbose: true

# caBundle: A PEM-encoded CA certificate bundle as a multiline string to be used for verifying server certificates.
# When testing inside the devenv environment, the 'devenv up' command will create new self-signed certificates and
# start a local, HTTPS-enabled Nginx server.
# The server will take the certificate from $CAROOT/full-cert.pem.
# If caBundle is not set, the requests made using this configuration file will fail with a TLS certificate verification error.
# Add the content of $CAROOT/rootCA.pem to the variable caBundle to test the sample configuration against the local
# webserver.
#
caBundle: |
-----BEGIN CERTIFICATE-----
MIIEbTCCAtWgAwIBAgIQJdy/eKgQx9G54MUxW+ow5zANBgkqhkiG9w0BAQsFADBP
...
Comment thread
xenOs76 marked this conversation as resolved.

# requests: List of HTTP requests to execute. Required option.
requests:
- name: httpBunComGet
# name: The name of the request, used for display purposes. Required option.
- name: SampleRequestAgainstLocalWebserver

# transportOverrideUrl: Override URL for the transport layer. Can be used to force a connection to a specific IP or proxy. Must start with https://
transportOverrideUrl: https://127.0.0.1:9443
Comment on lines +31 to +32
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot Apr 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Comment overstates the requirement for transportOverrideUrl.

The comment says it "Must start with https://", but transportAddressFromURLString in internal/requests/requests_handlers.go auto-prepends https:// when the scheme is missing. Suggest softening the wording so users aren’t misled into thinking a missing scheme is a hard error.

📝 Suggested wording 
-    # transportOverrideUrl: Override URL for the transport layer. Can be used to force a connection to a specific IP or proxy. Must start with https://
+    # transportOverrideUrl: Override URL/host:port for the transport layer (e.g. https://127.0.0.1:9443).
+    # Used to force the connection to a specific IP/proxy. Scheme defaults to https and port defaults to 443 if omitted.
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
# transportOverrideUrl: Override URL for the transport layer. Can be used to force a connection to a specific IP or proxy. Must start with https://
transportOverrideUrl: https://127.0.0.1:9443
# transportOverrideUrl: Override URL/host:port for the transport layer (e.g. https://127.0.0.1:9443).
# Used to force the connection to a specific IP/proxy. Scheme defaults to https and port defaults to 443 if omitted.
transportOverrideUrl: https://127.0.0.1:9443
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@cmd/embedded/config-example.yaml` around lines 31 - 32, Update the comment
for transportOverrideUrl in the example config to not assert a hard requirement
that it "Must start with https://"; instead indicate that a full URL is accepted
but the code path transportAddressFromURLString will auto-prepend "https://" if
the scheme is missing, so users can supply an IP/host with or without scheme.
Reference transportOverrideUrl and transportAddressFromURLString in the comment
to clarify behavior.


# enableProxyProtocolV2: Enables sending an HAProxy PROXY protocol v2 header. Requires 'transportOverrideUrl' to be set.
enableProxyProtocolV2: false

transportOverrideUrl: https://cat.httpbun.com:443
clientTimeout: 3
# clientTimeout: The timeout for the HTTP client in seconds.
clientTimeout: 5

# insecure: If true, skips TLS certificate verification (InsecureSkipVerify).
insecure: false

# requestDebug: If true, dumps the raw HTTP request to the output for debugging.
requestDebug: false

# responseDebug: If true, dumps the raw HTTP response, including TLS connection details, for debugging.
responseDebug: false

# printResponseBody: If true, prints the body of the HTTP response.
printResponseBody: true
printResponseHeaders: true

userAgent: wrench-custom-ua
# responseBodyMatchRegexp: A regular expression to match against the response body.
responseBodyMatchRegexp: ".*https-wrench-agent.*"

requestHeaders:
- key: x-custom-header
value: custom-header-value
- key: x-api-key
value: api-value
# printResponseHeaders: If true, prints the headers of the HTTP response.
printResponseHeaders: true

# responseHeadersFilter: A list of specific response headers to filter and display.
responseHeadersFilter:
- X-Powered-By
- Via
- Content-Type
- Server

hosts:
- name: httpbun.com
uriList:
- /headers
- /status/302
- /status/404
- /status/503

- name: httpBunPostCerts

# printResponseCertificates: If true, prints the TLS certificates returned in the response.
printResponseCertificates: true
printResponseBody: true

# requestMethod: The HTTP method to use for the request (e.g., GET, POST, PUT, DELETE).
requestMethod: POST

# requestHeaders: A list of custom headers to send with the HTTP request.
requestHeaders:
- key: content-type
# key: The name of the header.
- key: Content-Type
# value: The value of the header.
value: application/json
requestBody: '{"hello":"world"}'
- key: X-Custom-Header
value: custom-value

# requestBody: The body payload to send with the HTTP request.
requestBody: "{\"key\": \"value\"}"

# userAgent: A custom User-Agent string to send with the request.
userAgent: custom-https-wrench-agent/1.0

# hosts: The target hosts to send the request to. Required option.
hosts:
- name: httpbun.com
# name: The hostname (used for the Host header and TLS ServerName indication). Required option.
- name: example.com
# uriList: A list of URIs (paths) to request on this host. Must start with a forward slash (/).
uriList:
- /post
- /status/503
6 changes: 3 additions & 3 deletions cmd/root_test.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,7 @@ func TestRootCmd_LoadConfig(t *testing.T) {
require.NoError(t, err)
require.False(t, config.Debug)
require.True(t, config.Verbose)
require.Empty(t, config.CaBundle)
// require.Empty(t, config.CaBundle)

// testing mapstructure squash/embedding of requests.RequestsMetaConfig
// into HTTPSWrenchConfig
Expand All @@ -71,8 +71,8 @@ func TestRootCmd_LoadConfig(t *testing.T) {
require.IsType(t, expectedRequestsConfigs, config.Requests)

// testing against the current values of the embedded config
require.Equal(t, "httpBunComGet", config.Requests[0].Name)
require.Equal(t, "https://cat.httpbun.com:443", config.Requests[0].TransportOverrideURL)
require.Equal(t, "SampleRequestAgainstLocalWebserver", config.Requests[0].Name)
require.Equal(t, "https://127.0.0.1:9443", config.Requests[0].TransportOverrideURL)
})
t.Run("LoadConfig unmarshal error", func(t *testing.T) {
oldCfg := cfgFile
Expand Down
14 changes: 7 additions & 7 deletions devenv.lock
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,11 +3,11 @@
"devenv": {
"locked": {
"dir": "src/modules",
"lastModified": 1776863933,
"narHash": "sha256-v9NoQFSln9n5zqVWUWUc9PajsMaGmga51HOAJqMx7Qw=",
"lastModified": 1777299001,
"narHash": "sha256-r1tFf3mRY5/Fh5DskQLiXjb4AUnM+tOA3pNyrLkXNfA=",
"owner": "cachix",
"repo": "devenv",
"rev": "863b4204725efaeeb73811e376f928232b720646",
"rev": "cbcbe22f0990293d0b540fbc7703b1361cbce060",
"type": "github"
},
"original": {
Expand Down Expand Up @@ -109,11 +109,11 @@
},
"nixpkgs-stable": {
"locked": {
"lastModified": 1776734388,
"narHash": "sha256-vl3dkhlE5gzsItuHoEMVe+DlonsK+0836LIRDnm6MXQ=",
"lastModified": 1777077449,
"narHash": "sha256-AIiMJiqvGrN4HyLEbKAoCSRRYn0rnlW5VbKNIMIYqm4=",
"owner": "NixOS",
"repo": "nixpkgs",
"rev": "10e7ad5bbcb421fe07e3a4ad53a634b0cd57ffac",
"rev": "a4bf06618f0b5ee50f14ed8f0da77d34ecc19160",
"type": "github"
},
"original": {
Expand Down Expand Up @@ -153,4 +153,4 @@
},
"root": "root",
"version": 7
}
}
Loading
Loading