xpipe-mirror/beacon/README.md

55 lines
2.7 KiB
Markdown
Raw Normal View History

2022-11-24 07:43:30 +00:00
[![Maven Central](https://maven-badges.herokuapp.com/maven-central/io.xpipe/xpipe-beacon/badge.svg)](https://maven-badges.herokuapp.com/maven-central/io.xpipe/xpipe-beacon)
[![javadoc](https://javadoc.io/badge2/io.xpipe/xpipe-beacon/javadoc.svg)](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
2023-05-20 14:23:36 +00:00
The XPipe beacon component is responsible for handling all communications between the XPipe daemon
2024-06-15 10:40:03 +00:00
and the APIs and the CLI. It provides an API that supports all kinds
of different operations.
2024-06-18 20:23:40 +00:00
For a full documentation, see the [OpenAPI spec](/../openapi.yaml)
2022-11-24 07:43:30 +00:00
### Inner Workings
2024-06-15 10:40:03 +00:00
- The underlying communication is realized through an HTTP server on port `21721`
2022-11-24 07:43:30 +00:00
- The data structures and exchange protocols are specified in the
2024-06-15 10:40:03 +00:00
[io.xpipe.beacon.api package](src/main/java/io/xpipe/beacon/api).
2022-11-24 07:43:30 +00:00
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.
2024-06-18 20:23:40 +00:00
- The body of a message is usually formatted in the json format.
2022-11-24 07:43:30 +00:00
As a result, all data structures exchanged must be serializable/deserializable with jackson.
2022-06-17 22:29:41 +00:00
## Configuration
2022-11-24 07:43:30 +00:00
#### Custom port
2024-06-18 20:23:40 +00:00
The default port can be changed by passing the property `io.xpipe.beacon.port=<port>` to the daemon.
2022-11-24 07:43:30 +00:00
Note that if both sides do not have the same port setting, they won't be able to reach each other.
#### Custom launch command
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>`.
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-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
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
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.