Skip to content

Latest commit

 

History

History
233 lines (201 loc) · 10.5 KB

README.md

File metadata and controls

233 lines (201 loc) · 10.5 KB
Raw

Discord Build Status NuGet Larger Logo

Telnet Negotiation Core

Summary

This project provides a library that implements telnet functionality, and as many of its RFCs are viable, in a testable manner. This is done with an eye on MUDs at this time, but may improve to support more terminal capabilities as time permits and if there is ask for it.

At this time, this repository is in a rough state and does not yet implement some common modern code standards, but is constantly evolving.

State

This library is in a state where breaking changes to the interface are expected.

Support

RFC Description Supported Comments
RFC 855 Telnet Option Specification Full
RFC 1091 Terminal Type Negotiation Full
MTTS MTTS Negotiation (Extends TTYPE) Full
RFC 1073 Window Size Negotiation (NAWS) Full
GMCP Generic Mud Communication Protocol Full
MSSP MSSP Negotiation Full Untested
RFC 885 End Of Record Negotiation Full Untested
EOR End Of Record Negotiation Full Untested
MSDP Mud Server Data Protocol Partial Partial Tested
RFC 2066 Charset Negotiation Partial No TTABLE support
RFC 858 Suppress GOAHEAD Negotiation Full Untested
RFC 1572 New Environment Negotiation No Planned
MNES Mud New Environment Negotiation No Planned
MCCP Mud Client Compression Protocol No Rejects
RFC 1950 ZLIB Compression No Rejects
RFC 857 Echo Negotiation No Rejects
RFC 1079 Terminal Speed Negotiation No Rejects
RFC 1372 Flow Control Negotiation No Rejects
RFC 1184 Line Mode Negotiation No Rejects
RFC 1096 X-Display Negotiation No Rejects
RFC 1408 Environment Negotiation No Rejects
RFC 2941 Authentication Negotiation No Rejects
RFC 2946 Encryption Negotiation No Rejects

ANSI Support, ETC?

Being a Telnet Negotiation Library, this library doesn't give support for extensions like ANSI, Pueblo, MXP, etc at this time.

Use

Client

A documented example exists in the TestClient Project.

Initiate a logger. A Serilog logger is required by this library at this time.

var log = new LoggerConfiguration()
  .Enrich.FromLogContext()
  .WriteTo.Console()
  .WriteTo.File(new CompactJsonFormatter(), "LogResult.log")
  .MinimumLevel.LogDebug()
  .CreateLogger();

Log.Logger = log;

Create functions that implement your desired behavior on getting a signal.

private async ValueTask WriteToOutputStreamAsync(byte[] arg, StreamWriter writer)
{
  try 
  { 
    await writer.BaseStream.WriteAsync(arg, CancellationToken.None);
  }
  catch(ObjectDisposedException ode)
  {
    _Logger.LogInformation("Stream has been closed", ode);
  }
}

public static ValueTask WriteBackAsync(byte[] writeback, Encoding encoding) =>
  Task.Run(() => Console.WriteLine(encoding.GetString(writeback)));

public ValueTask SignalGMCPAsync((string module, string writeback) val, Encoding encoding) =>
  Task.Run(() => _Logger.LogDebug("GMCP Signal: {Module}: {WriteBack}", val.module, val.writeback));

public ValueTask SignalMSSPAsync(MSSPConfig val) =>
  Task.Run(() => _Logger.LogDebug("New MSSP: {@MSSP}", val));

public ValueTask SignalPromptAsync() =>
  Task.Run(() => _Logger.LogDebug("Prompt"));

public ValueTask SignalNAWSAsync(int height, int width) => 
  Task.Run(() => _Logger.LogDebug("Client Height and Width updated: {Height}x{Width}", height, width));

Initialize the Interpreter.

var telnet = new TelnetInterpreter(TelnetInterpreter.TelnetMode.Client, _Logger.ForContext<TelnetInterpreter>())
{
  CallbackOnSubmitAsync = WriteBackAsync,
  CallbackNegotiationAsync = (x) => WriteToOutputStreamAsync(x, output),
  SignalOnGMCPAsync = SignalGMCPAsync,
  SignalOnMSSPAsync = SignalMSSPAsync,
  SignalOnNAWSAsync = SignalNAWSAsync,
  SignalOnPromptingAsync = SignalPromptAsync,
  CharsetOrder = new[] { Encoding.GetEncoding("utf-8"), Encoding.GetEncoding("iso-8859-1") }
}.BuildAsync();

Start interpreting.

for (int currentByte = 0; currentByte != -1; currentByte = input.BaseStream.ReadByte())
{
  telnet.InterpretAsync((byte)currentByte).GetAwaiter().GetResult();
}

