PrintMaster Developer Documentation on PrintMaster Docs

Auto-Update & Installer Repackaging Plan

Mon, 01 Jan 0001 00:00:00 +0000

This document captures the agreed strategy for server- and agent-driven updates, including manifest signing, installer repackaging, and rollout choreography. It serves as a checklist we can iterate through incrementally.

Goals

Enable the PrintMaster server to self-update without user intervention (non-Docker deployments).
Allow the server to orchestrate agent updates, including fully background installations triggered from the fleet UI.
Provide customized installers (per fleet/tenant) that embed configuration data and can be used for both onboarding and update flows.
Maintain trust without external code-signing certificates by using server-signed manifests and checksum validation.
Keep Docker deployments opt-in / manual since they already rely on image pulls.

High-Level Architecture

Release Intake

Build & Release Workflow

Mon, 01 Jan 0001 00:00:00 +0000

Quick Start (Development)

Windows PowerShell Quick Launch

Use the helper script to test, build, and launch the agent:

# From project root (where dev/ exists)
pwsh -NoProfile -ExecutionPolicy Bypass .\dev\launch.ps1

This script will:

Run go test ./... (exits if tests fail)
Build agent into ./bin/printmaster-agent.exe
Start the built binary
Open browser to http://localhost:8080

Manual Development Workflow

If you prefer manual control:

# Run tests
go test ./...

# Build (from project root)
go build -o ./bin/printmaster-agent.exe ./agent

# Run the agent
./bin/printmaster-agent.exe

# Open UI
Start-Process 'http://localhost:8080'

Note: The launch script is intentionally conservative - tests must pass before build and server start.

Deprecations and Removed Features

Mon, 01 Jan 0001 00:00:00 +0000

This document tracks features that have been removed or are pending removal, with rationale and migration notes.

Removed Features

Candidate/MIB Profile Workflow

Status: ✅ Removed
When: Early 2025
What: Agent no longer loads or parses vendor candidate files or MIB profiles. All associated UI and HTTP endpoints removed.
Rationale: Simplify agent, reduce maintenance cost, avoid tight coupling to vendor-specific data files
Migration: None required. Discovery now relies on Printer-MIB and minimal vendor-agnostic heuristics
Cleanup: Any data under mib_profiles/ can be deleted safely

Sandbox Simulation

Status: ✅ Removed
What: Sandbox feature (simulate candidates against saved walks) removed
Rationale: Depended on candidates/MIB profiles; added complexity without core value
Migration: Use built-in discovery and targeted diagnostic walks

`/mib_walk` HTTP Endpoint

Status: ✅ Removed
What: On-demand MIB walk HTTP endpoint
Rationale: Encourage bounded, targeted walks inside discovery pipeline; avoid broad, ad-hoc walks
Migration: Use discovery and “Walk All” device action in UI where applicable; targeted walks occur automatically for confirmed printers

`/saved_ranges` HTTP Endpoint

Status: ✅ Removed (Replaced)
When: October 2025
What: Legacy IP ranges endpoint
Replacement: Use unified /settings endpoint (GET/POST for discovery.ranges_text)

Migration:

// Old:
fetch('/saved_ranges');

// New:
const settings = await fetch('/settings').then(r => r.json());
const ranges = settings.discovery.ranges_text;

Manual MIB Walk UI Functions

Status: ✅ Removed
Location: agent/web/app.js
Functions: runMibWalk(), runMibWalkFor(ip)
Rationale: Full device information now gathered automatically during discovery; deep scan pipeline provides comprehensive data collection
Migration: Automated scanning provides all needed data

Removed Features (Previously Pending)

Old Logging System

Status: ✅ Removed
When: December 2025
Location: Was in agent/main.go
Functions: logMsg(msg string), logMutex, logBuffer []string
Description: Simple timestamp-prefixed logging to in-memory buffer and file
Replacement: Structured logger package (common/logger/logger.go) - now used throughout codebase
Migration: Complete - all logging now uses appLogger structured logging

Deprecated (Still Supported)

`/settings/subnet_scan` HTTP Endpoint

Status: ⚠️ Deprecated (still works)
Replacement: Use /settings endpoint (GET/POST for discovery.subnet_scan)

