serf_private.h revision 251886 
1/* Copyright 2002-2004 Justin Erenkrantz and Greg Stein
2 *
3 * Licensed under the Apache License, Version 2.0 (the "License");
4 * you may not use this file except in compliance with the License.
5 * You may obtain a copy of the License at
6 *
7 *     http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software
10 * distributed under the License is distributed on an "AS IS" BASIS,
11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 * See the License for the specific language governing permissions and
13 * limitations under the License.
14 */
15
16#ifndef _SERF_PRIVATE_H_
17#define _SERF_PRIVATE_H_
18
19/* ### what the hell? why does the APR interface have a "size" ??
20   ### the implication is that, if we bust this limit, we'd need to
21   ### stop, rebuild a pollset, and repopulate it. what suckage.  */
22#define MAX_CONN 16
23
24/* Windows does not define IOV_MAX, so we need to ensure it is defined. */
25#ifndef IOV_MAX
26#define IOV_MAX 16
27#endif
28
29#define SERF_IO_CLIENT (1)
30#define SERF_IO_CONN (2)
31#define SERF_IO_LISTENER (3)
32
33/* Internal logging facilities, set flag to 1 to enable console logging for
34   the selected component. */
35#define SSL_VERBOSE 0
36#define SSL_MSG_VERBOSE 0  /* logs decrypted requests and responses. */
37#define SOCK_VERBOSE 0
38#define SOCK_MSG_VERBOSE 0 /* logs bytes received from or written to a socket. */
39#define CONN_VERBOSE 0
40#define AUTH_VERBOSE 0
41
42
43typedef struct serf__authn_scheme_t serf__authn_scheme_t;
44
45typedef struct serf_io_baton_t {
46    int type;
47    union {
48        serf_incoming_t *client;
49        serf_connection_t *conn;
50        serf_listener_t *listener;
51    } u;
52} serf_io_baton_t;
53
54/* Holds all the information corresponding to a request/response pair. */
55struct serf_request_t {
56    serf_connection_t *conn;
57
58    apr_pool_t *respool;
59    serf_bucket_alloc_t *allocator;
60
61    /* The bucket corresponding to the request. Will be NULL once the
62     * bucket has been emptied (for delivery into the socket).
63     */
64    serf_bucket_t *req_bkt;
65
66    serf_request_setup_t setup;
67    void *setup_baton;
68
69    serf_response_acceptor_t acceptor;
70    void *acceptor_baton;
71
72    serf_response_handler_t handler;
73    void *handler_baton;
74
75    serf_bucket_t *resp_bkt;
76
77    int written;
78    int priority;
79
80    /* This baton is currently only used for digest authentication, which
81       needs access to the uri of the request in the response handler.
82       If serf_request_t is replaced by a serf_http_request_t in the future,
83       which knows about uri and method and such, this baton won't be needed
84       anymore. */
85    void *auth_baton;
86
87    struct serf_request_t *next;
88};
89
90typedef struct serf_pollset_t {
91    /* the set of connections to poll */
92    apr_pollset_t *pollset;
93} serf_pollset_t;
94
95typedef struct serf__authn_info_t {
96    const char *realm;
97
98    const serf__authn_scheme_t *scheme;
99
100    void *baton;
101} serf__authn_info_t;
102
103struct serf_context_t {
104    /* the pool used for self and for other allocations */
105    apr_pool_t *pool;
106
107    void *pollset_baton;
108    serf_socket_add_t pollset_add;
109    serf_socket_remove_t pollset_rm;
110
111    /* one of our connections has a dirty pollset state. */
112    int dirty_pollset;
113
114    /* the list of active connections */
115    apr_array_header_t *conns;
116#define GET_CONN(ctx, i) (((serf_connection_t **)(ctx)->conns->elts)[i])
117
118    /* Proxy server address */
119    apr_sockaddr_t *proxy_address;
120
121    /* Progress callback */
122    serf_progress_t progress_func;
123    void *progress_baton;
124    apr_off_t progress_read;
125    apr_off_t progress_written;
126
127    /* authentication info for this context, shared by all connections. */
128    serf__authn_info_t authn_info;
129    serf__authn_info_t proxy_authn_info;
130
131    /* List of authn types supported by the client.*/
132    int authn_types;
133    /* Callback function used to get credentials for a realm. */
134    serf_credentials_callback_t cred_cb;
135};
136
137struct serf_listener_t {
138    serf_context_t *ctx;
139    serf_io_baton_t baton;
140    apr_socket_t *skt;
141    apr_pool_t *pool;
142    apr_pollfd_t desc;
143    void *accept_baton;
144    serf_accept_client_t accept_func;
145};
146
147struct serf_incoming_t {
148    serf_context_t *ctx;
149    serf_io_baton_t baton;
150    void *request_baton;
151    serf_incoming_request_cb_t request;
152    apr_socket_t *skt;
153    apr_pollfd_t desc;
154};
155
156/* States for the different stages in the lifecyle of a connection. */
157typedef enum {
158    SERF_CONN_INIT,             /* no socket created yet */
159    SERF_CONN_SETUP_SSLTUNNEL,  /* ssl tunnel being setup, no requests sent */
160    SERF_CONN_CONNECTED,        /* conn is ready to send requests */
161    SERF_CONN_CLOSING,          /* conn is closing, no more requests,
162                                   start a new socket */
163} serf__connection_state_t;
164
165struct serf_connection_t {
166    serf_context_t *ctx;
167
168    apr_status_t status;
169    serf_io_baton_t baton;
170
171    apr_pool_t *pool;
172    serf_bucket_alloc_t *allocator;
173
174    apr_sockaddr_t *address;
175
176    apr_socket_t *skt;
177    apr_pool_t *skt_pool;
178
179    /* the last reqevents we gave to pollset_add */
180    apr_int16_t reqevents;
181
182    /* the events we've seen for this connection in our returned pollset */
183    apr_int16_t seen_in_pollset;
184
185    /* are we a dirty connection that needs its poll status updated? */
186    int dirty_conn;
187
188    /* number of completed requests we've sent */
189    unsigned int completed_requests;
190
191    /* number of completed responses we've got */
192    unsigned int completed_responses;
193
194    /* keepalive */
195    unsigned int probable_keepalive_limit;
196
197    /* Current state of the connection (whether or not it is connected). */
198    serf__connection_state_t state;
199
200    /* This connection may have responses without a request! */
201    int async_responses;
202    serf_bucket_t *current_async_response;
203    serf_response_acceptor_t async_acceptor;
204    void *async_acceptor_baton;
205    serf_response_handler_t async_handler;
206    void *async_handler_baton;
207
208    /* A bucket wrapped around our socket (for reading responses). */
209    serf_bucket_t *stream;
210    /* A reference to the aggregate bucket that provides the boundary between
211     * request level buckets and connection level buckets.
212     */
213    serf_bucket_t *ostream_head;
214    serf_bucket_t *ostream_tail;
215
216    /* Aggregate bucket used to send the CONNECT request. */
217    serf_bucket_t *ssltunnel_ostream;
218
219    /* The list of active requests. */
220    serf_request_t *requests;
221    serf_request_t *requests_tail;
222
223    struct iovec vec[IOV_MAX];
224    int vec_len;
225
226    serf_connection_setup_t setup;
227    void *setup_baton;
228    serf_connection_closed_t closed;
229    void *closed_baton;
230
231    /* Max. number of outstanding requests. */
232    unsigned int max_outstanding_requests;
233
234    int hit_eof;
235    /* Host info. */
236    const char *host_url;
237    apr_uri_t host_info;
238
239    /* connection and authentication scheme specific information */
240    void *authn_baton;
241    void *proxy_authn_baton;
242
243    /* Time marker when connection begins. */
244    apr_time_t connect_time;
245
246    /* Calculated connection latency. Negative value if latency is unknown. */
247    apr_interval_time_t latency;
248};
249
250/*** Internal bucket functions ***/
251
252/** Transform a response_bucket in-place into an aggregate bucket. Restore the
253    status line and all headers, not just the body.
254
255    This can only be used when we haven't started reading the body of the
256    response yet.
257
258    Keep internal for now, probably only useful within serf.
259 */
260apr_status_t serf_response_full_become_aggregate(serf_bucket_t *bucket);
261
262/*** Authentication handler declarations ***/
263
264typedef enum { PROXY, HOST } peer_t;
265
266/**
267 * For each authentication scheme we need a handler function of type
268 * serf__auth_handler_func_t. This function will be called when an
269 * authentication challenge is received in a session.
270 */
271typedef apr_status_t
272(*serf__auth_handler_func_t)(int code,
273                             serf_request_t *request,
274                             serf_bucket_t *response,
275                             const char *auth_hdr,
276                             const char *auth_attr,
277                             void *baton,
278                             apr_pool_t *pool);
279
280/**
281 * For each authentication scheme we need an initialization function of type
282 * serf__init_context_func_t. This function will be called the first time
283 * serf tries a specific authentication scheme handler.
284 */
285typedef apr_status_t
286(*serf__init_context_func_t)(int code,
287                             serf_context_t *conn,
288                             apr_pool_t *pool);
289
290/**
291 * For each authentication scheme we need an initialization function of type
292 * serf__init_conn_func_t. This function will be called when a new
293 * connection is opened.
294 */
295typedef apr_status_t
296(*serf__init_conn_func_t)(int code,
297                          serf_connection_t *conn,
298                          apr_pool_t *pool);
299
300/**
301 * For each authentication scheme we need a setup_request function of type
302 * serf__setup_request_func_t. This function will be called when a
303 * new serf_request_t object is created and should fill in the correct
304 * authentication headers (if needed).
305 */
306typedef apr_status_t
307(*serf__setup_request_func_t)(peer_t peer,
308                              int code,
309                              serf_connection_t *conn,
310                              serf_request_t *request,
311                              const char *method,
312                              const char *uri,
313                              serf_bucket_t *hdrs_bkt);
314
315/**
316 * This function will be called when a response is received, so that the
317 * scheme handler can validate the Authentication related response headers
318 * (if needed).
319 */
320typedef apr_status_t
321(*serf__validate_response_func_t)(peer_t peer,
322                                  int code,
323                                  serf_connection_t *conn,
324                                  serf_request_t *request,
325                                  serf_bucket_t *response,
326                                  apr_pool_t *pool);
327
328/**
329 * serf__authn_scheme_t: vtable for an authn scheme provider.
330 */
331struct serf__authn_scheme_t {
332    /* The http status code that's handled by this authentication scheme.
333       Normal values are 401 for server authentication and 407 for proxy
334       authentication */
335    int code;
336
337    /* The name of this authentication scheme. This should be a case
338       sensitive match of the string sent in the HTTP authentication header. */
339    const char *name;
340
341    /* Internal code used for this authn type. */
342    int type;
343
344    /* The context initialization function if any; otherwise, NULL */
345    serf__init_context_func_t init_ctx_func;
346
347    /* The connection initialization function if any; otherwise, NULL */
348    serf__init_conn_func_t init_conn_func;
349
350    /* The authentication handler function */
351    serf__auth_handler_func_t handle_func;
352
353    /* Function to set up the authentication header of a request */
354    serf__setup_request_func_t setup_request_func;
355
356    /* Function to validate the authentication header of a response */
357    serf__validate_response_func_t validate_response_func;
358};
359
360/**
361 * Handles a 401 or 407 response, tries the different available authentication
362 * handlers.
363 */
364apr_status_t serf__handle_auth_response(int *consumed_response,
365                                        serf_request_t *request,
366                                        serf_bucket_t *response,
367                                        void *baton,
368                                        apr_pool_t *pool);
369
370/* fromt context.c */
371void serf__context_progress_delta(void *progress_baton, apr_off_t read,
372                                  apr_off_t written);
373
374/* from incoming.c */
375apr_status_t serf__process_client(serf_incoming_t *l, apr_int16_t events);
376apr_status_t serf__process_listener(serf_listener_t *l);
377
378/* from outgoing.c */
379apr_status_t serf__open_connections(serf_context_t *ctx);
380apr_status_t serf__process_connection(serf_connection_t *conn,
381                                       apr_int16_t events);
382apr_status_t serf__conn_update_pollset(serf_connection_t *conn);
383
384/* from ssltunnel.c */
385apr_status_t serf__ssltunnel_connect(serf_connection_t *conn);
386
387
388/** Logging functions. Use one of the [COMP]_VERBOSE flags to enable specific
389    logging.
390 **/
391
392/* Logs a standard event, with filename & timestamp header */
393void serf__log(int verbose_flag, const char *filename, const char *fmt, ...);
394
395/* Logs a standard event, but without prefix. This is useful to build up
396 log lines in parts. */
397void serf__log_nopref(int verbose_flag, const char *fmt, ...);
398
399/* Logs a socket event, add local and remote ip address:port */
400void serf__log_skt(int verbose_flag, const char *filename, apr_socket_t *skt,
401                   const char *fmt, ...);
402
403#endif
404