core/agent_configuration/agent_config.h

/* rtb_agent_config.h                                             -*- C++ -*-
   Jeremy Barnes, 24 March 2011
   Configuration for an RTB agent.
*/

#ifndef __rtb_agent_config_h__
#define __rtb_agent_config_h__

#include <string>
#include <vector>
#include <set>
#include "jml/arch/spinlock.h"
#include "soa/jsoncpp/json.h"
#include <boost/regex.hpp>
#include <boost/regex/icu.hpp>
#include "rtbkit/common/bid_request.h"
#include "include_exclude.h"
#include "rtbkit/common/account_key.h"

namespace RTBKIT {


struct BiddableSpots;
struct AgentStats;
struct ExchangeConnector;


/*****************************************************************************/
/* CREATIVE                                                                  */
/*****************************************************************************/

struct Creative {
    Creative(int width = 0, int height = 0,
             std::string name = "", int id = -1, int tagId = -1);

    // Three samples that can be used for testing...
    static const Creative sampleLB;
    static const Creative sampleBB;
    static const Creative sampleWS;

    void fromJson(const Json::Value & val);
    Json::Value toJson() const;

    Format format;

    int tagId;

    std::string name;
    int id;

    Json::Value providerConfig;

    mutable ML::Spinlock lock;

    std::map<std::string, std::shared_ptr<void> > providerData;

    template<typename T>
    const T * getProviderData(const std::string & provider) const
    {
        auto it = providerData.find(provider);
        if (it == providerData.end())
            throw ML::Exception("provider data for " + provider + " not found");
        if (it->second.get() == nullptr)
            throw ML::Exception("provider data for " + provider + " is null");
        
        return reinterpret_cast<const T *>(it->second.get());
    }

    Tags tags;

    TagFilterExpression eligibilityFilter;

    IncludeExclude<std::string> languageFilter;
    IncludeExclude<CachedRegex<boost::u32regex, Utf8String> > locationFilter;
    IncludeExclude<std::string> exchangeFilter;

    bool compatible(const AdSpot & spot) const;

    bool biddable(const std::string & exchange,
                  const std::string & protocolVersion) const;
};


/*****************************************************************************/
/* USER PARTITION                                                            */
/*****************************************************************************/

struct UserPartition {
    UserPartition();

    void swap(UserPartition & other);

    void clear();

    enum HashOn {
        NONE,        
        RANDOM,      

        EXCHANGEID,  
        PROVIDERID   
    } hashOn;

    int modulus;     

    struct Interval {
        Interval(int first = 0, int last = 0)
            : first(first), last(last)
        {
        }

        int first, last;

        bool in(int val) const
        {
            return val >= first && val < last;
        }

        Json::Value toJson() const;
    };

    bool empty() const
    {
        return hashOn == NONE && modulus == 1 && includeRanges.size() == 1
            && includeRanges[0].first == 0 && includeRanges[0].last == 1;
    }

    std::vector<Interval> includeRanges;

    bool matches(const UserIds & ids) const;

    void fromJson(const Json::Value & json);

    Json::Value toJson() const;
};


/*****************************************************************************/
/* BLACKLIST CONTROL                                                         */
/*****************************************************************************/

enum BlacklistType {
    BL_OFF,       
    BL_USER,      
    BL_USER_SITE  
};

enum BlacklistScope {
    BL_AGENT,      
    BL_ACCOUNT,    
};


/*****************************************************************************/
/* BID CONTROL TYPE                                                          */
/*****************************************************************************/

enum BidControlType {
    BC_RELAY,       
    BC_RELAY_FIXED, 
    BC_FIXED        
};


/*****************************************************************************/
/* BID RESULT FORMAT                                                         */
/*****************************************************************************/

enum BidResultFormat {
    BRF_FULL,         
    BRF_LIGHTWEIGHT,  
    BRF_NONE          
};

Json::Value toJson(BidResultFormat fmt);
void fromJson(BidResultFormat & fmt, const Json::Value & j);


/*****************************************************************************/
/* AGENT CONFIG                                                              */
/*****************************************************************************/

struct AgentConfig {
    AgentConfig();

    static AgentConfig createFromJson(const Json::Value & json);

    void parse(const std::string & jsonStr);
    void fromJson(const Json::Value & json);

    Json::Value toJson(bool includeCreatives = true) const;

    AccountKey account;   

    bool test;            
    
    std::string roundRobinGroup;
    int roundRobinWeight;

