larboard

What is this?

larboard is a proof of concept project that has a few goals:

1. Rewrite TinySign's functionality in a better language (i.e., some really basic Halo 2 map manipulation functionality)
2. Explore patterns for implementing interprocess communication (IPC)
3. Support multiple threads writing to a single instances of the IPC application
4. Provide the above in a language that can be compiled for many different OSes and architectures

What is so important about IPC?

Ultimately, I want to provide a library that can be easily wrapped by another running process, regardless of what the parent process is written in, or is running on.

This functionality is provided in the ipc package, which is then implemented by a Golang command line utility using the following patterns:

1. Define one interface at the top level of the library along with any method options as structs (with specified JSON fields)
2. Provide a single struct (also with specified JSON fields) that represents the result of an interface call
3. Provide simple structs for managing IPC instances, thus permitting a single process with multiple threads to safely use a single instance of the library via stdin

IPC API

Interprocess communication is enabled by compiling an included Golang command line application for a designated OS and architecture. The application will parse stdin for interface calls in the following format:

(ipc-instance-id)|(method-name)(json-blob)

Creating a new IPC instance

If the application is started without any special flags, you must create an IPC instance using the new keyword followed by an InstanceDetails:

new{"id":"abc123","game":"halo2"}

Communicating with an IPC instance

Once an instance is created, you can communicate with it by specifying its instance ID:

abc123|setmap{"file_path":"/Users/sfox/Desktop/halo/dune.map"}

You do not need to specify the instance ID if there is only one active instance. For example, if only one session exists, the call specified above is equivalent to calling:

setmap{"file_path":"/Users/sfox/Desktop/halo/dune.map"}

Optionally, you can specify a default instance for a given map by starting the application with the -d flag:

$ larboard -d ~/dune.map

You can change the default instance type using the -g flag:

$ larboard -d ~/dune.map -g halo2

You can output JSON in a more human readable format by specifying the -human flag:

$ larboard -human

Parsing IPC output

All output generated by the IPC API follows the Result struct:

abc123|setmap{"file_path":"/Users/sfox/Desktop/halo/dune.map"}
{"data":"","error":"","id":"abc123","message":""}

This provides a simple interface for coordinating output from different IPC instances.

Accessing larboard's interface via IPC

The primary interface provided by larboard is specified in larboard.go. The name may change, because I am bad at naming... So keep that in mind.

Method arguments will always be provided in the form of a struct that can be serialized to JSON. For example, the SetMap() method takes an argument of HaloMap, which can be found in the same source file as the interface:

type HaloMap struct {
	FilePath string `json:"file_path"`
}

Since SetMap() requires an argument, you must specify it as a JSON blob:

setmap{"file_path":"/Users/sfox/Desktop/halo/dune.map"}
{"data":"","error":"","id":"default","message":""}

This holds true for the other methods. For example, if you want to sign the map:

sign
{"data":"5cda9d4d","error":"","id":"default","message":""}

Or if you want to get the map's name:

name
{"data":"dune","error":"","id":"default","message":""}