feat: add connection and request limiting configuration options (#153)

* feat: add connection and request limiting configuration options

- Add -max-requests-per-tunnel flag to limit queued requests per tunnel (default: 20)
- Add -max-clients-per-token flag to limit concurrent clients per token (default: unlimited)
- Implement client count tracking with automatic cleanup on disconnect
- Update /_stats endpoint to display configuration limits and client counts
- Add comprehensive tests for both limiting features
- Update documentation with usage examples and monitoring information

These features address issues #146 and #137, providing better resource control
and preventing unauthorized token sharing or connection conflicts.

Closes #146
Closes #137

* feat: add connection and request limiting configuration options

- Add -max-requests-per-tunnel flag to limit queued requests per tunnel (default: 20)
- Add -max-clients-per-token flag to limit concurrent clients per token (default: unlimited)
- Implement client count tracking with automatic cleanup on disconnect
- Update /_stats endpoint to display configuration limits and client counts
- Add comprehensive tests for both limiting features
- Update documentation with usage examples and monitoring information

These features address issues #146 and #137, providing better resource control
and preventing unauthorized token sharing or connection conflicts.

Closes #146
Closes #137

Author: rshade

.github/workflows/commitlint.yml

@@ -10,8 +10,8 @@ jobs:
   lint:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
       - uses: wagoid/commitlint-github-action@b948419dd99f3fd78a6548d48f94e3df7f6bf3ed
         with:
           configFile: .commitlintrc.yml
-          failOnWarnings: true
+          failOnWarnings: true

.github/workflows/go.yml

@@ -5,9 +5,9 @@ name: Go
 
 on:
   push:
-    branches: [ "master" ]
+    branches: ["master"]
   pull_request:
-    branches: [ "master" ]
+    branches: ["master"]
   workflow_call:
 
 # Set default permissions
@@ -19,47 +19,46 @@ jobs:
     runs-on: ubuntu-latest
     permissions:
       contents: read
-      pull-requests: read # For golangci-lint annotations
+      pull-requests: read  # For golangci-lint annotations
     steps:
-    - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-    - name: Set up Go
-      uses: actions/setup-go@d35c59abb061a4a6fb18e82ac0862c26744d6ab5 # v5.5.0
-      with:
-        go-version: '1.24'
-        cache: true
-        cache-dependency-path: go.sum
-    
-    - name: golangci-lint
-      uses: golangci/golangci-lint-action@4afd733a84b1f43292c63897423277bb7f4313a9 # v8.0.0
-      with:
-        version: v2.1.2
-        
-    - name: Build
-      run: go build -v ./...
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
+      - name: Set up Go
+        uses: actions/setup-go@d35c59abb061a4a6fb18e82ac0862c26744d6ab5  # v5.5.0
+        with:
+          go-version: '1.24'
+          cache: true
+          cache-dependency-path: go.sum
+
+      - name: golangci-lint
+        uses: golangci/golangci-lint-action@4afd733a84b1f43292c63897423277bb7f4313a9  # v8.0.0
+        with:
+          version: v2.1.2
+
+      - name: Build
+        run: go build -v ./...
 
   test:
     needs: build
     runs-on: ubuntu-latest
     permissions:
       contents: read
     steps:
-    - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-    
-    - name: Set up Go
-      uses: actions/setup-go@d35c59abb061a4a6fb18e82ac0862c26744d6ab5 # v5.5.0
-      with:
-        go-version: '1.24'
-        cache: true
-        cache-dependency-path: go.sum
-    
-    - name: Run tests
-      run: go test -v ./...
-    
-    - name: Generate coverage report
-      run: go test -race -coverprofile=coverage.txt -covermode=atomic ./...
-    
-    - name: Upload coverage to Codecov
-      uses: codecov/codecov-action@18283e04ce6e62d37312384ff67231eb8fd56d24 # v5.4.3
-      with:
-        token: ${{ secrets.CODECOV_TOKEN }}
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
+
+      - name: Set up Go
+        uses: actions/setup-go@d35c59abb061a4a6fb18e82ac0862c26744d6ab5  # v5.5.0
+        with:
+          go-version: '1.24'
+          cache: true
+          cache-dependency-path: go.sum
+
+      - name: Run tests
+        run: go test -v ./...
+
+      - name: Generate coverage report
+        run: go test -race -coverprofile=coverage.txt -covermode=atomic ./...
 
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@18283e04ce6e62d37312384ff67231eb8fd56d24 # v5.4.3
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}

