Maiden-Networking

About Maiden-Networking

This module adds support for common networking problems to make implementing a client that has to rely on a remote connection easier.

Classes

We start with remote-client, which adds initiate-connection, close-connection, and client-connected-p that should be implemented to perform the obvious corresponding actions on the client.

Moving on to ip-client, which adds a host and port slot.

Next up there is socket-client, which adds socket and read-thread slots and handle-connection, handle-connection-error, process, receive, and send. It implements client-connected-p, and close-connection. It automatically launches a thread on initiate-connection, which calls handle-connection. This function should loop and call receive to get new information for as long as appropriate and pass it on to process. continue and abort restarts are automatically established around it. It also makes sure that receive and send are locked to avoid threading collisions while sending or receiving. handle-connection-error is invoked if an error within handle-connection is detected. Finally, if handle-connection exits, close-connection is called which takes care of properly cleaning up the thread and calling usocket:socket-close.

After that big stinker, we get reconnecting-client, which adds the failures, max-failures, backoff, and interval slots. It also implements handle-connection-error which should smartly handle problems in the connection by automatically reestablishing it. It does this max-failures times before giving up with a client-reconnection-exceeded-error. Each time interval amount of time is waited, which is increased by backoff. backoff can be one of :constant, :linear, or :exponential.

Next we have a smaller class called timeout-client, adding a timeout and last-received-time slot. Upon receive it updates the last-received-time with the current time, and when handle-connection-idle is invoked, it will test if the timeout is exceeded. If so, a client-timeout-error is signalled.

Moving on there is the text-client, adding an encoding, and buffer field. Since it is a subclass of socket-client it can implement the receive and send functions to handle strings. buffer can be either :line in which case read-line is used, or a string of a fixed length, in which case read-sequence is used.

Now we get to the tcp-client with which come the element-type and idle-interval slots. It implements client-connected-p, initiate-connection, handle-connection, and handle-connection-idle. The handle-connection method will repeatedly wait for input with the idle-interval timeout, after which handle-connection-idle is called until there actually is some input available. If input is available, process is called with the result of receive.

The text-tcp-client is merely a combination of text-client and tcp-client.

Next up we have the tcp-server, which adds a clients slot that keeps a list of known client connections of this server. It also adds the accept and make-tcp-server-client methods, which have standard implementations. By default accept just calls initiate-connection with the result of make-tcp-server-client, which simply constructs an instance of tcp-server-client.

The tcp-server-client is a tcp-client with a server slot, to which it pushes itself upon initialisation. Upon connection closing, it removes itself from the server's clients list again. If you actually do implement a server, you will definitely want to subclass this to implement actually receiving behaviour and override make-tcp-server-client to construct an instance of your subclass instead.

Copyright

maiden-networking is licensed under the Artistic license. © Nicolas Hafner <shinmera@tymoon.eu> . This library can be obtained on https://github.com/Shinmera/maiden.

Package Index

MAIDEN-NETWORKING (ORG.SHIRAKUMO.MAIDEN.MODULES.NETWORKING)

class

`CONNECTION-CLOSED`

Event issued when a connection has been closed fully.

See CONNECTION-EVENT

class

`CONNECTION-EVENT`

Superclass for all events relating to connection updates.

See CLIENT-EVENT

class

`CONNECTION-INITIATED`

Event issued when a connection has been initiated successfully.

See CONNECTION-EVENT

class

`INCOMING-EVENT`

Superclass for all events that represent data that has been received from the remote.

class

`IP-CLIENT`

Superclass for all clients that are connected over the IP protocol.

See HOST
See PORT
See REMOTE-CLIENT

class

`OUTGOING-EVENT`

Superclass for all events that represent requests for data to be sent to the remote.

class

`RECONNECTING-CLIENT`

Mixin for a client that attempts to reconnect automatically after a failure.

The reconnection will be attempted a couple of times, should it
fail the first time around. The current number of failures is
stored in FAILURES. The maximum number of possible failures in
MAX-FAILURES. The amount of time that is waited between each
successive reconnection attempt is handled by BACKOFF and INTERVAL
where BACKOFF is one of :CONSTANT :LINEAR :EXPONENTIAL, and the
INTERVAL is the step for each respective function combined by
the number of failed attempts so far. If the number of failed
attempts is exceeded, a condition of type CLIENT-RECONNECTION-
EXCEEDED-ERROR is signalled.

