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