include/anna/diameter.comm/Session.hpp

   1 // ANNA - Anna is Not Nothingness Anymore                                                         //
   2 //                                                                                                //
   3 // (c) Copyright 2005-2015 Eduardo Ramos Testillano & Francisco Ruiz Rayo                         //
   4 //                                                                                                //
   5 // See project site at http://redmine.teslayout.com/projects/anna-suite                           //
   6 // See accompanying file LICENSE or copy at http://www.teslayout.com/projects/public/anna.LICENSE //
   7
   8
   9 #ifndef anna_diameter_comm_Session_hpp
  10 #define anna_diameter_comm_Session_hpp
  11
  12
  13 // STL
  14 #include <string>
  15
  16 #include <anna/core/util/SortedVector.hpp>
  17 #include <anna/core/util/Millisecond.hpp>
  18 #include <anna/core/RuntimeException.hpp>
  19 #include <anna/timex/Timer.hpp>
  20
  21 #include <anna/diameter/defines.hpp>
  22 #include <anna/diameter.comm/ClassCode.hpp>
  23 #include <anna/diameter.comm/Message.hpp>
  24 #include <anna/diameter.comm/Timer.hpp>
  25
  26
  27 namespace anna {
  28 class DataBlock;
  29 namespace timex {
  30 class Engine;
  31 }
  32 }
  33
  34
  35 namespace anna {
  36
  37 namespace diameter {
  38
  39 namespace stack {
  40 class Engine;
  41 }
  42
  43 namespace comm {
  44
  45 class Timer;
  46 class Engine;
  47 class Response;
  48
  49
  50
  51 /**
  52    Modela la conexion realizada contra un servidor diameter.
  53 */
  54 class Session : public anna::timex::Timer {
  55
  56 public:
  57
  58   Session(const char *className, const char *timerName);
  59   //virtual ~Session();
  60
  61   /**
  62    * Default timeout for application message requests over the session.
  63    */
  64   static const anna::Millisecond DefaultTimeout;
  65
  66   /**
  67    * Default diameter port
  68    */
  69   static const int DefaultPort;
  70
  71
  72
  73
  74   /**
  75      Session states
  76      \see diameter::comm::Session::getState
  77   */
  78   struct State {
  79     enum _v {
  80       /* client + server */ Closed, /**< Closed */
  81       /* client          */ WaitingBind, /**< Connection confirmation pending*/
  82       /* client + server */ Bound, /**< Connection done included level application */
  83       /* client          */ Failover, /**< Last DWR timed out */
  84       /*          server */ Suspect, /**< Inactivity detected on session */
  85
  86 // .......
  87
  88
  89       // Cierre de iniciativa local:
  90       // 1. Envio DPR al PCRF y me pongo en estado 'WaitingDPA'. En este estado no habr� keep-alive DWR/DWA.
  91       // 2. No dejo pasar nuevas peticiones (BLOCK-SEND).
  92       // 3. Cierro al recibir el DPA.
  93       // 4. Si expira el DPA, tambien cierro.
  94       WaitingDPA, /**< After requesting DPR to server, send is blocked over the session: when DPA arrives (or answer expires) the session is closed */
  95
  96       // Cierre de iniciativa remota:
  97       // 1. Recibo DPR del PCRF y me pongo en estado 'Disconnecting'. En este estado no habr� keep-alive DWR/DWA.
  98       // 2. No dejo pasar nuevas peticiones (BLOCK-SEND).
  99       // 3. Espero cursar las peticiones pendientes (a m�s tardar, ser� una expiracion Tx desde la recepcion del DPR).
 100       // 4. Envio DPA y activo un temporizador de cierre local (2*Tx) como proteccion (por si el servidor no cierra).
 101       Disconnecting, /**< After receiving DPR from server, send is blocked over the session: when no pending requests, DPA is sent to the server who will close connection */
 102
 103       // Cierre abrupto con/sin espera de pendings:
 104       Closing /** Planned local disconnection without DPR; send is blocked over the session. Immediate unbind is used when IgnorePendings behaviour is configured */
 105     };
 106   };
 107
 108   /**
 109      Session state.
 110      \return State for this session.
 111   */
 112   State::_v getState() const { return a_state; }
 113
 114   /**
 115    * Defines behaviour on 'Disconnecting' state, about #unbind action (ignore/wait pending answers)
 116    */
 117   struct OnDisconnect { enum _v { IgnorePendings, WaitPendings /* graceful unbind */ }; };
 118
 119   /**
 120    * Sets behaviour on 'Disconnecting' state, about #unbind action (ignore/wait pending answers).
 121    * \param onDisconnect Behaviour on 'Disconnecting' state, about #unbind action (ignore/wait pending answers).
 122    */
 123   void setOnDisconnect(const OnDisconnect::_v onDisconnect)  { a_onDisconnect = onDisconnect; }
 124
 125   /**
 126    * Returns behaviour on 'Disconnecting' state, about #unbind action (ignore/wait pending answers).
 127    * \return behaviour on 'Disconnecting' state, about #unbind action (ignore/wait pending answers).
 128    */
 129   OnDisconnect::_v getOnDisconnect() const { return a_onDisconnect; }
 130
 131
 132
 133   /**
 134      Diameter server address, ip or hostname (remote for client-session, local for server-session).
 135      \return Diameter server address (remote for client-session, local for server-session).
 136   */
 137   virtual const std::string& getAddress() const  = 0;
 138
 139   /**
 140      Diameter server listen port (remote for client-session, local for server-session).
 141      \return Diameter server listen port (remote for client-session, local for server-session).
 142   */
 143   virtual int getPort() const  = 0;
 144
 145   /**
 146      Socket id.
 147      \return Socket id.
 148   */
 149   int getSocketId() const { return a_socketId; }
 150
 151   /**
 152      Returns the next hop-by-hop which will be used over the diameter session to send a message
 153      It is recommended to fix the message with this value (or store along with the message),
 154      for application context identification purposes
 155   */
 156   const HopByHop & getNextHopByHop() const { return a_nextHopByHop; }
 157
 158   /** Returns the next end-to-end which will be used over the diameter session to send a message
 159       It is recommended to fix the message with this value (or store along with the message),
 160       for application context identification purposes
 161   */
 162   const EndToEnd & getNextEndToEnd() const { return a_nextEndToEnd; }
 163
 164
 165   /**
 166      Set timeout to consider failed a request.
 167      \param v Requests class code.
 168      \param millisecond Milliseconds wait before considering the requests failed.
 169
 170      Timers are internally managed and automatically activated.
 171   */
 172   void setClassCodeTimeout(const ClassCode::_v v, const anna::Millisecond & millisecond) { a_timeouts [v] = millisecond;  }
 173
 174   /**
 175    * Timeout configured for class code \em v requests.
 176    * \return Timeout configured for class code \em v requests.
 177    */
 178   anna::Millisecond getClassCodeTimeout(const ClassCode::_v v) const { return a_timeouts [v]; }
 179
 180
 181   /**
 182      Returns \em true when diameter server is connected (application level) \em false in other case.
 183      \return \em true when diameter server is connected (application level) \em false in other case.
 184   */
 185   bool isBound() const { return a_state == State::Bound; }
 186
 187
 188 // Envia el mensaje recibido como parametro al servidor con el que estamos conectados mediante esta
 189 // sesion diameter. Dicho mensaje puede ser una peticion o una respuesta (no temporizada).
 190 //
 191 // En caso de enviar una peticion se activara automaticamente un temporizador. Si este llegara a caducar
 192 // se cancelara la busqueda y se invocara al metodo Session::eventResponse indicado que se ha producido
 193 // un error de temporizaci�n. La duracion del temporizador sera la establecida por
 194 // diameter::comm::TimerManager::setTimeout o el valor defecto.
 195 //
 196 // \param message Mensaje a enviar al servidor diameter con el que estamos conectados.
 197 // @return Diameter response reference asociated to a request. NULL if answer sent.
 198 // \warning Solo se podra hacer uso de este metodo cuando el metodo #isBound devuelva \em true.
 199   virtual const Response* send(const Message* message) noexcept(false) = 0;
 200   const Response* send(const Message& message) noexcept(false) { return send(&message); }
 201
 202 // Desconecta del extremo remoto
 203 // Se notifica la terminaci�n de cada una de las peticiones pendientes invocando al m�todo Session::eventResponse
 204 // \warning Despu�s de invocar a este m�todo habr�a que volver a iniciar una sesion.
 205   virtual bool unbind(bool forceDisconnect /* se usa en timer, para el actionTimer del tipo SessionUnbind, etc. */ = false) noexcept(false) = 0;
 206   // returns true if done at call time (no pendings or ignore pendings, except Disconnecting state by mean DPR/DPA)
 207
 208
 209   /**
 210      Gets the timestamp for last incoming activity over the session.
 211
 212      @return Last incoming activity timestamp.
 213   */
 214   const anna::Millisecond & getLastIncomingActivityTime() const { return a_lastIncomingActivityTime; }
 215
 216   /**
 217      Gets the timestamp for last outgoing activity over the session.
 218
 219      @return Last outgoing activity timestamp.
 220   */
 221   const anna::Millisecond & getLastOutgoingActivityTime() const { return a_lastOutgoingActivityTime; }
 222
 223   /**
 224      Gets the number of requests messages over-the-air.
 225
 226      @return OTA messages.
 227   */
 228   int getOTARequests() const { return a_responses.size(); }
 229
 230
 231   /**
 232      Returns idle state (no pending answers).
 233
 234      @return Idle state.
 235   */
 236   bool idle() const { return (getOTARequests() == 0); }
 237
 238
 239   /**
 240      In order to avoid message burst during failover procedures (alternate server forwardings done by application),
 241      orphan request notification could be deferred to expiration event. This is the default behaviour, however if
 242      need to notice quickly the transport failure for such requets, 'false' should be established. Result code of
 243      'OrphanTimeout' will be configured at response instance.
 244
 245      This only applies to client-sessions because is not usual to send request from server sessions and there wont
 246      be impact notifying orphan requests at the moment of the transport failure.
 247
 248      @defer Delayed notification for orphan request due to transport failures
 249   */
 250   void notifyOrphansOnExpiration(bool defer = true) { a_notifyOrphansOnExpiration = defer; }
 251
 252   /**
 253      Class string representation
 254      \return String with relevant information for this instance.
 255   */
 256   virtual std::string asString() const ;
 257
 258
 259   /**
 260      Class xml representation
 261      \param parent Parent XML node on which hold this instance information.
 262      \return XML document with relevant information for this instance.
 263   */
 264   virtual anna::xml::Node* asXML(anna::xml::Node* parent) const ;
 265
 266 protected:
 267
 268   // Auxiliary messages:
 269   Message a_dpr;
 270
 271   // Internal, traces, etc.
 272   const char *a_className;
 273
 274   // Main session attributes
 275   int a_socketId; // multiple connection functionality
 276   State::_v a_state;
 277   OnDisconnect::_v a_onDisconnect;
 278   Engine *a_engine;
 279   anna::diameter::comm::Timer *a_actionTimer;
 280
 281   // Sequencing
 282   HopByHop a_nextHopByHop;
 283   EndToEnd a_nextEndToEnd;
 284   virtual void initialize() ;
 285   void initializeSequences() ; // debe invocarse despues de haber asignado el a_parent
 286   void generateNextSequences() { a_nextHopByHop++; a_nextEndToEnd++; }
 287
 288   // Context Responses
 289   struct SortById {
 290     static HopByHop value(const Response*) ;
 291   };
 292   typedef anna::SortedVector <Response, SortById, HopByHop> response_container;
 293   typedef response_container::iterator response_iterator;
 294   typedef response_container::const_iterator const_response_iterator;
 295   response_container a_responses;
 296   bool a_notifyOrphansOnExpiration;
 297
 298   void response_add(Response* response) ;
 299   void response_erase(Response* response) ;
 300   Response* response_find(const HopByHop hopByHop) noexcept(false);
 301
 302   response_iterator response_begin() { return a_responses.begin(); }
 303   response_iterator response_end() { return a_responses.end(); }
 304   static Response* response(response_iterator ii) { return response_container::data(ii); }
 305
 306   const_response_iterator response_begin() const { return a_responses.begin(); }
 307   const_response_iterator response_end() const { return a_responses.end(); }
 308   static const Response* response(const_response_iterator ii) { return response_container::data(ii); }
 309
 310   // Activity
 311   anna::timex::Engine* a_timeController;
 312   anna::Millisecond a_lastIncomingActivityTime;   // last unix timestamp (in milliseconds) when message reception was managed over the session
 313   anna::Millisecond a_lastOutgoingActivityTime;   // last unix timestamp (in milliseconds) when message sending was managed over the session
 314   virtual void updateIncomingActivityTime() ;
 315   virtual void updateOutgoingActivityTime() ;
 316
 317   // Self-timer expiration handler
 318   virtual void expire(anna::timex::Engine *timeController) noexcept(false) {;}
 319
 320   // Timming:
 321   anna::Millisecond a_timeouts [ClassCode::Max];
 322
 323   // Handlers:
 324   /**
 325      Handler about event break connection over the session.
 326
 327      When notified, ANNA.diameter.comm generates an diameter::comm::ClientSession::eventResponse for every request with pending answers.
 328   */
 329   virtual void eventPeerShutdown()  = 0;
 330
 331   /**
 332      Handler about a request retransmission over the session.
 333
 334      \param request Message retransmitted
 335   */
 336   virtual void eventRequestRetransmission(Message *request)  = 0;
 337
 338   /**
 339      Handler for diameter session responses
 340
 341      \param response Answer data block object for corresponding diameter request
 342   */
 343   virtual void eventResponse(const Response& response) noexcept(false) = 0;
 344
 345   /**
 346      Handler for diameter session requests
 347
 348      \param request Request container object for corresponding diameter reception
 349   */
 350   virtual void eventRequest(const anna::DataBlock& request) noexcept(false) = 0;
 351   //void eventRequest(const Message& request) noexcept(false);
 352
 353
 354   /**
 355      Handler for diameter session responses out of context
 356
 357      \param response Answer data block object without context match
 358   */
 359   virtual void eventUnknownResponse(const anna::DataBlock& response) noexcept(false) = 0;
 360
 361   /**
 362      Handler for diameter session Disconnect-Peer-Answer messages
 363
 364      \param response Answer data block object without context match
 365   */
 366   virtual void eventDPA(const anna::DataBlock& response) noexcept(false) = 0;
 367
 368
 369
 370   /**
 371   * Handlers
 372   */
 373   virtual void receive(const anna::comm::Message& message) noexcept(false) = 0;
 374 //PROTOCOL ERRORS
 375 //The errors at the protocol level are reported in response messages that contain the �E� bit and the error code in the AVP result-Code (various errors having been produced only the first one of them is reported). Examples of these errors are:
 376 //An unrecognized AVP with the �M� bit is received.
 377 //An AVP is received with an unrecognized value (in the AVP failed-AVP indicates the attribute that the error caused).
 378 //An mandatory AVP is not received.
 379 //Length of operation incorrect.
 380 //Length of AVP incorrect.
 381 //Coding of some AVP incorrect.
 382 //Erroneous inclusion of parameters.
 383
 384
 385
 386
 387
 388   virtual void finalize() ; // invoked from ClientSessionReceiver::eventBreakConnection()
 389
 390
 391   virtual void expireResponse(Response*) ;
 392   void sendDPA() noexcept(false);
 393   void activateActionTimer(const anna::diameter::comm::Timer::Type::_v type) ;
 394   void cancelActionTimer() ;
 395   void activateTimer() ; // Session timer
 396   void cancelTimer() ; // Session timer
 397   virtual void timerStopped() {;}
 398   virtual void timerStarted() {;}
 399
 400
 401   virtual void setState(State::_v state) ;
 402
 403   //anna::diameter::comm::Timer *getActionTimer() const { return (a_actionTimer); }
 404
 405
 406   // helpers
 407   static const char* asText(const State::_v) ;
 408   static const char* asText(const OnDisconnect::_v) ;
 409
 410
 411   friend class anna::diameter::comm::Timer;
 412   friend class Engine;
 413   friend class Response;
 414 };
 415
 416 }
 417 }
 418 }
 419
 420 #endif
 421