src/adaptation/icap/ModXact.h

   1 /*
   2  * Copyright (C) 1996-2018 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_ICAPMODXACT_H
  10 #define SQUID_ICAPMODXACT_H
  11
  12 #include "AccessLogEntry.h"
  13 #include "adaptation/icap/InOut.h"
  14 #include "adaptation/icap/Launcher.h"
  15 #include "adaptation/icap/Xaction.h"
  16 #include "BodyPipe.h"
  17 #include "http/one/forward.h"
  18
  19 /*
  20  * ICAPModXact implements ICAP REQMOD and RESPMOD transaction using
  21  * ICAPXaction as the base. The ICAPModXact receives a virgin HTTP message
  22  * from an ICAP vecoring point, (a.k.a., initiator), communicates with the
  23  * ICAP server, and sends the adapted HTTP message headers back.
  24  * Virgin/adapted HTTP message body is reveived/sent using BodyPipe
  25  * interface. The initiator (or its associate) is expected to send and/or
  26  * receive the HTTP body.
  27  */
  28
  29 namespace Adaptation
  30 {
  31 namespace Icap
  32 {
  33
  34 // estimated future presence and size of something (e.g., HTTP body)
  35
  36 class SizedEstimate
  37 {
  38
  39 public:
  40     SizedEstimate(); // not expected by default
  41     void expect(int64_t aSize); // expect with any, even unknown size
  42     bool expected() const;
  43
  44     /* other members can be accessed iff expected() */
  45
  46     bool knownSize() const;
  47     uint64_t size() const; // can be accessed iff knownSize()
  48
  49 private:
  50     enum { dtUnexpected = -2, dtUnknown = -1 };
  51     int64_t theData; // combines expectation and size info to save RAM
  52 };
  53
  54 // Virgin body may be used for two activities: (a) writing preview or prime
  55 // body to the ICAP server and (b) sending the body back in the echo mode.
  56 // Both activities use the same BodyPipe and may be active at the same time.
  57 // This class is used to maintain the state of body writing or sending
  58 // activity and to coordinate consumption of the shared virgin body buffer.
  59 class VirginBodyAct
  60 {
  61
  62 public:
  63     VirginBodyAct();
  64
  65     void plan(); // the activity may happen; do not consume at or above offset
  66     void disable(); // the activity wont continue; no consumption restrictions
  67
  68     bool active() const { return theState == stActive; }
  69     bool disabled() const { return theState == stDisabled; }
  70
  71     // methods below require active()
  72
  73     uint64_t offset() const; // the absolute beginning of not-yet-acted-on data
  74     void progress(size_t size); // note processed body bytes
  75
  76 private:
  77     int64_t theStart; // unprocessed virgin body data offset
  78
  79     typedef enum { stUndecided, stActive, stDisabled } State;
  80     State theState;
  81 };
  82
  83 // maintains preview-related sizes
  84
  85 class Preview
  86 {
  87
  88 public:
  89     Preview();            // disabled
  90     void enable(size_t anAd); // enabled with advertised size
  91     bool enabled() const;
  92
  93     /* other members can be accessed iff enabled() */
  94
  95     size_t ad() const;      // advertised preview size
  96     size_t debt() const;    // remains to write
  97     bool done() const;      // wrote everything
  98     bool ieof() const;      // premature EOF
  99
 100     void wrote(size_t size, bool wroteEof);
 101
 102 private:
 103     size_t theWritten;
 104     size_t theAd;
 105     enum State { stDisabled, stWriting, stIeof, stDone } theState;
 106 };
 107
 108 /// Parses and stores ICAP trailer header block.
 109 class TrailerParser
 110 {
 111 public:
 112     TrailerParser() : trailer(hoReply), hdr_sz(0) {}
 113     /// Parses trailers stored in a buffer.
 114     /// \returns true and sets hdr_sz on success
 115     /// \returns false and sets *error to zero when needs more data
 116     /// \returns false and sets *error to a positive Http::StatusCode on error
 117     bool parse(const char *buf, int len, int atEnd, Http::StatusCode *error);
 118     HttpHeader trailer;
 119     /// parsed trailer size if parse() was successful
 120     size_t hdr_sz; // pedantic XXX: wrong type dictated by HttpHeader::parse() API
 121 };
 122
 123 class ModXact: public Xaction, public BodyProducer, public BodyConsumer
 124 {
 125     CBDATA_CLASS(ModXact);
 126
 127 public:
 128     ModXact(Http::Message *virginHeader, HttpRequest *virginCause, AccessLogEntry::Pointer &alp, ServiceRep::Pointer &s);
 129     virtual ~ModXact();
 130
 131     // BodyProducer methods
 132     virtual void noteMoreBodySpaceAvailable(BodyPipe::Pointer);
 133     virtual void noteBodyConsumerAborted(BodyPipe::Pointer);
 134
 135     // BodyConsumer methods
 136     virtual void noteMoreBodyDataAvailable(BodyPipe::Pointer);
 137     virtual void noteBodyProductionEnded(BodyPipe::Pointer);
 138     virtual void noteBodyProducerAborted(BodyPipe::Pointer);
 139
 140     // comm handlers
 141     virtual void handleCommConnected();
 142     virtual void handleCommWrote(size_t size);
 143     virtual void handleCommRead(size_t size);
 144     void handleCommWroteHeaders();
 145     void handleCommWroteBody();
 146
 147     // service waiting
 148     void noteServiceReady();
 149     void noteServiceAvailable();
 150
 151 public:
 152     InOut virgin;
 153     InOut adapted;
 154
 155     // bypasses exceptions if needed and possible
 156     virtual void callException(const std::exception &e);
 157
 158     /// record error detail in the virgin request if possible
 159     virtual void detailError(int errDetail);
 160     // Icap::Xaction API
 161     virtual void clearError();
 162     /// The master transaction log entry
 163     virtual AccessLogEntry::Pointer masterLogEntry() { return alMaster; }
 164
 165 private:
 166     virtual void start();
 167
 168     /// locates the request, either as a cause or as a virgin message itself
 169     const HttpRequest &virginRequest() const; // Must always be available
 170
 171     void estimateVirginBody();
 172     void makeAdaptedBodyPipe(const char *what);
 173
 174     void waitForService();
 175
 176     // will not send anything [else] on the adapted pipe
 177     bool doneSending() const;
 178
 179     void startWriting();
 180     void writeMore();
 181     void writePreviewBody();
 182     void writePrimeBody();
 183     void writeSomeBody(const char *label, size_t size);
 184     void decideWritingAfterPreview(const char *previewKind);
 185
 186     void startReading();
 187     void readMore();
 188     virtual bool doneReading() const { return commEof || state.doneParsing(); }
 189     virtual bool doneWriting() const { return state.doneWriting(); }
 190
 191     size_t virginContentSize(const VirginBodyAct &act) const;
 192     const char *virginContentData(const VirginBodyAct &act) const;
 193     bool virginBodyEndReached(const VirginBodyAct &act) const;
 194
 195     void makeRequestHeaders(MemBuf &buf);
 196     void makeAllowHeader(MemBuf &buf);
 197     void makeUsernameHeader(const HttpRequest *request, MemBuf &buf);
 198     void addLastRequestChunk(MemBuf &buf);
 199     void openChunk(MemBuf &buf, size_t chunkSize, bool ieof);
 200     void closeChunk(MemBuf &buf);
 201     void virginConsume();
 202     void finishNullOrEmptyBodyPreview(MemBuf &buf);
 203
 204     void decideOnPreview();
 205     void decideOnRetries();
 206     bool shouldAllow204();
 207     bool shouldAllow206any();
 208     bool shouldAllow206in();
 209     bool shouldAllow206out();
 210     bool canBackupEverything() const;
 211
 212     void prepBackup(size_t expectedSize);
 213     void backup(const MemBuf &buf);
 214
 215     void parseMore();
 216
 217     void parseHeaders();
 218     void parseIcapHead();
 219     void parseHttpHead();
 220     bool parseHead(Http::Message *head);
 221
 222     void decideOnParsingBody();
 223     void parseBody();
 224     void parseIcapTrailer();
 225     void maybeAllocateHttpMsg();
 226
 227     void handle100Continue();
 228     bool validate200Ok();
 229     void handle200Ok();
 230     void handle204NoContent();
 231     void handle206PartialContent();
 232     void handleUnknownScode();
 233
 234     void bypassFailure();
 235
 236     void startSending();
 237     void disableBypass(const char *reason, bool includeGroupBypass);
 238
 239     void prepEchoing();
 240     void prepPartialBodyEchoing(uint64_t pos);
 241     void echoMore();
 242     void updateSources(); ///< Update the Http::Message sources
 243
 244     virtual bool doneAll() const;
 245     virtual void swanSong();
 246
 247     void stopReceiving();
 248     void stopSending(bool nicely);
 249     void stopWriting(bool nicely);
 250     void stopParsing(const bool checkUnparsedData = true);
 251     void stopBackup();
 252
 253     virtual void fillPendingStatus(MemBuf &buf) const;
 254     virtual void fillDoneStatus(MemBuf &buf) const;
 255     virtual bool fillVirginHttpHeader(MemBuf&) const;
 256
 257 private:
 258     /// parses a message header or trailer
 259     /// \returns true on success
 260     /// \returns false if more data is needed
 261     /// \throw TextException on unrecoverable error
 262     template<class Part>
 263     bool parsePart(Part *part, const char *description);
 264
 265     void packHead(MemBuf &httpBuf, const Http::Message *head);
 266     void encapsulateHead(MemBuf &icapBuf, const char *section, MemBuf &httpBuf, const Http::Message *head);
 267     bool gotEncapsulated(const char *section) const;
 268     /// whether ICAP response header indicates HTTP header presence
 269     bool expectHttpHeader() const;
 270     /// whether ICAP response header indicates HTTP body presence
 271     bool expectHttpBody() const;
 272     /// whether ICAP response header indicates ICAP trailers presence
 273     bool expectIcapTrailers() const;
 274     void checkConsuming();
 275
 276     virtual void finalizeLogInfo();
 277
 278     SizedEstimate virginBody;
 279     VirginBodyAct virginBodyWriting; // virgin body writing state
 280     VirginBodyAct virginBodySending;  // virgin body sending state
 281     uint64_t virginConsumed;        // virgin data consumed so far
 282     Preview preview; // use for creating (writing) the preview
 283
 284     Http1::TeChunkedParser *bodyParser; // ICAP response body parser
 285
 286     bool canStartBypass; // enables bypass of transaction failures
 287     bool protectGroupBypass; // protects ServiceGroup-wide bypass of failures
 288
 289     /**
 290      * size of HTTP header in ICAP reply or -1 if there is not any encapsulated
 291      * message data
 292      */
 293     int64_t replyHttpHeaderSize;
 294     /**
 295      * size of dechunked HTTP body in ICAP reply or -1 if there is not any
 296      * encapsulated message data
 297      */
 298     int64_t replyHttpBodySize;
 299
 300     int adaptHistoryId; ///< adaptation history slot reservation
 301
 302     TrailerParser *trailerParser;
 303
 304     class State
 305     {
 306
 307     public:
 308         State();
 309
 310     public:
 311
 312         bool serviceWaiting; // waiting for ICAP service options
 313         bool allowedPostview204; // mmust handle 204 No Content outside preview
 314         bool allowedPostview206; // must handle 206 Partial Content outside preview
 315         bool allowedPreview206; // must handle 206 Partial Content inside preview
 316         bool readyForUob; ///< got a 206 response and expect a use-origin-body
 317         bool waitedForService; ///< true if was queued at least once
 318
 319         // will not write anything [else] to the ICAP server connection
 320         bool doneWriting() const { return writing == writingReallyDone; }
 321
 322         // will not use virgin.body_pipe
 323         bool doneConsumingVirgin() const {
 324             return writing >= writingAlmostDone
 325                    && ((sending == sendingAdapted && !readyForUob) ||
 326                        sending == sendingDone);
 327         }
 328
 329         // parsed entire ICAP response from the ICAP server
 330         bool doneParsing() const { return parsing == psDone; }
 331
 332         // is parsing ICAP or HTTP headers read from the ICAP server
 333         bool parsingHeaders() const {
 334             return parsing == psIcapHeader ||
 335                    parsing == psHttpHeader;
 336         }
 337
 338         enum Parsing { psIcapHeader, psHttpHeader, psBody, psIcapTrailer, psDone } parsing;
 339
 340         // measures ICAP request writing progress
 341         enum Writing { writingInit, writingConnect, writingHeaders,
 342                        writingPreview, writingPaused, writingPrime,
 343                        writingAlmostDone, // waiting for the last write() call to finish
 344                        writingReallyDone
 345                      } writing;
 346
 347         enum Sending { sendingUndecided, sendingVirgin, sendingAdapted,
 348                        sendingDone
 349                      } sending;
 350     } state;
 351
 352     AccessLogEntry::Pointer alMaster; ///< Master transaction AccessLogEntry
 353 };
 354
 355 // An Launcher that stores ModXact construction info and
 356 // creates ModXact when needed
 357 class ModXactLauncher: public Launcher
 358 {
 359     CBDATA_CLASS(ModXactLauncher);
 360
 361 public:
 362     ModXactLauncher(Http::Message *virginHeader, HttpRequest *virginCause, AccessLogEntry::Pointer &alp, Adaptation::ServicePointer s);
 363
 364 protected:
 365     virtual Xaction *createXaction();
 366
 367     virtual void swanSong();
 368
 369     /// starts or stops transaction accounting in ICAP history
 370     void updateHistory(bool start);
 371
 372     InOut virgin;
 373
 374     AccessLogEntry::Pointer al;
 375 };
 376
 377 } // namespace Icap
 378 } // namespace Adaptation
 379
 380 #endif /* SQUID_ICAPMOD_XACT_H */
 381