177 lines
3.7 KiB
Markdown
177 lines
3.7 KiB
Markdown
# luxtools-client
|
||
|
||
Small local HTTP helper that lets the Dokuwiki plugin `luxtools` open folders on the same machine.
|
||
|
||
This program runs on the user’s machine and listens on a loopback address only (defaults to `127.0.0.1:8765`). The plugin calls it to open a folder in the OS file manager.
|
||
|
||
## What it does
|
||
|
||
- Exposes `GET /health` for a simple health check.
|
||
- Exposes `GET /open?path=...` and `POST /open` to open a folder.
|
||
- Normalizes and validates the requested path:
|
||
- Accepts absolute paths only.
|
||
- If a file path is provided, it opens the containing directory.
|
||
- Accepts `file://...` URLs (handy when the caller passes a file URL).
|
||
- Optionally restricts which folders can be opened via `-allow` prefixes.
|
||
|
||
## Build
|
||
|
||
Requires Go 1.22+.
|
||
|
||
```bash
|
||
go build -o luxtools-client .
|
||
```
|
||
|
||
## Run
|
||
|
||
```bash
|
||
./luxtools-client
|
||
```
|
||
|
||
### Flags
|
||
|
||
- `-listen` (default `127.0.0.1:8765`): listen address (`host:port`). Must be loopback.
|
||
- `-allow` (repeatable): allowed path prefix. If you specify one or more, the requested path must start with one of them.
|
||
|
||
Examples:
|
||
|
||
```bash
|
||
# Listen on a different local port
|
||
./luxtools-client -listen 127.0.0.1:9000
|
||
|
||
# Restrict opens to your home directory (repeat -allow as needed)
|
||
./luxtools-client -allow "$HOME"
|
||
```
|
||
|
||
## Install as a service
|
||
|
||
The scripts below install (or update) the client as a service that starts automatically with the system.
|
||
They assume the client binary already exists in the same folder as the scripts.
|
||
|
||
### Linux (systemd)
|
||
|
||
Install / update:
|
||
|
||
```bash
|
||
./install-linux.sh
|
||
```
|
||
|
||
Optional flags:
|
||
|
||
```bash
|
||
# Change listen address (still must be loopback)
|
||
./install-linux.sh --listen 127.0.0.1:9000
|
||
|
||
# Restrict allowed folders (repeatable)
|
||
./install-linux.sh --allow "$HOME" --allow "/mnt/data"
|
||
```
|
||
|
||
Uninstall:
|
||
|
||
```bash
|
||
./uninstall-linux.sh
|
||
```
|
||
|
||
Keep config on uninstall:
|
||
|
||
```bash
|
||
./uninstall-linux.sh --keep-config
|
||
```
|
||
|
||
Notes:
|
||
|
||
- Installs to `~/.local/share/luxtools-client/luxtools-client`
|
||
- Creates a systemd *user* unit at `~/.config/systemd/user/luxtools-client.service`
|
||
- Stores config in `~/.config/luxtools-client/luxtools-client.env`
|
||
|
||
### Windows (Scheduled Task at logon)
|
||
|
||
Because this tool needs to open File Explorer (a GUI app) in the *current user session*, it should run as a per-user Scheduled Task triggered “At log on” (similar to a systemd *user* service).
|
||
|
||
Install / update:
|
||
|
||
```bat
|
||
install-windows-task.bat
|
||
```
|
||
|
||
Optional flags:
|
||
|
||
```bat
|
||
install-windows-task.bat --listen 127.0.0.1:9000
|
||
|
||
REM Restrict allowed folders (repeatable)
|
||
install-windows-task.bat --allow "%USERPROFILE%" --allow "D:\Data"
|
||
```
|
||
|
||
Uninstall:
|
||
|
||
```bat
|
||
uninstall-windows-task.bat
|
||
```
|
||
|
||
Keep config on uninstall:
|
||
|
||
```bat
|
||
uninstall-windows-task.bat --keep-config
|
||
```
|
||
|
||
Notes:
|
||
|
||
- Installs to `%LOCALAPPDATA%\luxtools-client\luxtools-client.exe`
|
||
- Stores config in `%LOCALAPPDATA%\luxtools-client\config.json`
|
||
- Re-running the install script updates the EXE in place and restarts the task.
|
||
|
||
## API
|
||
|
||
### `GET /health`
|
||
|
||
Returns JSON:
|
||
|
||
```json
|
||
{"ok": true, "time": "2026-01-05T12:34:56Z"}
|
||
```
|
||
|
||
### `POST /open`
|
||
|
||
Request body:
|
||
|
||
```json
|
||
{"path": "/absolute/path"}
|
||
```
|
||
|
||
Response:
|
||
|
||
```json
|
||
{"ok": true, "message": "opened"}
|
||
```
|
||
|
||
Example:
|
||
|
||
```bash
|
||
curl -sS -X POST \
|
||
-H 'Content-Type: application/json' \
|
||
--data '{"path":"/tmp"}' \
|
||
http://127.0.0.1:8765/open
|
||
```
|
||
|
||
### `GET /open?path=...`
|
||
|
||
For GET callers, success returns `204 No Content` (to reduce console noise in certain callers).
|
||
|
||
Example:
|
||
|
||
```bash
|
||
curl -i \
|
||
'http://127.0.0.1:8765/open?path=/tmp'
|
||
```
|
||
|
||
## OS support
|
||
|
||
- Linux: uses `xdg-open`.
|
||
- Windows: uses `explorer.exe`.
|
||
|
||
## Notes / security
|
||
|
||
- The server refuses to bind to non-loopback addresses.
|
||
- Use `-allow` to prevent opening arbitrary folders if other local processes can reach the port.
|