serial

Overview ¶

Package serial provides a framework 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

Communication is serial (i.e. proceeds in a well-defined order) within each client-server session, but multiple clients can connect concurrently to the same server and the order in which parts of different client-server sessions are processed is not guaranteed. Communication proceeds as follows:

• client sends a one-byte task code;
• client sends message data of arbitrary length.

The task code specifies the task that the server should perform. The task code is a uint8. Values >= 250 are reserved for internal use. The message data is implementation-specific, and is an encoded stream of blocks of bytes. By this we mean:

• The first byte of every block is a uint8 indicating the number N of bytes in the block.
• The next N bytes of data represent the content of the byte stream.
• N is 0 if and only if the stream has ended.

For example, the message data representing an empty message is encoded to the single byte 0x00. The encoded sequence of bytes:

[0x03, 0x01, 0x02, 0x03, 0x01, 0x04, 0x00]

will be decoded to the message data:

[0x01, 0x02, 0x03, 0x04]

When finished, the server will respond with a one-byte response code.

Case 1. serverutil.OK response:

• server sends a response code of serverutil.OK;
• server sends response data of arbitrary length.

The response data is implementation-specific, and is an encoded stream of bytes in the same format as described above for message data. The client may now send a further TaskCode, with communication proceeding as before, or may close the connection to the server.

Case 2. serverutil.Error response:

• server sends a response code of serverutil.Error;
• server sends a one-byte error code.

The error code specifies the error that occurred.

Case 3. serverutil.Goodbye response:

• server sends a response code of serverutil.Goodbye.

The server is going away and will not respond to the task.

The client and server for the serial package are provided in the subpackages serialclient (https://godoc.org/bitbucket.org/pcas/serverutil/serial/serialclient) and serialserver (https://godoc.org/bitbucket.org/pcas/serverutil/serial/serialserver); see therein for detailed documentation on usage. An example implementation can be found in the example directory.