ServiceRep.h
Go to the documentation of this file.
1 /*
2  * Copyright (C) 1996-2022 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"
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 
61 {
63 
64 public:
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;
76  bool availableForOld() const;
77 
78  virtual Initiate *makeXactLauncher(Http::Message *virginHeader, HttpRequest *virginCause, AccessLogEntry::Pointer &alp);
79 
80  void callWhenAvailable(AsyncCall::Pointer &cb, bool priority = false);
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;
90  void putConnection(const Comm::ConnectionPointer &conn, bool isReusable, bool sendReset, const char *comment);
92  void noteConnectionFailed(const char *comment);
93 
94  void noteFailure(); // called by transactions to report service failure
95 
97  void noteGoneWaiter();
98  bool existWaiters() const {return (theAllWaiters > 0);}
99 
100  //AsyncJob virtual methods
101  virtual bool doneAll() const { return Adaptation::Initiator::doneAll() && false;}
102  virtual void callException(const std::exception &e);
103 
104  virtual void detach();
105  virtual bool detached() const;
106 
107 public: // treat these as private, they are for callbacks only
108  void noteTimeToUpdate();
109  void noteTimeToNotify();
110 
111  // receive either an ICAP OPTIONS response header or an abort message
112  virtual void noteAdaptationAnswer(const Answer &answer);
113 
116 
117 private:
118  // stores Prepare() callback info
119 
120  struct Client {
121  Pointer service; // one for each client to preserve service
123  };
124 
125  typedef std::vector<Client> Clients;
126  // TODO: rename to theUpWaiters
127  Clients theClients; // all clients waiting for a call back
128 
130  CbcPointer<Adaptation::Initiate> theOptionsFetcher; // pending ICAP OPTIONS transaction
131  time_t theLastUpdate; // time the options were last updated
132 
135  std::deque<Client> theNotificationWaiters;
137  int theAllWaiters;
141  // TODO: use a better type like the FadingCounter for connOverloadReported
142  mutable bool connOverloadReported;
144 
146  const char *isSuspended; // also stores suspension reason for debugging
147 
148  bool notifying; // may be true in any state except for the initial
149  bool updateScheduled; // time-based options update has been scheduled
150 
151 private:
152  ICAP::Method parseMethod(const char *) const;
153  ICAP::VectPoint parseVectPoint(const char *) const;
154 
155  void suspend(const char *reason);
156 
157  bool hasOptions() const;
158  bool needNewOptions() const;
159  time_t optionsFetchTime() const;
160 
161  void scheduleUpdate(time_t when);
162  void scheduleNotification();
163 
164  void startGettingOptions();
165  void handleNewOptions(Options *newOptions);
166  void changeOptions(Options *newOptions);
167  void checkOptions();
168 
169  void announceStatusChange(const char *downPhrase, bool important) const;
170 
172  void setMaxConnections();
174  int excessConnections() const;
179  int availableConnections() const;
184  void busyCheckpoint();
185 
186  const char *status() const;
187 
188  mutable bool wasAnnouncedUp; // prevent sequential same-state announcements
190 };
191 
192 class ModXact;
195 class ConnWaiterDialer: public NullaryMemFunT<ModXact>
196 {
197 public:
203 };
204 
205 } // namespace Icap
206 } // namespace Adaptation
207 
208 #endif /* SQUID_ICAPSERVICEREP_H */
209 
virtual bool doneAll() const
whether positive goal has been reached
Definition: ServiceRep.h:101
std::vector< Client > Clients
Definition: ServiceRep.h:125
common parts of HttpRequest and HttpReply
Definition: Message.h:26
std::shared_ptr< SSL_CTX > ContextPointer
Definition: Context.h:29
void noteNewWaiter()
New xaction waiting for service to be up or available.
Definition: ServiceRep.h:96
std::vector< const Option * > Options
Definition: Options.h:214
virtual Initiate * makeXactLauncher(Http::Message *virginHeader, HttpRequest *virginCause, AccessLogEntry::Pointer &alp)
Definition: ServiceRep.cc:670
virtual bool up() const
Definition: ServiceRep.cc:300
void suspend(const char *reason)
Definition: ServiceRep.cc:278
bool connOverloadReported
whether we reported exceeding theMaxConnections
Definition: ServiceRep.h:142
Definition: SBuf.h:94
void callWhenAvailable(AsyncCall::Pointer &cb, bool priority=false)
Definition: ServiceRep.cc:401
ServiceRep(const ServiceConfigPointer &aConfig)
Definition: ServiceRep.cc:33
Security::SessionStatePointer sslSession
Definition: ServiceRep.h:115
ICAP::Method parseMethod(const char *) const
void noteConnectionFailed(const char *comment)
Definition: ServiceRep.cc:177
ICAP::VectPoint parseVectPoint(const char *) const
virtual void callException(const std::exception &e)
called when the job throws during an async call
Definition: ServiceRep.cc:566
ServiceRep::Pointer theService
Definition: ServiceRep.h:199
virtual void noteAdaptationAnswer(const Answer &answer)
Definition: ServiceRep.cc:536
bool availableForOld() const
a transaction notified about connection slot availability may start communicating with the service
Definition: ServiceRep.cc:315
virtual bool doneAll() const
whether positive goal has been reached
Definition: AsyncJob.cc:97
Comm::ConnectionPointer getIdleConnection(bool isRetriable)
Definition: ServiceRep.cc:117
ConnWaiterDialer(const CbcPointer< Adaptation::Icap::ModXact > &xact, Adaptation::Icap::ConnWaiterDialer::Parent::Method aHandler)
Definition: ServiceRep.cc:729
void scheduleUpdate(time_t when)
Definition: ServiceRep.cc:608
void putConnection(const Comm::ConnectionPointer &conn, bool isReusable, bool sendReset, const char *comment)
Definition: ServiceRep.cc:146
bool wantsUrl(const SBuf &urlPath) const
Definition: ServiceRep.cc:323
void noteConnectionUse(const Comm::ConnectionPointer &conn)
Definition: ServiceRep.cc:171
void callWhenReady(AsyncCall::Pointer &cb)
Definition: ServiceRep.cc:419
int conn
the current server connection FD
Definition: Transport.cc:26
Security::ContextPointer sslContext
Definition: ServiceRep.h:114
bool existWaiters() const
if there are xactions waiting for the service to be available
Definition: ServiceRep.h:98
void noteGoneWaiter()
An xaction is not waiting any more for service to be available.
Definition: ServiceRep.cc:237
std::deque< Client > theNotificationWaiters
Definition: ServiceRep.h:135
time_t optionsFetchTime() const
Definition: ServiceRep.cc:646
summarizes adaptation service answer for the noteAdaptationAnswer() API
Definition: Answer.h:23
const char * status() const
internal cleanup; do not call directly
Definition: ServiceRep.cc:677
bool wantsPreview(const SBuf &urlPath, size_t &wantedSize) const
Definition: ServiceRep.cc:329
IdleConnList * theIdleConns
idle persistent connection pool
Definition: ServiceRep.h:143
std::unique_ptr< SSL_SESSION, HardFun< void, SSL_SESSION *, &SSL_SESSION_free > > SessionStatePointer
Definition: Session.h:51
Counts events, forgetting old ones. Useful for "3 errors/minute" limits.
Definition: FadingCounter.h:16
virtual bool detached() const
whether detached() was called
Definition: ServiceRep.cc:724
RefCount< ServiceRep > Pointer
Definition: ServiceRep.h:65
FadingCounter theSessionFailures
Definition: ServiceRep.h:145
void changeOptions(Options *newOptions)
Definition: ServiceRep.cc:453
int theMaxConnections
the maximum allowed connections to the service
Definition: ServiceRep.h:140
bool availableForNew() const
a new transaction may start communicating with the service
Definition: ServiceRep.cc:305
void setMaxConnections()
Set the maximum allowed connections for the service.
Definition: ServiceRep.cc:183
virtual bool probed() const
Definition: ServiceRep.cc:290
NullaryMemFunT< ModXact > Parent
Definition: ServiceRep.h:198
CbcPointer< Adaptation::Initiate > theOptionsFetcher
Definition: ServiceRep.h:130
int excessConnections() const
The number of connections which excess the Max-Connections limit.
Definition: ServiceRep.cc:222
void handleNewOptions(Options *newOptions)
Definition: ServiceRep.cc:574
void announceStatusChange(const char *downPhrase, bool important) const
Definition: ServiceRep.cc:521

 

Introduction

Documentation

Support

Miscellaneous

Web Site Translations

Mirrors