Message Format

First you need to start the process. It receives commands via stdin and strictly outputs via stdout. Debug information and errors go through stderr.

To send a command you need the following structure:

[32 bit big endian data length + 4]
[32 bit big endian request id]
[JSON data]

You will get something back that looks like this:

[32 bit big endian data length + 4]
[32 bit big endian request id]
[JSON response]

The request id will be the same as the one that got sent in. Every request will get a response. If an exception occurs it sets "error" to true, msg will be the exception message and exception will be the full string value of the exception.

For synchronous requests it's recommended to increase the request id for every request. Otherwise random will also work. It's important to unregister for waiting for a response after receiving it as every request gets exactly one response.

To use the functionalities of workspace-d you first need to load the components.

v3 message format

The version message from v1/v2 is still the same.

Otherwise the following message types are supported: [version, load, new, config-get, config-set, call, import-paths, import-files, string-import-paths]

{
	"cmd": "new",
	"cwd": "/path/to/dir",
	("config": object)
}

The new command should be used to create a new instance of a workspace. Create a new instance for every project you wish to open. A separate component instance (and with that, resources and configuration) will be created.

{
	"cmd": "load",
	"component": <component>,
	("autoregister": bool)
}

Use the load command to load a component. Check the documentation for available components. It will automatically register onto all instances, you can change autoregister to disable this.

{
	"cmd": "config-set",
	("cwd": "/path/to/dir"),
	"config": object
}

You can use config-set to override the config of an instance or the global configuration which new instances inherit of.

{
	"cmd": "config-get",
	("cwd": "/path/to/dir")
}

This will return the current config either for an instance or the global one.

{
	"cmd": "call",
	"component": <component>,
	"method": string,
	("params": object[]),
	("cwd": "/path/to/dir")
}

The call command is used to call functions on an instance or on the global object. See the documentation for available commands per component. The parameters directly map onto the command parameters in order (as opposed to named parameters in v2).

{
	"cmd": "import-paths" OR "cmd": "import-files" OR "cmd": "string-import-paths",
	"cwd": "/path/to/dir"
}

These commands return the import paths, import file paths and string import paths respectively for a given instance.

See tc_as_a_exe in the test folder for an example implementation of a simple test case.

old (v1 and v2) messages

This section describes the old workspace-d message format (pre-v3) which used single workspaces. As v3 supports multiple workspaces, these commands will no longer work like this.

For loading dub and dcd:

{
	"cmd": "load",
	"components": ["dub", "dcd"],
	"dir": "/path/to/dir"
}

For every component there are different arguments. They also share some arguments like "dir" for the current working directory.

Some arguments are optional and some are required. In every code file for most components there is an init struct at the top of the code, where every variable with a default value is optional.

For running command from a component like dub:

{
	"cmd": "dub",
	"subcmd": "list:import"
}

This will return a JSON array of all import paths. For example:

[
	"/path/to/component/src",
	"/path/to/dir/source"
]

Before running workspace-d commands one should make sure it is the correct version using the version command.

Request:
{
	"cmd": "version"
}

Response:
{
	"major": 1,
	"minor": 0,
	"patch": 0
}

When stopping the plugin everything should be unloaded and the process should be stopped when done.

{
	"cmd": "unload",
	"components": "*"
}

Broadcast messages

Broadcast messages exist since workspace-d v2 and above.

Broadcast ID: 0x7F000000

workspace-d will send a broadcast message when starting a component with an outdated version of the program. Such a message will get sent with response/message id 0x7F000000. Such an outdated program message will look like this in the v2 protocol:

{
	"type": "outdated",
	"component": "dcd"
}

In v3 the broadcast message has an additional workspace attached to the message:

{
	"workspace": "cwd" OR null,
	"data": { /* old broadcast data */ }
}

The following broadcast types can occur:

data.type	data properties	Description
"bindfail" (Since 3.3.0)	{"component":string, "msg":string, "trace":string}	Occurs when a component failed to start when automatically attaching to a workspace. This data type has a special additional component attribute as described above.
"outdated"	{"component":string}	Sent when an external component is out of date. Currently only sent by DCD
"crash"	{"component":string}	Sent when a running async task has crashed. Currently only sent by DCD when the dcd-server closes.
"warning"	{"component":string, "detail":string}	Sent when a component wants a warning message displayed to the user. Currently sent by dub for no selected configuration.
"error"	{"component":string, "detail":string}	Sent when a component wants a error message displayed to the user. Currently sent by dub for failure in listing import paths.

Component Documentation