src/adaptation/icap/ServiceRep.h

   1 /*
   2  * Copyright (C) 1996-2015 The Squid Software Foundation and contributors
   3  *
   4  * Squid software is distributed under GPLv2+ license and includes
   5  * contributions from numerous individuals and organizations.
   6  * Please see the COPYING and CONTRIBUTORS files for details.
   7  */
   8
   9 #ifndef SQUID_ICAPSERVICEREP_H
  10 #define SQUID_ICAPSERVICEREP_H
  11
  12 #include "adaptation/forward.h"
  13 #include "adaptation/icap/Elements.h"
  14 #include "adaptation/Initiator.h"
  15 #include "adaptation/Service.h"
  16 #include "base/AsyncJobCalls.h"
  17 #include "cbdata.h"
  18 #include "comm.h"
  19 #include "FadingCounter.h"
  20 #include "pconn.h"
  21 #include <deque>
  22
  23 namespace Adaptation
  24 {
  25 namespace Icap
  26 {
  27
  28 class Options;
  29 class OptXact;
  30
  31 /* The ICAP service representative maintains information about a single ICAP
  32    service that Squid communicates with. The representative initiates OPTIONS
  33    requests to the service to keep cached options fresh. One ICAP server may
  34    host many ICAP services. */
  35
  36 /*
  37  * A service with a fresh cached OPTIONS response and without many failures
  38  * is an "up" service. All other services are "down". A service is "probed"
  39  * if we tried to get an OPTIONS response from it and succeeded or failed.
  40  * A probed down service is called "broken".
  41  *
  42  * The number of failures required to bring an up service down is determined
  43  * by icap_service_failure_limit in squid.conf.
  44  *
  45  * As a bootstrapping mechanism, ICAP transactions wait for an unprobed
  46  * service to get a fresh OPTIONS response (see the callWhenReady method).
  47  * The waiting callback is called when the OPTIONS transaction completes,
  48  * even if the service is now broken.
  49  *
  50  * We do not initiate ICAP transactions with a broken service, but will
  51  * eventually retry to fetch its options in hope to bring the service up.
  52  *
  53  * A service that should no longer be used after Squid reconfiguration is
  54  * treated as if it does not have a fresh cached OPTIONS response. We do
  55  * not try to fetch fresh options for such a service. It should be
  56  * auto-destroyed by refcounting when no longer used.
  57  */
  58
  59 class ServiceRep : public RefCountable, public Adaptation::Service,
  60     public Adaptation::Initiator
  61 {
  62     CBDATA_CLASS(ServiceRep);
  63
  64 public:
  65     typedef RefCount<ServiceRep> Pointer;
  66
  67 public:
  68     explicit ServiceRep(const ServiceConfigPointer &aConfig);
  69     virtual ~ServiceRep();
  70
  71     virtual void finalize();
  72
  73     virtual bool probed() const; // see comments above
  74     virtual bool up() const; // see comments above
  75     bool availableForNew() const; ///< a new transaction may start communicating with the service
  76     bool availableForOld() const; ///< a transaction notified about connection slot availability may start communicating with the service
  77
  78     virtual Initiate *makeXactLauncher(HttpMsg *virginHeader, HttpRequest *virginCause, AccessLogEntry::Pointer &alp);
  79
  80     void callWhenAvailable(AsyncCall::Pointer &cb, bool priority = false);
  81     void callWhenReady(AsyncCall::Pointer &cb);
  82
  83     // the methods below can only be called on an up() service
  84     bool wantsUrl(const String &urlPath) const;
  85     bool wantsPreview(const String &urlPath, size_t &wantedSize) const;
  86     bool allows204() const;
  87     bool allows206() const;
  88     Comm::ConnectionPointer getConnection(bool isRetriable, bool &isReused);
  89     void putConnection(const Comm::ConnectionPointer &conn, bool isReusable, bool sendReset, const char *comment);
  90     void noteConnectionUse(const Comm::ConnectionPointer &conn);
  91     void noteConnectionFailed(const char *comment);
  92
  93     void noteFailure(); // called by transactions to report service failure
  94
  95     void noteNewWaiter() {theAllWaiters++;} ///< New xaction waiting for service to be up or available
  96     void noteGoneWaiter(); ///< An xaction is not waiting any more for service to be available
  97     bool existWaiters() const {return (theAllWaiters > 0);} ///< if there are xactions waiting for the service to be available
  98
  99     //AsyncJob virtual methods
 100     virtual bool doneAll() const { return Adaptation::Initiator::doneAll() && false;}
 101     virtual void callException(const std::exception &e);
 102
 103     virtual void detach();
 104     virtual bool detached() const;
 105
 106 public: // treat these as private, they are for callbacks only
 107     void noteTimeToUpdate();
 108     void noteTimeToNotify();
 109
 110     // receive either an ICAP OPTIONS response header or an abort message
 111     virtual void noteAdaptationAnswer(const Answer &answer);
 112
 113 private:
 114     // stores Prepare() callback info
 115
 116     struct Client {
 117         Pointer service; // one for each client to preserve service
 118         AsyncCall::Pointer callback;
 119     };
 120
 121     typedef std::vector<Client> Clients;
 122     // TODO: rename to theUpWaiters
 123     Clients theClients; // all clients waiting for a call back
 124
 125     Options *theOptions;
 126     CbcPointer<Adaptation::Initiate> theOptionsFetcher; // pending ICAP OPTIONS transaction
 127     time_t theLastUpdate; // time the options were last updated
 128
 129     /// FIFO queue of xactions waiting for a connection slot and not yet notified
 130     /// about it; xaction is removed when notification is scheduled
 131     std::deque<Client> theNotificationWaiters;
 132     int theBusyConns;   ///< number of connections given to active transactions
 133     /// number of xactions waiting for a connection slot (notified and not)
 134     /// the number is decreased after the xaction receives notification
 135     int theAllWaiters;
 136     int theMaxConnections; ///< the maximum allowed connections to the service
 137     // TODO: use a better type like the FadingCounter for connOverloadReported
 138     mutable bool connOverloadReported; ///< whether we reported exceeding theMaxConnections
 139     IdleConnList *theIdleConns; ///< idle persistent connection pool
 140
 141     FadingCounter theSessionFailures;
 142     const char *isSuspended; // also stores suspension reason for debugging
 143
 144     bool notifying; // may be true in any state except for the initial
 145     bool updateScheduled; // time-based options update has been scheduled
 146
 147 private:
 148     ICAP::Method parseMethod(const char *) const;
 149     ICAP::VectPoint parseVectPoint(const char *) const;
 150
 151     void suspend(const char *reason);
 152
 153     bool hasOptions() const;
 154     bool needNewOptions() const;
 155     time_t optionsFetchTime() const;
 156
 157     void scheduleUpdate(time_t when);
 158     void scheduleNotification();
 159
 160     void startGettingOptions();
 161     void handleNewOptions(Options *newOptions);
 162     void changeOptions(Options *newOptions);
 163     void checkOptions();
 164
 165     void announceStatusChange(const char *downPhrase, bool important) const;
 166
 167     /// Set the maximum allowed connections for the service
 168     void setMaxConnections();
 169     /// The number of connections which excess the Max-Connections limit
 170     int excessConnections() const;
 171     /**
 172      * The available connections slots to the ICAP server
 173      \return the available slots, or -1 if there is no limit on allowed connections
 174      */
 175     int availableConnections() const;
 176     /**
 177      * If there are xactions waiting for the service to be available, notify
 178      * as many xactions as the available connections slots.
 179      */
 180     void busyCheckpoint();
 181
 182     const char *status() const;
 183
 184     mutable bool wasAnnouncedUp; // prevent sequential same-state announcements
 185     bool isDetached;
 186 };
 187
 188 class ModXact;
 189 /// Custom dialer to call Service::noteNewWaiter and noteGoneWaiter
 190 /// to maintain Service idea of waiting and being-notified transactions.
 191 class ConnWaiterDialer: public NullaryMemFunT<ModXact>
 192 {
 193 public:
 194     typedef NullaryMemFunT<ModXact> Parent;
 195     ServiceRep::Pointer theService;
 196     ConnWaiterDialer(const CbcPointer<Adaptation::Icap::ModXact> &xact, Adaptation::Icap::ConnWaiterDialer::Parent::Method aHandler);
 197     ConnWaiterDialer(const Adaptation::Icap::ConnWaiterDialer &aConnWaiter);
 198     ~ConnWaiterDialer();
 199 };
 200
 201 } // namespace Icap
 202 } // namespace Adaptation
 203
 204 #endif /* SQUID_ICAPSERVICEREP_H */
 205