The http2 Reference Manual

4.1.1 http2/http2.asd

Source

http2.asd.

Parent Component

http2 (system).

ASDF Systems

http2.

---

4.1.2 http2/package.lisp

Source

http2.asd.

Parent Component

http2 (system).

Packages

• http2.
• http2/hpack.

---

4.1.3 http2/core/utils.lisp

Source

http2.asd.

Parent Component

core (module).

Public Interface

• +no-error+ (constant).
• read-byte* (function).

Internals

• *bytes-left* (special variable).
• *bytes-to-possibly-reuse* (special variable).
• *bytes-to-reuse* (special variable).
• *error-codes* (special variable).
• *log-stream* (special variable).
• *settings* (special variable).
• *when-no-bytes-left-fn* (special variable).
• +cancel+ (constant).
• +compression-error+ (constant).
• +connect-error+ (constant).
• +enhance-your-calm+ (constant).
• +flow-control-error+ (constant).
• +frame-size-error+ (constant).
• +http-1-1-required+ (constant).
• +inadequate-security+ (constant).
• +internal-error+ (constant).
• +protocol-error+ (constant).
• +refused-stream+ (constant).
• +settings-timeout+ (constant).
• +stream-closed+ (constant).
• find-setting-by-id (function).
• find-setting-code (function).
• get-error-name (function).
• logger (function).
• read-bytes (function).
• vector-from-hex-text (function).
• write-bytes (function).

---

4.1.4 http2/core/frames.lisp

Source

http2.asd.

Parent Component

core (module).

Public Interface

• read-frame (function).
• write-ack-setting-frame (function).
• write-altsvc-frame (function).
• write-continuation-frame (function).
• write-data-frame (function).
• write-frame-header (function).
• write-goaway-frame (function).
• write-headers-frame (function).
• write-ping-frame (function).
• write-priority-frame (function).
• write-push-promise-frame (function).
• write-rst-stream-frame (function).
• write-settings-frame (function).
• write-window-update-frame (function).

Internals

• *flag-codes* (special variable).
• *frame-types* (special variable).
• +altsvc-frame+ (constant).
• +continuation-frame+ (constant).
• +data-frame+ (constant).
• +goaway-frame+ (constant).
• +headers-frame+ (constant).
• +known-frame-types-count+ (constant).
• +ping-frame+ (constant).
• +priority-frame+ (constant).
• +push-promise-frame+ (constant).
• +rst-stream-frame+ (constant).
• +settings-frame+ (constant).
• +window-update-frame+ (constant).
• account-frame-window-contribution (function).
• copy-frame-type (function).
• create-new-local-stream (function).
• define-frame-type (macro).
• flags-to-code (function).
• flags-to-vars-code (function).
• frame-type (structure).
• frame-type-documentation (reader).
• (setf frame-type-documentation) (writer).
• frame-type-name (reader).
• (setf frame-type-name) (writer).
• frame-type-p (function).
• frame-type-receive-fn (reader).
• (setf frame-type-receive-fn) (writer).
• make-frame-type (function).
• read-altsvc-frame (function).
• read-and-add-headers (function).
• read-continuation-frame (function).
• read-data-frame (function).
• read-goaway-frame (function).
• read-headers-frame (function).
• read-padding (function).
• read-ping-frame (function).
• read-priority-frame (function).
• read-push-promise-frame (function).
• read-rst-stream-frame (function).
• read-settings-frame (function).
• read-window-update-frame (function).
• set-when-no-bytes-left-fn (function).
• write-31-bits (function).

---

4.1.5 http2/core/classes.lisp

Source

http2.asd.

Parent Component

core (module).

Public Interface

• *do-print-log* (special variable).
• apply-data-frame (generic function).
• apply-stream-priority (generic function).
• apply-window-size-increment (generic function).
• client-http2-connection (class).
• client-stream (class).
• close (method).
• do-goaway (generic function).
• do-pong (generic function).
• get-body (reader method).
• (setf get-body) (writer method).
• get-connection (reader method).
• (setf get-connection) (writer method).
• get-headers (reader method).
• (setf get-headers) (writer method).
• get-path (reader method).
• (setf get-path) (writer method).
• get-status (reader method).
• (setf get-status) (writer method).
• handle-undefined-frame (generic function).
• header-collecting-mixin (class).
• history-printing-object (class).
• initialize-instance (method).
• initialize-instance (method).
• logging-object (class).
• peer-acks-settings (generic function).
• peer-ends-http-stream (generic function).
• peer-expects-settings-ack (generic function).
• peer-opens-http-stream (generic function).
• peer-resets-stream (generic function).
• peer-sends-push-promise (generic function).
• print-object (method).
• print-object (method).
• print-object (method).
• print-object (method).
• send-headers (function).
• send-ping (generic function).
• set-peer-setting (generic function).
• timeshift-pinging-connection (class).

Internals

• +client-preface-start+ (special variable).
• add-header (generic function).
• add-log (generic function).
• body-collecting-mixin (class).
• check-place-empty-and-set-it (macro).
• count-open-streams (function).
• do-ping (generic function).
• dynamic-table-entry-size (function).
• flow-control-mixin (class).
• get-acked-settings (reader method).
• (setf get-acked-settings) (writer method).
• get-authority (reader method).
• (setf get-authority) (writer method).
• get-compression-context (reader method).
• (setf get-compression-context) (writer method).
• get-data (reader method).
• (setf get-data) (writer method).
• get-debug-data (reader method).
• get-debug-data (reader method).
• (setf get-debug-data) (writer method).
• (setf get-debug-data) (writer method).
• get-decompression-context (reader method).
• (setf get-decompression-context) (writer method).
• get-depends-on (reader method).
• (setf get-depends-on) (writer method).
• get-error-code (reader method).
• get-error-code (reader method).
• get-error-code (reader method).
• (setf get-error-code) (writer method).
• (setf get-error-code) (writer method).
• (setf get-error-code) (writer method).
• get-history (function).
• get-id-to-use (reader method).
• (setf get-id-to-use) (writer method).
• get-initial-peer-window-size (reader method).
• (setf get-initial-peer-window-size) (writer method).
• get-initial-window-size (reader method).
• (setf get-initial-window-size) (writer method).
• get-last-id-seen (reader method).
• (setf get-last-id-seen) (writer method).
• get-last-stream-id (reader method).
• get-last-stream-id (reader method).
• (setf get-last-stream-id) (writer method).
• (setf get-last-stream-id) (writer method).
• get-max-frame-size (reader method).
• (setf get-max-frame-size) (writer method).
• get-max-peer-frame-size (reader method).
• (setf get-max-peer-frame-size) (writer method).
• get-method (reader method).
• (setf get-method) (writer method).
• get-network-stream (reader method).
• get-network-stream (reader method).
• (setf get-network-stream) (writer method).
• (setf get-network-stream) (writer method).
• get-peer-accepts-push (reader method).
• (setf get-peer-accepts-push) (writer method).
• get-peer-window-size (reader method).
• (setf get-peer-window-size) (writer method).
• get-reversed-history (reader method).
• (setf get-reversed-history) (writer method).
• get-scheme (reader method).
• (setf get-scheme) (writer method).
• get-seen-text-header (reader method).
• (setf get-seen-text-header) (writer method).
• get-settings (generic function).
• get-state (reader method).
• (setf get-state) (method).
• (setf get-state) (writer method).
• get-stream (reader method).
• (setf get-stream) (writer method).
• get-stream-class (reader method).
• (setf get-stream-class) (writer method).
• get-stream-id (reader method).
• get-stream-id (reader method).
• (setf get-stream-id) (writer method).
• (setf get-stream-id) (writer method).
• get-streams (reader method).
• (setf get-streams) (writer method).
• get-weight (reader method).
• (setf get-weight) (writer method).
• get-window-size (reader method).
• (setf get-window-size) (writer method).
• go-away (condition).
• handle-alt-svc (generic function).
• history-keeping-object (class).
• http-stream-error (condition).
• http2-connection (class).
• http2-error (function).
• http2-stream (class).
• log-headers-mixin (class).
• logging-connection (class).
• logging-stream (class).
• maybe-lock-for-write (generic function).
• maybe-unlock-for-write (generic function).
• open-http2-stream (function).
• peer-opens-http-stream-really-open (function).
• peer-should-go-away (condition).
• process-end-headers (generic function).
• read-client-preface (function).
• send-stream-error (generic function).
• server-http2-connection (class).
• server-stream (class).

---

4.1.6 http2/core/hpack.lisp

Source

http2.asd.

Parent Component

core (module).

Public Interface

