// $Id: README 61580 2004-11-05 04:29:02Z mesnier_p $This directory contains the HTTP Tunneling, Bidirectional, Protocolimplementation. This is a new streaming abstraction layered over anHTTP document request/reply mechanism. It is designed to allow clientsthat are inside a of a corporate firewall to communicate with serversthat are outside, hence HTTP Tunneling. Also, once a connection isestablished, the outside peer is able to send asynchronous messages tothe inside peer, hence Bidirectional.HTBP provides Acceptor, Connector, and Stream classes that follow theinterface defined for the ACE_Acceptor and ACE_Connectortemplates. This means that HTBP can be used right away withapplications designed to use these templates.Bidirectionality is achieved in the context of the proxy's restrictionby using two channels between the peers. One channel is defined fordata flow from the inside to the outside, data flow from the outsidein occurs on the other channel. In-to-out data is passed in the formof a PUT command with the data payload marshalled into an"application/gzip" buffer. On this channel, the outside peer alwaysresponds with a simple document which serves as an ack. On theout-to-in channel, the inside client must send a token request in theform of a GET command. This request goes unfulfilled until the outsidepeer has data to send, which it does by supplying an HTML documentthat again encapsulates the data so that it may pass through the proxyuncorrupted.The connections from the inside peer to the proxy, or from the proxyto the outside peer may be closed by the proxy at any time. The insidepeer will automatically reconnect as needed when this happens. Sincethe outside peer cannot actively connect to the proxy, it will queueoutbound messages as long as it can until a new out-to-in channel ismade available, at which time it will flush its queue. The sense ofchannels may change over time, as the proxy may choose any localconnection to the server to send any request (GET or POST).The outside peer is identified using an ordinary INET addr, howeverthe inside peer uses a simple, transient unique ID to identifyitself. Inside peers will never have any type of persistent identity.The unique ID used to identify the inside peer is usually a UUID valueas composed by ACE_UUID_Generator. However, a domain based unique IDmay also be obtainedusing HTBP::ID_Requestor::get_HTID(). If no domainbased ID generator is configured, get_HTID() will return a UUID value.As there are a variety of HTTP proxies available, HTBP uses apluggable filter class that defines the particular characteristics ofa proxy and is responsible for marshalling and unmarshalling binarydata. As of now there is a single filter available that works with adefaulted Squid proxy and may also be used as a null filter, directlyconnecting the inside and outside peers. This mode is useful fortesting.CONFIGURING HTBPThis is done through the ACE_Configuration framework. On windowsplatforms, the Windows Registry may be used, whereas on non-windows, aflat file is used to configure. Configuration data may also bepersisted in a memory mapped file.The configuration map contains a single section, HTBP, that containsall the configurable parameters in name=value form. The following isan example of a configuration file:[htbp]proxy_host=<hostname>               This is the hostname of the http                                    proxy through which all requests                                    will be sent.proxy_port=<port>                   This is the proxy's port.htid_url=<url>                      If a domain based unique id is                                    required, this is the URL of the                                    ID generator.htid_via_proxy=<1|0>                If the htid_url must be reached                                    via the proxy, set this to 1.                                    Default is 0, meaning the ID                                    generator is directly accessible.COMPANION DIRECTORIES:$ACE_ROOT/tests/HTBP.               These are the test drivers, which                                    also serve as example code.$TAO_ROOT/orbsvcs/orbsvcs/HTIOP     This is a TAO pluggable protocol                                    based on HTBP.$TAO_ROOT/orbsvcs/tests/HTIOP       The tests for HTIOP.BACKGROUND INFORMATIONHT AddressesThe class HT_Addr is a subclass of ACE_INET_Addr class. The interfacefor the HT_Addr is a common interface to be used with the inside andoutside peers. The inside peer is identified by a HTID while theoutside peer is identified with an ip address.  Constructors areprovided to initialize the inside and outside peers in addition to thedefault and copy constructors.  addr_to_string and string_to_addrmethods from the base class are overridden to help convert the HT_Addrto a string and vice versa. Finally, the class provides accessormethods for the default local address and the default proxy addresses.The local address is the address of the inside peer and is obtainedusing the singleton HTID_Requestor class. The HTID_Requestor classsends a request to the web server that is running at the htid_url toget the HTID unique to each inside peer.The proxy address is of ACE_INET_Addr type as it is no different to aregular server. It is obtained using the singleton HT_Environmentclass. The HT_Environment class helps read the HT configuration fileand provides acccessors to the proxy address, port and the htid url.The code below illustrates the initialization of a local or inside,remote or outside and the proxy addresses using the classesaforementioned. HT_Addr local(HTID_REQUESTOR::instance()->get_HTID());    char hostname [1000];    if (ACE_OS::hostname (hostname,		      1000) == -1)    {      ACE_DEBUG ((LM_DEBUG, "Could not get the host name\n"));      return -1;    }    HT_Addr remote (8088, hostname);    char proxy_address [1000];    HT_ENVIRONMENT::instance ()->get_proxy_address (proxy_address);    unsigned int proxy_port;    HT_ENVIRONMENT::instance ()->get_proxy_port (proxy_port);    ACE_INET_Addr proxy(port, proxy_address);HT StreamsThe class HT_Stream is a sibling of the ACE_SOCK_IO class. It is usedto send and receive messages between two peers identified by their HTaddresses.  It is made a sibling of the ACE_SOCK_IO class rather thana decendant. This is due to the requirement in the HTBP protocol towrap all messages with an HTTP request or reply wrapper, and to sendapplication data in only one direction on one stream.HT SessionsA session is an entity that combines two HT_Streams that connectdirectly to a proxy to manage communication with a remote peer. Thesession may persist longer than either stream, assuming that the proxyis libel to close a connection at any time. This means that thesession needs to be able to reconnect to the remote peer. This alsomeans that the session needs to be aware of its location.  If it isoutside the proxy and looses a stream, nothing can really be done. Ifit is inside, then the next time a stream is required, then it mustreconnect before returning the stream. The session does not queueoutbound messages. It will be the responsibility of the application ora higher level protocol wrapper.Each session is identified by a special type,HT_Session_Id_t. HT_Session_Id_t is a class with three members, thelocal address, the peer address and an id of type ACE_UINT32. Asession map, ....Besides the default constructor and copy constructors, two otherconstructors are provided to initialize a session and are shown below.  /// Constructor (sets the underlying session id with <sid>).  HT_Session (const HT_Addr& peer,	    const HT_Addr& local = HT_Addr::default_local(),	    ACE_UINT32 sid = 0,              ACE_INET_Addr *proxy = 0,              int take_proxy = 0);  HT_Session (const HT_Session_Id_t &id,              ACE_INET_Addr *proxy = 0,              int take_proxy = 0);If a session id (sid) is not provided by the user, it is generatedusing the static method HT_Session::next_session_id().The following code illustrates the usage of HT_Stream and HT_Sessionclasses.HT_Filters<TBD>