This implements a primary method for HANDLE-CONNECTION-ERROR.

See FAILURES
See MAX-FAILURES
See BACKOFF
See INTERVAL
See CLIENT-RECONNECTION-EXCEEDED-ERROR
See HANDLE-CONNECTION-ERROR
See SOCKET-CLIENT

class

`REMOTE-CLIENT`

Superclass for all clients that are somehow connected to one or more remotes.

A remote-client may be a server, or a client in the networking
sense of the words.

The client's connection can be established by INITIATE-CONNECTION,
which is automatically called for you when the client is STARTed.
The client's connection can be shut down by CLOSE-CONNECTION,
which is automatically called for you when the client is STOPped.

Usually, once the connection has been initiated, a new thread is
spawned that calls HANDLE-CONNECTION to process the updates
coming from the remote. HANDLE-CONNECTION will then call RECEIVE
to receive an update, and then call PROCESS to perform the
necessary actions to handle the update in a useful manner. HANDLE-
CONNECTION must also take care of detecting errors in the
connection's stability. If the client must send something to the
remote, it must do so via the SEND function.

See INITIATE-CONNECTION
See CLOSE-CONNECTION
See HANDLE-CONNECTION
See RECEIVE
See PROCESS
See SEND

class

`SOCKET-CLIENT`

Superclass for all clients that are connected over a socket.

Updates over a socket-client are processed in the background by a
separate READ-THREAD. The READ-THREAD will simply call HANDLE-
CONNECTION. Sending to/from should happen over the SOCKET.

The thread is attempted to be shut down cleanly when the
connection is closed.

See SOCKET
See READ-THREAD
See IP-CLIENT

class

`TCP-CLIENT`

Superclass for all clients communicating over a TCP socket.

The default stream element-type is (UNSIGNED-BYTE 8).

See USOCKET:SOCKET-CONNECT
See IDLE-INTERVAL
see ELEMENT-TYPE
See SOCKET-CLIENT

class

`TCP-SERVER`

Superclass for all clients serving as a TCP server.

The HANDLE-CONNECTION method simply waits for new connections and
then calls ACCEPT with the new socket instance. The list of
connected clients is kept in CLIENTS.

See CLIENTS
See ACCEPT
See MAKE-TCP-SERVER-CLIENT
See SOCKET-CLIENT

class

`TCP-SERVER-CLIENT`

Superclass for all TCP server client instances.

Each client represents a connection to a remote client this serves
to. In case you subclass this, you must also subclass TCP-SERVER
and specialise on MAKE-TCP-SERVER-CLIENT to construct an instance
of your subclass.

See TCP-SERVER

class

`TEXT-CLIENT`

Mixin for a client whose connection deals with cleartext updates.

The updates are read into a buffer. If you need more control over
how the updates are read, you should implement your own version of
RECEIVE, or simply not use this mixin.

See ENCODING
See BUFFER
See SOCKET-CLIENT

class

`TEXT-TCP-CLIENT`

Superclass for all clients that have a text-based connection over TCP.

See TCP-CLIENT
See TEXT-CLIENT

class

`TIMEOUT-CLIENT`

Mixin for a client that generates a timeout error if there isn't enough feedback from the remote.

A timeout is detected by keeping track when the last update was
received from the remote. If the time distance is too great, then
the connection is closed and re-initiated.

See TIMEOUT
See LAST-RECEIVED-TIME
See REMOTE-CLIENT

condition

`CLIENT-CONNECTION-CLOSED-UNCLEANLY-WARNING`

Condition signalled when the connection could not be closed cleanly.

See CLOSE-CONNECTION
See CLIENT-CONDITION
See SOCKET-CLIENT

condition

`CLIENT-CONNECTION-FAILED-ERROR`

Condition signalled when the connection initiation failed.

See INITIATE-CONNECTION
See CLIENT-CONDITION
See SOCKET-CLIENT

condition

`CLIENT-RECONNECTION-EXCEEDED-ERROR`

Condition signalled when the maximum number of reconnection attempts has been exceeded.

See HANDLE-CONNECTION-ERROR
See RECONNECTING-CLIENT
See CLIENT-CONDITION

condition

`CLIENT-STILL-CONNECTED-ERROR`

Condition signalled when another connection initiation is attempted while it is still connected.

