#include <connection_st.h>

Data Fields
uint32_t	magic

uint8_t	state

unsigned int	type:5

unsigned int	purpose:5

unsigned int	read_blocked_on_bw:1

unsigned int	write_blocked_on_bw:1

unsigned int	hold_open_until_flushed:1

unsigned int	inbuf_reached_eof:1

unsigned int	in_flushed_some:1

unsigned int	in_connection_handle_write:1

unsigned int	always_rate_limit_as_remote:1

unsigned int	linked:1

unsigned int	reading_from_linked_conn:1

unsigned int	writing_to_linked_conn:1

unsigned int	active_on_link:1

unsigned int	linked_conn_is_closed:1

unsigned int	proxy_state:4

tor_socket_t	s

int	conn_array_index

struct event *	read_event

struct event *	write_event

struct buf_t *	inbuf

struct buf_t *	outbuf

time_t	timestamp_last_read_allowed

time_t	timestamp_last_write_allowed

time_t	timestamp_created

int	socket_family

tor_addr_t	addr

uint16_t	port

uint16_t	marked_for_close

const char *	marked_for_close_file

char *	address

struct connection_t *	linked_conn

uint64_t	global_identifier

uint32_t	n_read_conn_bw

uint32_t	n_written_conn_bw

Detailed Description

Description of a connection to another host or process, and associated data.

A connection is named based on what it's connected to – an "OR connection" has a Tor node on the other end, an "exit connection" has a website or other server on the other end, and an "AP connection" has an application proxy (and thus a user) on the other end.

Every connection has a type and a state. Connections never change their type, but can go through many state changes in their lifetime.

Every connection has two associated input and output buffers. Listeners don't use them. For non-listener connections, incoming data is appended to conn->inbuf, and outgoing data is taken from conn->outbuf. Connections differ primarily in the functions called to fill and drain these buffers.

Definition at line 45 of file connection_st.h.

Field Documentation

◆ active_on_link

unsigned int active_on_link

True iff we're currently able to read on the linked conn, and our read_event should be made active with libevent.

Definition at line 86 of file connection_st.h.

Referenced by connection_start_reading_from_linked_conn(), and connection_stop_reading_from_linked_conn().

◆ addr

tor_addr_t addr

IP address on the internet of this connection's peer, usually.

This address may come from several sources. If this is an outbound connection, it is the address we are trying to connect to–either directly through s, or via a proxy. (If we used a proxy, then getpeername(s) will not give this address.)

For incoming connections, this field is the address we got from getpeername() or accept(), as updated by any proxy that we are using (for example, an ExtORPort proxy).

For listeners, this is the address we are trying to bind to.

If this connection is using a unix socket, then this address is a null address, and the real address is in the address field.

If this connection represents a request made somewhere other than via TCP (for example, a UDP dns request, or a controller resolve request), then this address is the address that originated the request.

TECHNICAL DEBT:

There are a few places in the code that modify this address, or use it in other ways that we don't currently like. Please don't add any more!

The misuses of this field include:

Setting it on linked connections, possibly.
Updating it based on the Forwarded-For header– Forwarded-For is set by a proxy, but not a local trusted proxy.

Definition at line 145 of file connection_st.h.

Referenced by clock_skew_warning(), conn_get_proxy_type(), connection_ap_handshake_attach_circuit(), connection_describe_peer_internal(), connection_exit_connect(), connection_haproxy_proxy_connect(), connection_is_rate_limited(), connection_send_socks5_connect(), connection_socks4_proxy_connect(), get_proxy_addrport(), metrics_connection_process_inbuf(), and retry_listener_ports().

◆ address

char* address

String address of the peer of this connection.

TECHNICAL DEBT:

This field serves many purposes, and they're not all pretty. In addition to describing the peer we're connected to, it can also hold:

An address we're trying to resolve (as an exit).
A unix address we're trying to bind to (as a listener).

Definition at line 166 of file connection_st.h.

Referenced by connection_exit_begin_resolve(), orconn_target_get_name(), and retry_listener_ports().

◆ always_rate_limit_as_remote