.github/workflows/release.yml

@@ -22,23 +22,20 @@ jobs:
       contents: write  # Required for creating releases
       id-token: write # Required for signing
       packages: write # Required for container publishing
-    
     steps:
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
         with:
           fetch-depth: 0
-      
-      - uses: actions/setup-go@d35c59abb061a4a6fb18e82ac0862c26744d6ab5 # v5.5.0
+      - uses: actions/setup-go@d35c59abb061a4a6fb18e82ac0862c26744d6ab5  # v5.5.0
         with:
           go-version: '1.24'
           cache: true
           cache-dependency-path: go.sum
-      
       - name: Run GoReleaser
-        uses: goreleaser/goreleaser-action@9c156ee8a17a598857849441385a2041ef570552 # v6.3.0
+        uses: goreleaser/goreleaser-action@9c156ee8a17a598857849441385a2041ef570552  # v6.3.0
         with:
           distribution: goreleaser
           version: latest
           args: release --clean
         env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.yamllint

@@ -0,0 +1,11 @@
+---
+extends: default
+
+rules:
+  document-start: disable  # GitHub Actions workflows don't need document start
+  line-length:
+    max: 120  # Increased from 80 to accommodate GitHub Actions long names
+  truthy:
+    allowed-values: ['true', 'false', 'on']  # Allow 'on' for GitHub Actions
+  comments:
+    min-spaces-from-content: 1  # Allow single space before comments

CLAUDE.md

@@ -20,8 +20,9 @@ WStunnel is a WebSocket-based reverse HTTP/HTTPS tunneling solution that enables
 - `go test ./...` - Run all tests in the project
 
 ## Lint Commands
-- `make lint` - Run gofmt check and go vet
+- `make lint` - Run gofmt check, go vet, golangci-lint, and yamllint
 - `golangci-lint run` - Run comprehensive linting checks
+- `yamllint .github/workflows/` - Check YAML formatting in GitHub workflows
 
 ## Code Style Guidelines
 - **Formatting**: Use gofmt, tabs for indentation
@@ -53,6 +54,8 @@ WStunnel is a WebSocket-based reverse HTTP/HTTPS tunneling solution that enables
 - Port allocation uses `:0` to get random available ports
 - Use standard Go testing package with table-driven tests
 - Test files should be named `*_test.go` and placed alongside the code they test
+- **IMPORTANT**: Do NOT use Ginkgo/Gomega testing frameworks - use standard Go testing only
+- **NEVER** create or convert tests to use Ginkgo - always use the standard testing package
 
 ## Security Considerations
 - Tokens must be at least 16 characters
@@ -72,11 +75,26 @@ WStunnel is a WebSocket-based reverse HTTP/HTTPS tunneling solution that enables
 - WebSocket ping/pong failures often indicate network issues or proxy interference
 - Request timeouts can be tuned with `-timeout` flag (default 30s)
 
+## Configuration Options
+- **Max Requests Per Tunnel**: Use `-max-requests-per-tunnel N` to limit queued requests per tunnel (default: 20)
+- **Max Clients Per Token**: Use `-max-clients-per-token N` to limit concurrent clients per token (default: 0/unlimited)
+- When a tunnel reaches the max request limit, new requests return "too many requests in-flight, tunnel broken?"
+- When a token reaches the max client limit, new connections return HTTP 429 "Maximum number of clients reached"
+- Client counts are automatically decremented when clients disconnect
+
 ## CodeRabbit Review Settings
 The project uses CodeRabbit for automated code reviews (see `.coderabbit.yaml`). When writing code, ensure compliance with:
 - **Go conventions**: Use gofmt, organize imports (stdlib first), proper error handling
 - **Security**: Never log passwords/tokens, validate certificates, prevent timing attacks
 - **Testing**: Use standard Go testing with table-driven tests, cover edge cases
 - **Path-specific rules**: WebSocket code must follow patterns in tunnel/ws.go, use goroutine-per-request
 - **Excluded paths**: vendor/, build/, node_modules/, generated code, coverage.txt are not reviewed
-- CodeRabbit auto-approves dependency updates from Renovate and documentation-only changes
+- CodeRabbit auto-approves dependency updates from Renovate and documentation-only changes
+
+## CodeRabbit Fix Tool
+Use `~/bin/coderabbit-fix` to automatically apply CodeRabbit suggestions:
+- `coderabbit-fix 153 --ai-format` - Generate AI-formatted prompts from PR 153
+- `coderabbit-fix 153` - Apply all fixes from PR 153
+- `coderabbit-fix 153 --dry-run` - Show what would be changed without applying
+- The tool extracts detailed instructions from CodeRabbit comments including "Prompt for AI Agents" sections
+- Always run `make lint` and `make test` after applying fixes to ensure code quality