Server

A documented example exists in the TestServer Project. This uses a Kestrel server to make the TCP handling easier.

public class KestrelMockServer : ConnectionHandler
{
  private readonly ILogger _Logger;

  public KestrelMockServer(ILogger<KestrelMockServer> logger) : base()
  {
    Console.OutputEncoding = Encoding.UTF8;
    _Logger = logger;
  }

  private async ValueTask WriteToOutputStreamAsync(byte[] arg, PipeWriter writer)
  {
    try
    {
      await writer.WriteAsync(new ReadOnlyMemory<byte>(arg), CancellationToken.None);
    }
    catch (ObjectDisposedException ode)
    {
      _Logger.LogError(ode, "Stream has been closed");
    }
  }

  public ValueTask SignalGMCPAsync((string module, string writeback) val)
  {
    _Logger.LogDebug("GMCP Signal: {Module}: {WriteBack}", val.module, val.writeback);
    return ValueTask.CompletedTask;
  }

  public ValueTask SignalMSSPAsync(MSSPConfig val)
  {
    _Logger.LogDebug("New MSSP: {@MSSPConfig}", val);
    return ValueTask.CompletedTask;
  }

  public ValueTask SignalNAWSAsync(int height, int width)
  {
    _Logger.LogDebug("Client Height and Width updated: {Height}x{Width}", height, width);
    return ValueTask.CompletedTask;
  }

  private static async ValueTask SignalMSDPAsync(MSDPServerHandler handler, TelnetInterpreter telnet, string config) =>
    await handler.HandleAsync(telnet, config);

  public static async ValueTask WriteBackAsync(byte[] writeback, Encoding encoding, TelnetInterpreter telnet)
  {
    var str = encoding.GetString(writeback);
    if (str.StartsWith("echo"))
    {
      await telnet.SendAsync(encoding.GetBytes($"We heard: {str}" + Environment.NewLine));
    }
    Console.WriteLine(encoding.GetString(writeback));
  }

  private async ValueTask MSDPUpdateBehavior(string resetVariable)
  {
    _Logger.LogDebug("MSDP Reset Request: {@Reset}", resetVariable);
    await ValueTask.CompletedTask;
  }

  public async override ValueTask OnConnectedAsync(ConnectionContext connection)
  {
    using (_Logger.BeginScope(new Dictionary<string, object> { { "ConnectionId", connection.ConnectionId } }))
    {
      _Logger.LogInformation("{ConnectionId} connected", connection.ConnectionId);

      var MSDPHandler = new MSDPServerHandler(new MSDPServerModel(MSDPUpdateBehavior)
      {
        Commands = () => ["help", "stats", "info"],
        Configurable_Variables = () => ["CLIENT_NAME", "CLIENT_VERSION", "PLUGIN_ID"],
        Reportable_Variables = () => ["ROOM"],
        Sendable_Variables = () => ["ROOM"],
      });

      var telnet = await new TelnetInterpreter(TelnetInterpreter.TelnetMode.Server, _Logger)
      {
        CallbackOnSubmitAsync = WriteBackAsync,
        SignalOnGMCPAsync = SignalGMCPAsync,
        SignalOnMSSPAsync = SignalMSSPAsync,
        SignalOnNAWSAsync = SignalNAWSAsync,
        SignalOnMSDPAsync = (telnet, config) => SignalMSDPAsync(MSDPHandler, telnet, config),
        CallbackNegotiationAsync = (x) => WriteToOutputStreamAsync(x, connection.Transport.Output),
        CharsetOrder = new[] { Encoding.GetEncoding("utf-8"), Encoding.GetEncoding("iso-8859-1") }
      }
        .RegisterMSSPConfig(() => new MSSPConfig
        {
          Name = "My Telnet Negotiated Server",
          UTF_8 = true,
          Gameplay = ["ABC", "DEF"],
          Extended = new Dictionary<string, dynamic>
        {
          { "Foo",  "Bar"},
          { "Baz", (string[])["Moo", "Meow"] }
        }
        })
        .BuildAsync();

      while (true)
      {
        var result = await connection.Transport.Input.ReadAsync();
        var buffer = result.Buffer;

        foreach (var segment in buffer)
        {
          await telnet.InterpretByteArrayAsync(segment.Span.ToImmutableArray());
        }

        if (result.IsCompleted)
        {
          break;
        }

        connection.Transport.Input.AdvanceTo(buffer.End);
      }
      _Logger.LogInformation("{ConnectionId} disconnected", connection.ConnectionId);
    }
  }
}