mirror of
https://github.com/apple/swift-nio-http2
synced 2026-11-22 04:30:43 +00:00
Motivation: This is the beginning of removing the dependency on `nghttp2`. Modifications: I've added a new library target, `NIOHPACK`, which contains all the necessary pieces to implement HPACK encoding as specified in RFC 7541. There are unit tests exercising all the code and some additional edge cases around integer encoding, along with some performance tests for the Huffman encode/decode process. The latter currently takes longer to decode than to encode, which is worrying, but this is only really noticeable when encoding > 16KB strings as a rule; therefore I've decided not to pull out the optimization hammer just yet. Included in the unit tests are the inputs and outputs from all the examples in RFC 7541 and RFC 7540. I've tried to match the coding style from the repo, but some of my own idioms may have crept in here & there. Please let me know if you see anything wrong in that regard. Currently the static header table and Huffman encoding tables are implemented as Swift `let`s. For the static header table that's ok (only 62 entries), but the Huffman table is huge. I'm debating whether it's worth having that in a plain C file somewhere, but I'm not sure what the tradeoffs are vs. performance. Right now it seems to only affect compilation time, but I may be wrong. Result: In general, nothing will change: nothing in NIOHTTP2 is using this library yet. That part is what I'm working on now.
298 lines
13 KiB
Swift
298 lines
13 KiB
Swift
//===----------------------------------------------------------------------===//
|
|
//
|
|
// This source file is part of the SwiftNIO open source project
|
|
//
|
|
// Copyright (c) 2017-2018 Apple Inc. and the SwiftNIO project authors
|
|
// Licensed under Apache License v2.0
|
|
//
|
|
// See LICENSE.txt for license information
|
|
// See CONTRIBUTORS.txt for the list of SwiftNIO project authors
|
|
//
|
|
// SPDX-License-Identifier: Apache-2.0
|
|
//
|
|
//===----------------------------------------------------------------------===//
|
|
|
|
import NIO
|
|
|
|
/// An `HPACKEncoder` maintains its own dynamic header table and uses that to
|
|
/// encode HTTP headers to an internal byte buffer.
|
|
///
|
|
/// This encoder functions as an accumulator: each encode operation will append
|
|
/// bytes to a buffer maintained by the encoder, which must be cleared using
|
|
/// `reset()` before the encode can be re-used. It maintains a header table for
|
|
/// outbound header indexing, and will update the header table as described in
|
|
/// RFC 7541, appending and evicting items as described there.
|
|
public struct HPACKEncoder {
|
|
/// The default size of the encoder's dynamic header table.
|
|
public static var defaultDynamicTableSize: Int { return DynamicHeaderTable.defaultSize }
|
|
private static let defaultDataBufferSize = 128
|
|
|
|
public struct HeaderDefinition {
|
|
var name: String
|
|
var value: String
|
|
var indexing: HPACKIndexing
|
|
}
|
|
|
|
private enum EncoderState {
|
|
case idle
|
|
case resized(smallestMaxTableSize: Int?)
|
|
case encoding
|
|
}
|
|
|
|
// private but tests
|
|
var headerIndexTable: IndexedHeaderTable
|
|
|
|
private var state: EncoderState
|
|
private var buffer: ByteBuffer!
|
|
|
|
/// Whether to use Huffman encoding.
|
|
public let useHuffmanEncoding: Bool
|
|
|
|
/// The current size of the dynamic table.
|
|
///
|
|
/// This is defined as the sum of [name] + [value] + 32 for each header.
|
|
public var dynamicTableSize: Int {
|
|
return self.headerIndexTable.dynamicTableLength
|
|
}
|
|
|
|
/// The current maximum size to which the dynamic header table may grow.
|
|
public private(set) var allowedDynamicTableSize: Int {
|
|
get { return self.headerIndexTable.dynamicTableAllowedLength }
|
|
set { self.headerIndexTable.dynamicTableAllowedLength = newValue }
|
|
}
|
|
|
|
/// The hard maximum size of the dynamic header table, set via an HTTP/2
|
|
/// SETTINGS frame.
|
|
public var maximumDynamicTableSize: Int {
|
|
get { return self.headerIndexTable.maxDynamicTableLength }
|
|
set { self.headerIndexTable.maxDynamicTableLength = newValue }
|
|
}
|
|
|
|
/// Sets the maximum size for the dynamic table and encodes the new value
|
|
/// at the start of the current packed header block to send to the peer.
|
|
///
|
|
/// - Parameter size: The new maximum size for the dynamic header table.
|
|
/// - Throws: If the encoder is currently in use, or if the requested size
|
|
/// exceeds the maximum value negotiated with the peer.
|
|
public mutating func setDynamicTableSize(_ size: Int) throws {
|
|
guard size <= self.maximumDynamicTableSize else {
|
|
throw NIOHPACKErrors.InvalidDynamicTableSize(requestedSize: size, allowedSize: self.maximumDynamicTableSize)
|
|
}
|
|
guard size != self.allowedDynamicTableSize else {
|
|
// no need to change anything
|
|
return
|
|
}
|
|
|
|
switch self.state {
|
|
case .idle:
|
|
self.state = .resized(smallestMaxTableSize: nil)
|
|
case .resized(nil) where size > self.allowedDynamicTableSize:
|
|
self.state = .resized(smallestMaxTableSize: self.allowedDynamicTableSize)
|
|
case .resized(let smallest?) where size < smallest:
|
|
self.state = .resized(smallestMaxTableSize: nil)
|
|
case .encoding:
|
|
throw NIOHPACKErrors.EncoderAlreadyActive()
|
|
default:
|
|
// we don't need to change smallest recorded resize value
|
|
break
|
|
}
|
|
|
|
// set the new size on our dynamic table
|
|
self.allowedDynamicTableSize = size
|
|
}
|
|
|
|
/// Initializer and returns a new HPACK encoder.
|
|
///
|
|
/// - Parameters:
|
|
/// - allocator: An allocator for `ByteBuffer`s.
|
|
/// - maxDynamicTableSize: An initial maximum size for the encoder's dynamic header table.
|
|
public init(allocator: ByteBufferAllocator, useHuffmanEncoding: Bool = true, maxDynamicTableSize: Int = HPACKEncoder.defaultDynamicTableSize) {
|
|
self.headerIndexTable = IndexedHeaderTable(allocator: allocator, maxDynamicTableSize: maxDynamicTableSize)
|
|
self.useHuffmanEncoding = useHuffmanEncoding
|
|
self.state = .idle
|
|
}
|
|
|
|
/// Sets up the encoder to begin encoding a new header block.
|
|
///
|
|
/// - Parameter allocator: Used to allocate the `ByteBuffer` that will contain the encoded
|
|
/// bytes, obtained from `endEncoding()`.
|
|
public mutating func beginEncoding(allocator: ByteBufferAllocator) throws {
|
|
if case .encoding = self.state {
|
|
throw NIOHPACKErrors.EncoderAlreadyActive()
|
|
}
|
|
|
|
// create a buffer
|
|
self.buffer = allocator.buffer(capacity: 128) // arbitrary size
|
|
switch self.state {
|
|
case .idle:
|
|
self.state = .encoding
|
|
case .resized(nil):
|
|
// one resize
|
|
self.buffer.write(encodedInteger: UInt(self.allowedDynamicTableSize), prefix: 5, prefixBits: 0x20)
|
|
self.state = .encoding
|
|
case let .resized(smallestSize?):
|
|
// two resizes, one smaller than the other
|
|
self.buffer.write(encodedInteger: UInt(smallestSize), prefix: 5, prefixBits: 0x20)
|
|
self.buffer.write(encodedInteger: UInt(self.allowedDynamicTableSize), prefix: 5, prefixBits: 0x20)
|
|
self.state = .encoding
|
|
default:
|
|
break
|
|
}
|
|
}
|
|
|
|
/// Finishes encoding the current header block and returns the resulting buffer.
|
|
public mutating func endEncoding() throws -> ByteBuffer {
|
|
guard case .encoding = self.state else {
|
|
throw NIOHPACKErrors.EncoderNotStarted()
|
|
}
|
|
|
|
self.state = .idle
|
|
defer { self.buffer = nil }
|
|
return self.buffer
|
|
}
|
|
|
|
/// Appends() headers in the default fashion: indexed if possible, literal+indexable if not.
|
|
///
|
|
/// - Parameter headers: A sequence of key/value pairs representing HTTP headers.
|
|
public mutating func append<S: Sequence>(headers: S) throws where S.Element == (name: String, value: String) {
|
|
try self.append(headers: headers.lazy.map { HeaderDefinition(name: $0.0, value: $0.1, indexing: .indexable) })
|
|
}
|
|
|
|
/// Appends headers with their specified indexability.
|
|
///
|
|
/// - Parameter headers: A sequence of key/value/indexability tuples representing HTTP headers.
|
|
public mutating func append<S : Sequence>(headers: S) throws where S.Element == HeaderDefinition {
|
|
guard case .encoding = self.state else {
|
|
throw NIOHPACKErrors.EncoderNotStarted()
|
|
}
|
|
|
|
for header in headers {
|
|
switch header.indexing {
|
|
case .indexable:
|
|
try self._appendIndexed(header: header.name.utf8, value: header.value.utf8)
|
|
case .nonIndexable:
|
|
self._appendNonIndexed(header: header.name.utf8, value: header.value.utf8)
|
|
case .neverIndexed:
|
|
self._appendNeverIndexed(header: header.name.utf8, value: header.value.utf8)
|
|
}
|
|
}
|
|
}
|
|
|
|
/// Appends a set of headers with their associated indexability.
|
|
///
|
|
/// - Parameter headers: A `HPACKHeaders` structure containing a set of HTTP/2 header values.
|
|
public mutating func append(headers: HPACKHeaders) throws {
|
|
guard case .encoding = self.state else {
|
|
throw NIOHPACKErrors.EncoderNotStarted()
|
|
}
|
|
|
|
for header in headers.headerIndices {
|
|
let nameView = headers.view(of: header.name)
|
|
let valueView = headers.view(of: header.value)
|
|
|
|
switch header.indexing {
|
|
case .indexable:
|
|
try self._appendIndexed(header: nameView, value: valueView)
|
|
case .nonIndexable:
|
|
self._appendNonIndexed(header: nameView, value: valueView)
|
|
case .neverIndexed:
|
|
self._appendNeverIndexed(header: nameView, value: valueView)
|
|
}
|
|
}
|
|
}
|
|
|
|
/// Appends a header/value pair, using indexed names/values if possible. If no indexed pair is available,
|
|
/// it will use an indexed header and literal value, or a literal header and value. The name/value pair
|
|
/// will be indexed for future use.
|
|
public mutating func append(header name: String, value: String) throws {
|
|
guard case .encoding = self.state else {
|
|
throw NIOHPACKErrors.EncoderNotStarted()
|
|
}
|
|
try self._appendIndexed(header: name.utf8, value: value.utf8)
|
|
}
|
|
|
|
/// Returns `true` if the item needs to be added to the header table
|
|
private mutating func _appendIndexed<Name: Collection, Value: Collection>(header name: Name, value: Value) throws where Name.Element == UInt8, Value.Element == UInt8 {
|
|
if let (index, hasValue) = self.headerIndexTable.firstHeaderMatch(for: name, value: value) {
|
|
if hasValue {
|
|
// purely indexed. Nice & simple.
|
|
self.buffer.write(encodedInteger: UInt(index), prefix: 7, prefixBits: 0x80)
|
|
// everything is indexed-- nothing more to do!
|
|
return
|
|
} else {
|
|
// no value, so append the index to represent the name, followed by the value's
|
|
// length
|
|
self.buffer.write(encodedInteger: UInt(index), prefix: 6, prefixBits: 0x40)
|
|
// now encode and append the value string
|
|
self.appendEncodedString(value)
|
|
}
|
|
} else {
|
|
// no indexed name or value. Have to add them both, with a zero index.
|
|
self.buffer.write(integer: UInt8(0x40))
|
|
self.appendEncodedString(name)
|
|
self.appendEncodedString(value)
|
|
}
|
|
|
|
// add to the header table
|
|
try self.headerIndexTable.add(headerNamed: name, value: value)
|
|
}
|
|
|
|
private mutating func appendEncodedString<C: Collection>(_ utf8: C) where C.Element == UInt8 {
|
|
// encode the value
|
|
if self.useHuffmanEncoding {
|
|
// problem: we need to encode the length before the encoded bytes, so we can't just receive the length
|
|
// after encoding to the target buffer itself. So we have to determine the length first.
|
|
self.buffer.write(encodedInteger: UInt(ByteBuffer.huffmanEncodedLength(of: utf8)), prefix: 7, prefixBits: 0x80)
|
|
self.buffer.writeHuffmanEncoded(bytes: utf8)
|
|
} else {
|
|
self.buffer.write(encodedInteger: UInt(utf8.count), prefix: 7, prefixBits: 0)
|
|
self.buffer.write(bytes: utf8)
|
|
}
|
|
}
|
|
|
|
/// Appends a header that is *not* to be entered into the dynamic header table, but allows that
|
|
/// stipulation to be overriden by a proxy server/rewriter.
|
|
public mutating func appendNonIndexed(header: String, value: String) throws {
|
|
guard case .encoding = self.state else {
|
|
throw NIOHPACKErrors.EncoderNotStarted()
|
|
}
|
|
self._appendNonIndexed(header: header.utf8, value: value.utf8)
|
|
}
|
|
|
|
private mutating func _appendNonIndexed<Name: Collection, Value: Collection>(header: Name, value: Value) where Name.Element == UInt8, Value.Element == UInt8 {
|
|
if let (index, _) = self.headerIndexTable.firstHeaderMatch(for: header, value: value) {
|
|
// we actually don't care if it has a value in this instance; we're only indexing the
|
|
// name.
|
|
self.buffer.write(encodedInteger: UInt(index), prefix: 4, prefixBits: 0)
|
|
// now append the value
|
|
self.appendEncodedString(value)
|
|
} else {
|
|
self.buffer.write(integer: UInt8(0)) // top 4 bits are zero, and index is zero (no index)
|
|
self.appendEncodedString(header)
|
|
self.appendEncodedString(value)
|
|
}
|
|
}
|
|
|
|
/// Appends a header that is *never* indexed, preventing even rewriting proxies from doing so.
|
|
public mutating func appendNeverIndexed(header: String, value: String) throws {
|
|
guard case .encoding = self.state else {
|
|
throw NIOHPACKErrors.EncoderNotStarted()
|
|
}
|
|
self._appendNeverIndexed(header: header.utf8, value: value.utf8)
|
|
}
|
|
|
|
private mutating func _appendNeverIndexed<Name: Collection, Value: Collection>(header: Name, value: Value) where Name.Element == UInt8, Value.Element == UInt8 {
|
|
// compiler doesn't like us passing `nil` here as it can't infer the types, apparently.
|
|
if let (index, _) = self.headerIndexTable.firstHeaderMatch(for: header, value: Optional<Value>.none) {
|
|
// we only use the index in this instance
|
|
self.buffer.write(encodedInteger: UInt(index), prefix: 4, prefixBits: 0x10)
|
|
// now append the value
|
|
self.appendEncodedString(value)
|
|
} else {
|
|
self.buffer.write(integer: UInt8(0x10)) // prefix bits + zero index
|
|
self.appendEncodedString(header)
|
|
self.appendEncodedString(value)
|
|
}
|
|
}
|
|
}
|