#jtenner/telnet

#Status

#Features

• Incremental TELNET parser for arbitrary byte chunks.
• TELNET encoder for data, commands, negotiation triplets, and subnegotiations.
• Canonical IAC escaping for data and subnegotiation payloads.
• WILL/WON'T/DO/DON'T negotiation state with explicit transition actions.
• Transport-independent Session orchestration for parser, encoder, negotiator, policy, and option codecs.
• Policy-driven option support with automatic replies to peer requests and opaque startup negotiation for built-in supported options such as remote NAWS.
• RFC/IANA command and option mapping helpers.
• Option-payload codecs for:
  • BINARY policy boundary
  • ECHO and SUPPRESS-GO-AHEAD negotiation
  • TERMINAL-TYPE
  • NAWS
  • LINEMODE
  • NEW-ENVIRON
  • CHARSET
  • START_TLS as a transport-security boundary codec
• Lossless raw preservation for unknown/private option payloads.
• Deterministic fuzz/property tests, target-parity checks, and native scanner stress coverage.

#Non-goals

• No TCP or async runtime dependency in the core package.
• No built-in remote shell server.
• No automatic credential handling.
• No terminal emulator.
• No bundled TLS implementation; START_TLS FOLLOWS is surfaced as a session boundary event for an adapter to upgrade the transport.

#Get started with Session

1. Build a SessionConfig or start from Session::default().
2. Allocate an output buffer large enough for generated TELNET replies.
3. Call session.receive(input, out) for each inbound transport chunk.
4. Write out[0:result.bytes_written] to your socket/TLS stream.
5. Save result.session and handle result.events.

let mut session = @telnet.Session::default()
let out = Bytes::new(8192)
let input = Bytes::from_array([
  255.to_byte(), 251.to_byte(), 1.to_byte(), // IAC WILL ECHO
  72.to_byte(), 105.to_byte(),
])

match session.receive(input, out) {
  Ok(result) => {
    session = result.session
    // Write the first result.bytes_written bytes of out to your transport.
    // Then inspect result.events for Data, negotiation state, decoded payloads,
    // START_TLS boundaries, and option enable/disable notifications.
  }
  Err(error) => {
    // Grow the output buffer if error.kind is OutputBufferTooSmall, or report
    // malformed/policy errors according to your adapter's rules.
  }
}

#Quick examples

#Parse a stream

let parser = @telnet.Parser::default()
let result = parser.feed(Bytes::from_array([
  72.to_byte(), 105.to_byte(), 255.to_byte(), 246.to_byte(),
]))
// Events: Data("Hi"), Command(AYT)

let first = @telnet.Parser::default().feed(Bytes::from_array([
  255.to_byte(), 251.to_byte(),
]))
let second = first.parser.feed(Bytes::from_array([1.to_byte()]))
// Event: Negotiation(WILL, ECHO)

#Encode TELNET bytes

let out = Bytes::new(3)
let event = @telnet.NegotiationEvent::{
  verb: @telnet.NegotiationVerb::Will,
  option: @telnet.OptionCode::new(1.to_byte()), // ECHO
}
let item = @telnet.EncodeItem::Negotiation(event)
ignore(@telnet.Encoder::canonical().encode_item(item, out))
// out == IAC WILL ECHO: [255, 251, 1]

let data = @telnet.ByteSpan::new(
  Bytes::from_array([65.to_byte(), 255.to_byte(), 66.to_byte()]),
  0,
  3,
)
let out = Bytes::new(4)
ignore(@telnet.Encoder::canonical().encode_item(
  @telnet.EncodeItem::EscapedData(data),
  out,
))
// out == [65, 255, 255, 66]

#Decode subnegotiation payloads

let payload = @telnet.ByteSpan::new(
  Bytes::from_array([0.to_byte(), 80.to_byte(), 0.to_byte(), 24.to_byte()]),
  0,
  4,
)
match @telnet.OptionPayload::decode(@telnet.OptionCode::new(31.to_byte()), payload) {
  Ok(@telnet.OptionPayload::Naws(size)) => {
    // size.columns == 80, size.rows == 24
  }
  _ => ()
}

