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 "adaptation/Service.h"
  39 #include "adaptation/forward.h"
  40 #include "adaptation/Initiator.h"
  41 #include "adaptation/icap/Elements.h"
  42
  43
  44 namespace Adaptation {
  45 namespace Icap {
  46
  47 class Options;
  48 class OptXact;
  49
  50 /* The ICAP service representative maintains information about a single ICAP
  51    service that Squid communicates with. The representative initiates OPTIONS
  52    requests to the service to keep cached options fresh. One ICAP server may
  53    host many ICAP services. */
  54
  55 /*
  56  * A service with a fresh cached OPTIONS response and without many failures
  57  * is an "up" service. All other services are "down". A service is "probed"
  58  * if we tried to get an OPTIONS response from it and succeeded or failed.
  59  * A probed down service is called "broken".
  60  *
  61  * The number of failures required to bring an up service down is determined
  62  * by icap_service_failure_limit in squid.conf.
  63  *
  64  * As a bootstrapping mechanism, ICAP transactions wait for an unprobed
  65  * service to get a fresh OPTIONS response (see the callWhenReady method).
  66  * The waiting callback is called when the OPTIONS transaction completes,
  67  * even if the service is now broken.
  68  *
  69  * We do not initiate ICAP transactions with a broken service, but will
  70  * eventually retry to fetch its options in hope to bring the service up.
  71  *
  72  * A service that should no longer be used after Squid reconfiguration is
  73  * treated as if it does not have a fresh cached OPTIONS response. We do
  74  * not try to fetch fresh options for such a service. It should be
  75  * auto-destroyed by refcounting when no longer used.
  76  */
  77
  78
  79 class ServiceRep : public RefCountable, public Adaptation::Service,
  80             public Adaptation::Initiator
  81 {
  82
  83 public:
  84     typedef RefCount<ServiceRep> Pointer;
  85
  86 public:
  87     ServiceRep(const Adaptation::ServiceConfig &config);
  88     virtual ~ServiceRep();
  89
  90     void setSelf(Pointer &aSelf); // needs self pointer for OptXact
  91     virtual void finalize();
  92
  93     void invalidate(); // call when the service is no longer needed or valid
  94
  95     bool probed() const; // see comments above
  96     bool up() const; // see comments above
  97
  98     virtual Adaptation::Initiate *makeXactLauncher(Adaptation::Initiator *, 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
 107     void noteFailure(); // called by transactions to report service failure
 108
 109     //AsyncJob virtual methods
 110     virtual bool doneAll() const { return Adaptation::Initiator::doneAll() && false;}
 111
 112 public: // treat these as private, they are for callbacks only
 113     void noteTimeToUpdate();
 114     void noteTimeToNotify();
 115
 116     // receive either an ICAP OPTIONS response header or an abort message
 117     virtual void noteAdaptationAnswer(HttpMsg *msg);
 118     virtual void noteAdaptationQueryAbort(bool);
 119
 120 private:
 121     // stores Prepare() callback info
 122
 123     struct Client {
 124         Pointer service; // one for each client to preserve service
 125         AsyncCall::Pointer callback;
 126     };
 127
 128     typedef Vector<Client> Clients;
 129     Clients theClients; // all clients waiting for a call back
 130
 131     Options *theOptions;
 132     Adaptation::Initiate *theOptionsFetcher; // pending ICAP OPTIONS transaction
 133     time_t theLastUpdate; // time the options were last updated
 134
 135     static const int TheSessionFailureLimit;
 136     int theSessionFailures;
 137     const char *isSuspended; // also stores suspension reason for debugging
 138
 139     bool notifying; // may be true in any state except for the initial
 140     bool updateScheduled; // time-based options update has been scheduled
 141
 142 private:
 143     ICAP::Method parseMethod(const char *) const;
 144     ICAP::VectPoint parseVectPoint(const char *) const;
 145
 146     void suspend(const char *reason);
 147
 148     bool hasOptions() const;
 149     bool needNewOptions() const;
 150     time_t optionsFetchTime() const;
 151
 152     void scheduleUpdate(time_t when);
 153     void scheduleNotification();
 154
 155     void startGettingOptions();
 156     void handleNewOptions(Options *newOptions);
 157     void changeOptions(Options *newOptions);
 158     void checkOptions();
 159
 160     void announceStatusChange(const char *downPhrase, bool important) const;
 161
 162     const char *status() const;
 163
 164     Pointer self;
 165     mutable bool wasAnnouncedUp; // prevent sequential same-state announcements
 166     CBDATA_CLASS2(ServiceRep);
 167 };
 168
 169
 170 } // namespace Icap
 171 } // namespace Adaptation
 172
 173 #endif /* SQUID_ICAPSERVICEREP_H */