2 * Copyright (C) 1996-2016 The Squid Software Foundation and contributors
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.
9 #ifndef SQUID_ICAPSERVICEREP_H
10 #define SQUID_ICAPSERVICEREP_H
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"
19 #include "FadingCounter.h"
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. */
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".
42 * The number of failures required to bring an up service down is determined
43 * by icap_service_failure_limit in squid.conf.
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.
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.
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.
59 class ServiceRep
: public RefCountable
, public Adaptation::Service
,
60 public Adaptation::Initiator
62 CBDATA_CLASS(ServiceRep
);
65 typedef RefCount
<ServiceRep
> Pointer
;
68 explicit ServiceRep(const ServiceConfigPointer
&aConfig
);
69 virtual ~ServiceRep();
71 virtual void finalize();
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
78 virtual Initiate
*makeXactLauncher(HttpMsg
*virginHeader
, HttpRequest
*virginCause
, AccessLogEntry::Pointer
&alp
);
80 void callWhenAvailable(AsyncCall::Pointer
&cb
, bool priority
= false);
81 void callWhenReady(AsyncCall::Pointer
&cb
);
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
);
93 void noteFailure(); // called by transactions to report service failure
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
99 //AsyncJob virtual methods
100 virtual bool doneAll() const { return Adaptation::Initiator::doneAll() && false;}
101 virtual void callException(const std::exception
&e
);
103 virtual void detach();
104 virtual bool detached() const;
106 public: // treat these as private, they are for callbacks only
107 void noteTimeToUpdate();
108 void noteTimeToNotify();
110 // receive either an ICAP OPTIONS response header or an abort message
111 virtual void noteAdaptationAnswer(const Answer
&answer
);
113 Security::ContextPtr sslContext
;
114 Security::SessionStatePointer sslSession
;
117 // stores Prepare() callback info
120 Pointer service
; // one for each client to preserve service
121 AsyncCall::Pointer callback
;
124 typedef std::vector
<Client
> Clients
;
125 // TODO: rename to theUpWaiters
126 Clients theClients
; // all clients waiting for a call back
129 CbcPointer
<Adaptation::Initiate
> theOptionsFetcher
; // pending ICAP OPTIONS transaction
130 time_t theLastUpdate
; // time the options were last updated
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
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
144 FadingCounter theSessionFailures
;
145 const char *isSuspended
; // also stores suspension reason for debugging
147 bool notifying
; // may be true in any state except for the initial
148 bool updateScheduled
; // time-based options update has been scheduled
151 ICAP::Method
parseMethod(const char *) const;
152 ICAP::VectPoint
parseVectPoint(const char *) const;
154 void suspend(const char *reason
);
156 bool hasOptions() const;
157 bool needNewOptions() const;
158 time_t optionsFetchTime() const;
160 void scheduleUpdate(time_t when
);
161 void scheduleNotification();
163 void startGettingOptions();
164 void handleNewOptions(Options
*newOptions
);
165 void changeOptions(Options
*newOptions
);
168 void announceStatusChange(const char *downPhrase
, bool important
) const;
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;
175 * The available connections slots to the ICAP server
176 \return the available slots, or -1 if there is no limit on allowed connections
178 int availableConnections() const;
180 * If there are xactions waiting for the service to be available, notify
181 * as many xactions as the available connections slots.
183 void busyCheckpoint();
185 const char *status() const;
187 mutable bool wasAnnouncedUp
; // prevent sequential same-state announcements
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
>
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
);
205 } // namespace Adaptation
207 #endif /* SQUID_ICAPSERVICEREP_H */