== Writing TCP servers and clients

Vert.x allows you to easily write non blocking TCP clients and servers.

=== Creating a TCP server

The simplest way to create a TCP server, using all default options is as follows:

[source,ruby]
----

server = vertx.create_net_server()

----

=== Configuring a TCP server

If you don't want the default, a server can be configured by passing in a `link:../cheatsheet/NetServerOptions.html[NetServerOptions]`
instance when creating it:

[source,ruby]
----

options = {
  'port' => 4321
}
server = vertx.create_net_server(options)

----

=== Start the Server Listening

To tell the server to listen for incoming requests you use one of the `link:yardoc/Vertx/NetServer.html#listen-instance_method[listen]`
alternatives.

To tell the server to listen at the host and port as specified in the options:

[source,ruby]
----

server = vertx.create_net_server()
server.listen()

----

Or to specify the host and port in the call to listen, ignoring what is configured in the options:

[source,ruby]
----

server = vertx.create_net_server()
server.listen(1234, "localhost")

----

The default host is `0.0.0.0` which means 'listen on all available addresses' and the default port is `0`, which is a
special value that instructs the server to find a random unused local port and use that.

The actual bind is asynchronous so the server might not actually be listening until some time *after* the call to
listen has returned.

If you want to be notified when the server is actually listening you can provide a handler to the `listen` call.
For example:

[source,ruby]
----

server = vertx.create_net_server()
server.listen(1234, "localhost") { |res_err,res|
  if (res_err == nil)
    puts "Server is now listening!"
  else
    puts "Failed to bind!"
  end
}

----

=== Listening on a random port

If `0` is used as the listening port, the server will find an unused random port to listen on.

To find out the real port the server is listening on you can call `link:yardoc/Vertx/NetServer.html#actual_port-instance_method[actualPort]`.

[source,ruby]
----

server = vertx.create_net_server()
server.listen(0, "localhost") { |res_err,res|
  if (res_err == nil)
    puts "Server is now listening on actual port: #{server.actual_port()}"
  else
    puts "Failed to bind!"
  end
}

----

=== Getting notified of incoming connections

To be notified when a connection is made you need to set a `link:yardoc/Vertx/NetServer.html#connect_handler-instance_method[connectHandler]`:

[source,ruby]
----

server = vertx.create_net_server()
server.connect_handler() { |socket|
  # Handle the connection in here
}

----

When a connection is made the handler will be called with an instance of `link:yardoc/Vertx/NetSocket.html[NetSocket]`.

This is a socket-like interface to the actual connection, and allows you to read and write data as well as do various
other things like close the socket.

=== Reading data from the socket

To read data from the socket you set the `link:yardoc/Vertx/NetSocket.html#handler-instance_method[handler]` on the
socket.

This handler will be called with an instance of `link:yardoc/Vertx/Buffer.html[Buffer]` every time data is received on
the socket.

[source,ruby]
----

server = vertx.create_net_server()
server.connect_handler() { |socket|
  socket.handler() { |buffer|
    puts "I received some bytes: #{buffer.length()}"
  }
}

----

=== Writing data to a socket

You write to a socket using one of `link:yardoc/Vertx/NetSocket.html#write-instance_method[write]`.

[source,ruby]
----
require 'vertx/buffer'

# Write a buffer
buffer = Vertx::Buffer.buffer().append_float(12.34).append_int(123)
socket.write(buffer)

# Write a string in UTF-8 encoding
socket.write("some data")

# Write a string using the specified encoding
socket.write("some data", "UTF-16")



----

Write operations are asynchronous and may not occur until some time after the call to write has returned.

=== Closed handler

If you want to be notified when a socket is closed, you can set a `link:yardoc/Vertx/NetSocket.html#close_handler-instance_method[closeHandler]`
on it:

[source,ruby]
----

socket.close_handler() { |v|
  puts "The socket has been closed"
}

----

=== Handling exceptions

You can set an `link:yardoc/Vertx/NetSocket.html#exception_handler-instance_method[exceptionHandler]` to receive any
exceptions that happen on the socket.

=== Event bus write handler

