{"id":33926904,"url":"https://github.com/pervrosen/wtcat","last_synced_at":"2026-01-13T22:52:44.762Z","repository":{"id":327652688,"uuid":"1110214706","full_name":"pervrosen/wtcat","owner":"pervrosen","description":"Web transport CLI similar to wscat or websocat","archived":false,"fork":false,"pushed_at":"2025-12-04T23:11:58.000Z","size":11,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-08T06:52:02.095Z","etag":null,"topics":["cli","http3","quic","rust","testing","webtransport"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pervrosen.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-04T21:50:57.000Z","updated_at":"2025-12-04T23:04:59.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/pervrosen/wtcat","commit_stats":null,"previous_names":["pervrosen/wtcat"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/pervrosen/wtcat","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pervrosen%2Fwtcat","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pervrosen%2Fwtcat/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pervrosen%2Fwtcat/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pervrosen%2Fwtcat/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pervrosen","download_url":"https://codeload.github.com/pervrosen/wtcat/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pervrosen%2Fwtcat/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28400416,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-13T14:36:09.778Z","status":"ssl_error","status_checked_at":"2026-01-13T14:35:19.697Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","http3","quic","rust","testing","webtransport"],"created_at":"2025-12-12T10:35:46.583Z","updated_at":"2026-01-13T22:52:44.756Z","avatar_url":"https://github.com/pervrosen.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# wtcat - WebTransport CLI Client\n\n[![Crates.io](https://img.shields.io/crates/v/wtcat.svg)](https://crates.io/crates/wtcat)\n[![Documentation](https://docs.rs/wtcat/badge.svg)](https://docs.rs/wtcat)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n[![Downloads](https://img.shields.io/crates/d/wtcat.svg)](https://crates.io/crates/wtcat)\n\n**wtcat** is a WebTransport CLI client for testing and debugging, similar to how `wscat` is used for WebSocket connections. It provides an easy way to connect to WebTransport servers, test authentication, and monitor real-time message streams.\n\n## Features\n\n- 🚀 **Simple WebTransport connections** - Connect to any WebTransport server\n- 🔐 **Flexible authentication** - Support for JWT tokens, username/password, or no auth\n- 📤 **Custom payloads** - Send arbitrary JSON messages on connection\n- 📡 **Real-time streaming** - Monitor server messages in real-time\n- 🔧 **JSON mode** - Pipe output to `jq` and other tools\n- 🔒 **TLS options** - Support for self-signed certificates (development)\n- ⚡ **QUIC/HTTP3** - Built on modern WebTransport protocol\n\n## Installation\n\n### From crates.io\n\n```bash\ncargo install wtcat\n```\n\n### From source\n\n```bash\ngit clone https://github.com/pervrosen/wtcat.git\ncd wtcat\ncargo install --path .\n```\n\n## Quick Start\n\n### Basic connection (no auth)\n\n```bash\nwtcat --url https://localhost:4433 --no-auth -k\n```\n\n### With JWT token\n\n```bash\nwtcat --url https://localhost:4433 --token \"your-jwt-token\" -k\n```\n\n### With username/password authentication\n\n```bash\nwtcat --url https://localhost:4433 \\\n  --username admin \\\n  --password password \\\n  --auth-url https://api.example.com/auth/login \\\n  -k\n```\n\n### JSON mode (pipeable to jq)\n\n```bash\nwtcat --url https://localhost:4433 --token \"token\" -j -k | jq '.type'\n```\n\n## Usage\n\n```\nwtcat - WebTransport CLI client for testing (like wscat for WebSocket)\n\nUsage: wtcat [OPTIONS] --url \u003cURL\u003e\n\nOptions:\n  -u, --url \u003cURL\u003e\n          WebTransport server URL (e.g., https://localhost:4433 or https://localhost:4433/wt)\n\n  -t, --token \u003cTOKEN\u003e\n          JWT token for authentication (optional)\n\n      --username \u003cUSERNAME\u003e\n          Username for authentication (requires --password and --auth-url)\n\n  -p, --password \u003cPASSWORD\u003e\n          Password for authentication (requires --username and --auth-url)\n\n      --auth-url \u003cAUTH_URL\u003e\n          Authentication endpoint URL (e.g., https://api.example.com/auth/login)\n          Required when using --username and --password\n\n  -s, --send \u003cSEND\u003e\n          Custom JSON payload to send on connection (e.g., '{\"subscribe\": \"updates\"}')\n\n      --no-auth\n          Skip authentication - connect without sending auth message\n\n  -k, --insecure\n          Skip TLS certificate verification (for self-signed certs)\n\n  -j, --json\n          Output only JSON (no decorative text, pipeable to jq)\n\n      --auth-timeout \u003cAUTH_TIMEOUT\u003e\n          Timeout for authentication response in seconds [default: 10]\n\n  -h, --help\n          Print help\n\n  -V, --version\n          Print version\n```\n\n## Examples\n\n### 1. Test local development server\n\n```bash\nwtcat --url https://localhost:4433/wt \\\n  --token \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\" \\\n  --insecure\n```\n\n### 2. Connect with custom auth endpoint\n\n```bash\nwtcat --url https://wt.example.com:4433 \\\n  --username developer \\\n  --password dev123 \\\n  --auth-url https://api.example.com/auth/login\n```\n\n### 3. Send custom JSON payload\n\n```bash\nwtcat --url https://localhost:4433 \\\n  --send '{\"type\":\"subscribe\",\"channel\":\"updates\"}' \\\n  --insecure \\\n  --no-auth\n```\n\n### 4. Monitor and filter JSON messages with jq\n\n```bash\n# Extract specific fields from all messages\nwtcat --url https://localhost:4433 -t $TOKEN -j -k | jq '.timestamp'\n\n# Filter messages by type\nwtcat --url https://localhost:4433 -t $TOKEN -j -k | jq 'select(.type == \"price_update\")'\n\n# Pretty print specific fields\nwtcat --url https://localhost:4433 -t $TOKEN -j -k | jq '{type, value, timestamp}'\n```\n\n### 5. Testing different servers\n\n```bash\n# Connect to production server (with valid cert)\nwtcat --url https://wt.production.com:443 --token $TOKEN\n\n# Connect to staging (self-signed cert)\nwtcat --url https://wt.staging.com:4433 --token $TOKEN -k\n\n# Connect without any auth\nwtcat --url https://test.local:4433 --no-auth -k\n```\n\n## Authentication\n\nwtcat supports multiple authentication methods:\n\n### 1. JWT Token (Direct)\n\nProvide a JWT token directly if you already have one:\n\n```bash\nwtcat --url https://localhost:4433 --token \"your-jwt-token\"\n```\n\n### 2. Username/Password\n\nLet wtcat fetch a JWT token for you by authenticating against an HTTP API:\n\n```bash\nwtcat --url https://localhost:4433 \\\n  --username admin \\\n  --password secret \\\n  --auth-url https://api.example.com/auth/login\n```\n\nThe auth endpoint should:\n- Accept `POST` requests with JSON: `{\"username\": \"...\", \"password\": \"...\"}`\n- Return JSON with one of: `token`, `access_token`, or `jwt` field\n\n### 3. Custom Payload\n\nSend a custom JSON authentication message:\n\n```bash\nwtcat --url https://localhost:4433 \\\n  --send '{\"auth_type\":\"bearer\",\"credentials\":\"xyz123\"}'\n```\n\n### 4. No Authentication\n\nConnect without sending any authentication message:\n\n```bash\nwtcat --url https://localhost:4433 --no-auth\n```\n\n## TLS Certificate Verification\n\n### Development (Self-Signed Certificates)\n\nUse the `-k` or `--insecure` flag to skip certificate verification:\n\n```bash\nwtcat --url https://localhost:4433 -k --no-auth\n```\n\n⚠️ **Warning**: Only use `--insecure` for development with self-signed certificates. Never use it in production!\n\n### Production (Valid Certificates)\n\nFor production servers with CA-signed certificates, simply omit the `-k` flag:\n\n```bash\nwtcat --url https://wt.example.com:443 --token $TOKEN\n```\n\n## JSON Output Mode\n\nUse `-j` or `--json` to output only JSON messages without decorative text. Perfect for piping to other tools:\n\n```bash\n# Basic JSON output\nwtcat --url https://localhost:4433 -t $TOKEN -j -k\n\n# With jq for filtering\nwtcat --url https://localhost:4433 -t $TOKEN -j -k | jq '.value'\n\n# Save to file\nwtcat --url https://localhost:4433 -t $TOKEN -j -k \u003e messages.jsonl\n\n# Process with other tools\nwtcat --url https://localhost:4433 -t $TOKEN -j -k | grep \"error\"\n```\n\n## Troubleshooting\n\n### Connection refused\n\n```\nError: Connection refused (os error 61)\n```\n\n**Solution**: Ensure the WebTransport server is running and accessible at the specified URL and port.\n\n### Certificate verification failed\n\n```\nError: invalid peer certificate: UnknownIssuer\n```\n\n**Solution**: Use the `--insecure` flag for self-signed certificates:\n\n```bash\nwtcat --url https://localhost:4433 -k --no-auth\n```\n\n### Authentication timeout\n\n```\n❌ Timeout waiting for authentication response (10s)\n```\n\n**Solutions**:\n- Check if the server is responding to authentication requests\n- Verify your token is valid and not expired\n- Increase timeout with `--auth-timeout 30`\n- Try with `--no-auth` to test basic connectivity first\n\n### ALPN protocol mismatch\n\n```\nError: peer doesn't support any known protocol\n```\n\n**Solution**: The server must support HTTP/3 ALPN protocol (`h3`). Ensure your server is configured for WebTransport/HTTP3.\n\n## How It Works\n\nwtcat uses the QUIC protocol (HTTP/3) to establish WebTransport connections:\n\n```\n┌─────────┐                          ┌─────────┐\n│  wtcat  │                          │ Server  │\n└────┬────┘                          └────┬────┘\n     │                                    │\n     │  1. QUIC connection (TLS 1.3)    │\n     │──────────────────────────────────\u003e│\n     │                                    │\n     │  2. Open bidirectional stream     │\n     │──────────────────────────────────\u003e│\n     │                                    │\n     │  3. Send auth/custom message      │\n     │──────────────────────────────────\u003e│\n     │                                    │\n     │  4. Receive response              │\n     │\u003c──────────────────────────────────│\n     │                                    │\n     │  5. Stream messages               │\n     │\u003c══════════════════════════════════│\n     │  (real-time updates)              │\n     │                                    │\n```\n\n## Comparison: wtcat vs wscat\n\n| Feature | wtcat (WebTransport) | wscat (WebSocket) |\n|---------|---------------------|-------------------|\n| Protocol | QUIC/HTTP3 | TCP/HTTP1.1 or HTTP/2 |\n| Encryption | TLS 1.3 (mandatory) | Optional (ws/wss) |\n| Latency | Lower (0-RTT) | Higher |\n| Head-of-line blocking | No | Yes |\n| Multiplexing | Native | Via HTTP/2 |\n| Mobile-friendly | Yes (survives IP changes) | No |\n| Browser support | ~75% (2025) | ~98% |\n\n## Development\n\n### Building from source\n\n```bash\ngit clone https://github.com/pervrosen/wtcat.git\ncd wtcat\ncargo build --release\n```\n\n### Running tests\n\n```bash\ncargo test\n```\n\n### Development mode\n\n```bash\ncargo run -- --url https://localhost:4433 --no-auth -k\n```\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- Inspired by [wscat](https://github.com/websockets/wscat) for WebSocket\n- Built with [Quinn](https://github.com/quinn-rs/quinn) - Rust QUIC implementation\n- Uses [rustls](https://github.com/rustls/rustls) for TLS\n\n## Related Projects\n\n- **wscat** - WebSocket testing tool\n- **websocat** - Advanced WebSocket client\n- **curl** - HTTP client (supports HTTP/3 in newer versions)\n- **h2load** - HTTP/2 and HTTP/3 load testing tool\n\n## Support\n\n- 📖 [Documentation](https://docs.rs/wtcat)\n- 🐛 [Issue Tracker](https://github.com/pervrosen/wtcat/issues)\n- 💬 [Discussions](https://github.com/pervrosen/wtcat/discussions)\n\n---\n\nMade with ❤️ by the Rust community\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpervrosen%2Fwtcat","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpervrosen%2Fwtcat","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpervrosen%2Fwtcat/lists"}