[#897] Updated doc

doc/sphinx/arm/hooks-lease-cmds.rst

@@ -501,6 +501,21 @@ An example result returned when the host was found:
      "text": "IPv4 lease found."
    }
 
+.. note::
+
+   The client last transaction time (``cltt`` field) is bound to the
+   valid lifetime (``valid-lft``) and to the expire date (not reported
+   here but stored in databases) by the equation
+   :math:`cltt + valid_lft = expire`
+
+   at the exception of the infinite valid lifetime coded by the
+   0xfffffff (4294967295) special value which makes the expire value
+   to overflow on MySQL and old PostgreSQL backends where timestamps
+   are 32 bit long. So in these lease databases the expire date is the
+   same as the cltt i.e.
+   :math:`cltt = expire` when :math:`valid_lft = 0xffffffff` and the
+   lease backend is MySQL or PostgreSQL.
+
 .. _command-lease4-get-all:
 
 .. _command-lease6-get-all:

src/lib/dhcpsrv/mysql_lease_mgr.cc

@@ -559,7 +559,8 @@ public:
             // expiry time (expire).  The relationship is given by:
             //
             // expire = cltt_ + valid_lft_
-            // Avoid overflow
+            // Avoid overflow with infinite valid lifetime by using
+            // expire = cltt_ when valid_lft_ = 0xffffffff
             uint32_t valid_lft = lease_->valid_lft_;
             if (valid_lft == Lease::INFINITY_LFT) {
                 valid_lft = 0;
@@ -766,7 +767,8 @@ public:
     ///         data.
     Lease4Ptr getLeaseData() {
         // Convert times received from the database to times for the lease
-        // structure
+        // structure. See the expire code of createBindForSend for
+        // the infinite valid lifetime special case.
         time_t cltt = 0;
         // Recover from overflow
         uint32_t valid_lft = valid_lifetime_;
@@ -1003,7 +1005,8 @@ public:
             // expiry time (expire).  The relationship is given by:
             //
             // expire = cltt_ + valid_lft_
-            // Avoid overflow
+            // Avoid overflow with infinite valid lifetime by using
+            // expire = cltt_ when valid_lft_ = 0xffffffff
             uint32_t valid_lft = lease_->valid_lft_;
             if (valid_lft == Lease::INFINITY_LFT) {
                 valid_lft = 0;
@@ -1423,7 +1426,7 @@ public:
                                                     hostname, hwaddr,
                                                     prefix_len_));
         time_t cltt = 0;
-        // Recover from overflow
+        // Recover from overflow (see expire code of createBindForSend).
         uint32_t valid_lft = valid_lifetime_;
         if (valid_lft == Lease::INFINITY_LFT) {
             valid_lft = 0;
@@ -2846,6 +2849,8 @@ MySqlLeaseMgr::updateLease4(const Lease4Ptr& lease) {
 
     bind.push_back(inbind[0]);
 
+    // See the expire code of createBindForSend for the
+    // infinite valid lifetime special case.
     MYSQL_TIME expire;
     uint32_t valid_lft = lease->current_valid_lft_;
     if (valid_lft == Lease::INFINITY_LFT) {
@@ -2897,6 +2902,8 @@ MySqlLeaseMgr::updateLease6(const Lease6Ptr& lease) {
 
     bind.push_back(inbind[0]);
 
+    // See the expire code of createBindForSend for the
+    // infinite valid lifetime special case.
     MYSQL_TIME expire;
     uint32_t valid_lft = lease->current_valid_lft_;
     if (valid_lft == Lease::INFINITY_LFT) {
@@ -2959,6 +2966,8 @@ MySqlLeaseMgr::deleteLease(const Lease4Ptr& lease) {
     inbind[0].buffer = reinterpret_cast<char*>(&addr4);
     inbind[0].is_unsigned = MLM_TRUE;
 
+    // See the expire code of createBindForSend for the
+    // infinite valid lifetime special case.
     MYSQL_TIME expire;
     uint32_t valid_lft = lease->current_valid_lft_;
     if (valid_lft == Lease::INFINITY_LFT) {
@@ -3009,6 +3018,8 @@ MySqlLeaseMgr::deleteLease(const Lease6Ptr& lease) {
     inbind[0].buffer_length = addr6_length;
     inbind[0].length = &addr6_length;
 
+    // See the expire code of createBindForSend for the
+    // infinite valid lifetime special case.
     MYSQL_TIME expire;
     uint32_t valid_lft = lease->current_valid_lft_;
     if (valid_lft == Lease::INFINITY_LFT) {

src/lib/dhcpsrv/pgsql_lease_mgr.cc

@@ -502,7 +502,12 @@ public:
             valid_lifetime_str_ = boost::lexical_cast<std::string>(lease->valid_lft_);
             bind_array.add(valid_lifetime_str_);
 
-            // Avoid overflow
+            // The lease structure holds the client last transmission time (cltt_)
+            // For convenience for external tools, this is converted to lease
+            // expiry time (expire).  The relationship is given by:
+            // expire = cltt_ + valid_lft_
+            // Avoid overflow with infinite valid lifetime by using
+            // expire = cltt_ when valid_lft_ = 0xffffffff
             if (lease_->valid_lft_ == Lease::INFINITY_LFT) {
                 expire_str_ = convertToDatabaseTime(lease->cltt_, 0);
             } else {
@@ -562,7 +567,7 @@ public:
 
             getColumnValue(r, row , SUBNET_ID_COL, subnet_id_);
 
-            // Recover from overflow
+            // Recover from overflow (see createBindForSend)
             if (valid_lifetime_ == Lease::INFINITY_LFT) {
                 cltt_ = expire_;
             } else {
@@ -744,7 +749,12 @@ public:
             valid_lifetime_str_ = boost::lexical_cast<std::string>(lease->valid_lft_);
             bind_array.add(valid_lifetime_str_);
 
-            // Avoid overflow
+            // The lease structure holds the client last transmission time (cltt_)
+            // For convenience for external tools, this is converted to lease
+            // expiry time (expire).  The relationship is given by:
+            // expire = cltt_ + valid_lft_
+            // Avoid overflow with infinite valid lifetime by using
+            // expire = cltt_ when valid_lft_ = 0xffffffff
             if (lease_->valid_lft_ == Lease::INFINITY_LFT) {
                 expire_str_ = convertToDatabaseTime(lease->cltt_, 0);
             } else {
@@ -855,7 +865,7 @@ public:
             expire_ = convertFromDatabaseTime(getRawColumnValue(r, row,
                                                                 EXPIRE_COL));
 
-            // Recover from overflow
+            // Recover from overflow (see createBindForSend)
             if (valid_lifetime_ == Lease::INFINITY_LFT) {
                 cltt_ = expire_;
             } else {
@@ -2082,7 +2092,7 @@ PgSqlLeaseMgr::updateLease4(const Lease4Ptr& lease) {
     bind_array.add(addr4_str);
 
     std::string expire_str;
-    // Avoid overflow
+    // Avoid overflow (see createBindForSend)
     if (lease->current_valid_lft_ == Lease::INFINITY_LFT) {
         expire_str = PgSqlLeaseExchange::convertToDatabaseTime(lease->current_cltt_, 0);
     } else {
@@ -2119,7 +2129,7 @@ PgSqlLeaseMgr::updateLease6(const Lease6Ptr& lease) {
     bind_array.add(addr_str);
 
     std::string expire_str;
-    // Avoid overflow
+    // Avoid overflow (see createBindForSend)
     if (lease->current_valid_lft_ == Lease::INFINITY_LFT) {
         expire_str = PgSqlLeaseExchange::convertToDatabaseTime(lease->current_cltt_, 0);
     } else {
@@ -2167,7 +2177,7 @@ PgSqlLeaseMgr::deleteLease(const Lease4Ptr& lease) {
     bind_array.add(addr4_str);
 
     std::string expire_str;
-    // Avoid overflow
+    // Avoid overflow (see createBindForSend)
     if (lease->current_valid_lft_ == Lease::INFINITY_LFT) {
         expire_str = PgSqlLeaseExchange::convertToDatabaseTime(lease->current_cltt_, 0);
     } else {
@@ -2208,7 +2218,7 @@ PgSqlLeaseMgr::deleteLease(const Lease6Ptr& lease) {
     bind_array.add(addr6_str);
 
     std::string expire_str;
-    // Avoid overflow
+    // Avoid overflow (see createBindForSend)
     if (lease->current_valid_lft_ == Lease::INFINITY_LFT) {
         expire_str = PgSqlLeaseExchange::convertToDatabaseTime(lease->current_cltt_, 0);
     } else {