• compile-headers (function).
• decode-huffman (function).
• dynamic-table-value (function).
• encode-header (function).
• get-bytes-left-in-table (reader method).
• (setf get-bytes-left-in-table) (writer method).
• get-deleted-items (reader method).
• (setf get-deleted-items) (writer method).
• get-dynamic-table (reader method).
• (setf get-dynamic-table) (writer method).
• get-dynamic-table-size (reader method).
• (setf get-dynamic-table-size) (writer method).
• get-integer-from-octet (function).
• get-updates-needed (reader method).
• (setf get-updates-needed) (writer method).
• hpack-context (class).
• integer-to-array (function).
• read-http-header (function).
• request-headers (function).
• update-dynamic-table-size (function).

Internals

• *huffman-code* (special variable).
• *use-huffman-coding-by-default* (special variable).
• +last-static-header-index+ (constant).
• +last-static-header-pair+ (constant).
• +literal-header-index+ (constant).
• +literal-header-never-index+ (constant).
• +literal-header-noindex+ (constant).
• add-dynamic-header (method).
• compute-header-size (function).
• compute-update-dynamic-size-codes (function).
• context-table-element (type).
• decode-huffman-to-stream (function).
• decode-octet-fn (function).
• encode-dynamic-table-update (function).
• encode-huffman (function).
• find-header-in-tables (function).
• find-in-tables (function).
• find-pair-in-tables (function).
• header-writer (function).
• huffman-coded-size (function).
• make-cond-branch (function).
• read-from-tables (function).
• read-huffman (function).
• read-literal-header-field-new-name (function).
• read-literal-header-indexed-name (function).
• read-string-from-stream (function).
• static-headers-table (special variable).
• store-string (function).
• vector-index-to-hpack-index (function).
• write-indexed-header-pair (function).
• write-indexed-name (function).
• write-integer-to-array (function).
• write-literal-header-pair (function).

---

4.1.7 http2/core/payload-streams.lisp

Source

http2.asd.

Parent Component

core (module).

Public Interface

• apply-data-frame (method).
• close (method).
• close (method).
• extract-charset-from-content-type (function).
• http-stream-to-vector (function).
• initialize-instance (method).
• initialize-instance (method).
• make-transport-output-stream (function).
• stream-element-type (method).
• stream-force-output (method).
• stream-listen (method).
• stream-read-byte (method).
• stream-write-byte (method).
• stream-write-sequence (method).

Internals

• *charset-names* (special variable).
• *default-encoding* (special variable).
• *default-text-encoding* (special variable).
• binary-stream (class).
• empty-data-p (function).
• get-base-http2-stream (reader method).
• (setf get-base-http2-stream) (writer method).
• get-charset (reader method).
• (setf get-charset) (writer method).
• get-compression (reader method).
• (setf get-compression) (writer method).
• get-data (reader method).
• (setf get-data) (writer method).
• get-index (reader method).
• (setf get-index) (writer method).
• get-output-buffer (reader method).
• (setf get-output-buffer) (writer method).
• get-payload-input-stream (reader method).
• (setf get-payload-input-stream) (writer method).
• http2-stream-with-input-stream (class).
• make-transport-input-stream (function).
• make-transport-input-stream-from-stream (function).
• make-transport-output-stream-from-stream (function).
• payload-input-stream (class).
• payload-output-stream (class).
• payload-stream (class).
• pop-frame (function).
• push-frame (function).
• send-data (function).
• with-output-payload-slots (macro).

---

6.1.1 Constants

Constant: +no-error+ ¶

graceful shutdown

Package

http2.

Source

utils.lisp.

---

6.1.2 Special variables

Special Variable: *do-print-log* ¶

Set to true value to log to the *TRACE-OUTPUT*.

Package

http2.

Source

classes.lisp.

---

6.1.3 Ordinary functions

Function: compile-headers (headers context) ¶

Package

http2/hpack.

Source

hpack.lisp.

Function: decode-huffman (bytes) ¶

Package

http2/hpack.

Source

hpack.lisp.

Function: dynamic-table-value (context idx) ¶

Header on position IDX in the dynamic table in CONTEXT.

This is factored out to be used in testing.

Package

http2/hpack.

Source

hpack.lisp.

Function: encode-header (name value &optional context huffman) ¶

Encode header consisting of NAME and VALUE.

The ‘never-indexed‘ format is never generated,
use a separate function for this (and this function needs to be written).

When CONTEXT is provided, use incremental indexing with dynamic table in that CONTEXT.

Use Huffman when HUFFMAN is true.

Package

http2/hpack.

Source

hpack.lisp.

Function: extract-charset-from-content-type (content-type) ¶

Guess charset from the content type. NIL for binary data.

Package

http2.

Source

payload-streams.lisp.

Function: get-integer-from-octet (stream initial-octet bit-size) ¶

Decode an integer from starting OCTET and additional octets in STREAM as defined in RFC7541 sect. 5.1.

Package

http2/hpack.

Source

hpack.lisp.

Function: http-stream-to-vector (raw-stream) ¶

Read HTTP2 stream payload data, do guessed conversions and return either
string or octets vector. You can expect the HTTP2 stream to be closed after calling this.

Package

http2.

Source

payload-streams.lisp.

Function: integer-to-array (integer bit-size mask) ¶

Represent integer to a vector as defined in RFC7541 sect. 5.1.

Package

http2/hpack.

Source

hpack.lisp.

Function: make-transport-output-stream (raw-stream charset gzip) ¶

An OUTPUT-STREAM built atop RAW STREAM with added text to binary encoding using charset (as understood by flexi-streams) and possibly gzip compression.

Package

http2.

Source

payload-streams.lisp.

Function: read-byte* (stream) ¶

Package

http2/hpack.

Source

utils.lisp.

Function: read-frame (connection &optional stream) ¶

All frames begin with a fixed 9-octet header followed by a variable- length payload.

#+begin_src artist +———————————————–+
| Length (24) | +—————+—————+—————+
| Type (8) | Flags (8) | +-+————-+—————+——————————-+ |R| Stream Identifier (31) | +=+=============================================================+ | Frame Payload (0...) ... +—————————————————————+ #+end_src

Length: The length of the frame payload expressed as an unsigned 24-bit integer. Values greater than 2^14 (16,384) MUST NOT be sent unless the receiver has set a larger value for SETTINGS_MAX_FRAME_SIZE.

The 9 octets of the frame header are not included in this value.

Type: The 8-bit type of the frame. The frame type determines the format and semantics of the frame. Implementations MUST ignore and discard any frame that has a type that is unknown.

Flags: An 8-bit field reserved for boolean flags specific to the frame type.

Flags are assigned semantics specific to the indicated frame type. Flags that have no defined semantics for a particular frame type MUST be ignored and MUST be left unset (0x0) when sending.

R: A reserved 1-bit field. The semantics of this bit are undefined, and the bit MUST remain unset (0x0) when sending and MUST be ignored when receiving.

Stream Identifier: A stream identifier (see Section 5.1.1) expressed as an unsigned 31-bit integer. The value 0x0 is reserved for frames that are associated with the connection as a whole as opposed to an individual stream.

Package

http2.

Source

frames.lisp.

Function: read-http-header (stream context) ¶

Read header field from network stream associated with the CONNECTION.

Package

http2/hpack.

Source

hpack.lisp.

Function: request-headers (method path authority &key scheme content-type gzip-content additional-headers) ¶

Encode standard request headers that are obligatory.

Package

http2/hpack.

Source

hpack.lisp.

Function: send-headers (stream headers &key end-stream end-headers &allow-other-keys) ¶

Send HEADERS to a HTTP2 stream. The stream is returned.

The END-HEADERS and END-STREAM allow to set the appropriate flags.

Package

http2.

Source

classes.lisp.

Function: update-dynamic-table-size (context new-size) ¶

Update dynamic table for new size that is smaller than the previous one.

Zero size means evict completely; in this case the new vector can be cleaned

Package

http2/hpack.

Source

hpack.lisp.

Function: write-ack-setting-frame (stream) ¶

Write ACK settings frame.

ACK (0x1): When set, bit 0 indicates that this frame acknowledges receipt and application of the peer’s SETTINGS frame. When this bit is set, the payload of the SETTINGS frame MUST be empty. Receipt of a SETTINGS frame with the ACK flag set and a length field value other than 0 MUST be treated as a connection error (Section 5.4.1) of type FRAME_SIZE_ERROR. For more information, see Section 6.5.3 ("Settings Synchronization").

Package

http2.

Source

frames.lisp.

Function: write-altsvc-frame (http-connection-or-stream origin alt-svc-field-value &key) ¶