unsigned int always_rate_limit_as_remote

If true, then we treat this connection as remote for the purpose of rate-limiting, no matter what its address is.

Definition at line 74 of file connection_st.h.

Referenced by connection_is_rate_limited().

◆ conn_array_index

int conn_array_index

Index into the global connection array.

Definition at line 97 of file connection_st.h.

Referenced by circuit_dump_by_conn(), connection_add_impl(), connection_is_moribund(), and connection_unlink().

◆ global_identifier

uint64_t global_identifier

Unique identifier for this connection on this Tor instance.

Definition at line 171 of file connection_st.h.

Referenced by control_event_conn_bandwidth(), and record_num_bytes_transferred_impl().

◆ hold_open_until_flushed

unsigned int hold_open_until_flushed

Despite this connection's being marked for close, do we flush it before closing it?

Definition at line 61 of file connection_st.h.

Referenced by connection_expire_held_open(), and connection_may_write_to_buf().

◆ in_connection_handle_write

unsigned int in_connection_handle_write

True if connection_handle_write is currently running on this connection.

Definition at line 71 of file connection_st.h.

◆ in_flushed_some

unsigned int in_flushed_some

Set to 1 when we're inside connection_flushed_some to keep us from calling connection_handle_write() recursively.

Definition at line 68 of file connection_st.h.

Referenced by connection_flushed_some().

◆ inbuf

struct buf_t* inbuf

Buffer holding data read over this connection.

Definition at line 101 of file connection_st.h.

Referenced by conn_get_buffer_age(), connection_buf_get_bytes(), connection_buf_get_line(), connection_buf_read_from_socket(), connection_fetch_ext_or_cmd_from_buf(), connection_fetch_from_buf_http(), connection_fetch_from_buf_socks_client(), connection_fetch_var_cell_from_buf(), connection_handle_read_impl(), connection_read_https_proxy_response(), and peek_connection_has_control0_command().

◆ inbuf_reached_eof

unsigned int inbuf_reached_eof

Boolean: did read() return 0 on this conn?

Definition at line 64 of file connection_st.h.

◆ linked

unsigned int linked

True if there is, or has been, a linked_conn.

Definition at line 78 of file connection_st.h.

Referenced by connection_add_impl(), connection_edge_flushed_some(), connection_edge_process_inbuf(), connection_is_rate_limited(), connection_link_connections(), connection_should_read_from_linked_conn(), connection_start_reading(), connection_start_reading_from_linked_conn(), connection_start_writing(), connection_stop_reading(), connection_stop_reading_from_linked_conn(), and connection_stop_writing().

◆ linked_conn

struct connection_t* linked_conn

Another connection that's connected to this one in lieu of a socket.

Definition at line 168 of file connection_st.h.

Referenced by circuit_get_streams_max_data_age(), connection_dir_is_anonymous(), connection_link_connections(), connection_should_read_from_linked_conn(), connection_start_writing(), connection_stop_writing(), and connection_unlink().

◆ linked_conn_is_closed

unsigned int linked_conn_is_closed

True iff we've called connection_close_immediate() on this linked connection.

Definition at line 89 of file connection_st.h.

◆ magic

uint32_t magic

For memory debugging: must equal one of *_CONNECTION_MAGIC.

Definition at line 46 of file connection_st.h.

Referenced by connection_ap_mark_as_pending_circuit_(), connection_dir_is_anonymous(), connection_free_minimal(), EDGE_TO_ENTRY_CONN(), TO_CONTROL_CONN(), TO_DIR_CONN(), TO_EDGE_CONN(), TO_ENTRY_CONN(), TO_LISTENER_CONN(), and TO_OR_CONN().

◆ marked_for_close

uint16_t marked_for_close

Should we close this conn on the next iteration of the main loop? (If true, holds the line number where this connection was marked.)

Definition at line 149 of file connection_st.h.

