socketplate.app

socketplate – “app entry point” helper module

Also provides all necessary public imports to quickstart coding.

Developer manual

Hello and welcome to socketplate.

How to get started

socketplate.app provides to entry points:

• Single connection handler
• Manual handler setup

Both come with batteries included:

• Several command-line configuration options (worker count etc.)
• Built-in --help parameter
• Privilege dropping (on POSIX)
• Specify a custom app name
• Custom tuning of the socket server (see socketplate.server.server.SocketServerTunables)

All that’s left to do is to pick either of the entry points and call the corresponding runSocketplateApp overload from your main() function.

Single connection handler

In this mode listening addresses are read from args that will usually point to the program’s command line args.

This way, an end-user can specify listening addresses by passing -S <socket> parameters.

$ ./your-app --S 127.0.0.1:8080
$ ./your-app --S [::1]:8080
$ ./your-app

Sample code:

import socketplate.app;

int main(string[] args)
{
    return runSocketplateApp("my app", args, (SocketConnection connection) {
        // your code here…
    });
}

There’s no need to give up default listening addresses either. Provide an array of them as the 4th parameter of the runSocketplateApp function. If default listening addresses are provided, the server will use them when non are specified through args.

string[] defaultListeningAddresses = [
    "127.0.0.1:8080",
    "[::1]:8080",
];

return runSocketplateApp("my app", args, (SocketConnection connection) {
    // your code here…
}, defaultListeningAddresses);

Manual handler setup

This variation allows you to setup listeners through code instead.

Code sample:

import socketplate.app;

int main(string[] args)
{
    return runSocketplateApp("my app", args, (SocketServer server)
    {
        server.listenTCP("127.0.0.1:8080", (SocketConnection connection){
            // listener 1
            // your code here…
        });

        server.listenTCP("[::1]:8080", (SocketConnection connection) {
            // listener 2
            // your code here…
        });
    });
}

In practice you might want to use callback variables and reuse them across listeners:

return runSocketplateApp("my app", args, (SocketServer server)
{
    ConnectionHandler myConnHandler = (SocketConnection connection) {
        // your code here…
    };

    server.listenTCP("127.0.0.1:8080", myConnHandler);
    server.listenTCP(    "[::1]:8080", myConnHandler);
}

Connection usage

Established connections are made available as socketplate.connection.SocketConnection.

To close a connection, simply call .close() on it.

Sending

Sending data is super easy:

delegate(SocketConnection connection)
{
    ptrdiff_t bytesSent = connection.send("my data");
}

Receiving

Received data is retrieved via user-provided buffers.

delegate(SocketConnection connection)
{
    // allocate a new buffer (with a size of 256 bytes)
    ubyte[] buffer = new ubyte[](256)

    // read data into the buffer
    auto bytesReceived = connection.receive(buffer);

    if (bytesReceived <= 0) {
        // connection either got closed or timed out,
        // or an error ocurred
        return;
    }

    // slice the buffer (to view only the received data)
    ubyte[] data = buffer[0 .. bytesReceived];

    // do something…
}

delegate(SocketConnection connection)
{
    // allocate a new buffer (with a size of 256 bytes)
    ubyte[] buffer = new ubyte[](256)

    // read data into the buffer
    // note: `receiveSlice` throws on error
    ubyte[] data = connection.receiveSlice(buffer);

    if (data.length == 0) {
        // nothing received, connection got closed remotely
        return;
    }

    // do something…
}

Logging

See socketplate.log for details.

logInfo("My log message");