See RFC 7838. The ALTSVC HTTP/2 frame advertises the availability of an alternative service to an HTTP/2 client.

#+begin_src artist +——————————-+——————————-+ | Origin-Len (16) | Origin? (*) ... +——————————-+——————————-+ | Alt-Svc-Field-Value (*) ... +—————————————————————+ #+end_src

Package

http2.

Source

frames.lisp.

Function: write-continuation-frame (http-connection-or-stream headers &key end-headers) ¶

#+begin_src artist

+—————————————————————+
| Header Block Fragment (*) ... +—————————————————————+ #+end_src

The CONTINUATION frame (type=0x9) is used to continue a sequence of header block fragments (Section 4.3). Any number of CONTINUATION frames can be sent, as long as the preceding frame is on the same stream and is a HEADERS, PUSH_PROMISE, or CONTINUATION frame without the END_HEADERS flag set.

Package

http2.

Source

frames.lisp.

Function: write-data-frame (http-connection-or-stream data &key padded end-stream) ¶

#+begin_src artist

+—————+———————————————–+ | Data (*) ... +—————————————————————+ #+end_src

DATA frames (type=0x0) convey arbitrary, variable-length sequences of octets associated with a stream. One or more DATA frames are used, for instance, to carry HTTP request or response payloads.

Package

http2.

Source

frames.lisp.

Function: write-frame-header (stream length type flags http-stream r) ¶

All frames begin with a fixed 9-octet header followed by a variable- length payload.

#+begin_src artist +———————————————–+
| Length (24) | +—————+—————+—————+
| Type (8) | Flags (8) | +-+————-+—————+——————————-+ |R| Stream Identifier (31) | +=+=============================================================+ | Frame Payload (0...) ... +—————————————————————+ #+end_src

Length: The length of the frame payload expressed as an unsigned 24-bit integer. Values greater than 2^14 (16,384) MUST NOT be sent unless the receiver has set a larger value for SETTINGS_MAX_FRAME_SIZE.

The 9 octets of the frame header are not included in this value.

Type: The 8-bit type of the frame. The frame type determines the format and semantics of the frame.

Flags: An 8-bit field reserved for boolean flags specific to the frame type.

Flags are assigned semantics specific to the indicated frame type. Flags that have no defined semantics for a particular frame type MUST be ignored and MUST be left unset (0x0) when sending.

R: A reserved 1-bit field. The semantics of this bit are undefined, and the bit MUST remain unset (0x0) when sending and MUST be ignored when receiving.

Stream Identifier: A stream identifier (see Section 5.1.1) expressed as an unsigned 31-bit integer. The value 0x0 is reserved for frames that are associated with the connection as a whole as opposed to an individual stream.

Package

http2.

Source

frames.lisp.

Function: write-goaway-frame (http-connection-or-stream last-stream-id error-code debug-data &key reserved) ¶

#+begin_src artist +-+————————————————————-+ |R| Last-Stream-ID (31) | +-+————————————————————-+ | Error Code (32) | +—————————————————————+ | Additional Debug Data (*) | +—————————————————————+ #+end_src

The GOAWAY frame (type=0x7) is used to initiate shutdown of a connection or to signal serious error conditions. GOAWAY allows an endpoint to gracefully stop accepting new streams while still finishing processing of previously established streams. This enables administrative actions, like server maintenance.

Package

http2.

Source

frames.lisp.

Function: write-headers-frame (http-connection-or-stream headers &key padded end-stream end-headers priority) ¶

#+begin_src artist

+-+————-+———————————————–+ |E| Stream Dependency? (31) | +-+————-+———————————————–+ | Weight? (8) | +-+————-+———————————————–+ | Header Block Fragment (*) ... +—————————————————————+ #+end_src

The HEADERS frame (type=0x1) is used to open a stream (Section 5.1), and additionally carries a header block fragment. HEADERS frames can be sent on a stream in the "idle", "reserved (local)", "open", or "half-closed (remote)" state.

Package

http2.

Source

frames.lisp.

Function: write-ping-frame (http-connection-or-stream opaque-data &key ack) ¶

The PING frame (type=0x6) is a mechanism for measuring a minimal round-trip time from the sender, as well as determining whether an idle connection is still functional. PING frames can be sent from any endpoint.

#+begin_src artist +—————————————————————+ | | | Opaque Data (64) | | | +—————————————————————+ #+end_src

Figure 12: PING Payload Format

In addition to the frame header, PING frames MUST contain 8 octets of opaque data in the payload. A sender can include any value it chooses and use those octets in any fashion.

Receivers of a PING frame that does not include an ACK flag MUST send a PING frame with the ACK flag set in response, with an identical payload. PING responses SHOULD be given higher priority than any other frame.

The PING frame defines the following flags:

ACK (0x1): When set, bit 0 indicates that this PING frame is a PING response. An endpoint MUST set this flag in PING responses. An endpoint MUST NOT respond to PING frames containing this flag.

Package

http2.

Source

frames.lisp.

Function: write-priority-frame (http-connection-or-stream exclusive stream-dependency weight &key) ¶

The PRIORITY frame (type=0x2) specifies the sender-advised priority of a stream (Section 5.3).

#+begin_src artist +-+————————————————————-+ |E| Stream Dependency (31) | +-+————-+———————————————–+ | Weight (8) |
+-+————-+
#+end_src

The payload of a PRIORITY frame contains the following fields:

E: A single-bit flag indicating that the stream dependency is exclusive (see Section 5.3).

Stream Dependency: A 31-bit stream identifier for the stream that this stream depends on (see Section 5.3).

Weight: An unsigned 8-bit integer representing a priority weight for the stream (see Section 5.3). Add one to the value to obtain a weight between 1 and 256.

Package

http2.

Source

frames.lisp.

Function: write-push-promise-frame (http-connection-or-stream promised-stream-id headers &key reserved padded end-headers) ¶

The PUSH_PROMISE frame (type=0x5) is used to notify the peer endpoint in advance of streams the sender intends to initiate. The PUSH_PROMISE frame includes the unsigned 31-bit identifier of the stream the endpoint plans to create along with a set of headers that provide additional context for the stream. Section 8.2 contains a thorough description of the use of PUSH_PROMISE frames.

#+begin_src artist +-+————-+———————————————–+ |R| Promised Stream ID (31) | +-+—————————–+——————————-+ | Header Block Fragment (*) ... +—————————————————————+ #+end_src

The PUSH_PROMISE frame payload has the following fields:

R: A single reserved bit.

Promised Stream ID: An unsigned 31-bit integer that identifies the stream that is reserved by the PUSH_PROMISE. The promised stream identifier MUST be a valid choice for the next stream sent by the sender (see "new stream identifier" in Section 5.1.1).

Header Block Fragment: A header block fragment (Section 4.3) containing request header fields.

The PUSH_PROMISE frame defines the following flags:

END_HEADERS (0x4): When set, bit 2 indicates that this frame contains an entire header block (Section 4.3) and is not followed by any CONTINUATION frames.

A PUSH_PROMISE frame without the END_HEADERS flag set MUST be followed by a CONTINUATION frame for the same stream. A receiver MUST treat the receipt of any other type of frame or a frame on a different stream as a connection error (Section 5.4.1) of type PROTOCOL_ERROR.

Package

http2.

Source

frames.lisp.

Function: write-rst-stream-frame (http-connection-or-stream error-code &key) ¶

The RST_STREAM frame (type=0x3) allows for immediate termination of a stream. RST_STREAM is sent to request cancellation of a stream or to indicate that an error condition has occurred.

#+begin_src artist +—————————————————————+ | Error Code (32) | +—————————————————————+ #+end_src

The RST_STREAM frame contains a single unsigned, 32-bit integer identifying the error code (Section 7). The error code indicates why the stream is being terminated.

The RST_STREAM frame does not define any flags.

Package

http2.

Source

frames.lisp.

Function: write-settings-frame (http-connection-or-stream settings &key ack) ¶

#+begin_src artist
+——————————-+
| Identifier (16) | +——————————-+——————————-+ | Value (32) | +—————————————————————+ #+end_src

The SETTINGS frame (type=0x4) conveys configuration parameters that affect how endpoints communicate, such as preferences and constraints on peer behavior. The SETTINGS frame is also used to acknowledge the receipt of those parameters. Individually, a SETTINGS parameter can also be referred to as a "setting".

Package

http2.

Source

frames.lisp.

Function: write-window-update-frame (http-connection-or-stream window-size-increment &key reserved) ¶

