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