Merge pull request #47 from jkbrsn/cli-timeout

CLI timeout

Author: jkbrsn

.gitignore

@@ -25,8 +25,3 @@ bin/
 
 # Snap packages
 *.snap
-
-# AI agent files
-AGENTS.md
-CLAUDE.md
-

AGENTS.md

@@ -0,0 +1,66 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Build & Test Commands
+
+```bash
+# Build
+make build              # Build binary → bin/wsstat
+make build-all          # Build for all 9 platforms (linux/darwin/windows × 386/amd64/arm64)
+
+# Test
+make test               # Run all tests with -shuffle=on
+make test N=5           # Run tests 5 times (burst/flaky detection)
+make test RACE=1        # Enable race detector
+make test V=1           # Verbose output
+make test N=3 RACE=1 V=1  # Combined flags
+
+# Single package
+go test ./internal/app -v -race
+
+# Single test
+go test ./... -run '^TestName$' -v -race
+go test ./ -run 'TestWSStat/Basic' -v  # Focused subtest
+
+# Lint & Format
+make lint               # golangci-lint (revive, misspell, standard linters)
+make fmt                # gofmt -s -w .
+```
+
+## Project Structure
+
+- **Module**: `github.com/jkbrsn/wsstat/v2`
+- **CLI**: `cmd/wsstat/` - flag parsing, config assembly, delegates to internal/app
+- **App layer**: `internal/app/` - high-level Client API, output formatting, orchestration
+- **Core library**: root package (`wsstat.go`, `result.go`, `subscription.go`, `wrappers.go`) - public API; wraps gorilla/websocket with timing instrumentation
+
+## Architecture
+
+Three-layer design:
+1. **CLI** parses flags, validates URLs (auto-adds `wss://` if missing), builds config
+2. **internal/app.Client** orchestrates measurement/subscription flows, handles output formatting
+3. **Root wsstat package** provides `WSStat` type for timed WebSocket operations with `Result` containing DNS/TCP/TLS/WS/RTT timings
+
+All layers use functional options pattern: `New(opts ...Option)` with `WithTimeout()`, `WithTLSConfig()`, `WithBufferSize()`, etc.
+
+## Code Conventions
+
+- **Imports**: std lib, blank line, third-party, blank line, local packages; alphabetical within groups
+- **Formatting**: `gofmt -s`; soft 100-char line limit; max 80 lines per function (excluding tests)
+- **Errors**: wrap with `fmt.Errorf("context: %w", err)`; no trailing periods; sentinels as `var ErrX = errors.New(...)`
+- **Logging**: default `zerolog.Nop()`; inject via options; avoid noisy logs in tests
+- **Types**: prefer concrete types; avoid `interface{}`; nil-safe slices/maps; pass `context.Context`
+- **Security**: TLS verifies by default; CLI `-insecure` switches to `ws://`
+
+## Testing Notes
+
+- Tests start an echo WebSocket server on `localhost:8080` (TestMain); avoid port conflicts
+- Uses `testify` (assert, require) for assertions
+- CI runs with race detector and 16x repetition for flaky detection
+
+## PR/Commit Standards
+
+- Conventional commits: `feat:`, `fix:`, `docs:`, `chore(scope):` (e.g., `chore(version): bump to 2.2.0`)
+- Ensure `make lint && make test` pass before submitting
+- If user-facing behavior changes, update `CHANGELOG.md` and `VERSION`

CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+Notable changes to this project will be documented in this file. To keep it lightweight, releases 2+ minor versions back will be churned regularly.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
+## [2.2.0]
+
+### Added
+
+- (CLI) New option `--timeout` (default 5s).
+  - Applies both to connection dial and read timeouts.
+- `AGENTS.md`, symlinked to `CLAUDE.md` and `GEMINI.md`.
+
+## [2.1.3]
+
+### Changed
+
+- Upgraded to Go 1.25.6.
+
+## [2.1.1]
+
+### Fixed
+
+- (CLI) Terminal output now shows the correct IP when using the `--resolve` option.
+
+## [2.1.0]
+
+### Added
+
+- (CLI) New option `--resolve`, allowing for direct IP targeting rather than DNS resolution.

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