See INITIATE-CONNECTION
See CLIENT-CONDITION
See SOCKET-CLIENT

condition

`CLIENT-TIMEOUT-ERROR`

Condition signalled when the connection has timed out.

See HANDLE-CONNECTION
See TIMEOUT-CLIENT

condition

`DATA-CONDITION`

Superclass for all conditions relating to errors during interpretation of an update from the remote.

See REMOTE

condition

`DATA-PARSE-ERROR`

Condition signalled when the data received from the remote could not be parsed.

See DATA-CONDITION
See CLIENT-CONDITION

condition

`DATA-TOO-LONG-WARNING`

Condition signalled when the data to be sent is too long and was truncated or dropped as a result.

See DATA-CONDITION
See CLIENT-CONDITION

condition

`UNKNOWN-DATA-WARNING`

Condition signalled when the data received could be parsed, but is something unknown that the client doesn't know what to do with.

See DATA-CONDITION
See CLIENT-CONDITION

accessor (

`BACKOFF`

OBJECT)

The type of backoff used to determine the amount of time between each reconnection attempt.

Must be one of the following.
:CONSTANT     The sleep time is INTERVAL
:LINEAR       The sleep time is INTERVAL*FAILURES
:EXPONENTIAL  The sleep time is INTERVAL^FAILURES

See INTERVAL
See RECONNECTING-CLIENT

accessor (

`BUFFER`

OBJECT)

The buffer used to read from the connection.

Can be either a vector, or :line if READ-LINE should be used
instead.

See TEXT-CLIENT

accessor (

`CLIENTS`

OBJECT)

Accessor to the TCP server's list of client instances.

See TCP-SERVER
See TCP-SERVER-CLIENT

accessor (

`DATA`

OBJECT)

Reader for the data that could not be interpreted.

See DATA-CONDITION

accessor (

`ENCODING`

OBJECT)

The character encoding used by the connection.

See TEXT-CLIENT

accessor (

`FAILURES`

OBJECT)

The current number of failures occurred during reconnection attempts.

See RECONNECTING-CLIENT

accessor (

`HOST`

OBJECT)

Accessor to the host that the client is connected to.

See IP-CLIENT

accessor (

`IDLE-INTERVAL`

OBJECT)

The number of seconds to wait for an update from the remote before calling HANDLE-CONNECTION-IDLE.

See TCP-CLIENT

accessor (

`INTERVAL`

OBJECT)

The interval used for the calculation of the backoff time between reconnection attempts.

See BACKOFF
See RECONNECTING-CLIENT

accessor (

`LAST-RECEIVED-TIME`

OBJECT)

Accessor to the universal-time representing the last time an update was received from the remote.

See TIMEOUT-CLIENT

accessor (

`MAX-FAILURES`

OBJECT)

The maximum number of failed connection attempts that may occur before it gives up.

See RECONNECTING-CLIENT

accessor (

`PORT`

OBJECT)

Accessor to the port that the client is connected to.

See IP-CLIENT

accessor (

`READ-THREAD`

OBJECT)

Accessor to the background reading thread used to process the connection.

See SOCKET-CLIENT
See BT:THREAD

accessor (
SERVER
OBJECT)
```
 
```

accessor (

`SOCKET`

OBJECT)

Accessor to the socket object that handles the internals of the connection.

See SOCKET-CLIENT
See USOCKET:SOCKET

accessor (

`TIMEOUT`

CONDITION)

Accessor to the number of seconds after which the connection is deemed to have been severed.

See TIMEOUT-CLIENT

generic (

`ACCEPT`

SOCKET TCP-SERVER)

This function is called to establish the connection to a new client.

It should create the appropriate client instance and add it to the
server's list of clients. It should then initiate the actual
connection establishment and connection handling protocols.

See TCP-SERVER
See MAKE-TCP-SERVER-CLIENT

generic (

`CLIENT-CONNECTED-P`

CLIENT)

Returns true if the client is currently connected to its remote.

See REMOTE-CLIENT

generic (

`CLOSE-CONNECTION`

CLIENT)

Closes the connection to the remote if it's still open.

May signal a warning of type CLIENT-CONNECTION-CLOSED-UNCLEANLY-
WARNING if the connection could not be closed cleanly.

See REMOTE-CLIENT
See CLIENT-CONNECTION-CLOSED-UNCLEANLY-WARNING

