ticket.cpp

Go to the documentation of this file.

// Copyright (c) 2016-2025  Made to Order Software Corp.  All Rights Reserved
//
// https://snapwebsites.org/project/cluck
// contact@m2osw.com
//
// This program is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
 
// self
//
#include    "ticket.h"
 
#include    "cluckd.h"
 
 
// cluck
//
#include    <cluck/exception.h>
#include    <cluck/names.h>
 
 
// advgetopt
//
#include    <advgetopt/validator_integer.h>
 
 
// snapdev
//
#include    <snapdev/hexadecimal_string.h>
#include    <snapdev/string_replace_many.h>
#include    <snapdev/tokenize_string.h>
 
 
// snaplogger
//
#include    <snaplogger/message.h>
 
 
// last include
//
#include    <snapdev/poison.h>
 
 
 
namespace cluck_daemon
{
 
 
 
ticket::ticket(
              cluckd * c
            , messenger::pointer_t messenger
            , std::string const & object_name
            , ed::dispatcher_match::tag_t tag
            , std::string const & entering_key
            , cluck::timeout_t obtention_timeout
            , cluck::timeout_t lock_duration
            , std::string const & server_name
            , std::string const & service_name)
    : f_cluckd(c)
    , f_messenger(messenger)
    , f_object_name(object_name)
    , f_tag(tag)
    , f_obtention_timeout(obtention_timeout)
    , f_lock_duration(std::clamp(
              lock_duration
            , cluck::CLUCK_UNLOCK_MINIMUM_TIMEOUT
            , cluck::CLUCK_MAXIMUM_TIMEOUT))
    , f_server_name(server_name)
    , f_service_name(service_name)
    , f_owner(f_cluckd->get_server_name())
    , f_entering_key(entering_key)
{
    set_unlock_duration(f_lock_duration);
 
    // TODO: see how to not say "attempting a lock" when we are deserializing
    //       an existing lock.
    SNAP_LOG_TRACE
        << "Attempting to lock \""
        << f_object_name
        << "\" ("
        << f_tag
        << ") on \""
        << f_entering_key
        << "\" for \""
        << f_server_name
        << '/'
        << f_service_name
        << "\" (timeout: "
        << f_obtention_timeout
        << ")."
        << SNAP_LOG_SEND;
}
 
 
bool ticket::send_message_to_leaders(ed::message & msg)
{
    // finish the message initialization
    //
    msg.set_service(cluck::g_name_cluck_service_name);
    msg.add_parameter(cluck::g_name_cluck_param_object_name, f_object_name);
    msg.add_parameter(cluck::g_name_cluck_param_tag, f_tag);
 
    computer::pointer_t leader(f_cluckd->get_leader_a());
    if(leader != nullptr)
    {
        // there are at least two leaders
        //
        int count(0);
        msg.set_server(leader->get_name());
        if(f_messenger->send_message(msg))
        {
            ++count;
        }
 
        // check for a third leader
        //
        leader = f_cluckd->get_leader_b();
        if(leader != nullptr)
        {
            msg.set_server(leader->get_name());
            if(f_messenger->send_message(msg))
            {
                ++count;
            }
        }
 
        // we have to wait for at least one reply if we were able to send
        // at least one message
        //
        return count > 0;
    }
 
    // there is only one leader (ourselves)
    //
    // call the one_leader() function to verify that this is indeed correct
    // otherwise we would mess up the algorithm
    //
    return one_leader();
}
 
 
void ticket::entering()
{
    // TODO implement the special case when there is only 1 leader
    //      (on the other hand, that should be rather rare)
    //computer::pointer_t leader(f_cluckd->get_leader_a());
    //if(leader == nullptr)
    //{
    //    -- do the necessary to obtain the lock --
    //    return;
    //}
 
    ed::message entering_message;
    entering_message.set_command(cluck::g_name_cluck_cmd_lock_entering);
    entering_message.add_parameter(cluck::g_name_cluck_param_key, f_entering_key);
    entering_message.add_parameter(cluck::g_name_cluck_param_timeout, f_obtention_timeout);
    entering_message.add_parameter(cluck::g_name_cluck_param_duration, f_lock_duration);
    if(f_lock_duration != f_unlock_duration)
    {
        entering_message.add_parameter(cluck::g_name_cluck_param_unlock_duration, f_unlock_duration);
    }
    entering_message.add_parameter(cluck::g_name_cluck_param_source, f_server_name + "/" + f_service_name);
    entering_message.add_parameter(cluck::g_name_cluck_param_serial, f_serial);
    if(send_message_to_leaders(entering_message))
    {
        if(one_leader())
        {
            // there are no other leaders, make sure the algorithm progresses
            //
            entered();
        }
    }
}
 
 
void ticket::entered()
{
    // is this ticket concerned?
    //
    if(!f_get_max_ticket)
    {
        // with 2 or 3 leaders, quorum is obtain with one
        // single acknowledgement
        //
        f_get_max_ticket = true;
 
        // calculate this instance max. ticket number
        //
        f_our_ticket = f_cluckd->get_last_ticket(f_object_name);
 
        ed::message get_max_ticket_message;
        get_max_ticket_message.set_command(cluck::g_name_cluck_cmd_get_max_ticket);
        get_max_ticket_message.add_parameter(cluck::g_name_cluck_param_key, f_entering_key);
        if(send_message_to_leaders(get_max_ticket_message))
        {
            if(one_leader())
            {
                // there are no other leaders, make sure the algorithm progresses
                //
                max_ticket(f_our_ticket);
            }
        }
    }
}
 
 
void ticket::max_ticket(ticket_id_t new_max_ticket)
{
    if(!f_added_ticket)
    {
        if(new_max_ticket > f_our_ticket)
        {
            f_our_ticket = new_max_ticket;
        }
 
        ++f_our_ticket;
        if(f_our_ticket == NO_TICKET)
        {
            // f_out_ticket is a 32 bit number, this can happen only if you
            // created over 4 billion locks back to back--i.e. created a new
            // one before the previous one was released; or put in a different
            // way: the list of tickets with that "object name" never went
            // back to being empty for that long...
            //
            throw cluck::out_of_range("ticket::max_ticket() tried to generate the next ticket and got a wrapping around number.");
        }
 
        add_ticket();
    }
}
 
 
void ticket::add_ticket()
{
    // we expect exactly one call to this function
    //
    if(f_added_ticket)
    {
        throw cluck::logic_error("ticket::add_ticket() called more than once."); // LCOV_EXCL_LINE
    }
    f_added_ticket = true;
 
    //
    // WARNING: the ticket key MUST be properly sorted by:
    //
    //              ticket number
    //              server name
    //              client pid
    //
    // The client PID does not need to be sorted numerically, just be sorted
    // so one client is before the other.
    //
    // However, the ticket number MUST be numerically sorted. For this reason,
    // since the key is a string, we must add introducing zeroes.
    //
    f_ticket_key = snapdev::int_to_hex(f_our_ticket, false, 8)
                 + '/'
                 + f_entering_key;
 
    f_cluckd->set_ticket(f_object_name, f_ticket_key, shared_from_this());
 
    ed::message add_ticket_message;
    add_ticket_message.set_command(cluck::g_name_cluck_cmd_add_ticket);
    add_ticket_message.add_parameter(cluck::g_name_cluck_param_key, f_ticket_key);
    add_ticket_message.add_parameter(cluck::g_name_cluck_param_timeout, f_obtention_timeout);
    if(send_message_to_leaders(add_ticket_message))
    {
        if(one_leader())
        {
            ticket_added(f_cluckd->get_entering_tickets(f_object_name));
        }
    }
}
 
 
void ticket::ticket_added(key_map_t const & still_entering)
{
    if(!f_added_ticket_quorum)
    {
        // when we have 2 or 3 leaders, quorum is obtain with one
        // single acknowledgement
        //
        f_added_ticket_quorum = true;
 
        f_still_entering = still_entering;
 
        // okay, the ticket was added on all cluck daemons
        // now we can forget about the entering flag
        // (equivalent to setting it to false)
        //
        ed::message exiting_message;
        exiting_message.set_command(cluck::g_name_cluck_cmd_lock_exiting);
        exiting_message.add_parameter(cluck::g_name_cluck_param_key, f_entering_key);
        snapdev::NOT_USED(send_message_to_leaders(exiting_message));
 
        f_cluckd->lock_exiting(exiting_message);
    }
}
 
 
void ticket::remove_entering(std::string const & key)
{
    if(f_added_ticket_quorum
    && !f_ticket_ready)
    {
        auto it(f_still_entering.find(key));
        if(it != f_still_entering.end())
        {
            f_still_entering.erase(it);
 
            // just like the quorum computation, we compute the
            // remaining list of entering tickets dynamically at
            // the time we check the value
            //
            for(auto key_entering(f_still_entering.begin()); key_entering != f_still_entering.end(); )
            {
                if(key_entering->second->timed_out())
                {
                    key_entering = f_still_entering.erase(key_entering);
                }
                else
                {
                    ++key_entering;
                }
            }
 
            // once all removed, our ticket is ready!
            //
            if(f_still_entering.empty())
            {
                f_ticket_ready = true;
 
                // let the other two leaders know that the ticket is ready
                //
                ed::message ticket_ready_message;
                ticket_ready_message.set_command(cluck::g_name_cluck_cmd_ticket_ready);
                ticket_ready_message.add_parameter(cluck::g_name_cluck_param_key, f_ticket_key);
                snapdev::NOT_USED(send_message_to_leaders(ticket_ready_message));
            }
        }
    }
}
 
 
void ticket::activate_lock()
{
    if(f_ticket_ready
    && !f_locked
    && f_lock_failed == lock_failure_t::LOCK_FAILURE_NONE)
    {
        ed::message activate_lock_message;
        activate_lock_message.set_command(cluck::g_name_cluck_cmd_activate_lock);
        activate_lock_message.add_parameter(cluck::g_name_cluck_param_key, f_ticket_key);
        if(send_message_to_leaders(activate_lock_message))
        {
            if(one_leader())
            {
                lock_activated();
            }
        }
    }
}
 
 
void ticket::lock_activated()
{
    if(f_ticket_ready
    && !f_locked
    && f_lock_failed == lock_failure_t::LOCK_FAILURE_NONE)
    {
        f_locked = true;
        f_lock_timeout_date = snapdev::now() + f_lock_duration;
        f_unlocked_timeout_date = f_lock_timeout_date + f_unlock_duration;
 
        if(f_owner == f_cluckd->get_server_name())
        {
            ed::message locked_message;
            locked_message.set_command(cluck::g_name_cluck_cmd_locked);
            locked_message.set_server(f_server_name);
            locked_message.set_service(f_service_name);
            locked_message.add_parameter(cluck::g_name_cluck_param_object_name, f_object_name);
            locked_message.add_parameter(cluck::g_name_cluck_param_timeout_date, f_lock_timeout_date);
            locked_message.add_parameter(cluck::g_name_cluck_param_unlocked_date, f_unlocked_timeout_date);
            locked_message.add_parameter(cluck::g_name_cluck_param_tag, f_tag);
            f_messenger->send_message(locked_message);
        }
    }
}
 
 
void ticket::drop_ticket()
{
    SNAP_LOG_TRACE
        << "Unlock on \""
        << f_object_name
        << "\" ("
        << f_tag
        << ") with key \""
        << f_entering_key
        << "\"."
        << SNAP_LOG_SEND;
 
    ed::message drop_ticket_message;
    drop_ticket_message.set_command(cluck::g_name_cluck_cmd_drop_ticket);
    drop_ticket_message.add_parameter(
              cluck::g_name_cluck_param_key
            , f_ticket_key.empty() ? f_entering_key : f_ticket_key);
    send_message_to_leaders(drop_ticket_message);
 
    if(f_lock_failed == lock_failure_t::LOCK_FAILURE_NONE)
    {
        f_lock_failed = lock_failure_t::LOCK_FAILURE_UNLOCKING;
 
        //if(f_owner == f_cluckd->get_server_name()) -- this can happen with any leader so we have to send the UNLOCKED
        //                                              the other leaders won't call this function they receive DROP_TICKET
        //                                              instead and as mentioned in the TODO below, we should get a QUORUM
        //                                              instead...
        {
            // we can immediately say it got unlocked...
            //
            // TODO: this is true ONLY if you lock the same object no more than
            //       once within a session, which is not unlikely false (it is
            //       true for what I can remember of Snap!, but long term this
            //       is not safe.) Like the LOCK, we need a quorum and then
            //       send the UNLOCK... At this point, I'm not too sure how
            //       we implement such because the drop_ticket function ends
            //       up deleting the ticket from memory and thus no counting
            //       can happen after that... (i.e. we need a special case
            //       of the receiver for the UNLOCK, argh!)
            //
            ed::message unlocked_message;
            unlocked_message.set_command(cluck::g_name_cluck_cmd_unlocked);
            unlocked_message.set_server(f_server_name);
            unlocked_message.set_service(f_service_name);
            unlocked_message.add_parameter(cluck::g_name_cluck_param_object_name, f_object_name);
            unlocked_message.add_parameter(cluck::g_name_cluck_param_unlocked_date, snapdev::now());
            unlocked_message.add_parameter(cluck::g_name_cluck_param_tag, f_tag);
            f_messenger->send_message(unlocked_message);
        }
    }
}
 
 
void ticket::lock_failed(std::string const & reason)
{
    enum send_msg_t
    {
        SEND_MSG_NONE,
        SEND_MSG_UNLOCKING,
        SEND_MSG_UNLOCKED,
        SEND_MSG_FAILED,
    };
 
    send_msg_t send(SEND_MSG_NONE);
 
    switch(f_lock_failed)
    {
    case lock_failure_t::LOCK_FAILURE_NONE:
        // send that message at most once
        //
        f_lock_failed = lock_failure_t::LOCK_FAILURE_LOCK;
 
        if(f_locked)
        {
            // now we have to extend the lock timeout to make sure that
            // the UNLOCKING has a chance to be acknowledged
            //
            f_lock_timeout_date += f_unlock_duration;
            if(timed_out())
            {
                // this case is logical here, but I don't think it can
                // happen because the f_locked is true and thus the only
                // value we can use is f_lock_timeout_date and we just
                // increased that value by at least 3 seconds
                //
                send = SEND_MSG_UNLOCKED; // LCOV_EXCL_LINE
            }
            else
            {
                send = SEND_MSG_UNLOCKING;
            }
        }
        else
        {
            send = SEND_MSG_FAILED;
        }
        break;
 
    case lock_failure_t::LOCK_FAILURE_LOCK:
        f_lock_failed = lock_failure_t::LOCK_FAILURE_UNLOCKING;
 
        if(f_locked)
        {
            send = SEND_MSG_UNLOCKED;
        }
        break;
 
    case lock_failure_t::LOCK_FAILURE_UNLOCKING:
        // we already sent all the possible messages
        break;
 
    }
 
    // we want the f_lock_failed and f_lock_timeout_date set before returning
    //
    if(f_owner != f_cluckd->get_server_name())
    {
        return;
    }
 
    switch(send)
    {
    case SEND_MSG_NONE:
        // don't send another message
        break;
 
    case SEND_MSG_UNLOCKING:
        {
            // if we were locked and reach here, then the lock
            // timed out while locked but the unlock timeout was
            // not yet reached so just send an UNLOCKING message
            //
            SNAP_LOG_IMPORTANT
                << "Lock on \""
                << f_object_name
                << "\" ("
                << f_tag
                << ") with key \""
                << f_entering_key
                << "\" timed out its lock allowed time."
                << SNAP_LOG_SEND;
 
            ed::message lock_failed_message;
            lock_failed_message.set_command(cluck::g_name_cluck_cmd_unlocking);
            lock_failed_message.set_server(f_server_name);
            lock_failed_message.set_service(f_service_name);
            lock_failed_message.add_parameter(cluck::g_name_cluck_param_object_name, f_object_name);
            lock_failed_message.add_parameter(cluck::g_name_cluck_param_tag, f_tag);
            lock_failed_message.add_parameter(cluck::g_name_cluck_param_error, cluck::g_name_cluck_value_timedout);
            f_messenger->send_message(lock_failed_message);
        }
        break;
 
    case SEND_MSG_UNLOCKED:
        {
            // if we were locked and/or unlocking and we reach here,
            // then the lock completely timed out and we immediately
            // completely unlock with an UNLOCKED message
            //
            // IMPORTANT: that means the service should stop using the
            //            shared resources but there is absoltely no
            //            guarantee about that; however, this situation
            //            should only occur when a service somehow does
            //            not properly UNLOCK its lock
            //
            SNAP_LOG_IMPORTANT
                << "Lock on \""
                << f_object_name
                << "\" ("
                << f_tag
                << ") with key \""
                << f_entering_key
                << "\" timed out its unlocking allowed time."
                << SNAP_LOG_SEND;
 
            ed::message lock_failed_message;
            lock_failed_message.set_command(cluck::g_name_cluck_cmd_unlocked);
            lock_failed_message.set_server(f_server_name);
            lock_failed_message.set_service(f_service_name);
            lock_failed_message.add_parameter(cluck::g_name_cluck_param_object_name, f_object_name);
            lock_failed_message.add_parameter(cluck::g_name_cluck_param_tag, f_tag);
            lock_failed_message.add_parameter(cluck::g_name_cluck_param_error, cluck::g_name_cluck_value_timedout);
            f_messenger->send_message(lock_failed_message);
        }
        break;
 
    case SEND_MSG_FAILED:
        {
            SNAP_LOG_IMPORTANT
                << "Lock on \""
                << f_object_name
                << "\" ("
                << f_tag
                << ") with key \""
                << f_entering_key
                << "\" failed."
                << SNAP_LOG_SEND;
 
            ed::message lock_failed_message;
            lock_failed_message.set_command(cluck::g_name_cluck_cmd_lock_failed);
            lock_failed_message.set_server(f_server_name);
            lock_failed_message.set_service(f_service_name);
            lock_failed_message.add_parameter(cluck::g_name_cluck_param_object_name, f_object_name);
            lock_failed_message.add_parameter(cluck::g_name_cluck_param_tag, f_tag);
            lock_failed_message.add_parameter(cluck::g_name_cluck_param_key, f_entering_key);
            lock_failed_message.add_parameter(cluck::g_name_cluck_param_error, cluck::g_name_cluck_value_failed);
            lock_failed_message.add_parameter(cluck::g_name_cluck_param_description,
                    "ticket failed before or after the lock was obtained ("
                    + reason
                    + ")");
            f_messenger->send_message(lock_failed_message);
        }
        break;
 
    }
}
 
 
void ticket::set_owner(std::string const & owner)
{
    f_owner = owner;
}
 
 
std::string const & ticket::get_owner() const
{
    return f_owner;
}
 
 
pid_t ticket::get_client_pid() const
{
    std::vector<std::string> segments;
    if(snapdev::tokenize_string(segments, f_entering_key, "/") != 2)
    {
        throw cluck::invalid_parameter(
                  "ticket::get_client_pid() split f_entering_key \""
                + f_entering_key
                + "\" and did not get exactly two segments.");
    }
    std::int64_t value;
    advgetopt::validator_integer::convert_string(segments[1], value);
    return static_cast<pid_t>(value);
}
 
 
void ticket::set_serial(serial_t serial)
{
    f_serial = serial;
}
 
 
ticket::serial_t ticket::get_serial() const
{
    return f_serial;
}
 
 
void ticket::set_unlock_duration(cluck::timeout_t duration)
{
    if(duration == cluck::CLUCK_DEFAULT_TIMEOUT)
    {
        duration = f_lock_duration;
    }
 
    f_unlock_duration = std::clamp(
                              duration
                            , cluck::CLUCK_UNLOCK_MINIMUM_TIMEOUT
                            , cluck::CLUCK_MAXIMUM_TIMEOUT);
}
 
 
cluck::timeout_t ticket::get_unlock_duration() const
{
    return f_unlock_duration;
}
 
 
void ticket::set_ready()
{
    f_ticket_ready = true;
}
 
 
void ticket::set_ticket_number(ticket_id_t const number)
{
    if(f_our_ticket != NO_TICKET
    || f_added_ticket)
    {
        throw cluck::logic_error("ticket::set_ticket_number() called with "
                + std::to_string(number)
                + " when f_our_ticket is already set to "
                + std::to_string(f_our_ticket)
                + ".");
    }
    f_added_ticket = true;
 
    f_our_ticket = number;
    f_ticket_key = snapdev::int_to_hex(f_our_ticket, false, 8)
                 + '/'
                 + f_entering_key;
}
 
 
ticket::ticket_id_t ticket::get_ticket_number() const
{
    return f_our_ticket;
}
 
 
bool ticket::is_locked() const
{
    return f_locked;
}
 
 
bool ticket::one_leader() const
{
    return f_cluckd->get_computer_count() == 1;
}
 
 
cluck::timeout_t ticket::get_obtention_timeout() const
{
    return f_obtention_timeout;
}
 
 
void ticket::set_alive_timeout(cluck::timeout_t timeout)
{
    if(timeout < cluck::timeout_t())
    {
        timeout = cluck::timeout_t();
    }
 
    if(timeout < f_obtention_timeout)
    {
        f_alive_timeout = timeout;
    }
    else
    {
        // use the obtention timeout if smaller because that was the
        // first premise that the client asked about
        //
        f_alive_timeout = f_obtention_timeout;
    }
}
 
 
cluck::timeout_t ticket::get_lock_duration() const
{
    return f_lock_duration;
}
 
 
cluck::timeout_t ticket::get_lock_timeout_date() const
{
    return f_lock_timeout_date;
}
 
 
cluck::timeout_t ticket::get_current_timeout_date() const
{
    if(f_alive_timeout > cluck::timeout_t())
    {
        return f_alive_timeout;
    }
 
    if(f_locked)
    {
        return f_lock_timeout_date;
    }
 
    return f_obtention_timeout;
}
 
 
bool ticket::timed_out() const
{
    return get_current_timeout_date() <= snapdev::now();
}
 
 
std::string const & ticket::get_object_name() const
{
    return f_object_name;
}
 
 
ed::dispatcher_match::tag_t ticket::get_tag() const
{
    return f_tag;
}
 
 
std::string const & ticket::get_server_name() const
{
    return f_server_name;
}
 
 
std::string const & ticket::get_service_name() const
{
    return f_service_name;
}
 
 
std::string const & ticket::get_entering_key() const
{
    return f_entering_key;
}
 
 
std::string const & ticket::get_ticket_key() const
{
    return f_ticket_key;
}
 
 
std::string ticket::serialize() const
{
    std::map<std::string, std::string> data;
 
    data["object_name"]         = f_object_name;
    data["tag"]                 = std::to_string(static_cast<int>(f_tag));
    data["obtention_timeout"]   = f_obtention_timeout.to_timestamp(true);
    //data["alive_timeout"]       = f_alive_timeout.to_timestamp(true); -- we do not want to transfer this one
    data["lock_duration"]       = f_lock_duration.to_timestamp(true);
    data["unlock_duration"]     = f_unlock_duration.to_timestamp(true);
    data["server_name"]         = f_server_name;
    data["service_name"]        = f_service_name;
    data["owner"]               = f_owner;
    if(f_serial != NO_SERIAL)
    {
        data["serial"]          = std::to_string(f_serial);
    }
    data["entering_key"]        = f_entering_key;
    data["get_max_ticket"]      = f_get_max_ticket ? "true" : "false";
    data["our_ticket"]          = std::to_string(f_our_ticket);
    data["added_ticket"]        = f_added_ticket ? "true" : "false";
    data["ticket_key"]          = f_ticket_key;
    data["added_ticket_quorum"] = f_added_ticket_quorum ? "true" : "false";
 
    // this is a map
    //data["still_entering"]      = f_still_entering;
    //ticket::key_map_t  f_still_entering = key_map_t();
 
    data["ticket_ready"]        = f_ticket_ready ? "true" : "false";
    data["locked"]              = f_locked ? "true" : "false";
    data["lock_timeout_date"]   = f_lock_timeout_date.to_timestamp(true);
 
    switch(f_lock_failed)
    {
    case lock_failure_t::LOCK_FAILURE_NONE:
        data["lock_failed"] = "none";
        break;
 
    case lock_failure_t::LOCK_FAILURE_LOCK:
        data["lock_failed"] = "lock";
        break;
 
    case lock_failure_t::LOCK_FAILURE_UNLOCKING:
        data["lock_failed"] = "unlocking";
        break;
 
    }
 
    std::string result;
    for(auto & it : data)
    {
        result += it.first;
        result += '=';
        // make sure the value does not include any '|'
        result += snapdev::string_replace_many(it.second, {{"|", "%7C"}});
        result += '|';
    }
    result.pop_back();
 
    return result;
}
 
 
void ticket::unserialize(std::string const & data)
{
    std::vector<std::string> vars;
    snapdev::NOT_USED(snapdev::tokenize_string(vars, data, "|"));
    for(auto const & d : vars)
    {
        std::string::size_type const pos(d.find('='));
        std::string const name(d.substr(0, pos));
        std::string const value(d.substr(pos + 1));
        switch(name[0])
        {
        case 'a':
            if(name == "added_ticket")
            {
                f_added_ticket = f_added_ticket || value == "true";
            }
            else if(name == "added_ticket_quorum")
            {
                f_added_ticket_quorum = f_added_ticket_quorum || value == "true";
            }
            //else if(name == "alive_timeout") -- we do not transfer this one (not required, and could actually cause problems)
            //{
            //    f_alive_timeout = cluck::timeout_t(value);
            //}
            break;
 
        case 'e':
            if(name == "entering_key")
            {
#ifdef _DEBUG
                if(f_entering_key != value)
                {
                    // LCOV_EXCL_START
                    throw cluck::logic_error(
                                "ticket::unserialize() not unserializing entering key \""
                                + value
                                + "\" over itself \""
                                + f_entering_key
                                + "\" (entering key mismatch).");
                    // LCOV_EXCL_STOP
                }
#endif
                f_entering_key = value;
            }
            break;
 
        case 'g':
            if(name == "get_max_ticket")
            {
                f_get_max_ticket = f_get_max_ticket || value == "true";
            }
            break;
 
        case 'l':
            if(name == "lock_duration")
            {
                f_lock_duration = cluck::timeout_t(value);
            }
            else if(name == "locked")
            {
                f_locked = f_locked || value == "true";
            }
            else if(name == "lock_timeout_date")
            {
                // the time may be larger because of an UNLOCK so we keep
                // the largest value
                //
                cluck::timeout_t const timeout_date(value);
                if(timeout_date > f_lock_timeout_date)
                {
                    f_lock_timeout_date = timeout_date;
                }
            }
            else if(name == "lock_failed")
            {
                // in this case, we avoid reducing the error level
                //
                if(value == "unlocking")
                {
                    f_lock_failed = lock_failure_t::LOCK_FAILURE_UNLOCKING;
                }
                else if(value == "lock" && f_lock_failed == lock_failure_t::LOCK_FAILURE_NONE)
                {
                    f_lock_failed = lock_failure_t::LOCK_FAILURE_LOCK;
                }
            }
            break;
 
        case 'o':
            if(name == "object_name")
            {
#ifdef _DEBUG
                if(f_object_name != value)
                {
                    // LCOV_EXCL_START
                    throw cluck::logic_error(
                                "ticket::unserialize() not unserializing object name \""
                                + value
                                + "\" over itself \""
                                + f_object_name
                                + "\" (object name mismatch).");
                    // LCOV_EXCL_STOP
                }
#endif
                f_object_name = value;
            }
            else if(name == "obtention_timeout")
            {
                f_obtention_timeout = cluck::timeout_t(value);
            }
            else if(name == "owner")
            {
                f_owner = value;
            }
            else if(name == "our_ticket")
            {
                std::int64_t v;
                advgetopt::validator_integer::convert_string(value, v);
                f_our_ticket = v;
            }
            break;
 
        case 's':
            if(name == "server_name")
            {
                f_server_name = value;
            }
            else if(name == "service_name")
            {
                f_service_name = value;
            }
            else if(name == "serial")
            {
                std::int64_t v;
                advgetopt::validator_integer::convert_string(value, v);
                f_serial = v;
            }
            break;
 
        case 't':
            if(name == "tag")
            {
                std::int64_t v;
                advgetopt::validator_integer::convert_string(value, v);
                f_tag = v;
            }
            else if(name == "ticket_key")
            {
                f_ticket_key = value;
            }
            else if(name == "ticket_ready")
            {
                f_ticket_ready = f_ticket_ready || value == "true";
            }
            break;
 
        case 'u':
            if(name == "unlock_duration")
            {
                f_unlock_duration = cluck::timeout_t(value);
            }
            break;
 
        }
    }
}
 
 
 
} // namespace cluck_daemon
// vim: ts=4 sw=4 et