Migration:

// Old:
fetch('/settings/subnet_scan');

// New:
const settings = await fetch('/settings').then(r => r.json());
const enabled = settings.discovery.subnet_scan;

Removal Date: v1.0 (will be removed in 1.0 release)

Migration Checklist

When removing deprecated code:

Device Report Proxy Worker

Mon, 01 Jan 0001 00:00:00 +0000

This document describes the Cloudflare Worker that handles device diagnostic reports for PrintMaster.

Overview

The proxy worker receives diagnostic reports from PrintMaster agents, creates a GitHub Gist with the full diagnostic data, and returns URLs for creating a pre-filled GitHub issue.

Endpoint

URL: https://api.printmaster.work/diagnostic
Method: POST
Content-Type: application/json

Request Format

{
 "report": {
 "report_id": "RPT-18B2A3C4D5E6-1234",
 "timestamp": "2024-01-15T10:30:00Z",
 "agent_version": "0.25.7",
 "os": "windows",
 "arch": "amd64",
 "issue_type": "wrong_manufacturer",
 "expected_value": "HP LaserJet Pro M404dn",
 "user_message": "Device shows as Unknown instead of HP",
 "device_ip": "10.0.1.50",
 "device_serial": "VNC1234567",
 "device_model": "HP LaserJet Pro M404dn",
 "device_mac": "00:11:22:33:44:55",
 "current_manufacturer": "Unknown",
 "current_model": "Unknown Printer",
 "current_serial": "VNC1234567",
 "current_hostname": "[hash:a1b2c3d4]",
 "current_page_count": 15234,
 "detected_vendor": "Unknown",
 "detection_steps": [
 "Querying sysDescr (.1.3.6.1.2.1.1.1.0)",
 "No vendor match found"
 ],
 "snmp_responses": [
 {
 "oid": ".1.3.6.1.2.1.1.1.0",
 "type": "OctetString",
 "value": "HP LaserJet Pro M404dn",
 "hex_value": ""
 }
 ],
 "recent_logs": [
 "2024-01-15T10:29:55Z [INFO] Scanning device 10.0.1.50"
 ]
 }
}

Response Format

Success (200 OK)

{
 "success": true,
 "gist_url": "https://gist.github.com/printmaster-bot/abc123def456",
 "issue_url": "https://github.com/printmaster-org/printmaster/issues/new?template=device-report.yml&title=%5BDevice+Report%5D+wrong_manufacturer+%E2%80%93+HP+LaserJet+Pro+M404dn&gist_url=https%3A%2F%2Fgist.github.com%2Fprintmaster-bot%2Fabc123def456&issue_type=Wrong+manufacturer+detection&expected_value=HP+LaserJet+Pro+M404dn&device_model=HP+LaserJet+Pro+M404dn&device_manufacturer=Unknown"
}

Error (4xx/5xx)

{
 "success": false,
 "error": "Failed to create gist: rate limit exceeded"
}

Cloudflare Worker Implementation

Create a new Cloudflare Worker with the following code:

Epson Remote-Mode Integration Plan

Mon, 01 Jan 0001 00:00:00 +0000

This document captures the concrete steps required to land Epson remote-mode support in the agent while keeping the feature isolated behind a flag and reusing the new SNMP batching helper.

Goals

Reuse the remote-mode command surface documented in docs/SNMP_RESEARCH_NOTES.md (commands di, st, ia, ii, ||).
Surface reliable ink, maintenance-box, and alert data in PrinterInfo/metrics without relying on sparse Printer-MIB leaves.
Limit SNMP chatter by batching OIDs (already covered by batchedGet) and caching EEPROM ranges per device.

Building Blocks

Batching helper (agent/scanner/snmp_batch.go): already available; use it whenever remote-mode helpers need scalar GETs.
Vendor module hook (agent/scanner/vendor/epson.go): entry point for calling the remote-mode helper from MetricOIDs/Parse whenever the feature flag is on.
Learned OID cache (agent/agent/types.go::LearnedOIDMap): add an EpsonEEPROMWindows slice so we remember which address ranges returned data.
Feature flag plumbing: add epson_remote_mode_enabled to agent config, default false, surfaced through settings UI.
Storage + downsampling: extend DeviceMetricsSnapshot to track main_waste, borderless_waste, waste_box_3 so they flow through existing downsamplers.