#+begin_src artist
+-+————————————————————-+
|R| Window Size Increment (31) |
+-+————————————————————-+
#+end_src

The WINDOW_UPDATE frame (type=0x8) is used to implement flow control; see Section 5.2 for an overview. Flow control operates at two levels: on each individual stream and on the entire connection.

Package

http2.

Source

frames.lisp.

---

6.1.4 Generic functions

Generic Function: apply-data-frame (stream payload) ¶

Data frame is received by a stream.
By default does nothing; there are several mixins that implement reading the data.

Package

http2.

Source

classes.lisp.

Methods

Method: apply-data-frame ((stream http2-stream-with-input-stream) frame-data) ¶

Source

payload-streams.lisp.

Method: apply-data-frame (stream payload) ¶

Method: apply-data-frame ((stream body-collecting-mixin) data) ¶

Method: apply-data-frame :before ((stream logging-object) payload) ¶

Generic Function: apply-stream-priority (stream exclusive weight stream-dependency) ¶

Called when priority frame - or other frame with priority settings set - arrives. Does nothing, as priorities are deprecated in RFC9113 anyway.

Package

http2.

Source

classes.lisp.

Methods

Method: apply-stream-priority (stream exclusive weight stream-dependency) ¶

Method: apply-stream-priority :before ((stream logging-object) exclusive weight stream-dependency) ¶

Generic Function: apply-window-size-increment (object increment) ¶

Called on window update frame. By default, increases PEER-WINDOW-SIZE slot of the strem or connection.

Package

http2.

Source

classes.lisp.

Methods

Method: apply-window-size-increment :before ((object logging-object) increment) ¶

Method: apply-window-size-increment (object increment) ¶

Generic Function: do-goaway (connection error-code last-stream-id debug-data) ¶

Called when a go-away frame is received. By default throws GO-AWAY condition if error was reported.

Package

http2.

Source

classes.lisp.

Methods

Method: do-goaway ((connection logging-object) error-code last-stream-id debug-data) ¶

Method: do-goaway ((connection client-http2-connection) error-code last-stream-id debug-data) ¶

Method: do-goaway ((connection server-http2-connection) error-code last-stream-id debug-data) ¶

Generic Function: do-pong (connection data) ¶

Called when ping-frame with ACK is received. By default warns about unexpected ping response; see also TIMESHIFT-PINGING-CONNECTION mixin.

Package

http2.

Source

classes.lisp.

Methods

Method: do-pong :before ((connection logging-object) data) ¶

Method: do-pong (connection data) ¶

Method: do-pong ((connection timeshift-pinging-connection) data) ¶

Generic Reader: get-body (object) ¶

Package

http2.

Methods

Reader Method: get-body ((body-collecting-mixin body-collecting-mixin)) ¶

automatically generated reader method

Source

classes.lisp.

Target Slot

body.

Generic Writer: (setf get-body) (object) ¶

Package

http2.

Methods

Writer Method: (setf get-body) ((body-collecting-mixin body-collecting-mixin)) ¶

automatically generated writer method

Source

classes.lisp.

Target Slot

body.

Generic Reader: get-bytes-left-in-table (object) ¶

Package

http2/hpack.

Methods

Reader Method: get-bytes-left-in-table ((hpack-context hpack-context)) ¶

automatically generated reader method

Source

hpack.lisp.

Target Slot

bytes-left-in-table.

Generic Writer: (setf get-bytes-left-in-table) (object) ¶

Package

http2/hpack.

Methods

Writer Method: (setf get-bytes-left-in-table) ((hpack-context hpack-context)) ¶

automatically generated writer method

Source

hpack.lisp.

Target Slot

bytes-left-in-table.

Generic Reader: get-connection (object) ¶

Package

http2.

Methods

Reader Method: get-connection ((http2-stream http2-stream)) ¶

automatically generated reader method

Source

classes.lisp.

Target Slot

connection.

Generic Writer: (setf get-connection) (object) ¶

Package

http2.

Methods

Writer Method: (setf get-connection) ((http2-stream http2-stream)) ¶

automatically generated writer method

Source

classes.lisp.

Target Slot

connection.

Generic Reader: get-deleted-items (object) ¶

Package

http2/hpack.

Methods

Reader Method: get-deleted-items ((hpack-context hpack-context)) ¶

automatically generated reader method

Source

hpack.lisp.

Target Slot

deleted-items.

Generic Writer: (setf get-deleted-items) (object) ¶

Package

http2/hpack.

Methods

Writer Method: (setf get-deleted-items) ((hpack-context hpack-context)) ¶

automatically generated writer method

Source

hpack.lisp.

Target Slot

deleted-items.

Generic Reader: get-dynamic-table (object) ¶

Package

http2/hpack.

Methods

Reader Method: get-dynamic-table ((hpack-context hpack-context)) ¶

automatically generated reader method

Source

hpack.lisp.

Target Slot

dynamic-table.

Generic Writer: (setf get-dynamic-table) (object) ¶

Package

http2/hpack.

Methods

Writer Method: (setf get-dynamic-table) ((hpack-context hpack-context)) ¶

automatically generated writer method

Source

hpack.lisp.

Target Slot

dynamic-table.

Generic Reader: get-dynamic-table-size (object) ¶

Package

http2/hpack.

Methods

Reader Method: get-dynamic-table-size ((hpack-context hpack-context)) ¶

automatically generated reader method

Source

hpack.lisp.

Target Slot

dynamic-table-size.

Generic Writer: (setf get-dynamic-table-size) (object) ¶

Package

http2/hpack.

Methods

Writer Method: (setf get-dynamic-table-size) ((hpack-context hpack-context)) ¶

automatically generated writer method

Source

hpack.lisp.

Target Slot

dynamic-table-size.

Generic Reader: get-headers (object) ¶

Package

http2.

Methods

Reader Method: get-headers ((header-collecting-mixin header-collecting-mixin)) ¶

automatically generated reader method

Source

classes.lisp.

Target Slot

headers.

Generic Writer: (setf get-headers) (object) ¶

Package

http2.

Methods

Writer Method: (setf get-headers) ((header-collecting-mixin header-collecting-mixin)) ¶

automatically generated writer method

Source

classes.lisp.

Target Slot

headers.

Generic Reader: get-path (object) ¶

Generic Writer: (setf get-path) (object) ¶

Package

http2.

Methods

Reader Method: get-path ((server-stream server-stream)) ¶

Writer Method: (setf get-path) ((server-stream server-stream)) ¶

The path and query parts of the target URI

Source

classes.lisp.

Target Slot

path.

Generic Reader: get-status (object) ¶

Generic Writer: (setf get-status) (object) ¶

Package

http2.

Methods

Reader Method: get-status ((client-stream client-stream)) ¶

Writer Method: (setf get-status) ((client-stream client-stream)) ¶

HTTP status code field (see [RFC7231], Section 6)

Source

classes.lisp.

Target Slot

status.

Generic Reader: get-updates-needed (object) ¶

Package

http2/hpack.

Methods

Reader Method: get-updates-needed ((hpack-context hpack-context)) ¶

automatically generated reader method

Source

hpack.lisp.

Target Slot

updates-needed.

Generic Writer: (setf get-updates-needed) (object) ¶

Package

http2/hpack.

Methods

Writer Method: (setf get-updates-needed) ((hpack-context hpack-context)) ¶

automatically generated writer method

Source

hpack.lisp.

Target Slot

updates-needed.

Generic Function: handle-undefined-frame (type flags length) ¶

Callback that is called when a frame of unknown type is received - see extensions.

Package

http2.

Source

classes.lisp.

Methods

Method: handle-undefined-frame (type flags length) ¶

Generic Function: peer-acks-settings (connection) ¶

Called when SETTINGS-FRAME with ACK flag is received. By default does nothing.

Package

http2.

Source

classes.lisp.

Methods

Method: peer-acks-settings (connection) ¶

Method: peer-acks-settings ((connection logging-object)) ¶

Generic Function: peer-ends-http-stream (stream) ¶

Do relevant state changes when closing http stream (as part of received HEADERS or PAYLOAD).

Package

http2.

Source

classes.lisp.

Methods

Method: peer-ends-http-stream :after ((stream logging-object)) ¶

Method: peer-ends-http-stream (stream) ¶

Generic Function: peer-expects-settings-ack (connection) ¶

Called when settings-frame without ACK is received, after individual SET-PEER-SETTING calls. By default, send ACK frame.

Package

http2.

Source

classes.lisp.

Methods

Method: peer-expects-settings-ack (connection) ¶

Method: peer-expects-settings-ack :before ((connection logging-object)) ¶

