HTTP2Framer.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 <cstdint>
#include <deque>
#include <folly/Optional.h>
#include <folly/Range.h>
#include <folly/io/Cursor.h>
#include <proxygen/lib/http/codec/ErrorCode.h>
#include <proxygen/lib/http/codec/HTTPCodec.h>
#include <proxygen/lib/http/codec/SettingsId.h>
#include <proxygen/lib/utils/Export.h>
#include <string.h>

#include <proxygen/lib/http/codec/HTTP2Constants.h>

namespace proxygen { namespace http2 {


extern const uint8_t kMinExperimentalFrameType;
using Padding = folly::Optional<uint8_t>;
extern const Padding kNoPadding;


enum class FrameType : uint8_t {
  DATA = 0,
  HEADERS = 1,
  PRIORITY = 2,
  RST_STREAM = 3,
  SETTINGS = 4,
  PUSH_PROMISE = 5,
  PING = 6,
  GOAWAY = 7,
  WINDOW_UPDATE = 8,
  CONTINUATION = 9,
  ALTSVC = 10, // not in current draft so frame type has not been assigned

  // experimental use
  EX_HEADERS = 0xfb,

  // For secondary certificate authentication in HTTP/2 as specified in the
  // draft-ietf-httpbis-http2-secondary-certs-02.
  CERTIFICATE_REQUEST = 0xf0,
  CERTIFICATE = 0xf1,
  CERTIFICATE_NEEDED = 0xf2,
  USE_CERTIFICATE = 0xf3,
};

enum Flags {
  ACK = 0x1,
  END_STREAM = 0x1,
  END_HEADERS = 0x4,
  PADDED = 0x8,
  PRIORITY = 0x20,
  // experimental flag for EX stream only
  UNIDIRECTIONAL = 0x40,

