From 077479b0030445f541470804f8f7e57a2ad68f72 Mon Sep 17 00:00:00 2001 From: Jesse Luehrs Date: Tue, 30 Jun 2009 00:01:57 -0500 Subject: add description and caveats --- lib/IO/Socket/Telnet/HalfDuplex.pm | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/lib/IO/Socket/Telnet/HalfDuplex.pm b/lib/IO/Socket/Telnet/HalfDuplex.pm index 5b82130..4cd7c0c 100644 --- a/lib/IO/Socket/Telnet/HalfDuplex.pm +++ b/lib/IO/Socket/Telnet/HalfDuplex.pm @@ -18,6 +18,35 @@ IO::Socket::Telnet::HalfDuplex - more reliable telnet communication =head1 DESCRIPTION +A common issue when communicating over a network is deciding when input is done +being received. If the communication is a fixed protocol, the protocol should +define this clearly, but this isn't always the case; in particular, interactive +telnet sessions provide no way to tell whether or not the data that has been +sent is the full amount of data that the server wants to send, or whether that +was just a single packet which should be combined with future packets to form +the full message. This module attempts to alleviate this somewhat by providing +a way to estimate how much time you should wait before assuming that all the +data has arrived. + +The method used is a slight abuse of the telnet out-of-band option +negotiation - most telnet servers, when told to DO an option that they don't +understand, will respond that they WONT do that option, and will continue to do +so every time (this is not guaranteed by the telnet spec, however - if this +isn't the case, L is the only option). We can use this +method to get an estimate of how long we should wait for the data. This module +sends a ping in the out-of-band data before reading, with the assumption that +by the time it gets to the server, all the output that has been generated by +your most recent C will already be queued up in the server's output +buffer. This would be guaranteed if we were just communicating with the telnet +server directly, but typically we are communicating with a subprocess spawned +by the telnet server, which means that the telnet server can respond to the +ping while the subprocess is continuing to send data, making this not failsafe. +It's generally a safe assumption for interactive programs across a network, +though, since interactive programs tend to respond quickly, relative to network +latency. After sending the ping, we just read as much as we can until we get +the pong. This process is all wrapped up in the L method provided by +this module; the rest of the interface is just inherited from +L. =cut @@ -99,6 +128,13 @@ sub _telnet_negotiation { return $self->$external_callback($option); } +=head1 CAVEATS + +This is not actually guaranteed half-duplex communication - that's not possible +in general over a telnet connection without specifying a protocol in advance. +This module just does its best to get as close as possible, and tends to do +reasonably well in practice. + =head1 BUGS No known bugs. -- cgit v1.2.3-54-g00ecf