From b6a333ae2d78e3b1bfd9be8ab6adc1ab38ff67ca Mon Sep 17 00:00:00 2001 From: Xevion Date: Fri, 1 Aug 2025 13:29:25 -0500 Subject: [PATCH] docs: rewrite README for current windows details, reformat --- README.md | 81 +++++++++++++++++++++++++++---------------------------- 1 file changed, 40 insertions(+), 41 deletions(-) diff --git a/README.md b/README.md index 2a3a9a2..0e25f01 100644 --- a/README.md +++ b/README.md @@ -15,68 +15,67 @@ The application follows a layered architecture: - **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. - **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. - - 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. - - 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. - - **Reload**: If not paused, pause the application, re-read configuration files, then resume. This is just a macro for pause + resume. + - **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. + - **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. + - 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. ### 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. -- 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. +- 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. 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 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. - - 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. -- 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. 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. - An internal CLI-based method that provides customized systemd unit file generation & simple management commands. ### Feature Targets -- [X] Cross-platform Background Service (Linux, Windows) +- [x] Cross-platform Background Service (Linux, Windows) - [ ] Windows - - [X] Windows Service Implementation - - [X] MSI-based Installer - - [ ] CLI-based Installer - - [ ] Winget Package Publishing + - [x] MSI-based Installer + - [ ] CLI-based Installer + - [ ] Winget Package Publishing - [ ] Linux - - [X] `systemd` Service Implementation - - [ ] CLI-based Installer - - [ ] Script-based Installer - - [ ] `systemd` Unit File Templating/Generation - - [ ] Smart `journalctl` logging bypass + - [x] `systemd` Service Implementation + - [ ] CLI-based Installer + - [ ] Script-based Installer + - [ ] `systemd` Unit File Templating/Generation + - [ ] Smart `journalctl` logging bypass - Application - - [ ] TOML Configuration - - [ ] Health Checks - - [ ] Tray Icon, Tray Menu - - [X] Structured Logging - - [ ] Configurable - - [ ] Better library (logrus, zap, zerolog, etc.) - - [ ] Testing - - [ ] Unit Tests - - [ ] Integration Tests - - [ ] Code Coverage -- [X] Development Tooling -- [X] Conventional Commits -- [X] GitHub Actions - - [X] Per-commit Artifacts - - [X] MSI Packages - - [ ] Automatic Releases (GitHub Releases, Winget) - - [ ] Testing, Linting, and/or Formatting -- [ ] README Documentation Links \ No newline at end of file + - [ ] TOML Configuration + - [x] Health Checks + - [x] Tray Icon + - [ ] Tray Menu + - [x] Structured Logging + - [ ] Configurable + - [ ] Better library (logrus, zap, zerolog, etc.) + - [ ] Testing + - [ ] Unit Tests + - [ ] Integration Tests + - [ ] Code Coverage +- [x] Development Tooling +- [x] Conventional Commits +- [x] GitHub Actions + - [x] Per-commit Artifacts + - [x] MSI Packages + - [ ] Automatic Releases (GitHub Releases, Winget) + - [ ] Testing, Linting, and/or Formatting +- [ ] README Documentation Links