TELNET.pmod

//
// The TELNET protocol as described by RFC 764 and others.
//
// Henrik Grubbström <grubba@roxen.com> 1998-04-04
//

#pike __REAL_VERSION__

// #define TELNET_DEBUG

#ifdef TELNET_DEBUG
#define DWRITE(X ...)	werror("TELNET: " X)
#else
#define DWRITE(X ...)
#endif /* TELNET_DEBUG */

//! Implements TELNET as described by RFC 764 and RFC 854
//!
//! Also implements the Q method of TELNET option negotiation
//! as specified by RFC 1143.

/* Extract from RFC 1143:
 *
 * EXAMPLE STATE MACHINE FOR THE Q METHOD OF IMPLEMENTING
 * TELNET OPTION NEGOTIATION 
 *
 * There are two sides, we (us) and he (him).  We keep four variables:
 *
 *    us: state of option on our side (NO/WANTNO/WANTYES/YES)
 *    usq: a queue bit (EMPTY/OPPOSITE) if us is WANTNO or WANTYES
 *    him: state of option on his side
 *    himq: a queue bit if him is WANTNO or WANTYES
 *
 * An option is enabled if and only if its state is YES.  Note that
 * us/usq and him/himq could be combined into two six-choice states.
 *
 * "Error" below means that producing diagnostic information may be a
 * good idea, though it isn't required.
 *
 * Upon receipt of WILL, we choose based upon him and himq:
 *    NO            If we agree that he should enable, him=YES, send
 *                  DO; otherwise, send DONT.
 *    YES           Ignore.
 *    WANTNO  EMPTY Error: DONT answered by WILL. him=NO.
 *         OPPOSITE Error: DONT answered by WILL. him=YES*,
 *                  himq=EMPTY.
 *    WANTYES EMPTY him=YES.
 *         OPPOSITE him=WANTNO, himq=EMPTY, send DONT.
 *
 * * This behavior is debatable; DONT will never be answered by WILL
 *   over a reliable connection between TELNETs compliant with this
 *   RFC, so this was chosen (1) not to generate further messages,
 *   because if we know we're dealing with a noncompliant TELNET we
 *   shouldn't trust it to be sensible; (2) to empty the queue
 *   sensibly.
 *
 * Upon receipt of WONT, we choose based upon him and himq:
 *    NO            Ignore.
 *    YES           him=NO, send DONT.
 *    WANTNO  EMPTY him=NO.
 *         OPPOSITE him=WANTYES, himq=NONE, send DO.
 *    WANTYES EMPTY him=NO.*
 *         OPPOSITE him=NO, himq=NONE.**
 *
 * * Here is the only spot a length-two queue could be useful; after
 *   a WILL negotiation was refused, a queue of WONT WILL would mean
 *   to request the option again. This seems of too little utility
 *   and too much potential waste; there is little chance that the
 *   other side will change its mind immediately.
 *