Implementation Steps

Remote-mode transport helper

Git & GitHub Integration - Complete ✅

Mon, 01 Jan 0001 00:00:00 +0000

What Was Added

1. Automated Release Script (`release.ps1`)

Location: c:\temp\printmaster\release.ps1

Usage:

# Patch release (bug fixes)
.\release.ps1 agent patch

# Minor release (new features)
.\release.ps1 agent minor

# Major release (breaking changes)
.\release.ps1 agent major

# Release server or both
.\release.ps1 server patch
.\release.ps1 both patch

What it does automatically:

✅ Checks if working directory is clean
✅ Bumps version in VERSION file(s)
✅ Runs all tests
✅ Builds optimized release binary
✅ Commits VERSION change
✅ Creates git tag (e.g., v0.2.0)
✅ Pushes to GitHub

Flags:

PrintMaster Test Coverage Analysis

Mon, 01 Jan 0001 00:00:00 +0000

Last Updated: December 27, 2025

This document provides a comprehensive analysis of test coverage across the PrintMaster codebase, identifying well-tested areas, gaps, and recommendations for improvement.

Executive Summary

Component	Test Files	Coverage Level	Priority for Improvement
Server Storage	20+	⭐⭐⭐⭐⭐ Excellent	Low
Agent Scanner	8	⭐⭐⭐⭐ Good	Medium
Common Libraries	12	⭐⭐⭐⭐ Good	Low
Server API/Handlers	3	⭐⭐⭐ Moderate	Medium
Agent Storage	6	⭐⭐⭐⭐ Good	Low
Reports System	3	⭐⭐⭐ Moderate	Medium
WebSocket/Proxy	2	⭐⭐⭐ Moderate	Medium
E2E Tests	3	⭐⭐ Basic	HIGH
Email Templates	0	⭐ None	HIGH
Spooler (Windows)	0	⭐ None	HIGH
Metrics Collector	0	⭐ None	HIGH
Report Scheduler	0	⭐ None	HIGH
OIDC Handlers	0	⭐ None	Medium
JS/Frontend	14	⭐⭐⭐ Moderate	Medium

1. Go Unit Tests (92 test files)

1.1 Server Package (`server/`)

✅ Excellent Coverage

File/Package	Tests	Description
`storage/*_test.go`	20+ files	Most comprehensive testing - Covers all CRUD operations, agents, devices, metrics, alerts, reports, users, sessions, tenants, settings, OIDC, dialects
`main_test.go`	30+ tests	Health endpoints, auth, heartbeat, batch uploads, token handling, device proxy parsing
`config_test.go`	Multiple	Configuration loading/parsing
`websocket_test.go`	8+ tests	WebSocket connection, heartbeat, proxy requests

Key storage tests:

PrintMaster TODO

Mon, 01 Jan 0001 00:00:00 +0000

Consolidated pending features and improvements from across the codebase.

Current Version: Agent v0.23.6, Server v0.23.6

🔴 High Priority (Pre-1.0)

USB Printer Support

Implemented via an IPP-USB HTTP proxy (Windows only) — see USB_IMPLEMENTATION.md. The earlier pure-Go SNMP-over-USB plan (gousbsnmp) was abandoned and never built.

IPP-USB proxy + web-scraped metrics (Windows)
Linux/macOS USB device enumeration + proxy support
Same metrics as network printers (page counts, toner, supplies) - USB scraping is best-effort per vendor, not at parity yet
USB printer configuration UI
USB/network printer differentiation in main devices table (currently tracked separately)

SNMPv3 Support

Security enhancement for enterprise deployments.

PROJECT STRUCTURE

Mon, 01 Jan 0001 00:00:00 +0000

Project Structure (Overview)