Every socket automatically registers a handler on the event bus, and when any buffers are received in this handler,
it writes them to itself.

This enables you to write data to a socket which is potentially in a completely different verticle or even in a
different Vert.x instance by sending the buffer to the address of that handler.

The address of the handler is given by `link:yardoc/Vertx/NetSocket.html#write_handler_id-instance_method[writeHandlerID]`

=== Local and remote addresses

The local address of a `link:yardoc/Vertx/NetSocket.html[NetSocket]` can be retrieved using `link:yardoc/Vertx/NetSocket.html#local_address-instance_method[localAddress]`.

The remote address, (i.e. the address of the other end of the connection) of a `link:yardoc/Vertx/NetSocket.html[NetSocket]`
can be retrieved using `link:yardoc/Vertx/NetSocket.html#remote_address-instance_method[remoteAddress]`.

=== Sending files

Files can be written to the socket directly using `link:yardoc/Vertx/NetSocket.html#send_file-instance_method[sendFile]`. This can be a very
efficient way to send files, as it can be handled by the OS kernel directly where supported by the operating system.

[source,ruby]
----

socket.send_file("myfile.dat")

----

=== Streaming sockets

Instances of `link:yardoc/Vertx/NetSocket.html[NetSocket]` are also `link:yardoc/Vertx/ReadStream.html[ReadStream]` and
`link:yardoc/Vertx/WriteStream.html[WriteStream]` instances so they can be used to pump data to or from other
read and write streams.

See the chapter on <<streams, streams and pumps>> for more information.

=== Upgrading connections to SSL/TLS

A non SSL/TLS connection can be upgraded to SSL/TLS using `link:yardoc/Vertx/NetSocket.html#upgrade_to_ssl-instance_method[upgradeToSsl]`.

The server or client must be configured for SSL/TLS for this to work correctly. Please see the <<ssl, chapter on SSL/TLS>>
for more information.

=== Closing a TCP Server

Call `link:yardoc/Vertx/NetServer.html#close-instance_method[close]` to close the server. Closing the server closes any open connections
and releases all server resources.

The close is actually asynchronous and might not complete until some time after the call has returned.
If you want to be notified when the actual close has completed then you can pass in a handler.

This handler will then be called when the close has fully completed.

[source,ruby]
----

server.close() { |res_err,res|
  if (res_err == nil)
    puts "Server is now closed"
  else
    puts "close failed"
  end
}

----

=== Automatic clean-up in verticles

If you're creating TCP servers and clients from inside verticles, those servers and clients will be automatically closed
when the verticle is undeployed.

=== Scaling - sharing TCP servers

The handlers of any TCP server are always executed on the same event loop thread.

This means that if you are running on a server with a lot of cores, and you only have this one instance
deployed then you will have at most one core utilised on your server.

In order to utilise more cores of your server you will need to deploy more instances of the server.

You can instantiate more instances programmatically in your code:

[source,ruby]
----

# Create a few instances so we can utilise cores

i = 0
while (i < 10)
  server = vertx.create_net_server()
  server.connect_handler() { |socket|
    socket.handler() { |buffer|
      # Just echo back the data
      socket.write(buffer)
    }
  }
  server.listen(1234, "localhost")
  i+=1
end

----

or, if you are using verticles you can simply deploy more instances of your server verticle by using the `-instances` option
on the command line:

 vertx run com.mycompany.MyVerticle -instances 10

or when programmatically deploying your verticle

[source,ruby]
----

options = {
  'instances' => 10
}
vertx.deploy_verticle("com.mycompany.MyVerticle", options)

----

Once you do this you will find the echo server works functionally identically to before, but all your cores on your
server can be utilised and more work can be handled.

At this point you might be asking yourself *'How can you have more than one server listening on the
same host and port? Surely you will get port conflicts as soon as you try and deploy more than one instance?'*

_Vert.x does a little magic here.*_

When you deploy another server on the same host and port as an existing server it doesn't actually try and create a
new server listening on the same host/port.

Instead it internally maintains just a single server, and, as incoming connections arrive it distributes
them in a round-robin fashion to any of the connect handlers.

