HTTPCodec.h

Go to the documentation of this file.

/*
 *  Copyright (c) 2015-present, Facebook, Inc.
 *  All rights reserved.
 *
 *  This source code is licensed under the BSD-style license found in the
 *  LICENSE file in the root directory of this source tree. An additional grant
 *  of patent rights can be found in the PATENTS file in the same directory.
 *
 */
#pragma once

#include <folly/Portability.h>
#include <folly/io/IOBufQueue.h>
#include <proxygen/lib/http/HTTPException.h>
#include <proxygen/lib/http/HTTPHeaderSize.h>
#include <proxygen/lib/http/codec/CodecProtocol.h>
#include <proxygen/lib/http/codec/ErrorCode.h>
#include <proxygen/lib/http/codec/HTTPSettings.h>
#include <proxygen/lib/http/codec/TransportDirection.h>
#include <proxygen/lib/http/codec/compress/HeaderCodec.h>
#include <proxygen/lib/http/codec/compress/HPACKCodec.h>

namespace proxygen {

class HTTPHeaders;
class HTTPMessage;
class HTTPTransactionHandler;
class HTTPErrorPage;

class HTTPCodec {
 public:

  using StreamID = uint64_t;

  static const folly::Optional<StreamID> NoStream;

  static const folly::Optional<uint8_t> NoPadding;

  static const StreamID MAX_STREAM_ID = 1u << 31;

  struct ExAttributes {
    ExAttributes() {}
    ExAttributes(StreamID controlStreamId, bool isUnidirectional)
      : controlStream(controlStreamId), unidirectional(isUnidirectional) {}

    StreamID controlStream;
    bool unidirectional;
  };

  static const folly::Optional<ExAttributes> NoExAttributes;

  class PriorityQueue {
   public:
    virtual ~PriorityQueue() {}

    virtual void addPriorityNode(StreamID id, StreamID parent) = 0;
  };

  class Callback {
   public:
    virtual void onMessageBegin(StreamID stream, HTTPMessage* msg) = 0;

    virtual void onPushMessageBegin(StreamID /* stream */,
                                    StreamID /* assocStream */,
                                    HTTPMessage* /* msg */) {}

    virtual void onExMessageBegin(StreamID /* stream */,
                                  StreamID /* controlStream */,
                                  bool /* unidirectional */,
                                  HTTPMessage* /* msg */) {}

    virtual void onHeadersComplete(StreamID stream,
                                   std::unique_ptr<HTTPMessage> msg) = 0;

    virtual void onBody(StreamID stream,
                        std::unique_ptr<folly::IOBuf> chain,
                        uint16_t padding) = 0;

    virtual void onChunkHeader(StreamID /* stream */, size_t /* length */) {}

    virtual void onChunkComplete(StreamID /* stream */) {}

    virtual void onTrailersComplete(StreamID stream,
                                    std::unique_ptr<HTTPHeaders> trailers) = 0;

    virtual void onMessageComplete(StreamID stream, bool upgrade) = 0;

    virtual void onError(StreamID stream,
                         const HTTPException& error,
                         bool newTxn = false) = 0;

    virtual void onAbort(
        StreamID /* stream */,
        ErrorCode /* code */) {}

    virtual void onFrameHeader(
        StreamID /* stream_id */,
        uint8_t /* flags */,
        uint64_t /* length */,
        uint8_t /* type */,
        uint16_t /* version */ = 0) {}

    virtual void onGoaway(
        uint64_t /* lastGoodStreamID */,
        ErrorCode /* code */,
        std::unique_ptr<folly::IOBuf> /* debugData */ = nullptr) {}

    virtual void onPingRequest(uint64_t /* uniqueID */) {}

    virtual void onPingReply(uint64_t /* uniqueID */) {}

    virtual void onWindowUpdate(StreamID /* stream */, uint32_t /* amount */) {}

    virtual void onSettings(const SettingsList& /* settings */) {}

    virtual void onSettingsAck() {}

    virtual void onPriority(
        StreamID /* stream */,
        const HTTPMessage::HTTPPriority& /* pri */) {}

    virtual bool onNativeProtocolUpgrade(
        StreamID /* stream */,
        CodecProtocol /* protocol */,
        const std::string& /* protocolString */,
        HTTPMessage& /* msg */) {
      return false;
    }

    virtual void onGenerateFrameHeader(
        StreamID /* stream_id */,
        uint8_t /* type */,
        uint64_t /* length */,
        uint16_t /* version */ = 0) {}

    virtual void onCertificateRequest(
        uint16_t /* requestId */,
        std::unique_ptr<folly::IOBuf> /* authRequest */) {
    }

    virtual void onCertificate(
        uint16_t /* certId */,
        std::unique_ptr<folly::IOBuf> /* authenticator */) {
    }

    virtual uint32_t numOutgoingStreams() const { return 0; }

    virtual uint32_t numIncomingStreams() const { return 0; }

    virtual ~Callback() {}
  };

  virtual ~HTTPCodec() {}

  virtual HPACKTableInfo getHPACKTableInfo() const {
    HPACKTableInfo defaultHPACKTableInfo;
    return defaultHPACKTableInfo;
  }

  virtual CodecProtocol getProtocol() const = 0;

  virtual const std::string& getUserAgent() const = 0;

  virtual TransportDirection getTransportDirection() const = 0;

  virtual bool supportsStreamFlowControl() const {
    return false;
  }

  virtual bool supportsSessionFlowControl() const {
    return false;
  }

  virtual StreamID createStream() = 0;

  virtual void setCallback(Callback* callback) = 0;

