Local Server

You could use this to make a little game on your server or something.

The server library listens on a Unix domain socket you specify (like a file path), and then other users can send requests to the server using the client library.

The server library can tell you what user sent a request, giving you some nice OS-level authentication.

There are also WIP command line utilities that should make it easier to work with the libraries from scripts.

Dependency

• JWT mode requires libjwt. Eventually I’ll try to add a way to build it without JWT mode, for those who don’t need it.

Building

Make the libraries

> make lib

Make the command line util

> make exe

Usage

Using the libraries

To use the libraries, you'll need the library file created from the make lib step and the corresponding header file.

So, for example, to use the server, you'd need:

• ./bin/server.so
• ./include/server.h

You should be able to use these libraries in a variety of languages that support a C foreign function interface (FFI).

API

I'll write up API documentation soon, but for now, look at the header files in ./include for an idea of the API.

Running the command line util

There are subcommands for the server and the client respectively. This part is still a WIP, so don't expect much yet!

Server

The server listens for strings from clients, writes them to stdout, and waits for a line from stdin to send back to the client. This can be handled interactively, but it can also be hooked into with a script, as in the example ./server.sh.

> localserv server [-u] [-a] <socket-path>

• <socket-path>: any file path that you have permissions to that isn't already occupied, e.g., ~/example.sock
• -u, --username: flag to include username in request output.
• -a, --auth: flag for auth mode (implies --username)

Auth mode

The server features an auth mode, in which it implements an additional protocol layer for enabling a simple form of authorization. In this mode, servers will accept three types of messages from clients.

Issue

Request:

ISSUE

Response: The server issues a JSON web token (JWT) which identifies the username of the client. This JWT has a short lifespan (15 seconds), and is primarily used to get a longer-lasting token via the "refresh" action. This action does not write anything to stdout or read anything from stdin.

Refresh

Request:

REFRESH
<JSON web token>

Response: If the token is valid, server issues a new JSON web token (JWT) with the same username identified. This JWT has a long lifespan (10 minutes), and can be used with the "authorize" action to send messages to the server. This action does not write anything to stdout or read anything from stdin.

Issue

Message format:

AUTHORIZE
<JSON web token>
<message>

Response: If the token is valid, server conveys the username identified in the JWT and the corresponding message to stdin, and waits for a response from stdout, conveying it back to the client.

Client

> localserv client <socket-path> [<request>]

• <socket-path>: the same path you specified when starting your server.
• <request>: just any string you want to send to the server.

Server script example

After building with make exe, run the server script ./server.sh like so:

> ./server.sh ~/myserver.sock

Leave this running, and in another terminal session, run the client against the same socket:

> bin/localserv client ~/myserver.sock 'my message'
MY MESSAGE

As shown, you should receive the capitalized version of your message from the server. In theory, this should work if other users too, if they run the client against the same socket.