src/SilkroadBot.Domain/Interfaces/IProtocolAdapter.cs

using SilkroadBot.Domain.Enums;

namespace SilkroadBot.Domain.Interfaces;

/// <summary>
/// Protocol adapter for a specific game client type/version.
/// </summary>
public interface IProtocolAdapter
{
    /// <summary>The client type this adapter supports.</summary>
    GameClientType ClientType { get; }
    
    /// <summary>Protocol version identifier.</summary>
    string ProtocolVersion { get; }
    
    /// <summary>Gateway server default port.</summary>
    int GatewayPort { get; }
    
    /// <summary>Agent server default port.</summary>
    int AgentPort { get; }
    
    /// <summary>Security initialization bytes for handshake.</summary>
    byte[] GetSecurityInitBytes();
    
    /// <summary>Decode a raw packet for this protocol version.</summary>
    PacketDecodeResult DecodePacket(ReadOnlySpan<byte> data);
    
    /// <summary>Encode a packet for sending.</summary>
    byte[] EncodePacket(ushort opcode, byte[] payload, bool encrypted = false);
    
    /// <summary>Get the opcode mapping for this version.</summary>
    IOpcodeMap GetOpcodeMap();
}

/// <summary>
/// Result of decoding a packet from the wire.
/// </summary>
public record PacketDecodeResult(
    bool Success,
    ushort Opcode,
    byte[] Payload,
    int BytesConsumed,
    string? Error = null
);

/// <summary>
/// Maps logical opcodes to protocol-specific values.
/// </summary>
public interface IOpcodeMap
{
    ushort GetOpcode(string logicalName);
    string GetLogicalName(ushort opcode);
    bool IsKnownOpcode(ushort opcode);
}

/// <summary>
/// Server info for connection.
/// </summary>
public record ServerInfo(string Host, int Port, string Name, GameClientType ClientType);