Add OnSocketAvailableAsync Hook

[johannespfeiffer]

Motivation

This change adds the OnSocketAvailableAsync hook, allowing users to perform actions on the socket once it becomes available. This is particularly useful for scenarios where an HTTP proxy is required to connect to a NATS server.

Key Change

This hook enables users to interact with the socket directly, allowing custom actions such as sending an HTTP CONNECT request to establish a tunnel through a proxy.

Example Usage

_connection.OnSocketAvailableAsync = async (_socket) =>
{
    var hostname = "my-http-proxy-host";
    var port = 3128;
    string connectRequest = $"CONNECT {hostname}:{port} HTTP/1.1\r\nHost: {hostname}:{port}\r\n\r\n";
    byte[] requestBytes = Encoding.ASCII.GetBytes(connectRequest);
    await _socket.SendAsync(requestBytes);

    // Validate proxy response
    byte[] buffer = new byte[4096];
    int bytesRead = await _socket.ReceiveAsync(buffer);
    string response = Encoding.ASCII.GetString(buffer, 0, bytesRead);

    if (!response.Contains("200 Connection established"))
    {
        throw new Exception($"Proxy connection failed. Response: {response}");
    }
};

[mtmk]

if we need to make it public we should move the file out of internal

edit: also does this really need to be public?

[johannespfeiffer]

Yes, if we want to use it in public Func<ISocketConnection, ValueTask<ISocketConnection>>. Will move it.

[mtmk]

we should pull this up to INatsConnection as well. also can we return ValueTask to be consistent?

[mtmk]

thanks @johannespfeiffer looks very useful. can you think of a way to write a test? (I think websocket callbacks have a test might be helpful)

[mtmk]

I will try to test this soon. Do you have an example setup or some kind of instructions to try it out in a real setup e.g. with a proxy like Squid or something?

[johannespfeiffer]

Yes, exactly like that.

I used squid on a separate machine (just used the standard settings).

Then on the machine running the nats-client I've added a firewall rule to only allow outgoing connections to the machine with the squid proxy.

[mtmk]

finally got around to this. sorry for the delay. here is a working example augmenting the example above:

using System.Text;
using NATS.Client.Core;

var proxy = "localhost:3128";
var nats = "demo.nats.io:4222";

await using var connection = new NatsConnection(new NatsOpts
{
    Url = proxy,
    TlsOpts = new NatsTlsOpts { Mode = TlsMode.Disable },
});

// Must assign a delegate to OnSocketAvailableAsync before calling ConnectAsync or any other method
connection.OnSocketAvailableAsync = async socket =>
{
    // Send CONNECT request to proxy
    await socket.SendAsync(Encoding.ASCII.GetBytes($"CONNECT {nats} HTTP/1.1\r\nHost: {nats}\r\n\r\n"));

    // Validate proxy response
    var buffer = new byte[4096];
    var read = await socket.ReceiveAsync(buffer);
    var response = Encoding.ASCII.GetString(buffer, 0, read);
    if (!response.Contains("200 Connection established"))
    {
        throw new Exception($"Proxy connection failed. Response: {response}");
    }

    return socket;
};

// Establish connection to NATS server through the proxy
await connection.ConnectAsync();
Console.WriteLine($"Connected to server {connection.ServerInfo?.Name}");

// Work with the connection as usual
var rtt = await connection.PingAsync();
Console.WriteLine($"RTT {rtt}");

If you install a local Squid proxy server to forward traffic to the NATS server make sure to comment out the following line in the Squid configuration file:

# http_access deny CONNECT !SSL_ports

[mtmk]

LGTM thanks @johannespfeiffer