GEMINI.md

@@ -0,0 +1 @@
+AGENTS.md

README.md

@@ -113,59 +113,30 @@ For macOS:
 
 ### Usage
 
-All the options are available from the help output, have a look at `wsstat -h`:
+Some examples:
 
-```sh
-wsstat 2.0.0
-Measure latency on WebSocket connections
-
-USAGE:
-  wsstat [options] <url>
-  wsstat -subscribe [options] <url>
-
-General:
-  -c, --count <int>              number of interactions [default: 1; unlimited when subscribing]
-      --version                  print program version and exit
-
-Input (choose one):
-      --rpc-method <string>      JSON-RPC method name to send (with id=1, jsonrpc=2.0)
-  -t, --text <string>            text message to send
-
-Subscription:
-  -s, --subscribe                stream events until interrupted
-      --subscribe-once           subscribe and exit after the first event
-  -b, --buffer <int>             subscription delivery buffer size in messages [default: 0]
-      --summary-interval <duration>
-                                 print stat summaries every interval (e.g., 5s, 1m) [default: disabled]
-
-Connection:
-  -H, --header <string>          HTTP header to include with request (repeatable; format: "Key: Value")
-      --resolve <string>         resolve host:port to specific address (repeatable; format: "HOST:PORT:ADDRESS")
-  -k, --insecure                 skip TLS certificate verification (use with caution)
-      --no-tls                   assume ws:// when URL lacks scheme [default: wss://]
-      --color <string>           color output mode: auto, always, never [default: auto]
-
-Output:
-  -q, --quiet                    suppress all output except response
-  -v, --verbose                  increase verbosity (level 1)
-  -vv                            increase verbosity (level 2)
-  -f, --format <string>          output format: auto, json, raw [default: auto]
-
-Verbosity Levels:
-  (default)                      minimal request info with summary timings
-  -v                             adds target/TLS summaries and timing diagram
-  -vv                            includes full TLS certificates and headers
-
-Examples:
-  wsstat wss://echo.example.com
-  wsstat -t "ping" wss://echo.example.com
-  wsstat --rpc-method eth_blockNumber wss://rpc.example.com/ws
-  wsstat --subscribe --summary-interval 5s wss://stream.example.com/feed
-  wsstat -H "Authorization: Bearer TOKEN" -H "Origin: https://foo" wss://api.example.com/ws
-  wsstat --resolve example.com:443:127.0.0.1 wss://example.com/ws
-  wsstat --insecure -vv wss://self-signed.example.com
+```bash
+# Basic request
+wsstat wss://echo.example.com
+
+# Send an RPC method
+wsstat --rpc-method eth_blockNumber wss://rpc.example.com/ws
+
+# Start a subscription
+wsstat --subscribe --summary-interval 5s wss://stream.example.com/feed
+
+# Attach headers to dial request
+wsstat -H "Authorization: Bearer TOKEN" -H "Origin: https://foo" wss://api.example.com/ws
+
+# Resolve to a target IP and set a longer timeout
+wsstat --resolve example.com:443:127.0.0.1 --timeout 30s wss://example.com/ws
+
+# Allow insecure connection, make output extra verbose
+wsstat --insecure -vv wss://self-signed.example.com
 ```
 
+For a full list of the available options, check the `wsstat --help` option of your client.
+
 ### Subscription Mode
 
 Long-lived streaming endpoints can be exercised with the subscription mode:
@@ -203,7 +174,7 @@ wsstat -subscribe-once -text '{"method":"subscribe_ticker"}' wss://example.org/w
 
 For machine-readable output of summaries, add `-format json`.
 
-## wsstat Package
+## wsstat Library Package
 
 Use the `wsstat` Golang package to trace WebSocket connection and latency in your Go applications. It wraps [gorilla/websocket](https://pkg.go.dev/github.com/gorilla/websocket) for the WebSocket protocol implementation, and measures the duration of the different phases of the connection cycle.
 

VERSION

@@ -1 +1 @@
-2.1.3
+2.2.0

cmd/wsstat/config.go

@@ -21,6 +21,7 @@ type Config struct {
 	SubscribeOnce   bool
 	BufferSize      int
 	SummaryInterval time.Duration
+	Timeout         time.Duration
 	Format          string
 	ColorMode       string
 	Quiet           bool
@@ -81,6 +82,7 @@ func parseConfig() (*Config, error) {
 		SubscribeOnce:   *subscribeOnce,
 		BufferSize:      *bufferSize,
 		SummaryInterval: *summaryInterval,
+		Timeout:         *timeout,
 		Format:          strings.ToLower(*formatOption),
 		ColorMode:       strings.ToLower(*colorArg),
 		Quiet:           *quiet,

cmd/wsstat/main.go

@@ -54,6 +54,7 @@ var (
 	subscribeOnce    = flag.Bool("subscribe-once", false, "subscribe and exit after the first event")
 	bufferSize       = flag.Int("buffer", 0, "subscription delivery buffer size (messages)")
 	summaryInterval  = flag.Duration("summary-interval", 0, "print subscription summaries every interval (e.g., 1s, 5m, 1h); 0 disables")
+	timeout          = flag.Duration("timeout", 0, "read/dial timeout (e.g., 30s, 1m); 0 uses default (5s)")
 
 	// Output
 	formatOption = flag.String("format", "auto", "output format: auto, json, or raw")
@@ -128,6 +129,7 @@ func run() error {
 		app.WithBuffer(cfg.BufferSize),
 		app.WithSummaryInterval(cfg.SummaryInterval),
 		app.WithInsecure(cfg.Insecure),
+		app.WithTimeout(cfg.Timeout),
 	)
 
 	if err := ws.Validate(); err != nil {
@@ -196,6 +198,7 @@ func printUsage() {
 	fmt.Fprintln(os.Stderr, "      --resolve <string>         resolve host:port to specific address (repeatable; format: \"HOST:PORT:ADDRESS\")")
 	fmt.Fprintln(os.Stderr, "  -k, --insecure                 skip TLS certificate verification (use with caution)")
 	fmt.Fprintln(os.Stderr, "      --no-tls                   assume ws:// when URL lacks scheme [default: wss://]")
+	fmt.Fprintln(os.Stderr, "      --timeout <duration>       read/dial timeout (e.g., 30s, 1m) [default: 5s]")
 	fmt.Fprintln(os.Stderr, "      --color <string>           color output mode: auto, always, never [default: auto]")
 	fmt.Fprintln(os.Stderr)
 

internal/app/client.go

@@ -76,6 +76,9 @@ type Client struct {
 
 	// TLS configuration
 	insecure bool // skip TLS certificate verification
+
+	// Timeouts
+	timeout time.Duration // read/dial timeout; 0 means use library default
 }
 
 // Option configures a Client.
@@ -165,6 +168,11 @@ func WithInsecure(insecure bool) Option {
 	return func(c *Client) { c.insecure = insecure }
 }
 
+// WithTimeout sets the read/dial timeout. Zero uses the library default (5s).
+func WithTimeout(d time.Duration) Option {
+	return func(c *Client) { c.timeout = d }
+}
+
 // Count returns the configured interaction count.
 func (c *Client) Count() int { return c.count }
 
@@ -197,6 +205,10 @@ func (c *Client) wsstatOptions() []wsstat.Option {
 		opts = append(opts, wsstat.WithResolves(c.resolves))
 	}
 
+	if c.timeout > 0 {
+		opts = append(opts, wsstat.WithTimeout(c.timeout))
+	}
+
 	return opts
 }