Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions .env.example
Original file line number Diff line number Diff line change
Expand Up @@ -19,3 +19,7 @@ PRINT_AGENT_API_SECRET="your-api-secret"

# Optional — health check server (leave empty to disable)
# PRINT_AGENT_HEALTH_ADDR=:8080

# Optional — only if the GitHub repository becomes private: read-only token used
# by `printer update` (see README, "Dépôt privé").
# PRINTER_GITHUB_TOKEN=
22 changes: 22 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
name: CI

on:
push:
branches: [main]
pull_request:

permissions:
contents: read

jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
- uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
with:
go-version-file: go.mod
- run: go vet ./...
- run: go test ./...
- run: CGO_ENABLED=0 go build -o /dev/null ./cmd/printer
- run: bash -n deploy/install.sh
68 changes: 68 additions & 0 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
name: Release

# Push a tag vX.Y.Z on main to publish a release:
# git tag -a v1.0.0 -m "v1.0.0" && git push origin v1.0.0
on:
push:
tags: ["v*"]

permissions:
contents: write

# One release at a time; never cancel a release half-published.
concurrency:
group: release
cancel-in-progress: false

jobs:
release:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
fetch-depth: 0

- name: Check the tag is a release version
run: |
if ! [[ "$GITHUB_REF_NAME" =~ ^v[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$ ]]; then
echo "::error::tag $GITHUB_REF_NAME is not vMAJOR.MINOR.PATCH"
exit 1
fi

- name: Check the tagged commit is on main
run: |
git fetch --no-tags origin main
if ! git merge-base --is-ancestor "$GITHUB_SHA" origin/main; then
echo "::error::$GITHUB_REF_NAME ($GITHUB_SHA) is not on main: tag a commit of main"
exit 1
fi

- uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
with:
go-version-file: go.mod

- name: Vet and test
run: |
go vet ./...
go test ./...

- name: Build
run: |
mkdir -p dist
for arch in amd64 arm64; do
CGO_ENABLED=0 GOOS=linux GOARCH="$arch" go build -trimpath \
-ldflags "-s -w -X main.version=${GITHUB_REF_NAME} -X main.commit=${GITHUB_SHA::7} -X main.date=$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
-o "dist/printer_linux_${arch}" ./cmd/printer
done
./dist/printer_linux_amd64 version
test "$(./dist/printer_linux_amd64 version --short)" = "$GITHUB_REF_NAME"
(cd dist && sha256sum printer_linux_* > checksums.txt && cat checksums.txt)

- name: Publish the GitHub release
env:
GH_TOKEN: ${{ github.token }}
run: |
prerelease=()
if [[ "$GITHUB_REF_NAME" == *-* ]]; then prerelease=(--prerelease); fi
gh release create "$GITHUB_REF_NAME" dist/* \
--verify-tag --title "$GITHUB_REF_NAME" --generate-notes "${prerelease[@]}"
4 changes: 4 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -2,3 +2,7 @@ venv/
.venv/
__pycache__/
*.pyc

# Local builds
/printer
/dist/
16 changes: 12 additions & 4 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,11 @@ Go-based print job distribution agent for POS systems. Polls or listens (SSE/Mer
## Commands

```bash
# Build
go build -o print-agent ./cmd/print-agent
# Build (single binary: agent + management CLI)
go build -o printer ./cmd/printer

# Install the local build on this machine (systemd user service, like a release)
./deploy/install.sh --from-source

# Run all tests
go test ./...
Expand All @@ -30,7 +33,9 @@ go test -v ./internal/agent

**Dual-mode agent**: SSE via Mercure (primary, real-time) + HTTP polling (fallback). Falls back to polling if Mercure is unavailable; polling interval widens (2s → 30s) when SSE is active.

**Entry point**: `cmd/print-agent/main.go` — CLI with subcommands (`run`, `detect`, `receipt-test`, `open-drawer`, `label`, `sticker-address`, `sticker-image`).
**Entry point**: `cmd/printer/main.go` — CLI with subcommands: the agent (`run`), printing tools (`detect`, `receipt-test`, `open-drawer`, `label`, `sticker-address`, `sticker-image`) and the management commands in `manage.go`/`update.go`/`setup.go` (`status`, `start|stop|restart`, `log`, `update`, `rollback`, `config`, `test`, `autoupdate`, `setup`, `version`). The version is injected with `-ldflags "-X main.version=vX.Y.Z"`.

**Deployment**: systemd user service `print-agent.service` running `~/.local/bin/printer run`, config `~/.config/print-agent/env`. Units, config template and label scripts are embedded in the binary (`assets.go`, root package `printagent`). Releases: `.github/workflows/release.yml` on tag `v*` publishes `printer_linux_{amd64,arm64}` + `checksums.txt`; `printer update` (`internal/selfupdate`) verifies the sha256, swaps atomically, restarts and rolls back if the service does not stay up (`internal/service`).

**Core loop** (`internal/agent/agent.go`): `Start()` runs concurrent goroutines for SSE listening, polling, heartbeat pings (30s), and printer sync (10s). Jobs are fetched via `FetchNextJob()`, dispatched, then acknowledged.

Expand All @@ -39,7 +44,10 @@ go test -v ./internal/agent
- `internal/dispatcher/` — Routes jobs to printer drivers by type. Per-printer mutexes prevent concurrent access. 3-attempt retry with exponential backoff.
- `internal/registry/` — Detects printers at `/dev/usb/*`, `/dev/lp*`, `/dev/ttyUSB*`. Tracks availability changes and syncs with server.
- `internal/receipt/` — ESC/POS receipt printer driver (native Go)
- `internal/label/` — Wraps Python scripts (`print.py`, `print_sticker.py`) for label/sticker printing via subprocess
- `internal/label/` — Wraps Python scripts (`print.py`, `print_sticker.py`) for label/sticker printing via subprocess (embedded copies extracted to `~/.cache/print-agent/scripts/` when not found next to the binary)
- `internal/envfile/` — Parses, validates and masks the systemd EnvironmentFile config
- `internal/selfupdate/` — GitHub release lookup, version comparison, checksum, atomic swap/rollback
- `internal/service/` — `systemctl --user` wrapper and post-restart health check

**Job types**: `receipt`, `put_aside`, `label`, `sticker_image`, `open_drawer`

Expand Down
Loading
Loading