preprintd 0.3.2

Printer swarm-worker daemon implementation for PreConnect.
preprintd-0.3.2 is not a library.

preprintd

Printer swarm-worker daemon implementation for PreConnect.

(Codeberg Mirror)

Overview

This tiny worker is just a TcpStream under the hood, constantly listening for jobs and claiming one if open. It works by constantly listening for incoming data from the api.preconnect.app endpoint (which uses Mercure under the hood for streaming real-time data), and then initiating the claiming procedure.

Compiling

Requires Rust (2024 edition or later) to be installed.

Run the traditional release command:

cargo build --release

You can also directly install the preprintd binary globally using cargo:

cargo install preprintd

[!NOTE] The release binary is optimized for the smallest-possible size, although you can change this behavior by disabling the optimizations specified in the [profile.release] section of Cargo.toml.

Prebuilt Binaries

See the GitHub Releases for a prebuilt binary for either Windows, Linux (built via CI workers running Ubuntu), or macOS.

Daemon Usage

Create a new systemd service which you can enable later:

sudo nano /etc/systemd/system/preprintd.service

Write this INI configuration in your preprintd.service file. Make sure to replace the following fields/values:

  1. Under Environment=:
  • WORKER_KEY: Your worker key credential (from the PreConnect API).
  • AGENT: Agent name to use for outbound requests.
  • DEF_HOST: The default printer host to use in case the API cannot provide one.
  • DEF_QUEUE: The default queue name to send printable data to.
  1. Replace /usr/bin/preprintd with the appropriate path to the daemon binary.

[!WARNING] Since preprintd does not require access to user-specific paths, the User field under [Service] could be virtually any value depending on your environment.

Enable and start it once you're done:

sudo systemctl daemon-reload
sudo systemctl enable preprintd.service
sudo systemctl start preprintd.service

# now check status:
systemctl status preprintd.service

To check the logs in real-time, run:

journalctl -u preprintd.service -f

Code Inspection

When you're going through the code, you'll see these:

  • The standard LPR/LPD sequence (except the code doing HTTP requests via reqwest's blocking API and every other code surrounding/using this logic).
  • Lots of LazyLock usage. Although this is not optimal for a program that's supposed to be tiny, we've kept this pattern to reuse as much data as physically possible without hardcoding and messing up.

More specific parts of the codebase that you may be more curious about are described below:

Mercure SSE Connection Protocol

preprintd streams real-time job notifications from the Mercure Hub (/.well-known/mercure).

  1. Endpoint: https://api.preconnect.app/.well-known/mercure?topic=https%3A%2F%2Fpreconnect.app%2Fprinter
  2. Authorization: Bearer <subscriber-jwt>
    • The subscriber JWT is created by signing {"mercure":{"subscribe":["https://preconnect.app/printer"]}} with HMAC-SHA256 using WORKER_KEY.
  3. Replay Support: On reconnect, pass the Last-Event-ID header containing the last id: value received from the stream to receive any missed jobs.

Windows Inconsistencies

Although most of the instructions above are primarily made for Linux (and can be migrated over to Unix/macOS), some built-in features are not available on the Windows operating system by default. For example, the STATE_DIRECTORY environment variable set via systemd during runtime never shows up there. Moreover, some Windows-specific features might be missing from this implementation entirely, for which it is encouraged that you give the Reference Implementation a try.

Identifying Workers

While claiming a job, each worker identifies itself with an X-Worker-Ident header. It is encrypted on transit using the same HMAC-SHA256 logic as mentioned above in the protocol section, and is verified on the server.

When decrypted, it gets a pattern of <UUID>_<ARCH> (e.g. 03780793-e7af-49c1-b55d-92ff57be8c6e_aarch64-apple-darwin). The architecture in the latter part indicates the architecture of the compiled binary and not the system it's running on. The UUID is generated once and kept static for the daemon's entire lifecycle on Unix/Linux if the state directory is set properly within the daemon's service file. However, on Windows, or in environments where the state directory is unset (as partially mentioned in Windows Inconsistencies), the worker identity is dynamic, meaning that the identity would be reset for each new session. You can easily overcome this by just setting STATE_DIRECTORY to a valid absolute path on your system.

Reference Implementation

See: https://github.com/sabbirba/preconnect/blob/main/printer.py (courtesy: @sabbirba)

License

Licensed under the GNU General Public License v3.