ServiceRep.h
Go to the documentation of this file.
1/*
2 * Copyright (C) 1996-2023 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"
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
23namespace Adaptation
24{
25namespace Icap
26{
27
28class Options;
29class 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
64public:
66
67public:
68 explicit ServiceRep(const ServiceConfigPointer &aConfig);
69 ~ServiceRep() override;
70
71 void finalize() override;
72
73 bool probed() const override; // see comments above
74 bool up() const override; // see comments above
75 bool availableForNew() const;
76 bool availableForOld() const;
77
78 Initiate *makeXactLauncher(Http::Message *virginHeader, HttpRequest *virginCause, AccessLogEntry::Pointer &alp) override;
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 override;
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() override; // called by transactions to report service failure
95
97 void noteGoneWaiter();
98 bool existWaiters() const {return (theAllWaiters > 0);}
99
100 //AsyncJob virtual methods
101 bool doneAll() const override { return Adaptation::Initiator::doneAll() && false;}
102 void callException(const std::exception &e) override;
103
104 void detach() override;
105 bool detached() const override;
106
107public: // 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 void noteAdaptationAnswer(const Answer &answer) override;
113
116
117private:
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;
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
151private:
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);
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 override;
187
188 mutable bool wasAnnouncedUp; // prevent sequential same-state announcements
190};
191
192class ModXact;
195class ConnWaiterDialer: public NullaryMemFunT<ModXact>
196{
197public:
202 ~ConnWaiterDialer() override;
203};
204
205} // namespace Icap
206} // namespace Adaptation
207
208#endif /* SQUID_ICAPSERVICEREP_H */
209
#define RefCountable
The locking interface for use on Reference-Counted classes.
Definition: Lock.h:66
int conn
the current server connection FD
Definition: Transport.cc:26
summarizes adaptation service answer for the noteAdaptationAnswer() API
Definition: Answer.h:23
ServiceRep::Pointer theService
Definition: ServiceRep.h:199
NullaryMemFunT< ModXact > Parent
Definition: ServiceRep.h:198
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 noteFailure() override
Definition: ServiceRep.cc:94
int theMaxConnections
the maximum allowed connections to the service
Definition: ServiceRep.h:140
void noteAdaptationAnswer(const Answer &answer) override
Definition: ServiceRep.cc:536
bool availableForOld() const
a transaction notified about connection slot availability may start communicating with the service
Definition: ServiceRep.cc:315
void noteConnectionUse(const Comm::ConnectionPointer &conn)
Definition: ServiceRep.cc:171
Security::SessionStatePointer sslSession
Definition: ServiceRep.h:115
void suspend(const char *reason)
Definition: ServiceRep.cc:278
void noteNewWaiter()
New xaction waiting for service to be up or available.
Definition: ServiceRep.h:96
time_t optionsFetchTime() const
Definition: ServiceRep.cc:646
Security::ContextPointer sslContext
Definition: ServiceRep.h:114
void changeOptions(Options *newOptions)
Definition: ServiceRep.cc:453
IdleConnList * theIdleConns
idle persistent connection pool
Definition: ServiceRep.h:143
std::vector< Client > Clients
Definition: ServiceRep.h:125
void callException(const std::exception &e) override
called when the job throws during an async call
Definition: ServiceRep.cc:566
ICAP::VectPoint parseVectPoint(const char *) const
bool up() const override
Definition: ServiceRep.cc:300
ServiceRep(const ServiceConfigPointer &aConfig)
Definition: ServiceRep.cc:33
void callWhenAvailable(AsyncCall::Pointer &cb, bool priority=false)
Definition: ServiceRep.cc:401
bool detached() const override
whether detached() was called
Definition: ServiceRep.cc:724
bool wantsUrl(const SBuf &urlPath) const override
Definition: ServiceRep.cc:323
RefCount< ServiceRep > Pointer
Definition: ServiceRep.h:65
bool existWaiters() const
if there are xactions waiting for the service to be available
Definition: ServiceRep.h:98
FadingCounter theSessionFailures
Definition: ServiceRep.h:145
bool doneAll() const override
whether positive goal has been reached
Definition: ServiceRep.h:101
const char * status() const override
internal cleanup; do not call directly
Definition: ServiceRep.cc:677
ICAP::Method parseMethod(const char *) const
void setMaxConnections()
Set the maximum allowed connections for the service.
Definition: ServiceRep.cc:183
void callWhenReady(AsyncCall::Pointer &cb)
Definition: ServiceRep.cc:419
void announceStatusChange(const char *downPhrase, bool important) const
Definition: ServiceRep.cc:521
void noteGoneWaiter()
An xaction is not waiting any more for service to be available.
Definition: ServiceRep.cc:237
bool probed() const override
Definition: ServiceRep.cc:290
Initiate * makeXactLauncher(Http::Message *virginHeader, HttpRequest *virginCause, AccessLogEntry::Pointer &alp) override
Definition: ServiceRep.cc:670
bool wantsPreview(const SBuf &urlPath, size_t &wantedSize) const
Definition: ServiceRep.cc:329
Comm::ConnectionPointer getIdleConnection(bool isRetriable)
Definition: ServiceRep.cc:117
bool connOverloadReported
whether we reported exceeding theMaxConnections
Definition: ServiceRep.h:142
std::deque< Client > theNotificationWaiters
Definition: ServiceRep.h:135
bool availableForNew() const
a new transaction may start communicating with the service
Definition: ServiceRep.cc:305
void handleNewOptions(Options *newOptions)
Definition: ServiceRep.cc:574
void noteConnectionFailed(const char *comment)
Definition: ServiceRep.cc:177
void putConnection(const Comm::ConnectionPointer &conn, bool isReusable, bool sendReset, const char *comment)
Definition: ServiceRep.cc:146
void finalize() override
Definition: ServiceRep.cc:59
int excessConnections() const
The number of connections which excess the Max-Connections limit.
Definition: ServiceRep.cc:222
CbcPointer< Adaptation::Initiate > theOptionsFetcher
Definition: ServiceRep.h:130
virtual bool doneAll() const
whether positive goal has been reached
Definition: AsyncJob.cc:112
Counts events, forgetting old ones. Useful for "3 errors/minute" limits.
Definition: FadingCounter.h:16
common parts of HttpRequest and HttpReply
Definition: Message.h:26
Definition: SBuf.h:94
std::vector< const Option * > Options
Definition: Options.h:214
std::shared_ptr< SSL_CTX > ContextPointer
Definition: Context.h:29
std::unique_ptr< SSL_SESSION, HardFun< void, SSL_SESSION *, &SSL_SESSION_free > > SessionStatePointer
Definition: Session.h:51

 

Introduction

Documentation

Support

Miscellaneous

Web Site Translations

Mirrors