Linker Sidecar API
Crystal Palace has a JSON-over-HTTP sidecar server to facilitate cross-language access to Crystal Palace.
Starting the Server
To start the sidecar:
./linkserve
The sidecar listens on 127.0.0.1 port 60060. You may change the port with -p port
API
The URL endpoint of the Sidecar is:
POST http://127.0.0.1:60060/link
The Sidecar accepts a POST'd JSON object for commands and arguments.
| Key | Type | Required | Description |
|---|---|---|---|
| action | string | Yes | 'link' or 'piclink' behavior |
| params | object | Yes | Parameters for our action |
| params.spec | string | Yes | Specification file |
| params.arch | string | Yes, if piclink | 'x86' or 'x64' arch target to act on |
| params.file | string | Yes, if link | full path to COFF ($OBJECT) or DLL ($DLL) to pass to .spec |
| config | array | no | An array of .spec files to run before params.spec to populate environment. Like CLI's @file.spec |
| env | object | no | Place key/values into execution environment: %key is a string. $key is a hexlified (e.g., 11223344) byte[] array. Like the CLI |
| yara | boolean | no | Generate yara rules with output |
The Sidecar output is an HTTP 200 OK with a JSON object. If the operation is successful:
| Key | Type | Description |
|---|---|---|
| success | boolean | True, if the operation was successful |
| message | string | A multi-line string with linker output. This may be empty too. |
| output_b64 | string | base64 encoded linker output. |
| yara | string | Yara rules and signatures, if requested. |
If the operation fails, the output is still HTTP 200 OK with a JSON object. But, the success value is false:
| Key | Type | Description |
|---|---|---|
| success | boolean | False, if the operation failed |
| message | string | A multi-line string with the error message |
| context | string | A hint about which part of the process/JSON input raised the error |
API JSON Examples
Arguments:
If the operation is successful:
If the operation fails:
Example Client
Below is a ./link-like client for Python3. This client requires the requests module. To install it:
pip install requests
The script (plaintext):
This project is licensed under the BSD License.
Other Notes
- The Sidecar API follows the concepts in the
linkandpiclinkCLI commands. - The Sidecar is designed for local-use only. There's no option to bind to 0.0.0.0. There is no authentication
- The Sidecar service does not produce output (outside of a catastrophic JVM failure) and it does not log
- A
GET http://127.0.0.1:60060/dieendpoint is available to ask the Sidecar to gracefully exit