printIt Virtual Printer — Enhanced Simulation Engine

A deterministic simulation engine for a physical IPP/TCP printer, not just a backend server.

---

What's new

Feature	Details
Full job lifecycle	pending → processing → completed / aborted / canceled
Time-based printing	Configurable pages/second; job progress tracked per page
Live SSE updates	GET /events streams every state change in real time
Error scenarios	Paper jam, out of paper, low ink, offline, overheating, data corruption
Printer-level state	idle / processing / stopped with IPP-compliant state reasons
Queue management	FIFO with configurable concurrency (default: 1 job at a time)
Cancel mid-job	DELETE /jobs/:id cancels pending or in-flight jobs
Retry failed jobs	POST /jobs/:id/retry re-queues aborted jobs (up to retry limit)
Ink + paper levels	Ink depletes per page; paper and ink can be reloaded via API
IPP Get-Job-Attributes	Live per-job state queries now return real data

---

Architecture

              ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐
              │  TCP :9100   │  │  IPP :8631   │  │  REST+SSE :3000  │
              └──────┬───────┘  └──────┬───────┘  └────────┬─────────┘
                     │                 │                    │
                     └────────┬────────┘                   │
                              ▼                            │
                     ┌─────────────────┐                  │
                     │  PrinterEngine  │◄─────────────────┘
                     │  (EventEmitter) │
                     └────────┬────────┘
                              │ emits events
                              ▼
                     ┌─────────────────┐
                     │   Job store     │
                     │  /app/jobs/*.prn│
                     └─────────────────┘

---

Configuration (config/printer.json)

{
  "printerName":              "printIt Virtual Printer",
  "host":                     "localhost",
  "port":                     9100,
  "ippPort":                  8631,
  "saveDirectory":            "/app/jobs",
  "status":                   "ONLINE",
  "discovery":                false,
  "maxConcurrentJobs":        1,
  "printSpeedPagesPerSecond": 0.5,
  "simulateErrors":           true,
  "errorProbability":         0.08,
  "retryLimit":               3
}

• printSpeedPagesPerSecond — controls how fast printing is simulated (0.5 = 2 seconds/page)
• errorProbability — probability of an error firing on any given page (0.08 = 8% per page)
• retryLimit — maximum retries per job before permanently blocking retry

---

REST API

Printer

Method	Path	Description
GET	/status	Live printer status, ink level, queue depth
POST	/printer/clear-error	Acknowledge and clear a blocking printer error
POST	/printer/reload-paper	Simulate loading paper
POST	/printer/replace-ink	Simulate replacing ink cartridge

Jobs

Method	Path	Description
GET	/jobs	All jobs. Filter: ?state=pending|processing|completed|aborted|canceled
GET	/jobs/:id	Full job detail including page history
DELETE	/jobs/:id	Cancel a pending or in-flight job
POST	/jobs/:id/retry	Re-queue an aborted job
GET	/queue	Jobs waiting to print, in order
POST	/test-job	Submit synthetic job { "name": "...", "pages": 3 }

Live events

GET /events

Server-Sent Events stream. Events:

Event	Payload
connected	Snapshot of current status and queue
job:submitted	Job summary
job:started	Job summary
job:progress	{ jobId, page, totalPages, progress }
job:completed	Job summary
job:canceled	Job summary
job:error	{ job, error: { code, message, retriable } }
job:retried	Job summary
printer:idle	Printer status snapshot
printer:error	{ code, message, retriable }
printer:error-cleared	The cleared error object

---

Error scenarios

Code	Retriable	Requires printer clear?
paper-jam	✅	No — auto-resumes if simulateErrors picks next job
out-of-paper	✅	Yes — call POST /printer/reload-paper
low-ink	❌	Yes — call POST /printer/replace-ink
offline	✅	Yes — call POST /printer/clear-error
connection-lost	✅	No
corrupt-data	❌	No — job fails; printer stays available
overheating	✅	Yes — call POST /printer/clear-error

---

Quick start

# Build and run
docker build -t printit .
create a folder and copy its path
docker run -p 3000:3000 -p 9100:9100 -p 8631:8631 -v "<path>" printit

# Submit a test job
curl -X POST http://localhost:3000/test-job \
  -H "Content-Type: application/json" \
  -d '{"name": "My Document", "pages": 4}'

# Watch live events
curl -N http://localhost:3000/events

# Cancel a job
curl -X DELETE http://localhost:3000/jobs/<job-id>

# Retry a failed job
curl -X POST http://localhost:3000/jobs/<job-id>/retry

# Clear a blocking error
curl -X POST http://localhost:3000/printer/clear-error

---

File layout

printit/
├── config/
│   └── printer.json
├── core/
│   ├── printerEngine.js   ← simulation heart (new)
│   ├── ippServer.js       ← IPP with live engine integration (rewritten)
│   ├── tcpServer.js       ← TCP with engine integration (rewritten)
│   └── discovery.js       ← Bonjour/mDNS (unchanged)
├── server.js              ← entry point + REST API (rewritten)
├── Dockerfile
└── package.json