Generic Function: peer-opens-http-stream (connection stream-id frame-type) ¶

Unknown stream ID was sent by the other side - i.e., from headers frame. Should return an object representing new stream.

Package

http2.

Source

classes.lisp.

Methods

Method: peer-opens-http-stream :before ((connection logging-object) stream-id frame-type) ¶

Method: peer-opens-http-stream (connection stream-id (frame-type (eql 1))) ¶

Method: peer-opens-http-stream (connection stream-id (frame-type (eql 2))) ¶

Method: peer-opens-http-stream :before ((connection client-http2-connection) stream-id frame-type) ¶

Method: peer-opens-http-stream :before ((connection server-http2-connection) stream-id frame-type) ¶

Method: peer-opens-http-stream :around ((connection logging-object) stream-id frame-type) ¶

Generic Function: peer-resets-stream (stream error-code) ¶

The RST_STREAM frame fully terminates the referenced stream and causes it to enter the "closed" state. After receiving a RST_STREAM on a stream, the receiver MUST NOT send additional frames for that stream, with the exception of PRIORITY. However, after sending the RST_STREAM, the sending endpoint MUST be prepared to receive and process additional frames sent on the stream that might have been sent by the peer prior to the arrival of the RST_STREAM.

Package

http2.

Source

classes.lisp.

Methods

Method: peer-resets-stream (stream error-code) ¶

Method: peer-resets-stream :before ((stream logging-object) error-code) ¶

Generic Function: peer-sends-push-promise (stream) ¶

This should be called on push promise (FIXME: and maybe it is not, and maybe the parameters should be different anyway). By default throws an error.

Package

http2.

Source

classes.lisp.

Methods

Method: peer-sends-push-promise (stream) ¶

Generic Function: send-ping (connection &optional payload) ¶

Send a ping request.

Package

http2.

Source

classes.lisp.

Methods

Method: send-ping (connection &optional payload) ¶

Method: send-ping ((connection timeshift-pinging-connection) &optional payload) ¶

Generic Function: set-peer-setting (connection name value) ¶

Process received information about peers setting.

The setting relates to the CONNECTION. NAME is a keyword symbol (see *SETTINGS*, subject to possible change to 16bit number in future) and VALUE is 32bit number.

Package

http2.

Source

classes.lisp.

Methods

Method: set-peer-setting (connection name value) ¶

Fallback.

Method: set-peer-setting :before ((connection logging-object) name value) ¶

Method: set-peer-setting (connection (name (eql :header-table-size)) value) ¶

Method: set-peer-setting (connection (name (eql :initial-window-size)) value) ¶

Method: set-peer-setting (connection (name (eql :max-frame-size)) value) ¶

Method: set-peer-setting (connection (name (eql :max-header-list-size)) value) ¶

Method: set-peer-setting ((connection client-http2-connection) (name (eql :enable-push)) value) ¶

Method: set-peer-setting ((connection server-http2-connection) (name (eql :enable-push)) value) ¶

Method: set-peer-setting (connection (name (eql :max-concurrent-streams)) value) ¶

---

6.1.5 Standalone methods

Method: close ((stream payload-output-stream) &key &allow-other-keys) ¶

Source

payload-streams.lisp.

Method: close ((stream payload-input-stream) &key &allow-other-keys) ¶

Source

payload-streams.lisp.

Method: close ((connection http2-connection) &key &allow-other-keys) ¶

Source

classes.lisp.

Method: initialize-instance :after ((connection client-http2-connection) &key &allow-other-keys) ¶

In HTTP/2, each endpoint is required to send a connection preface as a final confirmation of the protocol in use and to establish the initial settings for the HTTP/2 connection. The client and server each send a different connection preface.

The client connection preface starts with a sequence of 24 octets. This sequence MUST be followed by a SETTINGS frame (Section 6.5), which MAY be empty.

Source

classes.lisp.

Method: initialize-instance :after ((stream http2-stream) &key connection) ¶

Source

classes.lisp.

Method: initialize-instance :after ((stream payload-output-stream) &key base-http2-stream connection window-size &allow-other-keys) ¶

Source

payload-streams.lisp.

Method: initialize-instance :after ((stream payload-input-stream) &key base-http2-stream &allow-other-keys) ¶

Source

payload-streams.lisp.

Method: print-object ((stream server-stream) out) ¶

Source

classes.lisp.

Method: print-object ((o http2-stream) out) ¶

Source

classes.lisp.

Method: print-object ((err go-away) out) ¶

Source

classes.lisp.

Method: print-object ((err http-stream-error) out) ¶

Source

classes.lisp.

Method: stream-element-type ((stream binary-stream)) ¶

Source

payload-streams.lisp.

Method: stream-force-output ((stream payload-output-stream)) ¶

Package

sb-gray.

Source

payload-streams.lisp.

Method: stream-listen ((stream payload-input-stream)) ¶

Package

sb-gray.

Source

payload-streams.lisp.

Method: stream-read-byte ((stream payload-input-stream)) ¶

Package

sb-gray.

Source

payload-streams.lisp.

Method: stream-write-byte ((stream payload-output-stream) byte) ¶

Package

sb-gray.

Source

payload-streams.lisp.

Method: stream-write-sequence ((stream payload-output-stream) sequence start end &key) ¶

Package

trivial-gray-streams.

Source

payload-streams.lisp.

---

6.1.6 Classes

Class: client-http2-connection ¶

Client connections have odd-numbered streams.

Package

http2.

Source

classes.lisp.

Direct superclasses

http2-connection.

Direct methods

• do-goaway.
• get-settings.
• initialize-instance.
• peer-opens-http-stream.
• set-peer-setting.

Direct Default Initargs

Initarg	Value
:id-to-use	1

Class: client-stream ¶

