serialserver

Overview ¶

Package serialserver provides a server for synchronous client-server communication.

This work is licensed under CC0 1.0 Universal (CC0 1.0), Public Domain Dedication. For details see:

http://creativecommons.org/publicdomain/zero/1.0/

Online go-documentation is available at:

https://godoc.org/bitbucket.org/pcas/serverutil/serial/serialserver

The basic communication protocol is described in package bitbucket.org/pcas/serverutil/serial (https://godoc.org/bitbucket.org/pcas/serverutil/serial). In summary:

1. client sends a task code specifying the task for the server to perform;

2. client sends message data (implementation specific, encoded as described in https://godoc.org/bitbucket.org/pcas/serverutil/serial);

3. server sends a response code, which is one of: - serverutil.OK - serverutil.Error - serverutil.Goodbye

   4a. if the response code is serverutil.OK, server sends response data (implementation-specific, encoded as described in https://godoc.org/bitbucket.org/pcas/serverutil/serial);

   4b. if the response code is serverutil.Error, server sends a serial.ErrorCode describing the error;

   4c. if the response code is serverutil.Goodbye then the server is closing the connection without handling the task.

The server is free to silently close the connection at any time.

To get a new server, do something like:

  S := serialserver.New(&serialserver.Timeout{
	Wait:  30 * time.Minute,
	Read:  5 * time.Second,
	Write: 5 * time.Second,
  })

where Wait, Read, and Write are, respectively, the time.Duration timeout to use whilst waiting for a new task, the rolling read timeout once a task has started, and the rolling write timeout.

You then need to register a task function of type TaskFunc for each task code that the server could be passed. You do this by calling S.Register(t,f) where t is the serverutil.TaskCode and f is the TaskFunc.

The task function f will be called whenever the task code received by the server in step 1 above is t. The task function is passed a binaryutil.BinaryReader 'in' that contains the message data (if any) sent by the client in step 2. The reader 'in' will automatically decode the message data; in particular, the user never needs to encode or decode data, and 'in' will automatically return io.EOF at the end of the message data. The client should return a io.Reader 'out', or an error. Any response data should be written to the returned io.Reader 'out'; this response data will be sent by the server as in step 4a. The contents of 'out' will automatically be encoded before being sent to the server; the user never needs to encode data.

If a non-nil error err is returned by the task function then the reader 'out' will be ignored. If err satisfies the the serverutil.ErrorCoder interface, then a serverutil.Error response code will be sent to the client, followed by the err.ErrorCode(), as in step 4b. If the returned error does not satisfy the serverutil.ErrorCoder interface then the situation is serious: the client will be placed in an error state, and the connection will be dropped.

This task function is passed a context.Context ctx that will be cancelled on server shutdown, and which could also for example contain session-specific data such as username or authentication credentials (these would have been negotiated during a handshake, which takes place outside the serialclient/serialserver framework). Any long-running or blocking tasks should make use of this context. The task function is also provided with a log.Interface logger lg, to which it should write useful feedback.

Once all task functions have been registered, the server can be used as follows:

// Listen on the port
listener, err := net.Listen("tcp", ":"+port)
if err != nil {
	// Handle the error
	// ...
}
defer listener.Close()
// Make a context to cancel everything
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
// Register the task handlers (see the discussion above)
// ...
// Listen for connections
for {
	conn, err := listener.Accept()
	if err != nil {
		// Handle the error
		// ...
	}
	// Do any handshake required and establish the byte
	// order e being used by the client
	// ...
	e := binary.BigEndian
	// Call the connection handler; updatedCtx is the
	// context ctx along with with any session-specific
	// data provided during the handshake.
	s.HandleConnection(updatedCtx, conn, e, args...)
}

Any variadic arguments 'args' passed to HandleConnection will be passed to any task functions called for this connection. This provides a way of passing in session-specific data without attaching them to the context.

See package bitbucket.org/pcas/logger/cmd/logd (https://godoc.org/bitbucket.org/pcas/logger/cmd/logd) for a real-world example of a server that uses the serialserver package.

Package serialserver provides a server for basic, synchronous client-server communication.

This work is licensed under CC0 1.0 Universal (CC0 1.0), Public Domain Dedication. For details see:

http://creativecommons.org/publicdomain/zero/1.0/

Online go-documentation is available at:

https://godoc.org/bitbucket.org/pcas/serverutil/serial/serialserver

/////////////////////////////////////////////////////////////////////// server.go ///////////////////////////////////////////////////////////////////////

A Server listens for tasks on a specified connection and responds appropriately, with cancellation provided by a context ctx. So typical usage looks like:

ln, err := net.Listen("tcp", ":8080")

if err != nil {
	// handle error
}

s := serialserver.New(timeouts)

for acceptingConnections {
	conn, err := ln.Accept()
	if err != nil {
		// handle error
	}
	// Typically some form of client handshake code goes here; this provides an
	// opportunity to determine the byte order e being used by the client.
	// ...
	// Handle the connection
	go s.HandleConnection(ctx, conn, e)
}

Here timeouts describes the *serialserver.Timeout durations (and can be nil, in which case the default timeouts will be used), and ctx is a context.Context that can be used to terminate the client connection. Typically you will install a signal handler which, on catching a signal that indicates we should shut down, sets acceptingConnections to false and calls the cancel function for the context ctx.