Consequently Vert.x TCP servers can scale over available cores while each instance remains single threaded.

=== Creating a TCP client

The simplest way to create a TCP client, using all default options is as follows:

[source,ruby]
----

client = vertx.create_net_client()

----

=== Configuring a TCP client

If you don't want the default, a client can be configured by passing in a `link:../cheatsheet/NetClientOptions.html[NetClientOptions]`
instance when creating it:

[source,ruby]
----

options = {
  'connectTimeout' => 10000
}
client = vertx.create_net_client(options)

----

=== Making connections

To make a connection to a server you use `link:yardoc/Vertx/NetClient.html#connect-instance_method[connect]`,
specifying the port and host of the server and a handler that will be called with a result containing the
`link:yardoc/Vertx/NetSocket.html[NetSocket]` when connection is successful or with a failure if connection failed.

[source,ruby]
----

options = {
  'connectTimeout' => 10000
}
client = vertx.create_net_client(options)
client.connect(4321, "localhost") { |res_err,res|
  if (res_err == nil)
    puts "Connected!"
    socket = res
  else
    puts "Failed to connect: #{res_err.get_message()}"
  end
}

----

=== Configuring connection attempts

A client can be configured to automatically retry connecting to the server in the event that it cannot connect.
This is configured with `link:../cheatsheet/NetClientOptions.html#reconnectInterval[reconnectInterval]` and
`link:../cheatsheet/NetClientOptions.html#reconnectAttempts[reconnectAttempts]`.

NOTE: Currently Vert.x will not attempt to reconnect if a connection fails, reconnect attempts and interval
only apply to creating initial connections.

[source,ruby]
----

options = {
}
options['reconnectAttempts'] = 10['reconnectInterval'] = 500

client = vertx.create_net_client(options)

----

By default, multiple connection attempts are disabled.

[[ssl]]
=== Configuring servers and clients to work with SSL/TLS

TCP clients and servers can be configured to use http://en.wikipedia.org/wiki/Transport_Layer_Security[Transport Layer Security]
- earlier versions of TLS were known as SSL.

The APIs of the servers and clients are identical whether or not SSL/TLS is used, and it's enabled by configuring
the `link:../cheatsheet/NetClientOptions.html[NetClientOptions]` or `link:../cheatsheet/NetServerOptions.html[NetServerOptions]` instances used
to create the servers or clients.

==== Enabling SSL/TLS on the server

SSL/TLS is enabled with  `link:../cheatsheet/NetServerOptions.html#ssl[ssl]`.

By default it is disabled.

==== Specifying key/certificate for the server

SSL/TLS servers usually provide certificates to clients in order verify their identity to clients.

Certificates/keys can be configured for servers in several ways:

The first method is by specifying the location of a Java key-store which contains the certificate and private key.

Java key stores can be managed with the http://docs.oracle.com/javase/6/docs/technotes/tools/solaris/keytool.html[keytool]
utility which ships with the JDK.

The password for the key store should also be provided:

[source,ruby]
----
options = {
  'ssl' => true,
  'keyStoreOptions' => {
    'path' => "/path/to/your/server-keystore.jks",
    'password' => "password-of-your-keystore"
  }
}
server = vertx.create_net_server(options)

----

Alternatively you can read the key store yourself as a buffer and provide that directly:

[source,ruby]
----
myKeyStoreAsABuffer = vertx.file_system().read_file_blocking("/path/to/your/server-keystore.jks")
jksOptions = {
  'value' => myKeyStoreAsABuffer,
  'password' => "password-of-your-keystore"
}
options = {
  'ssl' => true,
  'keyStoreOptions' => jksOptions
}
server = vertx.create_net_server(options)

----

Key/certificate in PKCS#12 format (http://en.wikipedia.org/wiki/PKCS_12), usually with the `.pfx`  or the `.p12`
extension can also be loaded in a similar fashion than JKS key stores:

[source,ruby]
----
options = {
  'ssl' => true,
  'pfxKeyCertOptions' => {
    'path' => "/path/to/your/server-keystore.pfx",
    'password' => "password-of-your-keystore"
  }
}
server = vertx.create_net_server(options)

