WatsonTcp Documentation

WatsonTcp provides a mechanism for synchronous request/response patterns using ConversationGuid to match requests with responses.

The Workflow:

1. Sender: Creates a TaskCompletionSource<SyncResponse>, stores it in a dictionary keyed by the message's ConversationGuid, and sends the message with SyncRequest = true and an ExpirationUtc.
2. Receiver: Detects msg.SyncRequest == true, triggers the SyncRequestReceived callback, and sends a response with SyncResponse = true using the same ConversationGuid.
3. Original Sender: The receiver's DataReceiver detects the SyncResponse, finds the matching ConversationGuid in the dictionary, and completes the TaskCompletionSource.
4. Timeout: If the response does not arrive before ExpirationUtc, a TimeoutException is thrown.

Note on Clock Skew: The library uses WatsonCommon.GetExpirationTimestamp() to adjust for differences between the sender's and receiver's system clocks.

WatsonTcp uses a hybrid framing model to solve the problem of message demarcation in a bidirectional TCP stream. It combines length prefixing and delimiters to ensure both the sender and receiver know exactly where a message starts and ends.

The Framing Model

WatsonTcp's framing is loosely inspired by HTTP. It consists of two parts:

1. Metadata (Header): A JSON object containing information about the message (e.g., length, status, metadata).
2. Data (Payload): The actual application-layer message.

Structure

The header and the data are separated by a specific delimiter sequence: `[

]` (two carriage return/line feed sequences).

Example Structure:

{"len":1234,"status":"Normal",...other fields...}[
]
[
]
[data]

• The len field in the JSON header specifies the exact number of bytes in the [data] payload.
• The `[

]` sequence acts as the boundary between the header and the payload.

WatsonTcp provides reliable message-level delivery over TCP by implementing a custom framing protocol. Because TCP is a bidirectional byte stream without inherent message boundaries, WatsonTcp prepends each message with a JSON header that declares the payload length, followed by a \r\n\r\n delimiter, and then the raw data bytes.

Wire Format Structure:

1. JSON header: UTF-8 encoded JSON containing metadata (e.g., len, status, syncreq).
2. Delimiter: The exact bytes \r\n\r\n (hex: 13, 10, 13, 10).
3. Raw data: Exactly N bytes as specified in the header's len field.

Both endpoints must use WatsonTcp or implement this specific framing to communicate successfully.

+--------------------------------------------------+
| JSON header (UTF-8 encoded, no pretty printing)  |
| {"len":N,"status":"Normal","syncreq":false,...} |
+--------------------------------------------------+
| \r\n\r\n  (bytes: 13, 10, 13, 10)                |
+--------------------------------------------------+
| Raw data bytes (exactly N bytes)                |
+--------------------------------------------------+

A WatsonTcpClient follows a specific lifecycle from instantiation to disconnection.

1. Initialization: Create the client using new WatsonTcpClient(ip, port) (or the SSL variant).
2. Connection: Call Connect() or ConnectAsync(). This establishes the TCP connection, handles SSL/TLS negotiation if configured, sets up keepalives, and sends an initial RegisterClient message.
3. Active State: Once connected, the ServerConnected event fires, and a background DataReceiver task begins listening for incoming messages.
4. Disconnection: Call Disconnect() or Dispose(). This optionally sends a Shutdown message, cancels background tasks, closes the underlying streams, and sets Connected = false.

// Example lifecycle
var client = new WatsonTcpClient("127.0.0.1", 5000);
client.ServerConnected += (s, e) => Console.WriteLine("Connected!");

await client.ConnectAsync();

// ... use client ...

client.Disconnect();

A WatsonTcpServer manages incoming connections through a structured lifecycle:

1. Startup: Call Start(). This initializes the TcpListener, starts the _AcceptConnections task (which listens for new clients), and starts the _MonitorClients task (which handles idle timeouts).
2. Connection Acceptance: For every incoming connection, the server:
   • Validates the IP against PermittedIPs or BlockedIPs.
   • Checks MaxConnections (if EnforceMaxConnections is true, the listener pauses when capacity is reached).
   • Performs SSL/TLS negotiation if configured.
   • Handles Preshared Key (PSK) authentication if configured.
3. Active Client Management: Each client gets its own DataReceiver task to process messages and updates its ClientsLastSeen timestamp.
4. Shutdown: When the server is stopped, all client connections are terminated and background tasks are cancelled.

var server = new WatsonTcpServer("127.0.0.1", 5000);
server.ServerStarted += (s, e) => Console.WriteLine("Server started!");

server.Start();

// ... server runs ...

server.Stop();