Sipper 1.1.3

data/sipper/controllers/invite_controller.rb

@@ -0,0 +1,30 @@
+require 'base_controller'
+
+class InviteController < SIP::BaseController
+
+   transaction_usage :use_transactions=>true
+   
+   def initialize
+     logd("#{name} controller created")
+   end
+   
+   
+   def on_invite(session)
+     logd("on_invite called for #{name}")
+     r = session.create_response(200, "OK")
+     r.server = "Sipper"
+     session.send(r)
+   end
+   
+   
+   def on_ack(session)
+     logd("on_ack called for #{name}")
+   end
+   
+   def on_bye(session)
+     logd("on_bye called for #{name}, now invalidating")
+     r = session.create_response(200, "OK")
+     session.send(r)
+     session.invalidate(true)
+   end
+end

data/sipper/controllers/order.yaml

@@ -0,0 +1,3 @@
+- invite_controller.rb
+- second_hello_controller.rb
+- hello_controller.rb

data/sipper/custom_message.rb

@@ -0,0 +1,4 @@
+require 'ostruct'
+
+class CustomMessage < OpenStruct
+end

data/sipper/detached_session.rb

@@ -0,0 +1,11 @@
+require 'session'
+require 'sip_logger'
+
+class DetachedSession < Session
+  include SipLogger
+  
+  def initialize(rip, rp, rs, session_limit=nil, sepecified_transport=nil)
+    super(nil, nil, nil, rs, session_limit)  
+  end
+  
+end

data/sipper/docs/manual.txt

