contrib/unbound/util/netevent.h

   1 /*
   2  * util/netevent.h - event notification
   3  *
   4  * Copyright (c) 2007, NLnet Labs. All rights reserved.
   5  *
   6  * This software is open source.
   7  *
   8  * Redistribution and use in source and binary forms, with or without
   9  * modification, are permitted provided that the following conditions
  10  * are met:
  11  *
  12  * Redistributions of source code must retain the above copyright notice,
  13  * this list of conditions and the following disclaimer.
  14  *
  15  * Redistributions in binary form must reproduce the above copyright notice,
  16  * this list of conditions and the following disclaimer in the documentation
  17  * and/or other materials provided with the distribution.
  18  *
  19  * Neither the name of the NLNET LABS nor the names of its contributors may
  20  * be used to endorse or promote products derived from this software without
  21  * specific prior written permission.
  22  *
  23  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  24  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  25  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  26  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  27  * HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  28  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
  29  * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
  30  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
  31  * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
  32  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  33  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  34  */
  35
  36 /**
  37  * \file
  38  *
  39  * This file contains event notification functions.
  40  *
  41  * There are three types of communication points
  42  *    o UDP socket - perthread buffer.
  43  *    o TCP-accept socket - array of TCP-sockets, socketcount.
  44  *    o TCP socket - own buffer, parent-TCPaccept, read/write state,
  45  *                   number of bytes read/written, timeout.
  46  *
  47  * There are sockets aimed towards our clients and towards the internet.
  48  *    o frontside - aimed towards our clients, queries come in, answers back.
  49  *    o behind - aimed towards internet, to the authoritative DNS servers.
  50  *
  51  * Several event types are available:
  52  *    o comm_base - for thread safety of the comm points, one per thread.
  53  *    o comm_point - udp and tcp networking, with callbacks.
  54  *    o comm_timer - a timeout with callback.
  55  *    o comm_signal - callbacks when signal is caught.
  56  *    o comm_reply - holds reply info during networking callback.
  57  *
  58  */
  59
  60 #ifndef NET_EVENT_H
  61 #define NET_EVENT_H
  62
  63 #include "dnscrypt/dnscrypt.h"
  64 #ifdef HAVE_NGHTTP2_NGHTTP2_H
  65 #include <nghttp2/nghttp2.h>
  66 #endif
  67
  68 struct sldns_buffer;
  69 struct comm_point;
  70 struct comm_reply;
  71 struct tcl_list;
  72 struct ub_event_base;
  73
  74 struct mesh_state;
  75 struct mesh_area;
  76
  77 /* internal event notification data storage structure. */
  78 struct internal_event;
  79 struct internal_base;
  80 struct internal_timer; /* A sub struct of the comm_timer super struct */
  81
  82 enum listen_type;
  83
  84 /** callback from communication point function type */
  85 typedef int comm_point_callback_type(struct comm_point*, void*, int,
  86         struct comm_reply*);
  87
  88 /** to pass no_error to callback function */
  89 #define NETEVENT_NOERROR 0
  90 /** to pass closed connection to callback function */
  91 #define NETEVENT_CLOSED -1
  92 /** to pass timeout happened to callback function */
  93 #define NETEVENT_TIMEOUT -2
  94 /** to pass fallback from capsforID to callback function; 0x20 failed */
  95 #define NETEVENT_CAPSFAIL -3
  96 /** to pass done transfer to callback function; http file is complete */
  97 #define NETEVENT_DONE -4
  98 /** to pass write of the write packet is done to callback function
  99  * used when tcp_write_and_read is enabled */
 100 #define NETEVENT_PKT_WRITTEN -5
 101
 102 /** timeout to slow accept calls when not possible, in msec. */
 103 #define NETEVENT_SLOW_ACCEPT_TIME 2000
 104
 105 /**
 106  * A communication point dispatcher. Thread specific.
 107  */
 108 struct comm_base {
 109         /** behind the scenes structure. with say libevent info. alloced */
 110         struct internal_base* eb;
 111         /** callback to stop listening on accept sockets,
 112          * performed when accept() will not function properly */
 113         void (*stop_accept)(void*);
 114         /** callback to start listening on accept sockets, performed
 115          * after stop_accept() then a timeout has passed. */
 116         void (*start_accept)(void*);
 117         /** user argument for stop_accept and start_accept functions */
 118         void* cb_arg;
 119 };
 120
 121 /**
 122  * Reply information for a communication point.
 123  */
 124 struct comm_reply {
 125         /** the comm_point with fd to send reply on to. */
 126         struct comm_point* c;
 127         /** the address (for UDP based communication) */
 128         struct sockaddr_storage addr;
 129         /** length of address */
 130         socklen_t addrlen;
 131         /** return type 0 (none), 4(IP4), 6(IP6) */
 132         int srctype;
 133         /* DnsCrypt context */
 134 #ifdef USE_DNSCRYPT
 135         uint8_t client_nonce[crypto_box_HALF_NONCEBYTES];
 136         uint8_t nmkey[crypto_box_BEFORENMBYTES];
 137         const dnsccert *dnsc_cert;
 138         int is_dnscrypted;
 139 #endif
 140         /** the return source interface data */
 141         union {
 142 #ifdef IPV6_PKTINFO
 143                 struct in6_pktinfo v6info;
 144 #endif
 145 #ifdef IP_PKTINFO
 146                 struct in_pktinfo v4info;
 147 #elif defined(IP_RECVDSTADDR)
 148                 struct in_addr v4addr;
 149 #endif
 150         }
 151                 /** variable with return source data */
 152                 pktinfo;
 153         /** max udp size for udp packets */
 154         size_t max_udp_size;
 155 };
 156
 157 /**
 158  * Communication point to the network
 159  * These behaviours can be accomplished by setting the flags
 160  * and passing return values from the callback.
 161  *    udp frontside: called after readdone. sendafter.
 162  *    tcp frontside: called readdone, sendafter. close.
 163  *    udp behind: called after readdone. No send after.
 164  *    tcp behind: write done, read done, then called. No send after.
 165  */
 166 struct comm_point {
 167         /** behind the scenes structure, with say libevent info. alloced. */
 168         struct internal_event* ev;
 169
 170         /** file descriptor for communication point */
 171         int fd;
 172
 173         /** timeout (NULL if it does not). Malloced. */
 174         struct timeval* timeout;
 175
 176         /** buffer pointer. Either to perthread, or own buffer or NULL */
 177         struct sldns_buffer* buffer;
 178
 179         /* -------- TCP Handler -------- */
 180         /** Read/Write state for TCP */
 181         int tcp_is_reading;
 182         /** The current read/write count for TCP */
 183         size_t tcp_byte_count;
 184         /** parent communication point (for TCP sockets) */
 185         struct comm_point* tcp_parent;
 186         /** sockaddr from peer, for TCP handlers */
 187         struct comm_reply repinfo;
 188
 189         /* -------- TCP Accept -------- */
 190         /** the number of TCP handlers for this tcp-accept socket */
 191         int max_tcp_count;
 192         /** current number of tcp handler in-use for this accept socket */
 193         int cur_tcp_count;
 194         /** malloced array of tcp handlers for a tcp-accept,
 195             of size max_tcp_count. */
 196         struct comm_point** tcp_handlers;
 197         /** linked list of free tcp_handlers to use for new queries.
 198             For tcp_accept the first entry, for tcp_handlers the next one. */
 199         struct comm_point* tcp_free;
 200
 201         /* -------- SSL TCP DNS ------- */
 202         /** the SSL object with rw bio (owned) or for commaccept ctx ref */
 203         void* ssl;
 204         /** handshake state for init and renegotiate */
 205         enum {
 206                 /** no handshake, it has been done */
 207                 comm_ssl_shake_none = 0,
 208                 /** ssl initial handshake wants to read */
 209                 comm_ssl_shake_read,
 210                 /** ssl initial handshake wants to write */
 211                 comm_ssl_shake_write,
 212                 /** ssl_write wants to read */
 213                 comm_ssl_shake_hs_read,
 214                 /** ssl_read wants to write */
 215                 comm_ssl_shake_hs_write
 216         } ssl_shake_state;
 217
 218         /* -------- HTTP ------- */
 219         /** Do not allow connection to use HTTP version lower than this. 0=no
 220          * minimum. */
 221         enum {
 222                 http_version_none = 0,
 223                 http_version_2 = 2
 224         } http_min_version;
 225         /** http endpoint */
 226         char* http_endpoint;
 227         /* -------- HTTP/1.1 ------- */
 228         /** Currently reading in http headers */
 229         int http_in_headers;
 230         /** Currently reading in chunk headers, 0=not, 1=firstline, 2=unused
 231          * (more lines), 3=trailer headers after chunk */
 232         int http_in_chunk_headers;
 233         /** chunked transfer */
 234         int http_is_chunked;
 235         /** http temp buffer (shared buffer for temporary work) */
 236         struct sldns_buffer* http_temp;
 237         /** http stored content in buffer */
 238         size_t http_stored;
 239         /* -------- HTTP/2 ------- */
 240         /** http2 session */
 241         struct http2_session* h2_session;
 242         /** set to 1 if h2 is negotiated to be used (using alpn) */
 243         int use_h2;
 244         /** stream currently being handled */
 245         struct http2_stream* h2_stream;
 246         /** maximum allowed query buffer size, per stream */
 247         size_t http2_stream_max_qbuffer_size;
 248         /** maximum number of HTTP/2 streams per connection. Send in HTTP/2
 249          * SETTINGS frame. */
 250         uint32_t http2_max_streams;
 251
 252         /* -------- dnstap ------- */
 253         /** the dnstap environment */
 254         struct dt_env* dtenv;
 255
 256         /** is this a UDP, TCP-accept or TCP socket. */
 257         enum comm_point_type {
 258                 /** UDP socket - handle datagrams. */
 259                 comm_udp,
 260                 /** TCP accept socket - only creates handlers if readable. */
 261                 comm_tcp_accept,
 262                 /** TCP handler socket - handle byteperbyte readwrite. */
 263                 comm_tcp,
 264                 /** HTTP handler socket */
 265                 comm_http,
 266                 /** AF_UNIX socket - for internal commands. */
 267                 comm_local,
 268                 /** raw - not DNS format - for pipe readers and writers */
 269                 comm_raw
 270         }
 271                 /** variable with type of socket, UDP,TCP-accept,TCP,pipe */
 272                 type;
 273
 274         /* ---------- Behaviour ----------- */
 275         /** if set the connection is NOT closed on delete. */
 276         int do_not_close;
 277
 278         /** if set, the connection is closed on error, on timeout,
 279             and after read/write completes. No callback is done. */
 280         int tcp_do_close;
 281
 282         /** flag that indicates the stream is both written and read from. */
 283         int tcp_write_and_read;
 284
 285         /** byte count for written length over write channel, for when
 286          * tcp_write_and_read is enabled.  When tcp_write_and_read is enabled,
 287          * this is the counter for writing, the one for reading is in the
 288          * commpoint.buffer sldns buffer.  The counter counts from 0 to
 289          * 2+tcp_write_pkt_len, and includes the tcp length bytes. */
 290         size_t tcp_write_byte_count;
 291
 292         /** packet to write currently over the write channel. for when
 293          * tcp_write_and_read is enabled.  When tcp_write_and_read is enabled,
 294          * this is the buffer for the written packet, the commpoint.buffer
 295          * sldns buffer is the buffer for the received packet. */
 296         uint8_t* tcp_write_pkt;
 297         /** length of tcp_write_pkt in bytes */
 298         size_t tcp_write_pkt_len;
 299
 300         /** if set try to read another packet again (over connection with
 301          * multiple packets), once set, tries once, then zero again,
 302          * so set it in the packet complete section.
 303          * The pointer itself has to be set before the callback is invoked,
 304          * when you set things up, and continue to exist also after the
 305          * commpoint is closed and deleted in your callback.  So that after
 306          * the callback cleans up netevent can see what it has to do.
 307          * Or leave NULL if it is not used at all. */
 308         int* tcp_more_read_again;
 309
 310         /** if set try to write another packet (over connection with
 311          * multiple packets), once set, tries once, then zero again,
 312          * so set it in the packet complete section.
 313          * The pointer itself has to be set before the callback is invoked,
 314          * when you set things up, and continue to exist also after the
 315          * commpoint is closed and deleted in your callback.  So that after
 316          * the callback cleans up netevent can see what it has to do.
 317          * Or leave NULL if it is not used at all. */
 318         int* tcp_more_write_again;
 319
 320         /** if set, read/write completes:
 321                 read/write state of tcp is toggled.
 322                 buffer reset/bytecount reset.
 323                 this flag cleared.
 324             So that when that is done the callback is called. */
 325         int tcp_do_toggle_rw;
 326
 327         /** timeout in msec for TCP wait times for this connection */
 328         int tcp_timeout_msec;
 329
 330         /** if set, tcp keepalive is enabled on this connection */
 331         int tcp_keepalive;
 332
 333         /** if set, checks for pending error from nonblocking connect() call.*/
 334         int tcp_check_nb_connect;
 335
 336         /** if set, check for connection limit on tcp accept. */
 337         struct tcl_list* tcp_conn_limit;
 338         /** the entry for the connection. */
 339         struct tcl_addr* tcl_addr;
 340
 341         /** the structure to keep track of open requests on this channel */
 342         struct tcp_req_info* tcp_req_info;
 343
 344 #ifdef USE_MSG_FASTOPEN
 345         /** used to track if the sendto() call should be done when using TFO. */
 346         int tcp_do_fastopen;
 347 #endif
 348
 349 #ifdef USE_DNSCRYPT
 350         /** Is this a dnscrypt channel */
 351         int dnscrypt;
 352         /** encrypted buffer pointer. Either to perthread, or own buffer or NULL */
 353         struct sldns_buffer* dnscrypt_buffer;
 354 #endif
 355         /** number of queries outstanding on this socket, used by
 356          * outside network for udp ports */
 357         int inuse;
 358
 359         /** callback when done.
 360             tcp_accept does not get called back, is NULL then.
 361             If a timeout happens, callback with timeout=1 is called.
 362             If an error happens, callback is called with error set
 363             nonzero. If not NETEVENT_NOERROR, it is an errno value.
 364             If the connection is closed (by remote end) then the
 365             callback is called with error set to NETEVENT_CLOSED=-1.
 366             If a timeout happens on the connection, the error is set to
 367             NETEVENT_TIMEOUT=-2.
 368             The reply_info can be copied if the reply needs to happen at a
 369             later time. It consists of a struct with commpoint and address.
 370             It can be passed to a msg send routine some time later.
 371             Note the reply information is temporary and must be copied.
 372             NULL is passed for_reply info, in cases where error happened.
 373
 374             declare as:
 375             int my_callback(struct comm_point* c, void* my_arg, int error,
 376                 struct comm_reply *reply_info);
 377
 378             if the routine returns 0, nothing is done.
 379             Notzero, the buffer will be sent back to client.
 380                         For UDP this is done without changing the commpoint.
 381                         In TCP it sets write state.
 382         */
 383         comm_point_callback_type* callback;
 384         /** argument to pass to callback. */
 385         void *cb_arg;
 386 };
 387
 388 /**
 389  * Structure only for making timeout events.
 390  */
 391 struct comm_timer {
 392         /** the internal event stuff (derived) */
 393         struct internal_timer* ev_timer;
 394
 395         /** callback function, takes user arg only */
 396         void (*callback)(void*);
 397
 398         /** callback user argument */
 399         void* cb_arg;
 400 };
 401
 402 /**
 403  * Structure only for signal events.
 404  */
 405 struct comm_signal {
 406         /** the communication base */
 407         struct comm_base* base;
 408
 409         /** the internal event stuff */
 410         struct internal_signal* ev_signal;
 411
 412         /** callback function, takes signal number and user arg */
 413         void (*callback)(int, void*);
 414
 415         /** callback user argument */
 416         void* cb_arg;
 417 };
 418
 419 /**
 420  * Create a new comm base.
 421  * @param sigs: if true it attempts to create a default loop for
 422  *   signal handling.
 423  * @return: the new comm base. NULL on error.
 424  */
 425 struct comm_base* comm_base_create(int sigs);
 426
 427 /**
 428  * Create comm base that uses the given ub_event_base (underlying pluggable
 429  * event mechanism pointer).
 430  * @param base: underlying pluggable event base.
 431  * @return: the new comm base. NULL on error.
 432  */
 433 struct comm_base* comm_base_create_event(struct ub_event_base* base);
 434
 435 /**
 436  * Delete comm base structure but not the underlying lib event base.
 437  * All comm points must have been deleted.
 438  * @param b: the base to delete.
 439  */
 440 void comm_base_delete_no_base(struct comm_base* b);
 441
 442 /**
 443  * Destroy a comm base.
 444  * All comm points must have been deleted.
 445  * @param b: the base to delete.
 446  */
 447 void comm_base_delete(struct comm_base* b);
 448
 449 /**
 450  * Obtain two pointers. The pointers never change (until base_delete()).
 451  * The pointers point to time values that are updated regularly.
 452  * @param b: the communication base that will update the time values.
 453  * @param tt: pointer to time in seconds is returned.
 454  * @param tv: pointer to time in microseconds is returned.
 455  */
 456 void comm_base_timept(struct comm_base* b, time_t** tt, struct timeval** tv);
 457
 458 /**
 459  * Dispatch the comm base events.
 460  * @param b: the communication to perform.
 461  */
 462 void comm_base_dispatch(struct comm_base* b);
 463
 464 /**
 465  * Exit from dispatch loop.
 466  * @param b: the communication base that is in dispatch().
 467  */
 468 void comm_base_exit(struct comm_base* b);
 469
 470 /**
 471  * Set the slow_accept mode handlers.  You can not provide these if you do
 472  * not perform accept() calls.
 473  * @param b: comm base
 474  * @param stop_accept: function that stops listening to accept fds.
 475  * @param start_accept: function that resumes listening to accept fds.
 476  * @param arg: callback arg to pass to the functions.
 477  */
 478 void comm_base_set_slow_accept_handlers(struct comm_base* b,
 479         void (*stop_accept)(void*), void (*start_accept)(void*), void* arg);
 480
 481 /**
 482  * Access internal data structure (for util/tube.c on windows)
 483  * @param b: comm base
 484  * @return ub_event_base.
 485  */
 486 struct ub_event_base* comm_base_internal(struct comm_base* b);
 487
 488 /**
 489  * Create an UDP comm point. Calls malloc.
 490  * setups the structure with the parameters you provide.
 491  * @param base: in which base to alloc the commpoint.
 492  * @param fd : file descriptor of open UDP socket.
 493  * @param buffer: shared buffer by UDP sockets from this thread.
 494  * @param callback: callback function pointer.
 495  * @param callback_arg: will be passed to your callback function.
 496  * @return: returns the allocated communication point. NULL on error.
 497  * Sets timeout to NULL. Turns off TCP options.
 498  */
 499 struct comm_point* comm_point_create_udp(struct comm_base* base,
 500         int fd, struct sldns_buffer* buffer,
 501         comm_point_callback_type* callback, void* callback_arg);
 502
 503 /**
 504  * Create an UDP with ancillary data comm point. Calls malloc.
 505  * Uses recvmsg instead of recv to get udp message.
 506  * setups the structure with the parameters you provide.
 507  * @param base: in which base to alloc the commpoint.
 508  * @param fd : file descriptor of open UDP socket.
 509  * @param buffer: shared buffer by UDP sockets from this thread.
 510  * @param callback: callback function pointer.
 511  * @param callback_arg: will be passed to your callback function.
 512  * @return: returns the allocated communication point. NULL on error.
 513  * Sets timeout to NULL. Turns off TCP options.
 514  */
 515 struct comm_point* comm_point_create_udp_ancil(struct comm_base* base,
 516         int fd, struct sldns_buffer* buffer,
 517         comm_point_callback_type* callback, void* callback_arg);
 518
 519 /**
 520  * Create a TCP listener comm point. Calls malloc.
 521  * Setups the structure with the parameters you provide.
 522  * Also Creates TCP Handlers, pre allocated for you.
 523  * Uses the parameters you provide.
 524  * @param base: in which base to alloc the commpoint.
 525  * @param fd: file descriptor of open TCP socket set to listen nonblocking.
 526  * @param num: becomes max_tcp_count, the routine allocates that
 527  *      many tcp handler commpoints.
 528  * @param idle_timeout: TCP idle timeout in ms.
 529  * @param harden_large_queries: whether query size should be limited.
 530  * @param http_max_streams: maximum number of HTTP/2 streams per connection.
 531  * @param http_endpoint: HTTP endpoint to service queries on
 532  * @param tcp_conn_limit: TCP connection limit info.
 533  * @param bufsize: size of buffer to create for handlers.
 534  * @param spoolbuf: shared spool buffer for tcp_req_info structures.
 535  *      or NULL to not create those structures in the tcp handlers.
 536  * @param port_type: the type of port we are creating a TCP listener for. Used
 537  *      to select handler type to use.
 538  * @param callback: callback function pointer for TCP handlers.
 539  * @param callback_arg: will be passed to your callback function.
 540  * @return: returns the TCP listener commpoint. You can find the
 541  *      TCP handlers in the array inside the listener commpoint.
 542  *      returns NULL on error.
 543  * Inits timeout to NULL. All handlers are on the free list.
 544  */
 545 struct comm_point* comm_point_create_tcp(struct comm_base* base,
 546         int fd, int num, int idle_timeout, int harden_large_queries,
 547         uint32_t http_max_streams, char* http_endpoint,
 548         struct tcl_list* tcp_conn_limit,
 549         size_t bufsize, struct sldns_buffer* spoolbuf,
 550         enum listen_type port_type,
 551         comm_point_callback_type* callback, void* callback_arg);
 552
 553 /**
 554  * Create an outgoing TCP commpoint. No file descriptor is opened, left at -1.
 555  * @param base: in which base to alloc the commpoint.
 556  * @param bufsize: size of buffer to create for handlers.
 557  * @param callback: callback function pointer for the handler.
 558  * @param callback_arg: will be passed to your callback function.
 559  * @return: the commpoint or NULL on error.
 560  */
 561 struct comm_point* comm_point_create_tcp_out(struct comm_base* base,
 562         size_t bufsize, comm_point_callback_type* callback, void* callback_arg);
 563
 564 /**
 565  * Create an outgoing HTTP commpoint. No file descriptor is opened, left at -1.
 566  * @param base: in which base to alloc the commpoint.
 567  * @param bufsize: size of buffer to create for handlers.
 568  * @param callback: callback function pointer for the handler.
 569  * @param callback_arg: will be passed to your callback function.
 570  * @param temp: sldns buffer, shared between other http_out commpoints, for
 571  *      temporary data when performing callbacks.
 572  * @return: the commpoint or NULL on error.
 573  */
 574 struct comm_point* comm_point_create_http_out(struct comm_base* base,
 575         size_t bufsize, comm_point_callback_type* callback,
 576         void* callback_arg, struct sldns_buffer* temp);
 577
 578 /**
 579  * Create commpoint to listen to a local domain file descriptor.
 580  * @param base: in which base to alloc the commpoint.
 581  * @param fd: file descriptor of open AF_UNIX socket set to listen nonblocking.
 582  * @param bufsize: size of buffer to create for handlers.
 583  * @param callback: callback function pointer for the handler.
 584  * @param callback_arg: will be passed to your callback function.
 585  * @return: the commpoint or NULL on error.
 586  */
 587 struct comm_point* comm_point_create_local(struct comm_base* base,
 588         int fd, size_t bufsize,
 589         comm_point_callback_type* callback, void* callback_arg);
 590
 591 /**
 592  * Create commpoint to listen to a local domain pipe descriptor.
 593  * @param base: in which base to alloc the commpoint.
 594  * @param fd: file descriptor.
 595  * @param writing: true if you want to listen to writes, false for reads.
 596  * @param callback: callback function pointer for the handler.
 597  * @param callback_arg: will be passed to your callback function.
 598  * @return: the commpoint or NULL on error.
 599  */
 600 struct comm_point* comm_point_create_raw(struct comm_base* base,
 601         int fd, int writing,
 602         comm_point_callback_type* callback, void* callback_arg);
 603
 604 /**
 605  * Close a comm point fd.
 606  * @param c: comm point to close.
 607  */
 608 void comm_point_close(struct comm_point* c);
 609
 610 /**
 611  * Close and deallocate (free) the comm point. If the comm point is
 612  * a tcp-accept point, also its tcp-handler points are deleted.
 613  * @param c: comm point to delete.
 614  */
 615 void comm_point_delete(struct comm_point* c);
 616
 617 /**
 618  * Send reply. Put message into commpoint buffer.
 619  * @param repinfo: The reply info copied from a commpoint callback call.
 620  */
 621 void comm_point_send_reply(struct comm_reply* repinfo);
 622
 623 /**
 624  * Drop reply. Cleans up.
 625  * @param repinfo: The reply info copied from a commpoint callback call.
 626  */
 627 void comm_point_drop_reply(struct comm_reply* repinfo);
 628
 629 /**
 630  * Send an udp message over a commpoint.
 631  * @param c: commpoint to send it from.
 632  * @param packet: what to send.
 633  * @param addr: where to send it to.   If NULL, send is performed,
 634  *      for connected sockets, to the connected address.
 635  * @param addrlen: length of addr.
 636  * @param is_connected: if the UDP socket is connect()ed.
 637  * @return: false on a failure.
 638  */
 639 int comm_point_send_udp_msg(struct comm_point* c, struct sldns_buffer* packet,
 640         struct sockaddr* addr, socklen_t addrlen,int is_connected);
 641
 642 /**
 643  * Stop listening for input on the commpoint. No callbacks will happen.
 644  * @param c: commpoint to disable. The fd is not closed.
 645  */
 646 void comm_point_stop_listening(struct comm_point* c);
 647
 648 /**
 649  * Start listening again for input on the comm point.
 650  * @param c: commpoint to enable again.
 651  * @param newfd: new fd, or -1 to leave fd be.
 652  * @param msec: timeout in milliseconds, or -1 for no (change to the) timeout.
 653  *      So seconds*1000.
 654  */
 655 void comm_point_start_listening(struct comm_point* c, int newfd, int msec);
 656
 657 /**
 658  * Stop listening and start listening again for reading or writing.
 659  * @param c: commpoint
 660  * @param rd: if true, listens for reading.
 661  * @param wr: if true, listens for writing.
 662  */
 663 void comm_point_listen_for_rw(struct comm_point* c, int rd, int wr);
 664
 665 /**
 666  * Get size of memory used by comm point.
 667  * For TCP handlers this includes subhandlers.
 668  * For UDP handlers, this does not include the (shared) UDP buffer.
 669  * @param c: commpoint.
 670  * @return size in bytes.
 671  */
 672 size_t comm_point_get_mem(struct comm_point* c);
 673
 674 /**
 675  * create timer. Not active upon creation.
 676  * @param base: event handling base.
 677  * @param cb: callback function: void myfunc(void* myarg);
 678  * @param cb_arg: user callback argument.
 679  * @return: the new timer or NULL on error.
 680  */
 681 struct comm_timer* comm_timer_create(struct comm_base* base,
 682         void (*cb)(void*), void* cb_arg);
 683
 684 /**
 685  * disable timer. Stops callbacks from happening.
 686  * @param timer: to disable.
 687  */
 688 void comm_timer_disable(struct comm_timer* timer);
 689
 690 /**
 691  * reset timevalue for timer.
 692  * @param timer: timer to (re)set.
 693  * @param tv: when the timer should activate. if NULL timer is disabled.
 694  */
 695 void comm_timer_set(struct comm_timer* timer, struct timeval* tv);
 696
 697 /**
 698  * delete timer.
 699  * @param timer: to delete.
 700  */
 701 void comm_timer_delete(struct comm_timer* timer);
 702
 703 /**
 704  * see if timeout has been set to a value.
 705  * @param timer: the timer to examine.
 706  * @return: false if disabled or not set.
 707  */
 708 int comm_timer_is_set(struct comm_timer* timer);
 709
 710 /**
 711  * Get size of memory used by comm timer.
 712  * @param timer: the timer to examine.
 713  * @return size in bytes.
 714  */
 715 size_t comm_timer_get_mem(struct comm_timer* timer);
 716
 717 /**
 718  * Create a signal handler. Call signal_bind() later to bind to a signal.
 719  * @param base: communication base to use.
 720  * @param callback: called when signal is caught.
 721  * @param cb_arg: user argument to callback
 722  * @return: the signal struct or NULL on error.
 723  */
 724 struct comm_signal* comm_signal_create(struct comm_base* base,
 725         void (*callback)(int, void*), void* cb_arg);
 726
 727 /**
 728  * Bind signal struct to catch a signal. A signle comm_signal can be bound
 729  * to multiple signals, calling comm_signal_bind multiple times.
 730  * @param comsig: the communication point, with callback information.
 731  * @param sig: signal number.
 732  * @return: true on success. false on error.
 733  */
 734 int comm_signal_bind(struct comm_signal* comsig, int sig);
 735
 736 /**
 737  * Delete the signal communication point.
 738  * @param comsig: to delete.
 739  */
 740 void comm_signal_delete(struct comm_signal* comsig);
 741
 742 /**
 743  * perform accept(2) with error checking.
 744  * @param c: commpoint with accept fd.
 745  * @param addr: remote end returned here.
 746  * @param addrlen: length of remote end returned here.
 747  * @return new fd, or -1 on error.
 748  *      if -1, error message has been printed if necessary, simply drop
 749  *      out of the reading handler.
 750  */
 751 int comm_point_perform_accept(struct comm_point* c,
 752         struct sockaddr_storage* addr, socklen_t* addrlen);
 753
 754 /**** internal routines ****/
 755
 756 /**
 757  * This routine is published for checks and tests, and is only used internally.
 758  * handle libevent callback for udp comm point.
 759  * @param fd: file descriptor.
 760  * @param event: event bits from libevent:
 761  *      EV_READ, EV_WRITE, EV_SIGNAL, EV_TIMEOUT.
 762  * @param arg: the comm_point structure.
 763  */
 764 void comm_point_udp_callback(int fd, short event, void* arg);
 765
 766 /**
 767  * This routine is published for checks and tests, and is only used internally.
 768  * handle libevent callback for udp ancillary data comm point.
 769  * @param fd: file descriptor.
 770  * @param event: event bits from libevent:
 771  *      EV_READ, EV_WRITE, EV_SIGNAL, EV_TIMEOUT.
 772  * @param arg: the comm_point structure.
 773  */
 774 void comm_point_udp_ancil_callback(int fd, short event, void* arg);
 775
 776 /**
 777  * This routine is published for checks and tests, and is only used internally.
 778  * handle libevent callback for tcp accept comm point
 779  * @param fd: file descriptor.
 780  * @param event: event bits from libevent:
 781  *      EV_READ, EV_WRITE, EV_SIGNAL, EV_TIMEOUT.
 782  * @param arg: the comm_point structure.
 783  */
 784 void comm_point_tcp_accept_callback(int fd, short event, void* arg);
 785
 786 /**
 787  * This routine is published for checks and tests, and is only used internally.
 788  * handle libevent callback for tcp data comm point
 789  * @param fd: file descriptor.
 790  * @param event: event bits from libevent:
 791  *      EV_READ, EV_WRITE, EV_SIGNAL, EV_TIMEOUT.
 792  * @param arg: the comm_point structure.
 793  */
 794 void comm_point_tcp_handle_callback(int fd, short event, void* arg);
 795
 796 /**
 797  * This routine is published for checks and tests, and is only used internally.
 798  * handle libevent callback for tcp data comm point
 799  * @param fd: file descriptor.
 800  * @param event: event bits from libevent:
 801  *      EV_READ, EV_WRITE, EV_SIGNAL, EV_TIMEOUT.
 802  * @param arg: the comm_point structure.
 803  */
 804 void comm_point_http_handle_callback(int fd, short event, void* arg);
 805
 806 /**
 807  * HTTP2 session.  HTTP2 related info per comm point.
 808  */
 809 struct http2_session {
 810         /** first item in list of streams */
 811         struct http2_stream* first_stream;
 812 #ifdef HAVE_NGHTTP2
 813         /** nghttp2 session */
 814         nghttp2_session *session;
 815         /** store nghttp2 callbacks for easy reuse */
 816         nghttp2_session_callbacks* callbacks;
 817 #endif
 818         /** comm point containing buffer used to build answer in worker or
 819          * module */
 820         struct comm_point* c;
 821         /** session is instructed to get dropped (comm port will be closed) */
 822         int is_drop;
 823         /** postpone dropping the session, can be used to prevent dropping
 824          * while being in a callback */
 825         int postpone_drop;
 826 };
 827
 828 /** enum of HTTP status */
 829 enum http_status {
 830         HTTP_STATUS_OK = 200,
 831         HTTP_STATUS_BAD_REQUEST = 400,
 832         HTTP_STATUS_NOT_FOUND = 404,
 833         HTTP_STATUS_PAYLOAD_TOO_LARGE = 413,
 834         HTTP_STATUS_URI_TOO_LONG = 414,
 835         HTTP_STATUS_UNSUPPORTED_MEDIA_TYPE = 415,
 836         HTTP_STATUS_NOT_IMPLEMENTED = 501
 837 };
 838
 839 /**
 840  * HTTP stream. Part of list of HTTP2 streams per session.
 841  */
 842 struct http2_stream {
 843         /** next stream in list per session */
 844         struct http2_stream* next;
 845         /** previous stream in list per session */
 846         struct http2_stream* prev;
 847         /** HTTP2 stream ID is an unsigned 31-bit integer */
 848         int32_t stream_id;
 849         /** HTTP method used for this stream */
 850         enum {
 851                 HTTP_METHOD_POST = 1,
 852                 HTTP_METHOD_GET,
 853                 HTTP_METHOD_UNSUPPORTED
 854         } http_method;
 855         /** message contains invalid content type */
 856         int invalid_content_type;
 857         /** message body content type */
 858         size_t content_length;
 859         /** HTTP response status */
 860         enum http_status status;
 861         /** request for non existing endpoint */
 862         int invalid_endpoint;
 863         /** query in request is too large */
 864         int query_too_large;
 865         /** buffer to store query into. Can't use session shared buffer as query
 866          * can arrive in parts, intertwined with frames for other queries. */
 867         struct sldns_buffer* qbuffer;
 868         /** buffer to store response into. Can't use shared buffer as a next
 869          * query read callback can overwrite it before it is send out. */
 870         struct sldns_buffer* rbuffer;
 871         /** mesh area containing mesh state */
 872         struct mesh_area* mesh;
 873         /** mesh state for query. Used to remove mesh reply before closing
 874          * stream. */
 875         struct mesh_state* mesh_state;
 876 };
 877
 878 #ifdef HAVE_NGHTTP2
 879 /** nghttp2 receive cb. Read from SSL connection into nghttp2 buffer */
 880 ssize_t http2_recv_cb(nghttp2_session* session, uint8_t* buf,
 881         size_t len, int flags, void* cb_arg);
 882 /** nghttp2 send callback. Send from nghttp2 buffer to ssl socket */
 883 ssize_t http2_send_cb(nghttp2_session* session, const uint8_t* buf,
 884         size_t len, int flags, void* cb_arg);
 885 /** nghttp2 callback on closing stream */
 886 int http2_stream_close_cb(nghttp2_session* session, int32_t stream_id,
 887         uint32_t error_code, void* cb_arg);
 888 #endif
 889
 890 /**
 891  * Create new http2 stream
 892  * @param stream_id: ID for stream to create.
 893  * @return malloc'ed stream, NULL on error
 894  */
 895 struct http2_stream* http2_stream_create(int32_t stream_id);
 896
 897 /**
 898  * Add new stream to session linked list
 899  * @param h2_session: http2 session to add stream to
 900  * @param h2_stream: stream to add to session list
 901  */
 902 void http2_session_add_stream(struct http2_session* h2_session,
 903         struct http2_stream* h2_stream);
 904
 905 /** Add mesh state to stream. To be able to remove mesh reply on stream closure
 906  */
 907 void http2_stream_add_meshstate(struct http2_stream* h2_stream,
 908         struct mesh_area* mesh, struct mesh_state* m);
 909
 910 /**
 911  * This routine is published for checks and tests, and is only used internally.
 912  * handle libevent callback for timer comm.
 913  * @param fd: file descriptor (always -1).
 914  * @param event: event bits from libevent:
 915  *      EV_READ, EV_WRITE, EV_SIGNAL, EV_TIMEOUT.
 916  * @param arg: the comm_timer structure.
 917  */
 918 void comm_timer_callback(int fd, short event, void* arg);
 919
 920 /**
 921  * This routine is published for checks and tests, and is only used internally.
 922  * handle libevent callback for signal comm.
 923  * @param fd: file descriptor (used for the signal number).
 924  * @param event: event bits from libevent:
 925  *      EV_READ, EV_WRITE, EV_SIGNAL, EV_TIMEOUT.
 926  * @param arg: the internal commsignal structure.
 927  */
 928 void comm_signal_callback(int fd, short event, void* arg);
 929
 930 /**
 931  * This routine is published for checks and tests, and is only used internally.
 932  * libevent callback for AF_UNIX fds
 933  * @param fd: file descriptor.
 934  * @param event: event bits from libevent:
 935  *      EV_READ, EV_WRITE, EV_SIGNAL, EV_TIMEOUT.
 936  * @param arg: the comm_point structure.
 937  */
 938 void comm_point_local_handle_callback(int fd, short event, void* arg);
 939
 940 /**
 941  * This routine is published for checks and tests, and is only used internally.
 942  * libevent callback for raw fd access.
 943  * @param fd: file descriptor.
 944  * @param event: event bits from libevent:
 945  *      EV_READ, EV_WRITE, EV_SIGNAL, EV_TIMEOUT.
 946  * @param arg: the comm_point structure.
 947  */
 948 void comm_point_raw_handle_callback(int fd, short event, void* arg);
 949
 950 /**
 951  * This routine is published for checks and tests, and is only used internally.
 952  * libevent callback for timeout on slow accept.
 953  * @param fd: file descriptor.
 954  * @param event: event bits from libevent:
 955  *      EV_READ, EV_WRITE, EV_SIGNAL, EV_TIMEOUT.
 956  * @param arg: the comm_point structure.
 957  */
 958 void comm_base_handle_slow_accept(int fd, short event, void* arg);
 959
 960 #ifdef USE_WINSOCK
 961 /**
 962  * Callback for openssl BIO to on windows detect WSAEWOULDBLOCK and notify
 963  * the winsock_event of this for proper TCP nonblocking implementation.
 964  * @param c: comm_point, fd must be set its struct event is registered.
 965  * @param ssl: openssl SSL, fd must be set so it has a bio.
 966  */
 967 void comm_point_tcp_win_bio_cb(struct comm_point* c, void* ssl);
 968 #endif
 969
 970 /**
 971  * See if errno for tcp connect has to be logged or not. This uses errno
 972  * @param addr: apart from checking errno, the addr is checked for ip4mapped
 973  *      and broadcast type, hence passed.
 974  * @param addrlen: length of the addr parameter.
 975  * @return true if it needs to be logged.
 976  */
 977 int tcp_connect_errno_needs_log(struct sockaddr* addr, socklen_t addrlen);
 978
 979 #ifdef HAVE_SSL
 980 /**
 981  * True if the ssl handshake error has to be squelched from the logs
 982  * @param err: the error returned by the openssl routine, ERR_get_error.
 983  *      This is a packed structure with elements that are examined.
 984  * @return true if the error is squelched (not logged).
 985  */
 986 int squelch_err_ssl_handshake(unsigned long err);
 987 #endif
 988
 989 #endif /* NET_EVENT_H */