Networking: client-side and server-side sockets.

## How to use the "net" cluster

This page is divided into the following sections:

- vocabulary
- how to be a client
- how to be a server
- how to use the provided servers
- some technical aspects

### Vocabulary

Access | A word used by this cluster to design a server access on a host.
Address | A word used by this cluster to design a host.
Host | A machine connected to a network. Such a machine has an address and, usually, a name.
Server | A program that runs on a host. Such a programs listens on a "port number".

### Be a Client

To be client means trying to reach some server and getting some data from it.

There are two concepts to grasp before making a connection:

- Address: that's the network address of a machine (a "host"), given either by its name or its IP number. The net cluster knows of three kinds of addresses: the host name, the IP address and the local address which represents the local machine.
- Access: it allows to connect to some server that runs on a machine and listens on a port. The net cluster knows of three kinds of accesses: TCP and UDP access, and the special Local access that reaches the local machine.

To be a client, you have to do three things, in that order:

- create an address object
- create an access object, using the address object
- query a stream from the access object

In SmartEiffel, you would write it this way:

       connect_to_funet: TERMINAL_INPUT_OUTPUT_STREAM is
          local
             funet: HOST
             tcp: TCP_ACCESS
          do
             create funet.make(once "ftp.funet.fi")
             create tcp.make(funet, 21)
             Result := tcp.stream
          end

(See also the tutorial: class `SOCKETS`)

### Be a Server

To be a server, things are a bit more complex but not tremendously so.

First note that you must know something of the `lib/sequencer` cluster. You must also be familiar with agents.

To create a server, start by creating an address and an access. The address will filter which connections are allowed1, and the access port will determine which port the server will listen to.

Now you must create a `SOCKET_SERVER`, give it one or more agents using the ``when_connect'` feature. Those agents are called whenever a new client connects; each agent is given the same stream that represents the connection to the client.

Note that having multiple agents is potentially dangerous. Either all the agents cooperate, either having one registered is enough. Remember that all agents share the same stream.

At last, start the sequencer (see the `lib/sequencer` cluster and tutorial).

You also want to look at the `lib/net/servers` cluster.

(See also the tutorial: class `MULTIPLEX_SERVER`)

### Use a standard Server

SmartEiffel provides (or will provide) some standard servers, such as HTTP 1.1 or FTP. Those servers are designed to either start their own sequencer stack (stand-alone mode), or integrate in a stack you provide (e.g. when you start multiple servers or use the server concurrently with Vision).

Currently only a minimal HTTP server is provided. The tutorial gives an instance of this server in stand-alone mode. We call it Papoose :-)

### Technical aspects

The net cluster is quite simple.

- The `ADDRESS` class is an abstract class that represents an address. There are three implementations, in the `address' sub-cluster.
- The `ACCESS` class is an abstract class that represents an access. There are three implementations, in the `access' sub-cluster.
- The `SOCKET_INPUT_OUTPUT_STREAM` is a bi-directional stream. You cannot create such an object directly, it must be given to you either by `ACCESS``.stream` (client usage) or by the server (server usage: when an inbound connection occurs, agents are given a stream).
- The `SOCKET_SERVER` is the basic implementation of a server. It is a `JOB` in the `sequencer' terminology, hence it has to be used in conjunction with a `LOOP_STACK`.
- The `lib/net/low_level cluster contains really low-level classes, that should be used only by the cluster itself. Use at your own risk.
  - `SOCKET` is the basic implementation of a socket.
  - `SOCKET_HANDLER` allows low-level access to a `SOCKET`. Usual code doesn't need that, only the cluster itself should use this class.
  - `SOCKET_PLUG_IN` is the Eiffel side of the net plugin.
  `

Note that the address is not currently used to allow only some connections. It will be used in a future release.