Update README.md

BClient

README.md

@@ -3,21 +3,78 @@ bformat
 
 [![D](https://github.com/besterprotocol/bformat/actions/workflows/d.yml/badge.svg)](https://github.com/besterprotocol/bformat/actions/workflows/d.yml)
 
-A simple message format for length prefixed messages
+A simple message format for automatically length-prefixing messages over any [`Socket`](https://dlang.org/phobos/std_socket.html#.Socket) or [River-based](https://github.com/deavmi/river) [`Stream`](https://river.dpldocs.info/river.core.stream.Stream.html).
 
 ## What is bformat?
 
-bformat is simply a format and a library that allows one to prefix their messages with a length field such that it can be retrieved on the other side over a socket that is opened in a STREAM mode. It simply manages a socket's I/O stream such that the first 4 bytes are read as the length and then the preceding bytes are read accordingly. Rather than duplicate this sort of logic in all the code I wrote ever for my networking projects, I decided to make it a library as it would reduce the amount of duplicate code and also allow code re-use of something I could change or optimize later.
+bformat makes it easy to build applications whereby you want to send data over a streaming interface (either a `Socket` opened in `SocketType.STREAM` mode or a River-based `Stream`) and want to be able to read the data as length-prefixed messages, without the hassle of implementing this yourself. This is whwre bformat shines by providing support for this in a cross-platform manner so you do not have to worry aboutimplementing it yourself countless times again everytime you require such functionality in a project.
 
-It's also cross-platform and does all the byte-swapping endianess goodness you'd need - so you need not worry about that.
+## Usage
 
+You can see the [API](https://bformat.dpldocs.info/index.html) for information on how to use it but it boils down to spawning a new [`BClient`](https://bformat.dpldocs.info/bformat.client.BClient.html) which takes in either a `Socket` of `Stream` (see [River](https://river.dpldocs.info/river.html)) and then you can either send data using [`sendMessage(byte[])`](https://bformat.dpldocs.info/bformat.client.BClient.sendMessage.html) and receive using [`receiveMessage(ref byte[])`](https://bformat.dpldocs.info/bformat.client.BClient.receiveMessage.html).
 
-## Want to use it in your project?
+Below we have an example application which does just this:
 
-It's rather easy to add it to your D project (so far I have only implemented this in DLang as that is where I need it). 
+```d
+/**
+ * Create a server that encodes a message to the client
+ * and then let the client decode it from us; both making
+ * use of `BClient` to accomplish this
+ */
+unittest
+{
+	UnixAddress unixAddr = new UnixAddress("/tmp/bformatServer.sock");
 
-Just run the command `dub add bformat`.
+	scope(exit)
+	{
+		import std.stdio;
+		remove(cast(char*)unixAddr.path());
+	}
 
-When using the library you will want to use the two functions provided `sendMessage(Socket, byte[])` and `receiveMessage(Socket, ref byte[])`. These two functions allow you to send data and have it encoded into the bformat format and receive data and interpret the received bformat format such that the correct length of data can read.
+	Socket serverSocket = new Socket(AddressFamily.UNIX, SocketType.STREAM);
+	serverSocket.bind(unixAddr);
+	serverSocket.listen(0);
 
-And then you can take a look at the [source code documentation](https://bformat.dpldocs.info/v3.1.18/) here on the functions the library provides and how to use them.
+	class ServerThread : Thread
+	{
+		private Socket servSock;
+
+		this(Socket servSock)
+		{
+			this.servSock = servSock;
+			super(&worker);
+		}
+
+		private void worker()
+		{
+			Socket clientSock = servSock.accept();
+
+			BClient bClient = new BClient(clientSock);
+
+			byte[] message = cast(byte[])"ABBA";
+			bClient.sendMessage(message);
+		}
+	}
+
+	Thread serverThread = new ServerThread(serverSocket);
+	serverThread.start();
+
+	Socket client = new Socket(AddressFamily.UNIX, SocketType.STREAM);
+	client.connect(unixAddr);
+	BClient bClient = new BClient(client);
+
+	byte[] receivedMessage;
+	bClient.receiveMessage(receivedMessage);
+	assert(receivedMessage == "ABBA");
+	writeln(receivedMessage);
+	writeln(cast(string)receivedMessage);
+}
+```
+
+### Adding to your peoject
+
+It's rather easy to add it to your D project, just run the command `dub add bformat`.
+
+## License
+
+The license used is LGPL v3.

dub.json

@@ -2,9 +2,12 @@
 	"authors": [
 		"Tristan B. Velloza Kildaire"
 	],
-	"homepage": "https://deavmi.assigned.network/projects/bformat/",
 	"copyright": "Copyright © 2023, Tristan B. Kildaire",
+	"dependencies": {
+		"river": "~>0.3.6"
+	},
 	"description": "bformat socket writer and reader",
+	"homepage": "https://deavmi.assigned.network/projects/bformat/",
 	"license": "LGPL v3",
 	"name": "bformat",
 	"targetType": "library"

source/bformat/client.d

@@ -0,0 +1,209 @@
+/** 
+ * Socket encoding/decoding functions
+ */
+module bformat.client;
+
+import std.socket : Socket;
+import river.core;
+import river.impls.sock : SockStream;
+
+/** 
+ * Bformat client to encode and decode via a
+ * `Socket` or river-based `Stream`
+ */
+public class BClient
+{
+	/** 
+	 * Underlying stream
+	 */
+	private Stream stream;
+
+	/** 
+	 * Constructs a new `BClient` for encoding and decoding
+	 * to and from the provided `Socket`
+	 *
+	 * Params:
+	 *   socket = the `Socket` to use for writing and reading
+	 */
+	this(Socket socket)
+	{
+		this(new SockStream(socket));
+	}
+
+	/** 
+	 * Constructs a new `BClient` for encoding and decoding
+	 * to and from the provided river-based `Stream`
+	 *
+	 * Params:
+	 *   stream = the `Stream` to use for writing and reading
+	 */
+	this(Stream stream)
+	{
+		this.stream = stream;
+	}
+
+	/** 
+	 * Receives a message from the provided socket
+	 * by decoding the streamed bytes into bformat
+	 * and finally placing the resulting payload in
+	 * the provided array
+	 *
+	 * Params:
+	 *   originator = the socket to receive from
+	 *   receiveMessage = the nbuffer to receive into
+	 *
+	 * Returns: true if the receive succeeded, false otheriwse
+	 */
+	public bool receiveMessage(ref byte[] receiveMessage)
+	{
+		/* Construct a buffer to receive into */
+		byte[] receiveBuffer;
+
+		/* Get the length of the message */
+		byte[4] messageLengthBytes;
+
+		try
+		{
+			stream.readFully(messageLengthBytes);
+		}
+		catch(StreamException streamErr)
+		{
+			/* If there was an error reading from the socket */
+			return false;
+		}
+
+
+		/* Response message length */
+		uint messageLength;
+
+		/* Little endian version you simply read if off the bone (it's already in the correct order) */
+		version(LittleEndian)
+		{
+			messageLength = *cast(int*)messageLengthBytes.ptr;
+		}
+
+		/* Big endian requires we byte-sapped the little-endian encoded number */
+		version(BigEndian)
+		{
+			byte[] swappedLength;
+			swappedLength.length = 4;
+
+			swappedLength[0] = messageLengthBytes[3];
+			swappedLength[1] = messageLengthBytes[2];
+			swappedLength[2] = messageLengthBytes[1];
+			swappedLength[3] = messageLengthBytes[0];
+
+			messageLength = *cast(int*)swappedLength.ptr;
+		}
+
+
+		/* Read the full message */
+		receiveBuffer.length = messageLength;
+		try
+		{
+			stream.readFully(receiveBuffer);
+			receiveMessage = receiveBuffer;
+
+			/* If there was no error receiving the message */
+			return true;
+		}
+		catch(StreamException streamErr)
+		{
+			/* If there was an error reading from the socket */
+			return false;
+		}
+	}
+
+	/** 
+	 * Encodes the provided message into the bformat format
+	 * and sends it over the provided socket
+	 *
+	 * Params:
+	 *   recipient = the socket to send over
+	 *   message = the message to encode and send
+	 *
+	 * Returns: true if the send succeeded, false otherwise
+	 */
+	public bool sendMessage(byte[] message)
+	{
+		/* The message buffer */
+		byte[] messageBuffer;
+
+		import bformat.marshall : encodeBformat;
+		messageBuffer = encodeBformat(message);
+
+		try
+		{
+			/* Send the message */
+			stream.writeFully(messageBuffer);
+
+			return true;
+		}
+		catch(StreamException streamError)
+		{
+			return false;
+		}
+	}
+
+}
+
+version(unittest)
+{
+	import std.socket;
+	import core.thread;
+	import std.stdio;
+}
+
+/**
+ * Create a server that encodes a message to the client
+ * and then let the client decode it from us; both making
+ * use of `BClient` to accomplish this
+ */
+unittest
+{
+	UnixAddress unixAddr = new UnixAddress("/tmp/bformatServer.sock");
+
+	scope(exit)
+	{
+		import std.stdio;
+		remove(cast(char*)unixAddr.path());
+	}
+
+	Socket serverSocket = new Socket(AddressFamily.UNIX, SocketType.STREAM);
+	serverSocket.bind(unixAddr);
+	serverSocket.listen(0);
+
+	class ServerThread : Thread
+	{
+		private Socket servSock;
+
+		this(Socket servSock)
+		{
+			this.servSock = servSock;
+			super(&worker);
+		}
+
+		private void worker()
+		{
+			Socket clientSock = servSock.accept();
+
+			BClient bClient = new BClient(clientSock);
+
+			byte[] message = cast(byte[])"ABBA";
+			bClient.sendMessage(message);
+		}
+	}
+
+	Thread serverThread = new ServerThread(serverSocket);
+	serverThread.start();
+
+	Socket client = new Socket(AddressFamily.UNIX, SocketType.STREAM);
+	client.connect(unixAddr);
+	BClient bClient = new BClient(client);
+
+	byte[] receivedMessage;
+	bClient.receiveMessage(receivedMessage);
+	assert(receivedMessage == "ABBA");
+	writeln(receivedMessage);
+	writeln(cast(string)receivedMessage);
+}

source/bformat/package.d

@@ -4,18 +4,11 @@
 module bformat;
 
 /**
- * Encodes the provided message into the bformat format
- * and sends it over the provided socket
+ * Provides a client which consumes a stream
+ * which can encode and decode messages to
+ * and from it
  */
-public import bformat.sockets : sendMessage;
-
-/**
- * Receives a message from the provided socket
- * by decoding the streamed bytes into bformat
- * and finally placing the resulting payload in
- * the provided array
- */
-public import bformat.sockets : receiveMessage;
+public import bformat.client : BClient;
 
 /**
  * Encodes the provided message into the bformat format

source/bformat/sockets.d

@@ -1,132 +0,0 @@
-/** 
- * Socket encoding/decoding functions
- */
-module bformat.sockets;
-
-import std.socket : Socket, SocketFlags, MSG_WAITALL;
-
-/** 
- * Receives a message from the provided socket
- * by decoding the streamed bytes into bformat
- * and finally placing the resulting payload in
- * the provided array
- *
- * Params:
- *   originator = the socket to receive from
- *   receiveMessage = the nbuffer to receive into
- *
- * Returns: true if the receive succeeded, false otheriwse
- */
-public bool receiveMessage(Socket originator, ref byte[] receiveMessage)
-{
-	/* Construct a buffer to receive into */
-	byte[] receiveBuffer;
-
-	bool status = true;
-
-
-	/* The amount of bytes received */
-	long bytesReceived;
-
-	/* Get the length of the message */
-	byte[4] messageLengthBytes;
-	bytesReceived = originator.receive(messageLengthBytes, cast(SocketFlags)MSG_WAITALL);
-
-	/* If there was an error reading from the socket */
-	if(!(bytesReceived > 0))
-	{
-		status =  false;
-	}
-	/* If the receive was successful */
-	else
-	{
-		/* Response message length */
-		uint messageLength;
-
-		/* Little endian version you simply read if off the bone (it's already in the correct order) */
-		version(LittleEndian)
-		{
-			messageLength = *cast(int*)messageLengthBytes.ptr;
-		}
-
-		/* Big endian requires we byte-sapped the little-endian encoded number */
-		version(BigEndian)
-		{
-			byte[] swappedLength;
-			swappedLength.length = 4;
-
-			swappedLength[0] = messageLengthBytes[3];
-			swappedLength[1] = messageLengthBytes[2];
-			swappedLength[2] = messageLengthBytes[1];
-			swappedLength[3] = messageLengthBytes[0];
-
-			messageLength = *cast(int*)swappedLength.ptr;
-		}
-
-
-		/* Read the full message */
-		receiveBuffer.length = messageLength;
-		bytesReceived = originator.receive(receiveBuffer, cast(SocketFlags)MSG_WAITALL);
-
-		/* If there was an error reading from the socket */
-		if(!(bytesReceived > 0))
-		{
-			status = false;
-		}
-		/* If there was no error receiving the message */
-		else
-		{
-			receiveMessage = receiveBuffer;
-		}
-	}
-
-	return status;
-}
-
-/** 
- * Encodes the provided message into the bformat format
- * and sends it over the provided socket
- *
- * Params:
- *   recipient = the socket to send over
- *   message = the message to encode and send
- *
- * Returns: true if the send succeeded, false otherwise
- */
-public bool sendMessage(Socket recipient, byte[] message)
-{
-	/* The message buffer */
-	byte[] messageBuffer;
-
-	/* Encode the 4 byte message length header (little endian) */
-	int payloadLength = cast(int)message.length;
-	byte* lengthBytes = cast(byte*)&payloadLength;
-
-	/* On little endian simply get the bytes as is (it would be encoded as little endian) */
-	version(LittleEndian)
-	{
-		messageBuffer ~= *(lengthBytes+0);
-		messageBuffer ~= *(lengthBytes+1);
-		messageBuffer ~= *(lengthBytes+2);
-		messageBuffer ~= *(lengthBytes+3);
-	}
-
-	/* On Big Endian you must swap the big-endian-encoded number to be in little endian ordering */
-	version(BigEndian)
-	{
-		messageBuffer ~= *(lengthBytes+3);
-		messageBuffer ~= *(lengthBytes+2);
-		messageBuffer ~= *(lengthBytes+1);
-		messageBuffer ~= *(lengthBytes+0);
-	}
-	
-
-	/* Add the message to the buffer */
-	messageBuffer ~= cast(byte[])message;
-
-	/* Send the message */
-	long bytesSent = recipient.send(messageBuffer);
-
-	/* TODO: Compact this */
-	return bytesSent > 0;
-}