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
5package hpack
6
7import (
8 "io"
9)
10
11const (
12 uint32Max = ^uint32(0)
13 initialHeaderTableSize = 4096
14)
15
16type Encoder struct {
17 dynTab dynamicTable
18 // minSize is the minimum table size set by
19 // SetMaxDynamicTableSize after the previous Header Table Size
20 // Update.
21 minSize uint32
22 // maxSizeLimit is the maximum table size this encoder
23 // supports. This will protect the encoder from too large
24 // size.
25 maxSizeLimit uint32
26 // tableSizeUpdate indicates whether "Header Table Size
27 // Update" is required.
28 tableSizeUpdate bool
29 w io.Writer
30 buf []byte
31}
32
33// NewEncoder returns a new Encoder which performs HPACK encoding. An
34// encoded data is written to w.
35func NewEncoder(w io.Writer) *Encoder {
36 e := &Encoder{
37 minSize: uint32Max,
38 maxSizeLimit: initialHeaderTableSize,
39 tableSizeUpdate: false,
40 w: w,
41 }
42 e.dynTab.table.init()
43 e.dynTab.setMaxSize(initialHeaderTableSize)
44 return e
45}
46
47// WriteField encodes f into a single Write to e's underlying Writer.
48// This function may also produce bytes for "Header Table Size Update"
49// if necessary. If produced, it is done before encoding f.
50func (e *Encoder) WriteField(f HeaderField) error {
51 e.buf = e.buf[:0]
52
53 if e.tableSizeUpdate {
54 e.tableSizeUpdate = false
55 if e.minSize < e.dynTab.maxSize {
56 e.buf = appendTableSize(e.buf, e.minSize)
57 }
58 e.minSize = uint32Max
59 e.buf = appendTableSize(e.buf, e.dynTab.maxSize)
60 }
61
62 idx, nameValueMatch := e.searchTable(f)
63 if nameValueMatch {
64 e.buf = appendIndexed(e.buf, idx)
65 } else {
66 indexing := e.shouldIndex(f)
67 if indexing {
68 e.dynTab.add(f)
69 }
70
71 if idx == 0 {
72 e.buf = appendNewName(e.buf, f, indexing)
73 } else {
74 e.buf = appendIndexedName(e.buf, f, idx, indexing)
75 }
76 }
77 n, err := e.w.Write(e.buf)
78 if err == nil && n != len(e.buf) {
79 err = io.ErrShortWrite
80 }
81 return err
82}
83
84// searchTable searches f in both stable and dynamic header tables.
85// The static header table is searched first. Only when there is no
86// exact match for both name and value, the dynamic header table is
87// then searched. If there is no match, i is 0. If both name and value
88// match, i is the matched index and nameValueMatch becomes true. If
89// only name matches, i points to that index and nameValueMatch
90// becomes false.
91func (e *Encoder) searchTable(f HeaderField) (i uint64, nameValueMatch bool) {
92 i, nameValueMatch = staticTable.search(f)
93 if nameValueMatch {
94 return i, true
95 }
96
97 j, nameValueMatch := e.dynTab.table.search(f)
98 if nameValueMatch || (i == 0 && j != 0) {
99 return j + uint64(staticTable.len()), nameValueMatch
100 }
101
102 return i, false
103}
104
105// SetMaxDynamicTableSize changes the dynamic header table size to v.
106// The actual size is bounded by the value passed to
107// SetMaxDynamicTableSizeLimit.
108func (e *Encoder) SetMaxDynamicTableSize(v uint32) {
109 if v > e.maxSizeLimit {
110 v = e.maxSizeLimit
111 }
112 if v < e.minSize {
113 e.minSize = v
114 }
115 e.tableSizeUpdate = true
116 e.dynTab.setMaxSize(v)
117}
118
119// MaxDynamicTableSize returns the current dynamic header table size.
120func (e *Encoder) MaxDynamicTableSize() (v uint32) {
121 return e.dynTab.maxSize
122}
123
124// SetMaxDynamicTableSizeLimit changes the maximum value that can be
125// specified in SetMaxDynamicTableSize to v. By default, it is set to
126// 4096, which is the same size of the default dynamic header table
127// size described in HPACK specification. If the current maximum
128// dynamic header table size is strictly greater than v, "Header Table
129// Size Update" will be done in the next WriteField call and the
130// maximum dynamic header table size is truncated to v.
131func (e *Encoder) SetMaxDynamicTableSizeLimit(v uint32) {
132 e.maxSizeLimit = v
133 if e.dynTab.maxSize > v {
134 e.tableSizeUpdate = true
135 e.dynTab.setMaxSize(v)
136 }
137}
138
139// shouldIndex reports whether f should be indexed.
140func (e *Encoder) shouldIndex(f HeaderField) bool {
141 return !f.Sensitive && f.Size() <= e.dynTab.maxSize
142}
143
144// appendIndexed appends index i, as encoded in "Indexed Header Field"
145// representation, to dst and returns the extended buffer.
146func appendIndexed(dst []byte, i uint64) []byte {
147 first := len(dst)
148 dst = appendVarInt(dst, 7, i)
149 dst[first] |= 0x80
150 return dst
151}
152
153// appendNewName appends f, as encoded in one of "Literal Header field
154// - New Name" representation variants, to dst and returns the
155// extended buffer.
156//
157// If f.Sensitive is true, "Never Indexed" representation is used. If
158// f.Sensitive is false and indexing is true, "Incremental Indexing"
159// representation is used.
160func appendNewName(dst []byte, f HeaderField, indexing bool) []byte {
161 dst = append(dst, encodeTypeByte(indexing, f.Sensitive))
162 dst = appendHpackString(dst, f.Name)
163 return appendHpackString(dst, f.Value)
164}
165
166// appendIndexedName appends f and index i referring indexed name
167// entry, as encoded in one of "Literal Header field - Indexed Name"
168// representation variants, to dst and returns the extended buffer.
169//
170// If f.Sensitive is true, "Never Indexed" representation is used. If
171// f.Sensitive is false and indexing is true, "Incremental Indexing"
172// representation is used.
173func appendIndexedName(dst []byte, f HeaderField, i uint64, indexing bool) []byte {
174 first := len(dst)
175 var n byte
176 if indexing {
177 n = 6
178 } else {
179 n = 4
180 }
181 dst = appendVarInt(dst, n, i)
182 dst[first] |= encodeTypeByte(indexing, f.Sensitive)
183 return appendHpackString(dst, f.Value)
184}
185
186// appendTableSize appends v, as encoded in "Header Table Size Update"
187// representation, to dst and returns the extended buffer.
188func appendTableSize(dst []byte, v uint32) []byte {
189 first := len(dst)
190 dst = appendVarInt(dst, 5, uint64(v))
191 dst[first] |= 0x20
192 return dst
193}
194
195// appendVarInt appends i, as encoded in variable integer form using n
196// bit prefix, to dst and returns the extended buffer.
197//
198// See
199// https://httpwg.org/specs/rfc7541.html#integer.representation
200func appendVarInt(dst []byte, n byte, i uint64) []byte {
201 k := uint64((1 << n) - 1)
202 if i < k {
203 return append(dst, byte(i))
204 }
205 dst = append(dst, byte(k))
206 i -= k
207 for ; i >= 128; i >>= 7 {
208 dst = append(dst, byte(0x80|(i&0x7f)))
209 }
210 return append(dst, byte(i))
211}
212
213// appendHpackString appends s, as encoded in "String Literal"
214// representation, to dst and returns the extended buffer.
215//
216// s will be encoded in Huffman codes only when it produces strictly
217// shorter byte string.
218func appendHpackString(dst []byte, s string) []byte {
219 huffmanLength := HuffmanEncodeLength(s)
220 if huffmanLength < uint64(len(s)) {
221 first := len(dst)
222 dst = appendVarInt(dst, 7, huffmanLength)
223 dst = AppendHuffmanString(dst, s)
224 dst[first] |= 0x80
225 } else {
226 dst = appendVarInt(dst, 7, uint64(len(s)))
227 dst = append(dst, s...)
228 }
229 return dst
230}
231
232// encodeTypeByte returns type byte. If sensitive is true, type byte
233// for "Never Indexed" representation is returned. If sensitive is
234// false and indexing is true, type byte for "Incremental Indexing"
235// representation is returned. Otherwise, type byte for "Without
236// Indexing" is returned.
237func encodeTypeByte(indexing, sensitive bool) byte {
238 if sensitive {
239 return 0x10
240 }
241 if indexing {
242 return 0x40
243 }
244 return 0
245}