HTTP2 stream that checks headers as required for clients (no psedoheader other than :status allowed, etc.

Package

http2.

Source

classes.lisp.

Direct superclasses

http2-stream.

Direct methods

• add-header.
• (setf get-status).
• get-status.
• process-end-headers.

Direct Default Initargs

Initarg	Value
:status	nil

Direct slots

Slot: status ¶

HTTP status code field (see [RFC7231], Section 6)

Initargs

:status

Readers

get-status.

Writers

(setf get-status).

Class: header-collecting-mixin ¶

Mixin to be used to collect all observed headers to a slot.

Package

http2.

Source

classes.lisp.

Direct methods

• add-header.
• (setf get-headers).
• get-headers.

Direct Default Initargs

Initarg	Value
:headers	nil

Direct slots

Slot: headers ¶

Initargs

:headers

Readers

get-headers.

Writers

(setf get-headers).

Class: history-printing-object ¶

A LOGGING-OBJECT that implements ADD-LOG to print all logs to *TRACE-OUTPUT* as soon as it receives them.

Package

http2.

Source

classes.lisp.

Direct superclasses

logging-object.

Direct methods

add-log.

Class: hpack-context ¶

Dynamic tables implementation: they are stored in an adjustable array, with
[0] element storing first element initially (indexed by s+1), and (s+k)th element after k insertions.

After deletion of D elements, element s+k is stored on index D, element s+1
on index

<———- Index Address Space ———->
<– Static Table –> <– Dynamic Table –>
+—+———–+—+ +—–+———–+—–+
| 1 | ... | s | |s+1+D| ... |s+k+D| ...deleted... +—+———–+—+ +—–+———–+—–+
k D 0
<—– table aref index ————–>
^ |
| V
Insertion Point Dropping Point

Package

http2/hpack.

Source

hpack.lisp.

Direct methods

• (setf get-bytes-left-in-table).
• get-bytes-left-in-table.
• (setf get-deleted-items).
• get-deleted-items.
• (setf get-dynamic-table).
• get-dynamic-table.
• (setf get-dynamic-table-size).
• get-dynamic-table-size.
• (setf get-updates-needed).
• get-updates-needed.

Direct Default Initargs

Initarg	Value
:dynamic-table	(make-array 0 fill-pointer 0 adjustable t)
:dynamic-table-size	4096
:deleted-items	0
:updates-needed	nil

Direct slots

Slot: dynamic-table ¶

Initargs

:dynamic-table

Readers

get-dynamic-table.

Writers

(setf get-dynamic-table).

Slot: bytes-left-in-table ¶

Initargs

:dynamic-table-size

Readers

get-bytes-left-in-table.

Writers

(setf get-bytes-left-in-table).

Slot: dynamic-table-size ¶

Initargs

:dynamic-table-size

Readers

get-dynamic-table-size.

Writers

(setf get-dynamic-table-size).

Slot: updates-needed ¶

Initargs

:updates-needed

Readers

get-updates-needed.

Writers

(setf get-updates-needed).

Slot: deleted-items ¶

Initargs

:deleted-items

Readers

get-deleted-items.

Writers

(setf get-deleted-items).

Class: logging-object ¶

Objects with this mixin have ADD-LOG called in many situations so that the communication can be debugged or recorded.

Package

http2.

Source

classes.lisp.

Direct subclasses

• history-keeping-object.
• history-printing-object.

Direct methods

• add-header.
• apply-data-frame.
• apply-stream-priority.
• apply-window-size-increment.
• do-goaway.
• do-ping.
• do-pong.
• (setf get-state).
• handle-alt-svc.
• peer-acks-settings.
• peer-ends-http-stream.
• peer-expects-settings-ack.
• peer-opens-http-stream.
• peer-opens-http-stream.
• peer-resets-stream.
• process-end-headers.
• set-peer-setting.

Class: timeshift-pinging-connection ¶

A mixin that implements specific DO-PING and DO-PONG so that the RTT is printed after DO-PING is send.

Package

http2.

Source

classes.lisp.

Direct methods

• do-pong.
• send-ping.

---

6.2.1 Constants

Constant: +altsvc-frame+ ¶

Package

http2.

Source

frames.lisp.

Constant: +cancel+ ¶

stream cancelled

Package

http2.

Source

utils.lisp.

Constant: +compression-error+ ¶

compression state not updated

Package

http2.

Source

utils.lisp.

Constant: +connect-error+ ¶

tcp connection error for connect method

Package

http2.

Source

utils.lisp.

Constant: +continuation-frame+ ¶

Package

http2.

Source

frames.lisp.

Constant: +data-frame+ ¶

Package

http2.

Source

frames.lisp.

Constant: +enhance-your-calm+ ¶

processing capacity exceeded

Package

http2.

Source

utils.lisp.

Constant: +flow-control-error+ ¶

flow-control limits exceeded

Package

http2.

Source

utils.lisp.

Constant: +frame-size-error+ ¶

frame size incorrect

Package

http2.

Source

utils.lisp.

Constant: +goaway-frame+ ¶

Package

http2.

Source

frames.lisp.

Constant: +headers-frame+ ¶

Package

http2.

Source

frames.lisp.

Constant: +http-1-1-required+ ¶

Use HTTP/1.1 for the request

Package

http2.

Source

utils.lisp.

Constant: +inadequate-security+ ¶

negotiated tls parameters not acceptable

Package

http2.

Source

utils.lisp.

Constant: +internal-error+ ¶

implementation fault

Package

http2.

Source

utils.lisp.

Constant: +known-frame-types-count+ ¶

Number of frame types we know.

Package

http2.

Source

frames.lisp.

Constant: +last-static-header-index+ ¶

Package

http2/hpack.

Source

hpack.lisp.

Constant: +last-static-header-pair+ ¶

Package

http2/hpack.

Source

hpack.lisp.

Constant: +literal-header-index+ ¶

Package

http2/hpack.

Source

hpack.lisp.

Constant: +literal-header-never-index+ ¶

Package

http2/hpack.

Source

hpack.lisp.

Constant: +literal-header-noindex+ ¶

Package

http2/hpack.

Source

hpack.lisp.

Constant: +ping-frame+ ¶

Package

http2.

Source

frames.lisp.

Constant: +priority-frame+ ¶

Package

http2.

Source

frames.lisp.

Constant: +protocol-error+ ¶

protocol error detected

Package

http2.

Source

utils.lisp.

Constant: +push-promise-frame+ ¶

Package

http2.

Source

frames.lisp.

Constant: +refused-stream+ ¶

stream not processed

Package

http2.

Source

utils.lisp.

Constant: +rst-stream-frame+ ¶

Package

http2.

Source

frames.lisp.

Constant: +settings-frame+ ¶

Package

http2.

Source

frames.lisp.

Constant: +settings-timeout+ ¶

settings not acknowledged

Package

http2.

Source

utils.lisp.

Constant: +stream-closed+ ¶

frame received for closed stream

Package

http2.

Source

utils.lisp.

Constant: +window-update-frame+ ¶

Package

http2.

Source

frames.lisp.

---

6.2.2 Special variables

Special Variable: *bytes-left* ¶

Number of bytes left in frame

Package

http2.

Source

utils.lisp.

Special Variable: *bytes-to-possibly-reuse* ¶

Package

http2.

Source

utils.lisp.

Special Variable: *bytes-to-reuse* ¶

Package

http2.

Source

utils.lisp.

Special Variable: *charset-names* ¶

Translation table from header charset names to FLEXI-STREAM keywords.

Package

http2.

Source

payload-streams.lisp.

Special Variable: *default-encoding* ¶

Character encoding to be used when not recognized from headers. Default is nil - binary.

Package

http2.

Source

payload-streams.lisp.

Special Variable: *default-text-encoding* ¶

Character encoding for text/ content to be used when not recognized from headers.

Package

http2.

Source

payload-streams.lisp.

Special Variable: *error-codes* ¶

This table maps error codes to mnemonic names - symbols.

Error codes are 32-bit fields that are used in RST_STREAM and GOAWAY frames to convey the reasons for the stream or connection error.

Error codes share a common code space. Some error codes apply only to either streams or the entire connection and have no defined semantics in the other context.

Package

http2.

Source

utils.lisp.

Special Variable: *flag-codes* ¶

Property list of flag names and their bit index.

This makes use of the fact that same flag name has same index in all headers where it is used.

Package

http2.

Source

frames.lisp.

Special Variable: *frame-types* ¶

Array of frame types. It is populated later with DEFINE-FRAME-TYPE.

Package

http2.

Source

frames.lisp.

Special Variable: *huffman-code* ¶

The code-and-code-size table from the RFC 7541 (hpack) appendix B

Package

http2/hpack.

Source

hpack.lisp.

Special Variable: *log-stream* ¶

Stream for logging output send by LOGGER.

Package

http2.

Source

utils.lisp.

Special Variable: *settings* ¶

See https://www.iana.org/assignments/http2-parameters/http2-parameters.xhtml

Package

http2.

Source

utils.lisp.

Special Variable: *use-huffman-coding-by-default* ¶

Is set, the headers are by default huffman-encoded. Special value :maybe means whatever is shorter, plain encoding in case of draw.

Package

http2/hpack.

Source

hpack.lisp.

Special Variable: *when-no-bytes-left-fn* ¶

Function to call when no bytes are left. Either errors or calls continuations.

Package

http2.

Source

utils.lisp.

Special Variable: +client-preface-start+ ¶

The client connection preface starts with a sequence of 24 octets, which in hex notation is this. That is, the connection preface starts with the string "PRI * HTTP/2.0rnrnSMrnrn").

Package

http2.

Source

classes.lisp.

Special Variable: static-headers-table ¶

Static headers table. Each element is either list of header name and value, or just header name. The content is defined in the RFC7541, and is supposed to start at index 1, so leading nil.

Package

http2/hpack.

Source

hpack.lisp.

---

6.2.3 Macros

Macro: check-place-empty-and-set-it (new-value accessor) ¶

All HTTP/2 requests MUST include exactly one valid value for the :method, :scheme, and :path pseudo-header fields, unless it is a CONNECT request (Section 8.3). An HTTP request that omits mandatory pseudo-header fields is malformed (Section 8.1.2.6).

Package

http2.

Source

classes.lisp.

Macro: define-frame-type (type-code frame-type-name documentation (&rest parameters) (&key flags length must-have-stream-in must-not-have-stream bad-state-error has-reserved) writer-body (&body reader)) ¶

This specification defines a number of frame types, each identified by a unique 8-bit TYPE CODE. Each frame type serves a distinct purpose in the establishment and management either of the connection as a whole or of individual streams.

The macro defining FRAME-TYPE-NAME :foo defines
- a constant named ‘+foo+‘ that translates to TYPE-CODE,
- a writer function WRITE-FOO that takes CONNECTION, HTTP-STREAM and possibly other PARAMETERS, sends frame header for given frame type with FLAGS and LENGTH expressions, and then executes WRITER-BODY with functions write-bytes and write-vector bound to writing to the transport stream. Each PARAMETER is a list of name, size in bits (or :variable) and documentation.
- a reader function named READ-FOO that takes CONNECTION, HTTP-STREAM, payload LENGTH and FLAGS and reads the payload of the frame: it runs READER-BODY with read-bytes and read-vector bound to reading from the transport stream. This function is supposed to be called from READ-FRAME that has already read the header and determined the appropriate http stream.