----

Buffer configuration is also supported:

[source,ruby]
----
myKeyStoreAsABuffer = vertx.file_system().read_file_blocking("/path/to/your/server-keystore.pfx")
pfxOptions = {
  'value' => myKeyStoreAsABuffer,
  'password' => "password-of-your-keystore"
}
options = {
  'ssl' => true,
  'pfxKeyCertOptions' => pfxOptions
}
server = vertx.create_net_server(options)

----

Another way of providing server private key and certificate separately using `.pem` files.

[source,ruby]
----
options = {
  'ssl' => true,
  'pemKeyCertOptions' => {
    'keyPath' => "/path/to/your/server-key.pem",
    'certPath' => "/path/to/your/server-cert.pem"
  }
}
server = vertx.create_net_server(options)

----

Buffer configuration is also supported:

[source,ruby]
----
myKeyAsABuffer = vertx.file_system().read_file_blocking("/path/to/your/server-key.pem")
myCertAsABuffer = vertx.file_system().read_file_blocking("/path/to/your/server-cert.pem")
pemOptions = {
  'keyValue' => myKeyAsABuffer,
  'certValue' => myCertAsABuffer
}
options = {
  'ssl' => true,
  'pemKeyCertOptions' => pemOptions
}
server = vertx.create_net_server(options)

----

Keep in mind that pem configuration, the private key is not crypted.

==== Specifying trust for the server

SSL/TLS servers can use a certificate authority in order to verify the identity of the clients.

Certificate authorities can be configured for servers in several ways:

Java trust stores can be managed with the http://docs.oracle.com/javase/6/docs/technotes/tools/solaris/keytool.html[keytool]
utility which ships with the JDK.

The password for the trust store should also be provided:

[source,ruby]
----
options = {
  'ssl' => true,
  'clientAuthRequired' => true,
  'trustStoreOptions' => {
    'path' => "/path/to/your/truststore.jks",
    'password' => "password-of-your-truststore"
  }
}
server = vertx.create_net_server(options)

----

Alternatively you can read the trust store yourself as a buffer and provide that directly:

[source,ruby]
----
myTrustStoreAsABuffer = vertx.file_system().read_file_blocking("/path/to/your/truststore.jks")
options = {
  'ssl' => true,
  'clientAuthRequired' => true,
  'trustStoreOptions' => {
    'value' => myTrustStoreAsABuffer,
    'password' => "password-of-your-truststore"
  }
}
server = vertx.create_net_server(options)

----

Certificate authority in PKCS#12 format (http://en.wikipedia.org/wiki/PKCS_12), usually with the `.pfx`  or the `.p12`
extension can also be loaded in a similar fashion than JKS trust stores:

[source,ruby]
----
options = {
  'ssl' => true,
  'clientAuthRequired' => true,
  'pfxTrustOptions' => {
    'path' => "/path/to/your/truststore.pfx",
    'password' => "password-of-your-truststore"
  }
}
server = vertx.create_net_server(options)

----

Buffer configuration is also supported:

[source,ruby]
----
myTrustStoreAsABuffer = vertx.file_system().read_file_blocking("/path/to/your/truststore.pfx")
options = {
  'ssl' => true,
  'clientAuthRequired' => true,
  'pfxTrustOptions' => {
    'value' => myTrustStoreAsABuffer,
    'password' => "password-of-your-truststore"
  }
}
server = vertx.create_net_server(options)

----

Another way of providing server certificate authority using a list `.pem` files.

[source,ruby]
----
options = {
  'ssl' => true,
  'clientAuthRequired' => true,
  'pemTrustOptions' => {
    'certPaths' => [
      "/path/to/your/server-ca.pem"
    ]
  }
}
server = vertx.create_net_server(options)

----

Buffer configuration is also supported:

[source,ruby]
----
myCaAsABuffer = vertx.file_system().read_file_blocking("/path/to/your/server-ca.pfx")
options = {
  'ssl' => true,
  'clientAuthRequired' => true,
  'pemTrustOptions' => {
    'certValues' => [
      myCaAsABuffer
    ]
  }
}
server = vertx.create_net_server(options)

