• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 #ifndef HEADER_CURL_CFILTERS_H
2 #define HEADER_CURL_CFILTERS_H
3 /***************************************************************************
4  *                                  _   _ ____  _
5  *  Project                     ___| | | |  _ \| |
6  *                             / __| | | | |_) | |
7  *                            | (__| |_| |  _ <| |___
8  *                             \___|\___/|_| \_\_____|
9  *
10  * Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
11  *
12  * This software is licensed as described in the file COPYING, which
13  * you should have received as part of this distribution. The terms
14  * are also available at https://curl.se/docs/copyright.html.
15  *
16  * You may opt to use, copy, modify, merge, publish, distribute and/or sell
17  * copies of the Software, and permit persons to whom the Software is
18  * furnished to do so, under the terms of the COPYING file.
19  *
20  * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
21  * KIND, either express or implied.
22  *
23  * SPDX-License-Identifier: curl
24  *
25  ***************************************************************************/
26 
27 
28 struct Curl_cfilter;
29 struct Curl_easy;
30 struct Curl_dns_entry;
31 struct connectdata;
32 
33 /* Callback to destroy resources held by this filter instance.
34  * Implementations MUST NOT chain calls to cf->next.
35  */
36 typedef void     Curl_cft_destroy_this(struct Curl_cfilter *cf,
37                                        struct Curl_easy *data);
38 
39 typedef void     Curl_cft_close(struct Curl_cfilter *cf,
40                                 struct Curl_easy *data);
41 
42 typedef CURLcode Curl_cft_connect(struct Curl_cfilter *cf,
43                                   struct Curl_easy *data,
44                                   bool blocking, bool *done);
45 
46 /* Return the hostname and port the connection goes to.
47  * This may change with the connection state of filters when tunneling
48  * is involved.
49  * @param cf     the filter to ask
50  * @param data   the easy handle currently active
51  * @param phost  on return, points to the relevant, real hostname.
52  *               this is owned by the connection.
53  * @param pdisplay_host  on return, points to the printable hostname.
54  *               this is owned by the connection.
55  * @param pport  on return, contains the port number
56  */
57 typedef void     Curl_cft_get_host(struct Curl_cfilter *cf,
58                                   struct Curl_easy *data,
59                                   const char **phost,
60                                   const char **pdisplay_host,
61                                   int *pport);
62 
63 /* Filters may return sockets and fdset flags they are waiting for.
64  * The passes array has room for up to MAX_SOCKSPEREASYHANDLE sockets.
65  * @return read/write fdset for index in socks
66  *         or GETSOCK_BLANK when nothing to wait on
67  */
68 typedef int      Curl_cft_get_select_socks(struct Curl_cfilter *cf,
69                                            struct Curl_easy *data,
70                                            curl_socket_t *socks);
71 
72 typedef bool     Curl_cft_data_pending(struct Curl_cfilter *cf,
73                                        const struct Curl_easy *data);
74 
75 typedef ssize_t  Curl_cft_send(struct Curl_cfilter *cf,
76                                struct Curl_easy *data, /* transfer */
77                                const void *buf,        /* data to write */
78                                size_t len,             /* amount to write */
79                                CURLcode *err);         /* error to return */
80 
81 typedef ssize_t  Curl_cft_recv(struct Curl_cfilter *cf,
82                                struct Curl_easy *data, /* transfer */
83                                char *buf,              /* store data here */
84                                size_t len,             /* amount to read */
85                                CURLcode *err);         /* error to return */
86 
87 typedef bool     Curl_cft_conn_is_alive(struct Curl_cfilter *cf,
88                                         struct Curl_easy *data,
89                                         bool *input_pending);
90 
91 typedef CURLcode Curl_cft_conn_keep_alive(struct Curl_cfilter *cf,
92                                           struct Curl_easy *data);
93 
94 /**
95  * Events/controls for connection filters, their arguments and
96  * return code handling. Filter callbacks are invoked "top down".
97  * Return code handling:
98  * "first fail" meaning that the first filter returning != CURLE_OK, will
99  *              abort further event distribution and determine the result.
100  * "ignored" meaning return values are ignored and the event is distributed
101  *           to all filters in the chain. Overall result is always CURLE_OK.
102  */
103 /*      data event                          arg1       arg2     return */
104 #define CF_CTRL_DATA_ATTACH           1  /* 0          NULL     ignored */
105 #define CF_CTRL_DATA_DETACH           2  /* 0          NULL     ignored */
106 #define CF_CTRL_DATA_SETUP            4  /* 0          NULL     first fail */
107 #define CF_CTRL_DATA_IDLE             5  /* 0          NULL     first fail */
108 #define CF_CTRL_DATA_PAUSE            6  /* on/off     NULL     first fail */
109 #define CF_CTRL_DATA_DONE             7  /* premature  NULL     ignored */
110 #define CF_CTRL_DATA_DONE_SEND        8  /* 0          NULL     ignored */
111 /* update conn info at connection and data */
112 #define CF_CTRL_CONN_INFO_UPDATE (256+0) /* 0          NULL     ignored */
113 
114 /**
115  * Handle event/control for the filter.
116  * Implementations MUST NOT chain calls to cf->next.
117  */
118 typedef CURLcode Curl_cft_cntrl(struct Curl_cfilter *cf,
119                                 struct Curl_easy *data,
120                                 int event, int arg1, void *arg2);
121 
122 
123 /**
124  * Queries to ask via a `Curl_cft_query *query` method on a cfilter chain.
125  * - MAX_CONCURRENT: the maximum number of parallel transfers the filter
126  *                   chain expects to handle at the same time.
127  *                   default: 1 if no filter overrides.
128  * - CONNECT_REPLY_MS: milliseconds until the first indication of a server
129  *                   response was received on a connect. For TCP, this
130  *                   reflects the time until the socket connected. On UDP
131  *                   this gives the time the first bytes from the server
132  *                   were received.
133  *                   -1 if not determined yet.
134  * - CF_QUERY_SOCKET: the socket used by the filter chain
135  */
136 /*      query                             res1       res2     */
137 #define CF_QUERY_MAX_CONCURRENT     1  /* number     -        */
138 #define CF_QUERY_CONNECT_REPLY_MS   2  /* number     -        */
139 #define CF_QUERY_SOCKET             3  /* -          curl_socket_t */
140 #define CF_QUERY_TIMER_CONNECT      4  /* -          struct curltime */
141 #define CF_QUERY_TIMER_APPCONNECT   5  /* -          struct curltime */
142 
143 /**
144  * Query the cfilter for properties. Filters ignorant of a query will
145  * pass it "down" the filter chain.
146  */
147 typedef CURLcode Curl_cft_query(struct Curl_cfilter *cf,
148                                 struct Curl_easy *data,
149                                 int query, int *pres1, void *pres2);
150 
151 /**
152  * Type flags for connection filters. A filter can have none, one or
153  * many of those. Use to evaluate state/capabilities of a filter chain.
154  *
155  * CF_TYPE_IP_CONNECT: provides an IP connection or sth equivalent, like
156  *                     a CONNECT tunnel, a UNIX domain socket, a QUIC
157  *                     connection, etc.
158  * CF_TYPE_SSL:        provide SSL/TLS
159  * CF_TYPE_MULTIPLEX:  provides multiplexing of easy handles
160  */
161 #define CF_TYPE_IP_CONNECT  (1 << 0)
162 #define CF_TYPE_SSL         (1 << 1)
163 #define CF_TYPE_MULTIPLEX   (1 << 2)
164 
165 /* A connection filter type, e.g. specific implementation. */
166 struct Curl_cftype {
167   const char *name;                       /* name of the filter type */
168   int flags;                              /* flags of filter type */
169   int log_level;                          /* log level for such filters */
170   Curl_cft_destroy_this *destroy;         /* destroy resources of this cf */
171   Curl_cft_connect *connect;              /* establish connection */
172   Curl_cft_close *close;                  /* close conn */
173   Curl_cft_get_host *get_host;            /* host filter talks to */
174   Curl_cft_get_select_socks *get_select_socks;/* sockets to select on */
175   Curl_cft_data_pending *has_data_pending;/* conn has data pending */
176   Curl_cft_send *do_send;                 /* send data */
177   Curl_cft_recv *do_recv;                 /* receive data */
178   Curl_cft_cntrl *cntrl;                  /* events/control */
179   Curl_cft_conn_is_alive *is_alive;       /* FALSE if conn is dead, Jim! */
180   Curl_cft_conn_keep_alive *keep_alive;   /* try to keep it alive */
181   Curl_cft_query *query;                  /* query filter chain */
182 };
183 
184 /* A connection filter instance, e.g. registered at a connection */
185 struct Curl_cfilter {
186   const struct Curl_cftype *cft; /* the type providing implementation */
187   struct Curl_cfilter *next;     /* next filter in chain */
188   void *ctx;                     /* filter type specific settings */
189   struct connectdata *conn;      /* the connection this filter belongs to */
190   int sockindex;                 /* the index the filter is installed at */
191   BIT(connected);                /* != 0 iff this filter is connected */
192 };
193 
194 /* Default implementations for the type functions, implementing nop. */
195 void Curl_cf_def_destroy_this(struct Curl_cfilter *cf,
196                               struct Curl_easy *data);
197 
198 /* Default implementations for the type functions, implementing pass-through
199  * the filter chain. */
200 void     Curl_cf_def_close(struct Curl_cfilter *cf, struct Curl_easy *data);
201 CURLcode Curl_cf_def_connect(struct Curl_cfilter *cf,
202                              struct Curl_easy *data,
203                              bool blocking, bool *done);
204 void     Curl_cf_def_get_host(struct Curl_cfilter *cf, struct Curl_easy *data,
205                               const char **phost, const char **pdisplay_host,
206                               int *pport);
207 int      Curl_cf_def_get_select_socks(struct Curl_cfilter *cf,
208                                       struct Curl_easy *data,
209                                       curl_socket_t *socks);
210 bool     Curl_cf_def_data_pending(struct Curl_cfilter *cf,
211                                   const struct Curl_easy *data);
212 ssize_t  Curl_cf_def_send(struct Curl_cfilter *cf, struct Curl_easy *data,
213                           const void *buf, size_t len, CURLcode *err);
214 ssize_t  Curl_cf_def_recv(struct Curl_cfilter *cf, struct Curl_easy *data,
215                           char *buf, size_t len, CURLcode *err);
216 CURLcode Curl_cf_def_cntrl(struct Curl_cfilter *cf,
217                                 struct Curl_easy *data,
218                                 int event, int arg1, void *arg2);
219 bool     Curl_cf_def_conn_is_alive(struct Curl_cfilter *cf,
220                                    struct Curl_easy *data,
221                                    bool *input_pending);
222 CURLcode Curl_cf_def_conn_keep_alive(struct Curl_cfilter *cf,
223                                      struct Curl_easy *data);
224 CURLcode Curl_cf_def_query(struct Curl_cfilter *cf,
225                            struct Curl_easy *data,
226                            int query, int *pres1, void *pres2);
227 
228 /**
229  * Create a new filter instance, unattached to the filter chain.
230  * Use Curl_conn_cf_add() to add it to the chain.
231  * @param pcf  on success holds the created instance
232  * @param cft   the filter type
233  * @param ctx  the type specific context to use
234  */
235 CURLcode Curl_cf_create(struct Curl_cfilter **pcf,
236                         const struct Curl_cftype *cft,
237                         void *ctx);
238 
239 /**
240  * Add a filter instance to the `sockindex` filter chain at connection
241  * `conn`. The filter must not already be attached. It is inserted at
242  * the start of the chain (top).
243  */
244 void Curl_conn_cf_add(struct Curl_easy *data,
245                       struct connectdata *conn,
246                       int sockindex,
247                       struct Curl_cfilter *cf);
248 
249 /**
250  * Insert a filter (chain) after `cf_at`.
251  * `cf_new` must not already be attached.
252  */
253 void Curl_conn_cf_insert_after(struct Curl_cfilter *cf_at,
254                                struct Curl_cfilter *cf_new);
255 
256 /**
257  * Discard, e.g. remove and destroy a specific filter instance.
258  * If the filter is attached to a connection, it will be removed before
259  * it is destroyed.
260  */
261 void Curl_conn_cf_discard(struct Curl_cfilter *cf, struct Curl_easy *data);
262 
263 /**
264  * Discard all cfilters starting with `*pcf` and clearing it afterwards.
265  */
266 void Curl_conn_cf_discard_chain(struct Curl_cfilter **pcf,
267                                 struct Curl_easy *data);
268 
269 /**
270  * Remove and destroy all filters at chain `sockindex` on connection `conn`.
271  */
272 void Curl_conn_cf_discard_all(struct Curl_easy *data,
273                               struct connectdata *conn,
274                               int sockindex);
275 
276 
277 CURLcode Curl_conn_cf_connect(struct Curl_cfilter *cf,
278                               struct Curl_easy *data,
279                               bool blocking, bool *done);
280 void Curl_conn_cf_close(struct Curl_cfilter *cf, struct Curl_easy *data);
281 int Curl_conn_cf_get_select_socks(struct Curl_cfilter *cf,
282                                   struct Curl_easy *data,
283                                   curl_socket_t *socks);
284 bool Curl_conn_cf_data_pending(struct Curl_cfilter *cf,
285                                const struct Curl_easy *data);
286 ssize_t Curl_conn_cf_send(struct Curl_cfilter *cf, struct Curl_easy *data,
287                           const void *buf, size_t len, CURLcode *err);
288 ssize_t Curl_conn_cf_recv(struct Curl_cfilter *cf, struct Curl_easy *data,
289                           char *buf, size_t len, CURLcode *err);
290 CURLcode Curl_conn_cf_cntrl(struct Curl_cfilter *cf,
291                             struct Curl_easy *data,
292                             bool ignore_result,
293                             int event, int arg1, void *arg2);
294 
295 /**
296  * Get the socket used by the filter chain starting at `cf`.
297  * Returns CURL_SOCKET_BAD if not available.
298  */
299 curl_socket_t Curl_conn_cf_get_socket(struct Curl_cfilter *cf,
300                                       struct Curl_easy *data);
301 
302 
303 #define CURL_CF_SSL_DEFAULT  -1
304 #define CURL_CF_SSL_DISABLE  0
305 #define CURL_CF_SSL_ENABLE   1
306 
307 /**
308  * Bring the filter chain at `sockindex` for connection `data->conn` into
309  * connected state. Which will set `*done` to TRUE.
310  * This can be called on an already connected chain with no side effects.
311  * When not `blocking`, calls may return without error and `*done != TRUE`,
312  * while the individual filters negotiated the connection.
313  */
314 CURLcode Curl_conn_connect(struct Curl_easy *data, int sockindex,
315                            bool blocking, bool *done);
316 
317 /**
318  * Check if the filter chain at `sockindex` for connection `conn` is
319  * completely connected.
320  */
321 bool Curl_conn_is_connected(struct connectdata *conn, int sockindex);
322 
323 /**
324  * Determine if we have reached the remote host on IP level, e.g.
325  * have a TCP connection. This turns TRUE before a possible SSL
326  * handshake has been started/done.
327  */
328 bool Curl_conn_is_ip_connected(struct Curl_easy *data, int sockindex);
329 
330 /**
331  * Determine if the connection is using SSL to the remote host
332  * (or will be once connected). This will return FALSE, if SSL
333  * is only used in proxying and not for the tunnel itself.
334  */
335 bool Curl_conn_is_ssl(struct connectdata *conn, int sockindex);
336 
337 /**
338  * Connection provides multiplexing of easy handles at `socketindex`.
339  */
340 bool Curl_conn_is_multiplex(struct connectdata *conn, int sockindex);
341 
342 /**
343  * Close the filter chain at `sockindex` for connection `data->conn`.
344   * Filters remain in place and may be connected again afterwards.
345  */
346 void Curl_conn_close(struct Curl_easy *data, int sockindex);
347 
348 /**
349  * Return if data is pending in some connection filter at chain
350  * `sockindex` for connection `data->conn`.
351  */
352 bool Curl_conn_data_pending(struct Curl_easy *data,
353                             int sockindex);
354 
355 /**
356  * Return the socket used on data's connection for the index.
357  * Returns CURL_SOCKET_BAD if not available.
358  */
359 curl_socket_t Curl_conn_get_socket(struct Curl_easy *data, int sockindex);
360 
361 /**
362  * Get any select fd flags and the socket filters at chain `sockindex`
363  * at connection `conn` might be waiting for.
364  */
365 int Curl_conn_get_select_socks(struct Curl_easy *data, int sockindex,
366                                curl_socket_t *socks);
367 
368 /**
369  * Receive data through the filter chain at `sockindex` for connection
370  * `data->conn`. Copy at most `len` bytes into `buf`. Return the
371  * actuel number of bytes copied or a negative value on error.
372  * The error code is placed into `*code`.
373  */
374 ssize_t Curl_conn_recv(struct Curl_easy *data, int sockindex, char *buf,
375                        size_t len, CURLcode *code);
376 
377 /**
378  * Send `len` bytes of data from `buf` through the filter chain `sockindex`
379  * at connection `data->conn`. Return the actual number of bytes written
380  * or a negative value on error.
381  * The error code is placed into `*code`.
382  */
383 ssize_t Curl_conn_send(struct Curl_easy *data, int sockindex,
384                        const void *buf, size_t len, CURLcode *code);
385 
386 /**
387  * The easy handle `data` is being attached to `conn`. This does
388  * not mean that data will actually do a transfer. Attachment is
389  * also used for temporary actions on the connection.
390  */
391 void Curl_conn_ev_data_attach(struct connectdata *conn,
392                               struct Curl_easy *data);
393 
394 /**
395  * The easy handle `data` is being detached (no longer served)
396  * by connection `conn`. All filters are informed to release any resources
397  * related to `data`.
398  * Note: there may be several `data` attached to a connection at the same
399  * time.
400  */
401 void Curl_conn_ev_data_detach(struct connectdata *conn,
402                               struct Curl_easy *data);
403 
404 /**
405  * Notify connection filters that they need to setup data for
406  * a transfer.
407  */
408 CURLcode Curl_conn_ev_data_setup(struct Curl_easy *data);
409 
410 /**
411  * Notify connection filters that now would be a good time to
412  * perform any idle, e.g. time related, actions.
413  */
414 CURLcode Curl_conn_ev_data_idle(struct Curl_easy *data);
415 
416 /**
417  * Notify connection filters that the transfer represented by `data`
418  * is donw with sending data (e.g. has uploaded everything).
419  */
420 void Curl_conn_ev_data_done_send(struct Curl_easy *data);
421 
422 /**
423  * Notify connection filters that the transfer represented by `data`
424  * is finished - eventually premature, e.g. before being complete.
425  */
426 void Curl_conn_ev_data_done(struct Curl_easy *data, bool premature);
427 
428 /**
429  * Notify connection filters that the transfer of data is paused/unpaused.
430  */
431 CURLcode Curl_conn_ev_data_pause(struct Curl_easy *data, bool do_pause);
432 
433 /**
434  * Inform connection filters to update their info in `conn`.
435  */
436 void Curl_conn_ev_update_info(struct Curl_easy *data,
437                               struct connectdata *conn);
438 
439 /**
440  * Update connection statistics
441  */
442 void Curl_conn_report_connect_stats(struct Curl_easy *data,
443                                     struct connectdata *conn);
444 
445 /**
446  * Check if FIRSTSOCKET's cfilter chain deems connection alive.
447  */
448 bool Curl_conn_is_alive(struct Curl_easy *data, struct connectdata *conn,
449                         bool *input_pending);
450 
451 /**
452  * Try to upkeep the connection filters at sockindex.
453  */
454 CURLcode Curl_conn_keep_alive(struct Curl_easy *data,
455                               struct connectdata *conn,
456                               int sockindex);
457 
458 void Curl_conn_get_host(struct Curl_easy *data, int sockindex,
459                         const char **phost, const char **pdisplay_host,
460                         int *pport);
461 
462 /**
463  * Get the maximum number of parallel transfers the connection
464  * expects to be able to handle at `sockindex`.
465  */
466 size_t Curl_conn_get_max_concurrent(struct Curl_easy *data,
467                                     struct connectdata *conn,
468                                     int sockindex);
469 
470 
471 /**
472  * Types and macros used to keep the current easy handle in filter calls,
473  * allowing for nested invocations. See #10336.
474  *
475  * `cf_call_data` is intended to be a member of the cfilter's `ctx` type.
476  * A filter defines the macro `CF_CTX_CALL_DATA` to give access to that.
477  *
478  * With all values 0, the default, this indicates that there is no cfilter
479  * call with `data` ongoing.
480  * Macro `CF_DATA_SAVE` preserves the current `cf_call_data` in a local
481  * variable and sets the `data` given, incrementing the `depth` counter.
482  *
483  * Macro `CF_DATA_RESTORE` restores the old values from the local variable,
484  * while checking that `depth` values are as expected (debug build), catching
485  * cases where a "lower" RESTORE was not called.
486  *
487  * Finally, macro `CF_DATA_CURRENT` gives the easy handle of the current
488  * invocation.
489  */
490 struct cf_call_data {
491   struct Curl_easy *data;
492 #ifdef DEBUGBUILD
493   int depth;
494 #endif
495 };
496 
497 /**
498  * define to access the `struct cf_call_data for a cfilter. Normally
499  * a member in the cfilter's `ctx`.
500  *
501  * #define CF_CTX_CALL_DATA(cf)   -> struct cf_call_data instance
502 */
503 
504 #ifdef DEBUGBUILD
505 
506 #define CF_DATA_SAVE(save, cf, data) \
507   do { \
508     (save) = CF_CTX_CALL_DATA(cf); \
509     DEBUGASSERT((save).data == NULL || (save).depth > 0); \
510     CF_CTX_CALL_DATA(cf).depth++;  \
511     CF_CTX_CALL_DATA(cf).data = (struct Curl_easy *)data; \
512   } while(0)
513 
514 #define CF_DATA_RESTORE(cf, save) \
515   do { \
516     DEBUGASSERT(CF_CTX_CALL_DATA(cf).depth == (save).depth + 1); \
517     DEBUGASSERT((save).data == NULL || (save).depth > 0); \
518     CF_CTX_CALL_DATA(cf) = (save); \
519   } while(0)
520 
521 #else /* DEBUGBUILD */
522 
523 #define CF_DATA_SAVE(save, cf, data) \
524   do { \
525     (save) = CF_CTX_CALL_DATA(cf); \
526     CF_CTX_CALL_DATA(cf).data = (struct Curl_easy *)data; \
527   } while(0)
528 
529 #define CF_DATA_RESTORE(cf, save) \
530   do { \
531     CF_CTX_CALL_DATA(cf) = (save); \
532   } while(0)
533 
534 #endif /* !DEBUGBUILD */
535 
536 #define CF_DATA_CURRENT(cf) \
537   ((cf)? (CF_CTX_CALL_DATA(cf).data) : NULL)
538 
539 #endif /* HEADER_CURL_CFILTERS_H */
540