src/adaptation/icap/ServiceRep.h

   1
   2 /*
   3  * $Id$
   4  *
   5  *
   6  * SQUID Web Proxy Cache          http://www.squid-cache.org/
   7  * ----------------------------------------------------------
   8  *
   9  *  Squid is the result of efforts by numerous individuals from
  10  *  the Internet community; see the CONTRIBUTORS file for full
  11  *  details.   Many organizations have provided support for Squid's
  12  *  development; see the SPONSORS file for full details.  Squid is
  13  *  Copyrighted (C) 2001 by the Regents of the University of
  14  *  California; see the COPYRIGHT file for full details.  Squid
  15  *  incorporates software developed and/or copyrighted by other
  16  *  sources; see the CREDITS file for full details.
  17  *
  18  *  This program is free software; you can redistribute it and/or modify
  19  *  it under the terms of the GNU General Public License as published by
  20  *  the Free Software Foundation; either version 2 of the License, or
  21  *  (at your option) any later version.
  22  *
  23  *  This program is distributed in the hope that it will be useful,
  24  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  25  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  26  *  GNU General Public License for more details.
  27  *
  28  *  You should have received a copy of the GNU General Public License
  29  *  along with this program; if not, write to the Free Software
  30  *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, USA.
  31  *
  32  */
  33
  34 #ifndef SQUID_ICAPSERVICEREP_H
  35 #define SQUID_ICAPSERVICEREP_H
  36
  37 #include "cbdata.h"
  38 #include "FadingCounter.h"
  39 #include "adaptation/Service.h"
  40 #include "adaptation/forward.h"
  41 #include "adaptation/Initiator.h"
  42 #include "adaptation/icap/Elements.h"
  43
  44
  45 namespace Adaptation
  46 {
  47 namespace Icap
  48 {
  49
  50 class Options;
  51 class OptXact;
  52
  53 /* The ICAP service representative maintains information about a single ICAP
  54    service that Squid communicates with. The representative initiates OPTIONS
  55    requests to the service to keep cached options fresh. One ICAP server may
  56    host many ICAP services. */
  57
  58 /*
  59  * A service with a fresh cached OPTIONS response and without many failures
  60  * is an "up" service. All other services are "down". A service is "probed"
  61  * if we tried to get an OPTIONS response from it and succeeded or failed.
  62  * A probed down service is called "broken".
  63  *
  64  * The number of failures required to bring an up service down is determined
  65  * by icap_service_failure_limit in squid.conf.
  66  *
  67  * As a bootstrapping mechanism, ICAP transactions wait for an unprobed
  68  * service to get a fresh OPTIONS response (see the callWhenReady method).
  69  * The waiting callback is called when the OPTIONS transaction completes,
  70  * even if the service is now broken.
  71  *
  72  * We do not initiate ICAP transactions with a broken service, but will
  73  * eventually retry to fetch its options in hope to bring the service up.
  74  *
  75  * A service that should no longer be used after Squid reconfiguration is
  76  * treated as if it does not have a fresh cached OPTIONS response. We do
  77  * not try to fetch fresh options for such a service. It should be
  78  * auto-destroyed by refcounting when no longer used.
  79  */
  80
  81
  82 class ServiceRep : public RefCountable, public Adaptation::Service,
  83         public Adaptation::Initiator
  84 {
  85
  86 public:
  87     typedef RefCount<ServiceRep> Pointer;
  88
  89 public:
  90     ServiceRep(ServiceConfigPointer aConfig);
  91     virtual ~ServiceRep();
  92
  93     virtual void finalize();
  94
  95     virtual bool probed() const; // see comments above
  96     virtual bool up() const; // see comments above
  97
  98     virtual Initiate *makeXactLauncher(HttpMsg *virginHeader, HttpRequest *virginCause);
  99
 100     void callWhenReady(AsyncCall::Pointer &cb);
 101
 102     // the methods below can only be called on an up() service
 103     bool wantsUrl(const String &urlPath) const;
 104     bool wantsPreview(const String &urlPath, size_t &wantedSize) const;
 105     bool allows204() const;
 106     bool allows206() const;
 107
 108     void noteFailure(); // called by transactions to report service failure
 109
 110     //AsyncJob virtual methods
 111     virtual bool doneAll() const { return Adaptation::Initiator::doneAll() && false;}
 112     virtual void callException(const std::exception &e);
 113
 114     virtual void detach();
 115     virtual bool detached() const;
 116
 117 public: // treat these as private, they are for callbacks only
 118     void noteTimeToUpdate();
 119     void noteTimeToNotify();
 120
 121     // receive either an ICAP OPTIONS response header or an abort message
 122     virtual void noteAdaptationAnswer(const Answer &answer);
 123
 124 private:
 125     // stores Prepare() callback info
 126
 127     struct Client {
 128         Pointer service; // one for each client to preserve service
 129         AsyncCall::Pointer callback;
 130     };
 131
 132     typedef Vector<Client> Clients;
 133     Clients theClients; // all clients waiting for a call back
 134
 135     Options *theOptions;
 136     CbcPointer<Adaptation::Initiate> theOptionsFetcher; // pending ICAP OPTIONS transaction
 137     time_t theLastUpdate; // time the options were last updated
 138
 139     FadingCounter theSessionFailures;
 140     const char *isSuspended; // also stores suspension reason for debugging
 141
 142     bool notifying; // may be true in any state except for the initial
 143     bool updateScheduled; // time-based options update has been scheduled
 144
 145 private:
 146     ICAP::Method parseMethod(const char *) const;
 147     ICAP::VectPoint parseVectPoint(const char *) const;
 148
 149     void suspend(const char *reason);
 150
 151     bool hasOptions() const;
 152     bool needNewOptions() const;
 153     time_t optionsFetchTime() const;
 154
 155     void scheduleUpdate(time_t when);
 156     void scheduleNotification();
 157
 158     void startGettingOptions();
 159     void handleNewOptions(Options *newOptions);
 160     void changeOptions(Options *newOptions);
 161     void checkOptions();
 162
 163     void announceStatusChange(const char *downPhrase, bool important) const;
 164
 165     const char *status() const;
 166
 167     mutable bool wasAnnouncedUp; // prevent sequential same-state announcements
 168     bool isDetached;
 169     CBDATA_CLASS2(ServiceRep);
 170 };
 171
 172
 173 } // namespace Icap
 174 } // namespace Adaptation
 175
 176 #endif /* SQUID_ICAPSERVICEREP_H */