TCP Transport

TCP transport provides reliable, ordered byte stream communication — ideal for desktop game clients and binary protocols.

Configuration

altruist:
  server:
    http:
      host: "0.0.0.0"
      port: 8080
    transport:
      codec:
        provider: messagepack
      tcp:
        enabled: true
        port: 13000

The TCP server listens on its own port (separate from HTTP). You can run TCP alongside WebSocket and/or UDP — see Server Setup for multi-transport configuration.

How It Works

1. TCP listener binds to the configured port (e.g., 13000)
2. Client connects via raw TCP socket
3. Server assigns a unique clientId (GUID)
4. Incoming bytes are decoded using the configured codec (MessagePack or JSON)
5. Packets route to [Gate] handlers — same as WebSocket

Portal Code is Identical

Your portal code doesn't change when switching from WebSocket to TCP:

[Portal("/game")]
public class GamePortal : Portal
{
    [Gate("login")]
    public async Task OnLogin(LoginPacket packet, string clientId)
    {
        // Exact same code works for WebSocket and TCP
        await _router.Client.SendAsync(clientId, new LoginSuccessPacket());
    }
}

Client Connection (C# Example)

using System.Net.Sockets;

var client = new TcpClient();
await client.ConnectAsync("localhost", 13000);

var stream = client.GetStream();

// Send a MessagePack-encoded packet
byte[] data = MessagePackSerializer.Serialize(new LoginPacket { ... });
await stream.WriteAsync(data);

// Read response
var buffer = new byte[8192];
int bytesRead = await stream.ReadAsync(buffer);
var response = MessagePackSerializer.Deserialize<MessageEnvelope>(buffer.AsSpan(0, bytesRead));

Authentication

TCP connections use the same [Shield] system but via the non-HTTP path. The ShieldAttribute.AuthenticateNonHttpAsync method handles authentication for TCP clients:

[Portal("/game")]
[Shield(typeof(MyAuth))]
public class SecureGamePortal : Portal { ... }

For TCP, the initial bytes sent by the client are treated as authentication data.

Buffer Size

The default TCP receive buffer is 8192 bytes. This is suitable for most game packets. For larger payloads, consider breaking data into multiple packets.