src/adaptation/icap/Xaction.h

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