src/adaptation/icap/ServiceRep.h

   1 /*
   2  * Copyright (C) 1996-2017 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 SBuf &urlPath) const;
  85     bool wantsPreview(const SBuf &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     Security::ContextPointer sslContext;
 114     Security::SessionStatePointer sslSession;
 115
 116 private:
 117     // stores Prepare() callback info
 118
 119     struct Client {
 120         Pointer service; // one for each client to preserve service
 121         AsyncCall::Pointer callback;
 122     };
 123
 124     typedef std::vector<Client> Clients;
 125     // TODO: rename to theUpWaiters
 126     Clients theClients; // all clients waiting for a call back
 127
 128     Options *theOptions;
 129     CbcPointer<Adaptation::Initiate> theOptionsFetcher; // pending ICAP OPTIONS transaction
 130     time_t theLastUpdate; // time the options were last updated
 131
 132     /// FIFO queue of xactions waiting for a connection slot and not yet notified
 133     /// about it; xaction is removed when notification is scheduled
 134     std::deque<Client> theNotificationWaiters;
 135     int theBusyConns;   ///< number of connections given to active transactions
 136     /// number of xactions waiting for a connection slot (notified and not)
 137     /// the number is decreased after the xaction receives notification
 138     int theAllWaiters;
 139     int theMaxConnections; ///< the maximum allowed connections to the service
 140     // TODO: use a better type like the FadingCounter for connOverloadReported
 141     mutable bool connOverloadReported; ///< whether we reported exceeding theMaxConnections
 142     IdleConnList *theIdleConns; ///< idle persistent connection pool
 143
 144     FadingCounter theSessionFailures;
 145     const char *isSuspended; // also stores suspension reason for debugging
 146
 147     bool notifying; // may be true in any state except for the initial
 148     bool updateScheduled; // time-based options update has been scheduled
 149
 150 private:
 151     ICAP::Method parseMethod(const char *) const;
 152     ICAP::VectPoint parseVectPoint(const char *) const;
 153
 154     void suspend(const char *reason);
 155
 156     bool hasOptions() const;
 157     bool needNewOptions() const;
 158     time_t optionsFetchTime() const;
 159
 160     void scheduleUpdate(time_t when);
 161     void scheduleNotification();
 162
 163     void startGettingOptions();
 164     void handleNewOptions(Options *newOptions);
 165     void changeOptions(Options *newOptions);
 166     void checkOptions();
 167
 168     void announceStatusChange(const char *downPhrase, bool important) const;
 169
 170     /// Set the maximum allowed connections for the service
 171     void setMaxConnections();
 172     /// The number of connections which excess the Max-Connections limit
 173     int excessConnections() const;
 174     /**
 175      * The available connections slots to the ICAP server
 176      \return the available slots, or -1 if there is no limit on allowed connections
 177      */
 178     int availableConnections() const;
 179     /**
 180      * If there are xactions waiting for the service to be available, notify
 181      * as many xactions as the available connections slots.
 182      */
 183     void busyCheckpoint();
 184
 185     const char *status() const;
 186
 187     mutable bool wasAnnouncedUp; // prevent sequential same-state announcements
 188     bool isDetached;
 189 };
 190
 191 class ModXact;
 192 /// Custom dialer to call Service::noteNewWaiter and noteGoneWaiter
 193 /// to maintain Service idea of waiting and being-notified transactions.
 194 class ConnWaiterDialer: public NullaryMemFunT<ModXact>
 195 {
 196 public:
 197     typedef NullaryMemFunT<ModXact> Parent;
 198     ServiceRep::Pointer theService;
 199     ConnWaiterDialer(const CbcPointer<Adaptation::Icap::ModXact> &xact, Adaptation::Icap::ConnWaiterDialer::Parent::Method aHandler);
 200     ConnWaiterDialer(const Adaptation::Icap::ConnWaiterDialer &aConnWaiter);
 201     ~ConnWaiterDialer();
 202 };
 203
 204 } // namespace Icap
 205 } // namespace Adaptation
 206
 207 #endif /* SQUID_ICAPSERVICEREP_H */
 208