#Drive option negotiation

let negotiator = @telnet.Negotiator::new()
let incoming = @telnet.NegotiationEvent::{
  verb: @telnet.NegotiationVerb::Will,
  option: @telnet.OptionCode::new(1.to_byte()), // ECHO
}
let transition = negotiator.receive(incoming, @telnet.PolicyDecision::Accept)
let updated = negotiator.apply(transition)
// Encode any NegotiationAction::Send replies and write them on your transport.

#Use a Session

///|
let session = @telnet.Session::new(@telnet.SessionConfig::{
  parser_config: @telnet.Parser::default_config(),
  policy: @telnet.SessionPolicy::default_server(),
  incoming_text_policy: @telnet.SessionTextPolicy::Preserve,
  outgoing_text_policy: @telnet.SessionTextPolicy::Preserve,
  decode_known_options: true,
  emit_raw_subnegotiation: true,
  require_enabled_for_subnegotiation: false,
  reject_malformed_known_payloads: false,
  max_outbound_bytes: 8192,
})

///|
let out = Bytes::new(64)

///|
let result = session.receive(Bytes::new(0), out)
// With default_server policy, the first receive opaquely starts remote NAWS
// negotiation by writing IAC DO NAWS into out.

#Main API areas

• Parser: incremental byte-stream parser with feed, feed_span, finish, checkpoints, restore/reset, and configurable CR/coalescing/strictness policy.
• Encoder: canonical and raw TELNET byte encoders with capacity reporting.
• Negotiator: local/remote option-half state and explicit transition actions.
• Session: streamable protocol-state composition with policy-driven option support, generated output bytes, server-side ECHO, START_TLS boundary events, and NAWS window-size tracking.
• OptionPayload: decode/encode helpers for supported subnegotiation payloads.
• ByteSpan: public byte-slice model used by parser events and encoders.
• Mapping helpers: Command, NegotiationVerb, OptionCode, and KnownOption.

#Policy boundaries

• CrPolicy controls NVT CR/LF/CR-NUL handling at parser construction time; Session internally preserves parser data bytes so BINARY-aware semantics can be applied at the session layer.
• SessionPolicy is the source of option support. Accepted incoming option requests are answered automatically; built-in proactive support such as remote NAWS is negotiated opaquely on the first Session::receive call.
• BINARY negotiation is visible through negotiation state; it does not silently mutate parser configuration.
• START_TLS FOLLOWS decodes as a payload and is surfaced as TransportUpgradeRequired; plaintext blocking and transport upgrade enforcement remain adapter responsibilities.
• Unknown or unsupported option payloads can be preserved as OptionPayload::Raw.

#Supported options

#Testing

moon info
moon fmt
moon test

moon test --target js
moon test --target native

moon run cmd/fuzz -- ci
moon run --target wasm cmd/fuzz -- ci
moon run --target wasm-gc cmd/fuzz -- ci

bash tools/check-test-tautologies.sh
git diff --check

#Benchmarks

moon run --target js cmd/bench
moon run --target native cmd/bench

moon build --target wasm cmd/bench
node tools/run-wasm-bench.mjs _build/wasm/debug/build/cmd/bench/bench.wasm

moon build --target wasm-gc cmd/bench
bun tools/run-wasm-bench.mjs _build/wasm-gc/debug/build/cmd/bench/bench.wasm

node tools/collect-benchmarks.mjs --runs 5 \
  --markdown _build/bench/report.md \
  --out _build/bench/report.json

#Documentation

• docs/wiki/00-sources.md — RFC/IANA source policy.
• docs/wiki/02-protocol-model.md — parser event model and TELNET byte stream notes.
• docs/wiki/03-option-negotiation.md — negotiation model.
• docs/wiki/04-options-catalog.md — option support matrix.
• docs/wiki/06-testing-compliance.md — test and fuzz strategy.
• docs/wiki/conformance-matrix.md — requirement-to-test traceability.

#License