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":""}