@@ -0,0 +1,1621 @@
+- todo make it rdoc compatibile
+- todo have several complete examples in the doc to clarify usage. 
+- todo Have two part manual. (a) Test/App Developer's manual (b) Sipper Developer's manual
+- todo Rather than large paras have small headings
+- todo with each section have a SIP box or SIP section that describes or refreshes the SIP concepts
+  or quote from the RFCs. 
+
+Third Party Libraries
+---------------------
+0. Ruby 1.8.5 or higher
+1. Log4r : http://log4r.sourceforge.net/  
+2. Flex Mock : http://onestepback.org/software/flexmock/   gem install flexmock
+3. Facets 1.8.54 [Note previous version shall not work]
+4. Rake
+5. SMC http://smc.sourceforge.net/
+
+
+
+Manual
+------
+
+To get started set the environment variable SIPPER_HOME to where the sipper lib is installed, upto and 
+including sipper_src. IMPORTANT Even on Windows platform for this ENV var, use the forward slashes.
+Also set the configuration defaults in the SipperConfigurator of which the most important is the
+:LocalSipperIP which should be set to each of  the nodes IP (or name), this is the only node
+specific configuration. In case of multihomed host you can start the Sipper instance on any of the 
+IP addresses using the Sipper start options. The :LocalSipperIP is primarily used as a default for 
+tests.    
+[todo clarify the above]
+
+Starting Sipper
+---------------
+Config and default config.
+
+Usage
+-----
+
+Session Object
+--------------
+It is important to first of all understand what this session object is and how does it relate to
+various SIP constructs. 
+First of all this Session object in the Sipper API has nothing to do with the concept of "session"
+as talked about in the SIP RFC 3261, well almost nothing. But please read this small writeup to
+understand not only the Sipper session object but also the overall context it is used. 
+
+The Session in S(ession)IP is the multimedia session established between two end points using the
+SIP offer answer model. So the (SIP) session is a term used for an end-to-end communication session.
+Within the SIP parlance there is another term called "dialog" that is related but not the same as 
+session. While (SIP) session is the overall communication session, the SIP dialog is a signaling 
+only concept that enables the (SIP) session setup to take place. 
+SIP is a signaling protocol and it enables the establishment of these (SIP) sessions. A SIP Dialog
+(early or confirmed) is created when a provisional response with To tag or a 2xx response is 
+received for a dialog creating request (INVITE, SUBSCRIBE, NOTIFY, REFER). 
+A dialog is a context within which further SIP message exchange can take place and a dialog lasts
+until is teared down by a BYE request in most cases. The only purpose of dialog is to establish 
+some state at the end point UAs such that once the dialog is established the subsequent SIP messages
+are delivered and are sequenced properly. 
+(SIP) session may be setup as a result of this dialog creation for the INVITE request. RFC 3261 
+and 3264 define mechanisms of how the offer answer exchange happens using SDP (Session Description
+protocol) that is the payload of SIP messages. 3261 also established some rules as to what SIP
+messages can carry offers and answers. The effect of these rules is that there is a correspondence
+between (SIP) sessions and dialogs. It not necessarily one to one but there is a relationship. 
+Please refer to sections 12-14 of RFC 3261 to better understand the correspondence and distinction. 
+
+Now the Session object that you see in Sipper API is closely associated with a Dialog. In fact
+it a superset of a SIP dialog. A Sipper Session can be created even before any signaling takes
+place on the UAC. In fact this creation would the first step for starting any SIP communication as
+the Session API is the primary API for controllers.  
+
+
+Session creation
+----------------
+A session is automatically created when the request is first received by Sipper before the request is handed over to the right controller. 
+A session can also be created explicitly by invoking one of the several
+create_xxx_session methods defined on the BaseController. 
+Controller usually will know what type of session namely UDP, TCP, TLS or SCTP is it going to require, in such a case you should use the protocol specific method passing the remote ip and port. e.g for UDP the method would be create_udp_session(ip, port). This session is like 
+a point to point association between this Sipper end point and the 
+remote SIP entity at the given IP and port. 
+Sometimes the remote IP and port and even the transport to which the 
+request is to be sent is not known. In such a case procedures defined
+in RFC 3263 are followed to determine the right transport, ip and port
+based upon the appropriate DNS records.
+
+Detached Session
+---------------- 
+In such a case a "detached" session is used which is a session that 
+does not have a transport or a remote IP/port known at creation time.
+Such a session can be created by calling create_session() method. 
+At run time when the request is being sent, the right session protocol 
+is looked up as are the IP and port and are set in the session. 
+From this point onwards for all SIP signaling that transport, IP and port are used. 
+The detached session can also be used for cases when remote SIP end point is not yet known and some signaling in some other protocol is 
+to be done, like HTTP. 
+[Until the actual DNS lookup code is in place the only limitation
+of using create_session is that a real IP needs to be provided in 
+the request uri and currently udp transport is assumed which should
+be fixed when we have tcp and/or 3263 support]
+
+
+Dialog State Management
+-----------------------
+
+
+  Route Set
+  ---------
+  In the case of UAs the Route Set is learned as a result of Record-Route header exchange during setup of the 
+  dialog. This learned route set (even if empty) overrides any pre-existing route set. 
+  The following are relevant quotes from RFC 3261 with respect for route set management all in one place
+  to ease in understanding of the implementation -  
+  
+  "In some special circumstances, the presence of a pre-existing route set can affect the Request-URI 
+   of the message.  A pre-existing route set is an ordered set of URIs that identify a chain of servers, 
+   to which a UAC will send outgoing requests that are outside of a dialog.
+   Commonly, they are configured on the UA by a user or service provider manually, or through some 
+   other non-SIP mechanism.  When a provider wishes to configure a UA with an outbound proxy, 
+   it is RECOMMENDED that this be done by providing it with a pre-existing route set with a single URI, 
+   that of the outbound proxy.
+
+  If the first element in the route set indicated a strict router (resulting in forming the request as 
+  described in Section 12.2.1.1), the procedures MUST be applied to the Request-URI of the request .
+  A dialog contains certain pieces of state needed for further message   transmissions within the dialog.  
+  This state consists of the dialog ID, a local sequence number (used to order requests from the UA 
+  to its peer), a remote sequence number (used to order requests from its peer to the UA), a local URI, 
+  a remote URI, remote target, a Boolean flag called "secure", and a route set, which is an ordered 
+  list of URIs.  The route set is the list of servers that need to be traversed to send a request to 
+  the peer.  
+
+  The route set MUST be set to the list of URIs in the Record-Route header field from the request, taken 
+  in order and preserving all URI parameters.  If no Record-Route header field is present in the request, 
+  the route set MUST be set to the empty set.  This route set, even if empty, overrides any pre-existing 
+  route set for future requests in this dialog.  The remote target MUST be set to the URI from the 
+  Contact header field of the request.
+
+  The UAC uses the remote target and route set to build the Request-URI and Route header field of the request.
+
+  If the route set is empty, the UAC MUST place the remote target URI into the Request-URI.  
+  The UAC MUST NOT add a Route header field to the request.
+
+  If the route set is not empty, and the first URI in the route set contains the lr parameter (see Section 19.1.1), 
+  the UAC MUST place the remote target URI into the Request-URI and MUST include a Route header field 
+  containing the route set values in order, including all parameters .
+
+  If the route set is not empty, and its first URI does not contain the lr parameter, the UAC MUST 
+  place the first URI from the route set into the Request-URI, stripping any parameters that are not 
+  allowed in a Request-URI.  The UAC MUST add a Route header field containing the remainder of the 
+  route set values in order, including all parameters.  The UAC MUST then place the remote target URI 
+  into the Route header field as the last value. "
+  
+  As usual Sipper allows multiple ways to set the pre-existing route set. 
+  1. It can be configured system wide using the configuration parameter SipperConfigurator[:PreExistingRouteSet]
+  2. This can be overridden by a controller directive pre_existing_route_set <array> which affects all 
+     initial requests created by this controller. [see e.g. test_controller_using_pre_existing_rs1.rb]
+  3. This can be overridden while creating session and passing arguments to it. 
+     [see e.g. test_controller_using_pre_existing_rs2.rb]
+ 
+  Note:
+  The route set handling, target selection and strict router handling is all done automatically by Sipper, 
+  however for testing purposes if it is ever required to modify the request-uri or change the Route headers
+  (differently from the normal protocol behavior), the message can be changed prior to sending in any way. 
+  
+  
+  
+Session Invalidation
+--------------------
+When session.invalidate is called then the session does not immediately terminate. This is so because there
+may be some messages in the network owing to retransmissions that this session should deal. 
+Therefore the session is scheduled for invalidation at a time configured in as SipperConfigurator option 
+:SessionTimer. This is global setting for every session which can be overridden at the session level by 
+either calling session.session_timer = xxx or by setting the controller directive "session_timer". 
+The value of this parameter is in milliseconds. 
+
+Further the invalidate() method takes a boolean argument (force) which if set invalidates the session 
+immediately.
+
+When the timed session invalidation is going to happen the controller can optionally implement 
+session_being_invalidated_ok_to_proceed?(session) and return false if they want to increase the life
+of session. They can also set a new session timer value by calling session.set_session_timer(val) which 
+then becomes the new invalidation timer increment. 
+This extension cannot however go on indefinitely, there is an upper limit to the session lifetime
+which by default comes from the configuration parameter :SessionLimit. This can also be set by the 
+controller directive "session_limit" which roughly becomes the overall maximum lifetime of the session.
+"Roughly" because if the session has lived for time x, the session timer is x' and the 
+session limit is set for y where y > x but x + x' > y then the session will not re-schedule but 
+invalidate. In other words if the increment is such that it will increase the lifetime beyond
+session limit then it is not re-scheduled.  See the test case "test_session_lifetime" to see the 
+example of usage of these timers. 
+
+Session Limit Cleanup Timer
+---------------------
+The session timer kicks in only when the invalidate call is made. For situations where the controller
+never calls invalidate on session there is a overarching cleanup timer whose value is set to the 
+:SessionLimit that cleans up these session resources regardless. 
+
+
+
+Assigning Headers
+-----------------
+You can do simple assignments as msg.from = "myfrom" which will add the header. 
+While assigning headers the argument must be a string. 
+In case you have a multivalued header you can do either of 
+1. msg.route = "route1, route2, route3"
+2. msg.route = ["route1", "route2", "route3"]
+3. msg.add_route("route1").add_route("route2").add_route("route3")
+4. msg.push_route("route3").push_route("route2").push_route("route1")
+
+Header can be accessed by either the accessor eg. msg.header_name or by the hash access 
+msg[:header_name] note: it is better to use hash access for custom headers because if they are not
+created you might get a method missing exception.
+
+todo - elaborate above. 
+
+
+Accessing Headers and Content
+-----------------------------
+Headers can be accessed simply by using a method name same as that of the header name. As an example
+you can access To header by calling request.to or response.to, or for that matter any custom 
+header like request.my_header.
+Another way to access header value is use the hash access on the message using the header name as the symbol key. As an example you could access the via header using request[:via].  These two methods are almost identical though the latter should be preferred when you are not sure of the existence of an header and want to check it. So you should do something like - 
+  if request[:my_header]
+    puts request.my_header 
+  end
+This is particularly relevant for custom headers as Sipper creates the dynamic method access on messages for headers that are known to Sipper, you could of course do things like request.my_header = "foo" in which case Sipper will create the header and also dynamically generate the method definition for such access. However if you are accessing header which has not been assigned so far with method access like request.unknown_header_so_far() then Sipper shall throw an UnknownMethod Exception, the hash access request[:unknown_header_so_far] would correctly return nil. 
+
+Message content can also be accessed in a similar way, but make sure you use the plural form of content method. So request.content() returns only the first line of content while request.contents (note the s in the end) shall return the entire content as an array. (See the section on multivalued headers to see how Sipper uses the same mechanism for multivalued headers as well). 
+However if you want the message content as it is in raw form then you should use the method body() defined on the message. So request.body() shall return the message body as it appeared as a single string. 
+[todo add proper protocol handlers for handling sdp and other content types for proper handling].   
+ 
+
+Header Params
+-------------
+The easiest way to add a param to a header is to just add it by a method invocation. The header should 
+be defined before that. So to add a parameter foo to the header via you could do msg.via.foo = "bar".
+Note that this way of adding parameter implicitly parses the headers. If you all you want to do is to
+set a header with some parameter then you can directly add the header as string  
+e.g msg.test_header = "header;foo=bar" 
+
+Multivalued headers
+-------------------
+In a SIP message the headers can be accessed by convenient method like access like 
+msg.via. If the header is a multivalued header then access like this gets the top most header of 
+this kind.
+In order to get the entire set add an "s" to the method. So msg.vias will give you all headers in an
+ordered array.
+
+When you want to format multi valued header as separate headers in the message just invoke 
+format_as_separate_headers_for_mv() on the request/response. As an example the following code adds the 
+Allow header using both add() (to the end) and push() (to the top) variations and then sets them to be 
+used headers on separate lines. 
+
+    r = Request.create_initial("info", "sip:nasir@codepresso.com", :allow=>"INVITE")
+    r.add_allow("BYE").push_allow("OPTIONS")
+    r.format_as_separate_headers_for_mv(:allow)
+    
+The resultant message looks like - 
+
+INFO sip:nasir@codepresso.com SIP/2.0
+Contact: <sip:127.0.0.1:5060;transport=UDP>
+From: Sipper <sip:sipper@127.0.0.1:5060>;tag=1
+Via: SIP/2.0/UDP 127.0.0.1:5060;branch=z9hG4bK-1-0-1
+Call-Id: 1-2292@127.0.0.1
+Max-Forwards: 70
+To: Sut <sip:sut@127.0.0.1:5066>
+Cseq: 1 INFO
+Content-Length: 0
+Allow: OPTIONS
+Allow: INVITE
+Allow: BYE
+
+Whereas if you do not use format_as_separate_headers_for_mv() for multivalued headers the default is 
+single headers with comma separation.
+
+So the message would look like - 
+INFO sip:nasir@codepresso.com SIP/2.0
+Contact: <sip:127.0.0.1:5060;transport=UDP>
+From: Sipper <sip:sipper@127.0.0.1:5060>;tag=1
+Via: SIP/2.0/UDP 127.0.0.1:5060;branch=z9hG4bK-1-0-1
+Call-Id: 1-1804@127.0.0.1
+Max-Forwards: 70
+To: Sut <sip:sut@127.0.0.1:5066>
+Cseq: 1 INFO
+Content-Length: 0
+Allow: OPTIONS, INVITE, BYE
+
+
+Header Parsing
+--------------
+
+There is a default parser that is applied to every unknown header which basically parses the header into
+values and parameters. default_parse? method on such a header returns true. If your new header is such 
+that you need to work on the actual header constituents (for example like Sipper provided Via header) then
+you may need to provide your own parser for that header. 
+
+Any header in the message is always parsed either by using the named parser or if the parser is not present
+for a header then the default parser. The string version of header value is always accesible through
+to_s method on the header. For example for a request say r you would use - 
+  r.from.to_s to get the string representation of the From header. 
+  
+Assigning anything to the header results in either setting or creation of the named parameter. As an 
+example - 
+  request.to.tag = "xyz" results in setting of a tag parameter on the To header of the request. 
+If the parameter is not a known parameter, it is created on the header and can be accessed later by name
+  
+  response.via.foo = "bar" 
+Would result in creation of a new parameter foo with value bar on the Via header, something so 
+  response.via.to_s woudl then return something like - 
+SIP/2.0/UDP 127.0.0.1:6061;branch=z9hG4bK-2352-1-0;received=127.0.0.2;foo=bar 
+All the Message assignment methods like message.header_name = "xyz", message[:header_name] = "xyz" or 
+message.push or message.add result in parsing of the header value as header object. 
+Any subsequent access of the header returns the appropriate header object. Caling a to_s on the header
+object returns a properly formatted header string. Also on the header object can be called header_value 
+which returns the header value without the parameters and header_params which returns the parameters
+in a hash. 
+Depending upon the headers there are various convenience methods provided to access header constituents
+which are not necessarily header parameters eg. via.protocol, via.transport, from.diaply_name etc. 
+Besides this all the parameters defined on the header are also available as attributes e.g from.tag, 
+via.maddr etc. These attributes can also be changed and they will then affect the header value e.g 
+e.g if via.to_s is "SIP/2.0/TLS 175.19.37.207:6062;branch=z9hG4bK-1-0" and you change the sent_by_port
+like via.sent_by_port = "6063" then via.to_s now returns "SIP/2.0/TLS 175.19.37.207:6063;branch=z9hG4bK-1-0"
+
+Force assign a header
+---------------------
+In some cases you want to assign a header and bypass the parsing altogether. In that case use 
+Message#assign_unparsed instead of usual assignment. The header thus assigned is a string value and 
+no parser is invoked. Also if you already have a header object and want to assign but not parse a value
+then Header#assign(value, parse_option) can be used with parse_option as false. 
+  e.g. request.from.assign("Nasir Khan <sip:nasir@sipper.com>;tag=1", false) assigns the string to the
+already defined From header but assigns it without parsing. 
+However, a subsequent call to assign with parse_option as true now parses and assigns the header. 
+
+
+Freezing a header
+-----------------
+Header#freeze freezes the header and fixes the value of the header. Any further assignment will fail and 
+the value of the header as of now if also frozen. There is no way to unfreeze a header. 
+
+Providing a custom pluggable parser is extremely
+easy to do. 
+
+Write your own parser for a new header
+---------------------------------------------
+Your parser need to be in the lib/sipper_extensions directory under your controller source tree. 
+It should be a class in the module SipHeaders and the class itself
+should be a subclass of Header. So for a header called Foo your class will look like 
+
+module SipHeaders
+  class Foo < Header
+  end
+end
+
+The next thing that you may want to do is to provide an assign method that would parse and populate 
+various header constituents. You may also provide header_value and optionally a private _format and 
+header_params  
+
+
+Extensions Mechanism
+-------------------
+With your controller you can also provide an optional extension that can be used to extend the Sipper
+behavior. Under your lib directory under controller source tree you may provide a sipper_extensions 
+directory. In that you can provide a ruby source file where you may re-open any Sipper class. 
+Using the extensions mechanism you can for example modify an existing parser provided by Sipper. 
+As an example see test_extensions.rb for a sample of how From header formatting can be changed. 
+Note however that this extension is a Sipper level extension and once provided shall be applicable to 
+all controllers henceforth. 
+It is a good practice to "require" the file that is being extended in the extension before it is reopened
+and changed. 
+
+Stray Messages and Stray Message Handler
+----------------------------------------
+A stray message is a subsequent request or response for which no session is found or is an initial
+request for which no suitable controller could be found. 
+The default behavior to handle a stray message is to silently drop it. 
+An optional stray message handler can be provided that can deal with the stray message in many ways. 
+The stray message handler needs to be a subclass of SIP::StrayMessageHandler class (to be required from
+stray_message_manager.rb). The stray message handler can be anywhere with the controller, even inline but 
+the preferred place for the handler is the sipper_extensions directory. This is the place from where the
+extensions are loaded on startup. 
+The only method that needs be implemented by the stray message handler is the handle(message) method 
+that takes the stray message as an argument and is expected to return and array the first element of 
+which is an enum value the values of which are - 
+
+  1. SIP::StrayMessageHandler::SMH_DROP
+  2. SIP::StrayMessageHandler::SMH_HANDLED
+  3. SIP::StrayMessageHandler::SMH_RETRY  
+  4. SIP::StrayMessageHandler::SMH_TREAT_INITIAL
+
+Both SIP::StrayMessageHandler::SMH_DROP and SIP::StrayMessageHandler::SMH_HANDLED indicate that Sipper 
+does not need to deal with the message any more. 
+SIP::StrayMessageHandler::SMH_RETRY indicates that the message is to be retried. The message to be 
+retried is taken from the second element of the array returned from the stray message handler if present. 
+The idea is that SMH may modify the request such that it may find a session now. However, the retry 
+happens only once. 
+The return value SIP::StrayMessageHandler::SMH_TREAT_INITIAL indicates that the subsequent request 
+that could not find a session should now be treated as an initial request and retried, again the retry 
+shall happen only once. 
+Of course for the stray message that is was already an initial request or is a response the TREAT_INITIAL
+option is not applicable.
+
+To illustrate if a stray request is received then following can be done in the stray message handler - 
+
+1. Drop the request without doing any processing (this is also the default in absence of a handler), this
+   can be accomplished by returning [SIP::StrayMessageHandler::SMH_DROP, nil] from the handler. For an 
+   example of dropping the message through the handler see test_stray.rb and test_stray_inline.rb
+   
+2. Create and send a response to the request. For example send a 500 class response. In order to send the
+   response to a stray request the following needs to be done - 
+   
+   class ResponsiveStrayHandler < SIP::StrayMessageHandler
+      def handle(m)
+        ## ["AF_INET", 33302, "localhost.localdomain", "127.0.0.1"]
+        if m.is_request? && m.rcvd_from_info[0] == "AF_INET"
+          remote_ip = m.via.received || m.via.sent_by_ip
+          remote_port = m.via.sent_by_port
+          s = UdpSession.new(remote_ip, remote_port, nil)
+          r = s.create_response(200, "OK", m)
+          s.send(r)
+          s.invalidate(true)
+        end
+        [SIP::StrayMessageHandler::SMH_HANDLED, nil]
+      end
+    end
+    
+    Of course the first step is definition of a stray message handler class. The message (including stray)
+    has an rcvd_from_info attribute which is an array containing network information on the received message. 
+    In this example above, given that the request was received on UDP (AF_INET) we create a UdpSession for 
+    sending response. Session is the abstraction for all the communication in Sipper and so we create a 
+    session using the remote ip and port from the via header. 
+    Usually when you create a response from the session you do not pass the request to create the session
+    from because the session already knows about the incoming request, however in this case it is required
+    to pass in the stray request to session. There is also a minor kink of calling the create_response with 
+    not just the response code but also the response phrase "OK". You could alternatively have also used 
+    r = s.create_response(200, "SELECT", m) which selects the appropriate phrase from the response phrase
+    dictionary. 
+    Always remember to invalidate the session after you create such temporary sessions, if you do not do it
+    the session will eventually get timed out but needlessly hog memory till such time. 
+    Finally we must return from the handle() method the result of our actions which in this case is 
+    [SIP::StrayMessageHandler::SMH_HANDLED, nil]
+    
+3.  Retry the subsequent request after changing something in the request (for example the tags)
+    See the test_stray_retry.rb for an example of retrying the request, in this, arguably contrived example
+    the handler knows about the actual tags from another message parameter, but broadly this illustrates
+    how returning SIP::StrayMessageHandler::SMH_RETRY and the message as the second array element retries the
+    new request for dispatch. 
+    Keep in mind that this retry happens only once.  
+    class RetryStrayHandler < SIP::StrayMessageHandler
+      def handle(m)
+          m.from.tag = m.from.orig_tg
+        [SIP::StrayMessageHandler::SMH_RETRY, m]
+      end
+    end 
+    
+4.  Retry the request as if it is an initial request. This will allow the Sipper to create a new controller
+    session to deal with the request. An example could be a BYE request that was delivered to a system after
+    a failure and we instead of dropping it want to invoke a controller to handle it for billing purposes. 
+    See test_stray_retry_initial.rb for an example. Here the subequent BYE did not find a session as it was 
+    invalidated on ACK. Now the handler returns the same stray message (i.e BYE) with a TREAT_INITIAL flag. 
+    This results in Sipper creating a new session and finding an appropriate controller, which happens to be 
+    the same UAS controller. Another interesting aspect illustrated in this example is the usage of 
+    session.force_update_session_map = true in the UAC controller before sending the BYE. Normally the session
+    is added to the session map automatically, in this case however the session is already added as it has 
+    both local and remote tags. "session.force_update_session_map = true" forces the entry in the map with 
+    the new tags such that when the 200 OK is received for this BYE it reaches the session. 
+
+
+Similarly the stray responses can also be handled, not much is done with the responses except for 
+perhaps sending ACK in some extreme test cases. Usually you would just record the receipt of a response
+in the stray handler. 
+
+The following example illustrates sending of an ACK from the stray message handler for the response. 
+Please see the test case test_stray_res_acked.rb for a complete flow. 
+  
+  class ResponseStrayHandler < SIP::StrayMessageHandler
+      def handle(m)
+        ## ["AF_INET", 33302, "localhost.localdomain", "127.0.0.1"]
+        if m.is_response? && m.rcvd_from_info[0] == "AF_INET"
+          remote_ip = m.rcvd_from_info[3]
+          remote_port = SipperConfigurator[:LocalTestPort]
+          rts = if m[:record_route]
+            m.record_routes.reverse
+            else
+              nil
+            end
+          s = UdpSession.new(remote_ip, remote_port, rts)
+          r = s.create_initial_request("ACK", m.contact)
+          r.copy_from(m, :from, :to, :call_id)
+          s.send(r)
+          s.invalidate(true)
+        end
+        [SIP::StrayMessageHandler::SMH_HANDLED, nil]
+      end
+    end
+    
+Since sending an ACK literally from thin air is not a normal scenario, we may have to write a few 
+extra lines to get it right.     
+In this handler we first extract the remote IP from the rcvd_from_info attribute from the message and 
+since there is no way to find the remote port to which to send the ACK we use the :LocalTestPort
+from our configuration. To be strictly correct we take the Record-Route header values from the response
+and create the Route headers by reverting them. Next we create an initial request from a newly created
+session and copy headers from response and send it. It is important to copy From/To and CallId to be 
+able to match the remote dialog on the UAS. 
+
+    
+Message Attributes
+------------------
+You can set and get attributes on the Message (both request and response) at any time and 
+retrieve the value later. The attributes are stored in a hash with the message. 
+e.g  
+  request.attributes['one'] = 1
+  my_attr = request.attributes['one']
+  
+
+
+Controller Invocation
+---------------------
+todo clarify: 
+A controller is a class that is defined to handle requests or responses using the defined API. 
+A controller class must be derived from either the BaseController or from any of the BaseController's
+children. 
+The controller class name must have the string "Controller" in it. Valid names of controllers are 
+"UacInviteController", "MyTestController1" etc. while "MyTestcontroller" and "MyRandomClass" are not
+valid controller names. 
+The controllers are read from a controller directory and if there is an order.yaml present then
+they are tried in that order of invocation. If order.yaml is not present then the order
+defaults to alphabetical ordering. Even if present order.yaml does not need to list every
+single controller, only the ones listed will be tried in that order and the remaining default
+to alphabetical ordering. 
+Of the ordered list of controllers thus present, on a request interested? method is invoked
+on the controllers, only if they return true is that controller invoked. 
+The default interested? implementation just looks for the presence of the appropriate handling
+method, like for INVITE it looks for the implementation of "on_invite" method to see the 
+interest. 
+If the controller is defined inline then there is an option to have a method "order" on the 
+controller itself that places this controller on the defined index in the ordered list. 
+Controller interface for upcall of messages are -
+1. on_request(session) [on_invite, on_bye.....extended to any SIP method including custom methods]
+2. on_response(session) [on_trying_res, on_provisional_res, on_success_res, on_redirect_res, on_failure_res]
+3. on_timer(session) for invocation of timers
+  
+Besides this controllers is consulted for order() if implemented and interested?(),
+again if implemented. 
+
+Apart from this the controller can also implement the callback listener methods for session events
+
+1. no_ack_received(session) - if controller acted as a UAS and 2xx retrasnmission timer (64*T1) expires.
+2. no_prack_received(session)
+3. session_being_invalidated_ok_to_proceed?(session) - when the session is going to be invalidated
+   if the return value from this is false then the session_timer is reset and session is not
+   invalidated. The default value is true if not implemented. If the controllers want to change the
+   session lifetime in this callback they can do so by calling set_session_timer before returning 
+   false from this callback method. 
+   See test_session_callback_handler.rb to see an example. 
+
+
+Controller Lib
+--------------
+The default controller lib dir is controller_directory/lib. This can be changed by using 
+:ControllerLibPath configuration. This is automatically added to load path and so inside the 
+controller you can require any of your lib files. Usually you will put your state machine files
+or transaction handler files there but it can be any external library too. 
+Important to note that even though the default for :ControllerLibPath is controller_directory/lib but
+once set it does not change even if you change :ControllerPath subsequently. 
+
+Further there is a mechanism to load arbitrary libraries at the global level which you can do by 
+putting them (nested or otherwise) under the sipper/lib directory. These will be automatically loaded
+at sipper startup time. In case you want to reload libraries at the top level, for example you have
+dropped in a plugin module and want it to be reloaded then simply use the method
+  Sipper#reload_libs 
+to reload everything under the sipper/lib directory dynamically. 
+
+You should keep different types of libs in separate directories under
+the controller lib and top level lib. So the transaction handlers should be placed in a directory 
+separate from state machine drivers, the transport filters should always be placed under the directory 
+transport_filters . 
+See sipper_test/test_controllers/ict_tcbh directory and sipper_test/test_controllers/ctrl_trhandler 
+for an example of the layout. 
+
+
+Controller Directives
+---------------------
+
+1.  start_on_load <boolean>  e.g start_on_load false
+2.  transaction_usage <hash> e.g transaction_usage :use_transactions=>false, :use_ict=>true
+3.  transaction_timers <hash>  e.g transaction_timers :t1=>100, :tb=>7000
+4.  transaction_handlers <hash> e.g transaction_handlers :Ict=>MyIctHandler, :Nict=>MyNictHandler, :Base=>CatchAllHandler
+5.  session_timer <num>  e.g session_timer 500
+6.  session_limit <num>  e.g session_limit 2000
+7.  t2xx_usage <boolean> e.g t2xx_usage true
+8.  t2xx_timers <hash> e.g t2xx_timers :Start=>200, :Cap=>400, :Limit=>1500
+9.  header_order <array> e.g. header_order [:to, :from, :call_id, :via, :cseq]
+10. pre_existing_route_set <array> e.g. pre_existing_route_set ["sip:nasir@sipper.com;lr", "sip:nasir@goblet.com;lr"]
+11. use_compact_headers <array>  e.g use_compact_headers [:via, :from] or use_compact_headers [:all_headers] 
+
+Ordering of headers
+-------------------
+There are many ways to order headers in messages generated by Sipper. 
+(a) Using controller level directive - header_order [:to, :from, :call_id, :via, :cseq] orders the 
+    request and responses generated as a result of this controller activity in the given order. 
+
+(b) Set at the session level. Session#set_header_order(order_arr). Sets the header order array to the 
+    session and that applies to all the messages after this invocation. This overrides any setting
+    that the controller set using header_order directive.
+    e.g  session.set_header_order([:to, :from, :call_id, :via, :cseq])
+     
+(c) Setting directly on the message. This is the local scope limited to the message is question and 
+    does not affect other messages from the session.  This overrides both the directive setting and 
+    also the session level setting. 
+    e.g. request.header_order([:to, :from, :call_id, :via, :cseq])
+    
+    
+Using Compact headers
+---------------------
+In coming message is transparently parsed for any known compact form. As for outgoing messages there
+are three options. 
+
+(a) A controller level directive - e.g use_compact_headers [:via, :from] can be used to use cpmpact 
+headers in all messages generated by this controller for all sessions. 
+
+(b) Set at the session level. Session#set_compact_headers(array). Sets for the session and all messages
+that are sent from this session after the setting. 
+
+(c) Directly at the message. This has the scope limited to just this message in question. 
+  e.g request.compact_headers = [:to, :from]
+  
+In all the above cases a special symbol :all_headers can be used to enable setting of all headers
+as compact which have a compact notation. 
+e.g  use_compact_headers :all_headers
+
+
+    
+Session Recording and Call Flow validation
+------------------------------------------
+Session recording can be enabled by creating a request with header P-Session-Record with value
+either msg-info or msg-debug. 
+With msg-info only the message type and their direction is recorded while with msg-debug the whole
+message is recorded. 
+
+e.g  Request.create_initial("invite", "sip:nasir@sipper.com", :p_session_record=>"msg-info")
+
+The session is recorded in a yaml file whereever the configured value for :SessionRecordPath is. 
+This recording is conveniently made available through helper methods in the SipTestCase class.
+To make it even simpler for the test writer the DrivenSipTestCase class provides a mechanism for 
+automatic validation based on expectation provided as regular expressions. 
+Please see as an example the test test_cancel.rb to see a simple automatic validation of expectation
+based. 
+In that you will also see the usage of message recorded by the controller which is logged as a "neutral"
+message. This message does not have any direction so the direction elemnet in the message is recorded 
+as "!". Note the direction can be "<" for incoming messages, ">" for outgoing messages and "!" for 
+neutral messages. 
+The expectation can be provided in a simple regular expression language provided for Sipper. 
+
+The following is the description of the regular expression support for expectation validation. 
+
+  1. Wildcard is denoted by character "x" and is available for responses only e.g 
+     2xx, 1xx, 18x, 4x0. For wildcard responses the first character in the message MUST be a number. 
+     For example 1xx and 41x are valid as is 3xx but xxx or x00 are not valid as they do not 
+     start with an integer.  
+     
+  2. Alteration is denoted by the pipe symbol "|". e.g. 1xx|2xx|302 (optional) responses.
+   
+  3. Similarly alteration can be used for optional requests "< INVITE|SUBSCRIBE"
+  
+  4. Request and response MUST not be mixed in an alteration.
+   
+  5. Optional repetition can be provided like "> INVITE {min,max}" where min is the minimum times the 
+     incoming INVITE is expected and max is the maximum times the incoming INVITE is expected. 
+  
+     examples. 
+     "> INVITE {2,2}" have exactly 2 outgoing INVITEs.
+     "< 18x {2,3}" have 2 or 3 incoming 18x.  
+     "> 1xx {,3}" at most 3 out going 1xx responses. 
+     "> INVITE|SUBSCRIBE" exactly one INVITE or SUBSCRIBE. 
+     "< 2xx {1,}" at least 1 incoming 2xx responses. 
+     
+  6. The neutral expectation, the one recorded by the controller is recorded with the direction element
+     "!" and  the message string MUST not contain any spaces.    
+   
+  BNF for an element of expectation is - 
+  element    = direction 1*SPACE message*(1*PIPE message) 1*SPACE [repetition]
+  direction  =  ( "<" / ">" / "!" )
+  message    = string_with_no_spaces
+  PIPE       = "|"
+  SPACE      = " "
+  repetition = {[DIGIT] COMMA [DIGIT]}
+
+  To see an example of complex regular expression see the test_expectation_parser or test2xx_retransmission.
+  Valid expressions.
+  
+  Invalid Expresssions
+    "> INVITE, < 100 {0,}, > INVITE" - 
+      because we are stating that exactly one INVITE should come 
+      first and an optional 100 followed by another INVITE. So if 100 does not come then the actual
+      message flow would be two INVITEs in succesion. This would violate the first requirement of 
+      having exactly one INVITE as first element. If you want this behavior then you may use 
+      "> INVITE {1,}, < 100 {0,}" 
+    
+    "< 100, < 100"  - Here you are are expecting to have two 100 responses. If that is the case then '
+    the way to specify is to use the repetition options. So "< 100 {2,2}" should be used instead.   
+
+
+  Complex examples
+  
+  
+  
+
+Simple Controller Generator
+---------------------------
+Simple usage is 
+
+  gen_controller.rb <NameOfTheControllerClass> <flow in quotes>
+  e.g. gen_controller.rb TestController "> INVITE, < 180, > UPDATE, < 200, ! Hello, < 200"
+
+Note that a space is mandatory between direction and message and messages need to be comma separated. 
+Since it does'nt make sense to have a optional outgoing messages for controller generation, if there
+is found a usage like "> INVITE|SUBSCRIBE" then the controller will only be generated to send the 
+first message. INVITE in this case.
+
+It is possible to use the neutral direction "!" and a message following it. The only constraint is the 
+message should be a single word with no spaces. So "message received afer 200" is not valid but 
+"message_received_afer_200" is valid. 
+ 
+If you are using optional incoming message and if one of the message from the optional list is going to 
+be received again then you must use the same optional string in its entirety. 
+
+e.g. > INVITE, < 100, < 180, < 200|202, > ACK, > BYE, < 200
+
+is not valid as we are expecting a 200 or a 202 to INVITE and generating an ACK, while for the BYE 
+we are expecting just 200. While this would be a valid call flow scenario, it may not work correctly 
+so the right flow should be - 
+
+> INVITE, < 100, < 180, < 200|202, > ACK, > BYE, < 200|202
+
+Notice the 200|202 even for BYE. This usually would'nt affect the call flow. 
+The generated controller can be run using the run/run_sipper1 script passing it this 
+generated controller as in run_sipper1.rb -c <proper_path_to my_controller.rb>
+
+Besides the option for messages "<", ">" and log "!" there is also an option of adding a command to the
+flow string. The command start with an @ sign immediately followed by the command. e.g. "@sleep_ms 300" shall
+make the flow sleep for 300 milliseconds. 
+Another useful command is @set_timer <time_in_ms>, which schedules a timer and executes the next command or
+sends out the next message when the timer expires. 
+For a complete list of all commands please refer to documentation for 
+CommandElement class.  
+
+Similarly there is a script to generate the automated test and the accompanying inlined driver
+controller. 
+
+
+Simple Test Generator
+---------------------
+ 
+Usage for gen_test is - 
+
+gen_test.rb <name_of_test_class> "String of call flow" 
+
+e.g gen_test.rb MyTest "> INVITE, < 200, > ACK"
+
+The generated test class can be run standalone as 
+
+ ruby -I <path to sipper_test> my_test.rb
+
+If it is a UAS then it will wait for 180 seconds for getting a request before failing the test. 
+This config is part of generated code, which can be modified later.
+
+
+Generator Scripts
+-----------------
+In order to further facilitate the controller and test generation there is a sgen script provided. 
+
+sgen -h
+
+Options:   --version | -v  => print version information
+           --help | -h  => print this message
+           -c|-t [-r] <class_name> <flow_str>
+         => -c for controller and -t for test generation
+         => -r to optionally generate the reverse or opposite
+            flow from flow_str.
+            i.e if flow indicates UAS then generate a UAC etc.
+         => <class_name> is the name of class to be generated,
+            controller or test.
+         => <flow_str> is the actual call flow.
+            e.g. '< INVITE, > 100, > 200 {2,7}, < ACK'
+          
+          
+            
+Run Script
+----------
+In order to easily run the controller and/or the test there is a srun script - 
+
+srun -h
+
+ --version | -v  => print version information
+ --help | -h  => print this message
+ [-i <local_ip>] [-p <local_port>] [-r <remote_ip>] [-o remote_port>]  [-c|-t <file_name>]
+  => -c for controller and -t for test generation
+  => <file_name> is the name of test or controller class to be run.
+  in its simples usage, you can just start sipper by running it
+  without arguments. The controllers in this case are loaded from
+  the default controller path location.
+  
+The defaults for the controller case are - 
+local_ip    = :LocalSipperIP
+local_port  = 5060
+remote_ip   = :DefaultRIP
+remote_port = :DefaultRP
+
+And the defaults for test are - 
+local_ip    = :LocalSipperIP
+local_port  = :LocalTestPort
+remote_ip   = :DefaultRIP
+remote_port = :DefaultRP
+
+If you are running both controller and the test on the same server then make sure than the run options 
+take this into consideration. 
+
+
+String Recording
+----------------
+- In order to record only through a stringio object, use the start_controller with boolean true
+this will create a single stringio object and pass it through the controller to the session.
+In your controller you need to set the stringio object in your session. 
+So you should do something like "u.record_io = yield  if block_given? " in your start() method. 
+Hopefully this manual step would go away. 
+You would anyway need to have the P-Session_Record header set properly or a system wide configuration. 
+:SessionRecord. 
+
+
+- The recording is automatically read and verified using a helper for that in SipTestCase class. 
+
+
+Automatic validations
+---------------------
+Simple validation methods are provided on session to check the presence/value of header or header 
+parameters. [todo automatically generate the code for such validations]. The presence of a header
+can be checked by adding just one line in the controller. Session#validate_presence_of_headers e.g 
+
+def on_success_res(s)
+  s.validate_presence_of_headers :cseq, :test_header
+end
+
+to test the presence of CSeq and Test-Header in the message (in this case response). If found then
+an expectation element "! true" is added to the recording automatically. So if you are not using 
+the generator tool to create the test case you shall need to add the expectaion element "! true" at
+the right place. e.g 
+"> INVITE, < 200, ! true" etc. in your test. 
+In case the header is not present then the recording will be anything other than "! true". It actually 
+prints what header was not found in the message. 
+
+Similar to validating the headers you can also validate the presence of header parameters using 
+  Session#validate_presence_of_header_params(hdr, *params)
+e.g 
+
+  def on_invite(session)
+    session.validate_presence_of_header_params :test_header, :mytag
+  end
+validates that the header Test-Header exists and also contains a parameter called "mytag". Similar to
+the header validation this also records a "! true" if  the parameter is found.    
+
+Note that if there are many parameters or headers that you are expecting then you should use the 
+repetition option in the expectations like "! true {3,3}". Using "! true, !true, ! true" would be
+an invalid expression and would fail with a message like - 
+  "Expected= ! true between 1 and 1  Actual= ! true"
+This could never happen of course if you are using generators to write your tests. 
+
+You can also validate the header values by using the validation - validate_header_values it takes an argument
+hash with key as the header name and value as the header value.. 
+
+e.g session.validate_header_values :test_header_response=>"foo"
+validates that the header Test-Header-Response has value "foo". The validation needs a "! true" at the 
+appropriate place in the expectation string. 
+ 
+
+For examples on all the validations please refer to test_validations.rb
+
+
+Writing Tests
+-------------
+
+todo BaseTestCase
+todo SipTestCase
+todo DrivenSipTestCase
+
+In either of the type of test cases if you are using setup() then remember that setup() is called before
+every test method. You must always call super() before doing anything in your setup(). 
+e.g 
+  def setup
+    super
+    my_setup_step1
+    my_setup_step2
+    ........
+  end
+Similarly if you are having a teardown() method then you must call super() after you have 
+done your cleanup. 
+
+e.g 
+  def teardown
+    my_cleanup_step1
+    my_cleanup_step2
+    ..........
+  end
+
+
+  setup_once
+  ----------
+Further in sipper we have another type of setup step called setup_once(). You can override this 
+method in your tests too. As the name implies this will invoked just once when the test class is run
+for the first time. You may place one time setup stuff in this method like definition of inline 
+controllers. [See test_controller_using_nict.rb for an example]. As with setup super() needs to be 
+called as a first step in setup_once too. 
+
+
+
+
+Signaling completion of a test
+------------------------------
+
+SIP is a asynchronous protocol and furthermore as the call flow may vary on a case by case basis.
+No one but the client can say for sure when the call flow has actually ended. Instead of sleeping in 
+the test case waiting for all signaling to end there is a better way to signal completion. 
+
+Your controller should be a subclass of SipTestDriverController and your test case should be a subclass of 
+DrivenSipTestCase. 
+The only thing different that you need to do now is to invoke "session.flow_completed_for(test_class_name)" 
+in your controller when your flow actually completes. 
+If you do so then the test can proceed to capture results or do something 
+else without any sleep or wait as the test will be signaled under the covers, however if you do not call 
+"flow_completed_for" then the test will block a default 5 seconds before proceeding (config :WaitSecondsForTestCompletion). 
+If you are writing both UAC and UAS in  the same system then in that case it is likely that the flow completes
+last in a UAS, so it is better to invoke "flow_completed_for" in the UAS. 
+It is possible to run the test and controller(s) on different nodes and still make use of this 
+completion signaling feature. The only thing that you would need to do is to make sure that :TestServerName
+and  :TestServerPort configuration is set properly. The value for this should be same for all the nodes
+in the setup regardless of their role. 
+[todo elaborate on this with examples]
+There is one limitation with using Driven test cases and that is the controller will need to be started from 
+the test case itself. e.g.
+  start_named_controller("SipIct::UacIctTcbhController")
+You may not use the "start_on_load :true" directive with Driven test cases. 
+
+
+The session recording is written out when the session is invalidated, as the session is invalidated based on 
+a timer by default the signaling actually happens after session invalidation. 
+
+
+In case you are not using Driven test cases then you just want to make sure that you wait enough to just get 
+the recording out to the file. To do that you can enable a configuration option :EnableRecordingLock which 
+uses file locking mechanism to ensure that recording files are written and read under proper locks.
+
+Inline Controllers
+-------------------
+Besides defining the controllers in a FS location and providing the controller path at startup time
+you can also define the controller inline in a string and load and execute it from where
+you create sipper instance. For examples see sipper.rb and specialized form in test cases
+in test_inline_controller.rb
+
+It is oftentimes advisable to use the timer granularity value to base your tests on, rather than hard
+coded values of times. If you are using the granularity in the inline tests then you shall have to use
+inline interpreted variables [todo right name?] like #{var} eg. 
+
+  def setup_once
+    super
+    @grty = SIP::Locator[:Sth].granularity
+    str = <<-EOF
+      require 'sip_test_driver_controller'
+      class UacNictController1 < SIP::SipTestDriverController
+          transaction_timers :t1=>#{@grty*2} 
+          ....
+    EOF
+  end
+
+One important consideration while writing Inline controllers is the usage of variables while 
+inlining them in a string. 
+In Ruby while constructing a string you can inline local variable or instance variables e.g. 
+  x = 1
+  puts "The value of x is #{x}"
+prints "The value of x is 1"
+
+or with instance variables as
+
+  @iv = "hello"
+  puts "The instance variable is #@iv"
+prints "The stance variable is hello"
+
+Now while you are writing the inline controller, the entire inline controller definition is itself 
+a string inside the test case. If you are trying to use strings like 
+
+  tid = session.irequest.transaction.object_id  # ask for Demeter's forgiveness
+  logd("Received INFO with transcation #{tid}")
+
+it will not work in inline controller case, while it shall work just fine with the external controller.
+This is a limitation because Ruby tries to evaluate the string in the context of the test case
+and does not find the varaible "tid" in that scope. 
+The way out for inline controllers for such uses is to explicitly concatenate the string like 
+
+  tid = session.irequest.transaction.object_id  # ask for Demeter's forgiveness again!
+  logd("Received INFO with transaction " + tid.to_s)
+  
+  
+  
+Controllers Using State Machine Compiler
+----------------------------------------
+SIP is a stateful protocol and so are your controllers. For any relatively complex controller you 
+will end up writing non-trivial flows. 
+While Sipper makes it a extremely simple to write out a controller in minutes, you still will have to
+somehow maintain state for your business logic. As an example your controller may listen for 200 OK
+responses, so you simple implement the "on_success_res()" method. Now what if you issue different 
+requests and receive 200 for all of them but your behavior is different for say a 200 for INVITE and 
+200 for INFO. Also you could treat the same type of request differently based on CSeq or something 
+else, like your business code. 
+What will happen is that you will save the state of controller in session parameter session["state"] 
+and end up writing a series of if/else or case/when statements. This is fine even preferable for a 
+controller with say 6-7 message exchanges, as it is simple and readable, but for any exchange more than
+10 it becomes unreadable fast. 
+State machine patterns are a well known pattern described in several books and reference material on
+patterns, but perhaps one the best books it is dealt with is Robert Martin's 
+"Agile Software Development, Principles, Patterns, and Practices". 
+There is an open source implementation of the FSM pattern at http://smc.sourceforge.net which we are 
+using extensively in Sipper. 
+In order to use this state machine compiler you will have to be conversant with the state machine
+description language that Uncle Bob invented. It is fairly simple and there is a tutorial at 
+http://smc.sourceforge.net. For the purposes of writing controllers you should be up on your feet in
+a matter of few hours. There is a simple test case "test_smc_controller.rb" in this distro to help you. 
+The steps to use this pattern are - 
+
+1. Create the .sm file of your interactions. The context class will be your controller object. 
+   As controller objects are themselves stateless you should pass Session object to state machine
+   if you want a callback to be invoked in the context of a session. 
+2. Compile the state machine file into Ruby source using the smc compiler. 
+3. Keep the Ruby source in the lib directory of controller which defaults to controller_dir/lib, you
+   could override it by using c.
+4. Next thing is to write controllers and instantiate the state machine object from within the 
+   controller from which you want to use this pattern. You should save the instance as a session
+   attribute. 
+
+Note: When you are using smc and when the state machine calls back into the context call back function it 
+first clears the state, Only getting the control back it proceeds to change/advance the state. 
+So if you try to check the state in call back functions (basically in transit) you will get an exception.
+< elaborate on the example >   
+
+
+Simple Usage
+------------
+request_with and respond_with has been added to simplify the usage. Also you do the same thing for both 
+initial and subsequent requests. 
+Both request_with and respond_with methods return the request or response sent as their return values. 
+
+Logging
+-------
+
+
+Usage of CANCEL and Transactions
+--------------------------------
+
+Sending CANCEL
+--------------
+CANCEL can be sent either by creating one using session#create_cancel and then a subsequent session#send or
+directly using session#create_and_send_cancel_when_ready. The latter shall send CANCEL 
+if a provisional response is received and if not received so far then it shall buffer the CANCEL request
+and send automatically when a provisional response is received. 
+Also if strict protocol compliance is in use then a CANCEL can only be sent only if a provisional response
+is received, trying to send it using session#send shall raise an exception. However if the :ProtocolCompliance
+check is lax then not only can a CANCEL be sent anytime but also if the CANCEL is buffered in anticipation
+of a 1xx response and actually a final response comes instead, the CANCEL is sent if compliance is lax and 
+not otherwise. 
+
+If ICT is in use and a CANCEL is sent then a timer (called Timer Y in Sipper) is started which would fire
+if a 487 is not received for the ICT. The default is 64xT1.  
+In case a 487/INVITE is not received and Timer Y fires then a locally generated 408 response is sent up the
+stack to the controller. Since the 408 is generated locally an ACK by the transaction is not sent as 
+would be the case if a 487 response were received. 
+Of course NICT for CANCEL is a separate but associated transaction and completes independently of the ICT.
+
+
+Receiving CANCEL
+----------------
+As for sending 481/CANCEL when no server transaction was found the setting should be such that both 
+IST and NIST are in use. Sipper looks for the server transaction that is going to be cancelled and as the
+server transaction, though usually INVITE can well be non-INVITE both types of transactions should be in 
+use in configuration. Also the 481/CANCEL is generated by the CANCEL NIST. 
+
+
+
+Request Rejection
+-----------------
+Though controller can generate any responses, rejection of a request with an error (> 399) responses are 
+special in that the request is rejected. todo add behavior abour Session#reject_request_with 
+todo describe Sipper rejection, controller rejection and strict/lax behavior. 
+
+
+Timers
+------
+Timer facility added, for controllers the primary interface is session.schedule_timer_for() and the
+controllers should implement the on_timer(session, task) method. 
+There are 3 types of timers. 
+- app - set by controllers and handled as defined above.
+- session - set at the session level for things like retransmission of 200 OK to INVITE or cleanup
+- transaction - set from a certain transaction. 
+
+Each timer has a target of which the on_timer_expiration method is called, for both :app and :session
+types of timers the target is the concerned session object. Though any infrastructure class that implements a 
+on_timer_expiration(SIP::TimerTask) can be a timer target and can set a timer using SipTimerHelper, but 
+for Sipper so far there are just two types of targets - Session and Transcations. Session is the target for
+both Session level timers and also for app level timers, whereas Transaction is the target for transcation
+timers. (Note there is no constraint of any kind to not having additional timer types, no change is required
+if you create a new timer type :foo and schedule it using the timer manager.)
+
+TimerManager started from Sipper main is the class that controls the timer thread and has only 
+one configuration paramater i.e Timer granularity. The default granularity is 50ms. 
+
+TimerTask is the actual timer task which is passed around on schedule or invocation and can optionally
+carry a closure such that the entity that scheduled the task can access the context. For controllers
+this is just a block passed to the schedule_timer_for() method. 
+The timer id (tid) argument is meant to disambiguate if several timers are set from the same entity. 
+
+[As an example test_inline_controller uses the timer facility]
+
+SipTimerHelper is an infrastructure class that helps in setting of various types of timers and shall 
+have configuration for different timer values. ( todo this shall allow context level setting of 
+timers)
+
+The timers are at first placed in the transport queue so that they do not usurp protocol messages and 
+if the timer task has the session target then they are queued at the session level queue.
+
+A TimerTask with duration equal to zero is a special task which is allowed to fire instantaneously. This is 
+required to meet the RFC reqiutrements where we still go the timer route but with 0 value for consistency for
+reliable transports. Like Timer D in Invite Client Transaction.
+
+Canceling
+---------
+A TimerTask after it is created can be canceled by calling cancel() on it. If a timer is canceled then
+it is not invoked. If a timer is canceled before it is scheduled then it is not scheduled.
+
+
+Transport
+---------
+1. In Request.parse the received= is added to Via if the sent-by and actual IP is different.
+2. In Session.on_response the response is dropped if the top via has sent-by that does not belong to
+   the transport.
+3. todo connection oriented protocols.
+4. todo in Session.send_request we will flip the transport based on size
+5. todo multicast handling of messages
+6. For framing if strict protocol check is on we truncate the message on UDP upto the 
+   content length in Message.parse_content. In case the message is truncated and the Content-Length
+   header is larger than the actual content, Sipper does not automatically send 400 Bad Request
+   instead it returns the actual content length with content_len method and alleged content length 
+   by content_length. The controller can if they want generate a 400 Bad Request. See test_message.rb
+   test case "test_truncated_content". 
+
+
+Transport Filters
+-----------------
+A simple filter mechanism is provided at the lower most transport layer. There can be two types of filters
+Ingress and Outgress filters. These filters can be optionally provided under the controller lib directory 
+under transport_filters subdirectory. 
+The purpose of these optional filters is to work on the raw message as received or being delivered to the 
+socket underneath. The simple use could be to transform the message before sending or just after receiving
+on the wire for -
+
+ 1. Performing compression (SigComp) on the message or change some message attributes. 
+ 2. Logging and auditing-Tracking users using a regex match.
+ 3. Content conversion-Scaling maps, and so on.
+ 4. Localization-Targeting the request and response to a particular locale.
+ 5. XSL/T transformations of XML content-Targeting responses to more that one type of client.
+ 6. Message, Header, Content manipulation.
+ 7. Drop incoming or outgoing packet 
+ 
+etc. 
+
+In order to use the filters you should create a class that is a subclass of Transport::TransportIngressFilter
+if the filter is to transform incoming messages or a subclass of Transport::TransportOutgressFilter if the 
+filter is required for outgoing messages. The class thus created should just have one method "do_filter(str)"
+which takes in a string argument which is the raw message on/from the wire. This method "do_filter" should
+return the string after any transformation that it has applied to the message. 
+In case do_filter returns a nil then the filter chain is broken there and all further message processing 
+stops, i.e an incoming message is not consumed and an outgoing message is not sent. 
+See test2xx_retransmission_with_txns for an example of a transport filter that drops a message. 
+
+You can also have more than one filters of each type, each of these filters are then invoked sequentially 
+in a chain. The order of filter invocation by default is arbitrary, if you want them to be processed in a 
+certain order then you can provide the ordering in a yaml file each for ingress and outgress filters. 
+The yaml files must be named "in_order.yaml" and "out_order.yaml" respectively. The files should contain
+the names of the filter classes in order. e.g 
+ - InFilter1
+ - InFilter2
+ - InFilter3
+
+As an example of filter usage see the example under sipper_test/test_controllers/ctrl_trhandler and the test
+case test_transport_handler.rb. In this example the filter converts the outgoing INFO message to MESSAGE 
+request and when the UAS on getting MESSAGE sends the 200/OK it is converted back to 200/OK for INFO before
+being delivered to the UAC. i.e. 
+
+UAC                                  UAS
+  >--INFO--(conv MESSAGE) -->----------MESSAGE
+  <--200/INFO--(conv INFO)--<-------200/MESSAGE 
+
+For an example of multiple filters and their ordering mechanism also look at 
+sipper_test/test_controllers/multi_trhandlers and the associated test case at test_transport_multi_handler.rb
+
+Controller Level Filter for Testing
+-----------------------------------
+The transport filter chains are at a global level. They apply to all the incoming messages and 
+outgoing messages. Sometimes you may want them at the individual controller level when
+you are writing a test case with inlined controller. In that case the trick is to define 
+the filter not in the transport_filter directory but inline with the controller. 
+Also before defining the filter inline it is important to clear all filters. It is 
+advisable to define such filters in their own namespace i.e wrapped in a module to 
+protect namespace collisions. 
+To see an example of filters with inline controllers see test_non2xx_retransmission_with_ist.
+
+
+
+
+Transactions
+------------
+  todo elaborate on TU and usage of transaction with examples.
+  todo also describe "transcation actions", "transitions", "ctxt callback actions" etc and callbacks. 
+  
+  Transaction Usage - todo describe all. [break the description for controller usage / developer usage]
+  -----------------
+  - Config at the main config level,  - SessionConfigurator[:SessionTxnUsage] (global setting), all controllers all sessions
+  - Settable by controller - todo describe "transaction_usage" directive (see test_base_controller.rb &
+                             test_controller.rb). setting for that controller. All sessions of this controller
+  - Session level  - session.set_transaction_usage (hash_of_options, same as config) or  
+                     session.use_ict=true, session.use_transactions=false etc. 
+  - Request level. - the above session setting can be changed on a request by request basis (just before
+                     sending the request). 
+  
+  Transaction Timers from controller - todo describe in detail.
+  ----------------------------------
+  - Config at the main config level - SipperConfigurator[:TransactionTimers] (todo take info from below)
+  - Settable by controller - todo describe "transaction_timers" directive in detail.
+                             this is the setting for *all* the transactions under *all* sessions for the given
+                             controller.
+                             
+  - Session level  - session.set_transaction_timers(type, tmr_hash) on Session can be used to set timers for a given session 
+                     this will affect all the transactions under the given session of the given type. The type can be any one 
+                     of the transcation types :Ict, :Nict, :Ist, :Nist or it can be :Base where it sets those values for
+                     all the types of transactions. 
+                     
+  - Transaction level - the above session setting can be changed on a request by request basis (just before
+                        sending the request). The setting will affect the transcations after the setting
+                        was changed and any previous txns will remain bound by the timers they were started 
+                        with. The setting will override the configured setting for the timers given in the 
+                        hash, the rest of the timer values will be taken from the configuration or RFC default
+                        for the ones for which no value is configured. As with Session level this setting is 
+                        also available for all transactions or transaction of a particular type. 
+                        
+  - On the transaction object - The transaction is associated with the message that is sent or received, the
+                        transaction object can be obtained from the message msg.transaction and on it 
+                        the timers can be changed again even after the creation of transactions. However the
+                        timers that are already scheduled shall remain unaffected by this change. 
+                        Note however the transaction is created by the TU (Session) just before sending the request
+                        out and so msg.transaction may not be available when say the request is first created. 
+                        
+ 
+  
+  Transaction Callback Handler
+  ----------------------------
+  Optionally you can supply a transcation callback handler at the time the transcation is created. All the 
+  transaction transitions have a before_ and after_ method (around the actions) defined which the 
+  handler can use. 
+  todo define transition for each type of transaction in a table. 
+  So for example if the transcation SM defines a transition "provisional" there will be before_provisional and
+  after_provisional callbacks created. If a transaction callback handler is provided and that handler 
+  implements any of the methods "before_provisional" or "after_provisional" then they will be called before
+  and after the transition takes place. 
+  The transaction is passed as the argument to the handler. The "before" handler can return some values 
+  affecting the behavior of the state machine. 
+  In the before transition, if the return value "SIP::Transaction::SM_PROCEED_NO_ACTION" then all the 
+  methods starting with "__" (action methods) are masked (no action performed) when the state machine 
+  is actually invoked. 
+  todo define transaction action methods. 
+  The idea is that callback handler will return this only if it 
+  is willing to perform the action itself but still wants the state machine to proceed. 
+  It could return "SIP::Transaction::SM_PROCEED" (default) where the transaction callback is basially a 
+  notification and does not affect the behavior of transaction or associated action methods. 
+  Or it could return "SIP::Transaction::SM_DO_NOT_PROCEED", 
+  in which case the SM ignores this transition altogether. 
+  The "after" transition is just for informational purposes as far as that transition is concerned and any 
+  return value does not have any effect on transition. However the handler can still invoke any method
+  on the transcation or the associated message of the transaction. As an example the handler
+  can change the consumption status of message such that it shall or shall not be delivered to the 
+  controller. See test_invite_client_transaction.rb and test_non_invite_client_transaction.rb for callback
+  examples. 
+  Further the transaction callback handler can also define additional callback methods for transactions like
+  transport_err(txn), timeout(txn), cleanup(txn) and wrong_state(txn). 
+  if they are interested in these events. These events are all "after" in nature and no return value affect the 
+  transaction behavior. wrong_state() callback indicates that the state change that was attempted is not allowed
+  by the state machine. No state change or messaging associated with the transition happens. 
+  
+  todo make a table for each transaction with before and after transitions.
+ 
+  The transaction callback handler can be provided from the controller. From the controller you specify the 
+  name of the class for each type of transaction callback handler. like - 
+  
+    transaction_handlers :Ict=>MyIctHandler, :Nict=>MyNictHandler, :Base=>CatchAllHandler
+    
+  Above is a controller directive where you can specify the class name which will handle the transitions for 
+  each type of transactions. For each transaction a new instance of this class will be created. The :Base 
+  handler can be used for any transaction which does not have a specific handler defined. 
+  If a specific handler class is defined then that is used instead of the Base. The callback handler is invoked
+  only when it implements the callback methods ("before", "after" or any of the 4 event callbacks i.e transport_err,
+  timeout, cleanup and wrong_state) 
+  The transaction handler files must be located in the controller/lib directory.  
+  
+  Two important things to note-
+  1. If you are returning SM_PROCEED_NO_ACTION then you should do all what the state machine was 
+     supposed to do to have the right behavior (unless you do not want it), including setting the 
+     consume flag on the transcation. See "test_controller_using_ict_with_tcbh_no_action"
+     The default consume status is false unless set explicitly by the transaction or in this case
+     by the handler.
+  2. In order for you to control the transaction using the callback handler you MUST set the 
+     SipperConfigurator[:ProtocolCompliance] to lax. This is so because you are taking matters in your
+     hands and will be doing things that the RFC requires the transaction state machine to do.
+     
+ 
+ Alternatively the transaction handler can be directly set on the session using - 
+ 
+  set_transaction_handlers(txn_handler_hash)
+  e.g. session.set_transaction_handlers(:Ict=>MyIctHandler, :Base=>CatchAllHandler) 
+  
+  Here the class MyIctHandler should be on the Ruby load path, so either it can be part of the controller
+  lib or it can be placed in the top level lib at sipper/lib.
+  
+  Transaction handler is a very powerful feature and can be used to do interesting stuff. 
+  As an example in the test case test_invite_retransmission the transaction handler is used
+  to supress the generation of a 100 Trying response from the transaction, however the transaction
+  is allowed to proceed in state. 
+  
+   class IstTxnHandler
+      def before_invite(txn)
+        def before_invite(txn)
+          SIP::Transaction::SM_PROCEED  
+        end
+        txn.__consume_msg(true)
+        SIP::Transaction::SM_PROCEED_NO_ACTION
+      end  
+    end
+  
+ As you can see in this example we are actually re-defining the before_invite() method which is a
+ trick that can be used to make the handler change its behavior after say a first invocation as
+ in this case. 
+ Here we do not want 100 Trying to go for the first INVITE (forcing retransmissions) but then we
+ do want the transaction to proceed and also behave as usual (namely filter retransmissions) for 
+ retransmissions. 
+ Also in the same example you can see that the transaction handler is defined inline with the 
+ controllers.
+ For another interesting use of transaction handler see test_cancel_ith_ist_without_nist.  
+ 
+ Warning about the return value : See the code below
+ 
+      def before_success_final(txn)
+        txn.__consume_msg(true)
+        SIP::Transaction::SM_DO_NOT_PROCEED
+        def before_success_final(txn)
+          SIP::Transaction::SM_PROCEED
+        end
+      end
+      
+ this is a snippet from ICT transaction handler. This handler basically bypasses the transaction 
+ on getting the first 2xx response but re-defines the method to normaly handle any 2xx 
+ retransmission. However there is a small problem with the code which is not apparent on the 
+ first glance. The return value SIP::Transaction::SM_DO_NOT_PROCEED is not the last statement
+ in the first execution of the callback. The simple fix is to move the return to the end of the
+ method. 
+ 
+       def before_success_final(txn)
+        txn.__consume_msg(true)
+        def before_success_final(txn)
+          SIP::Transaction::SM_PROCEED
+        end
+        SIP::Transaction::SM_DO_NOT_PROCEED  # Moved to end to return this value. 
+      end
+      
+ 
+ 
+  Separation of transcation and TU
+  --------------------------------
+  Even though the callbacks on transaction states look similar to upcall to controller they are quite
+  different things. It is for this reason  there is no API provided to say initiate requests or create
+  responses from the transaction callback handlers. As these are low level actions  the transaction
+  state may not be amenable to carry out a high level action like messgaing at this time. 
+  The handler however, can access the transaction and the associated message and can invoke some 
+  methods on them, like changing the consumption status [e.g change the status such that a 2xx 
+  retransmission is sent to TU even in completed state of the NICT] or add or remove a header from
+  the request/response. 
+  
+  
+  Transaction User
+  ---------------
+  TU creates transaction and starts invoking "Invocation Action" methods. todo describe them 
+  Also for responses received, checks whether to consume them or not based on consume?  method return value.
+  There is only one call back into TU from ICT and that is notification on  transport error. 
+  There are 4 TU callbacks that TU should implement. 
+    (a) transaction_transport_err() gets called should CTs get a transport failure 
+    (b) transaction_timeout() gets called on timeout of a transaction
+    (c) transaction_cleanup() gets called on transaction termination
+    (d) transaction_wrong_state() gets called when a message is either received or being sent that is not 
+        valid for this state. The state transition and any messaging associated with such action does not 
+        happen.
+    (e) transaction_record() record the message from the transaction. Only outgoing messages ever get 
+        recorded from this method because the incoming messages always come through the session, which is
+        where they are recorded. For messages like 4xx/ACK or request retransmissions the session is not
+        involved and would not be able to record them, so transactions record them.
+  Besides this Session (which is also TU) is used to create responses or requests like ACKs that transaction
+  sends. 
+  For the purposes of Sipper, Session is the TU and creates and maintains the transactions. The controller 
+  can optionally provide a transaction handler. 
+  
+  Transaction Timeout
+  -------------------
+  According to RFC 3261 8.1.3.1 "Transaction Layer Errors" in case of an Invite Client Transaction 
+  timeout a 408 response is locally generated and sent up to TU or a Transaction handler if a 
+  handler is present. This response will be like any other except that it will return true for 
+  locally_generated?() method defined on the response. As this repsonse is not delivered to the 
+  transaction no ACK is generated for this. (It is a response generated by the transaction itself).
+  The controllers MUST NOT try to generate any ACK for the locally generated responses. 
+  
+  The 408 response is locally generated on transaction timeout even in case of NICT. The locally 
+  generated response can be tested to be local by invoking response.locally_generated?(). 
+  If the response is locally generated then the B2BUA or Proxy MUST not forward the response 
+  according to the provisions of RFC 4320 - 
+  
+  "4.2. Action 2
+   A transaction-stateful SIP element MUST NOT send a response with
+   Status-Code of 408 to a non-INVITE request. As a consequence, an
+   element that cannot respond before the transaction expires will not
+   send a final response at all."
+  
+  todo : For Proxy or B2bua implementations have a strict/lax behavior to forward or not the 
+  408 response. 
+  
+  Invite Client Transaction
+  -------------------------
+  Timers: The transcation base timers like T1, T2 and also derived timers TimerA, B etc. have 3 levels of
+  configuration. 
+  1. The bare default is what is recommended in RFC and will be taken if no configuration
+     override is provided. 
+  2. These defaults can be overridden by a system wide setting for any and all of these timer values
+     by setting the configuration in SipperConfigurator[:TransactionTimers] hash. eg. 
+     SipperConfigurator[:TransactionTimers] = { :t1=>200 }. Usually derived timers like Timer A, B .. etc
+     are dependent of T1, T2 etc. This can be overridden in the configuration but be aware that these 
+     timers are made dependent for a reason and if you override them you should carefully consider the 
+     behavior. e.g config SipperConfigurator[:TransactionTimers] = { :t1=>200, :ta=>150, :tb=10500 }
+  3. Finally this configuration can be overriden on a transaction by transaction basis when the Txn of 
+     any kind is constructed by optionally passing it a block of these timer values with a self qualifier.
+     e.g  ict = Ict.new(transport, tp_flags, rip, rp) { self.t1 = 200; self.ta=100 }. Note the ";" separating
+     the timers as this is a block not a hash.   
+  4. For reliable transports the TimerA does not start and TimerD starts for instantaneous firing. In case 
+     (say for testing) it is required to run these timers for any transport then all that is required is to 
+     make the transport behave as unreliable for which you just need to extend the transport object with 
+     the SIP::Transport::ReliableTransport module after making a dup object. 
+     See "test_no_timerA_reliable" test case in test_invite_client_transaction.rb.
+     
+  Strict/Lax behavior of ICT
+  --------------------------
+  If 'strict' protocol compliance check is in place and TU is using ICT then you will not be able to send ACK/non-2xx
+  yourself from the controller (you will obviously be able to send ACK/2xx), instead the ACK 
+  to non-2xx response will be automatically sent from 
+  the ICT. If the compliance check is 'lax' then you can send (if you want for some reason) 
+  the ACK/non-2xx from controller but 
+  note that the ICT will also send its ACK when the response reaches it. If you do not want "two"
+  ACKs then you should implement an transaction callback handler and on "before_non_success_final()" 
+  callback return the SIP::Transaction::SM_PROCEED_NO_ACTION to stop ICT from performing any action 
+  while still advancing in state. See the test case - TestControllerUsingIctWithTcbhNoAction. 
+     
+     
+  UAS 2xx retransmission behavior
+  -------------------------------     
+  Independent of transactions the 2xx response from the UAS is to be retransmitted, regardless of the 
+  transport. [section 13.3.1.4 of 3261]. There are 3 levels of configuration that affect this 
+  behavior. 
+  1. The default is to retransmit the 2xx response until the ACK is received or a timeout governed by
+     times T1, T2 and 64*T1. 
+  2. The usage itself and the timers can be overridden in the configuration using the config options
+     SipperConfigurator[:T2xxUsage] and SipperConfigurator[:T2xxTimers]. This setting applies to 
+     every session created.
+  3. The abose setting can be overridden by controller directives "t2xx_usage <boolean>" and
+     "t2xx_timers <hash>", the hash argument to the directive can contain upto 3 timer values with 
+     names :Start, :Cap and :Limit that correspond to T1, T2 and 64*T1 timers as described in the RFC.
+     as an example the directive could be -
+       t2xx_timers :Start=>100
+     which would set the starting time (equivalent to T1) to 100 msec while others would still be 
+     coming from configuration. 
+       t2xx_timers :Start=>100, :Cap=>400, :Limit=>16000
+     Sets the 2xx retransmission timer to start at 100 msec, doubles until it reaches :Cap and the 
+     retransmissions continue until :Limit or until ACK is received.
+     These settings apply to all the sessions created by the controller that uses these directives. 
+  4. These settings can also be set on the Session object itself by using the methods
+     session.set_t2xx_retrans_usage(boolean) and session.set_t2xx_retrans_timers(hash) which can be 
+     changed on a session by session basis. 
+  
+  See test2xx_retransmission.rb for example code. 
+ 
+
+
+Writing a B2BUA
+---------------
+[todo describe B2BUA entity]. A base B2buaController class is provided to easily create back to back user agents. 
+A B2BUA controller of yours should be a subclass of SIP::B2buaController e.g 
+  
+  require 'b2bua_controller'
+  class MyB2buaController < SIP::B2buaController 
+  end
+ 
+A B2BUA gets a request acting as a UAS and sends it out acting as a UAC with appliction specific 
+transformations. The first thing that a B2BUA might like to do is to create the UAC session. 
+The base SIP::B2buaController has methods -
+  create_peer_session(session, rip=SipperConfigurator[:DefaultRIP], 
+          rp=SipperConfigurator[:DefaultRP] )
+  to create a new peer session.
+  
+  get_peer_session(session)
+  to return an existing peer session, nil otherwise and 
+   
+  get_or_create_peer_session(session, rip=SipperConfigurator[:DefaultRIP], 
+          rp=SipperConfigurator[:DefaultRP] )  
+
+that creates or returns a peer session for the given remote IP and remote port if associated with the session
+argument, if not specified the default remote IP and port are taken from the configuration 
+- SipperConfigurator[:DefaultRIP] and SipperConfigurator[:DefaultRP]. 
+The peer session once created is associated with the session passed in argument and vice versa. 
+This allows for a subsequent call to get_peer_session to get the peer session from either of the
+sessions. 
+create_b2bua_request and create_b2bua_response are methods provided to create the request or response for
+the peer leg. This is just for convenience, you can of course create a new request or response, populate 
+the headers appropriately and send it on the peer session. 
+
+As a further convenience relay_request and relay_response methods are provided which simply relay the 
+request or response on the peer leg without any controller involvement, they do however use the session
+specific information like From/To tags, Call-Id, CSeq etc. 
+At any point the B2BUA can optionally call go_transparent method which does not even require a B2BUA 
+controller to implement any of the on_xxx methods. If a peer session is defined then the request and 
+response is relayed without any controller involvement. 
+
+Rather than invalidating peer session manually one by one, a convenience method is provided 
+called invalidate_sessions which invalidates both the B2BUA sessions from one invocation. 
+
+It is important to note that if the B2BUA is made to go transparent then it will not be invoked for 
+incoming requests or responses and therefore will not have an oppprtunity to invalidate sessions. 
+In such a case the session_limit directive which sets the overall session lifetime is used  to clean up
+the session resources. 
+
+The linked B2BUA sessions are a two way association. One session can be linked to only one other peer 
+session. Specifically a session can only link one and only one peer, but one session may have linkages 
+in more than one sessions. 
+Explicit linking and unlinking is possible using link_sessions and unlink_sessions. So if you want to
+create a new session from a b2bua session which already has a linked session you shall have to unlink 
+the sessions first and then use get_or_create_peer_session to create a new session and its linkage. 
+ 
+To see a very simple B2BUA example see the test_b2bua1.rb. Note that in all the b2bua tests, all the UAC, 
+B2BUA and UAS are defined in the same test code file, correct routing is made possible by using a
+custom header and implementation of the interested? method. 
+
+test_b2bua2.rb is an example of a transparent b2bua using the session_limit directive to invalidate
+sessions. [Explain with diagrams]
+Finally for a complex b2bua example have a loook at test_b2bua3.rb. [Explain with diagrams]
+ Strict/Lax behavior
+ -------------------
+ todo describe in detail what is the strict and lax behavior, also lax is when you are allowed to do
+ something which are usually a SHOULD NOT. (todo validate this). You can otherwise override a lot of 
+ behavior by transaction machine hooks and other such plugin behavior. 
+ 
+ 
+     
+ Testing
+ -------
+ - If in your tests you need to run Sipper then extend the built in class SipTestCase but remember to 
+   call super as the first thing in your "setup" method if you have one. 
+ - todo indicate difference between BaseTestCase and SipTestCase.
+ 
+ Troubleshooting
+ ---------------
+1. If you are seeing errors like - 
+
+[ERROR]:[1187887677.97]:[WorkerThread-4]:siplog::udpsession :: Exception can't p
+arse uri:druby://: occured while response processing by controller
+[ERROR]:[1187887677.97]:[WorkerThread-4]:siplog::udpsession :: d:/ruby/lib/ruby/
+1.8/drb/drb.rb:815:in `parse_uri'
+
+Then most likely your test is not derived from DrivenSipTestCase and you are still trying to signal the test using 
+session.flow_completed_for("MyTest") where MyTest is your test class name. This signaling facility is available only to driven test cases. Note however this might just add some delay in processing the outcome of test case is unaffected by this error.
+
+---------
+ 
+Done
+ 1. Add the continue recording stuff
+ 2. DA
+ 3. Registeration
+ 4. Media (sdp available from Message)
+ 5. Whole set_attribute story being called repeatedly, explain offer answer model etc
+ 6. Running tests in order, define "order_tests.yaml" and define test file names, make sure 
+    that the name of Test class inside of .rb file is derivable from the file name. 
+ 7. on_success_res_for_invite etc document it.
+ 8. 
+    
+New
+  1.    
+  2. Goblet release overlay
+  3. Config "GET xyz", "SET xyz pqr", "SET xyz pqr data_type"
+  irb(main):082:0> t = TCPSocket.new('127.0.0.1', 4681)
+=> #<TCPSocket:0x33ae4ec>
+irb(main):083:0> t.puts "SET WaitSecondsForTestCompletion 10"
+=> nil
+irb(main):084:0> t.gets
+=> "10\n"
+irb(main):085:0> t.puts "SET LocalSipperIP 192.168.1.2"
+=> nil
+irb(main):086:0> t.gets
+=> "192.168.1.2\n"
+irb(main):087:0>
+irb(main):088:0* t.puts "SET Abracadabra hello string"
+=> nil
+irb(main):089:0> t.puts "GET Abracadabra"
+=> nil
+irb(main):090:0> t.gets
+=> "hello\n"
+
+Also io.puts "KEY_NAMES"
+io.puts "KEY_DESCRIPTIONS"
+
+4. 
+