# WebSocket Load Test

A simple WebSocket client designed for load testing and monitoring Grove Portal's WebSocket endpoints. 

This tool provides real-time statistics, subscription management, per-type message logging, and detailed connection monitoring for multiple blockchain WebSocket services including Ethereum, Base, BSC, and XRPL EVM networks.

<p align="center">
<a href="https://github.com/buildwithgrove/path">
  <img src="https://storage.googleapis.com/grove-brand-assets/Presskit/Logo%20Joined-2.png" alt="Grove Logo" title="Uses PATH for RPC" width="500">
  <br>
  🌿 Load tests WebSocket endpoints using Grove's PATH API.
  <br>
</a>
</p>

## Prerequisites

**Grove Portal Account Required** - This tool is designed to work with Grove Portal's WebSocket endpoints. You'll need:

1. **Grove Portal Account**: Sign up at [https://www.portal.grove.city/](https://www.portal.grove.city/)
2. **Application**: Create an application in your Grove Portal dashboard
3. **API Credentials**: Get your Application ID and API Key from the portal

## Features

- 🚀 **Multiple Subscription Types**: Support for `newHeads`, `newPendingTransactions`
- 📊 **Real-time Statistics**: Live dashboard with connection metrics, message rates, and performance data
- 🔄 **Automatic Reconnection**: Robust reconnection logic with detailed connection history
- 📈 **Performance Monitoring**: Track message rates, success rates, and connection reliability
- 🎨 **Colorized Output**: Beautiful terminal interface with emojis and colored output
- ⚡ **Multiple Instances**: Create multiple subscription instances for load testing
- 📋 **Connection History**: Detailed tracking of all connection sessions

## Installation

```bash
go install github.com/commoddity/websocket-load-test@latest
```

## Usage

```bash
# Production deployment (default) - Ethereum WebSocket endpoint 
websocket-load-test \
    --service eth \
    --app-id $GROVE_PORTAL_APP_ID \
    --api-key $GROVE_PORTAL_API_KEY \
    --subs "newHeads,newPendingTransactions" \
    --count 10

# Local development server testing
websocket-load-test \
    --destination local \
    --service base \
    --app-id $GROVE_PORTAL_APP_ID \
    --api-key $GROVE_PORTAL_API_KEY \
    --subs "newHeads,newPendingTransactions" \
    --count 10 \
    --log

# Binary deployment testing
websocket-load-test \
    -d binary \
    -s bsc \
    -a $GROVE_PORTAL_APP_ID \
    -k $GROVE_PORTAL_API_KEY \
    --count 5

# Test XRPL EVM production (explicit prod destination)
websocket-load-test \
    --destination prod \
    --service xrplevm \
    --app-id $GROVE_PORTAL_APP_ID \
    --api-key $GROVE_PORTAL_API_KEY \
    --subs "newHeads,logs" \
    --count 15

# Test XRPL EVM testnet for development
websocket-load-test \
    --service xrplevm-testnet \
    --app-id $GROVE_PORTAL_APP_ID \
    --api-key $GROVE_PORTAL_API_KEY \
    --log
```

These examples will:
- Connect to the specified destination (prod/local/binary) endpoint
- Use appropriate URL patterns and headers based on destination
- Authenticate using your API key
- Create the specified number of subscriptions for each subscription type
- Display real-time statistics and performance metrics

### Command Line Options

| Flag            | Short  | Description                                                     | Default      | Example                  |
| --------------- | ------ | --------------------------------------------------------------- | ------------ | ------------------------ |
| `--destination` | `-d`   | Target destination (binary, local, prod)                        | `prod`       | `--destination "local"`  |
| `--service`     | `-s`   | Grove Portal service (eth, base, bsc, xrplevm, xrplevm-testnet) | `xrplevm`    | `--service "eth"`        |
| `--app-id`      | `-a`   | Grove Portal Application ID                                     | _(required)_ | `--app-id "app123"`      |
| `--api-key`     | `-k`   | Grove Portal API Key                                            | _(required)_ | `--api-key "key456"`     |
| `--subs`        | _none_ | Comma-separated subscription types                              | `newHeads`   | `--subs "newHeads,logs"` |
| `--count`       | `-c`   | Number of subscriptions per type                                | `1`          | `--count 10`             |
| `--log`         | `-l`   | Display latest WebSocket message                                | `false`      | `--log`                  |
| `--help`        | `-h`   | Show detailed help and examples                                 | _none_       | `--help`                 |

Use `websocket-load-test --help` for detailed usage examples and feature descriptions.

### Supported Destinations

- **`prod`** 🌐 - Production Grove Portal endpoints (default)
  - URL: `wss://[service].rpc.grove.city/v1/[app-id]`
  - No `Target-Service-Id` header required
- **`local`** 🏠 - Local development server
  - URL: `ws://localhost:3070/v1/[app-id]`
  - Includes `Target-Service-Id: [service]` header
- **`binary`** ⚙️ - Binary deployment testing
  - URL: `ws://localhost:3069/v1/[app-id]`
  - Includes `Target-Service-Id: [service]` header

### Supported Subscription Types

- **`newHeads`** 🧊 - New block headers
- **`newPendingTransactions`** ⚡ - Pending transactions

## Message Logging

Use the `--log` or `-l` flag to enable real-time message logging. When enabled, the tool displays the latest received WebSocket message for each subscription type in formatted JSON below the dashboard:

```bash
# Enable message logging
websocket-load-test \
    --app-id "your_app_id" \
    --api-key "your_api_key" \
    --log
```

**Features:**
- 📝 **Per-Type Display**: Shows the latest message for each subscription type (newHeads, newPendingTransactions, logs, etc.)
- 🕐 **Timestamps**: Displays when each message was received
- 🎨 **JSON Formatting**: Pretty-printed JSON with proper indentation
- 🔄 **Live Updates**: Automatically replaces with newer messages per type
- 📊 **Categorization**: Separates subscription events, confirmations, and errors
- 🎯 **Organized Layout**: Groups messages by subscription type with appropriate emojis

**Example Output:**
```
🕐 Last Updated: 19:57:32

📝 LATEST MESSAGES BY TYPE

✅ confirmations - Received at 19:57:25:
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x123abc..."
}

🧊 newHeads - Received at 19:57:31:
{
  "jsonrpc": "2.0",
  "method": "eth_subscription",
  "params": {
    "subscription": "0x123abc...",
    "result": {
      "number": "0x1234567",
      "hash": "0xabcdef...",
      "parentHash": "0x987654...",
      "timestamp": "0x64a8b2f0"
    }
  }
}

⚡ newPendingTransactions - Received at 19:57:30:
{
  "jsonrpc": "2.0",
  "method": "eth_subscription",
  "params": {
    "subscription": "0x456def...",
    "result": {
      "hash": "0x987654...",
      "from": "0xabc123...",
      "to": "0xdef456..."
    }
  }
}
```

## Dashboard Features

The real-time dashboard displays:

### Connection Metrics
- Total connections and reconnections
- Connection attempts and current duration
- Average, longest, and shortest connection times
- Connection reliability percentage

### Subscription Metrics
- Total subscriptions created
- Confirmation and subscription events
- Error events and success rate
- Messages categorized by subscription type

### Message Metrics
- Total messages received
- Current connection messages
- Messages per second (current and overall)
- Time since last event

### Performance Metrics
- Success rate percentage
- Events per subscription ratio
- Connection event rates
- Overall reliability statistics

### Connection History
- Last 5 connection sessions
- Duration and message count per session
- Connection start/end timestamps

## Configuration

### Destination Configuration

This tool supports three deployment destinations:

1. **Production (`prod`)**: Grove Portal production endpoints
2. **Local (`local`)**: Local development server on port 3070
3. **Binary (`binary`)**: Binary deployment testing on port 3069

Required configuration:
1. **Grove Portal Account**: Create account at [https://www.portal.grove.city/](https://www.portal.grove.city/)
2. **Application Setup**: Create an application in your Grove Portal dashboard
3. **Get Your Credentials**: Copy your Application ID and API Key from the dashboard

### Best Practices

1. **Authentication**: Always provide your Grove Portal API key with `--api-key` or `-k`
2. **Service Selection**: Supported services are eth, base, bsc, xrplevm, and xrplevm-testnet
3. **Destination Selection**: Choose prod (default), local, or binary destinations
4. **URL Auto-Construction**: URLs are automatically built based on destination
5. **Load Testing**: Start with small `--count` values (1-10) and increase gradually
6. **Rate Limits**: Monitor your Grove Portal dashboard for usage and limits

## Troubleshooting

### Common Issues

1. **Connection Failed**
   - Verify your Grove Portal Application ID is correct in the URL
   - Check that your API key is valid and set correctly
   - Ensure you have an active Grove Portal subscription
   - Verify you're using a supported service (eth, base, bsc, xrplevm, xrplevm-testnet)
   - For local/binary destinations, ensure the target servers are running

2. **Authentication Errors**
   - Check that `GROVE_PORTAL_API_KEY` environment variable is set
   - Verify your API key hasn't expired in the Grove Portal dashboard
   - Ensure your application has WebSocket access enabled

3. **No Messages Received**
   - Verify the subscription types are supported by the target chain
   - Check your Grove Portal dashboard for any service disruptions
   - Monitor error events in the real-time dashboard
   - For local/binary destinations, verify service routing is configured

4. **Rate Limiting**
   - Check your Grove Portal dashboard for rate limit status
   - Reduce the `-count` parameter for load testing
   - Monitor your application's usage in the Grove Portal dashboard

5. **High Reconnection Rate**
   - Check network stability
   - Verify you haven't exceeded Grove Portal rate limits
   - Consider reducing subscription count or frequency
   - For local/binary destinations, check server stability