printmaster/
├── agent/ # Agent service and embedded UI (Go)
│ ├── main.go # Agent entrypoint
│ ├── config.go / config.toml # Agent configuration loader + sample
│ ├── agent/ # Discovery + protocol workers (mDNS, SSDP, etc.)
│ ├── scanner/ # SNMP pipeline, vendor registry, metrics extraction
│ ├── storage/ # Embedded SQLite schema + migrations
│ ├── proxy/ / supplies/ # Proxy tunnel + consumables helpers
│ ├── featureflags/ # Toggle definitions used by agent UI
│ ├── web/ # Embedded UI assets (built into the binary)
│ └── docs/ # Agent-specific reference material
├── server/ # Multi-agent server/API hub (Go)
│ ├── main.go # Server entrypoint
│ ├── config.go / config.toml # Server configuration + defaults
│ ├── websocket.go # Agent tunnel / live proxy handling
│ ├── storage/ # Server persistence + tenancy data
│ ├── authz/, logger/, tls.go # Auxiliary subsystems
│ └── web/ # Server UI + static assets
├── common/ # Shared Go modules (config, logger, snmp, util, web)
├── docs/ # Architecture + operations documentation
├── dev/ # Local developer scripts (e.g., launch.ps1)
├── scripts/ # Operational PowerShell helpers (kill, update, etc.)
├── tools/ # Standalone utilities and generators
├── tests/ # Integration / e2e test harnesses
├── static/ # Third-party front-end assets (e.g., flatpickr)
├── ui/ # Legacy UI experiments (kept for reference)
├── logs/, test-results/ # Output folders (ignored in git)
├── build.ps1 / release.ps1 # Build + release orchestration
└── README.md # High-level overview

Module Descriptions

Agent (`agent/`)

Single-binary agent that discovers printers, collects metrics, persists to SQLite, and serves the embedded UI. Key subpackages:

Range syntax and parsing rules

Mon, 01 Jan 0001 00:00:00 +0000

This file documents what the server accepts in the range editor textarea and how the ParseRangeText behavior works.

Supported formats

Single IPv4 address: e.g. 192.168.1.42
CIDR notation: e.g. 192.168.1.0/24
Full range (start-end): e.g. 192.168.1.10-192.168.1.20
Short-hand range (right side maps to last N octets):
- 192.168.1.10-20 expands to 192.168.1.10 through 192.168.1.20.
- 10-20 is interpreted relative to the default/prepended subnet only when configured in the UI as Add/Override behavior.
Last-octet wildcard: 192.168.1.x or 192.168.1.* (expands the last octet 0..255)

Behaviors and constraints

Security Architecture for Agent-Server Communication

Mon, 01 Jan 0001 00:00:00 +0000

Historical design proposal — planned, not shipped as specified. This page is retained for context and stable heading anchors, not as a description of current security guarantees or valid configuration. Its MVP/Production/Enterprise labels, code sketches, phases, quotas, retention periods, JSON/YAML examples, mTLS, request signing, certificate rotation, encrypted credential synchronization, and proxy-session isolation are proposed designs, not verified shipped behavior. Some overlapping features now exist, but that does not validate this design as a whole.

SNMP Reference Guide

Mon, 01 Jan 0001 00:00:00 +0000

This document covers SNMP discovery, Printer-MIB OIDs, vendor detection, metrics collection, and meter history tracking in PrintMaster.

Overview

PrintMaster uses SNMP (Simple Network Management Protocol) to discover and monitor network printers. The implementation follows a two-phase scan approach:

Phase 1 (Quick Probe) - Small number of SNMP GETs to quickly verify device is a printer
Phase 2 (Deep Scan) - Targeted walk for confirmed printers to gather detailed metrics

This approach keeps discovery fast on large networks while still capturing rich vendor-specific data.

SNMP Research Notes

Mon, 01 Jan 0001 00:00:00 +0000

This file captures actionable takeaways from inspecting other open-source SNMP printer discovery/management tools so we can fold the best ideas into PrintMaster without blindly copying code.

Sources Consulted

Ircama/epson_print_conf (Python) — exhaustive remote-mode OIDs plus EEPROM decoding for dozens of Epson models (epson_print_conf.py).
CUPS SNMP backend (backend/snmp.c) — hardened discovery logic with vendor-specific fallbacks (OpenPrinting/cups).