Makefile

@@ -46,7 +46,7 @@ endif
 
 # the default target builds a binary in the top-level dir for whatever the local OS is
 default: $(EXE)
-$(EXE): *.go version
+$(EXE): *.go
 	go build -ldflags "-X 'main.VV=$(NAME)_$(TRAVIS_BRANCH)_$(DATE)_$(TRAVIS_COMMIT)'" -o $(EXE) .
 
 # the standard build produces a "local" executable, a linux tgz, and a darwin (macos) tgz
@@ -55,7 +55,7 @@ build: depend $(EXE) build/$(NAME)-linux-amd64.tgz build/$(NAME)-windows-amd64.z
 
 # create a tgz with the binary and any artifacts that are necessary
 # note the hack to allow for various GOOS & GOARCH combos, sigh
-build/$(NAME)-%.tgz: *.go version depend
+build/$(NAME)-%.tgz: *.go depend
 	rm -rf build/$(NAME)
 	mkdir -p build/$(NAME)
 	tgt=$*; GOOS=$${tgt%-*} GOARCH=$${tgt#*-} go build -ldflags "-X 'main.VV=$(NAME)_$(TRAVIS_BRANCH)_$(DATE)_$(TRAVIS_COMMIT)'" -o build/$(NAME)/$(NAME) .
@@ -68,7 +68,7 @@ build/$(NAME)-%.tgz: *.go version depend
 	tar -zcf $@ -C build ./$(NAME)
 	rm -r build/$(NAME)
 
-build/$(NAME)-%.zip: *.go version depend
+build/$(NAME)-%.zip: *.go depend
 	mkdir -p build/$(NAME)
 	tgt=$*; GOOS=$${tgt%-*} GOARCH=$${tgt#*-} go build -ldflags "-X 'main.VV=$(NAME)_$(TRAVIS_BRANCH)_$(DATE)_$(TRAVIS_COMMIT)'" -o build/$(NAME)/$(NAME).exe .
 	zip $@ build/$(NAME)/$(NAME).exe
@@ -101,12 +101,9 @@ upload: depend
 		fi; \
 	  done)
 
-# produce a version string that is embedded into the binary that captures the branch, the date
-# and the commit we're building
+# version target is now a no-op since we use ldflags to set VV
 version:
-	@echo "package main; const VV = \"$(NAME) $(TRAVIS_BRANCH) - $(DATE) - $(TRAVIS_COMMIT)\"" \
-	  >version.go
-	@echo "version.go: `cat version.go`"
+	@echo "Version is set via ldflags: $(NAME) $(TRAVIS_BRANCH) - $(DATE) - $(TRAVIS_COMMIT)"
 
 # Installing build dependencies is a bit of a mess. Don't want to spend lots of time in
 # Travis doing this. The folllowing just relies on go get no reinstalling when it's already
@@ -115,7 +112,8 @@ depend:
 	go mod download
 
 clean:
-	@echo "package main; const VV = \"$(NAME) unversioned - $(DATE)\"" >version.go
+	rm -f $(EXE) version.go
+	rm -rf build/
 
 # gofmt uses the awkward *.go */*.go because gofmt -l . descends into the Godeps workspace
 # and then pointlessly complains about bad formatting in imported packages, sigh
@@ -130,6 +128,28 @@ lint:
 	else \
 	  echo "golangci-lint not found, skipping"; \
 	fi
+	@if command -v yamllint > /dev/null; then \
+	  echo "Running yamllint..." && \
+	  yamllint --config-file .yamllint .github/workflows/ && \
+	  echo "✓ YAML files passed linting"; \
+	else \
+	  echo "yamllint not found, skipping. Install with: pip install yamllint"; \
+	fi
+
+# Auto-fix YAML files
+yamllint-fix:
+	@if command -v yamllint > /dev/null; then \
+	  echo "Checking YAML files for issues..." && \
+	  if ! yamllint .github/workflows/ > /dev/null 2>&1; then \
+	    echo "YAML linting issues detected. Note: yamllint doesn't have auto-fix capability." && \
+	    echo "Showing issues that need manual fixing:" && \
+	    yamllint .github/workflows/; \
+	  else \
+	    echo "✓ All YAML files are valid"; \
+	  fi \
+	else \
+	  echo "yamllint not found. Install with: pip install yamllint"; \
+	fi
 
 travis-test: lint
 	go test -race -coverprofile=coverage.txt -covermode=atomic ./...

README.md

@@ -103,10 +103,46 @@ WSTUNSRV RUNNING
 $
 ```
 
+#### Server Configuration Options
+
+The WStunnel server supports several configuration options to control resource usage and security:
+
+**Password Authentication:**
 To require passwords for specific tokens, use the `-passwords` option:
 
 ```bash
 $ ./wstunnel srv -port 8080 -passwords 'token1:password1,token2:password2' &
+2024/01/19 09:51:31 Listening on port 8080
+$ # Server is now running with password authentication
+```
+
+**Request Limiting:**
+To control the maximum number of queued requests per tunnel (default: 20):
+
+```bash
+$ ./wstunnel srv -port 8080 -max-requests-per-tunnel 50 &
+2024/01/19 09:51:31 Listening on port 8080
+```
+
+This prevents any single tunnel from consuming too many server resources by limiting how many requests can be queued for processing.
+
+**Client Limiting:**
+To limit the number of clients that can connect with the same token (default: unlimited):
+
+```bash
+$ ./wstunnel srv -port 8080 -max-clients-per-token 1 &
+2024/01/19 09:51:31 Listening on port 8080
+```
+
+This is useful when you want to ensure only a single client instance per token is allowed, preventing unauthorized token sharing or connection conflicts.
+
+**Combined Configuration Example:**
+
+```bash
+$ ./wstunnel srv -port 8080 \
+  -passwords 'prod-token:secure-password,dev-token:dev-pass' \
+  -max-requests-per-tunnel 30 \
+  -max-clients-per-token 2 &
 ```
 
 ### Start tunnel
@@ -237,16 +273,23 @@ server {
 WStunnel server provides a `/_stats` endpoint that displays information about connected tunnels. When accessed from localhost, it provides detailed information including:
 
 - Number of active tunnels
+- Server configuration limits
 - Token information for each tunnel
 - Pending requests per tunnel
 - Client IP address and reverse DNS lookup
 - Client version information
 - Idle time for each tunnel
+- Current client counts per token (when limits are configured)
 
 Example output:
 
 ```text
 tunnels=2
+max_requests_per_tunnel=20
+max_clients_per_token=1
+token_clients_my_token=1
+token_clients_another_=1
+total_clients=2
 
 tunnel00_token=my_token_...
 tunnel00_req_pending=0
@@ -262,6 +305,13 @@ tunnel01_client_version=wstunnel v1.0.0
 tunnel01_idle_secs=120.5
 ```
 
+The configuration limits section shows:
+
+- `max_requests_per_tunnel`: Maximum queued requests per tunnel
+- `max_clients_per_token`: Maximum clients allowed per token (0 = unlimited)
+- `token_clients_*`: Current number of clients for each token (when limits are configured)
+- `total_clients`: Total number of connected clients across all tokens
+
 Note: Full statistics are only available when the endpoint is accessed from localhost. Remote requests will only see the total number of tunnels.
 
 ### Reading wstunnel server logs

go.mod

@@ -11,25 +11,10 @@ require (
 )
 
 require (
-	github.com/onsi/ginkgo/v2 v2.23.4
-	github.com/onsi/gomega v1.37.0
-)
-
-require (
-	github.com/go-logr/logr v1.4.3 // indirect
-	github.com/go-task/slim-sprig/v3 v3.0.0 // indirect
-	github.com/google/go-cmp v0.7.0 // indirect
-	github.com/google/pprof v0.0.0-20250501235452-c0086092b71a // indirect
 	github.com/mattn/go-colorable v0.1.14 // indirect
 	github.com/mattn/go-isatty v0.0.20 // indirect
-	go.uber.org/automaxprocs v1.6.0 // indirect
-	golang.org/x/net v0.40.0 // indirect
 	golang.org/x/sys v0.33.0 // indirect
 	golang.org/x/term v0.32.0 // indirect
-	golang.org/x/text v0.25.0 // indirect
-	golang.org/x/tools v0.33.0 // indirect
-	google.golang.org/protobuf v1.36.6 // indirect
-	gopkg.in/yaml.v3 v3.0.1 // indirect
 )
 
 replace github.com/imdario/mergo => dario.cat/mergo v1.0.2