    float bidProbability;
    float minTimeAvailableMs;

    int maxInFlight;

    std::vector<std::string> requiredIds;

    IncludeExclude<DomainMatcher> hostFilter;
    IncludeExclude<CachedRegex<boost::regex, std::string> > urlFilter;
    IncludeExclude<CachedRegex<boost::regex, std::string> > languageFilter;
    IncludeExclude<CachedRegex<boost::u32regex, Utf8String> > locationFilter;

    struct SegmentInfo {
        SegmentInfo()
            : excludeIfNotPresent(false)
        {
        }

        bool excludeIfNotPresent;
        SegmentList include;
        SegmentList exclude;

        IncludeExclude<std::string> applyToExchanges;
        
        IncludeExcludeResult process(const SegmentList & segments) const;
        
        void fromJson(const Json::Value & val);
        Json::Value toJson() const;
    };

    std::map<std::string, SegmentInfo> segments;

    IncludeExclude<std::string> exchangeFilter;

    IncludeExclude<OpenRTB::AdPosition> foldPositionFilter;

    SegmentInfo tagFilter;

    struct HourOfWeekFilter {

        HourOfWeekFilter();

        bool isIncluded(Date auctionDate) const;

        bool isDefault() const;  // true if all hours are 1

        void fromJson(const Json::Value & val);
        Json::Value toJson() const;

    private:
        std::bitset<168> hourBitmap;
    };
    
    HourOfWeekFilter hourOfWeekFilter;

    UserPartition userPartition;

    std::vector<Creative> creatives;

    BlacklistType blacklistType;
    BlacklistScope blacklistScope;
    double blacklistTime;
    
    bool hasBlacklist() const
    {
        return blacklistType != BL_OFF && blacklistTime > 0.0;
    }

    BidControlType bidControlType;
    uint32_t fixedBidCpmInMicros;

    IncludeExclude<std::string> augmentationFilter;

    struct AugmentationInfo {
        std::string name;
        Json::Value config;

        bool operator < (const AugmentationInfo & other) const
        {
            return name < other.name;
        }
    };

    void addAugmentation(const std::string & name,
                         Json::Value config = Json::Value());

    void addAugmentation(AugmentationInfo info);

    std::vector<AugmentationInfo> augmentations;

    Json::Value providerConfig;

    mutable ML::Spinlock lock;

    std::map<std::string, std::shared_ptr<void> > providerData;

    template<typename T>
    const T * getProviderData(const std::string & provider) const
    {
        auto it = providerData.find("rubicon");
        if (it == providerData.end())
            throw ML::Exception("provider data for " + provider + " not found");
        if (it->second.get() == nullptr)
            throw ML::Exception("provider data for " + provider + " is null");
        
        return reinterpret_cast<const T *>(it->second.get());
    }

    SegmentList visitChannels;

    bool includeUnmatchedVisits;

    BidResultFormat winFormat, lossFormat, errorFormat;

    BiddableSpots
    canBid(const ExchangeConnector * exchangeConnector,
           const std::vector<AdSpot> & imp,
           const std::string & exchange,
           const std::string & protocolVersion,
           const std::string & language,
           const Utf8String & location, uint64_t locationHash,
           ML::Lightweight_Hash<uint64_t, int> & locationCache) const;


    struct RequestFilterCache
    {
        RequestFilterCache(const BidRequest& request) :
            urlHash(hashString(request.url.c_str())),

            language(!request.language.empty() ?
                    request.language : "unspecified"),
            languageHash(hashString(request.language)),

            location(request.location.fullLocationString()),
            locationHash(hashString(location))
        {}

        uint64_t urlHash;

        std::string language;
        uint64_t languageHash;

        Utf8String location;
        uint64_t locationHash;

        // Cache of regex -> bool
        ML::Lightweight_Hash<uint64_t, int> urlFilter;
        ML::Lightweight_Hash<uint64_t, int> languageFilter;
        ML::Lightweight_Hash<uint64_t, int> locationFilter;
    };

    typedef std::function<void(const char*)> FilterStatFn;

    BiddableSpots
    isBiddableRequest(const ExchangeConnector * exchange,
                      const BidRequest& request,
                      AgentStats& stats,
                      RequestFilterCache& cache,
                      const FilterStatFn & doFilterStat = FilterStatFn()) const;
};


} // namespace RTBKIT

#endif /* __rtb_agent_config_h__ */