2022-11-24 07:43:30 +00:00
|
|
|
[](https://maven-badges.herokuapp.com/maven-central/io.xpipe/xpipe-beacon)
|
|
|
|
|
[](https://javadoc.io/doc/io.xpipe/xpipe-beacon)
|
2022-03-10 18:38:57 +00:00
|
|
|
|
2023-05-20 14:23:36 +00:00
|
|
|
## XPipe Beacon
|
2022-03-08 22:30:13 +00:00
|
|
|
|
2023-05-20 14:23:36 +00:00
|
|
|
The XPipe beacon component is responsible for handling all communications between the XPipe daemon
|
2022-03-08 22:30:13 +00:00
|
|
|
and the various programming language APIs and the CLI. It provides an API that supports all kinds
|
|
|
|
|
of different operations.
|
|
|
|
|
|
2022-11-24 07:43:30 +00:00
|
|
|
### Inner Workings
|
2022-03-08 22:30:13 +00:00
|
|
|
|
2022-11-24 07:43:30 +00:00
|
|
|
- The underlying inter-process communication is realized through
|
2024-03-07 22:41:29 +00:00
|
|
|
TCP sockets on port `21721` on Windows and `21723` on Linux/macOS.
|
2022-03-08 22:30:13 +00:00
|
|
|
|
2022-11-24 07:43:30 +00:00
|
|
|
- The data structures and exchange protocols are specified in the
|
|
|
|
|
[io.xpipe.beacon.exchange package](src/main/java/io/xpipe/beacon/exchange).
|
|
|
|
|
|
2023-05-20 14:23:36 +00:00
|
|
|
- Every exchange is initiated from the outside by sending a request message to the XPipe daemon.
|
2022-11-24 07:43:30 +00:00
|
|
|
The daemon then always sends a response message.
|
|
|
|
|
|
|
|
|
|
- The header information of a message is formatted in the json format.
|
|
|
|
|
As a result, all data structures exchanged must be serializable/deserializable with jackson.
|
|
|
|
|
|
|
|
|
|
- Both the requests and responses can optionally include content in a body.
|
|
|
|
|
A body is initiated with two new lines (`\n`).
|
|
|
|
|
|
|
|
|
|
- The body is split into segments of max length `65536`.
|
|
|
|
|
Each segment is preceded by four bytes that specify the length of the next segment.
|
|
|
|
|
In case the next segment has a length of less than `65536` bytes, we know that the end of the body has been reached.
|
|
|
|
|
This way the socket communication can handle payloads of unknown length.
|
2022-03-08 22:30:13 +00:00
|
|
|
|
2022-06-17 22:29:41 +00:00
|
|
|
## Configuration
|
2022-03-08 22:30:13 +00:00
|
|
|
|
2022-11-24 07:43:30 +00:00
|
|
|
#### Custom port
|
|
|
|
|
|
|
|
|
|
The default port can be changed by passing the property `io.xpipe.beacon.port=<port>` to both the daemon and APIs.
|
|
|
|
|
Note that if both sides do not have the same port setting, they won't be able to reach each other.
|
|
|
|
|
|
|
|
|
|
#### Custom launch command
|
2022-03-08 22:30:13 +00:00
|
|
|
|
|
|
|
|
The beacon API also supports launching the daemon automatically in case it is not started yet.
|
2023-05-20 14:23:36 +00:00
|
|
|
By default, it launches the daemon of the local XPipe installation.
|
2022-11-24 07:43:30 +00:00
|
|
|
It is possible to pass a custom launch command with the property `io.xpipe.beacon.customDaemonCommand=<cmd>`
|
|
|
|
|
and pass arguments to it using the property `io.xpipe.beacon.daemonArgs=<args>`.
|
2022-03-08 22:30:13 +00:00
|
|
|
This allows for a custom launch behaviour in a testing/development environment.
|
2022-06-17 22:29:41 +00:00
|
|
|
Note that the `<cmd>` value has to be a single property string, which can be prone to formatting errors
|
2022-03-08 22:30:13 +00:00
|
|
|
|
2022-11-24 07:43:30 +00:00
|
|
|
#### Verbose output
|
|
|
|
|
|
|
|
|
|
By passing the property `io.xpipe.beacon.printMessages=true`, it is possible to print debug information
|
2022-03-08 22:30:13 +00:00
|
|
|
about the underlying communications.
|
2022-11-24 07:43:30 +00:00
|
|
|
In case the `io.xpipe.beacon.printDaemonOutput` property is set, the output of the daemon can also be
|
2022-03-08 22:30:13 +00:00
|
|
|
printed by passing the property `io.xpipe.beacon.debugExecOutput=true`.
|
|
|
|
|
|
2022-11-24 07:43:30 +00:00
|
|
|
#### Daemon debug mode
|
|
|
|
|
|
|
|
|
|
In case the daemon is started by the beacon, it is possible to customize in which mode the daemon will start up.
|
|
|
|
|
By passing the property `io.xpipe.beacon.launchDebugDaemon=true`, the daemon is started in debug mode,
|
|
|
|
|
i.e. will log more information and enable a few other options.
|
|
|
|
|
By passing the property `io.xpipe.beacon.attachDebuggerToDaemon=true`, it is possible to launch a daemon
|
|
|
|
|
in a mode where it is waiting to attach to a debugger first prior to starting up.
|
