xevion/HATray
1
0
Fork 0
mirror of https://github.com/Xevion/HATray.git synced 2025-12-05 23:15:09 -06:00
Code Issues Packages Projects Releases Wiki Activity

docs: rewrite README for current windows details, reformat

Browse Source
This commit is contained in:
Xevion
2025-08-01 13:29:25 -05:00
parent e252f62f52
commit b6a333ae2d
1 changed files with 40 additions and 41 deletions
Download Patch File Download Diff File Expand all files Collapse all files

81
README.md
View File

@@ -15,68 +15,67 @@ The application follows a layered architecture:
- **Command Layer**: A barebones entrypoint for the application, initializing the logger & emitting basic diagnostics. - **Command Layer**: A barebones entrypoint for the application, initializing the logger & emitting basic diagnostics.
- **Service Layer**: OS-dependent implementation that communicates with the App layer. It contains the true entrypoint for the application. - **Service Layer**: OS-dependent implementation that communicates with the App layer. It contains the true entrypoint for the application.
- **App Layer**: Generic, cross-platform implementation that exposes simple methods for controlling the application state - **App Layer**: Generic, cross-platform implementation that exposes simple methods for controlling the application state
- **Pause**: Disconnect from the server and cease any background tasks. - **Pause**: Disconnect from the server and cease any background tasks.
- Once paused, no logging occurs from the App layer, no connections are made, and no background tasks should run. - Once paused, no logging occurs from the App layer, no connections are made, and no background tasks should run.
- **Resume**: Reads configuration files, connects to the server and initiates background tasks. - **Resume**: Reads configuration files, connects to the server and initiates background tasks.
- Once running, the App layer should be connected (or attempting to reconnect) to the server. - Once running, the App layer should be connected (or attempting to reconnect) to the server.
- If an error occurs while attempting to resume or while running, the app layer will become paused. - If an error occurs while attempting to resume or while running, the app layer will become paused.
- **Reload**: If not paused, pause the application, re-read configuration files, then resume. This is just a macro for pause + resume. - **Reload**: If not paused, pause the application, re-read configuration files, then resume. This is just a macro for pause + resume.
### Windows Service Layer ### Windows Service Layer
The Windows service layer implements a legitimate Windows service that receives control signals through the Windows Service Control Manager (SCM). It uses Go project's [/x/sys/](https://pkg.go.dev/golang.org/x/sys) module (for [/x/sys/windows/svc](https://pkg.go.dev/golang.org/x/sys/windows/svc)) to interface with the SCM. The Windows service layer implements a pseudo-Windows service that mimics the behavior of a real service, but does not actually run as a service.
- In development (i.e. ran directly, or with `go run`), the service layer detects this and runs as a 'debug' service, which imitates the behavior of a real service, but does not actually run as a service. - This is required because tray icons are not supported by Windows services, as they run in the system space, and cannot interact with the user space.
- The service is fully responsive to most standard commands, including Start, Stop, Pause, Continue, and Interrogate.
For local development, you can run and build directly, or use `task service` to quickly install a service. `task package` provides a quick way to build and package the application using WiX.
Currently, I only have a MSI installer developed for Windows. I'm considering creating a specialized CLI-based installation method for Windows, one that will match the Linux experience, but that is yet to be completed. Currently, I only have a MSI installer developed for Windows. I'm considering creating a specialized CLI-based installation method for Windows, one that will match the Linux experience, but that is yet to be completed.
### Linux Service Layer ### Linux Service Layer
The Linux service layer implements a systemd service 'notify' type service. The Linux service layer implements a systemd service 'notify' type service.
- Note that we don't take advantage of most modern systemd features, such as `notify-reload`, `ReloadSignal=SIGHUP`, and so on. - Note that we don't take advantage of most modern systemd features, such as `notify-reload`, `ReloadSignal=SIGHUP`, and so on.
- This is because I use WSL2 as my primary development environment, which only has systemd v249. - This is because I use WSL2 as my primary development environment, which only has systemd v249.
- It uses the go-systemd package to interface with systemd, enabling proper handling of startup and reload signals. - It uses the go-systemd package to interface with systemd, enabling proper handling of startup and reload signals.
- The unit file is configured to send `SIGHUP` signals on reload, and will respond to `SIGHUP` (reload), and `SIGTERM` (stop). It also provides on-startup status updates, a watchdog mechanism, and a heartbeat mechanism (that updates the service status regularly). - The unit file is configured to send `SIGHUP` signals on reload, and will respond to `SIGHUP` (reload), and `SIGTERM` (stop). It also provides on-startup status updates, a watchdog mechanism, and a heartbeat mechanism (that updates the service status regularly).
Currently, the Linux service layer is only installed via the `task service` command. Currently, the Linux service layer is only installed via the `task service` command.
Ideally, I plan to provide at least two different methods for installation: Ideally, I plan to provide at least two different methods for installation:
- A one-command remote bash script that will download the binary, install the systemd unit file, and start the service. - A one-command remote bash script that will download the binary, install the systemd unit file, and start the service.
- An internal CLI-based method that provides customized systemd unit file generation & simple management commands. - An internal CLI-based method that provides customized systemd unit file generation & simple management commands.
### Feature Targets ### Feature Targets
- [X] Cross-platform Background Service (Linux, Windows) - [x] Cross-platform Background Service (Linux, Windows)
- [ ] Windows - [ ] Windows
- [X] Windows Service Implementation - [x] MSI-based Installer
- [X] MSI-based Installer - [ ] CLI-based Installer
- [ ] CLI-based Installer - [ ] Winget Package Publishing
- [ ] Winget Package Publishing
- [ ] Linux - [ ] Linux
- [X] `systemd` Service Implementation - [x] `systemd` Service Implementation
- [ ] CLI-based Installer - [ ] CLI-based Installer
- [ ] Script-based Installer - [ ] Script-based Installer
- [ ] `systemd` Unit File Templating/Generation - [ ] `systemd` Unit File Templating/Generation
- [ ] Smart `journalctl` logging bypass - [ ] Smart `journalctl` logging bypass
- Application - Application
- [ ] TOML Configuration - [ ] TOML Configuration
- [ ] Health Checks - [x] Health Checks
- [ ] Tray Icon, Tray Menu - [x] Tray Icon
- [X] Structured Logging - [ ] Tray Menu
- [ ] Configurable - [x] Structured Logging
- [ ] Better library (logrus, zap, zerolog, etc.) - [ ] Configurable
- [ ] Testing - [ ] Better library (logrus, zap, zerolog, etc.)
- [ ] Unit Tests - [ ] Testing
- [ ] Integration Tests - [ ] Unit Tests
- [ ] Code Coverage - [ ] Integration Tests
- [X] Development Tooling - [ ] Code Coverage
- [X] Conventional Commits - [x] Development Tooling
- [X] GitHub Actions - [x] Conventional Commits
- [X] Per-commit Artifacts - [x] GitHub Actions
- [X] MSI Packages - [x] Per-commit Artifacts
- [ ] Automatic Releases (GitHub Releases, Winget) - [x] MSI Packages
- [ ] Testing, Linting, and/or Formatting - [ ] Automatic Releases (GitHub Releases, Winget)
- [ ] README Documentation Links - [ ] Testing, Linting, and/or Formatting
- [ ] README Documentation Links