----

==== Enabling SSL/TLS on the client

Net Clients can also be easily configured to use SSL. They have the exact same API when using SSL as when using standard sockets.

To enable SSL on a NetClient the function setSSL(true) is called.

==== Client trust configuration

If the `link:unavailable#set_trust_all-instance_method[trustALl]` is set to true on the client, then the client will
trust all server certificates. The connection will still be encrypted but this mode is vulnerable to 'man in the middle' attacks. I.e. you can't
be sure who you are connecting to. Use this with caution. Default value is false.

[source,ruby]
----
options = {
  'ssl' => true,
  'trustAll' => true
}
client = vertx.create_net_client(options)

----

If `link:unavailable#set_trust_all-instance_method[trustAll]` is not set then a client trust store must be
configured and should contain the certificates of the servers that the client trusts.

Likewise server configuration, the client trust can be configured in several ways:

The first method is by specifying the location of a Java trust-store which contains the certificate authority.

It is just a standard Java key store, the same as the key stores on the server side. The client
trust store location is set by using the function `link:../cheatsheet/JksOptions.html#path[path]` on the
`link:../cheatsheet/JksOptions.html[jks options]`. If a server presents a certificate during connection which is not
in the client trust store, the connection attempt will not succeed.

[source,ruby]
----
options = {
  'ssl' => true,
  'trustStoreOptions' => {
    'path' => "/path/to/your/truststore.jks",
    'password' => "password-of-your-truststore"
  }
}
client = vertx.create_net_client(options)

----

Buffer configuration is also supported:

[source,ruby]
----
myTrustStoreAsABuffer = vertx.file_system().read_file_blocking("/path/to/your/truststore.jks")
options = {
  'ssl' => true,
  'trustStoreOptions' => {
    'value' => myTrustStoreAsABuffer,
    'password' => "password-of-your-truststore"
  }
}
client = vertx.create_net_client(options)

----

Certificate authority in PKCS#12 format (http://en.wikipedia.org/wiki/PKCS_12), usually with the `.pfx`  or the `.p12`
extension can also be loaded in a similar fashion than JKS trust stores:

[source,ruby]
----
options = {
  'ssl' => true,
  'pfxTrustOptions' => {
    'path' => "/path/to/your/truststore.pfx",
    'password' => "password-of-your-truststore"
  }
}
client = vertx.create_net_client(options)

----

Buffer configuration is also supported:

[source,ruby]
----
myTrustStoreAsABuffer = vertx.file_system().read_file_blocking("/path/to/your/truststore.pfx")
options = {
  'ssl' => true,
  'pfxTrustOptions' => {
    'value' => myTrustStoreAsABuffer,
    'password' => "password-of-your-truststore"
  }
}
client = vertx.create_net_client(options)

----

Another way of providing server certificate authority using a list `.pem` files.

[source,ruby]
----
options = {
  'ssl' => true,
  'pemTrustOptions' => {
    'certPaths' => [
      "/path/to/your/ca-cert.pem"
    ]
  }
}
client = vertx.create_net_client(options)

----

Buffer configuration is also supported:

[source,ruby]
----
myTrustStoreAsABuffer = vertx.file_system().read_file_blocking("/path/to/your/ca-cert.pem")
options = {
  'ssl' => true,
  'pemTrustOptions' => {
    'certValues' => [
      myTrustStoreAsABuffer
    ]
  }
}
client = vertx.create_net_client(options)

----

==== Specifying key/certificate for the client

If the server requires client authentication then the client must present its own certificate to the server when
connecting. The client can be configured in several ways:

The first method is by specifying the location of a Java key-store which contains the key and certificate.
Again it's just a regular Java key store. The client keystore location is set by using the function
`link:../cheatsheet/JksOptions.html#path[path]` on the
`link:../cheatsheet/JksOptions.html[jks options]`.

