ServerAgent

The ServerAgent is an experimental feature that allows Pioneer scripts to make calls to an API server. Out of the box its disabled and not used by any of the stock modules. That will change once we gain experience with it.

Enabling the agent

To enable the agent, you need to edit your config.ini and set two parameters:

• EnableServerAgent=1
• ServerEndpoint=http://somewhere/api

Obviously, you'll need the URL of an API server.

Using the agent

The agent has one method:

ServerAgent.Call(method, params, successCallback, failureCallback)

The arguments are:

• method: string, name of the remote method to call
• params: (optional) arbitrary data, converted to JSON and sent to the server
• successCallback: (optional) function called on successful return from the server. Passed any data returned from the server
• failureCallback: (optional) function called on failure. Passed an error message

ServerAgent.Call() returns immediately. If there is already a call being processed, calls are queued.

Writing a server

Servers will receive a HTTP POST request against the endpoint URL like this:

POST /api/method HTTP/1.1
User-Agent: PioneerServerAgent/git.0f09618
Content-Type: application/json

{"foo":"bar"}

The `params` argument to `ServerAgent.Call()` is JSON-encoded and sent in the request body.

The server should return something like:

HTTP/1.0 200 OK
Content-Type: application/json
Content-Length: 14

{"baz":"quux"}

The result body is JSON-decoded and passed to the `successCallback`.

This style of server is trivially implemented in just about any programming language. A sample server is available at https://github.com/robn/pioneer-apiserver/blob/master/pioneer-apiserver.psgi