Standard OIDs We Should Poll Everywhere

These came up repeatedly in both projects and map cleanly to our existing data model:

Testing and CI guidelines

Mon, 01 Jan 0001 00:00:00 +0000

This document describes how to write fast, deterministic tests for the PrintMaster agent and server.

Test Types

PrintMaster has three levels of testing:

Unit Tests - Test individual functions/packages in isolation (agent/, server/)
Integration Tests - Test component interactions (e.g., database rotation)
End-to-End Tests - Test full agent-server communication (see tests/ directory)

For E2E test details, see ../tests/E2E_TESTING.md.

Why mocking is necessary

Network operations (ICMP, TCP connect, SNMP Get/Walk) are slow and flaky in CI. Unit tests must avoid touching the real network so they remain fast and reliable. The project uses small package-level factories and interfaces to make mocking easy.

USB Printer Support

Mon, 01 Jan 0001 00:00:00 +0000

Status: ✅ Implemented (Windows only)

Summary

USB printer support is implemented as an IPP-USB HTTP proxy, not the SNMP-over-USB approach originally planned (see “Abandoned approach” below). The agent enumerates USB printers that expose an embedded web UI over the IPP-USB interface class, then tunnels HTTP requests to that web UI over the USB bulk endpoints — the same approach used by OpenPrinting/ipp-usb.

Metrics (page counts, toner levels, etc.) are obtained by scraping the printer’s embedded web UI/XML endpoints, not by querying SNMP OIDs over USB.

WebSocket HTTP Proxy Feature

Mon, 01 Jan 0001 00:00:00 +0000

Overview

The PrintMaster system now supports proxying HTTP requests through the WebSocket connection between agents and the server. This allows you to access:

Agent web UIs from anywhere (even behind NAT/firewalls)
Device web UIs (printer admin pages) through the agent’s network connection

Transport/HTTPS claims below were checked against source snapshot 565f4c0; this is not a full protocol audit. Default standalone server access is https://localhost:9443. HTTP 9090 is the backend when BEHIND_PROXY=true and PROXY_USE_HTTPS=false, not the agent’s HTTP 8080 port.

PrintMaster Developer Documentation on PrintMaster Docs

Auto-Update & Installer Repackaging Plan

Goals

High-Level Architecture

Build & Release Workflow

Quick Start (Development)

Windows PowerShell Quick Launch

Manual Development Workflow

Deprecations and Removed Features

Removed Features

Candidate/MIB Profile Workflow

Sandbox Simulation

/mib_walk HTTP Endpoint

/saved_ranges HTTP Endpoint

Manual MIB Walk UI Functions

Removed Features (Previously Pending)

Old Logging System

Deprecated (Still Supported)

/settings/subnet_scan HTTP Endpoint

Migration Checklist

Device Report Proxy Worker

Overview

Endpoint

Request Format

Response Format

Success (200 OK)

Error (4xx/5xx)

Cloudflare Worker Implementation

Epson Remote-Mode Integration Plan

Goals

Building Blocks

Implementation Steps

Git & GitHub Integration - Complete ✅

What Was Added

1. Automated Release Script (release.ps1)

PrintMaster Test Coverage Analysis

Executive Summary

1. Go Unit Tests (92 test files)

1.1 Server Package (server/)

✅ Excellent Coverage

PrintMaster TODO

🔴 High Priority (Pre-1.0)

USB Printer Support

SNMPv3 Support

PROJECT STRUCTURE

Project Structure (Overview)

Module Descriptions

Agent (agent/)

Range syntax and parsing rules

Security Architecture for Agent-Server Communication

SNMP Reference Guide

Overview

SNMP Research Notes

Sources Consulted

Standard OIDs We Should Poll Everywhere

Testing and CI guidelines

Test Types

Why mocking is necessary

USB Printer Support

Summary

WebSocket HTTP Proxy Feature

Overview

`/mib_walk` HTTP Endpoint

`/saved_ranges` HTTP Endpoint

`/settings/subnet_scan` HTTP Endpoint

1. Automated Release Script (`release.ps1`)

1.1 Server Package (`server/`)

Agent (`agent/`)