Crate nectar

nectar

nectar is a Tokio codec providing a partial Telnet protocol (RFC 854) implementation.

Supports primary negotiation options: DO, DONT, WILL, WONT. Supports subnegotiation (NAWS, custom byte sequences). Aims to implement some of the popular MUD protocol extensions.

Usage

Simply use cargo add nectar in your root project directory.

You must also be using tokio-utils with the codec feature enabled, as well as tokio.

See the Tokio docs if you wish to dive deeper into codecs. Essentially it is just a way to encode and decode the underlying TCP Stream in a structured manner - in this case, our structure being the Telnet protocol.

Example

See the echo_server directory for a working example with commented code. If you have cloned the nectar repository, you can run the echo server with cargo and then connect with telnet localhost 5000.

Note: Make sure you check the dependencies in the example Cargo.toml file.

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let addr = SocketAddr::from(([127, 0, 0, 1], 5000));
    let listener = TcpListener::bind(addr).await?;

    println!("telnet server started on: {}", addr);

    // Standard Tokio setup - we accept new connections and pass the
    // stream off to our handler function where the real work happens.
    loop {
        while let Ok((stream, _)) = listener.accept().await {
            tokio::spawn(async move {
                if let Err(e) = handler(stream).await {
                    eprintln!("error: {}", e);
                }
            });
        }
    }
}

async fn handler(stream: TcpStream) -> Result<(), Box<dyn std::error::Error>> {
    // We construct a 'Frame', which is just a wrapper around the underlying
    // stream that is decoded by the `nectar::TelnetCodec`.
    let mut frame = Framed::new(stream, TelnetCodec::new(1024));

    // In a real application, you would want to handle Some(Err(_)) and None
    // variants, but for this example we'll be succinct for simplicities sake.
    while let Some(Ok(msg)) = frame.next().await {
        match msg {
            // We'll keep it simple and only match against the Message event.
            TelnetEvent::Message(string) => {
                // Let's echo back what we received.
                frame.send(TelnetEvent::Message(string)).await?;
            }
            _ => break,
        }
    }
}

You can check out the Blossom source code for an example of nectar in a more complex, real-world scenario.

License

nectar source code is dual-licensed under either

• MIT License
• Apache License, Version 2.0

at your option.

Modules

• constants
  Various byte or byte sequences used in the Telnet protocol.
• error
  Codec and Io errors that may occur while processing Telnet events.
• event
  Top-level Telnet events, such as Message, Do, Will, and Subnegotiation.
• linemode
  Telnet linemode options
• option
  Telnet options such as Echo, GoAhead, and SuppressGoAhead.
• subnegotiation
  Telnet subnegotiation options.

Structs

• TelnetCodec
  Implements a Tokio codec for the Telnet protocol, along with MUD-specific extension protocols such as GMCP.