common/exchange_connector.h

/* exchange_connector.h                                            -*- C++ -*-
   Jeremy Barnes, 13 December 2012
   Copyright (c) 2012 Datacratic.  All rights reserved.

   Exchange connector.
*/

#pragma once

#include "soa/service/service_base.h"
#include "rtbkit/common/auction.h"
#include "jml/utils/unnamed_bool.h"

namespace RTBKIT {

class AgentConfig;
class Creative;


/*****************************************************************************/
/* EXCHANGE CONNECTOR                                                        */
/*****************************************************************************/

struct ExchangeConnector: public ServiceBase {

    ExchangeConnector(const std::string & name,
                      ServiceBase & parent);

    ExchangeConnector(const std::string & name,
                      std::shared_ptr<ServiceProxies>
                          = std::shared_ptr<ServiceProxies>());

    virtual ~ExchangeConnector();

    typedef boost::function<void (std::shared_ptr<Auction> Auction)>
        OnAuction;
    
    OnAuction onNewAuction, onAuctionDone;


    /*************************************************************************/
    /* METHODS CALLED BY THE ROUTER TO CONTROL THE EXCHANGE CONNECTOR        */
    /*************************************************************************/

    virtual void configure(const Json::Value & parameters) = 0;

    virtual void start();

    virtual void shutdown();

    virtual void enableUntil(Date date) = 0;

    virtual void setAcceptBidRequestProbability(double prob) = 0;

    virtual std::string exchangeName() const = 0;


    /*************************************************************************/
    /* EXCHANGE COMPATIBILITY                                                */
    /*************************************************************************/

    /* This functionality is used by the router to determine which campaigns
       may bid on inventory from the campaign, and which creatives are
       eligible to be shown to fill impressions for the campaign.

       This is where exchange-specific logic as to required information
       in the creative can be implemented, and allows feedback as to why
       a given campaign or creative is not working on an exchange for
       debugging purposes.
       
       Please note that these methods are called infrequently at campaign
       configuration time, and apply to *all* bid requests for each
       campaign.  Filtering of individual bid requests is done via
       the tags and filters mechanism.
    */

    struct ExchangeCompatibility {
        ExchangeCompatibility()
            : isCompatible(false)
        {
        }

        JML_IMPLEMENT_OPERATOR_BOOL(isCompatible);

        void setCompatible() { isCompatible = true;  reasons.clear(); }

        void setIncompatible() { isCompatible = false;  reasons.clear(); }

        void setIncompatible(const std::string & reason, bool includeReasons)
        {
            isCompatible = false;
            if (includeReasons)
                reasons.push_back(reason);
        }

        void setIncompatible(ML::compact_vector<std::string, 1> && reasons,
                             bool includeReasons)
        {
            isCompatible = false;
            if (includeReasons)
                this->reasons = std::move(reasons);
        }

        bool isCompatible;   
        ML::compact_vector<std::string, 1> reasons;  

        std::shared_ptr<void> info;
    };

    struct CampaignCompatibility : public ExchangeCompatibility {
        CampaignCompatibility()
        {
        }
        
        CampaignCompatibility(const AgentConfig & config);

        std::vector<ExchangeCompatibility> creatives;  
    };

    virtual ExchangeCompatibility
    getCampaignCompatibility(const AgentConfig & config,
                             bool includeReasons) const;
    
    virtual ExchangeCompatibility
    getCreativeCompatibility(const Creative & creative,
                             bool includeReasons) const;


    /*************************************************************************/
    /* FILTERING                                                             */
    /*************************************************************************/

    virtual bool bidRequestPreFilter(const BidRequest & request,
                                     const AgentConfig & config,
                                     const void * info) const;

    virtual bool bidRequestPostFilter(const BidRequest & request,
                                      const AgentConfig & config,
                                      const void * info) const;

    virtual bool bidRequestCreativeFilter(const BidRequest & request,
                                          const AgentConfig & config,
                                          const void * info) const;



    /*************************************************************************/
    /* FACTORY INTERFACE                                                     */
    /*************************************************************************/

    typedef std::function<ExchangeConnector * (ServiceBase * owner, std::string name)>
        Factory;
    
    static void registerFactory(const std::string & exchange, Factory factory);

    static std::unique_ptr<ExchangeConnector>
    create(const std::string & exchangeType,
           ServiceBase & owner,
           const std::string & name);

};


} // namespace RTBKIT