Referenced by add_connection_to_closeable_list(), ap_stream_wants_exit_attention(), circuit_resume_edge_reading_helper(), connection_about_to_close_connection(), connection_dir_finished_flushing(), connection_edge_destroy(), connection_edge_send_command(), connection_expire_held_open(), connection_handle_read_impl(), connection_is_moribund(), connection_mark_all_noncontrol_connections(), connection_mark_all_noncontrol_listeners(), connection_mark_for_close_internal_(), connection_mark_unattached_ap_(), connection_may_write_to_buf(), connection_or_single_set_badness_(), connection_state_is_connecting(), connection_state_is_open(), connection_unlink(), get_stream(), inform_pending_connections(), relay_lookup_conn(), and retry_all_listeners().

◆ marked_for_close_file

const char* marked_for_close_file

For debugging: in which file were we marked for close?

Definition at line 153 of file connection_st.h.

◆ n_read_conn_bw

uint32_t n_read_conn_bw

Bytes read since last call to control_event_conn_bandwidth_used(). Only used if we're configured to emit CONN_BW events.

Definition at line 175 of file connection_st.h.

Referenced by control_event_conn_bandwidth().

◆ n_written_conn_bw

uint32_t n_written_conn_bw

Bytes written since last call to control_event_conn_bandwidth_used(). Only used if we're configured to emit CONN_BW events.

Definition at line 179 of file connection_st.h.

Referenced by control_event_conn_bandwidth().

◆ outbuf

struct buf_t* outbuf

Buffer holding data to write over this connection.

Definition at line 102 of file connection_st.h.

Referenced by conn_get_buffer_age(), connection_bucket_write_limit(), connection_buf_add_buf(), connection_should_read_from_linked_conn(), and connection_write_to_buf_impl_().

◆ port

uint16_t port

If non-zero, port that socket "s" is directly connected to; may be the port for a proxy or pluggable transport, see "address" for the port at the final destination.

Definition at line 146 of file connection_st.h.

Referenced by clock_skew_warning(), conn_get_proxy_type(), connection_ap_handshake_attach_circuit(), connection_exit_connect(), connection_haproxy_proxy_connect(), connection_send_socks5_connect(), get_proxy_addrport(), orconn_target_get_name(), record_num_bytes_transferred_impl(), and retry_listener_ports().

◆ proxy_state

unsigned int proxy_state

CONNECT/SOCKS proxy client handshake state (for outgoing connections).

Definition at line 92 of file connection_st.h.

◆ purpose

unsigned int purpose

◆ read_blocked_on_bw

unsigned int read_blocked_on_bw

Boolean: should we start reading again once the bandwidth throttler allows it?

Definition at line 56 of file connection_st.h.

Referenced by connection_read_bw_exhausted(), and reenable_blocked_connections_cb().

◆ read_event

struct event* read_event

Libevent event structure.

Definition at line 99 of file connection_st.h.

Referenced by connection_is_reading(), connection_start_reading(), connection_stop_reading(), connection_unregister_events(), and set_streams_blocked_on_circ().

◆ reading_from_linked_conn

unsigned int reading_from_linked_conn

True iff we'd like to be notified about read events from the linked conn.

Definition at line 81 of file connection_st.h.

Referenced by connection_is_reading(), connection_should_read_from_linked_conn(), connection_start_reading(), connection_stop_reading(), and connection_unlink().

◆ s

tor_socket_t s

Our socket; set to TOR_INVALID_SOCKET if this connection is closed, or has no socket.

Definition at line 96 of file connection_st.h.

Referenced by conn_write_callback(), connection_add_impl(), connection_expire_held_open(), connection_finished_connecting(), connection_link_connections(), connection_tls_start_handshake(), dns_resolve_impl(), and dnsserv_configure_listener().

◆ socket_family

int socket_family

Address family of this connection's socket. Usually AF_INET, but it can also be AF_UNIX, or AF_INET6

Definition at line 111 of file connection_st.h.

Referenced by check_sockaddr_family_match(), record_num_bytes_transferred_impl(), and retry_listener_ports().

◆ state

uint8_t state

Current state of this connection.

Definition at line 49 of file connection_st.h.

