lsquic_frame_reader.h revision c51ce338 
1/* Copyright (c) 2017 LiteSpeed Technologies Inc.  See LICENSE. */
2/*
3 * lsquic_frame_reader.h -- Read HTTP frames from stream
4 */
5
6#ifndef LSQUIC_FRAME_READER_H
7#define LSQUIC_FRAME_READER_H 1
8
9#include <stddef.h>
10#include <stdint.h>
11
12struct lsquic_hdec;
13struct lsquic_mm;
14struct lsquic_stream;
15struct lsquic_frame_reader;
16
17
18enum frame_reader_flags
19{
20    FRF_SERVER      = (1 << 0),
21    FRF_HAVE_PREV   = (1 << 1),
22};
23
24
25/* Frame reader may hit some error conditions which are reported using
26 * callback fc_on_error.  These codes are later mapped stream- or
27 * connection-level errors.
28 */
29enum frame_reader_error
30{
31    FR_ERR_DUPLICATE_PSEH = 1,  /* Duplicate pseudo-header */
32    FR_ERR_INCOMPL_REQ_PSEH,    /* Not all request pseudo-headers are present */
33    FR_ERR_UNNEC_REQ_PSEH,      /* Unnecessary request pseudo-header present in
34                                 * the response.
35                                 */
36    FR_ERR_INCOMPL_RESP_PSEH,   /* Not all response pseudo-headers are present */
37    FR_ERR_UNNEC_RESP_PSEH,     /* Unnecessary response pseudo-header present in
38                                 * the response.
39                                 */
40    FR_ERR_UNKNOWN_PSEH,        /* Unknown pseudo-header */
41    FR_ERR_UPPERCASE_HEADER,    /* Uppercase letter in header */
42    FR_ERR_MISPLACED_PSEH,
43    FR_ERR_MISSING_PSEH,
44    FR_ERR_DECOMPRESS,
45    FR_ERR_INVALID_FRAME_SIZE,  /* E.g. a SETTINGS frame length is not a multiple
46                                 * of 6 (RFC 7540, Section 6.5.1).
47                                 */
48    FR_ERR_NONZERO_STREAM_ID,
49    FR_ERR_ZERO_STREAM_ID,
50    FR_ERR_SELF_DEP_STREAM,     /* A stream in priority frame cannot depend on
51                                 * itself (RFC 7540, Section 5.3.1).
52                                 */
53    FR_ERR_HEADERS_TOO_LARGE,
54    FR_ERR_UNEXPECTED_PUSH,
55    FR_ERR_NOMEM,               /* Cannot allocate any more memory. */
56    FR_ERR_EXPECTED_CONTIN,     /* Expected continuation frame. */
57};
58
59
60/* This struct is used to return decoded HEADERS and PUSH_PROMISE frames.
61 * Some of the fields are only used for HEADERS frames.  They are marked
62 * with "H" comment below.
63 */
64struct uncompressed_headers
65{
66    uint32_t               uh_stream_id;
67    uint32_t               uh_oth_stream_id; /* For HEADERS frame, the ID of the
68                                              * stream that this stream depends
69                                              * on.  (Zero means unset.) For
70                                              * PUSH_PROMISE, the promised stream
71                                              * ID.
72                                              */
73    unsigned               uh_size;          /* Number of characters in uh_headers, not
74                                              * counting the NUL byte.
75                                              */
76    unsigned       /* H */ uh_off;
77    unsigned short /* H */ uh_weight;        /* 1 - 256; 0 means not set */
78    signed char    /* H */ uh_exclusive;     /* 0 or 1 when set; -1 means not set */
79    enum {
80                   /* H */ UH_FIN  = (1 << 0),
81                           UH_PP   = (1 << 1), /* Push promise */
82    }                      uh_flags:8;
83    char                   uh_headers[       /* NUL-terminated C string */
84#if FRAME_READER_TESTING
85                                         FRAME_READER_TESTING
86#else
87                                                    0
88#endif
89    ];
90};
91
92struct frame_reader_callbacks
93{
94    void (*frc_on_headers)      (void *frame_cb_ctx, struct uncompressed_headers *);
95    void (*frc_on_push_promise) (void *frame_cb_ctx, struct uncompressed_headers *);
96    void (*frc_on_settings)     (void *frame_cb_ctx, uint16_t setting_id,
97                                 uint32_t setting_value);
98    void (*frc_on_priority)     (void *frame_cb_ctx, uint32_t stream_id,
99                                 int exclusive, uint32_t dep_stream_id,
100                                 unsigned weight);
101    void (*frc_on_error)        (void *frame_cb_ctx, uint32_t stream_id,
102                                 enum frame_reader_error);
103};
104
105typedef ssize_t (*fr_stream_read_f)(struct lsquic_stream *, void *, size_t);
106
107struct lsquic_frame_reader *
108lsquic_frame_reader_new (enum frame_reader_flags, unsigned max_headers_sz,
109                         struct lsquic_mm *, struct lsquic_stream *,
110                         fr_stream_read_f, struct lsquic_hdec *,
111                         const struct frame_reader_callbacks *,
112                         void *fr_cb_ctx);
113
114int
115lsquic_frame_reader_read (struct lsquic_frame_reader *);
116
117void
118lsquic_frame_reader_destroy (struct lsquic_frame_reader *);
119
120size_t
121lsquic_frame_reader_mem_used (const struct lsquic_frame_reader *);
122
123#endif
124