  // for secondary certificate authentication frames
  UNSOLICITED = 0x1,
  TO_BE_CONTINUED = 0x1,
};

struct FrameHeader {
  uint32_t length; // only 24 valid bits
  uint32_t stream;
  FrameType type;
  uint8_t flags;
  uint16_t unused;
};

static_assert(sizeof(FrameHeader) == 12, "The maths are not working");

struct PriorityUpdate {
  uint32_t streamDependency;
  bool exclusive;
  uint8_t weight;
};


FB_EXPORT extern const PriorityUpdate DefaultPriority;


bool isValidFrameType(FrameType t);

bool frameAffectsCompression(FrameType t);

bool frameHasPadding(const FrameHeader& header);


ErrorCode
parseFrameHeader(folly::io::Cursor& cursor,
                 FrameHeader& header) noexcept;

ErrorCode
parseData(folly::io::Cursor& cursor,
          const FrameHeader& header,
          std::unique_ptr<folly::IOBuf>& outBuf,
          uint16_t& padding) noexcept;

ErrorCode
parseDataBegin(folly::io::Cursor& cursor,
               const FrameHeader& header,
               size_t& parsed,
               uint16_t& outPadding) noexcept;

ErrorCode
parseDataEnd(folly::io::Cursor& cursor,
             const size_t bufLen,
             const size_t pendingDataFramePaddingBytes,
             size_t& toSkip) noexcept;

ErrorCode
parseHeaders(folly::io::Cursor& cursor,
             const FrameHeader& header,
             folly::Optional<PriorityUpdate>& outPriority,
             std::unique_ptr<folly::IOBuf>& outBuf) noexcept;

ErrorCode
parseExHeaders(folly::io::Cursor& cursor,
               const FrameHeader& header,
               HTTPCodec::ExAttributes& outExAttributes,
               folly::Optional<PriorityUpdate>& outPriority,
               std::unique_ptr<folly::IOBuf>& outBuf) noexcept;

ErrorCode
parsePriority(folly::io::Cursor& cursor,
              const FrameHeader& header,
              PriorityUpdate& outPriority) noexcept;

ErrorCode
parseRstStream(folly::io::Cursor& cursor,
               const FrameHeader& header,
               ErrorCode& outCode) noexcept;

ErrorCode
parseSettings(folly::io::Cursor& cursor,
              const FrameHeader& header,
              std::deque<SettingPair>& settings) noexcept;

ErrorCode
parsePushPromise(folly::io::Cursor& cursor,
                 const FrameHeader& header,
                 uint32_t& outPromisedStream,
                 std::unique_ptr<folly::IOBuf>& outBuf) noexcept;

ErrorCode
parsePing(folly::io::Cursor& cursor,
          const FrameHeader& header,
          uint64_t& outData) noexcept;

ErrorCode
parseGoaway(folly::io::Cursor& cursor,
            const FrameHeader& header,
            uint32_t& outLastStreamID,
            ErrorCode& outCode,
            std::unique_ptr<folly::IOBuf>& outDebugData) noexcept;

ErrorCode
parseWindowUpdate(folly::io::Cursor& cursor,
                  const FrameHeader& header,
                  uint32_t& outAmount) noexcept;

ErrorCode
parseContinuation(folly::io::Cursor& cursor,
                  const FrameHeader& header,
                  std::unique_ptr<folly::IOBuf>& outBuf) noexcept;

ErrorCode
parseAltSvc(folly::io::Cursor& cursor,
            const FrameHeader& header,
            uint32_t& outMaxAge,
            uint32_t& outPort,
            std::string& outProtocol,
            std::string& outHost,
            std::string& outOrigin) noexcept;

ErrorCode parseCertificateRequest(
    folly::io::Cursor& cursor,
    const FrameHeader& header,
    uint16_t& outRequestId,
    std::unique_ptr<folly::IOBuf>& outAuthRequest) noexcept;

ErrorCode
parseCertificate(
    folly::io::Cursor& cursor,
    const FrameHeader& header,
    uint16_t& outCertId,
    std::unique_ptr<folly::IOBuf>& outAuthenticator) noexcept;


size_t
writeData(folly::IOBufQueue& writeBuf,
          std::unique_ptr<folly::IOBuf> data,
          uint32_t stream,
          folly::Optional<uint8_t> padding,
          bool endStream,
          bool reuseIOBufHeadroom) noexcept;

size_t
writeHeaders(folly::IOBufQueue& writeBuf,
             std::unique_ptr<folly::IOBuf> headers,
             uint32_t stream,
             folly::Optional<PriorityUpdate> priority,
             folly::Optional<uint8_t> padding,
             bool endStream,
             bool endHeaders) noexcept;

size_t
writeExHeaders(folly::IOBufQueue& writeBuf,
               std::unique_ptr<folly::IOBuf> headers,
               uint32_t stream,
               const HTTPCodec::ExAttributes& exAttributes,
               const folly::Optional<PriorityUpdate>& priority,
               const folly::Optional<uint8_t>& padding,
               bool endStream,
               bool endHeaders) noexcept;

size_t
writePriority(folly::IOBufQueue& writeBuf,
              uint32_t stream,
              PriorityUpdate priority) noexcept;

size_t
writeRstStream(folly::IOBufQueue& writeBuf,
               uint32_t stream,
               ErrorCode errorCode) noexcept;

size_t
writeSettings(folly::IOBufQueue& writeBuf,
              const std::deque<SettingPair>& settings);

size_t
writeSettingsAck(folly::IOBufQueue& writeBuf);

size_t
writePushPromise(folly::IOBufQueue& writeBuf,
                 uint32_t associatedStream,
                 uint32_t promisedStream,
                 std::unique_ptr<folly::IOBuf> headers,
                 folly::Optional<uint8_t> padding,
                 bool endHeaders) noexcept;
size_t
writePing(folly::IOBufQueue& writeBuf,
          uint64_t data,
          bool ack) noexcept;

size_t
writeGoaway(folly::IOBufQueue& writeBuf,
            uint32_t lastStreamID,
            ErrorCode errorCode,
            std::unique_ptr<folly::IOBuf> debugData = nullptr) noexcept;

size_t
writeWindowUpdate(folly::IOBufQueue& writeBuf,
                  uint32_t stream,
                  uint32_t amount) noexcept;

size_t
writeContinuation(folly::IOBufQueue& queue,
                  uint32_t stream,
                  bool endHeaders,
                  std::unique_ptr<folly::IOBuf> headers) noexcept;
size_t
writeAltSvc(folly::IOBufQueue& writeBuf,
            uint32_t stream,
            uint32_t maxAge,
            uint16_t port,
            folly::StringPiece protocol,
            folly::StringPiece host,
            folly::StringPiece origin) noexcept;

size_t
writeCertificateRequest(folly::IOBufQueue& writeBuf,
                        uint16_t requestId,
                        std::unique_ptr<folly::IOBuf> authRequest);

size_t writeCertificate(folly::IOBufQueue& writeBuf,
                        uint16_t certId,
                        std::unique_ptr<folly::IOBuf> authenticator,
                        bool toBeContinued);

const char* getFrameTypeString(FrameType type);
}}