cmd/bpa-operator/vendor/golang.org/x/net/http2/frame.go

   1 // Copyright 2014 The Go Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style
   3 // license that can be found in the LICENSE file.
   4
   5 package http2
   6
   7 import (
   8         "bytes"
   9         "encoding/binary"
  10         "errors"
  11         "fmt"
  12         "io"
  13         "log"
  14         "strings"
  15         "sync"
  16
  17         "golang.org/x/net/http/httpguts"
  18         "golang.org/x/net/http2/hpack"
  19 )
  20
  21 const frameHeaderLen = 9
  22
  23 var padZeros = make([]byte, 255) // zeros for padding
  24
  25 // A FrameType is a registered frame type as defined in
  26 // http://http2.github.io/http2-spec/#rfc.section.11.2
  27 type FrameType uint8
  28
  29 const (
  30         FrameData         FrameType = 0x0
  31         FrameHeaders      FrameType = 0x1
  32         FramePriority     FrameType = 0x2
  33         FrameRSTStream    FrameType = 0x3
  34         FrameSettings     FrameType = 0x4
  35         FramePushPromise  FrameType = 0x5
  36         FramePing         FrameType = 0x6
  37         FrameGoAway       FrameType = 0x7
  38         FrameWindowUpdate FrameType = 0x8
  39         FrameContinuation FrameType = 0x9
  40 )
  41
  42 var frameName = map[FrameType]string{
  43         FrameData:         "DATA",
  44         FrameHeaders:      "HEADERS",
  45         FramePriority:     "PRIORITY",
  46         FrameRSTStream:    "RST_STREAM",
  47         FrameSettings:     "SETTINGS",
  48         FramePushPromise:  "PUSH_PROMISE",
  49         FramePing:         "PING",
  50         FrameGoAway:       "GOAWAY",
  51         FrameWindowUpdate: "WINDOW_UPDATE",
  52         FrameContinuation: "CONTINUATION",
  53 }
  54
  55 func (t FrameType) String() string {
  56         if s, ok := frameName[t]; ok {
  57                 return s
  58         }
  59         return fmt.Sprintf("UNKNOWN_FRAME_TYPE_%d", uint8(t))
  60 }
  61
  62 // Flags is a bitmask of HTTP/2 flags.
  63 // The meaning of flags varies depending on the frame type.
  64 type Flags uint8
  65
  66 // Has reports whether f contains all (0 or more) flags in v.
  67 func (f Flags) Has(v Flags) bool {
  68         return (f & v) == v
  69 }
  70
  71 // Frame-specific FrameHeader flag bits.
  72 const (
  73         // Data Frame
  74         FlagDataEndStream Flags = 0x1
  75         FlagDataPadded    Flags = 0x8
  76
  77         // Headers Frame
  78         FlagHeadersEndStream  Flags = 0x1
  79         FlagHeadersEndHeaders Flags = 0x4
  80         FlagHeadersPadded     Flags = 0x8
  81         FlagHeadersPriority   Flags = 0x20
  82
  83         // Settings Frame
  84         FlagSettingsAck Flags = 0x1
  85
  86         // Ping Frame
  87         FlagPingAck Flags = 0x1
  88
  89         // Continuation Frame
  90         FlagContinuationEndHeaders Flags = 0x4
  91
  92         FlagPushPromiseEndHeaders Flags = 0x4
  93         FlagPushPromisePadded     Flags = 0x8
  94 )
  95
  96 var flagName = map[FrameType]map[Flags]string{
  97         FrameData: {
  98                 FlagDataEndStream: "END_STREAM",
  99                 FlagDataPadded:    "PADDED",
 100         },
 101         FrameHeaders: {
 102                 FlagHeadersEndStream:  "END_STREAM",
 103                 FlagHeadersEndHeaders: "END_HEADERS",
 104                 FlagHeadersPadded:     "PADDED",
 105                 FlagHeadersPriority:   "PRIORITY",
 106         },
 107         FrameSettings: {
 108                 FlagSettingsAck: "ACK",
 109         },
 110         FramePing: {
 111                 FlagPingAck: "ACK",
 112         },
 113         FrameContinuation: {
 114                 FlagContinuationEndHeaders: "END_HEADERS",
 115         },
 116         FramePushPromise: {
 117                 FlagPushPromiseEndHeaders: "END_HEADERS",
 118                 FlagPushPromisePadded:     "PADDED",
 119         },
 120 }
 121
 122 // a frameParser parses a frame given its FrameHeader and payload
 123 // bytes. The length of payload will always equal fh.Length (which
 124 // might be 0).
 125 type frameParser func(fc *frameCache, fh FrameHeader, payload []byte) (Frame, error)
 126
 127 var frameParsers = map[FrameType]frameParser{
 128         FrameData:         parseDataFrame,
 129         FrameHeaders:      parseHeadersFrame,
 130         FramePriority:     parsePriorityFrame,
 131         FrameRSTStream:    parseRSTStreamFrame,
 132         FrameSettings:     parseSettingsFrame,
 133         FramePushPromise:  parsePushPromise,
 134         FramePing:         parsePingFrame,
 135         FrameGoAway:       parseGoAwayFrame,
 136         FrameWindowUpdate: parseWindowUpdateFrame,
 137         FrameContinuation: parseContinuationFrame,
 138 }
 139
 140 func typeFrameParser(t FrameType) frameParser {
 141         if f := frameParsers[t]; f != nil {
 142                 return f
 143         }
 144         return parseUnknownFrame
 145 }
 146
 147 // A FrameHeader is the 9 byte header of all HTTP/2 frames.
 148 //
 149 // See http://http2.github.io/http2-spec/#FrameHeader
 150 type FrameHeader struct {
 151         valid bool // caller can access []byte fields in the Frame
 152
 153         // Type is the 1 byte frame type. There are ten standard frame
 154         // types, but extension frame types may be written by WriteRawFrame
 155         // and will be returned by ReadFrame (as UnknownFrame).
 156         Type FrameType
 157
 158         // Flags are the 1 byte of 8 potential bit flags per frame.
 159         // They are specific to the frame type.
 160         Flags Flags
 161
 162         // Length is the length of the frame, not including the 9 byte header.
 163         // The maximum size is one byte less than 16MB (uint24), but only
 164         // frames up to 16KB are allowed without peer agreement.
 165         Length uint32
 166
 167         // StreamID is which stream this frame is for. Certain frames
 168         // are not stream-specific, in which case this field is 0.
 169         StreamID uint32
 170 }
 171
 172 // Header returns h. It exists so FrameHeaders can be embedded in other
 173 // specific frame types and implement the Frame interface.
 174 func (h FrameHeader) Header() FrameHeader { return h }
 175
 176 func (h FrameHeader) String() string {
 177         var buf bytes.Buffer
 178         buf.WriteString("[FrameHeader ")
 179         h.writeDebug(&buf)
 180         buf.WriteByte(']')
 181         return buf.String()
 182 }
 183
 184 func (h FrameHeader) writeDebug(buf *bytes.Buffer) {
 185         buf.WriteString(h.Type.String())
 186         if h.Flags != 0 {
 187                 buf.WriteString(" flags=")
 188                 set := 0
 189                 for i := uint8(0); i < 8; i++ {
 190                         if h.Flags&(1<<i) == 0 {
 191                                 continue
 192                         }
 193                         set++
 194                         if set > 1 {
 195                                 buf.WriteByte('|')
 196                         }
 197                         name := flagName[h.Type][Flags(1<<i)]
 198                         if name != "" {
 199                                 buf.WriteString(name)
 200                         } else {
 201                                 fmt.Fprintf(buf, "0x%x", 1<<i)
 202                         }
 203                 }
 204         }
 205         if h.StreamID != 0 {
 206                 fmt.Fprintf(buf, " stream=%d", h.StreamID)
 207         }
 208         fmt.Fprintf(buf, " len=%d", h.Length)
 209 }
 210
 211 func (h *FrameHeader) checkValid() {
 212         if !h.valid {
 213                 panic("Frame accessor called on non-owned Frame")
 214         }
 215 }
 216
 217 func (h *FrameHeader) invalidate() { h.valid = false }
 218
 219 // frame header bytes.
 220 // Used only by ReadFrameHeader.
 221 var fhBytes = sync.Pool{
 222         New: func() interface{} {
 223                 buf := make([]byte, frameHeaderLen)
 224                 return &buf
 225         },
 226 }
 227
 228 // ReadFrameHeader reads 9 bytes from r and returns a FrameHeader.
 229 // Most users should use Framer.ReadFrame instead.
 230 func ReadFrameHeader(r io.Reader) (FrameHeader, error) {
 231         bufp := fhBytes.Get().(*[]byte)
 232         defer fhBytes.Put(bufp)
 233         return readFrameHeader(*bufp, r)
 234 }
 235
 236 func readFrameHeader(buf []byte, r io.Reader) (FrameHeader, error) {
 237         _, err := io.ReadFull(r, buf[:frameHeaderLen])
 238         if err != nil {
 239                 return FrameHeader{}, err
 240         }
 241         return FrameHeader{
 242                 Length:   (uint32(buf[0])<<16 | uint32(buf[1])<<8 | uint32(buf[2])),
 243                 Type:     FrameType(buf[3]),
 244                 Flags:    Flags(buf[4]),
 245                 StreamID: binary.BigEndian.Uint32(buf[5:]) & (1<<31 - 1),
 246                 valid:    true,
 247         }, nil
 248 }
 249
 250 // A Frame is the base interface implemented by all frame types.
 251 // Callers will generally type-assert the specific frame type:
 252 // *HeadersFrame, *SettingsFrame, *WindowUpdateFrame, etc.
 253 //
 254 // Frames are only valid until the next call to Framer.ReadFrame.
 255 type Frame interface {
 256         Header() FrameHeader
 257
 258         // invalidate is called by Framer.ReadFrame to make this
 259         // frame's buffers as being invalid, since the subsequent
 260         // frame will reuse them.
 261         invalidate()
 262 }
 263
 264 // A Framer reads and writes Frames.
 265 type Framer struct {
 266         r         io.Reader
 267         lastFrame Frame
 268         errDetail error
 269
 270         // lastHeaderStream is non-zero if the last frame was an
 271         // unfinished HEADERS/CONTINUATION.
 272         lastHeaderStream uint32
 273
 274         maxReadSize uint32
 275         headerBuf   [frameHeaderLen]byte
 276
 277         // TODO: let getReadBuf be configurable, and use a less memory-pinning
 278         // allocator in server.go to minimize memory pinned for many idle conns.
 279         // Will probably also need to make frame invalidation have a hook too.
 280         getReadBuf func(size uint32) []byte
 281         readBuf    []byte // cache for default getReadBuf
 282
 283         maxWriteSize uint32 // zero means unlimited; TODO: implement
 284
 285         w    io.Writer
 286         wbuf []byte
 287
 288         // AllowIllegalWrites permits the Framer's Write methods to
 289         // write frames that do not conform to the HTTP/2 spec. This
 290         // permits using the Framer to test other HTTP/2
 291         // implementations' conformance to the spec.
 292         // If false, the Write methods will prefer to return an error
 293         // rather than comply.
 294         AllowIllegalWrites bool
 295
 296         // AllowIllegalReads permits the Framer's ReadFrame method
 297         // to return non-compliant frames or frame orders.
 298         // This is for testing and permits using the Framer to test
 299         // other HTTP/2 implementations' conformance to the spec.
 300         // It is not compatible with ReadMetaHeaders.
 301         AllowIllegalReads bool
 302
 303         // ReadMetaHeaders if non-nil causes ReadFrame to merge
 304         // HEADERS and CONTINUATION frames together and return
 305         // MetaHeadersFrame instead.
 306         ReadMetaHeaders *hpack.Decoder
 307
 308         // MaxHeaderListSize is the http2 MAX_HEADER_LIST_SIZE.
 309         // It's used only if ReadMetaHeaders is set; 0 means a sane default
 310         // (currently 16MB)
 311         // If the limit is hit, MetaHeadersFrame.Truncated is set true.
 312         MaxHeaderListSize uint32
 313
 314         // TODO: track which type of frame & with which flags was sent
 315         // last. Then return an error (unless AllowIllegalWrites) if
 316         // we're in the middle of a header block and a
 317         // non-Continuation or Continuation on a different stream is
 318         // attempted to be written.
 319
 320         logReads, logWrites bool
 321
 322         debugFramer       *Framer // only use for logging written writes
 323         debugFramerBuf    *bytes.Buffer
 324         debugReadLoggerf  func(string, ...interface{})
 325         debugWriteLoggerf func(string, ...interface{})
 326
 327         frameCache *frameCache // nil if frames aren't reused (default)
 328 }
 329
 330 func (fr *Framer) maxHeaderListSize() uint32 {
 331         if fr.MaxHeaderListSize == 0 {
 332                 return 16 << 20 // sane default, per docs
 333         }
 334         return fr.MaxHeaderListSize
 335 }
 336
 337 func (f *Framer) startWrite(ftype FrameType, flags Flags, streamID uint32) {
 338         // Write the FrameHeader.
 339         f.wbuf = append(f.wbuf[:0],
 340                 0, // 3 bytes of length, filled in in endWrite
 341                 0,
 342                 0,
 343                 byte(ftype),
 344                 byte(flags),
 345                 byte(streamID>>24),
 346                 byte(streamID>>16),
 347                 byte(streamID>>8),
 348                 byte(streamID))
 349 }
 350
 351 func (f *Framer) endWrite() error {
 352         // Now that we know the final size, fill in the FrameHeader in
 353         // the space previously reserved for it. Abuse append.
 354         length := len(f.wbuf) - frameHeaderLen
 355         if length >= (1 << 24) {
 356                 return ErrFrameTooLarge
 357         }
 358         _ = append(f.wbuf[:0],
 359                 byte(length>>16),
 360                 byte(length>>8),
 361                 byte(length))
 362         if f.logWrites {
 363                 f.logWrite()
 364         }
 365
 366         n, err := f.w.Write(f.wbuf)
 367         if err == nil && n != len(f.wbuf) {
 368                 err = io.ErrShortWrite
 369         }
 370         return err
 371 }
 372
 373 func (f *Framer) logWrite() {
 374         if f.debugFramer == nil {
 375                 f.debugFramerBuf = new(bytes.Buffer)
 376                 f.debugFramer = NewFramer(nil, f.debugFramerBuf)
 377                 f.debugFramer.logReads = false // we log it ourselves, saying "wrote" below
 378                 // Let us read anything, even if we accidentally wrote it
 379                 // in the wrong order:
 380                 f.debugFramer.AllowIllegalReads = true
 381         }
 382         f.debugFramerBuf.Write(f.wbuf)
 383         fr, err := f.debugFramer.ReadFrame()
 384         if err != nil {
 385                 f.debugWriteLoggerf("http2: Framer %p: failed to decode just-written frame", f)
 386                 return
 387         }
 388         f.debugWriteLoggerf("http2: Framer %p: wrote %v", f, summarizeFrame(fr))
 389 }
 390
 391 func (f *Framer) writeByte(v byte)     { f.wbuf = append(f.wbuf, v) }
 392 func (f *Framer) writeBytes(v []byte)  { f.wbuf = append(f.wbuf, v...) }
 393 func (f *Framer) writeUint16(v uint16) { f.wbuf = append(f.wbuf, byte(v>>8), byte(v)) }
 394 func (f *Framer) writeUint32(v uint32) {
 395         f.wbuf = append(f.wbuf, byte(v>>24), byte(v>>16), byte(v>>8), byte(v))
 396 }
 397
 398 const (
 399         minMaxFrameSize = 1 << 14
 400         maxFrameSize    = 1<<24 - 1
 401 )
 402
 403 // SetReuseFrames allows the Framer to reuse Frames.
 404 // If called on a Framer, Frames returned by calls to ReadFrame are only
 405 // valid until the next call to ReadFrame.
 406 func (fr *Framer) SetReuseFrames() {
 407         if fr.frameCache != nil {
 408                 return
 409         }
 410         fr.frameCache = &frameCache{}
 411 }
 412
 413 type frameCache struct {
 414         dataFrame DataFrame
 415 }
 416
 417 func (fc *frameCache) getDataFrame() *DataFrame {
 418         if fc == nil {
 419                 return &DataFrame{}
 420         }
 421         return &fc.dataFrame
 422 }
 423
 424 // NewFramer returns a Framer that writes frames to w and reads them from r.
 425 func NewFramer(w io.Writer, r io.Reader) *Framer {
 426         fr := &Framer{
 427                 w:                 w,
 428                 r:                 r,
 429                 logReads:          logFrameReads,
 430                 logWrites:         logFrameWrites,
 431                 debugReadLoggerf:  log.Printf,
 432                 debugWriteLoggerf: log.Printf,
 433         }
 434         fr.getReadBuf = func(size uint32) []byte {
 435                 if cap(fr.readBuf) >= int(size) {
 436                         return fr.readBuf[:size]
 437                 }
 438                 fr.readBuf = make([]byte, size)
 439                 return fr.readBuf
 440         }
 441         fr.SetMaxReadFrameSize(maxFrameSize)
 442         return fr
 443 }
 444
 445 // SetMaxReadFrameSize sets the maximum size of a frame
 446 // that will be read by a subsequent call to ReadFrame.
 447 // It is the caller's responsibility to advertise this
 448 // limit with a SETTINGS frame.
 449 func (fr *Framer) SetMaxReadFrameSize(v uint32) {
 450         if v > maxFrameSize {
 451                 v = maxFrameSize
 452         }
 453         fr.maxReadSize = v
 454 }
 455
 456 // ErrorDetail returns a more detailed error of the last error
 457 // returned by Framer.ReadFrame. For instance, if ReadFrame
 458 // returns a StreamError with code PROTOCOL_ERROR, ErrorDetail
 459 // will say exactly what was invalid. ErrorDetail is not guaranteed
 460 // to return a non-nil value and like the rest of the http2 package,
 461 // its return value is not protected by an API compatibility promise.
 462 // ErrorDetail is reset after the next call to ReadFrame.
 463 func (fr *Framer) ErrorDetail() error {
 464         return fr.errDetail
 465 }
 466
 467 // ErrFrameTooLarge is returned from Framer.ReadFrame when the peer
 468 // sends a frame that is larger than declared with SetMaxReadFrameSize.
 469 var ErrFrameTooLarge = errors.New("http2: frame too large")
 470
 471 // terminalReadFrameError reports whether err is an unrecoverable
 472 // error from ReadFrame and no other frames should be read.
 473 func terminalReadFrameError(err error) bool {
 474         if _, ok := err.(StreamError); ok {
 475                 return false
 476         }
 477         return err != nil
 478 }
 479
 480 // ReadFrame reads a single frame. The returned Frame is only valid
 481 // until the next call to ReadFrame.
 482 //
 483 // If the frame is larger than previously set with SetMaxReadFrameSize, the
 484 // returned error is ErrFrameTooLarge. Other errors may be of type
 485 // ConnectionError, StreamError, or anything else from the underlying
 486 // reader.
 487 func (fr *Framer) ReadFrame() (Frame, error) {
 488         fr.errDetail = nil
 489         if fr.lastFrame != nil {
 490                 fr.lastFrame.invalidate()
 491         }
 492         fh, err := readFrameHeader(fr.headerBuf[:], fr.r)
 493         if err != nil {
 494                 return nil, err
 495         }
 496         if fh.Length > fr.maxReadSize {
 497                 return nil, ErrFrameTooLarge
 498         }
 499         payload := fr.getReadBuf(fh.Length)
 500         if _, err := io.ReadFull(fr.r, payload); err != nil {
 501                 return nil, err
 502         }
 503         f, err := typeFrameParser(fh.Type)(fr.frameCache, fh, payload)
 504         if err != nil {
 505                 if ce, ok := err.(connError); ok {
 506                         return nil, fr.connError(ce.Code, ce.Reason)
 507                 }
 508                 return nil, err
 509         }
 510         if err := fr.checkFrameOrder(f); err != nil {
 511                 return nil, err
 512         }
 513         if fr.logReads {
 514                 fr.debugReadLoggerf("http2: Framer %p: read %v", fr, summarizeFrame(f))
 515         }
 516         if fh.Type == FrameHeaders && fr.ReadMetaHeaders != nil {
 517                 return fr.readMetaFrame(f.(*HeadersFrame))
 518         }
 519         return f, nil
 520 }
 521
 522 // connError returns ConnectionError(code) but first
 523 // stashes away a public reason to the caller can optionally relay it
 524 // to the peer before hanging up on them. This might help others debug
 525 // their implementations.
 526 func (fr *Framer) connError(code ErrCode, reason string) error {
 527         fr.errDetail = errors.New(reason)
 528         return ConnectionError(code)
 529 }
 530
 531 // checkFrameOrder reports an error if f is an invalid frame to return
 532 // next from ReadFrame. Mostly it checks whether HEADERS and
 533 // CONTINUATION frames are contiguous.
 534 func (fr *Framer) checkFrameOrder(f Frame) error {
 535         last := fr.lastFrame
 536         fr.lastFrame = f
 537         if fr.AllowIllegalReads {
 538                 return nil
 539         }
 540
 541         fh := f.Header()
 542         if fr.lastHeaderStream != 0 {
 543                 if fh.Type != FrameContinuation {
 544                         return fr.connError(ErrCodeProtocol,
 545                                 fmt.Sprintf("got %s for stream %d; expected CONTINUATION following %s for stream %d",
 546                                         fh.Type, fh.StreamID,
 547                                         last.Header().Type, fr.lastHeaderStream))
 548                 }
 549                 if fh.StreamID != fr.lastHeaderStream {
 550                         return fr.connError(ErrCodeProtocol,
 551                                 fmt.Sprintf("got CONTINUATION for stream %d; expected stream %d",
 552                                         fh.StreamID, fr.lastHeaderStream))
 553                 }
 554         } else if fh.Type == FrameContinuation {
 555                 return fr.connError(ErrCodeProtocol, fmt.Sprintf("unexpected CONTINUATION for stream %d", fh.StreamID))
 556         }
 557
 558         switch fh.Type {
 559         case FrameHeaders, FrameContinuation:
 560                 if fh.Flags.Has(FlagHeadersEndHeaders) {
 561                         fr.lastHeaderStream = 0
 562                 } else {
 563                         fr.lastHeaderStream = fh.StreamID
 564                 }
 565         }
 566
 567         return nil
 568 }
 569
 570 // A DataFrame conveys arbitrary, variable-length sequences of octets
 571 // associated with a stream.
 572 // See http://http2.github.io/http2-spec/#rfc.section.6.1
 573 type DataFrame struct {
 574         FrameHeader
 575         data []byte
 576 }
 577
 578 func (f *DataFrame) StreamEnded() bool {
 579         return f.FrameHeader.Flags.Has(FlagDataEndStream)
 580 }
 581
 582 // Data returns the frame's data octets, not including any padding
 583 // size byte or padding suffix bytes.
 584 // The caller must not retain the returned memory past the next
 585 // call to ReadFrame.
 586 func (f *DataFrame) Data() []byte {
 587         f.checkValid()
 588         return f.data
 589 }
 590
 591 func parseDataFrame(fc *frameCache, fh FrameHeader, payload []byte) (Frame, error) {
 592         if fh.StreamID == 0 {
 593                 // DATA frames MUST be associated with a stream. If a
 594                 // DATA frame is received whose stream identifier
 595                 // field is 0x0, the recipient MUST respond with a
 596                 // connection error (Section 5.4.1) of type
 597                 // PROTOCOL_ERROR.
 598                 return nil, connError{ErrCodeProtocol, "DATA frame with stream ID 0"}
 599         }
 600         f := fc.getDataFrame()
 601         f.FrameHeader = fh
 602
 603         var padSize byte
 604         if fh.Flags.Has(FlagDataPadded) {
 605                 var err error
 606                 payload, padSize, err = readByte(payload)
 607                 if err != nil {
 608                         return nil, err
 609                 }
 610         }
 611         if int(padSize) > len(payload) {
 612                 // If the length of the padding is greater than the
 613                 // length of the frame payload, the recipient MUST
 614                 // treat this as a connection error.
 615                 // Filed: https://github.com/http2/http2-spec/issues/610
 616                 return nil, connError{ErrCodeProtocol, "pad size larger than data payload"}
 617         }
 618         f.data = payload[:len(payload)-int(padSize)]
 619         return f, nil
 620 }
 621
 622 var (
 623         errStreamID    = errors.New("invalid stream ID")
 624         errDepStreamID = errors.New("invalid dependent stream ID")
 625         errPadLength   = errors.New("pad length too large")
 626         errPadBytes    = errors.New("padding bytes must all be zeros unless AllowIllegalWrites is enabled")
 627 )
 628
 629 func validStreamIDOrZero(streamID uint32) bool {
 630         return streamID&(1<<31) == 0
 631 }
 632
 633 func validStreamID(streamID uint32) bool {
 634         return streamID != 0 && streamID&(1<<31) == 0
 635 }
 636
 637 // WriteData writes a DATA frame.
 638 //
 639 // It will perform exactly one Write to the underlying Writer.
 640 // It is the caller's responsibility not to violate the maximum frame size
 641 // and to not call other Write methods concurrently.
 642 func (f *Framer) WriteData(streamID uint32, endStream bool, data []byte) error {
 643         return f.WriteDataPadded(streamID, endStream, data, nil)
 644 }
 645
 646 // WriteDataPadded writes a DATA frame with optional padding.
 647 //
 648 // If pad is nil, the padding bit is not sent.
 649 // The length of pad must not exceed 255 bytes.
 650 // The bytes of pad must all be zero, unless f.AllowIllegalWrites is set.
 651 //
 652 // It will perform exactly one Write to the underlying Writer.
 653 // It is the caller's responsibility not to violate the maximum frame size
 654 // and to not call other Write methods concurrently.
 655 func (f *Framer) WriteDataPadded(streamID uint32, endStream bool, data, pad []byte) error {
 656         if !validStreamID(streamID) && !f.AllowIllegalWrites {
 657                 return errStreamID
 658         }
 659         if len(pad) > 0 {
 660                 if len(pad) > 255 {
 661                         return errPadLength
 662                 }
 663                 if !f.AllowIllegalWrites {
 664                         for _, b := range pad {
 665                                 if b != 0 {
 666                                         // "Padding octets MUST be set to zero when sending."
 667                                         return errPadBytes
 668                                 }
 669                         }
 670                 }
 671         }
 672         var flags Flags
 673         if endStream {
 674                 flags |= FlagDataEndStream
 675         }
 676         if pad != nil {
 677                 flags |= FlagDataPadded
 678         }
 679         f.startWrite(FrameData, flags, streamID)
 680         if pad != nil {
 681                 f.wbuf = append(f.wbuf, byte(len(pad)))
 682         }
 683         f.wbuf = append(f.wbuf, data...)
 684         f.wbuf = append(f.wbuf, pad...)
 685         return f.endWrite()
 686 }
 687
 688 // A SettingsFrame conveys configuration parameters that affect how
 689 // endpoints communicate, such as preferences and constraints on peer
 690 // behavior.
 691 //
 692 // See http://http2.github.io/http2-spec/#SETTINGS
 693 type SettingsFrame struct {
 694         FrameHeader
 695         p []byte
 696 }
 697
 698 func parseSettingsFrame(_ *frameCache, fh FrameHeader, p []byte) (Frame, error) {
 699         if fh.Flags.Has(FlagSettingsAck) && fh.Length > 0 {
 700                 // When this (ACK 0x1) bit is set, the payload of the
 701                 // SETTINGS frame MUST be empty. Receipt of a
 702                 // SETTINGS frame with the ACK flag set and a length
 703                 // field value other than 0 MUST be treated as a
 704                 // connection error (Section 5.4.1) of type
 705                 // FRAME_SIZE_ERROR.
 706                 return nil, ConnectionError(ErrCodeFrameSize)
 707         }
 708         if fh.StreamID != 0 {
 709                 // SETTINGS frames always apply to a connection,
 710                 // never a single stream. The stream identifier for a
 711                 // SETTINGS frame MUST be zero (0x0).  If an endpoint
 712                 // receives a SETTINGS frame whose stream identifier
 713                 // field is anything other than 0x0, the endpoint MUST
 714                 // respond with a connection error (Section 5.4.1) of
 715                 // type PROTOCOL_ERROR.
 716                 return nil, ConnectionError(ErrCodeProtocol)
 717         }
 718         if len(p)%6 != 0 {
 719                 // Expecting even number of 6 byte settings.
 720                 return nil, ConnectionError(ErrCodeFrameSize)
 721         }
 722         f := &SettingsFrame{FrameHeader: fh, p: p}
 723         if v, ok := f.Value(SettingInitialWindowSize); ok && v > (1<<31)-1 {
 724                 // Values above the maximum flow control window size of 2^31 - 1 MUST
 725                 // be treated as a connection error (Section 5.4.1) of type
 726                 // FLOW_CONTROL_ERROR.
 727                 return nil, ConnectionError(ErrCodeFlowControl)
 728         }
 729         return f, nil
 730 }
 731
 732 func (f *SettingsFrame) IsAck() bool {
 733         return f.FrameHeader.Flags.Has(FlagSettingsAck)
 734 }
 735
 736 func (f *SettingsFrame) Value(id SettingID) (v uint32, ok bool) {
 737         f.checkValid()
 738         for i := 0; i < f.NumSettings(); i++ {
 739                 if s := f.Setting(i); s.ID == id {
 740                         return s.Val, true
 741                 }
 742         }
 743         return 0, false
 744 }
 745
 746 // Setting returns the setting from the frame at the given 0-based index.
 747 // The index must be >= 0 and less than f.NumSettings().
 748 func (f *SettingsFrame) Setting(i int) Setting {
 749         buf := f.p
 750         return Setting{
 751                 ID:  SettingID(binary.BigEndian.Uint16(buf[i*6 : i*6+2])),
 752                 Val: binary.BigEndian.Uint32(buf[i*6+2 : i*6+6]),
 753         }
 754 }
 755
 756 func (f *SettingsFrame) NumSettings() int { return len(f.p) / 6 }
 757
 758 // HasDuplicates reports whether f contains any duplicate setting IDs.
 759 func (f *SettingsFrame) HasDuplicates() bool {
 760         num := f.NumSettings()
 761         if num == 0 {
 762                 return false
 763         }
 764         // If it's small enough (the common case), just do the n^2
 765         // thing and avoid a map allocation.
 766         if num < 10 {
 767                 for i := 0; i < num; i++ {
 768                         idi := f.Setting(i).ID
 769                         for j := i + 1; j < num; j++ {
 770                                 idj := f.Setting(j).ID
 771                                 if idi == idj {
 772                                         return true
 773                                 }
 774                         }
 775                 }
 776                 return false
 777         }
 778         seen := map[SettingID]bool{}
 779         for i := 0; i < num; i++ {
 780                 id := f.Setting(i).ID
 781                 if seen[id] {
 782                         return true
 783                 }
 784                 seen[id] = true
 785         }
 786         return false
 787 }
 788
 789 // ForeachSetting runs fn for each setting.
 790 // It stops and returns the first error.
 791 func (f *SettingsFrame) ForeachSetting(fn func(Setting) error) error {
 792         f.checkValid()
 793         for i := 0; i < f.NumSettings(); i++ {
 794                 if err := fn(f.Setting(i)); err != nil {
 795                         return err
 796                 }
 797         }
 798         return nil
 799 }
 800
 801 // WriteSettings writes a SETTINGS frame with zero or more settings
 802 // specified and the ACK bit not set.
 803 //
 804 // It will perform exactly one Write to the underlying Writer.
 805 // It is the caller's responsibility to not call other Write methods concurrently.
 806 func (f *Framer) WriteSettings(settings ...Setting) error {
 807         f.startWrite(FrameSettings, 0, 0)
 808         for _, s := range settings {
 809                 f.writeUint16(uint16(s.ID))
 810                 f.writeUint32(s.Val)
 811         }
 812         return f.endWrite()
 813 }
 814
 815 // WriteSettingsAck writes an empty SETTINGS frame with the ACK bit set.
 816 //
 817 // It will perform exactly one Write to the underlying Writer.
 818 // It is the caller's responsibility to not call other Write methods concurrently.
 819 func (f *Framer) WriteSettingsAck() error {
 820         f.startWrite(FrameSettings, FlagSettingsAck, 0)
 821         return f.endWrite()
 822 }
 823
 824 // A PingFrame is a mechanism for measuring a minimal round trip time
 825 // from the sender, as well as determining whether an idle connection
 826 // is still functional.
 827 // See http://http2.github.io/http2-spec/#rfc.section.6.7
 828 type PingFrame struct {
 829         FrameHeader
 830         Data [8]byte
 831 }
 832
 833 func (f *PingFrame) IsAck() bool { return f.Flags.Has(FlagPingAck) }
 834
 835 func parsePingFrame(_ *frameCache, fh FrameHeader, payload []byte) (Frame, error) {
 836         if len(payload) != 8 {
 837                 return nil, ConnectionError(ErrCodeFrameSize)
 838         }
 839         if fh.StreamID != 0 {
 840                 return nil, ConnectionError(ErrCodeProtocol)
 841         }
 842         f := &PingFrame{FrameHeader: fh}
 843         copy(f.Data[:], payload)
 844         return f, nil
 845 }
 846
 847 func (f *Framer) WritePing(ack bool, data [8]byte) error {
 848         var flags Flags
 849         if ack {
 850                 flags = FlagPingAck
 851         }
 852         f.startWrite(FramePing, flags, 0)
 853         f.writeBytes(data[:])
 854         return f.endWrite()
 855 }
 856
 857 // A GoAwayFrame informs the remote peer to stop creating streams on this connection.
 858 // See http://http2.github.io/http2-spec/#rfc.section.6.8
 859 type GoAwayFrame struct {
 860         FrameHeader
 861         LastStreamID uint32
 862         ErrCode      ErrCode
 863         debugData    []byte
 864 }
 865
 866 // DebugData returns any debug data in the GOAWAY frame. Its contents
 867 // are not defined.
 868 // The caller must not retain the returned memory past the next
 869 // call to ReadFrame.
 870 func (f *GoAwayFrame) DebugData() []byte {
 871         f.checkValid()
 872         return f.debugData
 873 }
 874
 875 func parseGoAwayFrame(_ *frameCache, fh FrameHeader, p []byte) (Frame, error) {
 876         if fh.StreamID != 0 {
 877                 return nil, ConnectionError(ErrCodeProtocol)
 878         }
 879         if len(p) < 8 {
 880                 return nil, ConnectionError(ErrCodeFrameSize)
 881         }
 882         return &GoAwayFrame{
 883                 FrameHeader:  fh,
 884                 LastStreamID: binary.BigEndian.Uint32(p[:4]) & (1<<31 - 1),
 885                 ErrCode:      ErrCode(binary.BigEndian.Uint32(p[4:8])),
 886                 debugData:    p[8:],
 887         }, nil
 888 }
 889
 890 func (f *Framer) WriteGoAway(maxStreamID uint32, code ErrCode, debugData []byte) error {
 891         f.startWrite(FrameGoAway, 0, 0)
 892         f.writeUint32(maxStreamID & (1<<31 - 1))
 893         f.writeUint32(uint32(code))
 894         f.writeBytes(debugData)
 895         return f.endWrite()
 896 }
 897
 898 // An UnknownFrame is the frame type returned when the frame type is unknown
 899 // or no specific frame type parser exists.
 900 type UnknownFrame struct {
 901         FrameHeader
 902         p []byte
 903 }
 904
 905 // Payload returns the frame's payload (after the header).  It is not
 906 // valid to call this method after a subsequent call to
 907 // Framer.ReadFrame, nor is it valid to retain the returned slice.
 908 // The memory is owned by the Framer and is invalidated when the next
 909 // frame is read.
 910 func (f *UnknownFrame) Payload() []byte {
 911         f.checkValid()
 912         return f.p
 913 }
 914
 915 func parseUnknownFrame(_ *frameCache, fh FrameHeader, p []byte) (Frame, error) {
 916         return &UnknownFrame{fh, p}, nil
 917 }
 918
 919 // A WindowUpdateFrame is used to implement flow control.
 920 // See http://http2.github.io/http2-spec/#rfc.section.6.9
 921 type WindowUpdateFrame struct {
 922         FrameHeader
 923         Increment uint32 // never read with high bit set
 924 }
 925
 926 func parseWindowUpdateFrame(_ *frameCache, fh FrameHeader, p []byte) (Frame, error) {
 927         if len(p) != 4 {
 928                 return nil, ConnectionError(ErrCodeFrameSize)
 929         }
 930         inc := binary.BigEndian.Uint32(p[:4]) & 0x7fffffff // mask off high reserved bit
 931         if inc == 0 {
 932                 // A receiver MUST treat the receipt of a
 933                 // WINDOW_UPDATE frame with an flow control window
 934                 // increment of 0 as a stream error (Section 5.4.2) of
 935                 // type PROTOCOL_ERROR; errors on the connection flow
 936                 // control window MUST be treated as a connection
 937                 // error (Section 5.4.1).
 938                 if fh.StreamID == 0 {
 939                         return nil, ConnectionError(ErrCodeProtocol)
 940                 }
 941                 return nil, streamError(fh.StreamID, ErrCodeProtocol)
 942         }
 943         return &WindowUpdateFrame{
 944                 FrameHeader: fh,
 945                 Increment:   inc,
 946         }, nil
 947 }
 948
 949 // WriteWindowUpdate writes a WINDOW_UPDATE frame.
 950 // The increment value must be between 1 and 2,147,483,647, inclusive.
 951 // If the Stream ID is zero, the window update applies to the
 952 // connection as a whole.
 953 func (f *Framer) WriteWindowUpdate(streamID, incr uint32) error {
 954         // "The legal range for the increment to the flow control window is 1 to 2^31-1 (2,147,483,647) octets."
 955         if (incr < 1 || incr > 2147483647) && !f.AllowIllegalWrites {
 956                 return errors.New("illegal window increment value")
 957         }
 958         f.startWrite(FrameWindowUpdate, 0, streamID)
 959         f.writeUint32(incr)
 960         return f.endWrite()
 961 }
 962
 963 // A HeadersFrame is used to open a stream and additionally carries a
 964 // header block fragment.
 965 type HeadersFrame struct {
 966         FrameHeader
 967
 968         // Priority is set if FlagHeadersPriority is set in the FrameHeader.
 969         Priority PriorityParam
 970
 971         headerFragBuf []byte // not owned
 972 }
 973
 974 func (f *HeadersFrame) HeaderBlockFragment() []byte {
 975         f.checkValid()
 976         return f.headerFragBuf
 977 }
 978
 979 func (f *HeadersFrame) HeadersEnded() bool {
 980         return f.FrameHeader.Flags.Has(FlagHeadersEndHeaders)
 981 }
 982
 983 func (f *HeadersFrame) StreamEnded() bool {
 984         return f.FrameHeader.Flags.Has(FlagHeadersEndStream)
 985 }
 986
 987 func (f *HeadersFrame) HasPriority() bool {
 988         return f.FrameHeader.Flags.Has(FlagHeadersPriority)
 989 }
 990
 991 func parseHeadersFrame(_ *frameCache, fh FrameHeader, p []byte) (_ Frame, err error) {
 992         hf := &HeadersFrame{
 993                 FrameHeader: fh,
 994         }
 995         if fh.StreamID == 0 {
 996                 // HEADERS frames MUST be associated with a stream. If a HEADERS frame
 997                 // is received whose stream identifier field is 0x0, the recipient MUST
 998                 // respond with a connection error (Section 5.4.1) of type
 999                 // PROTOCOL_ERROR.
1000                 return nil, connError{ErrCodeProtocol, "HEADERS frame with stream ID 0"}
1001         }
1002         var padLength uint8
1003         if fh.Flags.Has(FlagHeadersPadded) {
1004                 if p, padLength, err = readByte(p); err != nil {
1005                         return
1006                 }
1007         }
1008         if fh.Flags.Has(FlagHeadersPriority) {
1009                 var v uint32
1010                 p, v, err = readUint32(p)
1011                 if err != nil {
1012                         return nil, err
1013                 }
1014                 hf.Priority.StreamDep = v & 0x7fffffff
1015                 hf.Priority.Exclusive = (v != hf.Priority.StreamDep) // high bit was set
1016                 p, hf.Priority.Weight, err = readByte(p)
1017                 if err != nil {
1018                         return nil, err
1019                 }
1020         }
1021         if len(p)-int(padLength) <= 0 {
1022                 return nil, streamError(fh.StreamID, ErrCodeProtocol)
1023         }
1024         hf.headerFragBuf = p[:len(p)-int(padLength)]
1025         return hf, nil
1026 }
1027
1028 // HeadersFrameParam are the parameters for writing a HEADERS frame.
1029 type HeadersFrameParam struct {
1030         // StreamID is the required Stream ID to initiate.
1031         StreamID uint32
1032         // BlockFragment is part (or all) of a Header Block.
1033         BlockFragment []byte
1034
1035         // EndStream indicates that the header block is the last that
1036         // the endpoint will send for the identified stream. Setting
1037         // this flag causes the stream to enter one of "half closed"
1038         // states.
1039         EndStream bool
1040
1041         // EndHeaders indicates that this frame contains an entire
1042         // header block and is not followed by any
1043         // CONTINUATION frames.
1044         EndHeaders bool
1045
1046         // PadLength is the optional number of bytes of zeros to add
1047         // to this frame.
1048         PadLength uint8
1049
1050         // Priority, if non-zero, includes stream priority information
1051         // in the HEADER frame.
1052         Priority PriorityParam
1053 }
1054
1055 // WriteHeaders writes a single HEADERS frame.
1056 //
1057 // This is a low-level header writing method. Encoding headers and
1058 // splitting them into any necessary CONTINUATION frames is handled
1059 // elsewhere.
1060 //
1061 // It will perform exactly one Write to the underlying Writer.
1062 // It is the caller's responsibility to not call other Write methods concurrently.
1063 func (f *Framer) WriteHeaders(p HeadersFrameParam) error {
1064         if !validStreamID(p.StreamID) && !f.AllowIllegalWrites {
1065                 return errStreamID
1066         }
1067         var flags Flags
1068         if p.PadLength != 0 {
1069                 flags |= FlagHeadersPadded
1070         }
1071         if p.EndStream {
1072                 flags |= FlagHeadersEndStream
1073         }
1074         if p.EndHeaders {
1075                 flags |= FlagHeadersEndHeaders
1076         }
1077         if !p.Priority.IsZero() {
1078                 flags |= FlagHeadersPriority
1079         }
1080         f.startWrite(FrameHeaders, flags, p.StreamID)
1081         if p.PadLength != 0 {
1082                 f.writeByte(p.PadLength)
1083         }
1084         if !p.Priority.IsZero() {
1085                 v := p.Priority.StreamDep
1086                 if !validStreamIDOrZero(v) && !f.AllowIllegalWrites {
1087                         return errDepStreamID
1088                 }
1089                 if p.Priority.Exclusive {
1090                         v |= 1 << 31
1091                 }
1092                 f.writeUint32(v)
1093                 f.writeByte(p.Priority.Weight)
1094         }
1095         f.wbuf = append(f.wbuf, p.BlockFragment...)
1096         f.wbuf = append(f.wbuf, padZeros[:p.PadLength]...)
1097         return f.endWrite()
1098 }
1099
1100 // A PriorityFrame specifies the sender-advised priority of a stream.
1101 // See http://http2.github.io/http2-spec/#rfc.section.6.3
1102 type PriorityFrame struct {
1103         FrameHeader
1104         PriorityParam
1105 }
1106
1107 // PriorityParam are the stream prioritzation parameters.
1108 type PriorityParam struct {
1109         // StreamDep is a 31-bit stream identifier for the
1110         // stream that this stream depends on. Zero means no
1111         // dependency.
1112         StreamDep uint32
1113
1114         // Exclusive is whether the dependency is exclusive.
1115         Exclusive bool
1116
1117         // Weight is the stream's zero-indexed weight. It should be
1118         // set together with StreamDep, or neither should be set. Per
1119         // the spec, "Add one to the value to obtain a weight between
1120         // 1 and 256."
1121         Weight uint8
1122 }
1123
1124 func (p PriorityParam) IsZero() bool {
1125         return p == PriorityParam{}
1126 }
1127
1128 func parsePriorityFrame(_ *frameCache, fh FrameHeader, payload []byte) (Frame, error) {
1129         if fh.StreamID == 0 {
1130                 return nil, connError{ErrCodeProtocol, "PRIORITY frame with stream ID 0"}
1131         }
1132         if len(payload) != 5 {
1133                 return nil, connError{ErrCodeFrameSize, fmt.Sprintf("PRIORITY frame payload size was %d; want 5", len(payload))}
1134         }
1135         v := binary.BigEndian.Uint32(payload[:4])
1136         streamID := v & 0x7fffffff // mask off high bit
1137         return &PriorityFrame{
1138                 FrameHeader: fh,
1139                 PriorityParam: PriorityParam{
1140                         Weight:    payload[4],
1141                         StreamDep: streamID,
1142                         Exclusive: streamID != v, // was high bit set?
1143                 },
1144         }, nil
1145 }
1146
1147 // WritePriority writes a PRIORITY frame.
1148 //
1149 // It will perform exactly one Write to the underlying Writer.
1150 // It is the caller's responsibility to not call other Write methods concurrently.
1151 func (f *Framer) WritePriority(streamID uint32, p PriorityParam) error {
1152         if !validStreamID(streamID) && !f.AllowIllegalWrites {
1153                 return errStreamID
1154         }
1155         if !validStreamIDOrZero(p.StreamDep) {
1156                 return errDepStreamID
1157         }
1158         f.startWrite(FramePriority, 0, streamID)
1159         v := p.StreamDep
1160         if p.Exclusive {
1161                 v |= 1 << 31
1162         }
1163         f.writeUint32(v)
1164         f.writeByte(p.Weight)
1165         return f.endWrite()
1166 }
1167
1168 // A RSTStreamFrame allows for abnormal termination of a stream.
1169 // See http://http2.github.io/http2-spec/#rfc.section.6.4
1170 type RSTStreamFrame struct {
1171         FrameHeader
1172         ErrCode ErrCode
1173 }
1174
1175 func parseRSTStreamFrame(_ *frameCache, fh FrameHeader, p []byte) (Frame, error) {
1176         if len(p) != 4 {
1177                 return nil, ConnectionError(ErrCodeFrameSize)
1178         }
1179         if fh.StreamID == 0 {
1180                 return nil, ConnectionError(ErrCodeProtocol)
1181         }
1182         return &RSTStreamFrame{fh, ErrCode(binary.BigEndian.Uint32(p[:4]))}, nil
1183 }
1184
1185 // WriteRSTStream writes a RST_STREAM frame.
1186 //
1187 // It will perform exactly one Write to the underlying Writer.
1188 // It is the caller's responsibility to not call other Write methods concurrently.
1189 func (f *Framer) WriteRSTStream(streamID uint32, code ErrCode) error {
1190         if !validStreamID(streamID) && !f.AllowIllegalWrites {
1191                 return errStreamID
1192         }
1193         f.startWrite(FrameRSTStream, 0, streamID)
1194         f.writeUint32(uint32(code))
1195         return f.endWrite()
1196 }
1197
1198 // A ContinuationFrame is used to continue a sequence of header block fragments.
1199 // See http://http2.github.io/http2-spec/#rfc.section.6.10
1200 type ContinuationFrame struct {
1201         FrameHeader
1202         headerFragBuf []byte
1203 }
1204
1205 func parseContinuationFrame(_ *frameCache, fh FrameHeader, p []byte) (Frame, error) {
1206         if fh.StreamID == 0 {
1207                 return nil, connError{ErrCodeProtocol, "CONTINUATION frame with stream ID 0"}
1208         }
1209         return &ContinuationFrame{fh, p}, nil
1210 }
1211
1212 func (f *ContinuationFrame) HeaderBlockFragment() []byte {
1213         f.checkValid()
1214         return f.headerFragBuf
1215 }
1216
1217 func (f *ContinuationFrame) HeadersEnded() bool {
1218         return f.FrameHeader.Flags.Has(FlagContinuationEndHeaders)
1219 }
1220
1221 // WriteContinuation writes a CONTINUATION frame.
1222 //
1223 // It will perform exactly one Write to the underlying Writer.
1224 // It is the caller's responsibility to not call other Write methods concurrently.
1225 func (f *Framer) WriteContinuation(streamID uint32, endHeaders bool, headerBlockFragment []byte) error {
1226         if !validStreamID(streamID) && !f.AllowIllegalWrites {
1227                 return errStreamID
1228         }
1229         var flags Flags
1230         if endHeaders {
1231                 flags |= FlagContinuationEndHeaders
1232         }
1233         f.startWrite(FrameContinuation, flags, streamID)
1234         f.wbuf = append(f.wbuf, headerBlockFragment...)
1235         return f.endWrite()
1236 }
1237
1238 // A PushPromiseFrame is used to initiate a server stream.
1239 // See http://http2.github.io/http2-spec/#rfc.section.6.6
1240 type PushPromiseFrame struct {
1241         FrameHeader
1242         PromiseID     uint32
1243         headerFragBuf []byte // not owned
1244 }
1245
1246 func (f *PushPromiseFrame) HeaderBlockFragment() []byte {
1247         f.checkValid()
1248         return f.headerFragBuf
1249 }
1250
1251 func (f *PushPromiseFrame) HeadersEnded() bool {
1252         return f.FrameHeader.Flags.Has(FlagPushPromiseEndHeaders)
1253 }
1254
1255 func parsePushPromise(_ *frameCache, fh FrameHeader, p []byte) (_ Frame, err error) {
1256         pp := &PushPromiseFrame{
1257                 FrameHeader: fh,
1258         }
1259         if pp.StreamID == 0 {
1260                 // PUSH_PROMISE frames MUST be associated with an existing,
1261                 // peer-initiated stream. The stream identifier of a
1262                 // PUSH_PROMISE frame indicates the stream it is associated
1263                 // with. If the stream identifier field specifies the value
1264                 // 0x0, a recipient MUST respond with a connection error
1265                 // (Section 5.4.1) of type PROTOCOL_ERROR.
1266                 return nil, ConnectionError(ErrCodeProtocol)
1267         }
1268         // The PUSH_PROMISE frame includes optional padding.
1269         // Padding fields and flags are identical to those defined for DATA frames
1270         var padLength uint8
1271         if fh.Flags.Has(FlagPushPromisePadded) {
1272                 if p, padLength, err = readByte(p); err != nil {
1273                         return
1274                 }
1275         }
1276
1277         p, pp.PromiseID, err = readUint32(p)
1278         if err != nil {
1279                 return
1280         }
1281         pp.PromiseID = pp.PromiseID & (1<<31 - 1)
1282
1283         if int(padLength) > len(p) {
1284                 // like the DATA frame, error out if padding is longer than the body.
1285                 return nil, ConnectionError(ErrCodeProtocol)
1286         }
1287         pp.headerFragBuf = p[:len(p)-int(padLength)]
1288         return pp, nil
1289 }
1290
1291 // PushPromiseParam are the parameters for writing a PUSH_PROMISE frame.
1292 type PushPromiseParam struct {
1293         // StreamID is the required Stream ID to initiate.
1294         StreamID uint32
1295
1296         // PromiseID is the required Stream ID which this
1297         // Push Promises
1298         PromiseID uint32
1299
1300         // BlockFragment is part (or all) of a Header Block.
1301         BlockFragment []byte
1302
1303         // EndHeaders indicates that this frame contains an entire
1304         // header block and is not followed by any
1305         // CONTINUATION frames.
1306         EndHeaders bool
1307
1308         // PadLength is the optional number of bytes of zeros to add
1309         // to this frame.
1310         PadLength uint8
1311 }
1312
1313 // WritePushPromise writes a single PushPromise Frame.
1314 //
1315 // As with Header Frames, This is the low level call for writing
1316 // individual frames. Continuation frames are handled elsewhere.
1317 //
1318 // It will perform exactly one Write to the underlying Writer.
1319 // It is the caller's responsibility to not call other Write methods concurrently.
1320 func (f *Framer) WritePushPromise(p PushPromiseParam) error {
1321         if !validStreamID(p.StreamID) && !f.AllowIllegalWrites {
1322                 return errStreamID
1323         }
1324         var flags Flags
1325         if p.PadLength != 0 {
1326                 flags |= FlagPushPromisePadded
1327         }
1328         if p.EndHeaders {
1329                 flags |= FlagPushPromiseEndHeaders
1330         }
1331         f.startWrite(FramePushPromise, flags, p.StreamID)
1332         if p.PadLength != 0 {
1333                 f.writeByte(p.PadLength)
1334         }
1335         if !validStreamID(p.PromiseID) && !f.AllowIllegalWrites {
1336                 return errStreamID
1337         }
1338         f.writeUint32(p.PromiseID)
1339         f.wbuf = append(f.wbuf, p.BlockFragment...)
1340         f.wbuf = append(f.wbuf, padZeros[:p.PadLength]...)
1341         return f.endWrite()
1342 }
1343
1344 // WriteRawFrame writes a raw frame. This can be used to write
1345 // extension frames unknown to this package.
1346 func (f *Framer) WriteRawFrame(t FrameType, flags Flags, streamID uint32, payload []byte) error {
1347         f.startWrite(t, flags, streamID)
1348         f.writeBytes(payload)
1349         return f.endWrite()
1350 }
1351
1352 func readByte(p []byte) (remain []byte, b byte, err error) {
1353         if len(p) == 0 {
1354                 return nil, 0, io.ErrUnexpectedEOF
1355         }
1356         return p[1:], p[0], nil
1357 }
1358
1359 func readUint32(p []byte) (remain []byte, v uint32, err error) {
1360         if len(p) < 4 {
1361                 return nil, 0, io.ErrUnexpectedEOF
1362         }
1363         return p[4:], binary.BigEndian.Uint32(p[:4]), nil
1364 }
1365
1366 type streamEnder interface {
1367         StreamEnded() bool
1368 }
1369
1370 type headersEnder interface {
1371         HeadersEnded() bool
1372 }
1373
1374 type headersOrContinuation interface {
1375         headersEnder
1376         HeaderBlockFragment() []byte
1377 }
1378
1379 // A MetaHeadersFrame is the representation of one HEADERS frame and
1380 // zero or more contiguous CONTINUATION frames and the decoding of
1381 // their HPACK-encoded contents.
1382 //
1383 // This type of frame does not appear on the wire and is only returned
1384 // by the Framer when Framer.ReadMetaHeaders is set.
1385 type MetaHeadersFrame struct {
1386         *HeadersFrame
1387
1388         // Fields are the fields contained in the HEADERS and
1389         // CONTINUATION frames. The underlying slice is owned by the
1390         // Framer and must not be retained after the next call to
1391         // ReadFrame.
1392         //
1393         // Fields are guaranteed to be in the correct http2 order and
1394         // not have unknown pseudo header fields or invalid header
1395         // field names or values. Required pseudo header fields may be
1396         // missing, however. Use the MetaHeadersFrame.Pseudo accessor
1397         // method access pseudo headers.
1398         Fields []hpack.HeaderField
1399
1400         // Truncated is whether the max header list size limit was hit
1401         // and Fields is incomplete. The hpack decoder state is still
1402         // valid, however.
1403         Truncated bool
1404 }
1405
1406 // PseudoValue returns the given pseudo header field's value.
1407 // The provided pseudo field should not contain the leading colon.
1408 func (mh *MetaHeadersFrame) PseudoValue(pseudo string) string {
1409         for _, hf := range mh.Fields {
1410                 if !hf.IsPseudo() {
1411                         return ""
1412                 }
1413                 if hf.Name[1:] == pseudo {
1414                         return hf.Value
1415                 }
1416         }
1417         return ""
1418 }
1419
1420 // RegularFields returns the regular (non-pseudo) header fields of mh.
1421 // The caller does not own the returned slice.
1422 func (mh *MetaHeadersFrame) RegularFields() []hpack.HeaderField {
1423         for i, hf := range mh.Fields {
1424                 if !hf.IsPseudo() {
1425                         return mh.Fields[i:]
1426                 }
1427         }
1428         return nil
1429 }
1430
1431 // PseudoFields returns the pseudo header fields of mh.
1432 // The caller does not own the returned slice.
1433 func (mh *MetaHeadersFrame) PseudoFields() []hpack.HeaderField {
1434         for i, hf := range mh.Fields {
1435                 if !hf.IsPseudo() {
1436                         return mh.Fields[:i]
1437                 }
1438         }
1439         return mh.Fields
1440 }
1441
1442 func (mh *MetaHeadersFrame) checkPseudos() error {
1443         var isRequest, isResponse bool
1444         pf := mh.PseudoFields()
1445         for i, hf := range pf {
1446                 switch hf.Name {
1447                 case ":method", ":path", ":scheme", ":authority":
1448                         isRequest = true
1449                 case ":status":
1450                         isResponse = true
1451                 default:
1452                         return pseudoHeaderError(hf.Name)
1453                 }
1454                 // Check for duplicates.
1455                 // This would be a bad algorithm, but N is 4.
1456                 // And this doesn't allocate.
1457                 for _, hf2 := range pf[:i] {
1458                         if hf.Name == hf2.Name {
1459                                 return duplicatePseudoHeaderError(hf.Name)
1460                         }
1461                 }
1462         }
1463         if isRequest && isResponse {
1464                 return errMixPseudoHeaderTypes
1465         }
1466         return nil
1467 }
1468
1469 func (fr *Framer) maxHeaderStringLen() int {
1470         v := fr.maxHeaderListSize()
1471         if uint32(int(v)) == v {
1472                 return int(v)
1473         }
1474         // They had a crazy big number for MaxHeaderBytes anyway,
1475         // so give them unlimited header lengths:
1476         return 0
1477 }
1478
1479 // readMetaFrame returns 0 or more CONTINUATION frames from fr and
1480 // merge them into the provided hf and returns a MetaHeadersFrame
1481 // with the decoded hpack values.
1482 func (fr *Framer) readMetaFrame(hf *HeadersFrame) (*MetaHeadersFrame, error) {
1483         if fr.AllowIllegalReads {
1484                 return nil, errors.New("illegal use of AllowIllegalReads with ReadMetaHeaders")
1485         }
1486         mh := &MetaHeadersFrame{
1487                 HeadersFrame: hf,
1488         }
1489         var remainSize = fr.maxHeaderListSize()
1490         var sawRegular bool
1491
1492         var invalid error // pseudo header field errors
1493         hdec := fr.ReadMetaHeaders
1494         hdec.SetEmitEnabled(true)
1495         hdec.SetMaxStringLength(fr.maxHeaderStringLen())
1496         hdec.SetEmitFunc(func(hf hpack.HeaderField) {
1497                 if VerboseLogs && fr.logReads {
1498                         fr.debugReadLoggerf("http2: decoded hpack field %+v", hf)
1499                 }
1500                 if !httpguts.ValidHeaderFieldValue(hf.Value) {
1501                         invalid = headerFieldValueError(hf.Value)
1502                 }
1503                 isPseudo := strings.HasPrefix(hf.Name, ":")
1504                 if isPseudo {
1505                         if sawRegular {
1506                                 invalid = errPseudoAfterRegular
1507                         }
1508                 } else {
1509                         sawRegular = true
1510                         if !validWireHeaderFieldName(hf.Name) {
1511                                 invalid = headerFieldNameError(hf.Name)
1512                         }
1513                 }
1514
1515                 if invalid != nil {
1516                         hdec.SetEmitEnabled(false)
1517                         return
1518                 }
1519
1520                 size := hf.Size()
1521                 if size > remainSize {
1522                         hdec.SetEmitEnabled(false)
1523                         mh.Truncated = true
1524                         return
1525                 }
1526                 remainSize -= size
1527
1528                 mh.Fields = append(mh.Fields, hf)
1529         })
1530         // Lose reference to MetaHeadersFrame:
1531         defer hdec.SetEmitFunc(func(hf hpack.HeaderField) {})
1532
1533         var hc headersOrContinuation = hf
1534         for {
1535                 frag := hc.HeaderBlockFragment()
1536                 if _, err := hdec.Write(frag); err != nil {
1537                         return nil, ConnectionError(ErrCodeCompression)
1538                 }
1539
1540                 if hc.HeadersEnded() {
1541                         break
1542                 }
1543                 if f, err := fr.ReadFrame(); err != nil {
1544                         return nil, err
1545                 } else {
1546                         hc = f.(*ContinuationFrame) // guaranteed by checkFrameOrder
1547                 }
1548         }
1549
1550         mh.HeadersFrame.headerFragBuf = nil
1551         mh.HeadersFrame.invalidate()
1552
1553         if err := hdec.Close(); err != nil {
1554                 return nil, ConnectionError(ErrCodeCompression)
1555         }
1556         if invalid != nil {
1557                 fr.errDetail = invalid
1558                 if VerboseLogs {
1559                         log.Printf("http2: invalid header: %v", invalid)
1560                 }
1561                 return nil, StreamError{mh.StreamID, ErrCodeProtocol, invalid}
1562         }
1563         if err := mh.checkPseudos(); err != nil {
1564                 fr.errDetail = err
1565                 if VerboseLogs {
1566                         log.Printf("http2: invalid pseudo headers: %v", err)
1567                 }
1568                 return nil, StreamError{mh.StreamID, ErrCodeProtocol, err}
1569         }
1570         return mh, nil
1571 }
1572
1573 func summarizeFrame(f Frame) string {
1574         var buf bytes.Buffer
1575         f.Header().writeDebug(&buf)
1576         switch f := f.(type) {
1577         case *SettingsFrame:
1578                 n := 0
1579                 f.ForeachSetting(func(s Setting) error {
1580                         n++
1581                         if n == 1 {
1582                                 buf.WriteString(", settings:")
1583                         }
1584                         fmt.Fprintf(&buf, " %v=%v,", s.ID, s.Val)
1585                         return nil
1586                 })
1587                 if n > 0 {
1588                         buf.Truncate(buf.Len() - 1) // remove trailing comma
1589                 }
1590         case *DataFrame:
1591                 data := f.Data()
1592                 const max = 256
1593                 if len(data) > max {
1594                         data = data[:max]
1595                 }
1596                 fmt.Fprintf(&buf, " data=%q", data)
1597                 if len(f.Data()) > max {
1598                         fmt.Fprintf(&buf, " (%d bytes omitted)", len(f.Data())-max)
1599                 }
1600         case *WindowUpdateFrame:
1601                 if f.StreamID == 0 {
1602                         buf.WriteString(" (conn)")
1603                 }
1604                 fmt.Fprintf(&buf, " incr=%v", f.Increment)
1605         case *PingFrame:
1606                 fmt.Fprintf(&buf, " ping=%q", f.Data[:])
1607         case *GoAwayFrame:
1608                 fmt.Fprintf(&buf, " LastStreamID=%v ErrCode=%v Debug=%q",
1609                         f.LastStreamID, f.ErrCode, f.debugData)
1610         case *RSTStreamFrame:
1611                 fmt.Fprintf(&buf, " ErrCode=%v", f.ErrCode)
1612         }
1613         return buf.String()
1614 }