cfilters.h 21 KB

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