The transmission of specific frame types can alter the state of a connection. If endpoints fail to maintain a synchronized view of the connection state, successful communication within the connection will no longer be possible. Therefore, it is important that endpoints have a shared comprehension of how the state is affected by the use any given frame.

Package

http2.

Source

frames.lisp.

Macro: with-output-payload-slots (stream &body body) ¶

Package

http2.

Source

payload-streams.lisp.

---

6.2.4 Ordinary functions

Function: account-frame-window-contribution (connection stream length) ¶

Package

http2.

Source

frames.lisp.

Function: compute-header-size (header) ¶

Size of the header for dynamic cache purposes: 32 octets plus header and name sizes, including leading : at special header names.

Package

http2/hpack.

Source

hpack.lisp.

Function: compute-update-dynamic-size-codes (res updates) ¶

Package

http2/hpack.

Source

hpack.lisp.

Function: copy-frame-type (instance) ¶

Package

http2.

Source

frames.lisp.

Function: count-open-streams (connection) ¶

Package

http2.

Source

classes.lisp.

Function: create-new-local-stream (connection &optional pars) ¶

Create new local stream of default class on CONNECTION. Additional PARS are passed to the make-instance

Package

http2.

Source

frames.lisp.

Function: decode-huffman-to-stream (char-stream bytes &optional nr nr-size prefix) ¶

Package

http2/hpack.

Source

hpack.lisp.

Function: decode-octet-fn (&optional codes) ¶

Package

http2/hpack.

Source

hpack.lisp.

Function: dynamic-table-entry-size (name value) ¶

The size of an entry is the sum of its name’s length in octets (as defined in Section 5.2), its value’s length in octets, and 32.

The size of an entry is calculated using the length of its name and value without any Huffman encoding applied.

Package

http2.

Source

classes.lisp.

Function: empty-data-p (data) ¶

Package

http2.

Source

payload-streams.lisp.

Function: encode-dynamic-table-update (res new-size) ¶

Encode table update to NEW-SIZE to an adjustable array RES.

Package

http2/hpack.

Source

hpack.lisp.

Function: encode-huffman (string res) ¶

Convert string to huffman encoding.

Package

http2/hpack.

Source

hpack.lisp.

Function: find-header-in-tables (context name) ¶

Find header NAME in static table and, if CONNECTION is not null, in its dynamic table. Return the index, or NIL if not found.

Package

http2/hpack.

Source

hpack.lisp.

Function: find-in-tables (context item test key static-end) ¶

Find something (pair or header name) in static and possibly dynamic table.

Package

http2/hpack.

Source

hpack.lisp.

Function: find-pair-in-tables (context pair) ¶

Find header PAIR in static table and, if CONNECTION is not null, in its dynamic table. Return the index, or NIL if not found.

Package

http2/hpack.

Source

hpack.lisp.

Function: find-setting-by-id (id) ¶

Package

http2.

Source

utils.lisp.

Function: find-setting-code (name) ¶

Find setting name by code

Package

http2.

Source

utils.lisp.

Function: flags-to-code (flags) ¶

Create code to generate flag octet from FLAGS variable.

Package

http2.

Source

frames.lisp.

Function: flags-to-vars-code (flags) ¶

Create code to extract variables named as each member of *flag-codes*
that is set to T if it is in FLAGS and appropriate bit is set in the read flags.

Package

http2.

Source

frames.lisp.

Reader: frame-type-documentation (instance) ¶

Writer: (setf frame-type-documentation) (instance) ¶

Package

http2.

Source

frames.lisp.

Target Slot

documentation.

Reader: frame-type-name (instance) ¶

Writer: (setf frame-type-name) (instance) ¶

Package

http2.

Source

frames.lisp.

Target Slot

name.

Function: frame-type-p (object) ¶

Package

http2.

Source

frames.lisp.

Reader: frame-type-receive-fn (instance) ¶

Writer: (setf frame-type-receive-fn) (instance) ¶

Package

http2.

Source

frames.lisp.

Target Slot

receive-fn.

Function: get-error-name (code) ¶

Package

http2.

Source

utils.lisp.

Function: get-history (object) ¶

Package

http2.

Source

classes.lisp.

Function: header-writer (res name value &optional context huffman) ¶

Encode header consisting of NAME and VALUE.

The ‘never-indexed‘ format is never generated, use a separate function for this (and this function needs to be written).

When CONTEXT is provided, use incremental indexing with dynamic table in that CONTEXT.

Use Huffman when HUFFMAN is true.

Package

http2/hpack.

Source

hpack.lisp.

Function: http2-error (connection error-code debug-code &rest args) ¶

Signal to the peer the ERROR CODE and kill connection.

For a client, raise error to signal we are done with connection. For a server, close the connection by invoking the restart.

Package

http2.

Source

classes.lisp.

Function: huffman-coded-size (string) ¶

Size of huffman-coded text

Package

http2/hpack.

Source

hpack.lisp.

Function: logger (fmt &rest pars) ¶

Send a format message to *LOG-STREAM*.

Package

http2.

Source

utils.lisp.

Function: make-cond-branch (i prefix code) ¶

Return decoder code for I matching PREFIX among codes.

Package

http2/hpack.

Source

hpack.lisp.

Function: make-frame-type (name documentation receive-fn) ¶

Package

http2.

Source

frames.lisp.

Function: make-transport-input-stream (raw-stream charset gzip) ¶

INPUT-STREAM built atop RAW-STREAM.

Guess encoding and need to gunzip from headers: - apply zip decompression if gzip is set
- if charset is not null, use it to convert to text.

Package

http2.

Source

payload-streams.lisp.

Function: make-transport-input-stream-from-stream (raw-stream charset encoded) ¶

INPUT-STREAM built atop RAW-STREAM.

Guess encoding and need to gunzip from headers:
- apply zip decompression content-encoding is gzip (FIXME: also compression) - use charset if understood in content-type
- otherwise guess whether text (use UTF-8) or binary.

Package

http2.

Source

payload-streams.lisp.

Function: make-transport-output-stream-from-stream (raw-stream charset gzip) ¶

An OUTPUT-STREAM built atop RAW STREAM with added charset and possibly compression.

Package

http2.

Source

payload-streams.lisp.

Function: open-http2-stream (connection headers &key end-stream end-headers stream-pars) ¶

Open http2 stream by sending headers.

Package

http2.

Source

classes.lisp.

Function: peer-opens-http-stream-really-open (connection stream-id state) ¶

Package

http2.

Source

classes.lisp.

Function: pop-frame (data) ¶

Package

http2.

Source

payload-streams.lisp.

Function: push-frame (data frame) ¶

Package

http2.

Source

payload-streams.lisp.

Function: read-altsvc-frame (connection http-stream length flags) ¶

See RFC 7838. The ALTSVC HTTP/2 frame advertises the availability of an alternative service to an HTTP/2 client.

#+begin_src artist +——————————-+——————————-+ | Origin-Len (16) | Origin? (*) ... +——————————-+——————————-+ | Alt-Svc-Field-Value (*) ... +—————————————————————+ #+end_src

Package

http2.

Source

frames.lisp.

Function: read-and-add-headers (connection http-stream length end-headers) ¶

Package

http2.

Source

frames.lisp.

Function: read-bytes (stream n) ¶

Read N bytes from stream to an integer

Package

http2.

Source

utils.lisp.

Function: read-client-preface (connection) ¶

Package

http2.

Source

classes.lisp.

Function: read-continuation-frame (connection http-stream length flags) ¶

#+begin_src artist

+—————————————————————+
| Header Block Fragment (*) ... +—————————————————————+ #+end_src

The CONTINUATION frame (type=0x9) is used to continue a sequence of header block fragments (Section 4.3). Any number of CONTINUATION frames can be sent, as long as the preceding frame is on the same stream and is a HEADERS, PUSH_PROMISE, or CONTINUATION frame without the END_HEADERS flag set.

Package

http2.

Source

frames.lisp.

Function: read-data-frame (connection http-stream length flags) ¶

#+begin_src artist

+—————+———————————————–+ | Data (*) ... +—————————————————————+ #+end_src

DATA frames (type=0x0) convey arbitrary, variable-length sequences of octets associated with a stream. One or more DATA frames are used, for instance, to carry HTTP request or response payloads.

Package

http2.

Source

frames.lisp.

Function: read-from-tables (index context) ¶

Read item on INDEX in static table or dynamic table in CONNECTION.

Package

http2/hpack.

Source

hpack.lisp.

Function: read-goaway-frame (connection http-stream length flags) ¶