generic (

`CLOSING-ERROR`

CONDITION)

Reader for the error that occurred during the connection closing attempt.

generic (

`ELEMENT-TYPE`

OBJECT)

Reader for the element-type the TCP connection's stream should use.

See TCP-CLIENT

generic (

`HANDLE-CONNECTION`

CLIENT)

This is called to handle the connection after it has been initiated.

This method is likely called in a background thread, and as such
must not exit unless the connection has been closed. The primary
method on this function must read content from the connection to
the remote server by RECEIVE and send it off for processing by
the client through PROCESS.

If an error occurs while the connection is live, the error must be
passed on to HANDLE-CONNECTION-ERROR.

If no update is received from the server in a long enough time,
the method must call HANDLE-CONNECTION-IDLE. The minimal or
maximal amount of time that may pass between two calls to HANDLE-
CONNECTION-IDLE is client-specific, however.

HANDLE-CONNECTION provides two restarts around the primary method:
CONTINUE, which will retry the primary method, and ABORT, which
will exit the connection handling.

Upon exiting HANDLE-CONNECTION, the connection is closed by CLOSE-
CONNECTION.

See REMOTE-CLIENT
See RECEIVE
See PROCESS
See HANDLE-CONNECTION-ERROR
See CLOSE-CONNECTION

generic (

`HANDLE-CONNECTION-ERROR`

ERR CLIENT)

This is called to handle errors during connection handling.

The primary method should decide what to do based on the condition
it received. Depending on this it may either close the connection
and exit, try to stabilise and mitigate, reconnect, or do whatever
seems suitable for the client.

See REMOTE-CLIENT
See HANDLE-CONNECTION

generic (

`HANDLE-CONNECTION-IDLE`

TCP-CLIENT)

This is called when the connection has not seen or provided new content within a long enough period of time.

The primary method should decide what to do in order to check
whether the connection is still alive, and what to do to stabilise
it, if anything.

See REMOTE-CLIENT
See HANDLE-CONNECTION

generic (

`INITIATE-CONNECTION`

CLIENT)

Opens the connection to the remote.

If the connection is already open, an error of type CLIENT-STILL-
CONNECTED-ERROR is signalled. If the connection has failed, a
condition of type CLIENT-CONNECTION-FAILED-ERROR is signalled.

After connection initiation, the client will most likely handle
the connection in the background and may signal a variety of
conditions while that happens.

See REMOTE-CLIENT
See CLIENT-STILL-CONNECTED-ERROR
See CLIENT-CONNECTION-FAILED-ERROR

generic (

`MAKE-TCP-SERVER-CLIENT`

SERVER SOCKET)

This function is called to construct a new client instance for the TCP server.

See TCP-SERVER-CLIENT

generic (

`PROCESS`

MESSAGE TCP-CLIENT)

This is called to handle an update from the remote.

The update may be an object of any type, depending on what the
client deals with. The client will likely want to convert the
update object into an event of some kind and issue that event
onto its cores.

If the data can be parsed, but the client doesn't understand it,
a condition of type UNKNOWN-DATA-WARNING is signalled.

See HANDLE-CONNECTION
See UNKNOWN-DATA-WARNING

generic (

`RECEIVE`

TCP-CLIENT)

This function blocks until it has read a complete update from the remote.

Whatever an "update" may be is client dependant. However, an
update must be an object that can be passed to PROCESS to be
handled by the client.

This function usually does not need to be called outside of
HANDLE-CONNECTION.

If the data cannot be parsed, a condition of type DATA-PARSE-ERROR
is signalled. If the data can be parsed, but the client doesn't
understand it, a condition of type UNKNOWN-DATA-WARNING is signalled.

This function may be called asynchronously.

See REMOTE-CLIENT
See HANDLE-CONNECTION
See UNKNOWN-DATA-WARNING

generic (

`SEND`

THING TCP-CLIENT)

This is called to send an update to the remote.

The update may be an object of any type, depending on what the
client deals with. The client will likely want to handle certain
types of events and convert them into objects to send off with,
using this function.

A client may only support updates up to a particular length. If
the length is exceeded, a condition of type DATA-TOO-LONG-WARNING
is signalled.

This function may be called asynchronously.

See REMOTE-CLIENT
See DATA-TOO-LONG-WARNING