class EventMachine::Connection
@see file:docs/GettingStarted.md EventMachine tutorial
All of the other instance methods defined here are called only by user code.
* {#ssl_handshake_completed}
* {#ssl_verify_peer} (if TLS is used)
* {#unbind}
* {#receive_data}
* {#connection_completed}
* {#post_init}
which may be called by the event loop are:
initialize method. The instance methods of EventMachine::Connection
This class is never instantiated by user code, and does not publish an
as described below.
objects whenever specific events occur on the corresponding connections,
The event loop will automatically call methods on EventMachine::Connection
that is active at any given time.
(and containing the mixed-in user code) for every network connection
EventMachine manages one object inherited from EventMachine::Connection
that will also be mixed in.
methods defined here, as well as add arbitrary additional code
User-defined handler modules may redefine any or all of the standard
specified in calls to {EventMachine.connect} or {EventMachine.start_server}.
the functionality contained in the user-defined module
When a Connection object is instantiated, it mixes in
to a remote server or accepted locally from a remote client.)
is created. (New connections can be either initiated locally
by EventMachine’s processing loop whenever a new connection
EventMachine::Connection is a class that is instantiated
def self.new(sig, *args)
- Private: -
def self.new(sig, *args) allocate.instance_eval do # Store signature @signature = sig # associate_callback_target sig # Call a superclass's #initialize if it has one initialize(*args) # post initialize callback post_init self end end
def associate_callback_target sig
def associate_callback_target sig # No-op for the time being end
def close_connection after_writing = false
{EventMachine::Connection#close_connection_after_writing}.
yet been sent across the network. If you want to avoid this behavior, use
sent to the connection using {EventMachine::Connection#send_data} but which has not
{#close_connection} will *silently discard* any outbound data which you have
this behavior.
However, it's not guaranteed that a future version of EventMachine will not change
the unbind callback will not re-enter your code "inside" of your call to close_connection.
take place sometime after your call to close_connection completes. In other words,
after you call close_connection. You may assume that the unbind callback will
will callback the unbind method for the particular connection at a point shortly
the connection is closed when close_connection returns. In particular, the framework
at the next available opportunity within the event loop. You may not assume that
you want to close. close_connection schedules the connection to be closed
callback handler, whether or not the callback was made against the connection
by the event loop. You may call this method against a connection object in any
EventMachine::Connection#close_connection is called only by user code, and never
def close_connection after_writing = false EventMachine::close_connection @signature, after_writing end
def close_connection_after_writing
- See: #send_data -
See: #close_connection -
def close_connection_after_writing close_connection true end
def comm_inactivity_timeout
activity takes place for at least that number of seconds.
indicates that the connection or socket will automatically be closed if no read or write
property of network-connection and datagram-socket objects. A nonzero value
comm_inactivity_timeout returns the current value (float in seconds) of the inactivity-timeout
def comm_inactivity_timeout EventMachine::get_comm_inactivity_timeout @signature end
def comm_inactivity_timeout= value
Specify a value of zero to indicate that no automatic timeout should take place.
if no read or write activity takes place for at least that number of seconds.
If the value is greater than zero, the connection or socket will automatically be closed
a network connection or datagram socket. Specify a non-negative float value in seconds.
Allows you to set the inactivity-timeout property for
def comm_inactivity_timeout= value EventMachine::set_comm_inactivity_timeout @signature, value.to_f end
def connection_completed
- See: file:docs/GettingStarted.md - EventMachine tutorial
See: Connection#unbind -
See: Connection#post_init -
def connection_completed end
def detach
Removes given connection from the event loop.
def detach EventMachine::detach_fd @signature end
def error?
-
(Boolean)- true if the connection is in an error state, false otherwise
def error? errno = EventMachine::report_connection_error_status(@signature) case errno when 0 false when -1 true else EventMachine::ERRNOS[errno] end end
def get_cipher_bits
def get_cipher_bits EventMachine::get_cipher_bits @signature end
def get_cipher_name
def get_cipher_name EventMachine::get_cipher_name @signature end
def get_cipher_protocol
def get_cipher_protocol EventMachine::get_cipher_protocol @signature end
def get_idle_time
def get_idle_time EventMachine::get_idle_time @signature end
def get_outbound_data_size
- Private: -
def get_outbound_data_size EventMachine::get_outbound_data_size @signature end
def get_outbound_data_size
def get_outbound_data_size EM._get_outbound_data_size @signature end
def get_peer_cert
- See: Connection#ssl_handshake_completed -
See: Connection#start_tls -
Returns:
-
(String)- the remote [X509 certificate](http://en.wikipedia.org/wiki/X.509), in the popular [PEM format](http://en.wikipedia.org/wiki/Privacy_Enhanced_Mail),
Other tags:
- Example: Getting peer TLS certificate information in EventMachine -
def get_peer_cert EventMachine::get_peer_cert @signature end
def get_peername
- Example: How to get peer IP address and port with EventMachine -
def get_peername EventMachine::get_peername @signature end
def get_pid
-
(Integer)-
def get_pid EventMachine::get_subprocess_pid @signature end
def get_proxied_bytes
The number of bytes proxied to another connection. Reset to zero when
def get_proxied_bytes EventMachine::get_proxied_bytes(@signature) end
def get_sni_hostname
def get_sni_hostname EventMachine::get_sni_hostname @signature end
def get_sock_opt level, option
def get_sock_opt level, option EventMachine::get_sock_opt @signature, level, option end
def get_sockname
end
puts "got #{data.inspect}"
port, ip = Socket.unpack_sockaddr_in(get_sockname)
def receive_data data
module Handler
require 'socket'
@example
values contained in the local-name structure returned from this method.
You can use {Socket.unpack_sockaddr_in} and its variants to obtain the
returns a sockaddr structure. The method returns nil if no local name is available.
of the local side of the connection. If a local name is available, this method
Used with stream-connections to obtain the identity
def get_sockname EventMachine::get_sockname @signature end
def get_status
-
(Integer)-
def get_status EventMachine::get_subprocess_status @signature end
def initialize(*args)
- Private: -
def initialize(*args) end
def notify_readable= mode
- See: #notify_readable? -
def notify_readable= mode EventMachine::set_notify_readable @signature, mode end
def notify_readable?
-
(Boolean)- true if the connection is being watched for readability.
def notify_readable? EventMachine::is_notify_readable @signature end
def notify_writable= mode
- See: #notify_writable? -
def notify_writable= mode EventMachine::set_notify_writable @signature, mode end
def notify_writable?
def notify_writable? EventMachine::is_notify_writable @signature end
def pause
- See: #resume -
def pause EventMachine::pause_connection @signature end
def paused?
- See: #resume -
See: #pause -
Returns:
-
(Boolean)- true if the connect was paused using {EventMachine::Connection#pause}.
def paused? EventMachine::connection_paused? @signature end
def pending_connect_timeout
-
(Float)- The duration after which a TCP connection in the connecting state will fail, in seconds.
def pending_connect_timeout EventMachine::get_pending_connect_timeout @signature end
def pending_connect_timeout= value
-
value(Float, #to_f) -- Connection timeout in seconds
def pending_connect_timeout= value EventMachine::set_pending_connect_timeout @signature, value.to_f end
def post_init
- See: #receive_data -
See: #send_data -
See: #unbind -
See: #connection_completed -
def post_init end
def proxy_completed
called when the reactor finished proxying all
def proxy_completed end
def proxy_incoming_to(conn,bufsize=0)
- See: EventMachine.enable_proxy -
def proxy_incoming_to(conn,bufsize=0) EventMachine::enable_proxy(self, conn, bufsize) end
def proxy_target_unbound
- See: EventMachine.enable_proxy -
def proxy_target_unbound end
def receive_data data
- See: file:docs/GettingStarted.md - EventMachine tutorial
See: #send_data -
See: #unbind -
See: #connection_completed -
See: #post_init -
Other tags:
- Note: - Depending on the protocol, buffer sizes and OS networking stack configuration, incoming data may or may not be "a complete message".
Parameters:
-
data(String) -- Opaque incoming data.
def receive_data data puts "............>>>#{data.length}" end
def reconnect server, port
-
port(Integer) -- Port to reconnect to -
server(String) -- Hostname or IP address
def reconnect server, port EventMachine::reconnect server, port, self end
def resume
- See: #pause -
def resume EventMachine::resume_connection @signature end
def send_data data
- See: Connection#unbind -
See: Connection#post_init -
See: Connection#receive_data -
See: file:docs/GettingStarted.md - EventMachine tutorial
Parameters:
-
data(String) -- Data to send asynchronously
def send_data data data = data.to_s size = data.bytesize if data.respond_to?(:bytesize) size ||= data.size EventMachine::send_data @signature, data, size end
def send_datagram data, recipient_address, recipient_port
-
recipient_port(String) -- Port of the recipient -
recipient_address(String) -- IP address of the recipient -
data(String) -- Data to send asynchronously
def send_datagram data, recipient_address, recipient_port data = data.to_s size = data.bytesize if data.respond_to?(:bytesize) size ||= data.size EventMachine::send_datagram @signature, data, size, recipient_address, Integer(recipient_port) end
def send_file_data filename
- Author: - Kirk Haines
Other tags:
- See: #send_data -
Parameters:
-
filename(String) -- Local path of the file to send
def send_file_data filename EventMachine::send_file_data @signature, filename end
def set_sock_opt level, optname, optval
def set_sock_opt level, optname, optval EventMachine::set_sock_opt @signature, level, optname, optval end
def ssl_handshake_completed
- See: #get_peer_cert -
def ssl_handshake_completed end
def ssl_verify_peer(cert)
- See: #start_tls -
Other tags:
- Example: This server never accepts any peers -
Example: This server always accepts all peers -
def ssl_verify_peer(cert) end
def start_tls args={}
- See: #ssl_verify_peer -
Other tags:
- Todo: - support passing key material via raw strings or Procs that return strings instead of
Todo: - support passing an encryption parameter, which can be string or Proc, to get a passphrase
Parameters:
-
args(Hash) --
Other tags:
- Example: Using TLS with EventMachine -
Options Hash:
(**args)-
:ssl_version(Array) -- indicates the allowed SSL/TLS versions. Possible values are: {SSLv2}, {SSLv3}, {TLSv1}, {TLSv1_1}, {TLSv1_2}. -
:dhparam(String) -- The local path of a file containing DH parameters for EDH ciphers in [PEM format](http://en.wikipedia.org/wiki/Privacy_Enhanced_Mail) See: 'openssl dhparam' -
:ecdh_curve(String) -- The curve for ECDHE ciphers. See available ciphers with 'openssl ecparam -list_curves' -
:cipher_list(String) -- indicates the available SSL cipher values. Default value is "ALL:!ADH:!LOW:!EXP:!DES-CBC3-SHA:@STRENGTH". Check the format of the OpenSSL cipher string at http://www.openssl.org/docs/apps/ciphers.html#CIPHER_LIST_FORMAT. -
:fail_if_no_peer_cert(Boolean) -- Used in conjunction with verify_peer. If set the SSL handshake will be terminated if the peer does not provide a certificate. -
:verify_peer(Boolean) -- indicates whether a server should request a certificate from a peer, to be verified by user code. -
:private_key_file(String) -- local path of a readable file that must contain a private key in the [PEM format](http://en.wikipedia.org/wiki/Privacy_Enhanced_Mail). -
:cert_chain_file(String) -- local path of a readable file that contants a chain of X509 certificates in
def start_tls args={} priv_key = args[:private_key_file] cert_chain = args[:cert_chain_file] verify_peer = args[:verify_peer] sni_hostname = args[:sni_hostname] cipher_list = args[:cipher_list] ssl_version = args[:ssl_version] ecdh_curve = args[:ecdh_curve] dhparam = args[:dhparam] fail_if_no_peer_cert = args[:fail_if_no_peer_cert] [priv_key, cert_chain].each do |file| next if file.nil? or file.empty? raise FileNotFoundException, "Could not find #{file} for start_tls" unless File.exist? file end protocols_bitmask = 0 if ssl_version.nil? protocols_bitmask |= EventMachine::EM_PROTO_TLSv1 protocols_bitmask |= EventMachine::EM_PROTO_TLSv1_1 protocols_bitmask |= EventMachine::EM_PROTO_TLSv1_2 else [ssl_version].flatten.each do |p| case p.to_s.downcase when 'sslv2' protocols_bitmask |= EventMachine::EM_PROTO_SSLv2 when 'sslv3' protocols_bitmask |= EventMachine::EM_PROTO_SSLv3 when 'tlsv1' protocols_bitmask |= EventMachine::EM_PROTO_TLSv1 when 'tlsv1_1' protocols_bitmask |= EventMachine::EM_PROTO_TLSv1_1 when 'tlsv1_2' protocols_bitmask |= EventMachine::EM_PROTO_TLSv1_2 else raise("Unrecognized SSL/TLS Protocol: #{p}") end end end EventMachine::set_tls_parms(@signature, priv_key || '', cert_chain || '', verify_peer, fail_if_no_peer_cert, sni_hostname || '', cipher_list || '', ecdh_curve || '', dhparam || '', protocols_bitmask) EventMachine::start_tls @signature end
def stop_proxying
def stop_proxying EventMachine::disable_proxy(self) end
def stream_file_data filename, args={}
-
(EventMachine::Deferrable)-
Parameters:
-
args(Hash) -- Options -
filename(String) -- Local path of the file to stream
Options Hash:
(**args)-
:http_chunks(Boolean) -- If true, this method will stream the file data in a format
def stream_file_data filename, args={} EventMachine::FileStreamer.new( self, filename, args ) end
def unbind
- See: file:docs/GettingStarted.md - EventMachine tutorial
See: #connection_completed -
See: #post_init -
Other tags:
- Example: Overriding Connection#close_connection to distinguish connections closed on our side -
def unbind end