#+begin_src artist +-+————————————————————-+ |R| Last-Stream-ID (31) | +-+————————————————————-+ | Error Code (32) | +—————————————————————+ | Additional Debug Data (*) | +—————————————————————+ #+end_src

The GOAWAY frame (type=0x7) is used to initiate shutdown of a connection or to signal serious error conditions. GOAWAY allows an endpoint to gracefully stop accepting new streams while still finishing processing of previously established streams. This enables administrative actions, like server maintenance.

Package

http2.

Source

frames.lisp.

Function: read-headers-frame (connection http-stream length flags) ¶

#+begin_src artist

+-+————-+———————————————–+ |E| Stream Dependency? (31) | +-+————-+———————————————–+ | Weight? (8) | +-+————-+———————————————–+ | Header Block Fragment (*) ... +—————————————————————+ #+end_src

The HEADERS frame (type=0x1) is used to open a stream (Section 5.1), and additionally carries a header block fragment. HEADERS frames can be sent on a stream in the "idle", "reserved (local)", "open", or "half-closed (remote)" state.

Package

http2.

Source

frames.lisp.

Function: read-huffman (stream len) ¶

Read Huffman coded text of length LEN from STREAM.

Package

http2/hpack.

Source

hpack.lisp.

Function: read-literal-header-field-new-name (stream) ¶

See 6.2.1 fig. 7, and 6.2.2. fig. 9 -
Neither name of the header nor value is in table, so read both as literals.

Package

http2/hpack.

Source

hpack.lisp.

Function: read-literal-header-indexed-name (stream octet0 context use-bits) ¶

See Fig. 6 and Fig. 8 - Name of header is in tables, value is literal.

Use USE-BITS from the OCTET0 for name index

Package

http2/hpack.

Source

hpack.lisp.

Function: read-padding (stream padding-size) ¶

Read the padding if padding-size is not NIL.

Package

http2.

Source

frames.lisp.

Function: read-ping-frame (connection http-stream length flags) ¶

The PING frame (type=0x6) is a mechanism for measuring a minimal round-trip time from the sender, as well as determining whether an idle connection is still functional. PING frames can be sent from any endpoint.

#+begin_src artist +—————————————————————+ | | | Opaque Data (64) | | | +—————————————————————+ #+end_src

Figure 12: PING Payload Format

In addition to the frame header, PING frames MUST contain 8 octets of opaque data in the payload. A sender can include any value it chooses and use those octets in any fashion.

Receivers of a PING frame that does not include an ACK flag MUST send a PING frame with the ACK flag set in response, with an identical payload. PING responses SHOULD be given higher priority than any other frame.

The PING frame defines the following flags:

ACK (0x1): When set, bit 0 indicates that this PING frame is a PING response. An endpoint MUST set this flag in PING responses. An endpoint MUST NOT respond to PING frames containing this flag.

Package

http2.

Source

frames.lisp.

Function: read-priority-frame (connection http-stream length flags) ¶

The PRIORITY frame (type=0x2) specifies the sender-advised priority of a stream (Section 5.3).

#+begin_src artist +-+————————————————————-+ |E| Stream Dependency (31) | +-+————-+———————————————–+ | Weight (8) |
+-+————-+
#+end_src

The payload of a PRIORITY frame contains the following fields:

E: A single-bit flag indicating that the stream dependency is exclusive (see Section 5.3).

Stream Dependency: A 31-bit stream identifier for the stream that this stream depends on (see Section 5.3).

Weight: An unsigned 8-bit integer representing a priority weight for the stream (see Section 5.3). Add one to the value to obtain a weight between 1 and 256.

Package

http2.

Source

frames.lisp.

Function: read-push-promise-frame (connection http-stream length flags) ¶

The PUSH_PROMISE frame (type=0x5) is used to notify the peer endpoint in advance of streams the sender intends to initiate. The PUSH_PROMISE frame includes the unsigned 31-bit identifier of the stream the endpoint plans to create along with a set of headers that provide additional context for the stream. Section 8.2 contains a thorough description of the use of PUSH_PROMISE frames.

#+begin_src artist +-+————-+———————————————–+ |R| Promised Stream ID (31) | +-+—————————–+——————————-+ | Header Block Fragment (*) ... +—————————————————————+ #+end_src

The PUSH_PROMISE frame payload has the following fields:

R: A single reserved bit.

Promised Stream ID: An unsigned 31-bit integer that identifies the stream that is reserved by the PUSH_PROMISE. The promised stream identifier MUST be a valid choice for the next stream sent by the sender (see "new stream identifier" in Section 5.1.1).

Header Block Fragment: A header block fragment (Section 4.3) containing request header fields.

The PUSH_PROMISE frame defines the following flags:

END_HEADERS (0x4): When set, bit 2 indicates that this frame contains an entire header block (Section 4.3) and is not followed by any CONTINUATION frames.

A PUSH_PROMISE frame without the END_HEADERS flag set MUST be followed by a CONTINUATION frame for the same stream. A receiver MUST treat the receipt of any other type of frame or a frame on a different stream as a connection error (Section 5.4.1) of type PROTOCOL_ERROR.

Package

http2.

Source

frames.lisp.

Function: read-rst-stream-frame (connection http-stream length flags) ¶

The RST_STREAM frame (type=0x3) allows for immediate termination of a stream. RST_STREAM is sent to request cancellation of a stream or to indicate that an error condition has occurred.

#+begin_src artist +—————————————————————+ | Error Code (32) | +—————————————————————+ #+end_src

The RST_STREAM frame contains a single unsigned, 32-bit integer identifying the error code (Section 7). The error code indicates why the stream is being terminated.

The RST_STREAM frame does not define any flags.

Package

http2.

Source

frames.lisp.

Function: read-settings-frame (connection http-stream length flags) ¶

#+begin_src artist
+——————————-+
| Identifier (16) | +——————————-+——————————-+ | Value (32) | +—————————————————————+ #+end_src

The SETTINGS frame (type=0x4) conveys configuration parameters that affect how endpoints communicate, such as preferences and constraints on peer behavior. The SETTINGS frame is also used to acknowledge the receipt of those parameters. Individually, a SETTINGS parameter can also be referred to as a "setting".

Package

http2.

Source

frames.lisp.

Function: read-string-from-stream (stream) ¶

Read string literal from a STREAM as defined in RFC7541 sect 5.2.

Package

http2/hpack.

Source

hpack.lisp.

Function: read-window-update-frame (connection http-stream length flags) ¶

#+begin_src artist
+-+————————————————————-+
|R| Window Size Increment (31) |
+-+————————————————————-+
#+end_src

The WINDOW_UPDATE frame (type=0x8) is used to implement flow control; see Section 5.2 for an overview. Flow control operates at two levels: on each individual stream and on the entire connection.

Package

http2.

Source

frames.lisp.

Function: send-data (stream sequence start size) ¶

Send data in OUTPUT-BUFFER and SIZE data from SEQUENCE starting at START in one data frame; mark them as sent.

Return new START.

Package

http2.

Source

payload-streams.lisp.

Function: set-when-no-bytes-left-fn (http2-stream-id end-headers) ¶

Read a header of continuation frame if continuation expected. Set *when-no-bytes-left-fn* appropriately.

Package

http2.

Source

frames.lisp.

Function: store-string (string res huffman) ¶

Add STRING to fillable array RES in format defined by HPACK, possibly using huffman encoding.

Package

http2/hpack.

Source

hpack.lisp.

Function: vector-from-hex-text (text) ¶

Package

http2.

Source

utils.lisp.

Function: vector-index-to-hpack-index (table idx) ¶

Convert between hpack index and index in the vector. This works both ways.

Package

http2/hpack.

Source

hpack.lisp.

Function: write-31-bits (stream value reserved) ¶

Write 31 bits of VALUE to a STREAM. Set first bit if RESERVED is set.

Package

http2.

Source

frames.lisp.

Function: write-bytes (stream n value) ¶

write VALUE as N octets to stream. Maximum length is 64 bits (used by ping).

Package

http2.

Source

utils.lisp.

Function: write-indexed-header-pair (res index) ¶

Package

http2/hpack.

Source

hpack.lisp.

Function: write-indexed-name (res code index value use-bits huffman) ¶

Package

http2/hpack.

Source

hpack.lisp.

Function: write-integer-to-array (array integer bit-size mask) ¶

Write integer to a fillable vector as defined in RFC7541 sect. 5.1.

Return the fillable vector.

Package

http2/hpack.

Source

hpack.lisp.

Function: write-literal-header-pair (res code name value huffman) ¶

Package

http2/hpack.

Source

hpack.lisp.

---