File: h2_stream.h

package info (click to toggle)
apache2 2.4.25-3%2Bdeb9u9
  • links: PTS, VCS
  • area: main
  • in suites: stretch
  • size: 58,936 kB
  • sloc: ansic: 179,394; perl: 11,183; sh: 5,784; php: 1,313; awk: 741; makefile: 627; lex: 374; yacc: 161; python: 72; xml: 1
file content (313 lines) | stat: -rw-r--r-- 11,646 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
/* Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

#ifndef __mod_h2__h2_stream__
#define __mod_h2__h2_stream__

#include "h2.h"

/**
 * A HTTP/2 stream, e.g. a client request+response in HTTP/1.1 terms.
 * 
 * A stream always belongs to a h2_session, the one managing the
 * connection to the client. The h2_session writes to the h2_stream,
 * adding HEADERS and DATA and finally an EOS. When headers are done,
 * h2_stream is scheduled for handling, which is expected to produce
 * a response h2_headers at least.
 * 
 * The h2_headers may be followed by more h2_headers (interim responses) and
 * by DATA frames read from the h2_stream until EOS is reached. Trailers
 * are send when a last h2_headers is received. This always closes the stream
 * output.
 */

struct h2_mplx;
struct h2_priority;
struct h2_request;
struct h2_headers;
struct h2_session;
struct h2_task;
struct h2_bucket_beam;

typedef struct h2_stream h2_stream;

typedef void h2_stream_state_cb(void *ctx, h2_stream *stream);
typedef void h2_stream_event_cb(void *ctx, h2_stream *stream, 
                                h2_stream_event_t ev);

/**
 * Callback structure for events and stream state transisitions
 */
typedef struct h2_stream_monitor {
    void *ctx;
    h2_stream_state_cb *on_state_enter;   /* called when a state is entered */
    h2_stream_state_cb *on_state_invalid; /* called when an invalid state change
                                             was detected */
    h2_stream_event_cb *on_state_event;   /* called right before the given event
                                             result in a new stream state */
    h2_stream_event_cb *on_event;         /* called for events that do not 
                                             trigger a state change */
} h2_stream_monitor;

struct h2_stream {
    int id;                     /* http2 stream identifier */
    int initiated_on;           /* initiating stream id (PUSH) or 0 */
    apr_pool_t *pool;           /* the memory pool for this stream */
    struct h2_session *session; /* the session this stream belongs to */
    h2_stream_state_t state;    /* state of this stream */
    
    apr_time_t created;         /* when stream was created */
    
    const struct h2_request *request; /* the request made in this stream */
    struct h2_request *rtmp;    /* request being assembled */
    apr_table_t *trailers;      /* optional incoming trailers */
    int request_headers_added;  /* number of request headers added */
    
    struct h2_bucket_beam *input;
    apr_bucket_brigade *in_buffer;
    int in_window_size;
    apr_time_t in_last_write;
    
    struct h2_bucket_beam *output;
    apr_bucket_brigade *out_buffer;
    apr_size_t max_mem;         /* maximum amount of data buffered */

    int rst_error;              /* stream error for RST_STREAM */
    unsigned int aborted   : 1; /* was aborted */
    unsigned int scheduled : 1; /* stream has been scheduled */
    unsigned int has_response : 1; /* response headers are known */
    unsigned int input_eof : 1; /* no more request data coming */
    unsigned int out_checked : 1; /* output eof was double checked */
    unsigned int push_policy;   /* which push policy to use for this request */
    
    struct h2_task *task;       /* assigned task to fullfill request */
    
    const h2_priority *pref_priority; /* preferred priority for this stream */
    apr_off_t out_frames;       /* # of frames sent out */
    apr_off_t out_frame_octets; /* # of RAW frame octets sent out */
    apr_off_t out_data_frames;  /* # of DATA frames sent */
    apr_off_t out_data_octets;  /* # of DATA octets (payload) sent */
    apr_off_t in_data_frames;   /* # of DATA frames received */
    apr_off_t in_data_octets;   /* # of DATA octets (payload) received */
    apr_off_t in_trailer_octets; /* # of HEADER octets (payload) received in trailers */
    
    h2_stream_monitor *monitor; /* optional monitor for stream states */
};


#define H2_STREAM_RST(s, def)    (s->rst_error? s->rst_error : (def))

/**
 * Create a stream in H2_SS_IDLE state.
 * @param id      the stream identifier
 * @param pool    the memory pool to use for this stream
 * @param session the session this stream belongs to
 * @param monitor an optional monitor to be called for events and 
 *                state transisitions
 * @param initiated_on the id of the stream this one was initiated on (PUSH)
 *
 * @return the newly opened stream
 */
h2_stream *h2_stream_create(int id, apr_pool_t *pool, 
                            struct h2_session *session,
                            h2_stream_monitor *monitor,
                            int initiated_on);

/**
 * Destroy memory pool if still owned by the stream.
 */
void h2_stream_destroy(h2_stream *stream);

/**
 * Prepare the stream so that processing may start.
 * 
 * This is the time to allocated resources not needed before.
 * 
 * @param stream the stream to prep 
 */
apr_status_t h2_stream_prep_processing(h2_stream *stream);

/*
 * Set a new monitor for this stream, replacing any existing one. Can
 * be called with NULL to have no monitor installed.
 */
void h2_stream_set_monitor(h2_stream *stream, h2_stream_monitor *monitor);

/**
 * Dispatch (handle) an event on the given stream.
 * @param stream  the streama the event happened on
 * @param ev      the type of event
 */
