"Fossies" - the Fresh Open Source Software Archive

Member "mod_http2-1.15.17/mod_http2/h2_stream.h" (22 Feb 2021, 11724 Bytes) of package /linux/www/apache_httpd_modules/mod_http2-1.15.17.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) C and C++ source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file. For more information about "h2_stream.h" see the Fossies "Dox" file reference documentation and the latest Fossies "Diffs" side-by-side code changes report: 1.15.16_vs_1.15.17.

    1 /* Licensed to the Apache Software Foundation (ASF) under one or more
    2  * contributor license agreements.  See the NOTICE file distributed with
    3  * this work for additional information regarding copyright ownership.
    4  * The ASF licenses this file to You under the Apache License, Version 2.0
    5  * (the "License"); you may not use this file except in compliance with
    6  * the License.  You may obtain a copy of the License at
    7  *
    8  *     http://www.apache.org/licenses/LICENSE-2.0
    9  *
   10  * Unless required by applicable law or agreed to in writing, software
   11  * distributed under the License is distributed on an "AS IS" BASIS,
   12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   13  * See the License for the specific language governing permissions and
   14  * limitations under the License.
   15  */
   16 
   17 #ifndef __mod_h2__h2_stream__
   18 #define __mod_h2__h2_stream__
   19 
   20 #include "h2.h"
   21 
   22 /**
   23  * A HTTP/2 stream, e.g. a client request+response in HTTP/1.1 terms.
   24  * 
   25  * A stream always belongs to a h2_session, the one managing the
   26  * connection to the client. The h2_session writes to the h2_stream,
   27  * adding HEADERS and DATA and finally an EOS. When headers are done,
   28  * h2_stream is scheduled for handling, which is expected to produce
   29  * a response h2_headers at least.
   30  * 
   31  * The h2_headers may be followed by more h2_headers (interim responses) and
   32  * by DATA frames read from the h2_stream until EOS is reached. Trailers
   33  * are send when a last h2_headers is received. This always closes the stream
   34  * output.
   35  */
   36 
   37 struct h2_mplx;
   38 struct h2_priority;
   39 struct h2_request;
   40 struct h2_headers;
   41 struct h2_session;
   42 struct h2_task;
   43 struct h2_bucket_beam;
   44 
   45 typedef struct h2_stream h2_stream;
   46 
   47 typedef void h2_stream_state_cb(void *ctx, h2_stream *stream);
   48 typedef void h2_stream_event_cb(void *ctx, h2_stream *stream, 
   49                                 h2_stream_event_t ev);
   50 
   51 /**
   52  * Callback structure for events and stream state transisitions
   53  */
   54 typedef struct h2_stream_monitor {
   55     void *ctx;
   56     h2_stream_state_cb *on_state_enter;   /* called when a state is entered */
   57     h2_stream_state_cb *on_state_invalid; /* called when an invalid state change
   58                                              was detected */
   59     h2_stream_event_cb *on_state_event;   /* called right before the given event
   60                                              result in a new stream state */
   61     h2_stream_event_cb *on_event;         /* called for events that do not 
   62                                              trigger a state change */
   63 } h2_stream_monitor;
   64 
   65 struct h2_stream {
   66     int id;                     /* http2 stream identifier */
   67     int initiated_on;           /* initiating stream id (PUSH) or 0 */
   68     apr_pool_t *pool;           /* the memory pool for this stream */
   69     struct h2_session *session; /* the session this stream belongs to */
   70     h2_stream_state_t state;    /* state of this stream */
   71     
   72     apr_time_t created;         /* when stream was created */
   73     
   74     const struct h2_request *request; /* the request made in this stream */
   75     struct h2_request *rtmp;    /* request being assembled */
   76     apr_table_t *trailers;      /* optional incoming trailers */
   77     int request_headers_added;  /* number of request headers added */
   78     
   79     struct h2_bucket_beam *input;
   80     apr_bucket_brigade *in_buffer;
   81     int in_window_size;
   82     apr_time_t in_last_write;
   83     
   84     struct h2_bucket_beam *output;
   85     apr_bucket_brigade *out_buffer;
   86     apr_size_t max_mem;         /* maximum amount of data buffered */
   87 
   88     int rst_error;              /* stream error for RST_STREAM */
   89     unsigned int aborted   : 1; /* was aborted */
   90     unsigned int scheduled : 1; /* stream has been scheduled */
   91     unsigned int has_response : 1; /* response headers are known */
   92     unsigned int input_eof : 1; /* no more request data coming */
   93     unsigned int out_checked : 1; /* output eof was double checked */
   94     unsigned int push_policy;   /* which push policy to use for this request */
   95     unsigned int input_buffering : 1; /* buffer request bodies for efficiency */
   96 
   97     struct h2_task *task;       /* assigned task to fullfill request */
   98     
   99     const h2_priority *pref_priority; /* preferred priority for this stream */
  100     apr_off_t out_frames;       /* # of frames sent out */
  101     apr_off_t out_frame_octets; /* # of RAW frame octets sent out */
  102     apr_off_t out_data_frames;  /* # of DATA frames sent */
  103     apr_off_t out_data_octets;  /* # of DATA octets (payload) sent */
  104     apr_off_t in_data_frames;   /* # of DATA frames received */
  105     apr_off_t in_data_octets;   /* # of DATA octets (payload) received */
  106     apr_off_t in_trailer_octets; /* # of HEADER octets (payload) received in trailers */
  107     
  108     h2_stream_monitor *monitor; /* optional monitor for stream states */
  109 };
  110 
  111 
  112 #define H2_STREAM_RST(s, def)    (s->rst_error? s->rst_error : (def))
  113 
  114 /**
  115  * Create a stream in H2_SS_IDLE state.
  116  * @param id      the stream identifier
  117  * @param pool    the memory pool to use for this stream
  118  * @param session the session this stream belongs to
  119  * @param monitor an optional monitor to be called for events and 
  120  *                state transisitions
  121  * @param initiated_on the id of the stream this one was initiated on (PUSH)
  122  *
  123  * @return the newly opened stream
  124  */
  125 h2_stream *h2_stream_create(int id, apr_pool_t *pool, 
  126                             struct h2_session *session,
  127                             h2_stream_monitor *monitor,
  128                             int initiated_on);
  129 
  130 /**
  131  * Destroy memory pool if still owned by the stream.
  132  */
  133 void h2_stream_destroy(h2_stream *stream);
  134 
  135 /**
  136  * Prepare the stream so that processing may start.
  137  * 
  138  * This is the time to allocated resources not needed before.
  139  * 
  140  * @param stream the stream to prep 
  141  */
  142 apr_status_t h2_stream_prep_processing(h2_stream *stream);
  143 
  144 /*
  145  * Set a new monitor for this stream, replacing any existing one. Can
  146  * be called with NULL to have no monitor installed.
  147  */
  148 void h2_stream_set_monitor(h2_stream *stream, h2_stream_monitor *monitor);
  149 
  150 /**
  151  * Dispatch (handle) an event on the given stream.
  152  * @param stream  the streama the event happened on
  153  * @param ev      the type of event
  154  */
  155 void h2_stream_dispatch(h2_stream *stream, h2_stream_event_t ev);
  156 
  157 /**
  158  * Cleanup references into requst processing.
  159  *
  160  * @param stream the stream to cleanup
  161  */
  162 void h2_stream_cleanup(h2_stream *stream);
  163 
  164 /**
  165  * Notify the stream that amount bytes have been consumed of its input
  166  * since the last invocation of this method (delta amount).
  167  */
  168 apr_status_t h2_stream_in_consumed(h2_stream *stream, apr_off_t amount);
  169 
  170 /**
  171  * Set complete stream headers from given h2_request.
  172  * 
  173  * @param stream stream to write request to
  174  * @param r the request with all the meta data
  175  * @param eos != 0 iff stream input is closed
  176  */
  177 void h2_stream_set_request(h2_stream *stream, const h2_request *r);
  178 
  179 /**
  180  * Set complete stream header from given request_rec.
  181  * 
  182  * @param stream stream to write request to
  183  * @param r the request with all the meta data
  184  * @param eos != 0 iff stream input is closed
  185  */
  186 apr_status_t h2_stream_set_request_rec(h2_stream *stream, 
  187                                        request_rec *r, int eos);
  188 
  189 /*
  190  * Add a HTTP/2 header (including pseudo headers) or trailer 
  191  * to the given stream, depending on stream state.
  192  *
  193  * @param stream stream to write the header to
  194  * @param name the name of the HTTP/2 header
  195  * @param nlen the number of characters in name
  196  * @param value the header value
  197  * @param vlen the number of characters in value
  198  */
  199 apr_status_t h2_stream_add_header(h2_stream *stream,
  200                                   const char *name, size_t nlen,
  201                                   const char *value, size_t vlen);
  202                                   
  203 /* End the construction of request headers */
  204 apr_status_t h2_stream_end_headers(h2_stream *stream, int eos, size_t raw_bytes);
  205 
  206 
  207 apr_status_t h2_stream_send_frame(h2_stream *stream, int frame_type, int flags, size_t frame_len);
  208 apr_status_t h2_stream_recv_frame(h2_stream *stream, int frame_type, int flags, size_t frame_len);
  209 
  210 /*
  211  * Process a frame of received DATA.
  212  *
  213  * @param stream stream to write the data to
  214  * @param flags the frame flags
  215  * @param data the beginning of the bytes to write
  216  * @param len the number of bytes to write
  217  */
  218 apr_status_t h2_stream_recv_DATA(h2_stream *stream, uint8_t flags,
  219                                  const uint8_t *data, size_t len);
  220 
  221 apr_status_t h2_stream_flush_input(h2_stream *stream);
  222 
  223 /**
  224  * Reset the stream. Stream write/reads will return errors afterwards.
  225  *
  226  * @param stream the stream to reset
  227  * @param error_code the HTTP/2 error code
  228  */
  229 void h2_stream_rst(h2_stream *stream, int error_code);
  230 
  231 /**
  232  * Determine if stream was closed already. This is true for
  233  * states H2_SS_CLOSED, H2_SS_CLEANUP. But not true
  234  * for H2_SS_CLOSED_L and H2_SS_CLOSED_R.
  235  *
  236  * @param stream the stream to check on
  237  * @return != 0 iff stream has been closed
  238  */
  239 int h2_stream_was_closed(const h2_stream *stream);
  240 
  241 /**
  242  * Do a speculative read on the stream output to determine the 
  243  * amount of data that can be read.
  244  * 
  245  * @param stream the stream to speculatively read from
  246  * @param plen (in-/out) number of bytes requested and on return amount of bytes that
  247  *        may be read without blocking
  248  * @param peos (out) != 0 iff end of stream will be reached when reading plen
  249  *        bytes (out value).
  250  * @param presponse (out) the response of one became available
  251  * @return APR_SUCCESS if out information was computed successfully.
  252  *         APR_EAGAIN if not data is available and end of stream has not been
  253  *         reached yet.
  254  */
  255 apr_status_t h2_stream_out_prepare(h2_stream *stream, apr_off_t *plen, 
  256                                    int *peos, h2_headers **presponse);
  257 
  258 /**
  259  * Read a maximum number of bytes into the bucket brigade.
  260  * 
  261  * @param stream the stream to read from
  262  * @param bb the brigade to append output to
  263  * @param plen (in-/out) max. number of bytes to append and on return actual
  264  *        number of bytes appended to brigade
  265  * @param peos (out) != 0 iff end of stream has been reached while reading
  266  * @return APR_SUCCESS if out information was computed successfully.
  267  *         APR_EAGAIN if not data is available and end of stream has not been
  268  *         reached yet.
  269  */
  270 apr_status_t h2_stream_read_to(h2_stream *stream, apr_bucket_brigade *bb, 
  271                                apr_off_t *plen, int *peos);
  272 
  273 /**
  274  * Get optional trailers for this stream, may be NULL. Meaningful
  275  * results can only be expected when the end of the response body has
  276  * been reached.
  277  *
  278  * @param stream to ask for trailers
  279  * @return trailers for NULL
  280  */
  281 apr_table_t *h2_stream_get_trailers(h2_stream *stream);
  282 
  283 /**
  284  * Submit any server push promises on this stream and schedule
  285  * the tasks connection with these.
  286  *
  287  * @param stream the stream for which to submit
  288  */
  289 apr_status_t h2_stream_submit_pushes(h2_stream *stream, h2_headers *response);
  290 
  291 /**
  292  * Get priority information set for this stream.
  293  */
  294 const struct h2_priority *h2_stream_get_priority(h2_stream *stream, 
  295                                                  h2_headers *response);
  296 
  297 /**
  298  * Return a textual representation of the stream state as in RFC 7540
  299  * nomenclator, all caps, underscores.
  300  */
  301 const char *h2_stream_state_str(h2_stream *stream);
  302 
  303 /**
  304  * Determine if stream is ready for submitting a response or a RST
  305  * @param stream the stream to check
  306  */
  307 int h2_stream_is_ready(h2_stream *stream);
  308 
  309 #define H2_STRM_MSG(s, msg)     \
  310     "h2_stream(%ld-%d,%s): "msg, s->session->id, s->id, h2_stream_state_str(s)
  311 
  312 #define H2_STRM_LOG(aplogno, s, msg)    aplogno H2_STRM_MSG(s, msg)
  313 
  314 #endif /* defined(__mod_h2__h2_stream__) */