src/adaptation/icap/Xaction.h

   1 /*
   2  * Copyright (C) 1996-2021 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_ICAPXACTION_H
  10 #define SQUID_ICAPXACTION_H
  11
  12 #include "AccessLogEntry.h"
  13 #include "adaptation/icap/ServiceRep.h"
  14 #include "adaptation/Initiate.h"
  15 #include "comm/ConnOpener.h"
  16 #include "error/forward.h"
  17 #include "HttpReply.h"
  18 #include "ipcache.h"
  19 #include "sbuf/SBuf.h"
  20
  21 class MemBuf;
  22
  23 namespace Adaptation
  24 {
  25 namespace Icap
  26 {
  27
  28 /*
  29  * The ICAP Xaction implements common tasks for ICAP OPTIONS, REQMOD, and
  30  * RESPMOD transactions. It is started by an Initiator. It terminates
  31  * on its own, when done. Transactions communicate with Initiator using
  32  * asynchronous messages because a transaction or Initiator may be gone at
  33  * any time.
  34  */
  35
  36 // Note: Xaction must be the first parent for object-unaware cbdata to work
  37
  38 class Xaction: public Adaptation::Initiate
  39 {
  40
  41 public:
  42     Xaction(const char *aTypeName, ServiceRep::Pointer &aService);
  43     virtual ~Xaction();
  44
  45     void disableRetries();
  46     void disableRepeats(const char *reason);
  47     bool retriable() const { return isRetriable; }
  48     bool repeatable() const { return isRepeatable; }
  49
  50     // comm handler wrappers, treat as private
  51     void noteCommConnected(const CommConnectCbParams &io);
  52     void noteCommWrote(const CommIoCbParams &io);
  53     void noteCommRead(const CommIoCbParams &io);
  54     void noteCommTimedout(const CommTimeoutCbParams &io);
  55     void noteCommClosed(const CommCloseCbParams &io);
  56
  57     // TODO: create these only when actually sending/receiving
  58     HttpRequest *icapRequest; ///< sent (or at least created) ICAP request
  59     HttpReply::Pointer icapReply; ///< received ICAP reply, if any
  60
  61     /// the number of times we tried to get to the service, including this time
  62     int attempts;
  63
  64 protected:
  65     virtual void start();
  66     virtual void noteInitiatorAborted(); // TODO: move to Adaptation::Initiate
  67
  68     // comm hanndlers; called by comm handler wrappers
  69     virtual void handleCommConnected() = 0;
  70     virtual void handleCommWrote(size_t sz) = 0;
  71     virtual void handleCommRead(size_t sz) = 0;
  72     virtual void handleCommTimedout();
  73     virtual void handleCommClosed();
  74
  75     void handleSecuredPeer(Security::EncryptorAnswer &answer);
  76     /// record error detail if possible
  77     virtual void detailError(const ErrorDetailPointer &) {}
  78
  79     void openConnection();
  80     void closeConnection();
  81     void dieOnConnectionFailure();
  82     bool haveConnection() const;
  83
  84     void scheduleRead();
  85     void scheduleWrite(MemBuf &buf);
  86     void updateTimeout();
  87
  88     void cancelRead();
  89
  90     bool parseHttpMsg(Http::Message *msg); // true=success; false=needMore; throw=err
  91     bool mayReadMore() const;
  92
  93     virtual bool doneReading() const;
  94     virtual bool doneWriting() const;
  95     bool doneWithIo() const;
  96     virtual bool doneAll() const;
  97
  98     // called just before the 'done' transaction is deleted
  99     virtual void swanSong();
 100
 101     // returns a temporary string depicting transaction status, for debugging
 102     virtual const char *status() const;
 103     virtual void fillPendingStatus(MemBuf &buf) const;
 104     virtual void fillDoneStatus(MemBuf &buf) const;
 105
 106     // useful for debugging
 107     virtual bool fillVirginHttpHeader(MemBuf&) const;
 108
 109 public:
 110     // custom exception handling and end-of-call checks
 111     virtual void callException(const std::exception  &e);
 112     virtual void callEnd();
 113     /// clear stored error details, if any; used for retries/repeats
 114     virtual void clearError() {}
 115     virtual AccessLogEntry::Pointer masterLogEntry();
 116     void dnsLookupDone(const ipcache_addrs *ia);
 117
 118 protected:
 119     // logging
 120     void setOutcome(const XactOutcome &xo);
 121     virtual void finalizeLogInfo();
 122
 123 public:
 124     ServiceRep &service();
 125
 126 private:
 127     void tellQueryAborted();
 128     void maybeLog();
 129
 130 protected:
 131     Comm::ConnectionPointer connection;     ///< ICAP server connection
 132     Adaptation::Icap::ServiceRep::Pointer theService;
 133
 134     SBuf readBuf;
 135     bool commEof;
 136     bool reuseConnection;
 137     bool isRetriable;  ///< can retry on persistent connection failures
 138     bool isRepeatable; ///< can repeat if no or unsatisfactory response
 139     bool ignoreLastWrite;
 140
 141     const char *stopReason;
 142
 143     // active (pending) comm callbacks for the ICAP server connection
 144     AsyncCall::Pointer connector;
 145     AsyncCall::Pointer reader;
 146     AsyncCall::Pointer writer;
 147     AsyncCall::Pointer closer;
 148
 149     AccessLogEntry::Pointer alep; ///< icap.log entry
 150     AccessLogEntry &al; ///< short for *alep
 151
 152     timeval icap_tr_start;     /*time when the ICAP transaction was created */
 153     timeval icap_tio_start;    /*time when the first ICAP request byte was scheduled for sending*/
 154     timeval icap_tio_finish;   /*time when the last byte of the ICAP responsewas received*/
 155
 156 private:
 157     Comm::ConnOpener::Pointer cs;
 158     AsyncCall::Pointer securer; ///< whether we are securing a connection
 159 };
 160
 161 } // namespace Icap
 162 } // namespace Adaptation
 163
 164 #endif /* SQUID_ICAPXACTION_H */
 165