[source,ruby]
----
options = {
  'ssl' => true,
  'keyStoreOptions' => {
    'path' => "/path/to/your/client-keystore.jks",
    'password' => "password-of-your-keystore"
  }
}
client = vertx.create_net_client(options)

----

Buffer configuration is also supported:

[source,ruby]
----
myKeyStoreAsABuffer = vertx.file_system().read_file_blocking("/path/to/your/client-keystore.jks")
jksOptions = {
  'value' => myKeyStoreAsABuffer,
  'password' => "password-of-your-keystore"
}
options = {
  'ssl' => true,
  'keyStoreOptions' => jksOptions
}
client = vertx.create_net_client(options)

----

Key/certificate in PKCS#12 format (http://en.wikipedia.org/wiki/PKCS_12), usually with the `.pfx`  or the `.p12`
extension can also be loaded in a similar fashion than JKS key stores:

[source,ruby]
----
options = {
  'ssl' => true,
  'pfxKeyCertOptions' => {
    'path' => "/path/to/your/client-keystore.pfx",
    'password' => "password-of-your-keystore"
  }
}
client = vertx.create_net_client(options)

----

Buffer configuration is also supported:

[source,ruby]
----
myKeyStoreAsABuffer = vertx.file_system().read_file_blocking("/path/to/your/client-keystore.pfx")
pfxOptions = {
  'value' => myKeyStoreAsABuffer,
  'password' => "password-of-your-keystore"
}
options = {
  'ssl' => true,
  'pfxKeyCertOptions' => pfxOptions
}
client = vertx.create_net_client(options)

----

Another way of providing server private key and certificate separately using `.pem` files.

[source,ruby]
----
options = {
  'ssl' => true,
  'pemKeyCertOptions' => {
    'keyPath' => "/path/to/your/client-key.pem",
    'certPath' => "/path/to/your/client-cert.pem"
  }
}
client = vertx.create_net_client(options)

----

Buffer configuration is also supported:

[source,ruby]
----
myKeyAsABuffer = vertx.file_system().read_file_blocking("/path/to/your/client-key.pem")
myCertAsABuffer = vertx.file_system().read_file_blocking("/path/to/your/client-cert.pem")
pemOptions = {
  'keyValue' => myKeyAsABuffer,
  'certValue' => myCertAsABuffer
}
options = {
  'ssl' => true,
  'pemKeyCertOptions' => pemOptions
}
client = vertx.create_net_client(options)

----

Keep in mind that pem configuration, the private key is not crypted.

==== Revoking certificate authorities

Trust can be configured to use a certificate revocation list (CRL) for revoked certificates that should no
longer be trusted. The `link:../cheatsheet/NetClientOptions.html#crlPath[crlPath]` configures
the crl list to use:

[source,ruby]
----
options = {
  'ssl' => true,
  'trustStoreOptions' => trustOptions,
  'crlPaths' => [
    "/path/to/your/crl.pem"
  ]
}
client = vertx.create_net_client(options)

----

Buffer configuration is also supported:

[source,ruby]
----
myCrlAsABuffer = vertx.file_system().read_file_blocking("/path/to/your/crl.pem")
options = {
  'ssl' => true,
  'trustStoreOptions' => trustOptions,
  'crlValues' => [
    myCrlAsABuffer
  ]
}
client = vertx.create_net_client(options)

----

==== Configuring the Cipher suite

By default, the TLS configuration will uses the Cipher suite of the JVM running Vert.x. This Cipher suite can be
configured with a suite of enabled ciphers:

[source,ruby]
----
options = {
  'ssl' => true,
  'keyStoreOptions' => keyStoreOptions,
  'enabledCipherSuites' => [
    "ECDHE-RSA-AES128-GCM-SHA256",
    "ECDHE-ECDSA-AES128-GCM-SHA256",
    "ECDHE-RSA-AES256-GCM-SHA384",
    "CDHE-ECDSA-AES256-GCM-SHA384"
  ]
}
server = vertx.create_net_server(options)

----

Cipher suite can be specified on the `link:../cheatsheet/NetServerOptions.html[NetServerOptions]` or `link:../cheatsheet/NetClientOptions.html[NetClientOptions]` configuration.