TCP/UDP Whistle
Relevant source files
The following files were used as context for generating this wiki page:
TCP/UDP Whistle is a network diagnostic and simulation tool within the DevUtils suite designed to allow developers to craft raw packets, listen on local ports, and simulate various network conditions. It provides a user interface for sending TCP and UDP payloads with granular control over timing, chunking, and data integrity, as well as a local listener capable of echoing responses and capturing incoming traffic.
The tool serves as a "Swiss Army Knife" for network debugging, enabling users to mimic slow or shaky links using delays and chunk sizes, or test service robustness by injecting malformed "junk" bytes into payloads.
Sources: README.md:16, components/tools/tcp-udp-whistle.tsx:143-150, messages/en.json:657-660
Architecture and Data Flow
The system follows a client-server architecture where the frontend React component communicates with a Node.js backend route. The frontend handles user input and state management, while the backend utilizes native Node.js modules (net and dgram) to perform low-level network operations.
Component Interaction
The UI triggers requests to the /api/whistle endpoint, which supports four primary modes: tcp-send, udp-send, tcp-listen, and udp-listen.
The diagram above shows the flow from the user interface through the API validation layer to the specific protocol handlers.
Sources: app/api/whistle/route.ts:7-22, app/api/whistle/route.ts:285-325, components/tools/tcp-udp-whistle.tsx:90-110
API Interface and Configuration
The backend API enforces strict limits on payload sizes and durations to ensure system stability. For security reasons, host resolution is restricted to loopback and localhost addresses.
Whistle Request Parameters
The WhistleRequest interface defines the configuration options available for network operations.
| Parameter | Type | Default | Description |
|---|---|---|---|
mode | Mode | Required | tcp-send, udp-send, tcp-listen, or udp-listen. |
host | string | 127.0.0.1 | Target address (Restricted to loopback range). |
port | number | Required | Destination or local binding port (1-65535). |
payload | string | "" | The data to be sent in "send" modes. |
timeoutMs | number | 5000 | Maximum time to wait for a response or connection. |
delayMs | number | 0 | Delay before sending data (max 8000ms). |
chunkSize | number | undefined | Size of data chunks for fragmented sending. |
durationMs | number | 600000 | How long the listener stays active (max 10 mins). |
malformed | boolean | false | If true, appends noise bytes (0x00, 0xff, etc.). |
echo | boolean | false | If true, the listener replies to incoming data. |
Sources: app/api/whistle/route.ts:9-55, app/api/whistle/route.ts:63-88
Network Handlers
Transmission Logic (tcp-send & udp-send)
Transmission handlers manage the connection lifecycle, payload construction, and response collection. For TCP, the system supports chunked delivery, sending data in segments with a fixed 120ms delay between chunks to simulate network throttling.
The sequence above illustrates the transmission flow, including payload fragmentation and response capture.
Sources: app/api/whistle/route.ts:100-141, app/api/whistle/route.ts:143-189
Listening and Simulation (tcp-listen & udp-listen)
The listening modes allow DevUtils to act as a temporary server. It captures incoming traffic and can be configured to "echo" a specific payload back to the sender after a designated respondDelayMs.
Key features of listeners:
- Capture Limit: Max 25 entries per session.
- Duration: Controlled by
durationMsor manual abort viaAbortSignal. - Echo Logic: Automatically sends a response to the
remoteAddressandremotePortof the incoming packet.
Sources: app/api/whistle/route.ts:191-235, app/api/whistle/route.ts:249-283, components/tools/tcp-udp-whistle.tsx:143-189
Frontend Implementation
The frontend is implemented in tcp-udp-whistle.tsx using React and Tailwind CSS. It provides a tabbed interface to separate "Send" and "Listen" workflows.
State Management
The component tracks the following critical states:
isSending/isListening: UI loading states.history: A list of the last 8 operations including protocol and data size summaries.sendResult/listenResult: The data returned from the API, displayed in both UTF-8 text and Hex formats.
Security Constraints
The UI reflects the backend's security model. The validateHost function on the server specifically checks that the host is a loopback address (e.g., 127.0.0.1, localhost, or 127.0.0.0/8 range) to prevent the tool from being used for SSRF (Server-Side Request Forgery) against external networks.
Sources: components/tools/tcp-udp-whistle.tsx:68-88, app/api/whistle/route.ts:63-88, messages/en.json:699-702
Technical Specifications Summary
| Aspect | Constraint/Detail |
|---|---|
| Max Payload Size | 4096 Bytes |
| Max Response Capture | 128 KB |
| Max Listen Duration | 600,000 ms (10 minutes) |
| TCP Chunk Delay | 120 ms (hardcoded for fragmentation) |
| Runtime | Node.js (Required for node:net and node:dgram) |
| Dependencies | lucide-react, i18next, @radix-ui/react-tabs |
Sources: app/api/whistle/route.ts:5-6, app/api/whistle/route.ts:37-40, package.json:44-65
Conclusion
TCP/UDP Whistle provides a localized environment for low-level protocol testing. By abstracting the complexities of Node.js socket programming into a simple web interface, it allows developers to quickly verify how their applications handle fragmented data, malformed packets, and various network latencies without leaving their development tool suite.