X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=src%2Fcadet%2Fgnunet-service-cadet_connection.h;h=fdb1843661e6ddd2861bcf7f3dff1d2e0dc104b9;hb=503717fce30f57907482678fb1abfe468309d7b1;hp=6a2eff7de5e5ddbc74ac3e81f1b82b26e13566d6;hpb=5886b0a23ebbcac2e8ed1edfcef63ea2188c68c5;p=oweals%2Fgnunet.git diff --git a/src/cadet/gnunet-service-cadet_connection.h b/src/cadet/gnunet-service-cadet_connection.h index 6a2eff7de..fdb184366 100644 --- a/src/cadet/gnunet-service-cadet_connection.h +++ b/src/cadet/gnunet-service-cadet_connection.h @@ -1,6 +1,7 @@ + /* This file is part of GNUnet. - (C) 2013 Christian Grothoff (and other contributing authors) + Copyright (C) 2001-2017 GNUnet e.V. GNUnet is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published @@ -14,567 +15,325 @@ You should have received a copy of the GNU General Public License along with GNUnet; see the file COPYING. If not, write to the - Free Software Foundation, Inc., 59 Temple Place - Suite 330, - Boston, MA 02111-1307, USA. + Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, + Boston, MA 02110-1301, USA. */ /** * @file cadet/gnunet-service-cadet_connection.h - * @brief cadet service; dealing with connections + * @brief A connection is a live end-to-end messaging mechanism + * where the peers are identified by a path and know how + * to forward along the route using a connection identifier + * for routing the data. * @author Bartlomiej Polot - * - * All functions in this file should use the prefix GMC (Gnunet Cadet Connection) + * @author Christian Grothoff */ - #ifndef GNUNET_SERVICE_CADET_CONNECTION_H #define GNUNET_SERVICE_CADET_CONNECTION_H -#ifdef __cplusplus -extern "C" -{ -#if 0 /* keep Emacsens' auto-indent happy */ -} -#endif -#endif - #include "gnunet_util_lib.h" - - -/** - * All the states a connection can be in. - */ -enum CadetConnectionState -{ - /** - * Uninitialized status, should never appear in operation. - */ - CADET_CONNECTION_NEW, - - /** - * Connection create message sent, waiting for ACK. - */ - CADET_CONNECTION_SENT, - - /** - * Connection ACK sent, waiting for ACK. - */ - CADET_CONNECTION_ACK, - - /** - * Connection confirmed, ready to carry traffic. - */ - CADET_CONNECTION_READY, - - /** - * Connection to be destroyed, just waiting to empty queues. - */ - CADET_CONNECTION_DESTROYED, - - /** - * Connection to be destroyed because of a distant peer, same as DESTROYED. - */ - CADET_CONNECTION_BROKEN, -}; - - -/** - * Struct containing all information regarding a connection to a peer. - */ -struct CadetConnection; - -/** - * Handle for messages queued but not yet sent. - */ -struct CadetConnectionQueue; - -#include "cadet_path.h" -#include "gnunet-service-cadet_channel.h" +#include "gnunet-service-cadet.h" #include "gnunet-service-cadet_peer.h" - +#include "cadet_protocol.h" /** - * Callback called when a queued message is sent. + * Function called to notify tunnel about change in our readyness. * - * @param cls Closure. - * @param c Connection this message was on. - * @param type Type of message sent. - * @param fwd Was this a FWD going message? - * @param size Size of the message. + * @param cls closure + * @param is_ready #GNUNET_YES if the connection is now ready for transmission, + * #GNUNET_NO if the connection is no longer ready for transmission */ -typedef void (*GCC_sent) (void *cls, - struct CadetConnection *c, - struct CadetConnectionQueue *q, - uint16_t type, int fwd, size_t size); +typedef void +(*GCC_ReadyCallback)(void *cls, + int is_ready); -/** - * Core handler for connection creation. - * - * @param cls Closure (unused). - * @param peer Sender (neighbor). - * @param message Message. - * - * @return GNUNET_OK to keep the connection open, - * GNUNET_SYSERR to close it (signal serious error) - */ -int -GCC_handle_create (void *cls, const struct GNUNET_PeerIdentity *peer, - const struct GNUNET_MessageHeader *message); /** - * Core handler for path confirmations. - * - * @param cls closure - * @param message message - * @param peer peer identity this notification is about + * Destroy a connection, called when the CORE layer is already done + * (i.e. has received a BROKEN message), but if we still have to + * communicate the destruction of the connection to the tunnel (if one + * exists). * - * @return GNUNET_OK to keep the connection open, - * GNUNET_SYSERR to close it (signal serious error) + * @param cc connection to destroy */ -int -GCC_handle_confirm (void *cls, const struct GNUNET_PeerIdentity *peer, - const struct GNUNET_MessageHeader *message); +void +GCC_destroy_without_core (struct CadetConnection *cc); -/** - * Core handler for notifications of broken paths - * - * @param cls Closure (unused). - * @param id Peer identity of sending neighbor. - * @param message Message. - * - * @return GNUNET_OK to keep the connection open, - * GNUNET_SYSERR to close it (signal serious error) - */ -int -GCC_handle_broken (void* cls, - const struct GNUNET_PeerIdentity* id, - const struct GNUNET_MessageHeader* message); /** - * Core handler for tunnel destruction + * Destroy a connection, called if the tunnel association with the + * connection was already broken, but we still need to notify the CORE + * layer about the breakage. * - * @param cls Closure (unused). - * @param peer Peer identity of sending neighbor. - * @param message Message. - * - * @return GNUNET_OK to keep the connection open, - * GNUNET_SYSERR to close it (signal serious error) + * @param cc connection to destroy */ -int -GCC_handle_destroy (void *cls, const struct GNUNET_PeerIdentity *peer, - const struct GNUNET_MessageHeader *message); +void +GCC_destroy_without_tunnel (struct CadetConnection *cc); -/** - * Core handler for encrypted cadet network traffic (channel mgmt, data). - * - * @param cls Closure (unused). - * @param message Message received. - * @param peer Peer who sent the message. - * - * @return GNUNET_OK to keep the connection open, - * GNUNET_SYSERR to close it (signal serious error) - */ -int -GCC_handle_encrypted (void *cls, const struct GNUNET_PeerIdentity *peer, - const struct GNUNET_MessageHeader *message); /** - * Core handler for key exchange traffic (ephemeral key, ping, pong). - * - * @param cls Closure (unused). - * @param message Message received. - * @param peer Peer who sent the message. + * Lookup a connection by its identifier. * - * @return GNUNET_OK to keep the connection open, - * GNUNET_SYSERR to close it (signal serious error) + * @param cid identifier to resolve + * @return NULL if connection was not found */ -int -GCC_handle_kx (void *cls, const struct GNUNET_PeerIdentity *peer, - const struct GNUNET_MessageHeader *message); +struct CadetConnection * +GCC_lookup (const struct GNUNET_CADET_ConnectionTunnelIdentifier *cid); -/** - * Core handler for cadet network traffic point-to-point acks. - * - * @param cls closure - * @param message message - * @param peer peer identity this notification is about - * - * @return GNUNET_OK to keep the connection open, - * GNUNET_SYSERR to close it (signal serious error) - */ -int -GCC_handle_ack (void *cls, const struct GNUNET_PeerIdentity *peer, - const struct GNUNET_MessageHeader *message); /** - * Core handler for cadet network traffic point-to-point ack polls. - * - * @param cls closure - * @param message message - * @param peer peer identity this notification is about + * Create a connection to @a destination via @a path and + * notify @a cb whenever we are ready for more data. * - * @return GNUNET_OK to keep the connection open, - * GNUNET_SYSERR to close it (signal serious error) + * @param destination where to go + * @param path which path to take (may not be the full path) + * @param off offset of @a destination on @a path + * @param options options for the connection + * @param ct which tunnel uses this connection + * @param ready_cb function to call when ready to transmit + * @param ready_cb_cls closure for @a cb + * @return handle to the connection */ -int -GCC_handle_poll (void *cls, const struct GNUNET_PeerIdentity *peer, - const struct GNUNET_MessageHeader *message); +struct CadetConnection * +GCC_create (struct CadetPeer *destination, + struct CadetPeerPath *path, + unsigned int off, + enum GNUNET_CADET_ChannelOption options, + struct CadetTConnection *ct, + GCC_ReadyCallback ready_cb, + void *ready_cb_cls); -/** - * Core handler for cadet keepalives. - * - * @param cls closure - * @param message message - * @param peer peer identity this notification is about - * @return GNUNET_OK to keep the connection open, - * GNUNET_SYSERR to close it (signal serious error) - * - * TODO: Check who we got this from, to validate route. - */ -int -GCC_handle_keepalive (void *cls, const struct GNUNET_PeerIdentity *peer, - const struct GNUNET_MessageHeader *message); /** - * Send an ACK on the appropriate connection/channel, depending on - * the direction and the position of the peer. + * Create a connection to @a destination via @a path and + * notify @a cb whenever we are ready for more data. This + * is an inbound tunnel, so we must use the existing @a cid * - * @param c Which connection to send the hop-by-hop ACK. - * @param fwd Is this a fwd ACK? (will go dest->root). - * @param force Send the ACK even if suboptimal (e.g. requested by POLL). + * @param destination where to go + * @param path which path to take (may not be the full path) + * @param options options for the connection + * @param ct which tunnel uses this connection + * @param ready_cb function to call when ready to transmit + * @param ready_cb_cls closure for @a cb + * @return handle to the connection, NULL if we already have + * a connection that takes precedence on @a path */ -void -GCC_send_ack (struct CadetConnection *c, int fwd, int force); +struct CadetConnection * +GCC_create_inbound (struct CadetPeer *destination, + struct CadetPeerPath *path, + enum GNUNET_CADET_ChannelOption options, + struct CadetTConnection *ct, + const struct GNUNET_CADET_ConnectionTunnelIdentifier *cid, + GCC_ReadyCallback ready_cb, + void *ready_cb_cls); + /** - * Initialize the connections subsystem + * Transmit message @a msg via connection @a cc. Must only be called + * (once) after the connection has signalled that it is ready via the + * `ready_cb`. Clients can also use #GCC_is_ready() to check if the + * connection is right now ready for transmission. * - * @param c Configuration handle. + * @param cc connection identification + * @param env envelope with message to transmit; + * the #GNUNET_MQ_notify_send() must not have yet been used + * for the envelope. Also, the message better match the + * connection identifier of this connection... */ void -GCC_init (const struct GNUNET_CONFIGURATION_Handle *c); +GCC_transmit (struct CadetConnection *cc, + struct GNUNET_MQ_Envelope *env); -/** - * Shut down the connections subsystem. - */ -void -GCC_shutdown (void); /** - * Create a connection. - * - * @param cid Connection ID (either created locally or imposed remotely). - * @param t Tunnel this connection belongs to (or NULL); - * @param p Path this connection has to use. - * @param own_pos Own position in the @c p path. + * A CREATE_ACK was received for this connection, process it. * - * @return Newly created connection, NULL in case of error (own id not in path). + * @param cc the connection that got the ACK. */ -struct CadetConnection * -GCC_new (const struct GNUNET_CADET_Hash *cid, - struct CadetTunnel *t, - struct CadetPeerPath *p, - unsigned int own_pos); +void +GCC_handle_connection_create_ack (struct CadetConnection *cc); + /** - * Connection is no longer needed: destroy it. + * We got a #GNUNET_MESSAGE_TYPE_CADET_CONNECTION_CREATE for a + * connection that we already have. Either our ACK got lost + * or something is fishy. Consider retransmitting the ACK. * - * Cancels all pending traffic (including possible DESTROY messages), all - * maintenance tasks and removes the connection from neighbor peers and tunnel. - * - * @param c Connection to destroy. + * @param cc connection that got the duplicate CREATE */ void -GCC_destroy (struct CadetConnection *c); +GCC_handle_duplicate_create (struct CadetConnection *cc); + /** - * Get the connection ID. + * Handle KX message. * - * @param c Connection to get the ID from. - * - * @return ID of the connection. + * @param cc connection that received encrypted message + * @param msg the key exchange message */ -const struct GNUNET_CADET_Hash * -GCC_get_id (const struct CadetConnection *c); +void +GCC_handle_kx (struct CadetConnection *cc, + const struct GNUNET_CADET_TunnelKeyExchangeMessage *msg); /** - * Get a hash for the connection ID. - * - * @param c Connection to get the hash. + * Handle KX_AUTH message. * - * @return Hash expanded from the ID of the connection. + * @param cc connection that received encrypted message + * @param msg the key exchange message */ -const struct GNUNET_HashCode * -GCC_get_h (const struct CadetConnection *c); +void +GCC_handle_kx_auth (struct CadetConnection *cc, + const struct GNUNET_CADET_TunnelKeyExchangeAuthMessage *msg); /** - * Get the connection path. - * - * @param c Connection to get the path from. - * - * @return path used by the connection. + * Performance metrics for a connection. */ -const struct CadetPeerPath * -GCC_get_path (const struct CadetConnection *c); +struct CadetConnectionMetrics +{ -/** - * Get the connection state. - * - * @param c Connection to get the state from. - * - * @return state of the connection. - */ -enum CadetConnectionState -GCC_get_state (const struct CadetConnection *c); + /** + * Our current best estimate of the latency, based on a weighted + * average of at least @a latency_datapoints values. + */ + struct GNUNET_TIME_Relative aged_latency; -/** - * Get the connection tunnel. - * - * @param c Connection to get the tunnel from. - * - * @return tunnel of the connection. - */ -struct CadetTunnel * -GCC_get_tunnel (const struct CadetConnection *c); + /** + * When was this connection first established? (by us sending or + * receiving the CREATE_ACK for the first time) + */ + struct GNUNET_TIME_Absolute age; -/** - * Get free buffer space in a connection. - * - * @param c Connection. - * @param fwd Is query about FWD traffic? - * - * @return Free buffer space [0 - max_msgs_queue/max_connections] - */ -unsigned int -GCC_get_buffer (struct CadetConnection *c, int fwd); + /** + * When was this connection last used? (by us sending or + * receiving a PAYLOAD message on it) + */ + struct GNUNET_TIME_Absolute last_use; -/** - * Get how many messages have we allowed to send to us from a direction. - * - * @param c Connection. - * @param fwd Are we asking about traffic from FWD (BCK messages)? - * - * @return last_ack_sent - last_pid_recv - */ -unsigned int -GCC_get_allowed (struct CadetConnection *c, int fwd); + /** + * How many packets that ought to generate an ACK did we send via + * this connection? + */ + unsigned long long num_acked_transmissions; -/** - * Get messages queued in a connection. - * - * @param c Connection. - * @param fwd Is query about FWD traffic? - * - * @return Number of messages queued. - */ -unsigned int -GCC_get_qn (struct CadetConnection *c, int fwd); + /** + * Number of packets that were sent via this connection did actually + * receive an ACK? (Note: ACKs may be transmitted and lost via + * other connections, so this value should only be interpreted + * relative to @e num_acked_transmissions and in relation to other + * connections.) + */ + unsigned long long num_successes; -/** - * Get next PID to use. - * - * @param c Connection. - * @param fwd Is query about FWD traffic? - * - * @return Last PID used + 1. - */ -unsigned int -GCC_get_pid (struct CadetConnection *c, int fwd); +}; -/** - * Allow the connection to advertise a buffer of the given size. - * - * The connection will send an @c fwd ACK message (so: in direction !fwd) - * allowing up to last_pid_recv + buffer. - * - * @param c Connection. - * @param buffer How many more messages the connection can accept. - * @param fwd Is this about FWD traffic? (The ack will go dest->root). - */ -void -GCC_allow (struct CadetConnection *c, unsigned int buffer, int fwd); /** - * Send FWD keepalive packets for a connection. + * Obtain performance @a metrics from @a cc. * - * @param cls Closure (connection for which to send the keepalive). - * @param tc Notification context. + * @param cc connection to query + * @return the metrics */ -void -GCC_fwd_keepalive (void *cls, const struct GNUNET_SCHEDULER_TaskContext *tc); +const struct CadetConnectionMetrics * +GCC_get_metrics (struct CadetConnection *cc); + /** - * Send BCK keepalive packets for a connection. + * Handle encrypted message. * - * @param cls Closure (connection for which to send the keepalive). - * @param tc Notification context. + * @param cc connection that received encrypted message + * @param msg the encrypted message to decrypt */ void -GCC_bck_keepalive (void *cls, const struct GNUNET_SCHEDULER_TaskContext *tc); +GCC_handle_encrypted (struct CadetConnection *cc, + const struct GNUNET_CADET_TunnelEncryptedMessage *msg); /** - * Notify other peers on a connection of a broken link. Mark connections - * to destroy after all traffic has been sent. + * We sent a message for which we expect to receive an ACK via + * the connection identified by @a cti. * - * @param c Connection on which there has been a disconnection. - * @param peer Peer that disconnected. + * @param cid connection identifier where we expect an ACK */ void -GCC_notify_broken (struct CadetConnection *c, - struct CadetPeer *peer); +GCC_ack_expected (const struct GNUNET_CADET_ConnectionTunnelIdentifier *cid); -/** - * Is this peer the first one on the connection? - * - * @param c Connection. - * @param fwd Is this about fwd traffic? - * - * @return #GNUNET_YES if origin, #GNUNET_NO if relay/terminal. - */ -int -GCC_is_origin (struct CadetConnection *c, int fwd); /** - * Is this peer the last one on the connection? + * We observed an ACK for a message that was originally sent via + * the connection identified by @a cti. * - * @param c Connection. - * @param fwd Is this about fwd traffic? - * Note that the ROOT is the terminal for BCK traffic! - * - * @return #GNUNET_YES if terminal, #GNUNET_NO if relay/origin. - */ -int -GCC_is_terminal (struct CadetConnection *c, int fwd); - -/** - * See if we are allowed to send by the next hop in the given direction. - * - * @param c Connection. - * @param fwd Is this about fwd traffic? - * - * @return #GNUNET_YES in case it's OK to send. + * @param cid connection identifier where we got an ACK for a message + * that was originally sent via this connection (the ACK + * may have gotten back to us via a different connection). */ -int -GCC_is_sendable (struct CadetConnection *c, int fwd); +void +GCC_ack_observed (const struct GNUNET_CADET_ConnectionTunnelIdentifier *cid); -/** - * Check if this connection is a direct one (never trim a direct connection). - * - * @param c Connection. - * - * @return #GNUNET_YES in case it's a direct connection, #GNUNET_NO otherwise. - */ -int -GCC_is_direct (struct CadetConnection *c); /** - * Cancel a previously sent message while it's in the queue. - * - * ONLY can be called before the continuation given to the send function - * is called. Once the continuation is called, the message is no longer in the - * queue. + * We observed some the given @a latency on the connection + * identified by @a cti. (The same connection was taken + * in both directions.) * - * @param q Handle to the queue. + * @param cti connection identifier where we measured latency + * @param latency the observed latency */ void -GCC_cancel (struct CadetConnectionQueue *q); +GCC_latency_observed (const struct GNUNET_CADET_ConnectionTunnelIdentifier *cti, + struct GNUNET_TIME_Relative latency); -/** - * Sends an already built message on a connection, properly registering - * all used resources. - * - * @param message Message to send. Function makes a copy of it. - * If message is not hop-by-hop, decrements TTL of copy. - * @param payload_type Type of payload, in case the message is encrypted. - * @param c Connection on which this message is transmitted. - * @param fwd Is this a fwd message? - * @param force Force the connection to accept the message (buffer overfill). - * @param cont Continuation called once message is sent. Can be NULL. - * @param cont_cls Closure for @c cont. - * - * @return Handle to cancel the message before it's sent. - * NULL on error or if @c cont is NULL. - * Invalid on @c cont call. - */ -struct CadetConnectionQueue * -GCC_send_prebuilt_message (const struct GNUNET_MessageHeader *message, - uint16_t payload_type, uint32_t payload_id, - struct CadetConnection *c, int fwd, int force, - GCC_sent cont, void *cont_cls); /** - * Sends a CREATE CONNECTION message for a path to a peer. - * Changes the connection and tunnel states if necessary. + * Return the tunnel associated with this connection. * - * @param connection Connection to create. + * @param cc connection to query + * @return corresponding entry in the tunnel's connection list */ -void -GCC_send_create (struct CadetConnection *connection); +struct CadetTConnection * +GCC_get_ct (struct CadetConnection *cc); -/** - * Send a message to all peers in this connection that the connection - * is no longer valid. - * - * If some peer should not receive the message, it should be zero'ed out - * before calling this function. - * - * @param c The connection whose peers to notify. - */ -void -GCC_send_destroy (struct CadetConnection *c); /** - * @brief Start a polling timer for the connection. - * - * When a neighbor does not accept more traffic on the connection it could be - * caused by a simple congestion or by a lost ACK. Polling enables to check - * for the lastest ACK status for a connection. + * Obtain the path used by this connection. * - * @param c Connection. - * @param fwd Should we poll in the FWD direction? + * @param cc connection + * @return path to @a cc */ -void -GCC_start_poll (struct CadetConnection *c, int fwd); +struct CadetPeerPath * +GCC_get_path (struct CadetConnection *cc); /** - * @brief Stop polling a connection for ACKs. + * Obtain unique ID for the connection. * - * Once we have enough ACKs for future traffic, polls are no longer necessary. - * - * @param c Connection. - * @param fwd Should we stop the poll in the FWD direction? + * @param cc connection. + * @return unique number of the connection */ -void -GCC_stop_poll (struct CadetConnection *c, int fwd); +const struct GNUNET_CADET_ConnectionTunnelIdentifier * +GCC_get_id (struct CadetConnection *cc); + /** * Get a (static) string for a connection. * - * @param c Connection. + * @param cc Connection. */ const char * -GCC_2s (const struct CadetConnection *c); +GCC_2s (const struct CadetConnection *cc); + /** - * Log all possible info about the connection state. + * Log connection info. * - * @param c Connection to debug. + * @param cc connection * @param level Debug level to use. */ void -GCC_debug (const struct CadetConnection *c, enum GNUNET_ErrorType level); +GCC_debug (struct CadetConnection *cc, + enum GNUNET_ErrorType level); -#if 0 /* keep Emacsens' auto-indent happy */ -{ -#endif -#ifdef __cplusplus -} -#endif -/* ifndef GNUNET_SERVICE_CADET_CONNECTION_H */ #endif -/* end of gnunet-service-cadet_connection.h */