void h2_stream_dispatch(h2_stream *stream, h2_stream_event_t ev);

/**
 * Cleanup references into requst processing.
 *
 * @param stream the stream to cleanup
 */
void h2_stream_cleanup(h2_stream *stream);

/**
 * Notify the stream that amount bytes have been consumed of its input
 * since the last invocation of this method (delta amount).
 */
apr_status_t h2_stream_in_consumed(h2_stream *stream, apr_off_t amount);

/**
 * Set complete stream headers from given h2_request.
 * 
 * @param stream stream to write request to
 * @param r the request with all the meta data
 * @param eos != 0 iff stream input is closed
 */
void h2_stream_set_request(h2_stream *stream, const h2_request *r);

/**
 * Set complete stream header from given request_rec.
 * 
 * @param stream stream to write request to
 * @param r the request with all the meta data
 * @param eos != 0 iff stream input is closed
 */
apr_status_t h2_stream_set_request_rec(h2_stream *stream, 
                                       request_rec *r, int eos);

/*
 * Add a HTTP/2 header (including pseudo headers) or trailer 
 * to the given stream, depending on stream state.
 *
 * @param stream stream to write the header to
 * @param name the name of the HTTP/2 header
 * @param nlen the number of characters in name
 * @param value the header value
 * @param vlen the number of characters in value
 */
apr_status_t h2_stream_add_header(h2_stream *stream,
                                  const char *name, size_t nlen,
                                  const char *value, size_t vlen);
                                  
/* End the contruction of request headers */
apr_status_t h2_stream_end_headers(h2_stream *stream, int eos, size_t raw_bytes);


apr_status_t h2_stream_send_frame(h2_stream *stream, int frame_type, int flags, size_t frame_len);
apr_status_t h2_stream_recv_frame(h2_stream *stream, int frame_type, int flags, size_t frame_len);

/*
 * Process a frame of received DATA.
 *
 * @param stream stream to write the data to
 * @param flags the frame flags
 * @param data the beginning of the bytes to write
 * @param len the number of bytes to write
 */
apr_status_t h2_stream_recv_DATA(h2_stream *stream, uint8_t flags,
                                 const uint8_t *data, size_t len);

apr_status_t h2_stream_flush_input(h2_stream *stream);

/**
 * Reset the stream. Stream write/reads will return errors afterwards.
 *
 * @param stream the stream to reset
 * @param error_code the HTTP/2 error code
 */
void h2_stream_rst(h2_stream *stream, int error_code);

/**
 * Determine if stream was closed already. This is true for
 * states H2_SS_CLOSED, H2_SS_CLEANUP. But not true
 * for H2_SS_CLOSED_L and H2_SS_CLOSED_R.
 *
 * @param stream the stream to check on
 * @return != 0 iff stream has been closed
 */
int h2_stream_was_closed(const h2_stream *stream);

/**
 * Do a speculative read on the stream output to determine the 
 * amount of data that can be read.
 * 
 * @param stream the stream to speculatively read from
 * @param plen (in-/out) number of bytes requested and on return amount of bytes that
 *        may be read without blocking
 * @param peos (out) != 0 iff end of stream will be reached when reading plen
 *        bytes (out value).
 * @param presponse (out) the response of one became available
 * @return APR_SUCCESS if out information was computed successfully.
 *         APR_EAGAIN if not data is available and end of stream has not been
 *         reached yet.
 */
apr_status_t h2_stream_out_prepare(h2_stream *stream, apr_off_t *plen, 
                                   int *peos, h2_headers **presponse);

/**
 * Read a maximum number of bytes into the bucket brigade.
 * 
 * @param stream the stream to read from
 * @param bb the brigade to append output to
 * @param plen (in-/out) max. number of bytes to append and on return actual
 *        number of bytes appended to brigade
 * @param peos (out) != 0 iff end of stream has been reached while reading
 * @return APR_SUCCESS if out information was computed successfully.
 *         APR_EAGAIN if not data is available and end of stream has not been
 *         reached yet.
 */
apr_status_t h2_stream_read_to(h2_stream *stream, apr_bucket_brigade *bb, 
                               apr_off_t *plen, int *peos);

/**
 * Get optional trailers for this stream, may be NULL. Meaningful
 * results can only be expected when the end of the response body has
 * been reached.
 *
 * @param stream to ask for trailers
 * @return trailers for NULL
 */
apr_table_t *h2_stream_get_trailers(h2_stream *stream);

/**
 * Submit any server push promises on this stream and schedule
 * the tasks connection with these.
 *
 * @param stream the stream for which to submit
 */
apr_status_t h2_stream_submit_pushes(h2_stream *stream, h2_headers *response);

/**
 * Get priority information set for this stream.
 */
const struct h2_priority *h2_stream_get_priority(h2_stream *stream, 
                                                 h2_headers *response);

/**
 * Return a textual representation of the stream state as in RFC 7540
 * nomenclator, all caps, underscores.
 */
const char *h2_stream_state_str(h2_stream *stream);

/**
 * Determine if stream is ready for submitting a response or a RST
 * @param stream the stream to check
 */
int h2_stream_is_ready(h2_stream *stream);

#define H2_STRM_MSG(s, msg)     \
    "h2_stream(%ld-%d,%s): "msg, s->session->id, s->id, h2_stream_state_str(s)

#define H2_STRM_LOG(aplogno, s, msg)    aplogno H2_STRM_MSG(s, msg)

#endif /* defined(__mod_h2__h2_stream__) */