Referenced by ap_stream_wants_exit_attention(), connection_ap_handshake_attach_chosen_circuit(), connection_ap_handshake_attach_circuit(), connection_ap_handshake_process_socks(), connection_ap_handshake_send_begin(), connection_ap_handshake_send_resolve(), connection_ap_mark_as_pending_circuit_(), connection_control_process_inbuf(), connection_describe(), connection_dir_about_to_close(), connection_dir_finished_connecting(), connection_dir_process_inbuf(), connection_dir_reached_eof(), connection_dirserv_flushed_some(), connection_dns_remove(), connection_edge_finished_connecting(), connection_edge_finished_flushing(), connection_edge_flushed_some(), connection_edge_process_inbuf(), connection_edge_process_resolved_cell(), connection_exit_about_to_close(), connection_expire_held_open(), connection_ext_or_auth_process_inbuf(), connection_ext_or_finished_flushing(), connection_flushed_some(), connection_or_change_state(), connection_or_finished_connecting(), connection_or_finished_flushing(), connection_or_get_state_description(), connection_or_group_set_badness_(), connection_or_process_inbuf(), connection_or_send_auth_challenge_cell(), connection_or_send_certs_cell(), connection_state_is_connecting(), connection_state_is_open(), control_protocol_is_valid(), inform_pending_connections(), is_valid_initial_command(), and mark_conn_as_waiting_for_circuit().

◆ timestamp_created

time_t timestamp_created

When was this connection_t created?

Definition at line 109 of file connection_st.h.

Referenced by connection_ap_handshake_attach_circuit(), connection_or_single_set_badness_(), and mark_conn_as_waiting_for_circuit().

◆ timestamp_last_read_allowed

time_t timestamp_last_read_allowed

When was the last time libevent said we could read?

Definition at line 104 of file connection_st.h.

Referenced by connection_handle_read_impl(), and mark_conn_as_waiting_for_circuit().

◆ timestamp_last_write_allowed

time_t timestamp_last_write_allowed

When was the last time libevent said we could write?

Definition at line 106 of file connection_st.h.

Referenced by connection_expire_held_open(), and mark_conn_as_waiting_for_circuit().

◆ type

unsigned int type

What kind of connection is this?

Definition at line 50 of file connection_st.h.

Referenced by ap_stream_wants_exit_attention(), assert_connection_ok(), circuit_detach_stream(), connection_about_to_close_connection(), connection_add_impl(), connection_ap_handshake_process_socks(), connection_ap_handshake_send_begin(), connection_ap_handshake_send_resolve(), connection_bucket_read_limit(), connection_bucket_write_limit(), connection_check_event(), connection_counts_as_relayed_traffic(), connection_describe(), connection_describe_peer_internal(), connection_dir_finished_connecting(), connection_dir_finished_flushing(), connection_dir_process_inbuf(), connection_dns_remove(), connection_edge_finished_connecting(), connection_edge_package_raw_inbuf(), connection_expire_held_open(), connection_ext_or_transition(), connection_finished_connecting(), connection_finished_flushing(), connection_flushed_some(), connection_free_minimal(), connection_handle_read_impl(), connection_init_accepted_conn(), connection_is_listener(), connection_mark_all_noncontrol_connections(), connection_mark_all_noncontrol_listeners(), connection_mark_for_close_(), connection_mark_unattached_ap_(), connection_or_get_state_description(), connection_or_nonopen_was_started_here(), connection_process_inbuf(), connection_reached_eof(), connection_state_is_connecting(), connection_state_is_open(), connection_unlink(), control_event_conn_bandwidth(), directory_handle_command(), directory_send_command(), dnsserv_close_listener(), dnsserv_configure_listener(), get_stream(), metrics_connection_process_inbuf(), oos_victim_comparator(), record_num_bytes_transferred_impl(), and retry_listener_ports().

◆ write_blocked_on_bw

unsigned int write_blocked_on_bw

Boolean: should we start writing again once the bandwidth throttler allows writes?

Definition at line 58 of file connection_st.h.

Referenced by connection_write_bw_exhausted(), and reenable_blocked_connections_cb().

◆ write_event

struct event* write_event