  virtual bool isBusy() const = 0;

  virtual void setParserPaused(bool paused) = 0;

  virtual size_t onIngress(const folly::IOBuf& buf) = 0;

  virtual void onIngressEOF() = 0;

  virtual bool onIngressUpgradeMessage(const HTTPMessage& /* msg */) {
    return true;
  }

  virtual bool isReusable() const = 0;

  virtual bool isWaitingToDrain() const = 0;

  virtual bool closeOnEgressComplete() const = 0;

  virtual bool supportsParallelRequests() const = 0;

  virtual bool supportsPushTransactions() const = 0;

  virtual bool supportsExTransactions() const {
    return false;
  }

  virtual size_t generateConnectionPreface(folly::IOBufQueue& /* writeBuf */) {
    return 0;
  }

  virtual void generateHeader(folly::IOBufQueue& writeBuf,
                              StreamID stream,
                              const HTTPMessage& msg,
                              bool eom = false,
                              HTTPHeaderSize* size = nullptr) = 0;

  virtual void generatePushPromise(folly::IOBufQueue& /* writeBuf */,
                                   StreamID /* stream */,
                                   const HTTPMessage& /* msg */,
                                   StreamID /* assocStream */,
                                   bool /* eom = false */,
                                   HTTPHeaderSize* /* size = nullptr */) {}

  virtual void generateExHeader(folly::IOBufQueue& /* writeBuf */,
                                StreamID /* stream */,
                                const HTTPMessage& /* msg */,
                                const HTTPCodec::ExAttributes& /*exAttributes*/,
                                bool /* eom = false */,
                                HTTPHeaderSize* /* size = nullptr */) {}

  virtual size_t generateBody(folly::IOBufQueue& writeBuf,
                              StreamID stream,
                              std::unique_ptr<folly::IOBuf> chain,
                              folly::Optional<uint8_t> padding,
                              bool eom) = 0;

  virtual size_t generateChunkHeader(folly::IOBufQueue& writeBuf,
                                     StreamID stream,
                                     size_t length) = 0;

  virtual size_t generateChunkTerminator(folly::IOBufQueue& writeBuf,
                                         StreamID stream) = 0;

  virtual size_t generateTrailers(folly::IOBufQueue& writeBuf,
                                  StreamID stream,
                                  const HTTPHeaders& trailers) = 0;

  virtual size_t generateEOM(folly::IOBufQueue& writeBuf,
                             StreamID stream) = 0;

  virtual size_t generateRstStream(folly::IOBufQueue& writeBuf,
                                   StreamID stream,
                                   ErrorCode code) = 0;

  virtual size_t generateGoaway(
    folly::IOBufQueue& writeBuf,
    StreamID lastStream,
    ErrorCode code,
    std::unique_ptr<folly::IOBuf> debugData = nullptr) = 0;

  virtual size_t generatePingRequest(folly::IOBufQueue& /* writeBuf */) {
    return 0;
  }

  virtual size_t generatePingReply(
      folly::IOBufQueue& /* writeBuf */,
      uint64_t /* uniqueID */) { return 0; }

  virtual size_t generateSettings(folly::IOBufQueue& /* writeBuf */) {
    return 0;
  }

  virtual size_t generateSettingsAck(folly::IOBufQueue& /* writeBuf */) {
    return 0;
  }

  /*
   * Generate a WINDOW_UPDATE message, if supported. The delta is the amount
   * of ingress bytes we processed and freed from the current receive window.
   * Returns the number of bytes written on the wire as a result of invoking
   * this function.
   */
  virtual size_t generateWindowUpdate(
      folly::IOBufQueue& /* writeBuf */,
      StreamID /* stream */,
      uint32_t /* delta */) {
    return 0;
  }

  /*
   * Generate a PRIORITY message, if supported
   */
  virtual size_t generatePriority(
      folly::IOBufQueue& /* writeBuf */,
      StreamID /* stream */,
      const HTTPMessage::HTTPPriority& /* pri */) {
    return 0;
  }

  /*
   * Generate a CERTIFICATE_REQUEST message, if supported in the protocol
   * implemented by the codec.
   */
  virtual size_t generateCertificateRequest(
      folly::IOBufQueue& /* writeBuf */,
      uint16_t /* requestId */,
      std::unique_ptr<folly::IOBuf> /* chain */) {
    return 0;
  }

  /*
   * Generate a CERTIFICATE message, if supported in the protocol
   * implemented by the codec.
   */
  virtual size_t generateCertificate(
      folly::IOBufQueue& /* writeBuf */,
      uint16_t /* certId */,
      std::unique_ptr<folly::IOBuf> /* certData */) {
    return 0;
  }

  /*
   * The below interfaces need only be implemented if the codec supports
   * settings
   */
  virtual HTTPSettings* getEgressSettings() {
    return nullptr;
  }

  virtual const HTTPSettings* getIngressSettings() const {
    return nullptr;
  }

  virtual void enableDoubleGoawayDrain() {}

  virtual void setHeaderCodecStats(HeaderCodec::Stats* /* stats */) {}

  virtual StreamID getLastIncomingStreamID() const { return 0; }

  virtual uint32_t getDefaultWindowSize() const { return 0; }

  virtual size_t addPriorityNodes(
      PriorityQueue& /* queue */,
      folly::IOBufQueue& /* writeBuf */,
      uint8_t /* maxLevel */) {
    return 0;
  }

  virtual StreamID mapPriorityToDependency(uint8_t /* priority */) const {
    return 0;
  }

  virtual int8_t mapDependencyToPriority(StreamID /* parent */) const {
    return -1;
  }
};

}