Compare commits

...
Author SHA1 Message Date
james.maesandCodex 290948ae16 docs: record installed native printing acceptance
Co-Authored-By: Codex (GPT-6) <noreply@openai.com>
Signed-off-by: James Maes <james@kof22.com>
2026-10-31 15:23:18 -05:00
james.maes 0199391dfc Merge pull request #14 from QRun-IO/docs/published-020-20261031
docs: document the published 0.2.0 prerelease
2026-10-31 11:37:49 -05:00
james.maesandCodex 696c623b4d docs: document the published 0.2.0 prerelease
Co-Authored-By: Codex (GPT-6) <noreply@openai.com>
Signed-off-by: James Maes <james@kof22.com>
2026-10-31 11:29:13 -05:00
james.maes f6a1402f58 Merge pull request #13 from QRun-IO/docs/release-020-20261031
docs: prepare native printing 0.2.0 prerelease
2026-10-31 11:08:09 -05:00
james.maesandCodex ad53b69c0f docs: prepare native printing 0.2.0 prerelease
Co-Authored-By: Codex (GPT-6) <noreply@openai.com>
Signed-off-by: James Maes <james@kof22.com>
2026-10-31 11:06:12 -05:00
james.maes a5b2cd29a3 Merge pull request #12 from QRun-IO/feat/server-device-controls-20261031
feat: add native printing device controls and session authorization
2026-10-31 10:43:18 -05:00
james.maesandCodex 3b73808650 fix: prevent legacy downgrade of native device credentials
Reject bound device tokens on every legacy device route. Native proof verification
continues through standard QQQ sessions and current user permissions. Disable
legacy enrollment by default and explicitly in the native host; legacy-only demo
and fixtures opt in, preserving eligible unbound-device migration.

Validation: 110 Java tests pass with zero failures/errors/skips and zero Checkstyle.
Actual native-bind HTTP regressions reject bearer-only claim/content/queue/control;
legacy enrollment denial preserves the code for successful native enrollment.
Independent review found no remaining blocker. No schema or dependency changes.

Co-Authored-By: Codex (GPT-6) <noreply@openai.com>
Signed-off-by: James Maes <james@kof22.com>
2026-10-31 10:24:13 -05:00
james.maesandCodex 23fccbb326 docs: explain standard QQQ session freshness policy
Record verified RC20 behavior: OAuth2 caching defaults off and reruns supported
host authorization hooks; explicitly cached sessions require normal invalidation
or a qualified freshness policy. Table-based sessions reread user rows but do
not automatically interpret arbitrary enabled fields.

Validation: exact frozen source and a10-check synthetic reproduction. No product
code or provider/runtime configuration changes. Long-lived provider renewal and
configured native grants remain deployment qualifications.

Co-Authored-By: Codex (GPT-6) <noreply@openai.com>
Signed-off-by: James Maes <james@kof22.com>
2026-10-31 09:35:57 -05:00
james.maesandCodex 3435686e7e fix: enforce native permissions during printing selections
Wrap standard extraction with explicit current-user enforcement after callbacks,
and authorize preview counts before the standard tenant-filtered count. Apply
the wrapper to all14 printing selection processes so trusted internal defaults
cannot skip table policies before Transform/Load checks.

Validation:109 Java tests pass with zero failures/errors/skips and zero
Checkstyle. New regressions exercise count/query denial, callback weakening,
selected/filter tenant isolation and process registrations. Native API classes
remain byte-identical to the23-check real client/server interop artifact.

Co-Authored-By: Codex (GPT-6) <noreply@openai.com>
Signed-off-by: James Maes <james@kof22.com>
2026-10-31 09:18:43 -05:00
james.maesandCodex 3062fc8e84 feat: add native printing device controls and session authorization
Add record/selection actions, per-device printers/jobs/queue/history and observed
connection/control status. Persist bounded device actions and immutable receipts,
serialize queue clearing against claims, and cancel only owned Windows jobs.

Register semantic printing extension 1.0.0 with standard QQQ sessions, secondary
bound-device proof, current native table/process/record checks and explicit
permission enforcement. Preserve legacy compatibility without primary fallback.
Pin protocol cc3c4e50e8f6f4fbc93d351fb51edb4f5438bbd3 and prepare 0.2.0-rc.1.

Validation: Java21 verify passes 106 tests with zero failures/errors/skips and
zero Checkstyle. All204 runtime dependency hashes match frozen inputs. Native
HTTP/OpenAPI, authority denial, FIFO eligibility, queue races, selection replay
and offline command expiry covered; cross-runtime/provider/install acceptance
remain separate gates. Independent source review findings are corrected.

Co-Authored-By: Codex (GPT-6) <noreply@openai.com>
Signed-off-by: James Maes <james@kof22.com>
2026-10-31 08:51:53 -05:00
james.maes 3c1283c05e Merge pull request #11 from QRun-IO/docs/published-014-20261031
docs: update published printing release guidance
2026-10-31 05:18:50 -05:00
james.maesandCodex c3e37a548e docs: update published printing release guidance
Align installation examples and acceptance notes with the verified release.
Keep physical-output and production deployment qualification limits explicit.

Co-Authored-By: Codex (GPT-6) <noreply@openai.com>
Signed-off-by: James Maes <james@kof22.com>
2026-10-31 05:13:59 -05:00
james.maes 412ffbbca1 Merge pull request #10 from QRun-IO/audit/storage-retention-hardening-20261030
fix(printing): harden queue and isolate document retention
2026-10-31 04:55:21 -05:00
james.maesandCodex c34883da07 fix: use official Query mascot on diagnostic prints
Preserve the official artwork aspect ratio in every PDF and thermal profile.
Record provenance and the completed local test and installed-client acceptance.

Co-Authored-By: Codex (GPT-6) <noreply@openai.com>
Signed-off-by: James Maes <james@kof22.com>
2026-10-31 04:51:49 -05:00
james.maesandCodex 31d1bc1cab docs(printing): record verified local host deployment
Record the approved H2 exception, passing complete CI and exact artifact
comparison, verified recovery/cold-copy checks, and the state-preserving
local native QQQ cutover. Keep remote S3 and physical-output limits explicit.

Co-Authored-By: Codex (GPT-6) <noreply@openai.com>
Signed-off-by: James Maes <james@kof22.com>
2026-10-31 04:09:57 -05:00
james.maesandCodex 09e099501b fix(ci): apply approved H2 license metadata exception
Reference merged standards EX-0013 while preserving the required reviewed-version inventory guard and every other license and vulnerability check.

Co-Authored-By: Codex (GPT-6) <noreply@openai.com>
Signed-off-by: James Maes <james@kof22.com>
2026-10-31 03:40:35 -05:00
james.maesandCodex 45261d5508 fix(storage): preserve documents when S3 key layouts change
Bind external print documents to the reviewed native S3 key layout and separator. Serialize destination components as ordered JSON so valid multiline prefixes cannot collide. Refuse incompatible reads, retries and cleanup while preserving content availability and retained-byte accounting; validate new retries before upload reservation and keep existing retry receipts and inline documents compatible.

Validation: isolated Java 21 verify passes 72 tests and zero Checkstyle violations. The multiline-prefix regression fails before the fix; independent review found no remaining issue. Actual Windows-to-Linux S3 qualification returns 409 before read/retry/cleanup IO, preserves the exact object and counters, and records zero transmissions with a positive-control observer. Five documentation files pass Markdown lint. Fresh hosted checks and the existing H2 metadata approval remain pending.

Co-authored-by: Codex (GPT-6) <noreply@openai.com>
Signed-off-by: James Maes <james@kof22.com>
2026-10-30 23:09:20 -05:00
james.maesandCodex 00dd2dda2d fix(build): package license and attribution notices
Use standard Maven resources to include root LICENSE and NOTICE under META-INF while retaining existing runtime assets. No implementation or dependency changes.

Validation: isolated frontend-profile verify passes 67 tests with zero Checkstyle violations. JAR inspection verifies exact notice bytes, all 38 implementation classes unchanged, font/license/logo resources retained, and unchanged dependency declarations. Independent review found no issue.

Co-authored-by: Codex (GPT-6) <noreply@openai.com>
Signed-off-by: James Maes <james@kof22.com>
2026-10-30 21:57:39 -05:00
james.maesandCodex d1821bedf2 fix(ci): constrain reviewed H2 license scope
Require the reviewed H2 runtime in the selected Maven inventory and reject absent or different versions. Record unchanged H2 licensing and exact-artifact native cold-restart acceptance while keeping the central license exception and live deployment pending.

Validation: 11 inventory guard tests and 6 SARIF guard tests pass; workflow lint and independent review passed. Production Java remains the verified 67-test H2-fixed candidate.

Co-authored-by: Codex (GPT-6) <noreply@openai.com>
Signed-off-by: James Maes <james@kof22.com>
2026-10-30 21:49:38 -05:00
james.maesandCodex fb99fafbbf fix: use H2 with durable close-time compaction
Pin H2 2.4.240 for upstream compaction data loss. A closed legacy fixture lost newly created audit tables after reopening with 2.3.232; replacing only the driver preserves them. Add cold-reopen durability coverage and document backup/runtime qualification. Full isolated verification passes 67 tests and all 204 dependency inventories agree.

Co-authored-by: Codex (GPT-6) <noreply@openai.com>
Signed-off-by: James Maes <james@kof22.com>
2026-10-30 21:29:26 -05:00
james.maesandCodex d52dfd722b fix: consume device request bodies before queue mutations
Claim and cancel could complete before reading valid JSON, causing Jetty to close the persistent connection before a subsequent status event. Consume the bounded body after authentication. A split-body HTTP regression fails before this change; full isolated UI-profile verification passes 66 tests and Checkstyle.

Co-authored-by: Codex (GPT-6) <noreply@openai.com>
Signed-off-by: James Maes <james@kof22.com>
2026-10-30 20:55:15 -05:00
james.maesandCodex 60ce6e4f93 ci: verify the complete printing host runtime inventory
Resolve the selected UI profile once into a Maven CycloneDX graph and fail closed when Trivy or OSV omits packages or returns malformed evidence. Keep existing vulnerability and malicious-package gates.

Co-authored-by: Codex (GPT-6) <noreply@openai.com>
Signed-off-by: James Maes <james@kof22.com>
2026-10-30 20:43:47 -05:00
james.maesandCodex 78e09115cb feat: connect authenticated QQQ screens to the local printing host
Use native table authentication and scheduling with preserved paired H2 data, tenant authorization and strict browser-origin checks. Verify both H2 identifier conventions and account/session boundaries.

Co-authored-by: Codex (GPT-6) <noreply@openai.com>
Signed-off-by: James Maes <james@kof22.com>
2026-10-30 20:10:47 -05:00
james.maesandCodex aeac1a6842 fix: bound print resource admission and inventory history
Co-authored-by: Codex (GPT-6) <noreply@openai.com>
Signed-off-by: James Maes <james@kof22.com>
2026-10-30 19:37:30 -05:00
james.maesandCodex 0028bfdfdc ci: reject missing security scan evidence
Co-authored-by: Codex (GPT-6) <noreply@openai.com>
Signed-off-by: James Maes <james@kof22.com>
2026-10-30 19:11:35 -05:00
james.maesandCodex 1655d4e811 fix(printing): harden queue and isolate document retention
Co-authored-by: Codex (GPT-6) <noreply@openai.com>
Signed-off-by: James Maes <james@kof22.com>
2026-10-30 18:59:07 -05:00
james.maesandCodex 33148b94d5 docs: confirm laser and Zebra diagnostic output
Co-authored-by: Codex (GPT-6) <noreply@openai.com>
2026-10-30 18:07:13 -05:00
james.maesandCodex ff4f328781 docs: record branded diagnostic verification
Co-authored-by: Codex (GPT-6) <noreply@openai.com>
2026-10-30 17:54:54 -05:00
james.maesandCodex a6266fe2bb feat: add branded warehouse print diagnostics
Co-authored-by: Codex (GPT-6) <noreply@openai.com>
Signed-off-by: James Maes <james@kof22.com>
2026-10-30 17:42:28 -05:00
james.maesandCodex 37f2ccddcb docs: record profile and history release verification
Co-authored-by: Codex (GPT-6) <noreply@openai.com>
Signed-off-by: James Maes <james@kof22.com>
2026-10-30 16:18:17 -05:00
79 changed files with 15893 additions and 186 deletions

No files matched your search

+53
View File
@@ -0,0 +1,53 @@
"""Reject missing/malformed CodeQL evidence before enforcing the severity gate."""
import json
import math
import os
from pathlib import Path
def check(directory, language, threshold):
if not math.isfinite(threshold) or not 0 <= threshold <= 10:
raise ValueError("Invalid security severity threshold")
canonical = {"java-kotlin": "java", "javascript-typescript": "javascript", "c-cpp": "cpp"}.get(language, language)
files = sorted(Path(directory).glob("*.sarif"))
if not canonical or not any(path.name == canonical + ".sarif" for path in files):
raise ValueError("Missing expected CodeQL SARIF report for " + language)
blocking = []
for path in files:
report = json.loads(path.read_text(encoding="utf-8"))
runs = report.get("runs")
if report.get("version") != "2.1.0" or not isinstance(runs, list) or not runs:
raise ValueError("Invalid or empty SARIF runs: " + path.name)
for run in runs:
driver = run.get("tool", {}).get("driver", {})
results = run.get("results")
if driver.get("name") != "CodeQL" or not isinstance(driver.get("rules"), list) or not isinstance(results, list):
raise ValueError("Missing CodeQL tool/rules/results evidence: " + path.name)
rules = {}
for component in [driver, *run.get("tool", {}).get("extensions", [])]:
for rule in component.get("rules", []):
rules[rule["id"]] = rule
if not rules:
raise ValueError("CodeQL report has no analyzed rule metadata: " + path.name)
for invocation in run.get("invocations", []):
if invocation.get("executionSuccessful") is False:
raise ValueError("CodeQL invocation failed: " + path.name)
for result in results:
rule_id = result.get("ruleId") or result.get("rule", {}).get("id")
if rule_id not in rules:
raise ValueError("Result references missing rule metadata: " + path.name)
if result.get("suppressions"):
continue
severity = float(rules[rule_id].get("properties", {}).get("security-severity", 0) or 0)
if not math.isfinite(severity) or not 0 <= severity <= 10:
raise ValueError("Invalid rule severity: " + rule_id)
if severity >= threshold:
blocking.append((severity, rule_id))
for severity, rule_id in sorted(blocking, reverse=True):
print(f"::error title=CodeQL security finding::{rule_id} ({severity})")
print(f"Validated {len(files)} SARIF report(s); {len(blocking)} blocking result(s)")
return bool(blocking)
if __name__ == "__main__":
raise SystemExit(1 if check(os.environ["SARIF_DIR"], os.environ["EXPECTED_LANGUAGE"], float(os.environ["THRESHOLD"])) else 0)
+125
View File
@@ -0,0 +1,125 @@
"""Fail closed unless scanners cover Maven's selected UI-host runtime graph."""
import argparse
from collections import Counter
import json
from pathlib import Path
import re
from urllib.parse import unquote, urlsplit
REQUIRED = {
"com.kingsrook.qqq:qqq-frontend-next",
"com.kingsrook.qqq:qqq-backend-core",
"com.kingsrook.qqq:qqq-backend-module-filesystem",
"com.google.guava:guava",
"com.h2database:h2",
}
REVIEWED_H2_VERSION = "2.4.240"
OMITTED = object()
def resolved(text):
packages = set()
for line in text.splitlines():
line = re.sub(r"\x1b\[[0-9;]*m", "", line).strip().split(" -- ", 1)[0].strip()
if not line or line == "The following files have been resolved:":
continue
parts = line.split(":")
if len(parts) not in (5, 6) or parts[-1] not in ("compile", "runtime"):
raise ValueError(f"Unexpected Maven runtime coordinate: {line}")
if not all(parts) or parts[2] != "jar":
raise ValueError(f"Invalid runtime JAR coordinate: {line}")
name = parts[0] + ":" + parts[1]
if parts[0].startswith(("org.junit", "org.opentest4j", "org.apiguardian")):
raise ValueError("Test library in runtime inventory")
packages.add((name, parts[-2]))
if not REQUIRED.issubset({name for name, _ in packages}):
raise ValueError("Maven inventory is empty or lacks required UI-host dependencies")
# The pinned dependency-review license exception matcher ignores versions.
# Keep any H2 metadata exception limited to the reviewed, unmodified runtime.
if {version for name, version in packages if name == "com.h2database:h2"} != {REVIEWED_H2_VERSION}:
raise ValueError("H2 runtime must match reviewed version " + REVIEWED_H2_VERSION)
return packages
def components(report):
if not isinstance(report, dict) or report.get("bomFormat") != "CycloneDX":
raise ValueError("Expected CycloneDX inventory")
packages = set()
for component in report.get("components", []):
purl = urlsplit(component.get("purl", ""))
if purl.scheme != "pkg" or not purl.path.startswith("maven/"):
raise ValueError("Missing Maven package URL")
coordinate, version = purl.path.removeprefix("maven/").rsplit("@", 1)
group, artifact = coordinate.split("/", 1)
packages.add((unquote(group) + ":" + unquote(artifact), unquote(version)))
if not packages:
raise ValueError("Empty CycloneDX inventory")
return packages
def check(expected, bom, trivy=OMITTED):
actual = components(bom)
if actual != expected:
raise ValueError(f"Maven/SBOM mismatch: missing={sorted(expected - actual)}, extra={sorted(actual - expected)}")
if trivy is not OMITTED:
if not isinstance(trivy, dict) or not isinstance(trivy.get("Results"), list):
raise ValueError("Expected Trivy report object with Results array")
scanned = {(p["Name"], p["Version"]) for r in trivy.get("Results", []) for p in r.get("Packages", [])}
# Trivy also reports the root project represented by SBOM metadata.
root = bom.get("metadata", {}).get("component", {})
allowed = expected | {(root.get("group", "") + ":" + root.get("name", ""), root.get("version", ""))}
if not expected.issubset(scanned) or not scanned.issubset(allowed):
raise ValueError(f"Maven/Trivy mismatch: missing={sorted(expected - scanned)}, extra={sorted(scanned - allowed)}")
return len(expected)
def check_osv(expected, report):
if not isinstance(report, dict) or not isinstance(report.get("results"), list):
raise ValueError("Expected OSV report object with results array")
# OSV 2.6.0 queries CycloneDX purls but omits Maven groups in JSON names:
# https://github.com/google/osv-scanner/issues/3099
# Fail on ambiguous display coordinates instead of claiming full identity proof.
projected = Counter((name.split(":", 1)[1], version) for name, version in expected)
if any(count != 1 for count in projected.values()):
raise ValueError("Ambiguous Maven coordinates in pinned OSV report format")
scanned = Counter()
for result in report["results"]:
if not isinstance(result, dict) or not isinstance(result.get("source"), dict):
raise ValueError("Missing OSV source")
if result["source"].get("type") != "sbom" or not isinstance(result["source"].get("path"), str):
raise ValueError("Expected OSV SBOM source")
if not isinstance(result.get("packages"), list):
raise ValueError("Missing OSV package inventory; use --all-packages")
for entry in result["packages"]:
if not isinstance(entry, dict) or not isinstance(entry.get("package"), dict):
raise ValueError("Malformed OSV package")
package = entry["package"]
if package.get("ecosystem") != "Maven" or not all(isinstance(package.get(k), str) and package[k] for k in ("name", "version")):
raise ValueError("Invalid OSV Maven package coordinate")
if "vulnerabilities" in entry and not isinstance(entry["vulnerabilities"], list):
raise ValueError("Malformed OSV vulnerabilities")
scanned[(package["name"], package["version"])] += 1
if scanned != projected:
raise ValueError("OSV --all-packages inventory differs from selected Maven graph")
return len(expected)
def main():
parser = argparse.ArgumentParser()
parser.add_argument("resolved", type=Path)
parser.add_argument("bom", type=Path)
parser.add_argument("trivy", type=Path, nargs="?")
parser.add_argument("--osv", type=Path)
args = parser.parse_args()
expected = resolved(args.resolved.read_text(encoding="utf-8"))
count = check(expected,
json.loads(args.bom.read_text(encoding="utf-8")),
json.loads(args.trivy.read_text(encoding="utf-8")) if args.trivy else OMITTED)
if args.osv:
check_osv(expected, json.loads(args.osv.read_text(encoding="utf-8")))
print(f"Verified {count} Maven runtime dependencies, including the UI frontend.")
if __name__ == "__main__":
main()
+105
View File
@@ -0,0 +1,105 @@
"""Synthetic regressions for missing, incorrect and empty scanner inventories."""
import copy
import importlib.util
from pathlib import Path
import sys
import subprocess
import tempfile
import json
import unittest
sys.dont_write_bytecode = True
spec = importlib.util.spec_from_file_location("inventory", Path(__file__).with_name("check-maven-inventory.py"))
inventory = importlib.util.module_from_spec(spec)
spec.loader.exec_module(inventory)
class InventoryTests(unittest.TestCase):
def setUp(self):
self.expected = {(name, "2.4.240" if name == "com.h2database:h2" else "1.0") for name in inventory.REQUIRED} | {("org.jspecify:jspecify", "1.0.0")}
self.text = "The following files have been resolved:\n" + "\n".join(
f" {name}:jar:{version}:runtime\x1b[36m -- module example\x1b[m" for name, version in self.expected)
self.bom = {"bomFormat": "CycloneDX", "components": [
{"purl": "pkg:maven/" + name.replace(":", "/") + "@" + version + "?type=jar"}
for name, version in self.expected]}
self.trivy = {"Results": [{"Packages": [{"Name": n, "Version": v} for n, v in self.expected], "Vulnerabilities": []}]}
def test_complete_graph_without_findings_passes(self):
self.assertEqual(self.expected, inventory.resolved(self.text))
self.assertEqual(6, inventory.check(self.expected, self.bom, self.trivy))
def test_missing_or_unreviewed_h2_version_fails(self):
without_h2 = "\n".join(line for line in self.text.splitlines() if "com.h2database:h2:" not in line)
for text in (without_h2, self.text.replace("2.4.240", "2.3.232"), self.text.replace("2.4.240", "2.4.241"),
self.text + "\ncom.h2database:h2:jar:2.3.232:runtime"):
with self.subTest(text=text), self.assertRaises(ValueError):
inventory.resolved(text)
def test_missing_frontend_and_empty_maven_fail(self):
for text in ("", "\n".join(line for line in self.text.splitlines() if "qqq-frontend-next" not in line)):
with self.assertRaises(ValueError):
inventory.resolved(text)
def test_test_scope_or_test_jar_fails(self):
for extra in ("example:test:jar:1:test", "org.junit.jupiter:junit-jupiter:jar:5:runtime"):
with self.assertRaises(ValueError):
inventory.resolved(self.text + "\n" + extra)
def test_empty_malformed_or_missing_component_fails(self):
for bom in ({}, {"bomFormat": "CycloneDX", "components": []}, {"bomFormat": "CycloneDX", "components": [{}]},
{"bomFormat": "CycloneDX", "components": self.bom["components"][1:]}):
with self.assertRaises(ValueError):
inventory.check(self.expected, bom)
def test_wrong_selected_version_fails(self):
bad = copy.deepcopy(self.trivy)
for package in bad["Results"][0]["Packages"]:
if package["Name"] == "org.jspecify:jspecify":
package["Version"] = "1.0.1"
with self.assertRaises(ValueError):
inventory.check(self.expected, self.bom, bad)
def test_empty_or_dropped_trivy_package_fails(self):
for report in (None, {}, {"Results": []}, {"Results": [{"Packages": self.trivy["Results"][0]["Packages"][1:]}]}):
with self.assertRaises(ValueError):
inventory.check(self.expected, self.bom, report)
def test_cli_supplied_null_trivy_fails(self):
with tempfile.TemporaryDirectory() as temporary:
directory = Path(temporary)
(directory / "resolved.txt").write_text(self.text, encoding="utf-8")
(directory / "bom.json").write_text(json.dumps(self.bom), encoding="utf-8")
(directory / "trivy.json").write_text("null", encoding="utf-8")
result = subprocess.run([sys.executable, str(Path(inventory.__file__)),
str(directory / "resolved.txt"), str(directory / "bom.json"),
str(directory / "trivy.json")], capture_output=True, text=True, check=False)
self.assertNotEqual(0, result.returncode)
self.assertIn("Expected Trivy report object", result.stderr)
def osv(self):
return {"results": [{"source": {"path": "/src/printing.cdx.json", "type": "sbom"}, "packages": [
{"package": {"name": name.split(":", 1)[1], "version": version, "ecosystem": "Maven"}}
for name, version in self.expected]}]}
def test_osv_all_clean_packages_pass_without_vulnerabilities(self):
self.assertEqual(6, inventory.check_osv(self.expected, self.osv()))
def test_osv_missing_malformed_or_partial_evidence_fails(self):
partial = self.osv()
partial["results"][0]["packages"].pop()
wrong = self.osv()
wrong["results"][0]["packages"][0]["package"]["version"] = "wrong"
duplicate = self.osv()
duplicate["results"][0]["packages"].append(duplicate["results"][0]["packages"][0])
for report in (None, {}, [], {"results": None}, {"results": []}, {"results": [{}]}, partial, wrong, duplicate):
with self.subTest(report=report), self.assertRaises(ValueError):
inventory.check_osv(self.expected, report)
def test_osv_ambiguous_group_projection_fails(self):
with self.assertRaises(ValueError):
inventory.check_osv(self.expected | {("other:jspecify", "1.0.0")}, self.osv())
if __name__ == "__main__":
unittest.main()
+89
View File
@@ -0,0 +1,89 @@
"""Exercise the exact CI guards using synthetic evidence only."""
import contextlib
import copy
import io
import importlib.util
import json
from pathlib import Path
import sys
import tempfile
import unittest
sys.dont_write_bytecode = True
def load(name):
spec = importlib.util.spec_from_file_location(name, Path(__file__).with_name(name + ".py"))
module = importlib.util.module_from_spec(spec)
spec.loader.exec_module(module)
return module
codeql = load("check-codeql-sarif")
class SarifTests(unittest.TestCase):
def setUp(self):
self.temporary = tempfile.TemporaryDirectory()
self.addCleanup(self.temporary.cleanup)
self.directory = Path(self.temporary.name)
self.report = {"version": "2.1.0", "runs": [{"tool": {"driver": {"name": "CodeQL", "rules": [{"id": "synthetic", "properties": {"security-severity": "8.0"}}]}}, "results": []}]}
def save(self, report):
(self.directory / "java.sarif").write_text(json.dumps(report), encoding="utf-8")
def test_clean_report_with_zero_findings_passes(self):
self.save(self.report)
self.assertFalse(codeql.check(self.directory, "java-kotlin", 7))
def test_missing_report_or_wrong_language_fails(self):
with self.assertRaises(ValueError):
codeql.check(self.directory, "java-kotlin", 7)
self.save(self.report)
with self.assertRaises(ValueError):
codeql.check(self.directory, "csharp", 7)
def test_empty_or_malformed_report_fails(self):
for text in ["", "{", "null", "[]"]:
with self.subTest(text=text):
(self.directory / "java.sarif").write_text(text)
with self.assertRaises((ValueError, AttributeError)):
codeql.check(self.directory, "java-kotlin", 7)
def test_missing_runs_tool_rules_or_results_fails(self):
variants = [{"version": "2.1.0"}, {"version": "2.1.0", "runs": []}]
for field in ["tool", "results"]:
bad = copy.deepcopy(self.report)
del bad["runs"][0][field]
variants.append(bad)
bad = copy.deepcopy(self.report)
bad["runs"][0]["tool"]["driver"]["rules"] = []
variants.append(bad)
for bad in variants:
with self.subTest(report=bad):
self.save(bad)
with self.assertRaises(ValueError):
codeql.check(self.directory, "java-kotlin", 7)
def test_high_finding_blocks_and_unknown_rule_fails(self):
self.report["runs"][0]["results"] = [{"ruleId": "synthetic"}]
self.save(self.report)
with contextlib.redirect_stdout(io.StringIO()):
self.assertTrue(codeql.check(self.directory, "java-kotlin", 7))
self.report["runs"][0]["results"] = [{"ruleId": "missing"}]
self.save(self.report)
with self.assertRaises(ValueError):
codeql.check(self.directory, "java-kotlin", 7)
def test_failed_invocation_and_invalid_threshold_fail(self):
self.report["runs"][0]["invocations"] = [{"executionSuccessful": False}]
self.save(self.report)
with self.assertRaises(ValueError):
codeql.check(self.directory, "java-kotlin", 7)
with self.assertRaises(ValueError):
codeql.check(self.directory, "java-kotlin", float("nan"))
if __name__ == "__main__":
unittest.main()
+20 -4
View File
@@ -26,7 +26,7 @@ jobs:
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
repository: QRun-IO/qqq-print-protocol
ref: a0de93b00e602abde9be77c1ec9103b670bf3c09
ref: cc3c4e50e8f6f4fbc93d351fb51edb4f5438bbd3
path: qqq-print-protocol
persist-credentials: false
- uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5.2.0
@@ -34,7 +34,7 @@ jobs:
distribution: temurin
java-version: '21'
- name: Checkstyle, unit tests and HTTP contract tests
run: bash ./mvnw --batch-mode --no-transfer-progress verify
run: bash ./mvnw --batch-mode --no-transfer-progress -Pui-demo verify
- name: Prepare JAR, POM and checksums
shell: bash
run: |
@@ -69,21 +69,37 @@ jobs:
contents: read
security-events: write
release-codeql:
if: startsWith(github.ref, 'refs/tags/v')
uses: ./.github/workflows/codeql.yml
permissions:
contents: read
security-events: write
release:
if: startsWith(github.ref, 'refs/tags/v')
needs: [verify, release-security]
needs: [verify, release-security, release-codeql]
runs-on: ubuntu-latest
timeout-minutes: 10
permissions:
contents: write
id-token: write
attestations: write
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7.0.0
- uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
with:
name: qbit-printing-package
path: dist
- name: Verify packaged checksums
working-directory: dist
run: sha256sum --check --strict SHA256SUMS
- name: Attest verified release artifacts
uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6 # v4.2.2
with:
subject-path: dist/*
- name: Publish tested GitHub release artifacts
env:
GH_TOKEN: ${{ github.token }}
+125
View File
@@ -0,0 +1,125 @@
# Local copy of KofTwentyTwo/standards at fdf5ed029603c938615a32b1beca3628b8787945 (v0.1.2).
# Pins, inputs and analysis checks preserved; report validation now fails closed.
# Static analysis (K22-CI-22): CodeQL with the security-extended suite, failing on
# alerts of high severity or above. Called as:
#
# jobs:
# codeql:
# uses: KofTwentyTwo/standards/.github/workflows/codeql.yml@<sha> # vX.Y.Z
# permissions:
# contents: read
# security-events: write
# with:
# languages: '["csharp", "actions"]'
# build-mode: manual
# build-command: dotnet build MySolution.slnx -p:Platform=x64
# runs-on: windows-latest
#
# producing `codeql / analyze (<language>)` for each language. The CodeQL action
# uploads results but never fails a build on them, so the last step reads the SARIF
# and fails on any result whose rule has security-severity >= the threshold.
# Suppress a false positive with a query filter in a CodeQL config file passed as
# `config-file`, citing the exception record in a comment.
name: codeql
on:
workflow_call:
inputs:
languages:
description: JSON array of CodeQL languages, e.g. '["csharp","actions"]'.
type: string
required: true
build-mode:
description: CodeQL build mode for compiled languages (none, autobuild, manual). Interpreted languages always use none.
type: string
default: autobuild
build-command:
description: Command run for build-mode manual.
type: string
default: ""
runs-on:
description: Runner label; Windows-only builds (WinUI, WPF) need windows-latest.
type: string
default: ubuntu-24.04
setup-dotnet:
description: Install the .NET SDK from global.json before building.
type: boolean
default: false
config-file:
description: Optional path to a CodeQL configuration file in the calling repository.
type: string
default: ""
fail-on-security-severity:
description: Minimum CVSS-style security-severity that fails the job (7.0 = high).
type: string
default: "7.0"
permissions: {}
jobs:
analyze:
name: analyze (${{ matrix.language }})
runs-on: ${{ inputs.runs-on }}
timeout-minutes: 60
permissions:
contents: read
security-events: write # upload SARIF results to code scanning
strategy:
fail-fast: false
matrix:
language: ${{ fromJSON(inputs.languages) }}
steps:
- name: Checkout
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- name: Test scan guard rejection paths
shell: python
run: |
import runpy
runpy.run_path(".github/scripts/test-scan-gates.py", run_name="__main__")
- name: Set up .NET SDK
if: inputs.setup-dotnet
uses: actions/setup-dotnet@a98b56852c35b8e3190ac28c8c2271da59106c68 # v6.0.0
with:
global-json-file: global.json
- name: Initialize CodeQL
uses: github/codeql-action/init@24c54180a607b1449ed407dd24f251e4e9147c8d # v4.38.3
with:
languages: ${{ matrix.language }}
build-mode: ${{ contains(fromJSON('["actions","javascript-typescript","python","ruby"]'), matrix.language) && 'none' || inputs.build-mode }}
queries: security-extended
config-file: ${{ inputs.config-file }}
- name: Build (manual mode)
if: inputs.build-mode == 'manual' && !contains(fromJSON('["actions","javascript-typescript","python","ruby"]'), matrix.language)
shell: bash
env:
BUILD_COMMAND: ${{ inputs.build-command }}
run: |
if [[ -z "$BUILD_COMMAND" ]]; then
echo "::error::build-mode is manual but build-command is empty"
exit 1
fi
eval "$BUILD_COMMAND"
- name: Analyze
uses: github/codeql-action/analyze@24c54180a607b1449ed407dd24f251e4e9147c8d # v4.38.3
with:
category: /language:${{ matrix.language }}
output: codeql-sarif
# Fork pull requests have a read-only token; analyze still runs and gates.
upload: ${{ (github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name != github.repository) && 'never' || 'always' }}
- name: Gate on security severity
shell: python
env:
SARIF_DIR: codeql-sarif
THRESHOLD: ${{ inputs.fail-on-security-severity }}
EXPECTED_LANGUAGE: ${{ matrix.language }}
run: |
import runpy
runpy.run_path(".github/scripts/check-codeql-sarif.py", run_name="__main__")
+3 -2
View File
@@ -5,13 +5,14 @@ on:
branches: [main]
schedule:
- cron: '41 6 * * 1'
workflow_call:
permissions: {}
jobs:
codeql:
uses: KofTwentyTwo/standards/.github/workflows/codeql.yml@fdf5ed029603c938615a32b1beca3628b8787945 # v0.1.2
uses: ./.github/workflows/codeql-analysis.yml
permissions:
contents: read
security-events: write
with:
languages: '["java-kotlin", "actions"]'
build-mode: none
build-mode: none
+25
View File
@@ -0,0 +1,25 @@
# Pull request gates (K22-CI-01): Conventional Commit title, DCO sign-off, and
# dependency review, from the shared KofTwentyTwo/standards workflow pinned by SHA
# (K22-CI-11). Dependabot's github-actions ecosystem keeps the pin current.
name: pr-gates
on:
pull_request:
permissions: {}
concurrency:
group: pr-gates-${{ github.event.pull_request.number }}
cancel-in-progress: true
jobs:
pr:
uses: KofTwentyTwo/standards/.github/workflows/pr.yml@fdf5ed029603c938615a32b1beca3628b8787945 # v0.1.2
with:
# EX-0013: reviewed unmodified H2 2.4.240; docs/H2-LICENSE-REVIEW.md.
# The required SCA inventory guard enforces the reviewed version because
# dependency-review's package license matcher ignores PURL versions.
allow-dependencies-licenses: pkg:maven/com.h2database/h2
permissions:
contents: read # read the commits being merged
pull-requests: read # read the pull request title and dependency diff
+36 -17
View File
@@ -1,7 +1,7 @@
# Local copy of KofTwentyTwo/standards security.yml at
# fdf5ed029603c938615a32b1beca3628b8787945 (v0.1.2).
# Scanner pins and security gates are preserved. SCA alone resolves Maven POMs
# first and mounts that fresh local repository read-only into pinned Trivy.
# Scanner pins and security gates are preserved. SCA scans Maven-selected runtime
# coordinates with ui-demo enabled; independent POM resolution can choose different versions.
name: security
on:
@@ -59,16 +59,25 @@ jobs:
with:
persist-credentials: false
# Fresh Maven resolution supplies transitive POMs before Trivy scans. This
# avoids Maven Central throttling from the scanner's concurrent resolver.
# Resolve the actual deployed profile, including frontend assets.
# Do not restore an Actions cache in this security job.
- name: Set up Java
uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5.2.0
with:
distribution: temurin
java-version: '21'
- name: Resolve Maven dependencies
run: bash ./mvnw --batch-mode --no-transfer-progress dependency:resolve
- name: Test inventory guards
run: python3 .github/scripts/test-maven-inventory.py
- name: Resolve selected runtime graph and SBOM
run: |
set -euo pipefail
bash ./mvnw --batch-mode --no-transfer-progress -Pui-demo \
dependency:list -DincludeScope=runtime -DoutputFile=target/runtime-dependencies.txt \
org.cyclonedx:cyclonedx-maven-plugin:2.9.1:makeBom \
-DincludeCompileScope=true -DincludeRuntimeScope=true \
-DincludeProvidedScope=false -DincludeSystemScope=false -DincludeTestScope=false \
-DoutputFormat=json -DoutputName=printing-runtime -Dcyclonedx.skipAttach=true
python3 .github/scripts/check-maven-inventory.py target/runtime-dependencies.txt target/printing-runtime.json
# SARIF for code scanning carries MEDIUM and above for visibility; the gate
# below fails only on the configured severities (HIGH and CRITICAL by default).
@@ -77,18 +86,15 @@ jobs:
TRIVY_IMAGE: ghcr.io/aquasecurity/trivy:0.75.0@sha256:af6acf9a6b85dfe389a1941505c0ce9efef52a4719635e1a962f022a3d855daa
run: |
set -euo pipefail
docker run --rm -v "$PWD:/src" -e HOME=/root -v "$HOME/.m2/repository:/root/.m2/repository:ro" "$TRIVY_IMAGE" \
fs --scanners vuln --severity MEDIUM,HIGH,CRITICAL \
--cache-dir /src/.trivycache --skip-dirs .trivycache \
--list-all-pkgs --format json --output /src/trivy.json --exit-code 0 /src
# Fail closed if Maven analysis did not include the actual dependency graph.
jq -e 'any(.Results[]?.Packages[]?; .Name == "com.kingsrook.qqq:qqq-backend-core") and
any(.Results[]?.Packages[]?; .Name == "com.google.guava:guava")' trivy.json > /dev/null
docker run --rm -v "$PWD:/src" "$TRIVY_IMAGE" \
sbom --scanners vuln --severity MEDIUM,HIGH,CRITICAL \
--cache-dir /src/.trivycache --list-all-pkgs --format json \
--output /src/trivy.json --exit-code 0 /src/target/printing-runtime.json
python3 .github/scripts/check-maven-inventory.py target/runtime-dependencies.txt target/printing-runtime.json trivy.json
docker run --rm -v "$PWD:/src" "$TRIVY_IMAGE" \
convert --format sarif --output /src/trivy.sarif /src/trivy.json
docker run --rm -v "$PWD:/src" "$TRIVY_IMAGE" \
convert --format cyclonedx --output /src/printing.cdx.json /src/trivy.json
jq -e '.components | length > 0' printing.cdx.json > /dev/null
# OSV reads the identical verified Maven graph, without another resolver.
cp target/printing-runtime.json printing.cdx.json
- name: Upload SARIF to code scanning
# Fork pull requests get a read-only token, so only same-repository runs upload.
@@ -109,12 +115,13 @@ jobs:
run: |
set -euo pipefail
status=0
docker run --rm -v "$PWD:/src:ro" "$OSV_IMAGE" scan source --lockfile /src/printing.cdx.json --format json > osv.json || status=$?
docker run --rm -v "$PWD:/src:ro" "$OSV_IMAGE" scan source --lockfile /src/printing.cdx.json --all-packages --format json > osv.json || status=$?
# 0: nothing found, 1: vulnerabilities found. Other statuses fail closed.
case "$status" in
0|1) ;;
*) echo "::error title=OSV-Scanner failed::exit code $status"; exit 1 ;;
esac
python3 .github/scripts/check-maven-inventory.py target/runtime-dependencies.txt target/printing-runtime.json trivy.json --osv osv.json
malicious=$(jq -r '
[ .results[]?.packages[]?
| .package as $p
@@ -138,6 +145,18 @@ jobs:
docker run --rm -v "$PWD:/src:ro" "$TRIVY_IMAGE" \
convert --severity HIGH,CRITICAL --format table --exit-code 1 /src/trivy.json
- name: Retain dependency scan evidence
if: always()
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
name: maven-runtime-security-inventory
path: |
target/runtime-dependencies.txt
target/printing-runtime.json
trivy.json
osv.json
if-no-files-found: error
workflows:
name: security / workflows
runs-on: ubuntu-24.04
+47
View File
@@ -1,5 +1,52 @@
# Changelog
## 0.2.0-rc.1 — 2026-10-31
- Add native device/table selection actions for pause, resume, disconnect,
reconnect, revocation, inventory refresh and queued-job clearing, plus exact
owned Windows-job cancellation and bounded command history.
- Show device presence, desired versus applied control state, related printers,
jobs and queue; include connection/control issues in the printing dashboard.
- Register semantic printing extension `1.0.0` at `/qqq/v1/qbit/printing`, using
standard QQQ user sessions and secondary device proof with current native
record/process permissions. Legacy bearer transport remains explicit compatibility.
- Preserve journal/history and distinguish accepted commands from confirmed
execution. Shared-core/provider native authentication acceptance and installed
candidate qualification remain required before deployment claims.
- Explicitly enforce current native permissions during selection counts and
extraction, including callbacks and query selections. Pass 110 Java tests and
25 real .NET client/native QQQ interoperability checks without print jobs,
including rejection of legacy enrollment and bound-token downgrade attempts.
- Reject account-bound device tokens on legacy routes and disable legacy
enrollment by default. Legacy-only hosts opt in explicitly; existing unbound
devices retain migration compatibility.
## 0.1.4-rc.1 — 2026-10-31
- Use the official Query dog mascot on every built-in PDF and ZPL diagnostic profile, preserving the original artwork and aspect ratio. Full local and hosted gates pass 73 tests with zero Checkstyle violations; PDF previews and reconstructed thermal graphics pass visual review. Local native deployment is accepted; physical output from the updated Query diagnostics remains unconfirmed.
- Add an authenticated loopback QQQ host that shares durable paired devices/jobs with native screens and retention scheduling, preserving the separate synthetic UI demo.
- Make native enrollment and test-print execution replay-safe and retain known duplicate-output risk after later failures.
- Strictly validate print options, inventory formats/status and event bounds before persistence; recheck current queue format support at claim time.
- Add dedicated S3 document storage through the host's QQQ storage API, tenant object namespaces and immutable destination/reference checks.
- Bind S3 documents to the reviewed native key layout and platform separator using unambiguous ordered identity components, including multiline base paths; reject incompatible or old experimental bindings before historical object access and preserve cleanup accounting. Validate new retry sources before reserving uploads while retaining replay and inline database compatibility. Portable upstream keys and historical-object migration remain separate work.
- Add admin retention settings with a 365-day default, reviewed cleanup and bounded scheduled maintenance; preserve job history and uncertain work.
- Use named facility choices during enrollment and revalidate them under the current user's tenant/record permissions.
- Require release security/CodeQL gates, verified artifact promotion and build provenance; report the real packaged QBit version.
- Enforce configurable atomic queue/storage/rate budgets and cumulative printer limits, with bounded management pagination and stable replay at capacity.
- Consume bounded claim/cancel request bodies before mutation so a persistent HTTP connection remains usable for the subsequent status event.
- Pin H2 2.4.240 to fix close-time compaction data loss; verify file-backed schema/settings across cold reopens and document closed-backup upgrade qualification.
- Verify the exact frontend-inclusive runtime inventory in Maven, Trivy and OSV; fail on malformed or incomplete scanner evidence.
- Include repository LICENSE and NOTICE under META-INF using standard Maven resources; preserve font license, provenance and diagnostic assets.
- The S3 safeguard checkpoint passed 72 tests with zero failures/errors/skips and Checkstyle violations, including incompatible S3 bindings, multiline prefix retargeting, retry accounting and inline document compatibility. Actual cross-platform refusal preserves objects and accounting with zero SDK requests. Required build/security/CodeQL/dependency gates pass with the approved scoped H2 record. Qualified artifacts passed isolated graceful/cold-restart checks and local paired-host acceptance with native authentication, preserved records, automatic connector reconnection and 365-day retention. No live S3 migration or remote deployment is claimed.
- Publish the JAR, POM and SHA256SUMS after [release run 41190650664](https://github.com/QRun-IO/qbit-printing/actions/runs/41190650664) passed all gates. Verify checksums and GitHub attestations for all three assets against the release tag and source; all packaged entry contents match the reviewed Query CI artifact.
## 0.1.3-rc.1 — 2026-10-30
- Shared QQQ-branded warehouse test pages and labels across native record/table actions and device requests.
- Bundle licensed JetBrains Mono Bold; embed PDF glyphs and use bounded ZPL graphics for consistent identifier readability.
- Add Letter/A4 and 4 × 6 profile options with explicit 203/300/600-dpi label resolution, compatible defaults and validation.
- Add font/media, deterministic generation, ZPL bitmap reconstruction and operator action regression coverage.
## 0.1.2-rc.1 — 2026-10-30
- Synchronize client-managed device/printer display names, descriptions and locations; preserve physical computer/queue names and stable identifiers.
+13
View File
@@ -4,3 +4,16 @@ Copyright 2026 Kingsrook, LLC
This product contains QQQ 4.1+ printing metadata, queue services,
device transport routes, demonstration hosts and compatibility tests.
Licensed under the Apache License, Version 2.0.
Built-in diagnostic documents bundle JetBrains Mono Bold v2.304.
Copyright 2020 The JetBrains Mono Project Authors.
The font is licensed under the SIL Open Font License, Version 1.1;
see src/main/resources/com/kingsrook/qbits/printing/fonts/OFL.txt.
Query, the QQQ and QRun.IO dog mascot, is supplied by QRun.IO.
Artwork provenance: src/main/resources/com/kingsrook/qbits/printing/images/README.md.
The local host runtime uses the unmodified H2 Database Engine, Copyright
2004-2025 H2 Group. H2 is dual licensed under MPL 2.0 or EPL 1.0; this
runtime uses the MPL 2.0 option. H2 is provided without warranty.
License: https://github.com/h2database/h2database/blob/version-2.4.240/LICENSE.txt
Corresponding source: https://github.com/h2database/h2database/tree/version-2.4.240
+42 -12
View File
@@ -2,10 +2,12 @@
Cloud printing for QQQ 4.1+, paired with the [Windows AppKit connector](https://github.com/QRun-IO/qqq-print-agent) and the [shared protocol](https://github.com/QRun-IO/qqq-print-protocol). The Windows connector initiates outbound HTTPS polling; the cloud needs no inbound route into the facility.
**0.1.0-rc.1 is an initial prerelease**, tested against QQQ **4.1.0-RC.20** and Java 21. The optional native UI demo uses QQQ frontend **1.0.0-RC.37**. GitHub releases provide a library JAR, POM and SHA-256 checksums. This repository does not claim Maven Central publication or provide a standalone executable/fat JAR.
**Prerelease software**, tested against QQQ **4.1.0-RC.20** and Java 21. The current published release is [**0.2.0-rc.1**](https://github.com/QRun-IO/qbit-printing/releases/tag/v0.2.0-rc.1). The tagged build passed 110 tests and zero Checkstyle violations. The optional native UI demo uses QQQ frontend **1.0.0-RC.37**. GitHub releases provide a library JAR, POM and SHA-256 checksums, with verified build attestations for all three assets. This repository does not claim Maven Central publication or provide a standalone executable/fat JAR.
Implemented: single-use enrollment, device credentials, inventory/approval, PDF/ZPL submission, durable JDBC queue, idempotency, claim/content/events, native QQQ setup/test-print processes, read-only device/printer/job tables and a durable enqueue effect target.
The 0.2.0-rc.1 source adds native record/selection actions, per-device printers/jobs/queue/history, desired versus observed status and standard-session authentication at the discovered `/qqq/v1/qbit/printing` extension. Device credentials become secondary identity proof alongside the current QQQ user's permissions. Upgrade the server before the 0.2.0 Windows client, then explicitly associate an existing unbound pairing during sign-in. These changes are included in the published release above. See the [authentication contract](https://github.com/QRun-IO/qqq-print-protocol/blob/main/docs/QQQ-AUTHENTICATION.md); bound devices cannot fall back to legacy `/printing/v1` authentication.
```mermaid
flowchart LR
A[QQQ application / durable job] --> B[Printing QBit and JDBC queue]
@@ -14,22 +16,24 @@ flowchart LR
D --> E[Local laser / Zebra]
```
See the [screen walkthrough](docs/UI-WALKTHROUGH.md), [operations and troubleshooting](docs/OPERATIONS.md), [contributing](CONTRIBUTING.md), [security reporting](SECURITY.md), [changelog](CHANGELOG.md), and [Apache-2.0 license](LICENSE).
See the [screen walkthrough](docs/UI-WALKTHROUGH.md), [storage and retention](docs/STORAGE-AND-RETENTION.md), [operations and troubleshooting](docs/OPERATIONS.md), [contributing](CONTRIBUTING.md), [security reporting](SECURITY.md), [changelog](CHANGELOG.md), and [Apache-2.0 license](LICENSE).
## Build and verify
Install Java 21. Clone this repository and `qqq-print-protocol` as siblings. CI pins protocol commit `f977bd01b62ceb7539190fd2861809537fcf504c`; use that commit for reproducible compatibility tests. Use the checked-in wrapper (Maven 3.9.11).
Install Java 21. Clone this repository and `qqq-print-protocol` as siblings. This source pins protocol commit `cc3c4e50e8f6f4fbc93d351fb51edb4f5438bbd3`; use that commit for reproducible compatibility tests. Use the checked-in wrapper (Maven 3.9.11).
```powershell
.\mvnw.cmd verify
.\mvnw.cmd dependency:build-classpath '-Dmdep.outputFile=target/runtime-classpath.txt' '-Dmdep.includeScope=runtime'
.\mvnw.cmd dependency:build-classpath '-Dmdep.outputFile=target/runtime-classpath.txt' '-DincludeScope=runtime'
```
On Linux/macOS use `bash ./mvnw verify` and the corresponding wrapper commands. First builds download dependencies; `-o` is only appropriate after they are cached.
Checkstyle runs during validate. Tests exercise real H2 persistence, native QQQ metadata/processes and real loopback HTTP through Javalin, including the shared fixtures and withdrawal of a locally exposed printer. Keep `../qqq-print-protocol` checked out or pass `-Dprinting.protocol.fixtures=<fixture-directory>`.
## Local server
## Legacy protocol demo
The new Windows client needs the [authenticated local application](#authenticated-local-application) below, or a QQQ application hosting the native printing extension. This protocol-only demo is for explicitly enabled legacy diagnostics; it does not provide native user sign-in.
Set `QQQ_PRINT_ADMIN_TOKEN` to a random value of at least 24 characters in the process environment; never put it in source or command arguments. Then:
@@ -43,22 +47,32 @@ For a directly managed Java process, classpath is `target/classes;` followed by
## Native QQQ UI preview
A separate local demo serves the real QQQ frontend with synthetic device/printer/job records. It binds only to `127.0.0.1:18082`, uses mock authentication and registers no device transport routes, so its synthetic jobs cannot be claimed by a physical connector.
A separate local demo serves the real QQQ frontend with synthetic device/printer/job records. It binds only to `127.0.0.1:18082` and uses mock authentication. Keep it isolated from real pairing data and physical connectors; it is a screen preview, not an authenticated deployment.
```powershell
.\mvnw.cmd -Pui-demo package dependency:build-classpath '-Dmdep.outputFile=target/ui-classpath.txt' '-Dmdep.includeScope=runtime'
.\mvnw.cmd -Pui-demo package dependency:build-classpath '-Dmdep.outputFile=target/ui-classpath.txt' '-DincludeScope=runtime'
$uiClasspath = 'target/classes;' + (Get-Content target/ui-classpath.txt -Raw).Trim()
java -cp $uiClasspath com.kingsrook.qbits.printing.PrintingUiDemo
```
Open `http://127.0.0.1:18082`. On Linux/macOS use `:` as the classpath separator. Set JVM property `-Dprinting.ui.port=<port>` before the main class to choose another port. This preview is distinct from the credential-protected protocol demo on port 18081; neither replaces deployment-specific authentication and authorization.
## Authenticated local application
`PrintingLocalHost` combines the real QQQ dashboard, native processes, authenticated sign-in and device routes against one durable H2 database. It binds only to loopback, uses QQQ table-based authentication, and starts the native Quartz retention schedule through `QApplicationLauncher`. Existing pairing and job history are retained when the database and tenant are preserved. Use the pinned H2 2.4.240 runtime; older 2.3.232 file-backed deployments require a closed backup and cold-reopen qualification. See [local host setup](docs/LOCAL-HOST.md) for explicit credentials, the required frontend/runtime dependencies and a reviewed cutover procedure.
The protocol-only `PrintingDemo` and synthetic, mock-authenticated `PrintingUiDemo` remain separate. Do not point the synthetic demo at real paired printer data. The local host retains database document storage until an actual dedicated S3 binding is configured in a deployment-owned application; it does not claim a remote cloud deployment.
Local native deployment of 0.2.0-rc.1 is accepted with authentication and access-denial checks, preserved pairing/history, connector reconnection and 365-day retention. The exact published Windows MSI is installed; standard QQQ table-based sign-in and explicit existing-pairing association succeeded. Both endpoints observed pause, disconnect, reconnect and resume, and inventory refresh returned `SUCCEEDED` / `INVENTORY_REFRESHED`. Native QQQ processes delivered a Letter PDF and a 4 × 6-inch, 300-dpi ZPL label to `SPOOLED` with the reviewed content hashes. Physical confirmation of these two outputs is pending.
The release passed 25 real client/native QQQ interoperability checks. Current Windows visual UI acceptance remains unverified, and a requested service restart was canceled before execution. Configured Authentik/provider renewal, production S3/IAM, remote deployment and 1.0 readiness remain separate qualification work. See the [installed-client acceptance scope](https://github.com/QRun-IO/qqq-print-agent/blob/main/docs/ACCEPTANCE.md). The historical 0.1.4-rc.1 release passed 73 tests and zero Checkstyle violations; the user confirmed all three of its Query diagnostic outputs good.
## Add to a QQQ application
For a source checkout, `mvnw.cmd install` (or `bash ./mvnw install`) installs the verified library into your local Maven repository. For a GitHub release, download the JAR, matching POM and `SHA256SUMS`, verify the checksums, then install those artifacts locally or through your organization's artifact repository. Example using the release files in the current directory:
```powershell
.\mvnw.cmd install:install-file '-Dfile=qbit-printing-0.1.0-rc.1.jar' '-DpomFile=qbit-printing-0.1.0-rc.1.pom'
.\mvnw.cmd install:install-file '-Dfile=qbit-printing-0.2.0-rc.1.jar' '-DpomFile=qbit-printing-0.2.0-rc.1.pom'
```
After the artifact is available in your configured repository, add:
@@ -67,7 +81,7 @@ After the artifact is available in your configured repository, add:
<dependency>
<groupId>com.kingsrook.qbits</groupId>
<artifactId>qbit-printing</artifactId>
<version>0.1.0-rc.1</version>
<version>0.2.0-rc.1</version>
</dependency>
```
@@ -77,23 +91,31 @@ Device and printer names, descriptions and locations are edited in the Windows c
`initialize()` adds profile columns, backfills physical names, widens existing name/title columns and creates dispatch/history indexes without deleting records. The existing `name` column becomes the effective display label; `computer_name`/`queue_name` retain technical names and `display_name` holds the optional override. Back up the database and run schema initialization during a maintenance/deployment window; column widening and index creation can lock populated tables.
Job history uses `GET /printing/v1/admin/jobs?limit=200&before=<nextCursor>` with opaque keyset cursors and a maximum 200 rows per page. Claims read one candidate, pending inspection reads 50, and all these queries project metadata without fetching stored documents. Native dashboard lists already cap attention rows at 10 per category and recent work at 25. Dispatch/history indexes support growing histories; the synthetic 10,000-row regression test checks bounded pages and claim correctness, **not** a certified 10,000-print/day throughput measurement. Driver speed, document size, database hardware and retention policy still determine capacity. Documents remain stored until the host supplies a retention policy; this change does not silently delete jobs or documents.
Job history uses `GET /printing/v1/admin/jobs?limit=200&before=<nextCursor>` with opaque keyset cursors and a maximum 200 rows per page. Claims read one candidate, pending inspection reads 50, and all these queries project metadata without fetching stored documents. Native dashboard lists already cap attention rows at 10 per category and recent work at 25. Dispatch/history indexes support growing histories; the synthetic 10,000-row regression test checks bounded pages and claim correctness, **not** a certified 10,000-print/day throughput measurement. Driver speed, document size, database hardware and retention policy still determine capacity. Document cleanup follows the configured retention policy and host schedule; the audit does not run a live purge or delete job history.
```java
PrintingService printing = new PrintingService(dataSource, tenantId);
printing.initialize();
new PrintingQBitProducer().withConfig(new PrintingQBitConfig()
.withBackendName("appRdbms")
.withStorageTableName("printing_documents") // existing dedicated S3 storage table
.withSchedulerName("appScheduler") // existing host scheduler
.withService(printing)).produce(qInstance, "printing");
server.addRouteProvider(new PrintingRoutes(printing, context -> hostPrintingAdminGuard(context)));
server.withAdditionalRouteProviders(List.of(new PrintingRoutes(printing, context -> hostPrintingAdminGuard(context))));
```
`hostPrintingAdminGuard` is the host's own authenticated administrator policy, not a supplied library method. The service is bound to one tenant; use a separate host service instance for each tenant. Device token verification and job ownership are enforced on every device operation. Management service methods are intended for trusted application code; enforce user/facility authorization before calling them.
The storage/scheduler options above are included in 0.1.4-rc.1. Configure a dedicated private printing bucket for the customer/environment through existing QQQ S3 metadata; no bucket credentials belong in printing forms. Admin retention defaults to 365 days after successful completion. Scheduled cleanup handles bounded batches every five minutes and preserves active, failed and uncertain work plus all receipts/history. Without a configured storage binding, legacy database documents remain supported; without a host scheduler, automatic cleanup does not run. Review [storage configuration, bucket isolation and S3 versioning](docs/STORAGE-AND-RETENTION.md) before deployment.
Enrollment uses a named facility selector. Set `withFacilityPossibleValueSourceName("your_existing_facility_source")` to reuse an already registered host source and its record security. Without it, the standalone choice is **Default facility**. The backend validates the selection under the current user's permissions before issuing an enrollment code; typing or forging an unknown/foreign-tenant ID cannot bypass that check. Existing stored facility IDs are preserved; configure their original source to resolve their names.
For native QQQ screens, grant `printing_admin` and populate the session's `printing_tenant` security key with the tenant ID. The Printing home shows device health, queue status and work needing attention, with Devices, Printers and Print jobs beneath it. It nests under an existing `admin` app when available. Processes are dashboard/table/record actions, not navigation entries. Secret/token and document columns are excluded from metadata. Table mutations are rejected; use the service/processes instead.
Typical setup: run **Enroll a print device** from Printing home or Print devices, enroll the Windows connector, and select local queues to expose in its companion/tray. Use **Set printer approval** to choose a named device and one of its printers. Test-print forms offer only exposed, approved printers supporting the chosen format. Device and printer choices respect the current user's tenant access.
For label printers, configure the machine's **Windows Printing Defaults** for the actual stock size and print method before testing PDFs through the service. A test profile selects document size and ZPL resolution; it does not change the Windows driver or printer's media configuration. Our 300 dpi Zebra required 4 × 6-inch stock and Thermal Direct instead of its previous 4.09 × 2-inch Thermal Transfer defaults. After correcting those settings and resuming the printer, the user confirmed the built-in PDF label, alongside the already confirmed ZPL label and laser PDF. Barcode scanning and measured alignment remain separate checks; `SPOOLED` alone is not proof of physical output.
On Printers, select one or more rows or open a printer record to **Approve printers**, **Disable printers**, **Print a test page**, or **Print a test label**. Standard QQQ review/result screens show the selected scope; preview does not print. Each selected printer is read again under the current user's permissions before execution. Jobs display the related printer and device names; approval, availability, format and status fields have named choices.
Metadata names follow QBit conventions: tables and data sources use `printing_*`, while processes/widgets use `printing...`. The initial namespace is fixed to `printing`. The QBit preserves the host's `QBrandingMetaData`; customer identity belongs in the host branding, not a custom QBit build.
@@ -130,7 +152,7 @@ On 2026-10-29, both the development Windows connector and the installed LocalSys
## CI and releases
Pull requests and `main` pushes run Java 21/Maven wrapper verification with the immutable sibling protocol checkout. A tag matching the POM version runs build/tests and the secrets, workflow, dependency and malicious-package security gates before publishing the tested JAR, POM and `SHA256SUMS` as GitHub release assets. Maven resolves the dependency graph before Trivy scans it; OSV consumes that same graph as CycloneDX. Empty dependency analysis fails. Hyphenated versions create prereleases. The workflow does not publish to Maven Central, deploy a QQQ application or print to hardware. The [0.1.0-rc.1 release](https://github.com/QRun-IO/qbit-printing/releases/tag/v0.1.0-rc.1) passed these hosted gates.
Pull requests and `main` pushes run Java 21/Maven wrapper verification with the immutable sibling protocol checkout. A tag matching the POM version runs build/tests and the secrets, workflow, dependency and malicious-package security gates before publishing the tested JAR, POM and `SHA256SUMS` as GitHub release assets. Build verification enables the `ui-demo` profile used by the local host. Maven generates its selected compile/runtime graph as a CycloneDX SBOM, including frontend assets. Trivy and OSV scan that graph; a guard rejects missing or different package versions, missing frontend assets, and empty inventories. CI retains the resolved graph and scanner evidence. OSV uses `--all-packages`; its pinned 2.6.0 reporter [omits Maven groups](https://github.com/google/osv-scanner/issues/3099), so the guard checks every reported artifact/version and rejects ambiguous names while the verified input retains full package URLs. Hyphenated versions create prereleases. The packaged JAR includes the repository LICENSE and NOTICE under `META-INF`, alongside the existing font license and diagnostic assets. The workflow does not publish to Maven Central, deploy a QQQ application or print to hardware. The [0.1.0-rc.1 release](https://github.com/QRun-IO/qbit-printing/releases/tag/v0.1.0-rc.1) passed these hosted gates.
## Printing home
@@ -143,3 +165,11 @@ This RC implements the happy path of the [QQQ dashboard standard](https://github
The Windows companion can request test prints and explicit reprints through device-scoped authenticated routes. The same printer approval/exposure rules apply. Upgrade the QBit and connector together for these additive protocol features. Reprints create a new job; uncertain/spooled originals require duplicate-output consent and remain unchanged.
QQQ's **Print jobs** table and records expose **Print again** and **Cancel queued jobs** using native selection/review/result screens. Cancellation is allowed only before dispatch; later work must be inspected in the Windows queue. The actions require printing administration permission and the configured tenant context.
## Warehouse diagnostic pages
All built-in printer test actions share `PrintingTestDocuments`: QQQ branding, the official [Query dog mascot](https://qrun.io/query), large warehouse-style identifiers and embedded JetBrains Mono Bold with a dotted zero and distinct 1/I/l. Query's original artwork and aspect ratio are preserved in PDF and thermal output; [asset provenance](src/main/resources/com/kingsrook/qbits/printing/images/README.md) ships with the resource. The font is included under SIL OFL 1.1; its license and provenance ship in the JAR. PDF embeds a font subset. ZPL renders the same glyphs into document-local, row-aligned graphics below Zebra's 99,999-byte per-field limit; it does not download or save a printer font.
Native record and selected-table actions expose a possible-value stock/resolution selector. Letter and A4 are PDF-only. Label profiles are 4 × 6 inches at 203, 300 or 600 dpi; PDF label output is always 101.6 × 152.4 mm. Select matching stock and printer resolution. Bulk actions apply the chosen profile to every selected destination, so group compatible printers. The document does not reconfigure Windows stock, calibrate the printer or save device configuration; ZPL width/length are transient format settings.
The device test-print API accepts optional `testProfile` with the same choices. Existing clients default to Letter PDF or 203-dpi 4 × 6 ZPL. Invalid profiles fail before enqueueing. Test actions use the ordinary durable queue and existing printer exposure/approval rules; discovery never automatically prints. A ZPL barcode, glyph comparisons and size/alignment marks support physical inspection. Rendering previews and spool acceptance do not prove paper or scanner quality.
+2 -2
View File
@@ -2,8 +2,8 @@
Report vulnerabilities privately through [GitHub vulnerability reporting](https://github.com/QRun-IO/qbit-printing/security/advisories/new), or `contact@kingsrook.com` if that channel is unavailable. Include affected versions, a minimal synthetic reproduction and expected versus actual authorization behavior. Do not put enrollment codes, bearer credentials, customer documents or exploit details in public issues.
The current `0.1.0-rc.1` prerelease targets QQQ 4.1+. Fixes target the current prerelease; older QQQ versions are outside scope.
The current prerelease targets QQQ 4.1+. Fixes target the current prerelease; older QQQ versions are outside scope.
The host must provide authenticated management authorization and the correct tenant/facility context. Native QQQ operations require `printing_admin` and a matching `printing_tenant` session security value. Device credentials only authorize their device's queue/content/status operations. HTTPS is required for remote deployment; the supplied HTTP demos deliberately bind to loopback.
The UI demonstration uses a fixed mock identity and synthetic data and must remain local. It registers no connector transport routes. RAW ZPL is printer-control input: submit trusted generated labels, not arbitrary untrusted printer commands. Stored documents can contain personal information and need an application-specific retention policy.
The UI demonstration uses a fixed mock identity and synthetic data and must remain local. It registers no connector transport routes. RAW ZPL is printer-control input: submit trusted generated labels, not arbitrary untrusted printer commands. Stored documents can contain personal information. See [storage and retention](docs/STORAGE-AND-RETENTION.md) for dedicated bucket boundaries, tenant isolation and the default 365-day policy.
+37
View File
@@ -0,0 +1,37 @@
# Server printing audit
Target: 0.1.4-rc.1. Current local implementation verification passed **72 tests, zero failures/errors/skips and zero Checkstyle violations**. The independent baseline scan and subsequent source remediation reviews are complete. Earlier audit and CI guard commits passed hosted checks; the latest S3 correction requires fresh hosted verification. No live database, customer bucket, enrollment or printer was changed.
## Corrected behavior
- Native test-print and enrollment backend replay reuse prepared identities. A consumed enrollment cannot be reactivated by repeating a process.
- Print options, inventory formats/status and event fields are checked before persistence. Claim rechecks the queue's current format capability.
- A later failure retains known submission risk. Reprint requires explicit consent when output might already exist, and retry replay resolves its existing receipt even if the original content has expired.
- Enrollment offers authorized named facility choices, with a host-source option and a named standalone default. Backend validation rejects forged and foreign-tenant selections.
- Print documents can use the existing QQQ S3 storage API with a dedicated printing bucket, tenant namespace and exact job/reference/destination validation. Legacy database documents remain readable.
- Immutable S3 bindings include the reviewed physical key layout and host separator. Ordered JSON preserves component boundaries, including multiline base paths. Incompatible historical content is rejected before reads, new retry reservations or cleanup; document availability and accounting remain intact.
- Durable upload intents and exact orphan cleanup account for failed uploads/queue commits. Cleanup commits each confirmed document removal independently. A renewable lease prevents normal overlapping maintenance; all work reuses a single connection and passes real one-/two-connection pool concurrency regressions.
- Native administration exposes the default 365-day policy, read-only storage scope, backlog and last cleanup result. A host scheduler runs bounded batches every five minutes. Age starts at server-observed successful completion; active, failed, uncertain and unknown-completion jobs remain protected.
- Release publication requires build/security/CodeQL checks, verified artifact promotion and build provenance. Packaged QBit metadata uses the JAR's real Implementation-Version.
- Shared submission admission enforces configurable atomic device/tenant limits for outstanding work, retained bytes and hourly allocations. Durable uploads remain charged until confirmed cleanup; matching receipts replay even at capacity. Legacy unknown uploads conservatively reserve 20 MiB.
- Cumulative printer limits prevent rotating identities from growing history indefinitely. Management pages remain bounded, with optional opaque cursors; approval, metadata and job references survive rejected snapshots. A narrow index avoids PostgreSQL limits on wide Unicode names.
## Evidence and migration
The gate exercises real H2 persistence and bounded pools, QQQ StorageAction with an in-memory backend, native process review/resume, current-session record security and real QApplicationJavalinServer route registration/authentication over loopback. Failure tests cover partial upload/deletion recovery, per-document commit boundaries, conflicting/foreign references, destination retargeting, overlapping cleanup and original-content expiry during retry replay. The built JAR manifest reports 0.1.4-rc.1.
Separate disposable S3-compatible fixtures exercise the actual QQQ S3StorageAction and AWS SDK. Windows and Linux same-platform controls each passed 65 checks, including PDF/ZPL, multipart upload, integrity, tenant separation and retention. A controlled Windows-to-Linux migration then reproduced the RC.20 path defect: the old binding matched, reads returned S3 404, and cleanup marked content unavailable while the original Windows-key object remained.
The corrected runtime rejects that migration with HTTP 409 for reads and retries and a recorded cleanup error with zero removals. A native SDK transmission observer, checked against a successful HEAD request, recorded zero requests for the refused read, retry and cleanup. The original object, content availability, tenant/device byte accounting and job/admission/orphan counts remained unchanged. Golden binding tests and a regression for the reproduced multiline-prefix collision also pass. This qualifies refusal of the incompatible layout; it does not implement portable upstream keys or historical-object migration.
H2 2.4.240 fixes the observed close-time compaction schema loss. Exact earlier CI artifacts passed native authentication/query/denial checks, an actual scheduled retention tick, forced termination and cold restart, plus a separate graceful registered-hook shutdown. Independent read-only inspection before application initialization preserved all required tables, settings and counts. These results remain tied to their tested artifacts; they do not qualify Windows reboot or unattended supervision.
Schema initialization adds consumed-enrollment receipts, storage references/content availability, completion timestamps, retention settings/lease and upload intents. Existing inline bytes are retained; completion dates are backfilled only from durable successful events. No automatic inline-to-S3 copy or live purge occurs. Schema changes should be qualified against a backed-up deployment database before rollout.
Admission accounting also backfills retained bytes and recent allocations. Stop older writers before this migration; mixed-version writers bypass accounting and are unsupported. Regression cases cover concurrent tenant admissions, retained terminal payloads, replay at capacity, failed cleanup, unknown legacy uploads, rotating inventory and long-name pagination. See [operations](OPERATIONS.md) for configurable limits and recovery.
## Remaining boundaries
Production S3 endpoints, IAM/bucket policies, external bucket users, PostgreSQL, multi-node lease-expiry behavior, remote TLS deployment and sustained 10,000-print/day throughput are not qualified by these tests. The private native scheduler check is separate from live deployment. SQL and object deletion are not one transaction; crashes between them require idempotent recovery. S3 versioning and unfinished multipart parts have separate lifecycle semantics. See [storage and retention](STORAGE-AND-RETENTION.md).
The completed independent deep scan covers the frozen pre-audit baseline, not the subsequently added storage feature. Its two server findings were remediated and received a fresh independent bypass/regression review; that review's wide-index compatibility finding was corrected before the final gate. Separate review and regressions cover the new storage boundaries. These results do not prove absence of defects or qualify the live deployment boundaries above. No numerical quality score is assigned.
+12
View File
@@ -0,0 +1,12 @@
# Workflow compatibility — 2026-10-30
The `zizmor/self-repository` advisory recommends GitHub's newer `$/` syntax. This repository currently uses `./.github/workflows/...` **only for job-level reusable workflow calls**. GitHub documents that both forms select the same commit as the calling workflow. These are not step-level local actions that resolve from a potentially different workspace checkout.
The latest released actionlint, **1.7.12**, rejects `$/` reusable workflow calls. This was reproduced locally with the pinned version; the unchanged `./` calls pass. The upstream compatibility issue is still open. Retaining the supported job-level form preserves full actionlint validation of the called workflow, including its inputs and permissions, without suppressing the syntax rule or disabling any security check.
The advisory is reviewed and deferred for this specific use. No global zizmor exception is added, no branch requirement is removed, and no administrator bypass is used. External actions and workflows remain pinned to reviewed full commit hashes.
Adopt `$/` when a reviewed actionlint release supports it, update the checksum-pinned tool, and verify all PR and release workflows. Reassess separately if a step-level local or composite action is introduced; this decision does not cover that case.
Sources: [GitHub workflow syntax](https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_iduses), [actionlint issue 711](https://github.com/rhysd/actionlint/issues/711), [current actionlint release](https://github.com/rhysd/actionlint/releases/tag/v1.7.12).
+25
View File
@@ -0,0 +1,25 @@
# H2 license review — 2026-10-30
Status: [EX-0013](https://github.com/KofTwentyTwo/standards/blob/7d758b13449057e442d658a089a3c55aa3a6d171/exceptions/register.md#ex-0013) was approved in [standards PR #54](https://github.com/KofTwentyTwo/standards/pull/54) on 2026-10-31. The caller enables only the recorded H2 package license-metadata exception; fresh hosted gates remain required.
The dependency-review job for `fb99faf` reported `com.h2database:h2@2.4.240` as `LicenseRef-scancode-unknown AND MPL-2.0`. Its vulnerability check found no advisories at the configured low-or-higher threshold. The package upgrade fixes the confirmed embedded database compaction defect; reverting the driver would restore that defect.
## Published terms and artifact
The upstream [2.4.240 license](https://github.com/h2database/h2database/blob/version-2.4.240/LICENSE.txt) expressly offers a choice of MPL-2.0 or EPL-1.0. Its [license FAQ](https://github.com/h2database/h2database/blob/version-2.4.240/h2/src/docsrc/html/license.html) describes unmodified binary redistribution and attribution. The published Maven POMs for [2.4.240](https://repo.maven.apache.org/maven2/com/h2database/h2/2.4.240/h2-2.4.240.pom) and [2.3.232](https://repo.maven.apache.org/maven2/com/h2database/h2/2.3.232/h2-2.3.232.pom) both declare MPL 2.0 and EPL 1.0. The upgrade does not introduce a new license choice.
The local host uses the unmodified Maven Central H2 JAR under the MPL-2.0 option. The reviewed 2.4.240 binary SHA-256 is `29b70e427cc1c40cdc376283adbb0cc62853073797bb5fe5761f81fe73d57ce0`. Preserve H2 attribution, license information and access to the corresponding [source tag](https://github.com/h2database/h2database/tree/version-2.4.240) when distributing a host runtime. The QBit's own Apache-2.0 license does not replace third-party terms. Standard Maven resources include the repository LICENSE and NOTICE under `META-INF` in the QBit JAR; the existing font license/provenance assets remain included. The earlier d1821be artifact omitted the root notices, so its source attribution alone did not demonstrate packaged attribution.
## Applicable policy and scope
`K22-DEP-02` in the [dependency standard](https://github.com/KofTwentyTwo/standards/blob/main/standards/dependencies.md) permits MPL-2.0 when used unmodified. The pinned reusable [`pr.yml`](https://github.com/KofTwentyTwo/standards/blob/fdf5ed029603c938615a32b1beca3628b8787945/.github/workflows/pr.yml) requires every `allow-dependencies-licenses` entry to have a record in `exceptions/register.md`. EX-0013 passed the [exception policy](https://github.com/KofTwentyTwo/standards/blob/main/policies/exceptions.md)'s normal gates and was merged at `7d758b13449057e442d658a089a3c55aa3a6d171`.
EX-0013 covers only this repository and the unmodified H2 2.4.240 binary identified above. It expires on 2027-04-30 or an H2 version/license change or correction of GitHub's classification, whichever occurs first. It does not permit changing shared license policy, skipping vulnerability review or bypassing a required check.
## Package-specific correction
The caller uses only the reusable workflow's package-specific `allow-dependencies-licenses` input for `pkg:maven/com.h2database/h2`. It preserves `license-check: true`, `vulnerability-check: true`, the low advisory threshold and every other package's existing license policy. Unknown licenses are not globally allowed, and the MPL allowlist is not broadened.
The pinned action's [license matcher](https://github.com/actions/dependency-review-action/blob/a1d282b36b6f3519aa1f3fc636f609c47dddb294/src/licenses.ts) calls [`purlsMatch`](https://github.com/actions/dependency-review-action/blob/a1d282b36b6f3519aa1f3fc636f609c47dddb294/src/purl.ts), which intentionally ignores package versions. Adding `@2.4.240` to the input does **not** enforce a version restriction. The required security inventory gate now rejects absent H2, any version other than the reviewed `2.4.240`, and multiple H2 versions. It compares the selected Maven graph with both scanner inventories. A later upgrade must update both the pin and this reviewed-version guard after a renewed license assessment. Cite the approved exception ID beside the workflow input and give the record a review/expiry date.
The workflow cites EX-0013 beside the input. Any renewal or change requires normal review of the central record and this caller; the package exclusion must not outlive the record's scope or expiry. This correction does not approve a release or live server cutover.
+71
View File
@@ -0,0 +1,71 @@
# Authenticated local QQQ printing host
`com.kingsrook.qbits.printing.PrintingLocalHost` runs real QQQ screens and the printing protocol together. Native sign-in verifies a configured account with QQQ's table-based authentication. Only that verified account receives `printing_admin` and the configured `printing_tenant`. Authentication/session tables are protected by QQQ's system-table permissions, and passwords are stored only as native password hashes. This host always binds to `127.0.0.1`; remote deployment needs a separately configured QQQ application and HTTPS ingress.
## Three distinct launch targets
| Main class | Data and authentication | Purpose |
| --- | --- | --- |
| `PrintingDemo` | Durable H2, bearer-protected management API, no native QQQ UI | Protocol/hardware development |
| `PrintingUiDemo` | Isolated in-memory synthetic data, mock administrator, no device routes | Native UI demonstration only |
| `PrintingLocalHost` | Durable H2 shared by native QQQ and device routes, real password/session authentication | Authenticated local application |
The local host adds its own `printing_admin_user` and `printing_admin_session` tables. It preserves existing printing tables, device credential hashes, receipt history and tenant identity. Physical table/column names are mapped to the existing H2 case convention; it does not rename an uppercase database or change `DATABASE_TO_UPPER`. Every host instance uses a distinct internal backend name to avoid cross-instance provider-cache collisions in QQQ RC20.
## Required configuration
| Environment variable | Meaning |
| --- | --- |
| `QQQ_PRINT_JDBC_URL` | Required `jdbc:h2:file:` URL. Use an absolute private path and `;IFEXISTS=TRUE` when upgrading an existing paired database. |
| `QQQ_PRINT_ADMIN_TOKEN` | Existing management bearer token, at least 24 characters. Separate from the browser password. |
| `QQQ_PRINT_UI_USERNAME` | Explicit local administrator username, up to 200 characters, with no colon/control characters. |
| `QQQ_PRINT_UI_INITIAL_PASSWORD` | Required only when the authentication user table is empty; 16–1024 characters. Existing passwords are never reset by this variable. Omit it after bootstrap. |
| `QQQ_PRINT_TENANT` | Default `demo`; preserve the exact tenant used by the paired service. |
| `QQQ_PRINT_PORT` | Default `18081`; loopback binding is mandatory. |
| `QQQ_PRINT_DB_USER` / `QQQ_PRINT_DB_PASSWORD` | Existing H2 credentials; defaults `sa` / empty for compatibility with the development database. Protect the database file with host filesystem permissions. |
There is no default browser password and no account chosen automatically. Startup fails when the configured username differs from an initialized account. A password reset or account change needs an explicit administrative procedure; restarting with new environment values does not perform one. Do not place passwords or tokens in source files, shell history, command arguments or shared logs. Use the host's existing protected credential-loading mechanism. Bootstrap credentials are not retained in the application's settings after hashing.
## Build and run
Use Java 21 and the Maven wrapper. The `ui-demo` profile supplies the real frontend-next runtime assets for both UI-capable launch targets:
```powershell
.\mvnw.cmd -Pui-demo verify dependency:build-classpath '-Dmdep.outputFile=target/local-host-classpath.txt' '-DincludeScope=runtime'
$dependencies = (Get-Content target/local-host-classpath.txt -Raw).Trim()
& "$env:JAVA_HOME/bin/java.exe" -cp "target/classes;$dependencies" com.kingsrook.qbits.printing.PrintingLocalHost
```
Set the required environment values securely before launch. Maven contract tests require the documented sibling protocol fixture checkout or `printing.protocol.fixtures` override. Browse to `http://localhost:18081/` (or the configured port) and use the native username/password screen. The existing Windows connector continues using the same server origin and device token; it does not receive the browser password or management token.
This command runs the host in the foreground. `QApplicationLauncher` owns graceful HTTP/scheduler shutdown. It does not install an operating-system service or auto-start registration; the deploying operator must provide supervision, protected credential loading, logs and backups for unattended use.
## Embedded database runtime
Use the pinned **H2 2.4.240** runtime for file-backed local hosts. H2 2.3.232 has a confirmed close-time compaction data-loss defect ([issue 4247](https://github.com/h2database/h2database/issues/4247), [fix 4249](https://github.com/h2database/h2database/pull/4249)). Keep exactly one H2 driver JAR on the classpath; replacing the application JAR alone does not replace its runtime dependencies. Regenerate the runtime classpath from the current POM and remove the old driver from the new deployment payload.
Before upgrading, back up the closed database and validate a separate copy through startup, full shutdown and cold reopen with the fixed driver. Confirm paired records, retention settings and job history after reopening, without rerunning initialization merely to make missing tables reappear. Keep the pre-upgrade backup for rollback; do not point an older driver at a database already opened by the new runtime. A successful fresh-database test does not certify every existing database file. Normal compaction remains enabled; no warm-up, retry or delay is part of the fix.
## Cut over an existing paired protocol server
1. Identify the exact existing database, tenant, management credential and connector URL. Inspect all pending and uncertain jobs through bounded management pages before a maintenance window.
2. Stop only that paired Java host. Back up its closed H2 database and protected configuration. Never copy a live H2 file and treat the copy as a guaranteed consistent backup.
3. Validate the new host against a separate backup copy and isolated port first. Keep device transport unreachable by real agents during that check; do not enqueue tests or seed synthetic work in the real database.
4. Provision the explicit browser account, then start the local host with the original database, tenant and port. Use `IFEXISTS=TRUE` to prevent a typo silently creating an empty database. The service's additive schema initialization runs during startup; older writers must remain stopped.
5. Verify sign-in, paired records in native Devices/Printers/Print jobs, connector heartbeat, named actions, retention settings and logout. Existing device enrollment must remain intact. Do not infer physical printing from queue acceptance.
Existing facility IDs are retained. The standalone enrollment form offers the named **Default facility** for new enrollment. This local host does not invent names for existing facility codes or import a production facility directory; a full application should supply its actual facility possible-value source.
## Browser and API boundaries
QQQ supplies password verification, failed-sign-in throttling, HttpOnly sessions, session expiry and logout. The local authorization subclass calls native verification first and maps only the configured account to printing permissions. Other valid accounts cannot gain those permissions. Native QQQ permission and tenant checks still apply to every table/process.
The host rejects non-loopback Host headers, cross-origin Origin headers and cross-site browser requests. Cookie-authenticated unsafe requests require an exact same-origin Origin header, including logout and native process actions. Explicit bearer/device API calls without ambient cookies remain usable from the connector. Use one loopback hostname consistently in the browser; `localhost` and `127.0.0.1` are different browser origins. These controls do not turn a local HTTP host into an Internet-facing service.
## Retention, storage and remaining deployment work
The native Quartz scheduler runs the existing bounded cleanup process every five minutes while the host runs. Settings and cleanup observations are persisted in the same database; the default is 365 days after successful completion. Active, failed, uncertain and unknown-completion work remains protected. Scheduler registration is rebuilt from QQQ metadata on restart; no new ad hoc timer or scheduler database is introduced.
This local host deliberately leaves the S3 binding unconfigured. Native settings report legacy database storage. New and existing documents therefore remain in the database; merely running this host does not move documents to S3. A deployed application must supply its existing dedicated `printing_*` S3 table/backend and scheduler configuration, with bucket/IAM/tenant separation described in [storage and retention](STORAGE-AND-RETENTION.md). The host must retain historical storage bindings when changing configuration.
Remote HTTPS deployment, real S3/IAM, production OAuth roles, PostgreSQL and operating-system supervision remain separate qualification work. Record Files source-version/actor integration remains pending its concrete public contract; standalone printing delivery storage must not own or delete canonical attachments.
+141 -2
View File
@@ -24,7 +24,146 @@ Normal progression is QUEUED → CLAIMED → RECEIVED → SUBMITTING → SPOOLED
Use a stable business idempotency key for retries of the same request. A changed target/document/options with the same key is a conflict. A deliberately new print requires a new key. The initial implementation does not automatically reclaim RECEIVED/SUBMITTING jobs or resend ambiguous output; inspect the queue and physical result before deciding to print again.
Documents are stored as base64 in the database. Set a host-specific retention and access policy before deploying sensitive packing slips or shipping labels. The first release has no retention scheduler or object-storage backend.
The pending 0.1.4 implementation stores new documents through the host's configured dedicated QQQ S3 storage table; existing inline database content remains readable. Administration defaults to 365 days after server-observed successful completion, with bounded scheduled cleanup when a host scheduler is configured. Active, failed, uncertain and unknown-completion legacy jobs remain protected. See [storage and retention](STORAGE-AND-RETENTION.md) for bucket separation, recovery and versioning details. No live storage migration or cleanup is implied by a source upgrade.
## Admission capacity and inventory history
The host configures resource ceilings through `PrintingQBitConfig.withAdmissionLimits(PrintingAdmissionLimits)`. The producer passes these limits to every submission path, including native processes, direct Java submissions, connector test prints and explicit retries. Retention remains a separate administrator setting, defaulting to 365 days after successful completion.
| Limit | Per device | Per tenant |
| --- | ---: | ---: |
| Outstanding jobs and upload reservations | 10,000 | 100,000 |
| Outstanding decoded document bytes | 10 GiB | 100 GiB |
| Retained decoded document bytes, including terminal jobs and upload reservations | 2 TiB | 20 TiB |
| New admissions in a rolling hour | 2,000 | 20,000 |
| Cumulative printer identities | 1,000 | 20,000 |
`PrintingAdmissionLimits.defaults()` returns these defaults. To override them, construct the record with device/tenant pairs in this order: outstanding jobs, outstanding bytes, retained bytes, hourly admissions, cumulative printers. Values must be positive. Use the same configuration on every QQQ node serving a tenant. Size retained capacity for actual document sizes and the chosen retention period; 10,000 jobs/day is a sizing target, not a measured hardware throughput result. These are logical application byte limits, not an S3 billing limit: object versions, multipart fragments and provider overhead require their own deployment monitoring and lifecycle policy.
Admission is serialized per tenant in SQL before storage writes. Pending and failed upload reservations stay charged until exact-object cleanup succeeds; failed admissions that reached a committed reservation also consume the hourly allowance. Legacy reservations with unknown length conservatively reserve the maximum 20 MiB each, against the tenant when their device is unknown. Existing payloads are backfilled without removal. Apply this additive accounting migration with older application writers stopped; mixed-version writers or direct SQL changes bypass accounting and are unsupported.
HTTP 429 means capacity, the rolling-hour allowance, cumulative inventory history, or an existing upload reservation prevents a new allocation. The response explains the category. Reuse the same idempotency/request identity when retrying: a completed matching replay returns its existing job even at capacity or after the original retry source expires. Wait for outstanding work or the hourly window, investigate failed cleanup/storage access, or have the host administrator adjust a justified capacity limit. Retention only removes eligible successful documents; it does not erase failed, uncertain or active work to make space.
Inventory snapshots remain limited to 200 entries. Rotating IDs cannot bypass cumulative history limits, and rejected snapshots leave approval, availability and job references intact. Existing IDs remain updateable when a legacy database already exceeds a limit. Management `GET /printing/v1/admin/devices/{deviceId}/printers` accepts `limit` (1–200, default 200) and opaque `before` from the preceding response's `nextCursor`. The response is `{ "printers": [...], "nextCursor": null | "..." }`, ordered by stored name and row identity. The existing Java `printers()` method returns the first bounded array; use `printersPage()` for additional history. Native QQQ tables retain their own backend paging.
## Device controls and durable action receipts
The native client API is the registered `printing` extension, semantic version
`1.0.0`, under `/qqq/v1/qbit/printing`. Discover it through QQQ's version endpoint;
its generated OpenAPI fragment is `src/main/resources/openapi/qqq-v1/printing.yaml`.
The contract test checks this fragment against the registered endpoint specs and
the initial semantic compatibility baseline. Core QQQ session authentication and
credential scopes run before printing operations; the application does not issue
another kind of user login token.
Every native operation requires the authenticated QQQ principal, `printing_admin`,
the configured tenant security key, and applicable native table, process and row
access. Device operations additionally require `X-QQQ-Device-Id` and
`X-QQQ-Device-Token` as secondary proof. Enrollment at `/devices/enroll` validates
the user's facility access before consuming the enrollment code and atomically
binds the device to the core user's stable identity. A legacy unbound device can
be bound only through explicit `/device/bind` with valid proof and native device
access. Ordinary requests never bind or transfer ownership implicitly.
`GET /session` returns the current principal and tenant; valid bound device headers
add the device identity. Native administration can manage another user's device
when current permissions allow it, without impersonating that user. Queue clear
and inventory updates authorize affected existing rows before mutation and compare
the reviewed identity set under the device lock. Claims authorize the exact job
and printer before dispatch, ordered by creation time then identity. An inaccessible
printer fails closed rather than granting access through its parent device.
Queue-clear review is bounded to 10,000 jobs. It performs a native Get for each
job and each distinct printer, with the device checked once. Get-specific policies
remain effective. Large clears on remote databases have not been performance
qualified; this review cost is separate from normal claim throughput.
Developer projections that request derived `device_status`, `control_status`, or
`command_status` must also select `id`. The normal native UI includes it. An
identity-free projection is rejected rather than returning a fabricated UNKNOWN
status; the frozen QQQ dependency has no pre-query projection hook for these fields.
Printing selection processes also enforce native table access before extraction
and preview counts. The printing extract wrapper preserves the core filter,
callbacks, and tenant row locks, then requires permission enforcement on the
query. Later review/load checks still reauthorize the selected records.
Authorization uses the native QQQ context established for each request. Host
authentication and session refresh policies determine when permission changes
reach that context; printing does not assert that an upstream cached session is
fresh. Cookie-authenticated unsafe calls must also satisfy the host's Origin/CSRF
policy. The local host requires its canonical same-origin authority.
In the qualified QQQ 4.1.0-RC.20 runtime, OAuth2 `sessionStoreEnabled` defaults
to `false`. Ordinary requests and session resume rerun the configured
`QAuthenticationModuleCustomizerInterface` hooks; the host can load current
permissions, tenant keys, and account status from its authoritative directory.
With session caching enabled, a cache hit skips those hooks. That configuration
requires explicit session-cache invalidation on authorization changes or another
qualified freshness policy. Periodic `manageSession` calls and token renewal alone
do not establish current provider roles or immediate account revocation.
TABLE_BASED authentication rereads the session and user rows on each request;
deleting either prevents resume. A generic user `enabled` column is not enforced
automatically, and this module does not invoke the OAuth customizer hooks. The
local host grants its configured account the configured printing role and tenant;
this is not a general mutable role directory. Qualify the integrating host's
authorization mapping and provider behavior separately from printing transport.
Device controls use the same tenant-scoped service facade from native management
and transport adapters. Adapters must authorize the current user, tenant, device,
and action before calling the facade; a device ID or an actor string is not an
authorization grant. The legacy `/printing/v1` device bearer transport remains a
compatibility interface, not a substitute for native QQQ user permissions.
Once a device is bound to a QQQ user, its token is secondary proof only: all
legacy device endpoints reject it, including claim, content and control polling.
Existing unbound legacy devices remain usable during migration. New legacy
enrollment is disabled by default in `PrintingRoutes` and explicitly disabled in
`PrintingLocalHost`; native enrollment uses `/qqq/v1/qbit/printing/devices/enroll`.
Only a legacy-only host such as `PrintingDemo` should opt into
`PrintingRoutes.LegacyEnrollment.ENABLED`. A rejected legacy enrollment does not
consume the code, which still requires native user and facility authorization.
Pause blocks new claims. Disconnect also expresses that ordinary agent heartbeat,
inventory publication, and claiming should stop; the independent authenticated
control poll remains available for reconnect. Neither operation cancels in-flight
jobs. Resume preserves connection state; reconnect preserves pause. Revocation
invalidates the enrolled credential permanently, blocks control polling, and
requires separate local re-enrollment. It cannot be undone with resume/reconnect.
Desired state, the last observed revision, and the last poll are separate facts:
a successful server action does not prove an offline device applied it.
Queue clear atomically changes only this device's QUEUED jobs to FAILED with the
existing cancellation reason. It preserves documents, accounting, and history;
CLAIMED, RECEIVED, SUBMITTING, and uncertain work remain untouched. Claim and clear
share the device lock across server instances. Spool cancellation accepts only an
owned job with a recorded spool identity. The agent must independently verify its
local connection-scoped ownership before asking the operating system to cancel;
the server never accepts an arbitrary queue name, spool ID, or executable.
Every management action supplies a new `requestId` and a UTC `issuedAt`, retained
unchanged across retries. A retained matching request returns its existing record;
a changed body returns 409. Without an existing record, requests older than 15
minutes return 410, and times over 60 seconds in the future return 400. Review a
new action explicitly when a form expires. Never silently refresh its time or
reuse its identity. Terminal records become eligible for bounded cleanup after
seven days; an unchanged old request still expires after its receipt is removed.
Remote inventory refresh and owned spool cancellation require advertised agent
capabilities, expire after 15 minutes, and have a limit of 100 pending commands
per device. Polls deliver at most 20 commands. The retained action history is
limited to 1,000 records per device, with one additional reserved revocation;
eligible old terminal records are reclaimed before admission. Capacity returns
429 explicitly. History pages contain at most 200 records and use the preceding
`nextCursor`; an expired or foreign cursor cannot disclose another device.
Agents durably journal remote command identity before any effect and return the
same receipt on duplicate delivery. Expiry stops delivery but does not prove that
an earlier attempt did not execute: a first late receipt may replace provisional
EXPIRED with its actual outcome. Once stored, a receipt is immutable; conflicting
replays return 409. `CANCEL_REQUESTED` means the operating system accepted a
cancellation request, not that paper was withdrawn or a physical print was undone.
## Common failures
@@ -42,4 +181,4 @@ Documents are stored as base64 in the database. Set a host-specific retention an
## Release qualification
Initial checks cover H2/native/HTTP tests and user-confirmed laser output from the development connector and installed Windows service. Follow-up qualification includes Zebra hardware, PostgreSQL, production host authentication, upgrade/migration paths, multiple QQQ nodes, prolonged disconnects and a broader printer/driver set. Current prerelease artifacts must not be described as certifying those scenarios.
Prior released checks include user-confirmed laser PDF and Zebra ZPL/PDF output with correct machine driver settings. Audit source checks cover H2, native processes, host HTTP registration, synthetic storage and small real connection pools. Follow-up qualification includes live S3/IAM, PostgreSQL, production host authentication, upgrade/migration paths, multiple QQQ nodes, prolonged disconnects and a broader printer/driver set. Current prerelease artifacts must not be described as certifying those scenarios.
+58 -4
View File
@@ -1,6 +1,60 @@
# Session state — current checkpoint 2026-10-29
# Session state — 2026-10-31
2026-10-30 source0.1.2-rc.1: implemented client-authoritative Name/Description/Location synchronization, preserved computer/queue technical names, read-only native QQQ profile fields and friendly selector labels. Added additive schema backfill/widening, dispatch/history indexes, one-row payload-free claims and metadata-only keyset history pages. Added long-text, explicit-clear, migration, tenant and synthetic 10,000-row pagination/claim tests. Root verified22tests with zeroCheckstyle violations using mvnw.cmd verify. Protocol28definitions/21fixtures passed and CI now pins a0de93b. Prior verification below predates these changes. No physical prints were requested by this work.
## Published 0.2.0-rc.1: local native happy path
The published release includes native device/table actions for pause, resume, disconnect, reconnect, revoke, inventory refresh and queued-job clearing; job records support exact owned Windows-job cancellation. Related printers, jobs, pending queue and bounded command history are registered. Derived status separates connection presence, desired state and observed revision. Domain writes use current QQQ permissions; clearing a queue checks every affected job before the transactional mutation.
The primary client transport is the discovered `/qqq/v1/qbit/printing` semantic extension with standard QQQ user sessions and secondary device proof. Authentik requires the shared advertised native PKCE session grant; no private bearer-only fallback substitutes for that authorization. The tagged Java 21 gate passed **110 tests**, zero failures/errors/skips and zero Checkstyle violations. All 204 runtime dependencies match the frozen approved hashes. Native HTTP, proof/binding denials, explicit permission enforcement, selection count/extraction, FIFO eligibility, queue races, cancellation replay and offline command expiry are covered. Bound device tokens are rejected on legacy routes, and new legacy enrollment defaults off; real HTTP regressions prove there is no secondary-proof downgrade. The actual .NET client passed 25 native table-based authentication/binding/control/logout checks without printers or jobs. Protected CI, release checksums and exact-tag asset attestations passed.
Local server migration and deployment preserved existing data, pairing and retention. The exact published Windows MSI installed with pairing, printer exposure and journal history preserved. Standard table-based sign-in and explicit association of the existing pairing succeeded through the installed service. Both service and server observed pause, disconnect, reconnect and resume at revisions 1–4; inventory refresh has a confirmed `SUCCEEDED` / `INVENTORY_REFRESHED` receipt.
Native QQQ processes submitted one Letter PDF and one 4 × 6-inch, 300-dpi ZPL label. Both reached `SPOOLED` with reviewed content hashes; no active server queue remained. Physical confirmation is pending. Current Windows visual UI acceptance is unverified, and a requested service restart was canceled before execution. Configured Authentik/provider renewal, remote deployment and 1.0 readiness remain unqualified. See the [installed-client acceptance scope](https://github.com/QRun-IO/qqq-print-agent/blob/main/docs/ACCEPTANCE.md).
The user previously confirmed all three 0.1.4 Query test prints good; that historical output does not confirm the two current-release requests. Barcode catalog expansion remains outside printing scope and belongs to document/barcode generation.
## Query mascot correction
Built-in diagnostic pages and labels now use the official Query dog artwork from [qrun.io/query](https://qrun.io/query), with the exact original asset and provenance recorded alongside the resource. White padding preserves its aspect ratio within the existing layout; warehouse glyphs, media profiles, barcode and print routing are unchanged. All five PDF profiles and three thermal resolutions are covered by the new regression. The isolated full build passed **73 tests with no failures/errors/skips and zero Checkstyle violations**. Generated PDF previews and actual ZPL graphic-field reconstruction were reviewed. The tested resource is packaged and the previous logo is absent.
This server-only correction is published in [v0.1.4-rc.1](https://github.com/QRun-IO/qbit-printing/releases/tag/v0.1.4-rc.1), and local native deployment is accepted. The Windows client already requests these server-generated documents; no client icon change is needed. Installed-client acceptance passed with credentials and history preserved. Physical output from the new Query diagnostics remains unconfirmed.
## Published audit release 0.1.4-rc.1
Local paired-host acceptance is complete following verified recovery backups. Native authentication, bounded record queries, anonymous/cross-origin/authentication-table denials, logout and the enabled **365-day** retention policy passed. Pairing and history were preserved, and the connector reconnected automatically. This acceptance used database document storage and did not request a new print. Dedicated production S3 provisioning, IAM and remote deployment remain unqualified.
All required checks passed for reviewed Query commit `c34883d`; protected merge `412ffbbc` preserves that exact tree. [Release run 41190650664](https://github.com/QRun-IO/qbit-printing/actions/runs/41190650664) passed every build, security and CodeQL gate before publishing assets for signed tag `v0.1.4-rc.1`. The current gate records **73 passing tests and zero Checkstyle violations**. All 204 runtime dependency coordinates are unchanged from the qualified audit runtime. The public JAR, POM and SHA256SUMS passed checksum and GitHub attestation verification, constrained to the exact source commit, tag and release workflow. All 48 JAR entry contents, including 38 implementation classes, match the reviewed Query CI package. Release JAR SHA256: `b31aa58588e2bad6b1ca63e5904906c0379ef75b6d2b550ad1680e668312065b`.
The preceding S3 safeguard checkpoint passed **72 Java tests, zero failures/errors/skips and zero Checkstyle violations**, with independent source review complete. It binds documents to the reviewed physical key layout and native separator using unambiguous ordered JSON. Historical reads, new retries and cleanup reject incompatible bindings before object IO; inline database content and prior retry receipts remain compatible. Old experimental S3 bindings are not silently adopted.
Actual isolated Windows-to-Linux qualification passed on local candidate JAR SHA256 `9163b5fb89c981b70d2bd416ca3920a17bcbda2fe61eaa7190f050cc27759495` with all 204 runtime libraries verified on both hosts. Read and retry returned 409; cleanup recorded an error with zero removals. A positive-control-checked native SDK observer recorded zero transmissions for those refusals. Content availability, tenant/device retained bytes, admission/orphan/job counts and the exact original object stayed unchanged. The earlier candidate reproduced false expiration of a Windows-key object from Linux; this correction prevents that loss of availability. Portable upstream keys, explicit historical migration and production IAM remain separate work. Fresh hosted checks for this correction and the scoped license input now pass.
Packaged candidate `00dd2dd` passed hosted [build](https://github.com/QRun-IO/qbit-printing/actions/runs/41162272066), [CodeQL](https://github.com/QRun-IO/qbit-printing/actions/runs/41162272168) and [security](https://github.com/QRun-IO/qbit-printing/actions/runs/41162272058). The isolated frontend-profile gate passes **67 Java tests, zero failures/errors/skips and zero Checkstyle violations**. All **204** runtime dependencies match the selected Maven graph and scanner inventories, with exactly one H2 2.4.240 JAR. Refreshed Trivy reports zero HIGH/CRITICAL findings; OSV reports zero malicious findings. The exact CI package includes matching LICENSE/NOTICE resources; all 38 implementation classes and existing runtime assets match the earlier `fb99faf` candidate.
The exact `fb99faf` CI application JAR and verified runtime payload passed isolated native acceptance against a fresh private copy of a closed database: real frontend, native authentication, bounded table counts/queries, denied requests, logout and retention settings at the **365-day default**. The native scheduler actually ran at `2026-10-31T02:45:00.087433600Z` and removed zero documents. After identity-verified forced termination, an independent SELECT-only read-only H2 inspection **before application initialization** found all 11 tables, including the four audit tables, with retention and record counts preserved. Restarting the same exact artifact passed the native checks again at `2026-10-31T02:47:10Z`. This qualifies the tested forced-termination/cold-reopen path. The graceful-shutdown check is recorded below. No live paired database, remote host, S3 storage or printer was changed by these checks.
Graceful shutdown is now separately verified on the exact packaged `00dd2dd` CI artifact. A fresh isolated closed-data copy passed native acceptance. A minimal private Java Attach agent invoked `System.exit(0)` after the owned process identity was checked; the real registered launcher hook stopped Quartz and HTTP, and the supervisor recorded JVM exit 0 at `2026-10-31T03:09:26.8635088Z`. Read-only JDBC inspection before reinitialization confirmed all required tables, retention and counts. The separate Attach client timed out waiting for a reply after server exit and was cleaned up; the server itself exited normally. All private children stopped and no physical output was requested. This does not qualify Windows reboot, service-manager shutdown or unattended supervision.
The prepared-copy failure was the upstream H2 2.3.232 close-time compaction defect (#4247/#4249). Replacing only H2 with **2.4.240** preserves the migrated schema using normal compaction. No warm-up, retry, delay or disabled-compaction production workaround is present. The public fresh-file cold-reopen test checks durability; it does not claim to reproduce every affected old-driver database. See [local runtime and backup guidance](LOCAL-HOST.md).
The earlier H2 license-metadata gate is resolved. [Standards PR #54](https://github.com/KofTwentyTwo/standards/pull/54) merged EX-0013 through normal required checks following explicit user approval. Its separately approved CodeQL repair retains Actions and JavaScript/TypeScript under the advanced security-extended workflow. Printing applies only the approved package input; its fresh [PR gates](https://github.com/QRun-IO/qbit-printing/actions/runs/41185576692) pass. The inventory guard still requires exactly unmodified H2 2.4.240, with 17 passing guard tests; all other license, vulnerability and branch protections remain enforced. See [license evidence and expiry](H2-LICENSE-REVIEW.md).
The audit also fixes native-process replay, tenant-scoped facility selectors, duplicate-output risk preservation, atomic queue/retained-byte/rate admission and bounded printer history. Dedicated QQQ document storage and scheduled retention protect active, failed and uncertain work. Stop older writers before schema/accounting migration and preserve verified recovery copies. See [audit evidence](AUDIT-2026-10-30.md), [operations](OPERATIONS.md) and [storage](STORAGE-AND-RETENTION.md). Real PostgreSQL/S3, remote authentication, multi-node operation and sustained physical throughput remain unqualified. Local acceptance, shared-standards approval and tagged audit publication are complete.
Record Files' **21:54 America/Chicago checkpoint on 2026-10-30** is acknowledged. Its latest typed reader and configured reporting authority are candidate source with focused tests; the verified installed artifact is still pending, and the earlier snapshot is not the final contract. The teams agree on the consumer-owned observation boundary and are resolving identifier bounds and optional spooler-ID canonicalization. Printing still needs its durable accepted source/initiator/job/destination binding, tenant-scoped committed event receipt and legitimate current native reporting identity before an adapter can be enabled. No adapter is enabled, no browser session or fabricated authority is retained, and spool completion is not physical-output confirmation. Standalone byte submission remains independent.
## Branded diagnostic documents — v0.1.3-rc.1 verified and published
Built-in test paths now share PrintingTestDocuments and TestPrintProfile. Native QQQ forms and device test requests choose Letter, A4 or 4 × 6-inch label profiles at 203/300/600 dpi; omitted profiles retain PDF Letter/ZPL 203 defaults. ZPL rejects page profiles. Documents use the QQQ logo and wordmark, bundled OFL JetBrains Mono Bold, character-pair checks and a 25.4 mm reference. PDF embeds vector text; ZPL carries a monochrome bitmap in whole-row graphic strips of at most 99,999 bytes each and native Code 128. No persistent font download is required. Identical PDF generation uses stable document IDs for idempotency; changed request content still conflicts.
Source `a6266fe` passed the full `mvnw.cmd verify` gate: **28 tests and zero Checkstyle violations**. This includes generator/media/font/margin tests, per-strip byte/row/hex bounds and full bitmap reconstruction checks at every density, plus native/API parity and profile validation. Exact-source [build 41139885188](https://github.com/QRun-IO/qbit-printing/actions/runs/41139885188), [CodeQL 41139885415](https://github.com/QRun-IO/qbit-printing/actions/runs/41139885415) and [security 41139884980](https://github.com/QRun-IO/qbit-printing/actions/runs/41139884980) passed. The [v0.1.3-rc.1 release](https://github.com/QRun-IO/qbit-printing/releases/tag/v0.1.3-rc.1) JAR, POM and SHA256SUMS assets are public and verified.
PrintingTestDocumentsExport writes local PDF/PNG/ZPL previews without contacting printers. Installed Windows 0.1.7 passed all 16 UI checks, and its published release assets are verified. The loopback QQQ server was restarted with the new code using the same paired database and retained credentials. Exactly one Letter PDF to the laser, one LABEL_4X6_300 ZPL to the Zebra and one LABEL_4X6_300 PDF to the Zebra initially reached SPOOLED through the installed management pipe, device API and shared generator. Their bytes matched the reviewed previews. The user confirmed the laser page and the Zebra ZPL label, but the initial Zebra PDF did not appear.
The Zebra machine driver defaults were 4.09 × 2 inches and Thermal Transfer, while the loaded stock required 4 × 6 inches and Thermal Direct. Windows Printing Defaults were corrected; the paused printer was restored to Thermal Direct and resumed. One fresh submission of the same generated PDF through QQQ administration and the installed service advanced the hardware counter by one while preserving Thermal Direct, and the user confirmed correct physical output. All three built-in format paths are now physically confirmed after the configuration correction; no application code fix was required. Barcode scanning and measured alignment remain unverified. Deployed remote QQQ integration and sustained throughput remain separate qualification work.
## Historical source and integration checkpoints
2026-10-30 source0.1.2-rc.1: implemented client-authoritative Name/Description/Location synchronization, preserved computer/queue technical names, read-only native QQQ profile fields and friendly selector labels. Added additive schema backfill/widening, dispatch/history indexes, one-row payload-free claims and metadata-only keyset history pages. Added long-text, explicit-clear, migration, tenant and synthetic 10,000-row pagination/claim tests. Root verified22tests with zeroCheckstyle violations using mvnw.cmd verify. Protocol28definitions/21fixtures passed and CI pins a0de93b. Exact-source GitHub build41126545760 and security41126545795 passed for cfe8a5f. Prior verification below predates these changes. No physical prints were requested by this work.
Current source is prepared for **0.1.1-rc.1**. Latest Java verification passed **19 tests with zero Checkstyle violations**. The full audit follow-up implements device-scoped test-print/retry/cancel/queued-job routes and native **Print again** / **Cancel queued jobs** actions from job records and table selections. Native review uses named records, rechecks administrator/tenant/row access and current state, requires explicit duplicate-risk confirmation for uncertain/spooled output, and uses a stable request identity for retry replay. Retry creates a new job and preserves the original outcome. Queued cancellation is serialized against claim and cannot promise cancellation after dispatch.
@@ -10,9 +64,9 @@ Final Windows MSI rebuild is in progress. Actual elevated upgrade/interactive ac
## Historical publication and implementation evidence
Published: https://github.com/QRun-IO/qbit-printing/releases/tag/v0.1.0-rc.1 at f7f451a. Tagged build/test/Checkstyle, secrets, workflow, dependency and malicious-package checks all passed before publication. JAR, POM and SHA256SUMS assets are public. Guava is fixed at 33.7.2-jre. The security workflow resolves Maven dependencies first, verifies the scanned graph and feeds the resulting CycloneDX inventory to OSV; this avoids Maven throttling and the upstream parent-POM placeholder parsing issue without skipping checks. Main protection requires verify and all three security jobs. Release JAR SHA-256: fefce42496a534f3227f496a0e5f9a6f8e9209e7175ddf14b18166968a6ad4d6.
Published: [v0.1.0-rc.1](https://github.com/QRun-IO/qbit-printing/releases/tag/v0.1.0-rc.1) at f7f451a. Tagged build/test/Checkstyle, secrets, workflow, dependency and malicious-package checks all passed before publication. JAR, POM and SHA256SUMS assets are public. Guava is fixed at 33.7.2-jre. The security workflow resolves Maven dependencies first, verifies the scanned graph and feeds the resulting CycloneDX inventory to OSV; this avoids Maven throttling and the upstream parent-POM placeholder parsing issue without skipping checks. Main protection requires verify and all three security jobs. Release JAR SHA-256: fefce42496a534f3227f496a0e5f9a6f8e9209e7175ddf14b18166968a6ad4d6.
Live frontend RC.37 acceptance: dashboard links and the six operational printer columns were inspected; selected-printer Print a test label review/submit completed successfully against synthetic data; record actions were verified. Safe screenshots and instructions are in UI-WALKTHROUGH.md. No additional physical print was sent by this UI demo. At that earlier acceptance checkpoint, the local preview ran at http://127.0.0.1:18084 (override of default 18082); inspect current processes before assuming it is still running.
Live frontend RC.37 acceptance: dashboard links and the six operational printer columns were inspected; selected-printer Print a test label review/submit completed successfully against synthetic data; record actions were verified. Safe screenshots and instructions are in UI-WALKTHROUGH.md. No additional physical print was sent by this UI demo. At that earlier acceptance checkpoint, the local preview ran at `http://127.0.0.1:18084` (override of default 18082); inspect current processes before assuming it is still running.
2026-10-29: Initial QQQ 4.1 printing QBit and durable protocol server prepared for 0.1.0-rc.1 publication. QQQ baseline 4.1.0-RC.20. Server scope includes JDBC storage, scoped device credentials, inventory approval, queue submission, replay-safe events, metadata, native enrollment/enable/test-print processes and durable enqueue target. Root owns commits/publication; this checkpoint does not assert remote publication.
+49
View File
@@ -0,0 +1,49 @@
# Print document storage and retention
Status: audit implementation pending final verification and release. QQQ 4.1+ hosts provide the existing storage and scheduler metadata; this module does not create buckets or copy credentials into printing settings.
## Deployment boundary
Use a dedicated private printing bucket for each customer/environment, separate from general uploads, backups and unrelated QBits. Configure it through the host's existing QQQ S3 backend and a printing storage table. Bind that table with `PrintingQBitConfig.withStorageTableName(...)` and the existing scheduler with `withSchedulerName(...)`. Printing uses QQQ `StorageAction` for writing, reading and deleting objects. The Windows agent receives authenticated document bytes through QQQ and never receives S3 credentials or a bucket-wide URL.
Keep access keys, role credentials and endpoint configuration in the host's established secret/configuration mechanism. Prefer a deployment role restricted to this printing bucket. Permit only the object read/write/delete operations the storage adapter needs, scoped to its printing prefix; grant bucket-level listing only if the configured adapter requires it, with an appropriate prefix condition. Do not grant bucket deletion, ACL/policy administration, or arbitrary access to other buckets. AWS distinguishes bucket and object resource permissions in its [bucket policy examples](https://docs.aws.amazon.com/AmazonS3/latest/userguide/example-bucket-policies.html).
The code validates the selected S3 metadata, detects conflicting bucket bindings within the QQQ instance and uses tenant-specific object namespaces. Each job retains its storage table, destination identity and exact document reference. Retrieval and cleanup validate those values and fail closed if metadata is retargeted or the reference belongs to another tenant/job. Cleanup deletes exact eligible objects; it never lists and wipes a prefix. Tenant prefixes are an application isolation control, not a substitute for separately scoped IAM roles or separate customer buckets.
Application metadata cannot prove that a bucket is unused by another application or that deployed IAM/bucket policies are correct. Deployment qualification must check those external controls, public-access blocking, transport/encryption policy and the intended customer/environment boundary. No live bucket has been created or changed by the audit.
## S3 key layout and migration
QQQ filesystem 4.1.0-RC.20 builds S3 keys with the host filesystem separator. With empty base paths, Windows writes two leading backslashes before the logical `printing/<tenant-hash>/<job>.ext` reference; Linux writes the canonical reference. Same-platform object operations have been qualified in isolated S3-compatible storage. The logical reference alone is therefore insufficient for IAM prefix rules or migration between platforms.
Printing fingerprints the reviewed `qqq-s3-filesystem-v1` layout and the actual `File.separatorChar` code point (47 or 92), alongside the endpoint, bucket, region, path-style setting and backend/table base paths. Ordered JSON encoding preserves the identity component boundaries, including valid multiline base paths. A different layout rejects historical reads, new retries and cleanup with a destination-mismatch error before accessing those objects. New retries whose source binding is already incompatible fail before reserving another upload; the document loader also rechecks the binding when reading. An already-created retry still returns its idempotent receipt. Cleanup preserves content availability, retained-byte accounting and orphan reservations on mismatch.
This S3 feature is unreleased. Old experimental fingerprints without the layout marker are deliberately rejected, even on their original platform. Startup never rewrites those bindings or moves/deletes their objects. Preserve the original database and objects until an explicitly reviewed migration or disposal; do not replace hashes merely to bypass the guard. Inline database documents remain readable and can be explicitly retried into the configured destination without any automatic storage migration.
This guard does not make QQQ keys portable. The upstream owner must provide portable key construction and legacy-key handling. Adopting that change, including a change on the same operating system, requires an explicit layout-marker review and a migration plan for historical bindings and exact objects. The marker is a reviewed compatibility contract, not automatic detection of dependency implementation changes. Cross-platform migration and production IAM remain separate qualification work.
## Retained originals and delivery copies
Record Files owns original versions and attachments; document generation owns rendering. Printing owns a separate delivery payload and queue receipts. Never bind printing cleanup to a Record Files bucket or pass an original's storage key as a printing-owned reference. Printing expiration must not remove a source attachment or weaken its retention policy.
The current independent integration seam accepts bytes and a stable business idempotency key. An authorized immutable-version reader and source/job correlation contract are being coordinated with Record Files; that API is not yet implemented or assumed here. Printing currently checks device/destination authorization at dispatch, not later revocation of the source attachment's permissions. A shared adapter must define that boundary before promising revocation propagation.
The existing `PrintEnqueueEffectTarget` accepts base64 document bytes in the host's durable outbox. That outbox may retain another delivery copy outside this module's S3 cleanup policy. Hosts must manage its retention separately; do not claim that configuring printing S3 moves existing outbox payloads or all upstream copies into the printing bucket. The future retained-version adapter should carry authorized opaque source IDs/hash/length/media type and actor/correlation, not bucket URLs or duplicated document bytes. Direct byte submission stores the printing-owned payload through the configured storage backend without adding this host-outbox copy.
## Administration and scheduled cleanup
Printing administration exposes retention settings and a reviewed **Run cleanup** action. The default is **365 days after successful completion**. The storage destination is read-only in these forms: bucket changes require a reviewed deployment/storage migration, not typing a new backend ID into a cleanup form. The screen reports the effective storage scope, schedule, eligible backlog and last cleanup result.
When the host supplies a scheduler, maintenance runs every five minutes in bounded batches of at most 200. That permits a nominal 57,600 eligible documents per day before storage latency or failures; it is not measured production throughput. Changing a retention setting does not itself purge documents. Disabling cleanup preserves content. Without a configured scheduler there is no automatic job; the administration screen must show that condition.
Only eligible successful terminal jobs lose their document content. Active, failed or uncertain work remains protected. Job metadata, document hashes, receipts and idempotency records remain available for auditing and duplicate prevention. Legacy completion times are recovered only from durable successful events; unknown completion dates remain protected. Existing inline database documents remain readable; the initial storage integration does not silently migrate old bytes to S3. Reprinting a job whose document has been removed returns an explicit unavailable-document result.
## Failure and versioning behavior
External object storage and SQL cannot share one transaction. Cleanup must retain retryable state on failed deletion, and submission must account for an uploaded object whose database write fails. A process crash between object and database operations remains a recovery boundary; do not delete unknown objects merely because a prefix looks old. Review the recorded cleanup outcome/backlog and storage errors before intervening.
Submission persists an exact upload intent before uploading and removes it atomically with the queued job. Failed compensation leaves that intent for maintenance; abandoned intents become eligible after one hour. Maintenance uses a renewable one-hour lease and exact row locks, reusing one SQL connection rather than acquiring a second connection while holding the first. Interrupted multipart uploads may leave unfinished parts rather than an object: configure the dedicated bucket's `AbortIncompleteMultipartUpload` lifecycle separately. Deleting an object does not remove unfinished multipart parts, and this lifecycle must not expire current objects by age.
With S3 versioning, a normal delete can create a delete marker while retaining noncurrent bytes. Application cleanup therefore means the current document is no longer available through printing; it does not promise permanent erasure of all versions. Set an explicit noncurrent-version retention policy consistent with the customer's requirements and any Object Lock policy. See AWS's [expiration semantics](https://docs.aws.amazon.com/AmazonS3/latest/userguide/lifecycle-expire-general-considerations.html) and [version lifecycle examples](https://docs.aws.amazon.com/AmazonS3/latest/userguide/lifecycle-configuration-examples.html).
Do not attach a blanket 365-day current-object expiration rule to the printing prefix: S3 cannot see job state and could delete an active or uncertain job that the application deliberately protects. The application controls eligibility; any noncurrent-version cleanup is a separate deployment policy.
+59 -10
View File
@@ -1,35 +1,84 @@
# Follow-up
- [x] Complete native device controls, per-record/selection actions, queue/history, dashboard and legacy-boundary integration tests; 110 tests pass with zero Checkstyle violations.
- [x] Complete 25 actual Windows Core client/native QQQ interoperability checks with table-based authentication, no printers and no jobs.
- [x] Publish and verify 0.2.0-rc.1 assets; deploy the local server and install the exact published Windows MSI with existing state preserved.
- [x] Qualify local installed-service table-based sign-in, explicit existing-pairing association, observed pause/disconnect/reconnect/resume and successful inventory refresh.
- [x] Run native QQQ Letter PDF and 4 × 6-inch, 300-dpi ZPL test processes; both reached `SPOOLED` with reviewed content hashes.
- [ ] Obtain physical confirmation of the two current-release outputs; qualify the current Windows visual UI and an actual service restart (elevation was canceled before execution).
- [ ] Qualify the shared Authentik native grant and long-lived renewal without a private authentication fork; local table-based acceptance does not cover the configured provider.
- [x] Review and merge immutable protocol inputs (cc3c4e5), pass protected CI and merge the server and Windows implementations normally.
- [x] Replace the test-document logo with the exact official Query dog asset; preserve aspect ratio and verify all PDF/thermal profiles with 73 passing tests, zero Checkstyle violations and reviewed previews.
- [x] Publish v0.1.4-rc.1 after all required release gates, verify checksums and all three asset attestations, and complete local native deployment acceptance.
- [x] Obtain user confirmation for all three updated Query diagnostic documents (Letter PDF, Zebra ZPL and Zebra PDF).
- [x] Correct S3 layout and multiline-prefix binding ambiguity; full isolated gate passes 72 tests with zero Checkstyle violations and independent review complete.
- [x] Reproduce the actual Windows-to-Linux false-expiration defect, then qualify the corrected runtime: zero SDK requests for refused reads/retries/cleanup and preserved objects, availability and accounting.
- [x] Pass fresh hosted gates for the S3 correction and approved scoped H2 input; verify exact CI artifacts, all 47 archive payloads and 204 runtime coordinates. Portable upstream keys, historical migration and production IAM remain separate qualification work.
- [x] Verify the H2 2.4.240 candidate at `fb99faf`: 67 Java tests, zero Checkstyle violations, hosted build/CodeQL/security pass, and all 204 selected runtime dependencies verified.
- [x] Qualify the exact CI artifact on an isolated closed-data copy: native frontend/authentication/query/denial/logout/retention checks, actual scheduled zero-removal tick, forced termination, read-only inspection before initialization, and successful cold restart; all 11 tables and retained state preserved.
- [x] Add the exact reviewed H2 version guard and license attribution/evidence; 17 Python guard tests and workflow lint pass.
- [x] Approve central H2 metadata record EX-0013 through standards PR #54, apply only its package-scoped workflow input and pass every fresh required check.
- [x] Qualify registered JVM-hook shutdown on exact `00dd2dd`: native acceptance, Quartz/HTTP shutdown, exit 0 and independent read-only cold inspection before initialization pass. Windows reboot/service-manager behavior remains separate.
- [x] Complete local paired-host acceptance after verified recovery backups and fresh required gates; preserve pairing and history. Native authentication/query/denial/logout, automatic connector reconnection and 365-day retention checks pass.
- [x] Finish audit regressions for native-process replay, strict options/inventory validation, retained duplicate risk and event field bounds; full gate passes 53 tests.
- [x] Implement admin-configurable document retention (one-year default), bounded scheduled cleanup and existing QQQ object-storage integration, retaining history/receipts and protecting active or uncertain output.
- [ ] Implement the optional Record Files adapter against its verified frozen contract: durable accepted-source/actor binding, legitimate current reporting identity and committed observation receipt. Adapter remains disabled; standalone printing does not depend on it.
- [x] Verify v0.1.4-rc.1 release run 41190650664, published JAR/POM/SHA256SUMS provenance and local native deployment acceptance.
- [x] Historical audit PR #10 checkpoint aeac1a6 passed hosted checks; current H2/native qualification and remaining license gate are recorded above.
- [x] Complete the independent baseline scan and current-source reviews of all five findings and remediations.
- [x] Add authenticated native QQQ local host sharing paired data with device routes and the existing scheduler; 65 tests/zero Checkstyle pass and independent source review found no blocker.
- [x] Complete live authenticated local-host deployment after isolated native and graceful/cold-copy acceptance; remote/S3 qualification remains separate under the user's local-first instruction.
- [x] Versioned shared contract and HTTP happy-path test.
- [x] Durable enrollment, device-scoped authentication, inventory and printer approval.
- [x] PDF/ZPL queue, idempotency, content integrity and status events.
- [x] QQQ metadata and native enrollment/enable/test-print processes.
- [x] Durable enqueue EffectTarget for QQQ workflows.
- [x] Verify local laser output from connector and installed LocalSystem service; user confirmed both pages.
- [ ] Verify Zebra hardware when connected.
- [x] Confirm physical built-in ZPL and PDF output on the connected Zebra; scanning and measured alignment remain separate checks below.
- [x] Add separate synthetic native QQQ frontend preview host.
- [x] Replace identifier text inputs with tenant-scoped, device-dependent selectors and add table/record actions.
- [ ] Qualify deployed QQQ host integration.
- [x] Qualify authenticated local QQQ host integration with preserved pairing/history and native retention scheduling.
- [ ] Qualify remote QQQ host deployment and production authentication/facility policy.
- [x] Separate local printer availability from server approval and block withdrawn queues.
- [x] Prepare public repository documentation, license, CI and GitHub prerelease artifacts.
- [x] Verify remote CI/security and publish v0.1.0-rc.1 JAR/POM/checksum assets.
- [x] Client-owned device/printer name, description and location synchronized into native QQQ metadata.
- [ ] Logical destinations and object-storage document backend.
- [ ] Run the coordinated Java gate for profile migration, long text and 10,000-row bounded-history regressions; qualify sustained throughput separately.
- [x] Implement the dedicated QQQ object-storage document backend; live S3/IAM qualification remains pending configuration.
- [ ] Logical destination mappings.
- [x] Run the coordinated Java gate for profile migration, long text and 10,000-row bounded-history regressions; included in the passing 28-test v0.1.3-rc.1 gate.
- [ ] Qualify sustained throughput separately from synthetic bounded-history tests.
- [x] Device-scoped test/retry/cancel/queued-job routes and native record/table cancellation/reprint review, explicit duplicate-risk consent and retry idempotency.
- [ ] Server-side job expiry/document retention and operational alerts.
- [x] Implement admin document retention and bounded scheduled cleanup, default 365 days.
- [ ] Server-side job expiry and operational alerts.
- [ ] PostgreSQL integration and multi-node stress tests; migration/version management.
- [ ] Resolve upstream/cached qbit-build-parent interpolation warning for Maven 3.10.
- [x] Add native Printing home with scoped operational widgets and actionable links.
- [ ] Complete dashboard-standard live attention, URL scope, stale/retry and responsive/accessibility acceptance.
## 0.1.1-rc.1 integration checkpoint
## Historical 0.1.1-rc.1 integration checkpoint
- [x] Verify current Java source: 19 tests passed, zero Checkstyle violations.
- [x] Preserve job outcome while retry creates a new job; reject cancellation after claim.
- [x] Expose cloud-queued jobs to the companion for visibility/cancellation before local receipt.
- [ ] Record the pending latest Windows changed-tree gate, including independent heartbeat during slow printing.
- [ ] Complete final MSI rebuild and actual elevated upgrade/UI acceptance after the user's pending UAC approval.
- [ ] Record final package hashes, signing status and applicable integration evidence before replacement release.
- [ ] Run a fresh explicitly authorized physical acceptance job for the final package; Zebra remains deferred.
The Windows gate, MSI rebuild, installed UI acceptance, release evidence and fresh hardware submissions pending at this historical checkpoint are superseded by the newer records below and the Windows acceptance notes. Zebra is connected and both label format paths are physically confirmed.
- [ ] Qualify reboot/sign-in/service recovery and deployed-host behavior; no source-only or synthetic result substitutes for those checks.
## v0.1.3-rc.1 diagnostic documents
- [x] Share branded diagnostic generators and explicit stock/resolution profiles across native QQQ and device test-print entrypoints.
- [x] Verify source a6266fe: full Maven gate passed 28 tests with zero Checkstyle violations; exact-source build, CodeQL and security workflows passed.
- [x] Publish v0.1.3-rc.1 and verify its public JAR, POM and SHA256SUMS assets.
- [x] Installed Windows 0.1.7 passed all 16 UI checks; reviewed built-in preview bytes matched the three submitted documents.
- [x] Submit one Letter PDF to the laser, one 4 × 6-inch 300 dpi ZPL and one matching PDF to the Zebra through the installed pipe/device API/shared generator; all reached SPOOLED with the original paired database retained.
- [x] User confirmed the Letter laser page and the Zebra label containing the barcode, identifying the latter as the built-in ZPL output.
- [x] Correct the Zebra machine driver defaults from 4.09 × 2-inch Thermal Transfer to 4 × 6-inch Thermal Direct, restore/resume the printer, and confirm one fresh built-in PDF printed correctly. No application code fix was needed.
- [x] Verify published Windows 0.1.7 assets; all three built-in physical paths are confirmed: laser PDF, Zebra ZPL and Zebra PDF.
- [ ] Obtain explicit barcode scan and measured alignment confirmation; successful spooling is not physical acceptance.
- [x] Complete independent review after the five baseline security findings are remediated; current details are in SESSION-STATE.md.
- [ ] Complete remote deployment and production S3/IAM qualification; local native acceptance and isolated storage tests do not establish these.
+16 -3
View File
@@ -4,7 +4,7 @@
<parent><groupId>com.kingsrook</groupId><artifactId>qbit-build-parent</artifactId><version>2.0.0</version><relativePath/></parent>
<groupId>com.kingsrook.qbits</groupId>
<artifactId>qbit-printing</artifactId>
<version>0.1.2-rc.1</version>
<version>0.2.0-rc.1</version>
<name>QQQ Printing</name>
<licenses><license><name>Apache License, Version 2.0</name><url>https://www.apache.org/licenses/LICENSE-2.0</url></license></licenses>
<properties>
@@ -22,14 +22,26 @@
<dependencies>
<dependency><groupId>com.kingsrook.qqq</groupId><artifactId>qqq-backend-core</artifactId><version>${qqq.version}</version></dependency>
<dependency><groupId>com.kingsrook.qqq</groupId><artifactId>qqq-backend-module-rdbms</artifactId><version>${qqq.version}</version></dependency>
<dependency><groupId>com.kingsrook.qqq</groupId><artifactId>qqq-backend-module-filesystem</artifactId><version>${qqq.version}</version></dependency>
<dependency><groupId>com.kingsrook.qqq</groupId><artifactId>qqq-middleware-javalin</artifactId><version>${qqq.version}</version></dependency>
<dependency><groupId>com.h2database</groupId><artifactId>h2</artifactId><version>2.3.232</version><scope>runtime</scope></dependency>
<!-- H2 2.4.240 fixes close-time compaction data loss (upstream #4247 / #4249). -->
<dependency><groupId>com.h2database</groupId><artifactId>h2</artifactId><version>2.4.240</version><scope>runtime</scope></dependency>
<dependency><groupId>org.junit.jupiter</groupId><artifactId>junit-jupiter</artifactId><version>6.0.1</version><scope>test</scope></dependency>
</dependencies>
<profiles><profile><id>ui-demo</id><dependencies>
<dependency><groupId>com.kingsrook.qqq</groupId><artifactId>qqq-frontend-next</artifactId><version>1.0.0-RC.37</version><scope>runtime</scope></dependency>
</dependencies></profile></profiles>
<build><plugins>
<build>
<resources>
<resource><directory>src/main/resources</directory></resource>
<resource>
<directory>${project.basedir}</directory>
<targetPath>META-INF</targetPath>
<includes><include>LICENSE</include><include>NOTICE</include></includes>
<filtering>false</filtering>
</resource>
</resources>
<plugins>
<plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-checkstyle-plugin</artifactId><version>3.3.1</version>
<dependencies><dependency><groupId>com.puppycrawl.tools</groupId><artifactId>checkstyle</artifactId><version>10.12.6</version></dependency></dependencies>
<configuration><configLocation>checkstyle/config.xml</configLocation><includeTestSourceDirectory>true</includeTestSourceDirectory><consoleOutput>true</consoleOutput><violationSeverity>warning</violationSeverity><failOnViolation>true</failOnViolation></configuration>
@@ -37,6 +49,7 @@
</plugin>
<plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-compiler-plugin</artifactId><version>3.14.1</version></plugin>
<plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-surefire-plugin</artifactId><version>3.5.4</version></plugin>
<plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-jar-plugin</artifactId><version>3.4.2</version><configuration><archive><manifestEntries><Implementation-Version>${project.version}</Implementation-Version></manifestEntries></archive></configuration></plugin>
<plugin><groupId>org.codehaus.mojo</groupId><artifactId>exec-maven-plugin</artifactId><version>3.6.3</version><configuration><mainClass>com.kingsrook.qbits.printing.PrintingDemo</mainClass></configuration></plugin>
</plugins></build>
</project>
@@ -0,0 +1,289 @@
/*
* QQQ - Low-code Application Framework for Engineers.
* Copyright (C) 2021-2025. Kingsrook, LLC
* 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
* contact@kingsrook.com
* https://github.com/Kingsrook/
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.kingsrook.qbits.printing;
import java.sql.Connection;
import java.sql.SQLException;
import java.time.Instant;
import java.util.Set;
/*******************************************************************************
** Tenant-serialized, payload-free resource accounting. Callers use one JDBC
** connection and acquire this lock before device, document or inventory locks.
*******************************************************************************/
final class PrintingAdmission
{
static final long UNKNOWN_UPLOAD_BYTES = 20L * 1024 * 1024;
private static final String ACTIVE = "('QUEUED','CLAIMED','RECEIVED','SUBMITTING')";
/***************************************************************************
** Static SQL helpers only.
***************************************************************************/
private PrintingAdmission()
{
}
/***************************************************************************
** Add accounting without purging old payloads or assuming unknown bytes zero.
***************************************************************************/
static void initialize(Connection connection, String tenant) throws SQLException
{
for(String sql : new String[] {
"ALTER TABLE printing_document_orphan ADD COLUMN IF NOT EXISTS device_id VARCHAR(36)",
"ALTER TABLE printing_document_orphan ADD COLUMN IF NOT EXISTS content_length BIGINT",
"ALTER TABLE printing_document_orphan ADD COLUMN IF NOT EXISTS idempotency_key VARCHAR(300)",
"CREATE TABLE IF NOT EXISTS printing_resource_usage (tenant_id VARCHAR(200) NOT NULL, device_id VARCHAR(36) NOT NULL, retained_bytes BIGINT NOT NULL, PRIMARY KEY(tenant_id,device_id))",
"CREATE TABLE IF NOT EXISTS printing_admission_event (id VARCHAR(36) PRIMARY KEY, tenant_id VARCHAR(200) NOT NULL, device_id VARCHAR(36), created_at VARCHAR(40) NOT NULL)",
"CREATE INDEX IF NOT EXISTS printing_admission_tenant_time_idx ON printing_admission_event(tenant_id,created_at)",
"CREATE INDEX IF NOT EXISTS printing_admission_device_time_idx ON printing_admission_event(tenant_id,device_id,created_at)",
"CREATE INDEX IF NOT EXISTS printing_job_outstanding_tenant_idx ON printing_job(tenant_id,status,content_length)",
"CREATE INDEX IF NOT EXISTS printing_job_outstanding_device_idx ON printing_job(tenant_id,device_id,status,content_length)",
"CREATE INDEX IF NOT EXISTS printing_orphan_device_idx ON printing_document_orphan(tenant_id,device_id)",
"CREATE INDEX IF NOT EXISTS printing_orphan_key_idx ON printing_document_orphan(tenant_id,idempotency_key)",
"CREATE INDEX IF NOT EXISTS printing_printer_inventory_idx ON printing_printer(device_id,available)",
"CREATE INDEX IF NOT EXISTS printing_printer_owner_idx ON printing_printer(tenant_id,device_id,id)"
})
{
execute(connection, sql);
}
initializeTenant(connection, tenant);
}
/***************************************************************************
** Existing schema may serve newly configured tenants without another DDL run.
***************************************************************************/
static void initializeTenant(Connection connection, String tenant) throws SQLException
{
connection.setAutoCommit(false);
if(number(connection, "SELECT COUNT(*) FROM printing_resource_usage WHERE tenant_id=? AND device_id=''", tenant) == 0)
{
try
{
execute(connection, "INSERT INTO printing_resource_usage VALUES (?, '', 0)", tenant);
}
catch(SQLException exception)
{
if(!"23505".equals(exception.getSQLState()))
{
throw exception;
}
connection.rollback();
connection.setAutoCommit(true);
return;
}
try
{
lock(connection, tenant);
long bytes = number(connection, "SELECT COALESCE(SUM(content_length),0) FROM printing_job WHERE tenant_id=? AND content_available=1", tenant)
+ orphanBytes(connection, tenant, null);
execute(connection, "UPDATE printing_resource_usage SET retained_bytes=? WHERE tenant_id=? AND device_id=''", bytes, tenant);
execute(connection, "INSERT INTO printing_resource_usage (tenant_id,device_id,retained_bytes) SELECT d.tenant_id,d.id,COALESCE((SELECT SUM(j.content_length) FROM printing_job j WHERE j.tenant_id=d.tenant_id AND j.device_id=d.id AND j.content_available=1),0)+COALESCE((SELECT SUM(COALESCE(o.content_length,20971520)) FROM printing_document_orphan o WHERE o.tenant_id=d.tenant_id AND o.device_id=d.id AND NOT EXISTS(SELECT 1 FROM printing_job j WHERE j.id=o.id)),0) FROM printing_device d WHERE d.tenant_id=?", tenant);
String cutoff = Instant.now().minusSeconds(3600).toString();
execute(connection, "INSERT INTO printing_admission_event SELECT id,tenant_id,device_id,created_at FROM printing_job WHERE tenant_id=? AND created_at>=?", tenant, cutoff);
execute(connection, "INSERT INTO printing_admission_event SELECT o.id,o.tenant_id,o.device_id,o.created_at FROM printing_document_orphan o WHERE o.tenant_id=? AND o.created_at>=? AND NOT EXISTS(SELECT 1 FROM printing_admission_event a WHERE a.id=o.id)", tenant, cutoff);
connection.commit();
}
catch(Exception exception)
{
connection.rollback();
throw exception;
}
finally
{
connection.setAutoCommit(true);
}
}
else
{
connection.commit();
connection.setAutoCommit(true);
}
}
/***************************************************************************
** Shared lock serializes capacity decisions across devices and processes.
***************************************************************************/
static void lock(Connection connection, String tenant) throws SQLException
{
try(var statement = connection.prepareStatement("SELECT retained_bytes FROM printing_resource_usage WHERE tenant_id=? AND device_id='' FOR UPDATE"))
{
statement.setString(1, tenant);
try(var rows = statement.executeQuery())
{
if(!rows.next())
{
throw new SQLException("Printing admission accounting has not been initialized");
}
}
}
}
/***************************************************************************
** Admission precedes every upload/inline insert; rollback restores all usage.
***************************************************************************/
static void reserve(Connection connection, String tenant, String device, String id, int bytes, PrintingAdmissionLimits limits) throws SQLException
{
if(number(connection, "SELECT COUNT(*) FROM printing_resource_usage WHERE tenant_id=? AND device_id=?", tenant, device) == 0)
{
execute(connection, "INSERT INTO printing_resource_usage VALUES (?, ?, 0)", tenant, device);
}
String cutoff = Instant.now().minusSeconds(3600).toString();
execute(connection, "DELETE FROM printing_admission_event WHERE tenant_id=? AND created_at<?", tenant, cutoff);
checkScope(connection, tenant, null, bytes, limits.tenantOutstandingJobs(), limits.tenantOutstandingBytes(), limits.tenantRetainedBytes(), limits.tenantJobsPerHour(), cutoff);
checkScope(connection, tenant, device, bytes, limits.deviceOutstandingJobs(), limits.deviceOutstandingBytes(), limits.deviceRetainedBytes(), limits.deviceJobsPerHour(), cutoff);
execute(connection, "UPDATE printing_resource_usage SET retained_bytes=retained_bytes+? WHERE tenant_id=? AND device_id IN ('',?)", bytes, tenant, device);
execute(connection, "INSERT INTO printing_admission_event VALUES (?,?,?,?)", id, tenant, device, Instant.now().toString());
}
/***************************************************************************
** SQL aggregates stay bounded by active capacity and the rolling hour index.
***************************************************************************/
private static void checkScope(Connection connection, String tenant, String device, int bytes, long jobLimit, long activeByteLimit, long retainedLimit, long hourlyLimit, String cutoff) throws SQLException
{
String predicate = "tenant_id=?" + (device == null ? "" : " AND device_id=?");
String outstanding = "SELECT content_length FROM printing_job WHERE " + predicate + " AND status IN " + ACTIVE
+ " UNION ALL SELECT COALESCE(content_length,20971520) FROM printing_document_orphan o WHERE " + predicate + " AND NOT EXISTS(SELECT 1 FROM printing_job j WHERE j.id=o.id)";
Object[] bothScopes = device == null ? new Object[] {tenant, tenant} : new Object[] {tenant, device, tenant, device};
long jobs = number(connection, "SELECT COUNT(*) FROM (" + outstanding + ") outstanding", bothScopes);
long activeBytes = number(connection, "SELECT COALESCE(SUM(content_length),0) FROM (" + outstanding + ") outstanding", bothScopes);
long retained = number(connection, "SELECT retained_bytes FROM printing_resource_usage WHERE tenant_id=? AND device_id=?", tenant, device == null ? "" : device);
Object[] rateScope = device == null ? new Object[] {tenant, cutoff} : new Object[] {tenant, device, cutoff};
long rate = number(connection, "SELECT COUNT(*) FROM printing_admission_event WHERE " + predicate + " AND created_at>=?", rateScope);
String scopeName = device == null ? "tenant" : "device";
if(jobs >= jobLimit || bytes > activeByteLimit || activeBytes > activeByteLimit - bytes)
{
throw new PrintingException(429, "The " + scopeName + " outstanding print-job capacity is full; wait for existing work or ask an administrator to adjust admission limits");
}
if(bytes > retainedLimit || retained > retainedLimit - bytes)
{
throw new PrintingException(429, "The " + scopeName + " retained print-document capacity is full; review retention and storage capacity before retrying");
}
if(rate >= hourlyLimit)
{
throw new PrintingException(429, "The " + scopeName + " hourly print-job admission limit is reached; retry later using the same request identity");
}
}
/***************************************************************************
** Failed upload reservations stay charged until exact confirmed removal.
***************************************************************************/
private static long orphanBytes(Connection connection, String tenant, String device) throws SQLException
{
String sql = "SELECT COALESCE(SUM(COALESCE(content_length,20971520)),0) FROM printing_document_orphan o WHERE tenant_id=?"
+ (device == null ? "" : " AND device_id=?") + " AND NOT EXISTS(SELECT 1 FROM printing_job j WHERE j.id=o.id)";
return (device == null ? number(connection, sql, tenant) : number(connection, sql, tenant, device));
}
/***************************************************************************
** Release only after deletion; an inconsistent counter fails closed.
***************************************************************************/
static void release(Connection connection, String tenant, String device, long bytes) throws SQLException
{
int expected = device == null ? 1 : 2;
String predicate = device == null ? "device_id=''" : "device_id IN ('',?)";
Object[] values = device == null ? new Object[] {bytes, tenant, bytes} : new Object[] {bytes, tenant, device, bytes};
if(execute(connection, "UPDATE printing_resource_usage SET retained_bytes=retained_bytes-? WHERE tenant_id=? AND " + predicate + " AND retained_bytes>=?", values) != expected)
{
throw new SQLException("Printing retained-byte accounting requires administrator reconciliation");
}
}
/***************************************************************************
** Cumulative IDs cannot bypass limits by rotating successive snapshots.
***************************************************************************/
static void inventory(Connection connection, String tenant, String device, Set<String> incoming, PrintingAdmissionLimits limits) throws SQLException
{
int additions = 0;
for(String id : incoming)
{
if(number(connection, "SELECT COUNT(*) FROM printing_printer WHERE tenant_id=? AND device_id=? AND printer_id=?", tenant, device, id) == 0)
{
additions++;
}
}
if(additions > 0 && (number(connection, "SELECT COUNT(*) FROM printing_printer WHERE tenant_id=? AND device_id=?", tenant, device) > limits.devicePrinters() - additions
|| number(connection, "SELECT COUNT(*) FROM printing_printer WHERE tenant_id=?", tenant) > limits.tenantPrinters() - additions))
{
throw new PrintingException(429, "Printer history capacity is full; existing printers remain available to update. Ask an administrator to review the cumulative inventory limit");
}
}
/***************************************************************************
** Read one scalar; never materialize payloads or an unbounded row list.
***************************************************************************/
private static long number(Connection connection, String sql, Object... values) throws SQLException
{
try(var statement = connection.prepareStatement(sql))
{
for(int index = 0; index < values.length; index++)
{
statement.setObject(index + 1, values[index]);
}
try(var rows = statement.executeQuery())
{
if(!rows.next())
{
throw new SQLException("Missing printing resource accounting row");
}
return (rows.getLong(1));
}
}
}
/***************************************************************************
** All identifiers are fixed SQL; only values come from callers.
***************************************************************************/
private static int execute(Connection connection, String sql, Object... values) throws SQLException
{
try(var statement = connection.prepareStatement(sql))
{
for(int index = 0; index < values.length; index++)
{
statement.setObject(index + 1, values[index]);
}
return (statement.executeUpdate());
}
}
}
@@ -0,0 +1,54 @@
/*
* QQQ - Low-code Application Framework for Engineers.
* Copyright (C) 2021-2025. Kingsrook, LLC
* 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
* contact@kingsrook.com
* https://github.com/Kingsrook/
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.kingsrook.qbits.printing;
/*******************************************************************************
** Host-configurable logical resource ceilings, independent of retention age.
*******************************************************************************/
public record PrintingAdmissionLimits(int deviceOutstandingJobs, int tenantOutstandingJobs,
long deviceOutstandingBytes, long tenantOutstandingBytes, long deviceRetainedBytes, long tenantRetainedBytes,
int deviceJobsPerHour, int tenantJobsPerHour, int devicePrinters, int tenantPrinters)
{
/***************************************************************************
** Never silently disable a security boundary through zero/negative limits.
***************************************************************************/
public PrintingAdmissionLimits
{
if(deviceOutstandingJobs < 1 || tenantOutstandingJobs < 1 || deviceOutstandingBytes < 1 || tenantOutstandingBytes < 1
|| deviceRetainedBytes < 1 || tenantRetainedBytes < 1 || deviceJobsPerHour < 1 || tenantJobsPerHour < 1 || devicePrinters < 1 || tenantPrinters < 1)
{
throw new IllegalArgumentException("Printing admission limits must all be positive");
}
}
/***************************************************************************
** Capacity must be sized for document sizes and the deployment's retention.
***************************************************************************/
public static PrintingAdmissionLimits defaults()
{
long gibibyte = 1024L * 1024 * 1024;
return (new PrintingAdmissionLimits(10_000, 100_000, 10 * gibibyte, 100 * gibibyte,
2048 * gibibyte, 20_480 * gibibyte, 2_000, 20_000, 1_000, 20_000));
}
}
@@ -0,0 +1,132 @@
/*
* QQQ - Low-code Application Framework for Engineers.
* Copyright (C) 2021-2025. Kingsrook, LLC
* 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
* contact@kingsrook.com
* https://github.com/Kingsrook/
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.kingsrook.qbits.printing;
import java.util.List;
import java.util.Set;
import com.kingsrook.qqq.backend.core.exceptions.QException;
import com.kingsrook.qqq.backend.core.exceptions.QPermissionDeniedException;
import com.kingsrook.qqq.backend.core.model.actions.tables.query.QCriteriaOperator;
import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterCriteria;
import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterOrderBy;
import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryInput;
import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryJoin;
import com.kingsrook.qqq.backend.core.model.data.QRecord;
import org.json.JSONArray;
import org.json.JSONObject;
/** Secondary proof binds a device to the already authenticated native QQQ principal. */
public final class PrintingAgentAuthorization
{
public static final String DEVICE_HEADER = "X-QQQ-Device-Id";
public static final String TOKEN_HEADER = "X-QQQ-Device-Token";
/** No independent authentication module or permanent service user. */
private PrintingAgentAuthorization()
{
}
/** Bind only on the explicit endpoint; all ordinary requests require the existing owner. */
public static String device(String id, String token, boolean bind) throws Exception
{
String principal = PrintingControlAuthorization.principal();
PrintingControlAuthorization.record(PrintingTables.DEVICE, id);
PrintingProcesses.currentService().authorizeAgent(id, token, principal, bind);
return (id);
}
/** Resolve a wire printer identity through native row security, not a raw SQL lookup. */
static QRecord printer(String device, String printer) throws QException
{
List<QRecord> rows = PrintingControlAuthorization.query(new QueryInput().withTableName(PrintingTables.PRINTER)
.withFilter(new QQueryFilter(new QFilterCriteria("device_id", QCriteriaOperator.EQUALS, device))
.withCriteria(new QFilterCriteria("printer_id", QCriteriaOperator.EQUALS, printer)).withLimit(1))).getRecords();
if(rows.isEmpty())
{
throw new QPermissionDeniedException("Printer is not accessible");
}
return (PrintingControlAuthorization.record(PrintingTables.PRINTER, rows.getFirst().getValueString("id")));
}
/** Inventory absence updates existing rows too, so authorize the complete bounded inventory. */
static Set<String> inventory(String device) throws Exception
{
Set<String> authorized = new java.util.HashSet<>();
String cursor = null;
do
{
JSONObject page = PrintingProcesses.currentService().printersPage(device, 200, cursor);
JSONArray printers = page.getJSONArray("printers");
for(int index = 0; index < printers.length(); index++)
{
authorized.add(printer(device, printers.getJSONObject(index).getString("printerId")).getValueString("id"));
if(authorized.size() > 10000)
{
throw new PrintingException(429, "Inventory exceeds the bounded native review limit");
}
}
cursor = page.isNull("nextCursor") ? null : page.getString("nextCursor");
}
while(cursor != null);
// Even an empty inventory must have native table READ access.
PrintingControlAuthorization.query(new QueryInput().withTableName(PrintingTables.PRINTER)
.withFilter(new QQueryFilter(new QFilterCriteria("device_id", QCriteriaOperator.EQUALS, device)).withLimit(1)));
return (authorized);
}
/** Select with native row security, then dispatch only that exact authorized identity. */
static JSONObject claim(String device) throws Exception
{
QQueryFilter formats = new QQueryFilter().withBooleanOperator(QQueryFilter.BooleanOperator.OR);
for(String format : List.of("PDF", "ZPL"))
{
formats.withSubFilter(new QQueryFilter(new QFilterCriteria("format", QCriteriaOperator.EQUALS, format))
.withCriteria(new QFilterCriteria(PrintingTables.PRINTER + ".formats", QCriteriaOperator.CONTAINS, "\"" + format + "\"")));
}
List<QRecord> rows = PrintingControlAuthorization.query(new QueryInput().withTableName(PrintingTables.JOB)
.withQueryJoin(new QueryJoin(PrintingTables.PRINTER))
.withFilter(new QQueryFilter(new QFilterCriteria("device_id", QCriteriaOperator.EQUALS, device))
.withCriteria(new QFilterCriteria("status", QCriteriaOperator.IN, List.of("QUEUED", "CLAIMED")))
.withCriteria(new QFilterCriteria(PrintingTables.PRINTER + ".enabled", QCriteriaOperator.EQUALS, 1))
.withCriteria(new QFilterCriteria(PrintingTables.PRINTER + ".available", QCriteriaOperator.EQUALS, 1))
.withSubFilter(formats)
.withOrderBy(new QFilterOrderBy("created_at", true)).withOrderBy(new QFilterOrderBy("id", true)).withLimit(20))).getRecords();
for(QRecord row : rows)
{
String id = row.getValueString("id");
PrintingControlAuthorization.job(device, id);
JSONObject result = PrintingProcesses.currentService().claimForJob(device, id);
if(!result.isNull("job"))
{
return (result);
}
}
return (new JSONObject().put("job", JSONObject.NULL));
}
}
@@ -0,0 +1,185 @@
/*
* QQQ - Low-code Application Framework for Engineers.
* Copyright (C) 2021-2025. Kingsrook, LLC
* 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
* contact@kingsrook.com
* https://github.com/Kingsrook/
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.kingsrook.qbits.printing;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import com.kingsrook.qqq.middleware.javalin.schemabuilder.ToSchema;
import com.kingsrook.qqq.openapi.model.Schema;
import com.kingsrook.qqq.openapi.model.Type;
/** Explicit typed native request/response contracts, namespaced independently from core schemas. */
final class PrintingApiSchemas
{
/** Static schema definitions. */
private PrintingApiSchemas()
{
}
/** Shared wire components describe every field; no opaque JSON blob substitutes for a contract. */
static Map<String, Schema> components()
{
Map<String, Schema> schemas = new LinkedHashMap<>();
add(schemas, "Empty", fields());
add(schemas, "Acknowledgment", fields("accepted", bool()), "accepted");
add(schemas, "Session", fields("principalId", text(200), "tenantId", text(200), "deviceId", id()), "principalId", "tenantId");
add(schemas, "EnrollmentRequest", fields("enrollmentCode", text(128), "deviceName", text(1024), "agentVersion", text(100)), "enrollmentCode", "deviceName", "agentVersion");
add(schemas, "Enrollment", fields("protocolVersion", number(), "deviceId", id(), "deviceToken", text(128).withDescription("Private device proof, returned once; never log."), "pollIntervalSeconds", number()), "protocolVersion", "deviceId", "deviceToken", "pollIntervalSeconds");
add(schemas, "Profile", fields("name", text(512).withNullable(true), "description", text(4096).withNullable(true), "location", text(512).withNullable(true)));
add(schemas, "HeartbeatRequest", fields("agentVersion", text(100), "profile", ref("Profile")), "agentVersion");
add(schemas, "Heartbeat", fields("serverTime", time()), "serverTime");
add(schemas, "Printer", fields("printerId", id(), "name", text(1024), "driverName", text(1024), "portName", text(1024), "status", enumeration("READY", "OFFLINE", "PAUSED", "ERROR", "UNKNOWN"), "formats", array(enumeration("PDF", "ZPL")), "displayName", text(512), "description", text(4096), "location", text(512)), "printerId", "name", "formats");
add(schemas, "InventoryRequest", fields("printers", array(ref("Printer"))), "printers");
add(schemas, "Options", fields("copies", number(), "scale", enumeration("ACTUAL_SIZE", "FIT"), "paperWidthMm", new Schema().withType(Type.NUMBER), "paperHeightMm", new Schema().withType(Type.NUMBER)));
add(schemas, "Job", fields("jobId", id(), "deviceId", id(), "printerId", id(), "title", text(1024), "format", enumeration("PDF", "ZPL"), "contentSha256", text(64), "contentLength", number(), "options", ref("Options"), "createdAt", time(), "status", enumeration("QUEUED", "CLAIMED", "RECEIVED", "SUBMITTING", "SPOOLED", "SPOOLER_COMPLETED", "FAILED", "OUTCOME_UNKNOWN"), "message", text(2048), "spoolerJobId", id()), "jobId", "deviceId", "printerId", "title", "format", "contentSha256", "contentLength", "options", "createdAt", "status");
add(schemas, "Claim", fields("job", ref("Job").withNullable(true)), "job");
add(schemas, "Jobs", fields("jobs", array(ref("Job"))), "jobs");
add(schemas, "EventRequest", fields("eventId", id(), "status", enumeration("RECEIVED", "SUBMITTING", "SPOOLED", "SPOOLER_COMPLETED", "FAILED", "OUTCOME_UNKNOWN"), "message", text(2048), "spoolerJobId", id()), "eventId", "status");
add(schemas, "TestRequest", fields("requestId", id(), "printerId", id(), "format", enumeration("PDF", "ZPL"), "testProfile", text(40)), "requestId", "printerId", "format");
add(schemas, "RetryRequest", fields("requestId", id(), "confirmDuplicateRisk", bool()), "requestId");
add(schemas, "DesiredState", fields("revision", number(), "dispatchPaused", bool(), "connectionState", enumeration("CONNECTED", "DISCONNECTED")), "revision", "dispatchPaused", "connectionState");
add(schemas, "ControlPollRequest", fields("controlVersion", number(), "agentVersion", text(100), "capabilities", array(enumeration("REFRESH_INVENTORY", "CANCEL_SPOOL")), "lastAppliedRevision", number()), "controlVersion", "agentVersion", "capabilities", "lastAppliedRevision");
add(schemas, "Command", fields("commandId", id(), "requestId", id(), "action", enumeration("REFRESH_INVENTORY", "CANCEL_SPOOL"), "createdAt", time(), "expiresAt", time(), "jobId", id()), "commandId", "requestId", "action", "createdAt", "expiresAt");
add(schemas, "ControlPoll", fields("controlVersion", number(), "serverTime", time(), "pollIntervalSeconds", number(), "desiredState", ref("DesiredState"), "commands", array(ref("Command"))), "controlVersion", "serverTime", "pollIntervalSeconds", "desiredState", "commands");
add(schemas, "ReceiptRequest", fields("receiptId", id(), "outcome", enumeration("INVENTORY_REFRESHED", "CANCEL_REQUESTED", "ALREADY_ABSENT", "OWNERSHIP_MISMATCH", "UNSUPPORTED", "FAILED", "EXPIRED", "OUTCOME_UNKNOWN"), "completedAt", time(), "message", text(1024)), "receiptId", "outcome", "completedAt");
Schema actions = enumeration("PAUSE_DISPATCH", "RESUME_DISPATCH", "DISCONNECT", "RECONNECT", "REVOKE", "REFRESH_INVENTORY", "CLEAR_QUEUE", "CANCEL_SPOOL");
add(schemas, "ActionRequest", fields("requestId", id(), "issuedAt", time(), "action", actions, "jobId", id()), "requestId", "issuedAt", "action");
add(schemas, "Action", fields("commandId", id(), "requestId", id(), "issuedAt", time(), "deviceId", id(), "action", actions, "status", enumeration("PENDING", "SUCCEEDED", "FAILED", "EXPIRED", "OUTCOME_UNKNOWN"), "createdAt", time(), "expiresAt", time(), "jobId", id(), "resultCode", text(80), "cancelledJobCount", number(), "receipt", ref("ReceiptRequest")), "commandId", "requestId", "issuedAt", "deviceId", "action", "status", "createdAt", "expiresAt");
add(schemas, "Actions", fields("commands", array(ref("Action")), "nextCursor", text(128).withNullable(true)), "commands", "nextCursor");
return (schemas);
}
/** Every schema has the extension prefix required by the native registry. */
static String name(String shortName)
{
return ("Printing" + shortName + "V1");
}
/** Refer to one typed reusable component. */
static Schema ref(String name)
{
return (new Schema().withRefToSchema(name(name)));
}
/** Bounded Unicode text. */
static Schema text(int limit)
{
return (new Schema().withType(Type.STRING).withMaxLength(limit));
}
/** SchemaBuilder customization retains explicit required fields unsupported by the base RC20 model. */
private record Shape(Map<String, Schema> properties, List<String> required) implements ToSchema
{
@Override
public Schema toSchema()
{
return (new RequiredSchema(required).withType(Type.OBJECT).withProperties(properties));
}
}
/** Required is a standard OpenAPI keyword missing from RC20's base Schema bean. */
public static class RequiredSchema extends Schema
{
private final List<String> required;
/** Retain the explicit protocol field requirements. */
public RequiredSchema(List<String> required)
{
this.required = required;
}
/** Published by the core Jackson schema serializer. */
public List<String> getRequired()
{
return (required);
}
}
/** Build typed object fields without map arity limits. */
private static Map<String, Schema> fields(Object... pairs)
{
Map<String, Schema> fields = new LinkedHashMap<>();
for(int index = 0; index < pairs.length; index += 2)
{
fields.put((String) pairs[index], (Schema) pairs[index + 1]);
}
return (fields);
}
/** Publish a customized typed schema. */
private static void add(Map<String, Schema> target, String name, Map<String, Schema> properties, String... required)
{
target.put(name(name), new Shape(properties, List.of(required)).toSchema());
}
/** Protocol identifier. */
private static Schema id()
{
return (text(128));
}
/** UTC wire timestamp. */
private static Schema time()
{
return (text(40).withFormat("date-time").withDescription("RFC3339 UTC ending in uppercase Z."));
}
/** Exact JSON integer, never a stringified numeric value. */
private static Schema number()
{
return (new Schema().withType(Type.INTEGER));
}
/** Required booleans must never be inferred from missing fields. */
private static Schema bool()
{
return (new Schema().withType(Type.BOOLEAN));
}
/** Closed action or status vocabulary. */
private static Schema enumeration(String... values)
{
return (new Schema().withType(Type.STRING).withEnumValues(List.of(values)));
}
/** Homogeneous typed arrays. */
private static Schema array(Schema items)
{
return (new Schema().withType(Type.ARRAY).withItems(items));
}
}
@@ -0,0 +1,139 @@
/*
* QQQ - Low-code Application Framework for Engineers.
* Copyright (C) 2021-2025. Kingsrook, LLC
* 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
* contact@kingsrook.com
* https://github.com/Kingsrook/
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.kingsrook.qbits.printing;
import java.time.Instant;
import java.time.format.DateTimeParseException;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.Set;
import com.kingsrook.qqq.backend.core.actions.customizers.TableCustomizerInterface;
import com.kingsrook.qqq.backend.core.actions.permissions.PermissionEnforcement;
import com.kingsrook.qqq.backend.core.actions.tables.QueryAction;
import com.kingsrook.qqq.backend.core.exceptions.QException;
import com.kingsrook.qqq.backend.core.model.actions.tables.QueryOrGetInputInterface;
import com.kingsrook.qqq.backend.core.model.actions.tables.query.QCriteriaOperator;
import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryInput;
import com.kingsrook.qqq.backend.core.model.data.QRecord;
/*******************************************************************************
** Effective command status never requires an offline device to poll again.
** Recorded status and durable receipts remain unchanged by native reads.
*******************************************************************************/
public class PrintingCommandStatus implements TableCustomizerInterface
{
private static final Set<String> DEPENDENCIES = Set.of("id", "status", "expires_at");
private static final Set<String> TERMINAL = Set.of("SUCCEEDED", "FAILED", "EXPIRED", "OUTCOME_UNKNOWN");
/***************************************************************************
** Enrich only the requested virtual field, preserving the caller's projection.
***************************************************************************/
@Override
public List<QRecord> postQuery(QueryOrGetInputInterface input, List<QRecord> records) throws QException
{
Set<String> selected = input instanceof QueryInput query ? query.getFieldNamesToInclude() : null;
if(selected != null && !selected.contains("command_status"))
{
return (records);
}
if(selected != null && !selected.contains("id"))
{
throw new QException("Select id with derived command status");
}
Map<String, QRecord> dependencies = dependencies(records);
Instant now = Instant.now();
for(QRecord record : records)
{
QRecord values = dependencies.getOrDefault(record.getValueString("id"), record);
record.setValue("command_status", effective(values, now));
}
return (records);
}
/***************************************************************************
** Dependency-only native queries preserve permissions and tenant locks.
** They are bounded by the selected IDs and cannot recurse into enrichment.
***************************************************************************/
private static Map<String, QRecord> dependencies(List<QRecord> records) throws QException
{
ArrayList<String> ids = new ArrayList<>();
for(QRecord record : records)
{
if(!record.getValues().keySet().containsAll(DEPENDENCIES) && record.getValueString("id") != null)
{
ids.add(record.getValueString("id"));
}
}
Map<String, QRecord> result = new HashMap<>();
for(int first = 0; first < ids.size(); first += 200)
{
List<String> page = ids.subList(first, Math.min(first + 200, ids.size()));
QueryInput input = new QueryInput().withTableName(PrintingTables.COMMAND).withFieldNamesToInclude(DEPENDENCIES)
.withFilter(new QQueryFilter().withCriteria("id", QCriteriaOperator.IN, page).withLimit(page.size()));
input.setPermissionEnforcement(PermissionEnforcement.ENFORCE);
for(QRecord row : new QueryAction().execute(input).getRecords())
{
result.put(row.getValueString("id"), row);
}
}
return (result);
}
/***************************************************************************
** A terminal receipt wins; a pending command needs a valid expiry observation.
***************************************************************************/
static String effective(QRecord record, Instant now)
{
String status = record.getValueString("status");
if(status != null && TERMINAL.contains(status))
{
return (status);
}
if(!"PENDING".equals(status))
{
return ("UNKNOWN");
}
String expiresAt = record.getValueString("expires_at");
if(expiresAt == null || expiresAt.isBlank())
{
return ("UNKNOWN");
}
try
{
return (Instant.parse(expiresAt).isBefore(now) ? "EXPIRED" : "PENDING");
}
catch(DateTimeParseException exception)
{
return ("UNKNOWN");
}
}
}
@@ -0,0 +1,186 @@
/*
* QQQ - Low-code Application Framework for Engineers.
* Copyright (C) 2021-2025. Kingsrook, LLC
* 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
* contact@kingsrook.com
* https://github.com/Kingsrook/
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.kingsrook.qbits.printing;
import java.util.Set;
import com.kingsrook.qqq.backend.core.actions.permissions.PermissionEnforcement;
import com.kingsrook.qqq.backend.core.actions.permissions.PermissionsHelper;
import com.kingsrook.qqq.backend.core.actions.tables.GetAction;
import com.kingsrook.qqq.backend.core.actions.tables.QueryAction;
import com.kingsrook.qqq.backend.core.context.QContext;
import com.kingsrook.qqq.backend.core.exceptions.QAuthenticationException;
import com.kingsrook.qqq.backend.core.exceptions.QException;
import com.kingsrook.qqq.backend.core.exceptions.QPermissionDeniedException;
import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepInput;
import com.kingsrook.qqq.backend.core.model.actions.tables.get.GetInput;
import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryInput;
import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryOutput;
import com.kingsrook.qqq.backend.core.model.data.QRecord;
import org.json.JSONObject;
/** Common current-user authorization for native UI and semantic API management. */
public final class PrintingControlAuthorization
{
/** Static authorization facade. */
private PrintingControlAuthorization()
{
}
/** Core user references, never emails or request-body identity, determine attribution. */
public static String principal() throws QException
{
if(QContext.getQSession() == null || QContext.getQSession().getUser() == null
|| QContext.getQSession().getUser().getIdReference() == null || QContext.getQSession().getUser().getIdReference().isBlank())
{
throw new QAuthenticationException("Sign in to continue");
}
new PrintingAdminPermission().checkPermissionsThrowing(new RunBackendStepInput(), null);
PrintingProcesses.currentService();
return (QContext.getQSession().getUser().getIdReference());
}
/** Native GetAction applies table access, field protection, and current record security. */
public static QRecord record(String table, String id) throws QException
{
principal();
if(id == null || id.isBlank())
{
throw new QPermissionDeniedException("Record is not accessible");
}
GetInput input = new GetInput();
input.setTableName(table);
input.setPrimaryKey(id);
input.setPermissionEnforcement(PermissionEnforcement.ENFORCE);
QRecord row = new GetAction().execute(input).getRecord();
if(row == null)
{
throw new QPermissionDeniedException("Record is not accessible");
}
return (row);
}
/** Operations without an existing row still require native table read authority. */
public static void table(String table) throws QException
{
principal();
query(new QueryInput().withTableName(table).withFilter(new QQueryFilter().withLimit(1)));
}
/** Explicit enforcement remains effective inside native process action scopes. */
static QueryOutput query(QueryInput input) throws QException
{
input.setPermissionEnforcement(PermissionEnforcement.ENFORCE);
return (new QueryAction().execute(input));
}
/** A job operation must also authorize its device and exact printer record. */
public static QRecord job(String deviceId, String jobId) throws QException
{
QRecord row = record(PrintingTables.JOB, jobId);
if(!deviceId.equals(row.getValueString("device_id")))
{
throw new QPermissionDeniedException("Job is not assigned to this device");
}
record(PrintingTables.DEVICE, deviceId);
QRecord printer = record(PrintingTables.PRINTER, row.getValueString("printer_row_id"));
if(!deviceId.equals(printer.getValueString("device_id")))
{
throw new QPermissionDeniedException("Printer is not assigned to this device");
}
return (row);
}
/** The native process permission remains the domain write authority; generic table writes stay disabled. */
public static void process(String name) throws QException
{
principal();
PermissionsHelper.checkProcessPermissionThrowing(new RunBackendStepInput().withProcessName(name), name);
}
/** Current users can manage authorized devices without impersonating the enrolled agent owner. */
public static JSONObject deviceAction(String deviceId, JSONObject request) throws Exception
{
String actor = principal();
record(PrintingTables.DEVICE, deviceId);
PrintingDeviceProcesses.Action selected = null;
for(PrintingDeviceProcesses.Action action : PrintingDeviceProcesses.Action.values())
{
if(action.wire.equals(request.optString("action")))
{
selected = action;
}
}
if(selected == null)
{
throw new PrintingException(400, "Invalid device action");
}
process(selected.process);
PrintingService service = PrintingProcesses.currentService();
String existing = service.existingDeviceAction(deviceId, request.optString("requestId"));
if(existing != null)
{
QRecord receipt = record(PrintingTables.COMMAND, existing);
if(receipt.getValueString("job_id") != null)
{
job(deviceId, receipt.getValueString("job_id"));
}
return (service.deviceAction(deviceId, request, actor));
}
Set<String> queue = null;
if("CLEAR_QUEUE".equals(selected.wire))
{
queue = service.queuedJobIdsForControl(deviceId);
Set<String> printers = new java.util.HashSet<>();
for(String id : queue)
{
QRecord queued = record(PrintingTables.JOB, id);
if(!deviceId.equals(queued.getValueString("device_id")))
{
throw new QPermissionDeniedException("Job is not assigned to this device");
}
printers.add(queued.getValueString("printer_row_id"));
}
for(String printerId : printers)
{
QRecord printer = record(PrintingTables.PRINTER, printerId);
if(!deviceId.equals(printer.getValueString("device_id")))
{
throw new QPermissionDeniedException("Printer is not assigned to this device");
}
}
}
if("CANCEL_SPOOL".equals(selected.wire))
{
job(deviceId, request.optString("jobId"));
}
return (service.deviceAction(deviceId, request, actor, queue));
}
}
@@ -46,7 +46,7 @@ public final class PrintingDemo
int port = Integer.parseInt(System.getenv().getOrDefault("QQQ_PRINT_PORT", "18081"));
PrintingService service = new PrintingService(new DriverDataSource(url, "sa", ""), "demo");
service.initialize();
PrintingRoutes routes = new PrintingRoutes(service, context -> MessageDigest.isEqual(adminToken.getBytes(StandardCharsets.UTF_8), PrintingRoutes.bearer(context).getBytes(StandardCharsets.UTF_8)));
PrintingRoutes routes = new PrintingRoutes(service, context -> MessageDigest.isEqual(adminToken.getBytes(StandardCharsets.UTF_8), PrintingRoutes.bearer(context).getBytes(StandardCharsets.UTF_8)), PrintingRoutes.LegacyEnrollment.ENABLED);
Javalin app = Javalin.create(config ->
{
config.http.maxRequestSize = 29 * 1024 * 1024;
@@ -0,0 +1,541 @@
/*
* QQQ - Low-code Application Framework for Engineers.
* Copyright (C) 2021-2025. Kingsrook, LLC
* 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
* contact@kingsrook.com
* https://github.com/Kingsrook/
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.kingsrook.qbits.printing;
import javax.sql.DataSource;
import java.sql.Connection;
import java.sql.SQLException;
import java.time.Instant;
import java.util.List;
import java.util.Set;
import java.util.UUID;
import org.json.JSONArray;
import org.json.JSONObject;
import static com.kingsrook.qbits.printing.PrintingService.query;
import static com.kingsrook.qbits.printing.PrintingService.update;
/** Durable device controls share the device lock with dispatch and submission. */
final class PrintingDeviceControls
{
private static final Set<String> ACTIONS = Set.of("PAUSE_DISPATCH", "RESUME_DISPATCH", "DISCONNECT", "RECONNECT", "REVOKE", "REFRESH_INVENTORY", "CLEAR_QUEUE", "CANCEL_SPOOL");
private static final Set<String> REMOTE = Set.of("REFRESH_INVENTORY", "CANCEL_SPOOL");
private final DataSource source;
private final String tenant;
/** Bind to the same immutable tenant and pool as the queue. */
PrintingDeviceControls(DataSource source, String tenant)
{
this.source = source;
this.tenant = tenant;
}
/** Add compatible default state and a bounded durable command ledger. */
static void initialize(Connection connection) throws SQLException
{
for(String sql : new String[] {
"ALTER TABLE printing_device ADD COLUMN IF NOT EXISTS dispatch_paused INTEGER DEFAULT 0 NOT NULL",
"ALTER TABLE printing_device ADD COLUMN IF NOT EXISTS connection_state VARCHAR(20) DEFAULT 'CONNECTED' NOT NULL",
"ALTER TABLE printing_device ADD COLUMN IF NOT EXISTS control_revision BIGINT DEFAULT 0 NOT NULL",
"ALTER TABLE printing_device ADD COLUMN IF NOT EXISTS control_version INTEGER DEFAULT 0 NOT NULL",
"ALTER TABLE printing_device ADD COLUMN IF NOT EXISTS control_capabilities VARCHAR(200) DEFAULT '[]' NOT NULL",
"ALTER TABLE printing_device ADD COLUMN IF NOT EXISTS control_last_poll_at VARCHAR(40)",
"ALTER TABLE printing_device ADD COLUMN IF NOT EXISTS control_applied_revision BIGINT DEFAULT 0 NOT NULL",
"ALTER TABLE printing_device ADD COLUMN IF NOT EXISTS revoked_at VARCHAR(40)",
"CREATE TABLE IF NOT EXISTS printing_device_command (id VARCHAR(36) PRIMARY KEY, tenant_id VARCHAR(200) NOT NULL, device_id VARCHAR(36) NOT NULL REFERENCES printing_device(id), request_id VARCHAR(128) NOT NULL, action VARCHAR(40) NOT NULL, job_id VARCHAR(36), actor VARCHAR(200) NOT NULL, request_json VARCHAR(2000) NOT NULL, status VARCHAR(40) NOT NULL, created_at VARCHAR(40) NOT NULL, expires_at VARCHAR(40) NOT NULL, result_code VARCHAR(80), cancelled_job_count INTEGER, receipt_json VARCHAR(8000), UNIQUE(tenant_id,device_id,request_id))",
"CREATE INDEX IF NOT EXISTS printing_command_owner_idx ON printing_device_command(tenant_id,device_id,created_at,id)",
"CREATE INDEX IF NOT EXISTS printing_command_pending_idx ON printing_device_command(tenant_id,device_id,status,expires_at)"
})
{
try(var statement = connection.prepareStatement(sql))
{
statement.execute();
}
}
}
/** Pure status projection never returns credential verifiers. */
static JSONObject state(JSONObject row)
{
JSONObject result = new JSONObject().put("supported", row.getInt("control_version") == 1)
.put("capabilities", new JSONArray(row.getString("control_capabilities")))
.put("lastAppliedRevision", row.getLong("control_applied_revision"))
.put("desiredState", new JSONObject().put("revision", row.getLong("control_revision"))
.put("dispatchPaused", row.getInt("dispatch_paused") == 1).put("connectionState", row.getString("connection_state")));
if(row.has("control_last_poll_at"))
{
result.put("lastPollAt", row.getString("control_last_poll_at"));
}
return (result);
}
/** Strict action input and original receipt enforce replay before any side effect. */
JSONObject action(String deviceId, JSONObject request, String actor) throws SQLException
{
return (action(deviceId, request, actor, null));
}
/** A native authorized queue snapshot must still match after taking the device lock. */
JSONObject action(String deviceId, JSONObject request, String actor, Set<String> authorizedQueue) throws SQLException
{
fields(request, Set.of("requestId", "issuedAt", "action", "jobId"));
String requestId = text(request, "requestId", 128);
if(!requestId.matches("[A-Za-z0-9._-]+"))
{
throw new PrintingException(400, "Invalid requestId");
}
String action = text(request, "action", 40);
if(!ACTIONS.contains(action) || request.has("jobId") != "CANCEL_SPOOL".equals(action))
{
throw new PrintingException(400, "Invalid device action");
}
String jobId = "CANCEL_SPOOL".equals(action) ? text(request, "jobId", 36) : null;
if(actor == null || actor.isBlank() || actor.length() > 200)
{
throw new PrintingException(400, "A bounded authenticated actor is required");
}
try(Connection connection = source.getConnection())
{
connection.setAutoCommit(false);
try
{
JSONObject device = lock(connection, deviceId, false);
List<JSONObject> old = query(connection, "SELECT * FROM printing_device_command WHERE tenant_id=? AND device_id=? AND request_id=?", tenant, deviceId, requestId);
if(!old.isEmpty())
{
if(!new JSONObject(old.getFirst().getString("request_json")).similar(request))
{
throw new PrintingException(409, "Request identity was already used for a different action");
}
connection.commit();
return (record(old.getFirst()));
}
Instant issued;
try
{
issued = Instant.parse(utc(request, "issuedAt"));
}
catch(java.time.format.DateTimeParseException exception)
{
throw new PrintingException(400, "Invalid action time");
}
Instant current = Instant.now();
if(issued.isBefore(current.minusSeconds(900)))
{
throw new PrintingException(410, "Action request expired; review a new action explicitly");
}
if(issued.isAfter(current.plusSeconds(60)))
{
throw new PrintingException(400, "Action time is too far in the future");
}
if(device.getInt("enabled") != 1 || device.has("revoked_at"))
{
throw new PrintingException(409, "Revoked devices require a new local enrollment");
}
if(!REMOTE.contains(action) && !Set.of("CLEAR_QUEUE", "REVOKE").contains(action) && device.getLong("control_revision") >= 9007199254740991L)
{
throw new PrintingException(409, "Control revision capacity reached");
}
expire(connection, deviceId);
update(connection, "DELETE FROM printing_device_command WHERE id IN (SELECT id FROM printing_device_command WHERE tenant_id=? AND device_id=? AND status<>'PENDING' AND created_at<? AND expires_at<? ORDER BY created_at,id LIMIT 200)", tenant, deviceId, Instant.now().minusSeconds(7 * 86400).toString(), Instant.now().toString());
long history = count(connection, "SELECT COUNT(*) AS n FROM printing_device_command WHERE tenant_id=? AND device_id=?", tenant, deviceId);
if(history >= 1000 && !"REVOKE".equals(action))
{
throw new PrintingException(429, "Device control receipt capacity reached; receipts are retained and revocation remains available");
}
String id = UUID.randomUUID().toString();
String now = current.toString();
String expires = current.plusSeconds(900).toString();
String result = null;
Integer cancelled = null;
if(REMOTE.contains(action))
{
if(device.getInt("control_version") != 1 || !new JSONArray(device.getString("control_capabilities")).toList().contains(action))
{
throw new PrintingException(409, "CONTROL_UNSUPPORTED");
}
if(count(connection, "SELECT COUNT(*) AS n FROM printing_device_command WHERE tenant_id=? AND device_id=? AND status='PENDING'", tenant, deviceId) >= 100)
{
throw new PrintingException(429, "Too many pending device commands");
}
if(jobId != null)
{
List<JSONObject> jobs = query(connection, "SELECT id,status,spooler_job_id FROM printing_job WHERE tenant_id=? AND device_id=? AND id=?", tenant, deviceId, jobId);
if(jobs.isEmpty())
{
throw new PrintingException(404, "Job not found");
}
if(!Set.of("SPOOLED", "SPOOLER_COMPLETED").contains(jobs.getFirst().getString("status")) || jobs.getFirst().optString("spooler_job_id").isBlank())
{
throw new PrintingException(409, "Only an owned job with a recorded spool identity can be canceled");
}
}
}
else if("CLEAR_QUEUE".equals(action))
{
if(authorizedQueue != null)
{
Set<String> currentQueue = new java.util.HashSet<>();
for(JSONObject row : query(connection, "SELECT id FROM printing_job WHERE tenant_id=? AND device_id=? AND status='QUEUED' LIMIT 10001", tenant, deviceId))
{
currentQueue.add(row.getString("id"));
}
if(!currentQueue.equals(authorizedQueue))
{
throw new PrintingException(409, "The queue changed; review the current authorized jobs before retrying");
}
}
cancelled = update(connection, "UPDATE printing_job SET status='FAILED',message=? WHERE tenant_id=? AND device_id=? AND status='QUEUED'", PrintingService.CANCELED_BEFORE_DISPATCH, tenant, deviceId);
result = "QUEUED_JOBS_CANCELLED";
}
else if("REVOKE".equals(action))
{
update(connection, "UPDATE printing_device SET enabled=0,token_hash=?,revoked_at=?,dispatch_paused=1,connection_state='DISCONNECTED',control_revision=? WHERE tenant_id=? AND id=?", UUID.randomUUID().toString(), now, Math.min(9007199254740991L, device.getLong("control_revision") + 1), tenant, deviceId);
update(connection, "UPDATE printing_device_command SET status='OUTCOME_UNKNOWN' WHERE tenant_id=? AND device_id=? AND status='PENDING'", tenant, deviceId);
result = "CREDENTIAL_REVOKED";
}
else
{
int paused = device.getInt("dispatch_paused");
String connected = device.getString("connection_state");
if("PAUSE_DISPATCH".equals(action))
{
paused = 1;
}
if("RESUME_DISPATCH".equals(action))
{
paused = 0;
}
if("DISCONNECT".equals(action))
{
connected = "DISCONNECTED";
}
if("RECONNECT".equals(action))
{
connected = "CONNECTED";
}
update(connection, "UPDATE printing_device SET dispatch_paused=?,connection_state=?,control_revision=control_revision+1 WHERE tenant_id=? AND id=?", paused, connected, tenant, deviceId);
result = "DESIRED_STATE_UPDATED";
}
update(connection, "INSERT INTO printing_device_command (id,tenant_id,device_id,request_id,action,job_id,actor,request_json,status,created_at,expires_at,result_code,cancelled_job_count) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?)",
id, tenant, deviceId, requestId, action, jobId, actor, request.toString(), REMOTE.contains(action) ? "PENDING" : "SUCCEEDED", now, expires, result, cancelled);
JSONObject response = record(command(connection, deviceId, id));
connection.commit();
return (response);
}
catch(Exception exception)
{
connection.rollback();
throw exception;
}
}
}
/** Independent outbound control traffic remains available while disconnected. */
JSONObject poll(String deviceId, JSONObject request) throws SQLException
{
fields(request, Set.of("controlVersion", "agentVersion", "capabilities", "lastAppliedRevision"));
if(integer(request, "controlVersion") != 1)
{
throw new PrintingException(400, "Unsupported control version");
}
String version = text(request, "agentVersion", 100);
long applied = integer(request, "lastAppliedRevision");
if(!(request.opt("capabilities") instanceof JSONArray capabilities) || capabilities.length() > 2
|| capabilities.toList().stream().anyMatch(value -> !REMOTE.contains(value)) || Set.copyOf(capabilities.toList()).size() != capabilities.length())
{
throw new PrintingException(400, "Invalid control capabilities");
}
try(Connection connection = source.getConnection())
{
connection.setAutoCommit(false);
try
{
JSONObject device = lock(connection, deviceId, true);
if(applied > device.getLong("control_revision"))
{
throw new PrintingException(409, "Unknown control revision");
}
String now = Instant.now().toString();
update(connection, "UPDATE printing_device SET control_version=1,control_capabilities=?,control_last_poll_at=?,control_applied_revision=?,agent_version=?,last_seen_at=? WHERE tenant_id=? AND id=?",
capabilities.toString(), now, applied, version, now, tenant, deviceId);
expire(connection, deviceId);
JSONArray commands = new JSONArray();
for(JSONObject row : query(connection, "SELECT * FROM printing_device_command WHERE tenant_id=? AND device_id=? AND status='PENDING' AND (action<>'REFRESH_INVENTORY' OR ?='CONNECTED') ORDER BY created_at,id LIMIT 20", tenant, deviceId, device.getString("connection_state")))
{
JSONObject value = record(row);
JSONObject delivery = new JSONObject();
for(String key : List.of("commandId", "requestId", "action", "createdAt", "expiresAt", "jobId"))
{
if(value.has(key))
{
delivery.put(key, value.get(key));
}
}
commands.put(delivery);
}
connection.commit();
return (new JSONObject().put("controlVersion", 1).put("serverTime", now).put("pollIntervalSeconds", 5)
.put("desiredState", state(device).getJSONObject("desiredState")).put("commands", commands));
}
catch(Exception exception)
{
connection.rollback();
throw exception;
}
}
}
/** An immutable receipt records observation, never rewrites printing outcomes. */
JSONObject receipt(String deviceId, String commandId, JSONObject receipt) throws SQLException
{
fields(receipt, Set.of("receiptId", "outcome", "completedAt", "message"));
if(!text(receipt, "receiptId", 128).matches("[A-Za-z0-9._-]+"))
{
throw new PrintingException(400, "Invalid receiptId");
}
String outcome = text(receipt, "outcome", 40);
try
{
Instant.parse(utc(receipt, "completedAt"));
}
catch(java.time.format.DateTimeParseException exception)
{
throw new PrintingException(400, "Invalid receipt time");
}
if(receipt.has("message") && (!(receipt.opt("message") instanceof String message) || message.length() > 1024 || message.indexOf('\0') >= 0))
{
throw new PrintingException(400, "Invalid receipt message");
}
if(receipt.toString().length() > 8000)
{
throw new PrintingException(400, "Receipt is too large");
}
try(Connection connection = source.getConnection())
{
connection.setAutoCommit(false);
try
{
lock(connection, deviceId, true);
JSONObject row = command(connection, deviceId, commandId);
String action = row.getString("action");
if(!REMOTE.contains(action))
{
throw new PrintingException(409, "This action has no device receipt");
}
Set<String> outcomes = "REFRESH_INVENTORY".equals(action)
? Set.of("INVENTORY_REFRESHED", "UNSUPPORTED", "FAILED", "EXPIRED", "OUTCOME_UNKNOWN")
: Set.of("CANCEL_REQUESTED", "ALREADY_ABSENT", "OWNERSHIP_MISMATCH", "UNSUPPORTED", "FAILED", "EXPIRED", "OUTCOME_UNKNOWN");
if(!outcomes.contains(outcome))
{
throw new PrintingException(400, "Invalid command outcome");
}
if(row.has("receipt_json"))
{
if(!new JSONObject(row.getString("receipt_json")).similar(receipt))
{
throw new PrintingException(409, "Command receipt is immutable");
}
}
else
{
String status = switch(outcome)
{
case "INVENTORY_REFRESHED", "CANCEL_REQUESTED", "ALREADY_ABSENT" -> "SUCCEEDED";
case "EXPIRED", "OUTCOME_UNKNOWN" -> outcome;
default -> "FAILED";
};
update(connection, "UPDATE printing_device_command SET status=?,receipt_json=? WHERE id=? AND tenant_id=? AND device_id=?", status, receipt.toString(), commandId, tenant, deviceId);
}
connection.commit();
return (new JSONObject().put("accepted", true));
}
catch(Exception exception)
{
connection.rollback();
throw exception;
}
}
}
/** Management history is bounded and remains readable after revocation. */
JSONObject page(String deviceId, int limit, String before) throws SQLException
{
if(limit < 1 || limit > 200)
{
throw new PrintingException(400, "Invalid command page limit");
}
try(Connection connection = source.getConnection())
{
List<JSONObject> rows;
if(query(connection, "SELECT id FROM printing_device WHERE tenant_id=? AND id=?", tenant, deviceId).isEmpty())
{
throw new PrintingException(404, "Device not found");
}
if(before == null)
{
rows = query(connection, "SELECT * FROM printing_device_command WHERE tenant_id=? AND device_id=? ORDER BY created_at DESC,id DESC LIMIT ?", tenant, deviceId, limit + 1);
}
else
{
JSONObject cursor = command(connection, deviceId, before);
rows = query(connection, "SELECT * FROM printing_device_command WHERE tenant_id=? AND device_id=? AND (created_at<? OR (created_at=? AND id<?)) ORDER BY created_at DESC,id DESC LIMIT ?", tenant, deviceId, cursor.getString("created_at"), cursor.getString("created_at"), before, limit + 1);
}
JSONArray commands = new JSONArray();
for(JSONObject row : rows.subList(0, Math.min(limit, rows.size())))
{
commands.put(record(row));
}
return (new JSONObject().put("commands", commands).put("nextCursor", rows.size() > limit ? rows.get(limit - 1).getString("id") : JSONObject.NULL));
}
}
/** Look up one exact tenant/device command without exposing another owner. */
JSONObject get(String deviceId, String commandId) throws SQLException
{
try(Connection connection = source.getConnection())
{
return (record(command(connection, deviceId, commandId)));
}
}
/** Serialize a device before any state, claim, or command mutation. */
private JSONObject lock(Connection connection, String deviceId, boolean active) throws SQLException
{
List<JSONObject> rows = query(connection, "SELECT * FROM printing_device WHERE tenant_id=? AND id=? FOR UPDATE", tenant, deviceId);
if(rows.isEmpty() || (active && (rows.getFirst().getInt("enabled") != 1 || rows.getFirst().has("revoked_at"))))
{
throw new PrintingException(404, "Device not found");
}
return (rows.getFirst());
}
/** Expiry stops delivery, but a later first receipt can still report actual execution. */
private void expire(Connection connection, String deviceId) throws SQLException
{
update(connection, "UPDATE printing_device_command SET status='EXPIRED' WHERE tenant_id=? AND device_id=? AND status='PENDING' AND expires_at<?", tenant, deviceId, Instant.now().toString());
}
/** Single-record lookup is always scoped, including cursors and receipts. */
private JSONObject command(Connection connection, String deviceId, String id) throws SQLException
{
List<JSONObject> rows = query(connection, "SELECT * FROM printing_device_command WHERE tenant_id=? AND device_id=? AND id=?", tenant, deviceId, id);
if(rows.isEmpty())
{
throw new PrintingException(404, "Command not found");
}
return (rows.getFirst());
}
/** Stable wire projection excludes raw request and authentication state. */
private static JSONObject record(JSONObject row)
{
JSONObject value = new JSONObject().put("commandId", row.getString("id")).put("requestId", row.getString("request_id")).put("issuedAt", new JSONObject(row.getString("request_json")).getString("issuedAt"))
.put("deviceId", row.getString("device_id")).put("action", row.getString("action")).put("status", row.getString("status"))
.put("createdAt", row.getString("created_at")).put("expiresAt", row.getString("expires_at"));
if("PENDING".equals(row.getString("status")) && Instant.parse(row.getString("expires_at")).isBefore(Instant.now()))
{
value.put("status", "EXPIRED");
}
if(row.has("job_id"))
{
value.put("jobId", row.getString("job_id"));
}
if(row.has("result_code"))
{
value.put("resultCode", row.getString("result_code"));
}
if(row.has("cancelled_job_count"))
{
value.put("cancelledJobCount", row.getInt("cancelled_job_count"));
}
if(row.has("receipt_json"))
{
value.put("receipt", new JSONObject(row.getString("receipt_json")));
}
return (value);
}
/** Numeric aggregates do not load a receipt history into application memory. */
private static long count(Connection connection, String sql, Object... values) throws SQLException
{
return (query(connection, sql, values).getFirst().getLong("n"));
}
/** Reject ambiguous or oversized text before persistence. */
private static String text(JSONObject object, String field, int maximum)
{
if(!(object.opt(field) instanceof String value) || value.isBlank() || value.length() > maximum || value.indexOf('\0') >= 0)
{
throw new PrintingException(400, "Invalid " + field);
}
return (value);
}
/** Protocol times have explicit UTC spelling rather than an implicit local zone. */
private static String utc(JSONObject object, String field)
{
String value = text(object, field, 40);
if(!value.endsWith("Z"))
{
throw new PrintingException(400, "UTC timestamp required");
}
return (value);
}
/** Require an exact nonnegative integral JSON value without coercion. */
private static long integer(JSONObject object, String field)
{
Object value = object.opt(field);
if(!(value instanceof Integer || value instanceof Long) || (((Number) value).longValue() < 0 || ((Number) value).longValue() > 9007199254740991L))
{
throw new PrintingException(400, "Invalid " + field);
}
return (((Number) value).longValue());
}
/** A closed vocabulary prevents arbitrary command payloads. */
private static void fields(JSONObject object, Set<String> allowed)
{
if(!allowed.containsAll(object.keySet()))
{
throw new PrintingException(400, "Unknown control field");
}
}
}
@@ -0,0 +1,351 @@
/*
* QQQ - Low-code Application Framework for Engineers.
* Copyright (C) 2021-2025. Kingsrook, LLC
* 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
* contact@kingsrook.com
* https://github.com/Kingsrook/
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.kingsrook.qbits.printing;
import java.io.Serializable;
import java.time.Instant;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.UUID;
import com.kingsrook.qqq.backend.core.actions.processes.BackendStep;
import com.kingsrook.qqq.backend.core.actions.tables.GetAction;
import com.kingsrook.qqq.backend.core.context.QContext;
import com.kingsrook.qqq.backend.core.exceptions.QException;
import com.kingsrook.qqq.backend.core.model.actions.processes.ProcessSummaryLine;
import com.kingsrook.qqq.backend.core.model.actions.processes.ProcessSummaryLineInterface;
import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepInput;
import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepOutput;
import com.kingsrook.qqq.backend.core.model.actions.processes.Status;
import com.kingsrook.qqq.backend.core.model.actions.tables.get.GetInput;
import com.kingsrook.qqq.backend.core.model.data.QRecord;
import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference;
import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldMetaData;
import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldType;
import com.kingsrook.qqq.backend.core.model.metadata.processes.QBackendStepMetaData;
import com.kingsrook.qqq.backend.core.model.metadata.processes.QComponentType;
import com.kingsrook.qqq.backend.core.model.metadata.processes.QFrontendComponentMetaData;
import com.kingsrook.qqq.backend.core.model.metadata.processes.QFrontendStepMetaData;
import com.kingsrook.qqq.backend.core.model.metadata.processes.QProcessMetaData;
import com.kingsrook.qqq.backend.core.processes.implementations.etl.streamedwithfrontend.AbstractLoadStep;
import com.kingsrook.qqq.backend.core.processes.implementations.etl.streamedwithfrontend.AbstractTransformStep;
import com.kingsrook.qqq.backend.core.processes.implementations.etl.streamedwithfrontend.ProcessSummaryProviderInterface;
import com.kingsrook.qqq.backend.core.processes.implementations.etl.streamedwithfrontend.StreamedETLWithFrontendProcess;
import org.json.JSONObject;
/*******************************************************************************
** Native administration controls use the caller's QQQ session and selected rows.
** Review is read-only; durable service requests execute only in the load step.
*******************************************************************************/
public final class PrintingDeviceProcesses
{
static final String REQUEST_ID = "printingControlRequestId";
static final String ISSUED_AT = "printingControlIssuedAt";
static final String CONFIRM = "confirmPrintingControl";
/***************************************************************************
** Each action is associated with both record and table-selection menus.
***************************************************************************/
public enum Action
{
PAUSE("printingPauseDevices", "Pause printing", "PAUSE_DISPATCH", false, false,
"New work will stop being dispatched. Jobs already received by Windows may still print."),
RESUME("printingResumeDevices", "Resume printing", "RESUME_DISPATCH", false, false,
"Dispatch will resume for connected, authorized devices. Administrative disconnect remains unchanged."),
DISCONNECT("printingDisconnectDevices", "Disconnect devices", "DISCONNECT", false, false,
"Normal printing traffic will stop. The outbound control channel remains available for reconnect."),
RECONNECT("printingReconnectDevices", "Reconnect devices", "RECONNECT", false, false,
"Connected agents will be asked to resume normal traffic. An offline computer cannot be reached immediately."),
REVOKE("printingRevokeDevices", "Revoke device access", "REVOKE", true, false,
"Access will be revoked permanently. The old credential cannot be restored; local re-enrollment is required."),
REFRESH("printingRefreshDevices", "Refresh printer inventory", "REFRESH_INVENTORY", false, false,
"A bounded refresh request will wait for a compatible agent. Acceptance does not mean it has executed."),
CLEAR("printingClearDeviceQueues", "Cancel queued jobs", "CLEAR_QUEUE", true, false,
"Only jobs still queued in QQQ will be canceled. History remains and Windows jobs are not purged."),
CANCEL_WINDOWS("printingCancelWindowsJobs", "Cancel Windows print job", "CANCEL_SPOOL", false, true,
"The agent will request cancellation only with proof that the spool entry belongs to this job. Printed output cannot be recalled.");
final String process;
final String label;
final String wire;
final boolean confirmation;
final boolean job;
final String preview;
/************************************************************************
** Keep labels separate from the closed wire action vocabulary.
************************************************************************/
Action(String process, String label, String wire, boolean confirmation, boolean job, String preview)
{
this.process = process;
this.label = label;
this.wire = wire;
this.confirmation = confirmation;
this.job = job;
this.preview = preview;
}
}
/***************************************************************************
** Utility class.
***************************************************************************/
private PrintingDeviceProcesses()
{
}
/***************************************************************************
** Standard streamed review supports checked rows, records and query selection.
***************************************************************************/
public static void register(QInstance instance)
{
for(Action action : Action.values())
{
String table = action.job ? PrintingTables.JOB : PrintingTables.DEVICE;
Map<String, Serializable> values = new HashMap<>();
values.put(StreamedETLWithFrontendProcess.FIELD_SOURCE_TABLE, table);
values.put(StreamedETLWithFrontendProcess.FIELD_DESTINATION_TABLE, table);
values.put(StreamedETLWithFrontendProcess.FIELD_SUPPORTS_FULL_VALIDATION, true);
values.put(StreamedETLWithFrontendProcess.FIELD_DO_FULL_VALIDATION, true);
values.put(StreamedETLWithFrontendProcess.FIELD_PREVIEW_MESSAGE, action.preview);
QProcessMetaData process = StreamedETLWithFrontendProcess.defineProcessMetaData(PrintingExtract.class, Transform.class, Load.class, values)
.withName(action.process).withLabel(action.label).withTableName(table).withMinInputRecords(1)
.withPermissionRules(PrintingProcesses.permissionRules());
process.withStep(0, new QBackendStepMetaData().withName("prepareControl").withCode(new QCodeReference(Prepare.class)));
if(action.confirmation)
{
process.withStep(1, new QFrontendStepMetaData().withName("confirmControl").withLabel(action.label)
.withFormField(new QFieldMetaData(CONFIRM, QFieldType.BOOLEAN).withLabel("I understand and confirm this action").withDefaultValue(false))
.withComponent(new QFrontendComponentMetaData().withType(QComponentType.EDIT_FORM)));
}
instance.addProcess(process);
}
}
/***************************************************************************
** Unknown names must never choose a more privileged default action.
***************************************************************************/
static Action action(RunBackendStepInput input) throws QException
{
for(Action action : Action.values())
{
if(action.process.equals(input.getProcessName()))
{
return (action);
}
}
throw new QException("Unknown printing control action");
}
/***************************************************************************
** Use a real authenticated user identifier, never a client-supplied actor.
***************************************************************************/
static String actor(RunBackendStepInput input) throws QException
{
new PrintingAdminPermission().checkPermissionsThrowing(input, null);
PrintingProcesses.currentService();
if(QContext.getQSession() == null || QContext.getQSession().getUser() == null
|| QContext.getQSession().getUser().getIdReference() == null || QContext.getQSession().getUser().getIdReference().isBlank())
{
throw new QException("Sign in with an authorized QQQ user before controlling a print device");
}
return (QContext.getQSession().getUser().getIdReference());
}
/***************************************************************************
** Resolve current records through QQQ permissions and tenant row locks.
***************************************************************************/
static QRecord resolve(RunBackendStepInput input, String id) throws QException
{
Action action = action(input);
GetInput get = new GetInput();
get.setTableName(action.job ? PrintingTables.JOB : PrintingTables.DEVICE);
get.setPrimaryKey(id);
get.setPermissionEnforcement(com.kingsrook.qqq.backend.core.actions.permissions.PermissionEnforcement.ENFORCE);
QRecord record = new GetAction().execute(get).getRecord();
if(record == null)
{
throw new QException("Choose an accessible print " + (action.job ? "job" : "device"));
}
if(action.job && "QUEUED".equals(record.getValueString("status")))
{
throw new QException("Use Cancel queued jobs for work that has not been dispatched to Windows");
}
return (record);
}
/***************************************************************************
** Keep request identity and issue time stable throughout review and replay.
***************************************************************************/
public static class Prepare implements BackendStep
{
/************************************************************************
** No service mutation or command delivery occurs during preparation.
************************************************************************/
@Override
public void run(RunBackendStepInput input, RunBackendStepOutput output) throws QException
{
actor(input);
action(input);
String request = input.getValueString(REQUEST_ID);
String issued = input.getValueString(ISSUED_AT);
if((request == null || request.isBlank()) != (issued == null || issued.isBlank()))
{
throw new QException("Restart this action to obtain a complete control request identity");
}
output.addValue(REQUEST_ID, request == null || request.isBlank() ? UUID.randomUUID().toString() : request);
output.addValue(ISSUED_AT, issued == null || issued.isBlank() ? Instant.now().toString() : issued);
}
}
/***************************************************************************
** The native preview rechecks scope without changing device or queue state.
***************************************************************************/
public static class Transform extends AbstractTransformStep implements ProcessSummaryProviderInterface
{
private final ProcessSummaryLine ready = new ProcessSummaryLine(Status.OK, 0, null)
.withSingularFutureMessage("record will receive the selected control action")
.withPluralFutureMessage("records will receive the selected control action");
/************************************************************************
** Never trust extracted rows after permissions or records have changed.
************************************************************************/
@Override
public void runOnePage(RunBackendStepInput input, RunBackendStepOutput output) throws QException
{
actor(input);
for(QRecord selected : input.getRecords())
{
QRecord current = resolve(input, selected.getValueString("id"));
ready.incrementCountAndAddPrimaryKey(current.getValue("id"));
output.getRecords().add(current);
}
}
/************************************************************************
** Standard summary links preserve the native record/table workflow.
************************************************************************/
@Override
public ArrayList<ProcessSummaryLineInterface> getProcessSummary(RunBackendStepOutput output, boolean isForResultScreen)
{
return (new ArrayList<>(List.of(ready)));
}
}
/***************************************************************************
** Apply the same durable action service as the authenticated HTTP adapter.
***************************************************************************/
public static class Load extends AbstractLoadStep implements ProcessSummaryProviderInterface
{
private final ProcessSummaryLine applied = new ProcessSummaryLine(Status.OK, 0, null)
.withSingularPastMessage("server control action was applied; device observation is shown separately")
.withPluralPastMessage("server control actions were applied; device observations are shown separately");
private final ProcessSummaryLine pending = new ProcessSummaryLine(Status.WARNING, 0, null)
.withSingularPastMessage("agent request is pending; no remote execution is confirmed")
.withPluralPastMessage("agent requests are pending; no remote execution is confirmed");
private final ProcessSummaryLine unresolved = new ProcessSummaryLine(Status.WARNING, 0, null)
.withSingularPastMessage("request did not complete; inspect command history before trying another request")
.withPluralPastMessage("requests did not complete; inspect command history before trying another request");
/************************************************************************
** Recheck current scope and consent immediately before each mutation.
************************************************************************/
@Override
public void runOnePage(RunBackendStepInput input, RunBackendStepOutput output) throws QException
{
actor(input);
Action action = action(input);
if(action.confirmation && !Boolean.TRUE.equals(input.getValueBoolean(CONFIRM)))
{
throw new QException("Confirm the reviewed action before continuing");
}
String requestId = input.getValueString(REQUEST_ID);
String issuedAt = input.getValueString(ISSUED_AT);
if(requestId == null || requestId.isBlank() || issuedAt == null || issuedAt.isBlank())
{
throw new QException("Restart this action to obtain a stable control request identity");
}
for(QRecord selected : input.getRecords())
{
QRecord current = resolve(input, selected.getValueString("id"));
String deviceId = current.getValueString(action.job ? "device_id" : "id");
JSONObject request = new JSONObject().put("requestId", action.job ? requestId + "-" + current.getValueString("id") : requestId)
.put("issuedAt", issuedAt).put("action", action.wire);
if(action.job)
{
request.put("jobId", current.getValueString("id"));
}
try
{
JSONObject result = PrintingControlAuthorization.deviceAction(deviceId, request);
String status = result.getString("status");
ProcessSummaryLine summary = "PENDING".equals(status) ? pending : ("SUCCEEDED".equals(status) ? applied : unresolved);
summary.incrementCountAndAddPrimaryKey(current.getValue("id"));
output.getRecords().add(current);
}
catch(Exception exception)
{
throw new QException("Printing control could not be completed. Review command history before submitting a new action.", exception);
}
}
}
/************************************************************************
** Pending requests are never presented as completed Windows operations.
************************************************************************/
@Override
public ArrayList<ProcessSummaryLineInterface> getProcessSummary(RunBackendStepOutput output, boolean isForResultScreen)
{
return (new ArrayList<>(List.of(applied, pending, unresolved)));
}
}
}
@@ -0,0 +1,179 @@
/*
* QQQ - Low-code Application Framework for Engineers.
* Copyright (C) 2021-2025. Kingsrook, LLC
* 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
* contact@kingsrook.com
* https://github.com/Kingsrook/
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.kingsrook.qbits.printing;
import java.time.Instant;
import java.time.format.DateTimeParseException;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.Set;
import com.kingsrook.qqq.backend.core.actions.customizers.TableCustomizerInterface;
import com.kingsrook.qqq.backend.core.actions.tables.QueryAction;
import com.kingsrook.qqq.backend.core.exceptions.QException;
import com.kingsrook.qqq.backend.core.model.actions.tables.QueryOrGetInputInterface;
import com.kingsrook.qqq.backend.core.model.actions.tables.query.QCriteriaOperator;
import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryInput;
import com.kingsrook.qqq.backend.core.model.data.QRecord;
/*******************************************************************************
** Presence and control application are observations, separate from desired state.
*******************************************************************************/
public class PrintingDeviceStatus implements TableCustomizerInterface
{
private static final Set<String> DEPENDENCIES = Set.of("id", "enabled", "connection_state", "last_seen_at", "control_last_poll_at", "dispatch_paused", "control_version", "control_revision", "control_applied_revision");
/***************************************************************************
** Query/Get already applied native user permissions and tenant row security.
***************************************************************************/
@Override
public List<QRecord> postQuery(QueryOrGetInputInterface input, List<QRecord> records) throws QException
{
Set<String> selected = input instanceof QueryInput query ? query.getFieldNamesToInclude() : null;
if(selected != null && !selected.contains("device_status") && !selected.contains("control_status"))
{
return (records);
}
if(selected != null && !selected.contains("id"))
{
throw new QException("Select id together with derived device status fields");
}
Map<String, QRecord> dependencies = dependencies(records);
Instant now = Instant.now();
for(QRecord record : records)
{
QRecord values = dependencies.getOrDefault(record.getValueString("id"), record);
if(selected == null || selected.contains("device_status"))
{
record.setValue("device_status", presence(values, now));
}
if(selected == null || selected.contains("control_status"))
{
record.setValue("control_status", application(values));
}
}
return (records);
}
/***************************************************************************
** Visible-column projections still need authoritative inputs. Fetch bounded
** batches through the same native permissions, never raw SQL or one query
** per row. Dependency-only queries do not invoke this enrichment again.
***************************************************************************/
private static Map<String, QRecord> dependencies(List<QRecord> records) throws QException
{
ArrayList<String> ids = new ArrayList<>();
for(QRecord record : records)
{
if(!record.getValues().keySet().containsAll(DEPENDENCIES) && record.getValueString("id") != null)
{
ids.add(record.getValueString("id"));
}
}
Map<String, QRecord> result = new HashMap<>();
for(int first = 0; first < ids.size(); first += 200)
{
List<String> page = ids.subList(first, Math.min(first + 200, ids.size()));
QueryInput input = new QueryInput().withTableName(PrintingTables.DEVICE).withFieldNamesToInclude(DEPENDENCIES)
.withFilter(new QQueryFilter().withCriteria("id", QCriteriaOperator.IN, page).withLimit(page.size()));
input.setPermissionEnforcement(com.kingsrook.qqq.backend.core.actions.permissions.PermissionEnforcement.ENFORCE);
for(QRecord row : new QueryAction().execute(input).getRecords())
{
result.put(row.getValueString("id"), row);
}
}
return (result);
}
/***************************************************************************
** A recently seen control poll still proves liveness while printing is paused.
***************************************************************************/
static String presence(QRecord record, Instant now)
{
if(record.getValueInteger("enabled") != null && record.getValueInteger("enabled") == 0)
{
return ("REVOKED");
}
if("DISCONNECTED".equals(record.getValueString("connection_state")))
{
return ("DISCONNECTED");
}
Instant heartbeat = timestamp(record.getValueString("last_seen_at"));
Instant control = timestamp(record.getValueString("control_last_poll_at"));
Instant seen = heartbeat == null || (control != null && control.isAfter(heartbeat)) ? control : heartbeat;
if(seen == null || seen.isAfter(now.plusSeconds(30)))
{
return ("UNKNOWN");
}
if(seen.isBefore(now.minusSeconds(90)))
{
return ("OFFLINE");
}
return (Integer.valueOf(1).equals(record.getValueInteger("dispatch_paused")) ? "PAUSED" : "ONLINE");
}
/***************************************************************************
** A server-side successful action is not proof that the agent applied it.
***************************************************************************/
static String application(QRecord record)
{
if(!Integer.valueOf(1).equals(record.getValueInteger("control_version")))
{
return ("UNKNOWN");
}
Long desired = record.getValueLong("control_revision");
Long observed = record.getValueLong("control_applied_revision");
return (desired != null && observed != null && desired.equals(observed) ? "APPLIED" : "PENDING");
}
/***************************************************************************
** Bad observations must remain unknown rather than imply a healthy device.
***************************************************************************/
private static Instant timestamp(String value)
{
if(value == null || value.isBlank())
{
return (null);
}
try
{
return (Instant.parse(value));
}
catch(DateTimeParseException exception)
{
return (null);
}
}
}
@@ -0,0 +1,293 @@
/*
* QQQ - Low-code Application Framework for Engineers.
* Copyright (C) 2021-2025. Kingsrook, LLC
* 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
* contact@kingsrook.com
* https://github.com/Kingsrook/
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.kingsrook.qbits.printing;
import java.io.InputStream;
import java.io.OutputStream;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.sql.SQLException;
import java.util.HexFormat;
import java.util.concurrent.Callable;
import com.kingsrook.qqq.backend.core.actions.tables.StorageAction;
import com.kingsrook.qqq.backend.core.context.QContext;
import com.kingsrook.qqq.backend.core.model.actions.tables.storage.StorageInput;
import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
import com.kingsrook.qqq.backend.core.model.session.QSystemUserSession;
import com.kingsrook.qqq.backend.module.filesystem.s3.model.metadata.S3BackendMetaData;
import com.kingsrook.qqq.backend.module.filesystem.s3.model.metadata.S3TableBackendDetails;
import org.json.JSONArray;
/*******************************************************************************
** Reuse the host's QQQ storage table and backend credentials, including S3.
** Only service-generated object references enter this adapter after tenant auth.
*******************************************************************************/
public class PrintingDocumentStorage
{
private static final String S3_KEY_LAYOUT = "qqq-s3-filesystem-v1";
private final QInstance instance;
private final String prefix;
private final boolean allowMemoryTest;
/***************************************************************************
** Bind storage to one host instance, including historical table bindings.
***************************************************************************/
public PrintingDocumentStorage(QInstance instance, String tenantId)
{
this(instance, tenantId, false);
}
/***************************************************************************
** Package-scoped memory fixture seam; no runtime environment bypass exists.
***************************************************************************/
PrintingDocumentStorage(QInstance instance, String tenantId, boolean allowMemoryTest)
{
this.instance = java.util.Objects.requireNonNull(instance);
this.prefix = "printing/" + digest(tenantId) + "/";
this.allowMemoryTest = allowMemoryTest;
}
/***************************************************************************
** Store immutable document bytes through the existing configured backend.
***************************************************************************/
public void put(String table, String reference, String format, byte[] content) throws SQLException
{
execute(() ->
{
try(OutputStream stream = new StorageAction().createOutputStream(input(table, reference).withContentType("PDF".equals(format) ? "application/pdf" : "application/vnd.zebra-zpl")))
{
stream.write(content);
}
return null;
});
}
/***************************************************************************
** Bound reads even if stored content was replaced outside this service.
***************************************************************************/
public byte[] get(String table, String reference) throws SQLException
{
return (execute(() ->
{
try(InputStream stream = new StorageAction().getInputStream(input(table, reference)))
{
byte[] bytes = stream.readNBytes(20 * 1024 * 1024 + 1);
if(bytes.length > 20 * 1024 * 1024)
{
throw new PrintingException(502, "Stored print document exceeds the allowed size");
}
return bytes;
}
}));
}
/***************************************************************************
** Backend deletion is idempotent; callers mark receipts only after success.
***************************************************************************/
public void delete(String table, String reference) throws SQLException
{
execute(() ->
{
new StorageAction().deleteObject(input(table, reference));
return null;
});
}
/***************************************************************************
** Read-only host metadata lets administrators see the resolved destination.
***************************************************************************/
public String backendName(String table)
{
if(instance.getTable(table) == null)
{
throw new IllegalArgumentException("Configured printing storage table does not exist");
}
return (instance.getTable(table).getBackendName());
}
/***************************************************************************
** Validate dedicated bucket use visible in this host's metadata. External
** bucket policies and unrelated applications still require deployment review.
** RC.20 keys use File.separator; changing that layout requires explicit
** binding review and migration, not silently adopting historical objects.
** Ordered JSON preserves component boundaries, including multiline paths.
***************************************************************************/
public String binding(String table)
{
var metadata = instance.getTable(table);
var backend = instance.getBackend(backendName(table));
if(allowMemoryTest && "memory".equals(backend.getBackendType()))
{
return (digest(table + ":" + backend.getName()));
}
if(!table.startsWith("printing_") || !(backend instanceof S3BackendMetaData s3) || !(metadata.getBackendDetails() instanceof S3TableBackendDetails details)
|| s3.getBucketName() == null || s3.getBucketName().isBlank())
{
throw new IllegalArgumentException("Printing requires a dedicated printing_* S3 storage table and configured bucket");
}
String identity = bucketIdentity(s3);
for(var other : instance.getTables().values())
{
if(!other.getName().startsWith("printing_") && instance.getBackend(other.getBackendName()) instanceof S3BackendMetaData otherBackend
&& identity.equals(bucketIdentity(otherBackend)))
{
throw new IllegalArgumentException("Printing bucket is shared with a non-printing table; configure a dedicated bucket");
}
}
return (digest(new JSONArray().put(identity).put(java.util.Objects.toString(s3.getRegion(), "")).put(java.util.Objects.toString(s3.getPathStyleAccess(), "false"))
.put(java.util.Objects.toString(s3.getBasePath(), "")).put(java.util.Objects.toString(details.getBasePath(), ""))
.put(S3_KEY_LAYOUT).put((int) java.io.File.separatorChar).toString()));
}
/***************************************************************************
** Display only the bucket name, never access keys or endpoint query data.
***************************************************************************/
public String bucketName(String table)
{
var backend = instance.getBackend(backendName(table));
return (backend instanceof S3BackendMetaData s3 ? s3.getBucketName() : "In-memory test storage");
}
/***************************************************************************
** A tenant-specific owned namespace is shared by validation and generation.
***************************************************************************/
public String prefix()
{
return (prefix);
}
/***************************************************************************
** Keep historical bindings immutable even when a host retargets metadata.
***************************************************************************/
public void verifyBinding(String table, String expected)
{
if(!binding(table).equals(expected))
{
throw new PrintingException(409, "Stored document destination no longer matches the host configuration");
}
}
/***************************************************************************
** Include provider identity; identical bucket names at distinct endpoints
** are not assumed to share storage. Fingerprints never contain credentials.
***************************************************************************/
private static String bucketIdentity(S3BackendMetaData backend)
{
String endpoint = java.util.Objects.toString(backend.getEndpoint(), "AWS");
if(!"AWS".equals(endpoint))
{
java.net.URI uri = java.net.URI.create(endpoint).normalize();
if(uri.getUserInfo() != null || uri.getQuery() != null || uri.getFragment() != null || uri.getHost() == null || !("https".equalsIgnoreCase(uri.getScheme())
|| ("http".equalsIgnoreCase(uri.getScheme()) && java.util.Set.of("localhost", "127.0.0.1", "[::1]").contains(uri.getHost().toLowerCase(java.util.Locale.ROOT)))))
{
throw new IllegalArgumentException("Printing storage endpoint requires HTTPS (except loopback development) and no credentials, query or fragment");
}
endpoint = uri.getScheme().toLowerCase(java.util.Locale.ROOT) + "://" + uri.getHost().toLowerCase(java.util.Locale.ROOT)
+ (uri.getPort() < 0 || ("https".equalsIgnoreCase(uri.getScheme()) && uri.getPort() == 443) || ("http".equalsIgnoreCase(uri.getScheme()) && uri.getPort() == 80) ? "" : ":" + uri.getPort()) + java.util.Objects.toString(uri.getPath(), "").replaceAll("/+$", "");
}
return (new JSONArray().put(endpoint).put(java.util.Objects.toString(backend.getBucketName())).toString());
}
/***************************************************************************
** Hash namespace/binding values instead of embedding host identifiers.
***************************************************************************/
private static String digest(String value)
{
try
{
return (HexFormat.of().formatHex(MessageDigest.getInstance("SHA-256").digest(value.getBytes(StandardCharsets.UTF_8))));
}
catch(java.security.NoSuchAlgorithmException exception)
{
throw new IllegalStateException(exception);
}
}
/***************************************************************************
** No caller-selected paths, bucket URLs or filesystem traversal are accepted.
***************************************************************************/
private StorageInput input(String table, String reference)
{
binding(table);
if(reference == null || !reference.startsWith(prefix) || !reference.matches("printing/[a-f0-9]{64}/[a-f0-9-]{36}\\.(pdf|zpl)"))
{
throw new IllegalArgumentException("Invalid owned printing storage reference");
}
return (new StorageInput(table).withReference(reference));
}
/***************************************************************************
** Device HTTP threads have no QQQ session. Use a narrow instance-bound
** system context only for storage, and always restore the caller context.
***************************************************************************/
private <T> T execute(Callable<T> operation) throws SQLException
{
var original = QContext.capture();
try
{
QContext.init(instance, new QSystemUserSession(instance));
return (operation.call());
}
catch(PrintingException exception)
{
throw exception;
}
catch(Exception exception)
{
throw new SQLException("Printing document storage operation failed", exception);
}
finally
{
QContext.init(original);
}
}
}
@@ -0,0 +1,56 @@
/*
* QQQ - Low-code Application Framework for Engineers.
* Copyright (C) 2021-2025. Kingsrook, LLC
* 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
* contact@kingsrook.com
* https://github.com/Kingsrook/
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.kingsrook.qbits.printing;
import com.kingsrook.qqq.backend.core.actions.permissions.PermissionEnforcement;
import com.kingsrook.qqq.backend.core.actions.permissions.PermissionsHelper;
import com.kingsrook.qqq.backend.core.actions.permissions.TablePermissionSubType;
import com.kingsrook.qqq.backend.core.exceptions.QException;
import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepInput;
import com.kingsrook.qqq.backend.core.model.actions.tables.count.CountInput;
import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryInput;
import com.kingsrook.qqq.backend.core.processes.implementations.etl.streamedwithfrontend.ExtractViaQueryStep;
/** Printing selections enforce current native table permissions before preview or extraction. */
public class PrintingExtract extends ExtractViaQueryStep
{
/** Preserve the standard callback, then prevent it from weakening current-user enforcement. */
@Override
protected void customizeInputPreQuery(RunBackendStepInput input, QueryInput query)
{
super.customizeInputPreQuery(input, query);
query.setPermissionEnforcement(PermissionEnforcement.ENFORCE);
}
/** RC20 exposes no count-input hook; authorize before its unchanged tenant-filtered count. */
@Override
public Integer doCount(RunBackendStepInput input) throws QException
{
CountInput count = new CountInput();
count.setTableName(input.getValueString(FIELD_SOURCE_TABLE));
count.setPermissionEnforcement(PermissionEnforcement.ENFORCE);
PermissionsHelper.checkTablePermissionThrowing(count, TablePermissionSubType.READ);
return (super.doCount(input));
}
}
@@ -0,0 +1,109 @@
/*
* QQQ - Low-code Application Framework for Engineers.
* Copyright (C) 2021-2025. Kingsrook, LLC
* 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
* contact@kingsrook.com
* https://github.com/Kingsrook/
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.kingsrook.qbits.printing;
import java.util.List;
import com.kingsrook.qqq.backend.core.actions.permissions.PermissionEnforcement;
import com.kingsrook.qqq.backend.core.actions.values.SearchPossibleValueSourceAction;
import com.kingsrook.qqq.backend.core.context.QContext;
import com.kingsrook.qqq.backend.core.exceptions.QException;
import com.kingsrook.qqq.backend.core.model.actions.values.SearchPossibleValueSourceInput;
import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldMetaData;
import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldType;
import com.kingsrook.qqq.backend.core.model.metadata.possiblevalues.QPossibleValue;
import com.kingsrook.qqq.backend.core.model.metadata.possiblevalues.QPossibleValueSource;
import com.kingsrook.qqq.backend.core.model.metadata.possiblevalues.QPossibleValueSourceType;
/*******************************************************************************
** Native facility choices share the host's current session and record security.
*******************************************************************************/
final class PrintingFacilities
{
static final String DEFAULT_SOURCE = "printing_facility";
/***************************************************************************
** Prevent instantiation of this metadata and validation helper.
***************************************************************************/
private PrintingFacilities()
{
}
/***************************************************************************
** A configured source must exist; standalone hosts receive one named choice.
***************************************************************************/
static String register(QInstance instance, PrintingQBitConfig config) throws QException
{
String source = config.getFacilityPossibleValueSourceName();
if(source == null || source.isBlank())
{
instance.addPossibleValueSource(new QPossibleValueSource().withName(DEFAULT_SOURCE).withType(QPossibleValueSourceType.ENUM)
.withEnumValues(List.of(new QPossibleValue<>("default", "Default facility"))));
return (DEFAULT_SOURCE);
}
if(instance.getPossibleValueSource(source) == null)
{
throw new QException("The configured printing facility possible-value source does not exist");
}
return (source);
}
/***************************************************************************
** Reuse the same source for enrollment and read-only device display.
***************************************************************************/
static QFieldMetaData field(QInstance instance)
{
String source = instance.getTable(PrintingTables.DEVICE).getField("facility_id").getPossibleValueSourceName();
return (new QFieldMetaData("facilityId", QFieldType.STRING).withLabel("Facility").withIsRequired(true).withMaxLength(200)
.withPossibleValueSourceName(source).withDefaultValue(DEFAULT_SOURCE.equals(source) ? "default" : null));
}
/***************************************************************************
** Re-query the selected ID under the caller's session, never a system session.
***************************************************************************/
static String validate(String selected) throws QException
{
if(selected == null || selected.isBlank() || selected.length() > 200)
{
throw new QException("Select an available facility");
}
String source = QContext.getQInstance().getTable(PrintingTables.DEVICE).getField("facility_id").getPossibleValueSourceName();
SearchPossibleValueSourceInput input = new SearchPossibleValueSourceInput()
.withPossibleValueSourceName(source).withIdList(List.of(selected));
input.setPermissionEnforcement(PermissionEnforcement.ENFORCE);
var options = new SearchPossibleValueSourceAction().execute(input);
if(options.getResults() == null || options.getResults().stream().noneMatch(option -> selected.equals(String.valueOf(option.getId()))))
{
throw new QException("The selected facility is unavailable or is not accessible to this user");
}
return (selected);
}
}
@@ -88,6 +88,7 @@ public class PrintingHome extends AbstractWidgetRenderer
add(instance, app, "printingHomePrinters", "Printers needing attention", WidgetType.STATISTICS, "systemHealth", 21, 3);
add(instance, app, "printingHomeFailures", "Failed or uncertain jobs", WidgetType.STATISTICS, "systemHealth", 22, 3);
add(instance, app, "printingHomePending", "Pending print jobs", WidgetType.STATISTICS, "systemHealth", 23, 3);
add(instance, app, "printingHomeControls", "Pending device commands", WidgetType.STATISTICS, "systemHealth", 24, 12);
add(instance, app, "printingHomeWork", "Pending and recent print work", WidgetType.TABLE, "queue", 30, 12);
}
@@ -128,10 +129,12 @@ public class PrintingHome extends AbstractWidgetRenderer
{
case "printingHomeHeader" -> header();
case "printingHomeAttention" -> attention(now);
case "printingHomeOffline" -> statistic(DEVICE, offline(now), "Devices · now · target 0 without heartbeat for 90 seconds");
case "printingHomeOffline" -> statistic(DEVICE, offline(now), "Enabled devices · now · disconnected by an administrator or unseen for 90 seconds");
case "printingHomePrinters" -> statistic(PRINTER, printerIssues(), "Enabled printers · now · target 0 needing attention");
case "printingHomeFailures" -> statistic(JOB, failures(now), "Jobs created in last 24 hours · target 0 failed or uncertain");
case "printingHomePending" -> statistic(JOB, statuses(PENDING), "Jobs · now · target queue drains after printing");
case "printingHomeControls" -> statistic(PrintingTables.COMMAND, statuses(List.of("PENDING"))
.withCriteria("expires_at", QCriteriaOperator.GREATER_THAN_OR_EQUALS, now.toString()), "Device commands · now · awaiting an agent receipt; not confirmed applied");
case "printingHomeWork" -> work(now);
default -> throw new QException("Unknown printing home widget");
};
@@ -149,6 +152,8 @@ public class PrintingHome extends AbstractWidgetRenderer
CompositeWidgetData data = column().withBlock(text("Keep packing slips and shipping labels moving by resolving disconnected devices, printer issues and print failures."))
.withBlock(text("Scope: current tenant. Devices/printers: now. Job exceptions/recent work: last 24 hours."))
.withBlock(text("Enroll a print device").withLink(new BlockLink("/app/printingEnrollDevice/?returnTo=%2Fapp%2Fprinting%2F")))
.withBlock(text("Printing retention settings").withLink(new BlockLink("/app/printingRetentionSettings/?returnTo=%2Fapp%2Fprinting%2F")))
.withBlock(text("Run retention cleanup").withLink(new BlockLink("/app/printingRunRetention/?returnTo=%2Fapp%2Fprinting%2F")))
.withBlock(text("Printing setup and help").withLink(new BlockLink("https://github.com/QRun-IO/qbit-printing/blob/main/docs/OPERATIONS.md")));
if(count(DEVICE, new QQueryFilter()) == 0)
{
@@ -165,13 +170,27 @@ public class PrintingHome extends AbstractWidgetRenderer
private static TableData attention(Instant now) throws QException
{
List<Map<String, Object>> rows = new ArrayList<>();
for(QRecord job : query(JOB, failures(now).withOrderBy(new QFilterOrderBy("created_at", true)).withLimit(10)))
for(QRecord job : query(JOB, failures(now).withOrderBy(new QFilterOrderBy("created_at", false)).withLimit(10)))
{
rows.add(issue(JOB, job, job.getValueString("title"), job.getValueString("status"), "Check the local queue and physical output before retrying an uncertain job.", "created_at"));
}
for(QRecord device : query(DEVICE, offline(now).withOrderBy(new QFilterOrderBy("last_seen_at", true)).withLimit(10)))
{
rows.add(issue(DEVICE, device, device.getValueString("name"), "No heartbeat for 90 seconds", "Open the Windows agent and check its service and outbound connection.", "last_seen_at"));
boolean disconnected = "DISCONNECTED".equals(device.getValueString("connection_state"));
rows.add(issue(DEVICE, device, device.getValueString("name"), disconnected ? "Administratively disconnected" : "No connection for 90 seconds",
disconnected ? "Open the device and use Reconnect; review its observed control revision." : "Open the Windows agent and check its service, sign-in and outbound connection.", "last_seen_at"));
}
for(QRecord device : query(DEVICE, new QQueryFilter().withCriteria("enabled", QCriteriaOperator.EQUALS, 1)
.withCriteria("dispatch_paused", QCriteriaOperator.EQUALS, 1).withOrderBy(new QFilterOrderBy("name")).withLimit(10)))
{
rows.add(issue(DEVICE, device, device.getValueString("name"), "Dispatch paused", "Open the device queue, then use Resume dispatch when it is ready.", "control_last_poll_at"));
}
for(QRecord command : query(PrintingTables.COMMAND, statuses(List.of("PENDING", "FAILED", "EXPIRED", "OUTCOME_UNKNOWN"))
.withCriteria("created_at", QCriteriaOperator.GREATER_THAN_OR_EQUALS, now.minusSeconds(86400).toString())
.withOrderBy(new QFilterOrderBy("created_at", false)).withLimit(10)))
{
rows.add(issue(PrintingTables.COMMAND, command, command.getValueString("action"), command.getValueString("command_status"),
"Review command history and the device connection before submitting another request.", "created_at"));
}
for(QRecord printer : query(PRINTER, printerIssues().withOrderBy(new QFilterOrderBy("last_seen_at", true)).withLimit(10)))
{
@@ -223,7 +242,9 @@ public class PrintingHome extends AbstractWidgetRenderer
***************************************************************************/
private static List<QRecord> query(String table, QQueryFilter filter) throws QException
{
return (new QueryAction().execute(new QueryInput().withTableName(table).withFilter(filter)).getRecords());
QueryInput input = new QueryInput().withTableName(table).withFilter(filter);
input.setPermissionEnforcement(com.kingsrook.qqq.backend.core.actions.permissions.PermissionEnforcement.ENFORCE);
return (new QueryAction().execute(input).getRecords());
}
@@ -233,17 +254,33 @@ public class PrintingHome extends AbstractWidgetRenderer
***************************************************************************/
private static int count(String table, QQueryFilter filter) throws QException
{
return (new CountAction().execute(new CountInput(table).withFilter(filter)).getCount());
CountInput input = new CountInput(table).withFilter(filter);
input.setPermissionEnforcement(com.kingsrook.qqq.backend.core.actions.permissions.PermissionEnforcement.ENFORCE);
return (new CountAction().execute(input).getCount());
}
/***************************************************************************
** A heartbeat older than 90 seconds means disconnected, not printer failure.
** Either authenticated connection proves liveness; requested disconnect stays visible.
***************************************************************************/
private static QQueryFilter offline(Instant now)
{
return (new QQueryFilter().withCriteria("enabled", QCriteriaOperator.EQUALS, 1).withCriteria("last_seen_at", QCriteriaOperator.LESS_THAN, now.minusSeconds(90).toString()));
QQueryFilter unseen = new QQueryFilter().withSubFilter(stale("last_seen_at", now)).withSubFilter(stale("control_last_poll_at", now));
QQueryFilter disconnected = new QQueryFilter().withBooleanOperator(QQueryFilter.BooleanOperator.OR)
.withCriteria("connection_state", QCriteriaOperator.EQUALS, "DISCONNECTED").withSubFilter(unseen);
return (new QQueryFilter().withCriteria("enabled", QCriteriaOperator.EQUALS, 1).withSubFilter(disconnected));
}
/***************************************************************************
** Legacy devices may never have sent a control poll.
***************************************************************************/
private static QQueryFilter stale(String field, Instant now)
{
return (new QQueryFilter().withBooleanOperator(QQueryFilter.BooleanOperator.OR)
.withCriteria(field, QCriteriaOperator.IS_BLANK).withCriteria(field, QCriteriaOperator.LESS_THAN, now.minusSeconds(90).toString()));
}
@@ -49,7 +49,6 @@ import com.kingsrook.qqq.backend.core.model.metadata.processes.QFrontendStepMeta
import com.kingsrook.qqq.backend.core.model.metadata.processes.QProcessMetaData;
import com.kingsrook.qqq.backend.core.processes.implementations.etl.streamedwithfrontend.AbstractLoadStep;
import com.kingsrook.qqq.backend.core.processes.implementations.etl.streamedwithfrontend.AbstractTransformStep;
import com.kingsrook.qqq.backend.core.processes.implementations.etl.streamedwithfrontend.ExtractViaQueryStep;
import com.kingsrook.qqq.backend.core.processes.implementations.etl.streamedwithfrontend.ProcessSummaryProviderInterface;
import com.kingsrook.qqq.backend.core.processes.implementations.etl.streamedwithfrontend.StreamedETLWithFrontendProcess;
import org.json.JSONObject;
@@ -82,7 +81,7 @@ public class PrintingJobProcesses
values.put(StreamedETLWithFrontendProcess.FIELD_PREVIEW_MESSAGE, retry
? "Each selected job will create a new print job. Previously spooled or uncertain output may print twice. Inspect the printer before continuing."
: "Only selected jobs still queued in QQQ will be canceled. Jobs already received by a device must be inspected in the Windows companion.");
QProcessMetaData process = StreamedETLWithFrontendProcess.defineProcessMetaData(ExtractViaQueryStep.class, Transform.class, Load.class, values)
QProcessMetaData process = StreamedETLWithFrontendProcess.defineProcessMetaData(PrintingExtract.class, Transform.class, Load.class, values)
.withName(name).withLabel(retry ? "Print again" : "Cancel queued jobs").withTableName(PrintingTables.JOB).withMinInputRecords(1)
.withPermissionRules(PrintingProcesses.permissionRules());
if(retry)
@@ -124,6 +123,7 @@ public class PrintingJobProcesses
static QRecord resolve(RunBackendStepInput input, String id) throws QException
{
GetInput get = new GetInput();
get.setPermissionEnforcement(com.kingsrook.qqq.backend.core.actions.permissions.PermissionEnforcement.ENFORCE);
get.setTableName(PrintingTables.JOB);
get.setPrimaryKey(id);
QRecord job = new GetAction().execute(get).getRecord();
@@ -132,7 +132,8 @@ public class PrintingJobProcesses
throw new QException("Choose an accessible print job");
}
String state = job.getValueString("status");
if(CANCEL.equals(input.getProcessName()) ? !"QUEUED".equals(state) : !Set.of("FAILED", "OUTCOME_UNKNOWN", "SPOOLED", "SPOOLER_COMPLETED").contains(state))
boolean alreadyCanceled = "FAILED".equals(state) && PrintingService.CANCELED_BEFORE_DISPATCH.equals(job.getValueString("message"));
if(CANCEL.equals(input.getProcessName()) ? (!"QUEUED".equals(state) && !alreadyCanceled) : !Set.of("FAILED", "OUTCOME_UNKNOWN", "SPOOLED", "SPOOLER_COMPLETED").contains(state))
{
throw new QException("Job " + job.getValueString("title") + " is " + state + " and cannot be processed by this action");
}
@@ -0,0 +1,78 @@
/*
* QQQ - Low-code Application Framework for Engineers.
* Copyright (C) 2021-2025. Kingsrook, LLC
* 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
* contact@kingsrook.com
* https://github.com/Kingsrook/
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.kingsrook.qbits.printing;
import java.util.Map;
import java.util.Set;
import com.kingsrook.qqq.backend.core.exceptions.QAuthenticationException;
import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
import com.kingsrook.qqq.backend.core.model.metadata.authentication.TableBasedAuthenticationMetaData;
import com.kingsrook.qqq.backend.core.model.session.QSession;
import com.kingsrook.qqq.backend.core.modules.authentication.implementations.TableBasedAuthenticationModule;
/*******************************************************************************
** Authorization mapping only; password/session verification remains native QQQ.
*******************************************************************************/
public class PrintingLocalAuthentication extends TableBasedAuthenticationModule
{
/***************************************************************************
** Only the explicitly configured, successfully verified account gets access.
***************************************************************************/
@Override
public QSession createSession(QInstance instance, Map<String, String> context) throws QAuthenticationException
{
QSession session = super.createSession(instance, context);
session.setPermissions(Set.of());
if(!(instance.getAuthentication() instanceof Metadata metadata) || session.getUser() == null
|| !metadata.username.equals(session.getUser().getIdReference()))
{
super.logout(instance, session.getUuid());
throw new QAuthenticationException("This account is not authorized for local printing administration");
}
session.setPermissions(Set.of("printing_admin"));
session.withSecurityKeyValue("printing_tenant", metadata.tenant);
return (session);
}
/***************************************************************************
** Host-only identity mapping; no password or device credential in metadata.
***************************************************************************/
static class Metadata extends TableBasedAuthenticationMetaData
{
private final String username;
private final String tenant;
/***********************************************************************
** Keep identity fields out of ordinary JavaBean frontend serialization.
***********************************************************************/
Metadata(String username, String tenant)
{
this.username = username;
this.tenant = tenant;
}
}
}
@@ -0,0 +1,246 @@
/*
* QQQ - Low-code Application Framework for Engineers.
* Copyright (C) 2021-2025. Kingsrook, LLC
* 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
* contact@kingsrook.com
* https://github.com/Kingsrook/
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.kingsrook.qbits.printing;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.sql.Connection;
import java.util.List;
import java.util.Locale;
import java.util.Properties;
import java.util.Set;
import com.kingsrook.qqq.backend.core.exceptions.QException;
import com.kingsrook.qqq.backend.core.instances.AbstractQQQApplication;
import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
import com.kingsrook.qqq.backend.core.model.metadata.authentication.AuthScope;
import com.kingsrook.qqq.backend.core.model.metadata.branding.QBrandingMetaData;
import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference;
import com.kingsrook.qqq.backend.core.model.metadata.scheduleing.quartz.QuartzSchedulerMetaData;
import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
import com.kingsrook.qqq.backend.core.modules.authentication.implementations.TableBasedAuthenticationModule;
import com.kingsrook.qqq.backend.module.rdbms.model.metadata.RDBMSBackendMetaData;
import com.kingsrook.qqq.backend.module.rdbms.model.metadata.RDBMSTableBackendDetails;
import com.kingsrook.qqq.middleware.javalin.QApplicationJavalinServer;
import com.kingsrook.qqq.middleware.javalin.QApplicationLauncher;
import com.kingsrook.qqq.middleware.javalin.QApplicationLauncherConfig;
import io.javalin.http.Context;
import io.javalin.http.ForbiddenResponse;
/*******************************************************************************
** Authenticated loopback host: native QQQ screens and paired device routes share
** one durable database. This is not a remote production deployment template.
*******************************************************************************/
public class PrintingLocalHost extends AbstractQQQApplication
{
static final String USER_TABLE = "printing_admin_user";
static final String SESSION_TABLE = "printing_admin_session";
static final String BACKEND = "printing-local-db";
static final String SCHEDULER = "printing-local-scheduler";
private final String backendName = BACKEND + "-" + java.util.UUID.randomUUID();
private final PrintingLocalSettings settings;
private final DriverDataSource source;
private final PrintingService service;
/***************************************************************************
** No default password, mock identity or synthetic records are provisioned.
***************************************************************************/
public static void main(String[] args) throws Exception
{
PrintingLocalHost host = new PrintingLocalHost(PrintingLocalSettings.fromEnvironment(System.getenv()));
QApplicationLauncher.run(host, new QApplicationLauncherConfig()
.withServerCustomizer(server -> host.configure(server, true)));
}
/***************************************************************************
** Construction opens only the explicitly configured database.
***************************************************************************/
PrintingLocalHost(PrintingLocalSettings settings) throws Exception
{
this.settings = new PrintingLocalSettings(settings.jdbcUrl(), settings.databaseUser(), settings.databasePassword(), settings.tenant(),
settings.port(), settings.administratorToken(), settings.username(), null);
source = new DriverDataSource(settings.jdbcUrl(), settings.databaseUser(), settings.databasePassword());
service = new PrintingService(source, settings.tenant());
service.initialize();
initializeAuthentication(settings.initialPassword());
}
/***************************************************************************
** Native authentication and an instance-owned Quartz schedule are registered.
***************************************************************************/
@Override
public QInstance defineQInstance() throws QException
{
try
{
QInstance instance = new QInstance();
instance.setFailOnMetaDataProducerError(true);
instance.setHomeAppName("printing");
instance.setBranding(new QBrandingMetaData().withAppName("QQQ Printing"));
instance.addBackend(new RDBMSBackendMetaData().withName(backendName).withVendor("h2").withHostName("local")
.withDatabaseName("printing").withUsername(settings.databaseUser()).withPassword(settings.databasePassword()).withJdbcUrl(settings.jdbcUrl()));
PrintingLocalAuthentication.Metadata auth = new PrintingLocalAuthentication.Metadata(settings.username(), settings.tenant());
auth.withUserTableName(USER_TABLE).withSessionTableName(SESSION_TABLE).withInactivityTimeoutSeconds(3600);
auth.withName("local-printing").withModuleCodeReference(new QCodeReference(PrintingLocalAuthentication.class));
instance.registerAuthenticationProvider(AuthScope.instanceDefault(), auth);
instance.addTable(auth.defineStandardUserTable(backendName));
instance.addTable(auth.defineStandardSessionTable(backendName));
Properties properties = new Properties();
properties.setProperty("org.quartz.scheduler.instanceName", SCHEDULER);
properties.setProperty("org.quartz.threadPool.threadCount", "2");
instance.addScheduler(new QuartzSchedulerMetaData().withProperties(properties).withName(SCHEDULER));
new PrintingQBitProducer().withConfig(new PrintingQBitConfig().withBackendName(backendName).withService(service)
.withSchedulerName(SCHEDULER)).produce(instance, "printing");
mapPhysicalNames(instance);
return (instance);
}
catch(Exception exception)
{
throw new QException("Unable to initialize the authenticated local printing host", exception);
}
}
/***************************************************************************
** Public middleware integration; a test may omit frontend assets only.
***************************************************************************/
void configure(QApplicationJavalinServer server, boolean frontend)
{
PrintingRoutes routes = new PrintingRoutes(service, context -> MessageDigest.isEqual(
settings.administratorToken().getBytes(StandardCharsets.UTF_8), PrintingRoutes.bearer(context).getBytes(StandardCharsets.UTF_8)), PrintingRoutes.LegacyEnrollment.DISABLED);
server.withPort(settings.port()).withServeFrontendNext(frontend).withServeFrontendMaterialDashboard(false)
.withAdditionalRouteProviders(List.of(routes)).withJavalinConfigCustomizer(config ->
{
config.jetty.host = "127.0.0.1";
config.http.maxRequestSize = 29 * 1024 * 1024;
config.routes.before(PrintingLocalHost::guardOrigin);
});
}
/***************************************************************************
** Reject DNS rebinding and cross-origin cookie mutations on real printers.
** Explicit API credentials without ambient cookies remain usable locally.
***************************************************************************/
static void guardOrigin(Context context)
{
String host = context.header("Host");
int port = context.req().getLocalPort();
Set<String> hosts = port == 80 ? Set.of("localhost", "127.0.0.1", "localhost:80", "127.0.0.1:80")
: Set.of("localhost:" + port, "127.0.0.1:" + port);
if(host == null || !hosts.contains(host.toLowerCase(Locale.ROOT)))
{
throw new ForbiddenResponse("The local printing host accepts only loopback host names");
}
String origin = context.header("Origin");
if(origin != null && !origin.equals("http://" + host))
{
throw new ForbiddenResponse("Cross-origin access to local printing is not allowed");
}
if("cross-site".equalsIgnoreCase(context.header("Sec-Fetch-Site")))
{
throw new ForbiddenResponse("Cross-site access to local printing is not allowed");
}
boolean unsafe = !Set.of("GET", "HEAD", "OPTIONS").contains(context.method().name());
boolean cookie = context.cookie("sessionUUID") != null || context.cookie("sessionId") != null;
if(unsafe && cookie && origin == null)
{
throw new ForbiddenResponse("Cookie-authenticated changes require a same-origin request");
}
}
/***************************************************************************
** Add native auth tables; an existing account is never implicitly reset.
***************************************************************************/
private void initializeAuthentication(String initialPassword) throws Exception
{
try(Connection connection = source.getConnection(); var statement = connection.createStatement())
{
statement.execute("CREATE TABLE IF NOT EXISTS printing_admin_user (id INTEGER GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY, username VARCHAR(200) NOT NULL UNIQUE, passwordHash VARCHAR(1024) NOT NULL, fullName VARCHAR(512), createDate TIMESTAMP WITH TIME ZONE, modifyDate TIMESTAMP WITH TIME ZONE)");
statement.execute("CREATE TABLE IF NOT EXISTS printing_admin_session (id VARCHAR(100) PRIMARY KEY, userId INTEGER NOT NULL REFERENCES printing_admin_user(id), accessTimestamp TIMESTAMP WITH TIME ZONE, createDate TIMESTAMP WITH TIME ZONE, modifyDate TIMESTAMP WITH TIME ZONE)");
try(var users = statement.executeQuery("SELECT username FROM printing_admin_user"))
{
boolean found = false;
boolean any = false;
while(users.next())
{
any = true;
found |= settings.username().equals(users.getString(1));
}
if(found)
{
return;
}
if(any)
{
throw new IllegalArgumentException("The configured local administrator does not match the initialized account; no account was changed");
}
}
String password = initialPassword;
if(password == null || password.length() < 16 || password.length() > 1024)
{
throw new IllegalArgumentException("First startup requires QQQ_PRINT_UI_INITIAL_PASSWORD of 16 to 1024 characters; no default password is provided");
}
try(var insert = connection.prepareStatement("INSERT INTO printing_admin_user(username,passwordHash,fullName,createDate,modifyDate) VALUES (?,?,?,CURRENT_TIMESTAMP,CURRENT_TIMESTAMP)"))
{
insert.setString(1, settings.username());
insert.setString(2, TableBasedAuthenticationModule.PasswordHasher.createHashedPassword(password));
insert.setString(3, "Local printing administrator");
insert.executeUpdate();
}
}
}
/***************************************************************************
** Preserve the existing H2 identifier convention without renaming live tables.
***************************************************************************/
private void mapPhysicalNames(QInstance instance) throws Exception
{
try(Connection connection = source.getConnection())
{
boolean uppercase = connection.getMetaData().storesUpperCaseIdentifiers();
for(QTableMetaData table : instance.getTables().values())
{
if(backendName.equals(table.getBackendName()))
{
table.withBackendDetails(new RDBMSTableBackendDetails().withTableName(uppercase ? table.getName().toUpperCase(Locale.ROOT) : table.getName()));
for(var field : table.getFields().values())
{
field.withBackendName(uppercase ? field.getName().toUpperCase(Locale.ROOT) : field.getName());
}
}
}
}
}
}
@@ -0,0 +1,93 @@
/*
* QQQ - Low-code Application Framework for Engineers.
* Copyright (C) 2021-2025. Kingsrook, LLC
* 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
* contact@kingsrook.com
* https://github.com/Kingsrook/
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.kingsrook.qbits.printing;
import java.util.Map;
/*******************************************************************************
** Explicit local-host configuration. Never render credentials in diagnostics.
*******************************************************************************/
record PrintingLocalSettings(String jdbcUrl, String databaseUser, String databasePassword, String tenant,
int port, String administratorToken, String username, String initialPassword)
{
/***************************************************************************
** Environment launch supports a durable local H2 file, never a remote bind.
***************************************************************************/
static PrintingLocalSettings fromEnvironment(Map<String, String> environment)
{
String jdbc = required(environment, "QQQ_PRINT_JDBC_URL");
if(!jdbc.startsWith("jdbc:h2:file:") || jdbc.contains("\n") || jdbc.contains("\r"))
{
throw new IllegalArgumentException("QQQ_PRINT_JDBC_URL must identify a durable local H2 file");
}
int port = Integer.parseInt(environment.getOrDefault("QQQ_PRINT_PORT", "18081"));
if(port < 1 || port > 65535)
{
throw new IllegalArgumentException("QQQ_PRINT_PORT must be between 1 and 65535");
}
return (new PrintingLocalSettings(jdbc, environment.getOrDefault("QQQ_PRINT_DB_USER", "sa"),
environment.getOrDefault("QQQ_PRINT_DB_PASSWORD", ""), environment.getOrDefault("QQQ_PRINT_TENANT", "demo"), port,
required(environment, "QQQ_PRINT_ADMIN_TOKEN"), required(environment, "QQQ_PRINT_UI_USERNAME"), environment.get("QQQ_PRINT_UI_INITIAL_PASSWORD")));
}
/***************************************************************************
** Tests may use isolated memory databases through this package-private API.
***************************************************************************/
PrintingLocalSettings
{
if(administratorToken == null || administratorToken.length() < 24 || username == null || username.isBlank()
|| username.length() > 200 || username.contains(":") || username.chars().anyMatch(Character::isISOControl)
|| tenant == null || tenant.isBlank() || tenant.length() > 200)
{
throw new IllegalArgumentException("Explicit administrator token, username and tenant are required");
}
}
/***************************************************************************
** Fail without including the supplied value.
***************************************************************************/
private static String required(Map<String, String> values, String name)
{
String value = values.get(name);
if(value == null || value.isBlank())
{
throw new IllegalArgumentException("Set " + name);
}
return (value);
}
/***************************************************************************
** Records must not expose their secret components through default toString.
***************************************************************************/
@Override
public String toString()
{
return ("PrintingLocalSettings[loopbackPort=" + port + ", credentials=redacted]");
}
}
@@ -22,7 +22,6 @@ package com.kingsrook.qbits.printing;
import java.io.Serializable;
import java.nio.charset.StandardCharsets;
import java.util.ArrayList;
import java.util.Base64;
import java.util.HashMap;
@@ -49,6 +48,9 @@ import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldMetaData;
import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldType;
import com.kingsrook.qqq.backend.core.model.metadata.layout.QAppMetaData;
import com.kingsrook.qqq.backend.core.model.metadata.permissions.QPermissionRules;
import com.kingsrook.qqq.backend.core.model.metadata.possiblevalues.QPossibleValue;
import com.kingsrook.qqq.backend.core.model.metadata.possiblevalues.QPossibleValueSource;
import com.kingsrook.qqq.backend.core.model.metadata.possiblevalues.QPossibleValueSourceType;
import com.kingsrook.qqq.backend.core.model.metadata.processes.QBackendStepMetaData;
import com.kingsrook.qqq.backend.core.model.metadata.processes.QComponentType;
import com.kingsrook.qqq.backend.core.model.metadata.processes.QFrontendComponentMetaData;
@@ -57,7 +59,6 @@ import com.kingsrook.qqq.backend.core.model.metadata.processes.QProcessMetaData;
import com.kingsrook.qqq.backend.core.model.metadata.qbits.QBitMetaData;
import com.kingsrook.qqq.backend.core.processes.implementations.etl.streamedwithfrontend.AbstractLoadStep;
import com.kingsrook.qqq.backend.core.processes.implementations.etl.streamedwithfrontend.AbstractTransformStep;
import com.kingsrook.qqq.backend.core.processes.implementations.etl.streamedwithfrontend.ExtractViaQueryStep;
import com.kingsrook.qqq.backend.core.processes.implementations.etl.streamedwithfrontend.ProcessSummaryProviderInterface;
import com.kingsrook.qqq.backend.core.processes.implementations.etl.streamedwithfrontend.StreamedETLWithFrontendProcess;
import org.json.JSONObject;
@@ -68,16 +69,21 @@ import org.json.JSONObject;
*******************************************************************************/
public class PrintingProcesses implements BackendStep
{
private static final String TEST_REQUEST_ID = "printingTestRequestId";
/***************************************************************************
** Register the setup and test actions in the Printing app.
***************************************************************************/
public static void register(QInstance instance, QAppMetaData app)
{
PrintingJobProcesses.register(instance);
add(instance, "printingEnrollDevice", "Enroll a print device", List.of(field("facilityId", "Facility"), field("deviceName", "Device name")));
registerProfiles(instance);
add(instance, "printingEnrollDevice", "Enroll a print device", List.of(PrintingFacilities.field(instance), field("deviceName", "Device name")));
add(instance, "printingEnablePrinter", "Set printer approval", List.of(deviceField(), printerField(null), new QFieldMetaData("enabled", QFieldType.BOOLEAN).withLabel("Approved for printing").withIsRequired(true)));
add(instance, "printingTestZpl", "Print a test label", List.of(deviceField(), printerField("ZPL")));
add(instance, "printingTestPdf", "Print a test page", List.of(deviceField(), printerField("PDF")));
add(instance, "printingTestZpl", "Print a test label", List.of(deviceField(), printerField("ZPL"), profileField(false)));
add(instance, "printingTestPdf", "Print a test page", List.of(deviceField(), printerField("PDF"), profileField(true)));
selected(instance, "printingTestSelectedPdf", "Print a test page", "Each selected PDF printer will receive one test page after you continue.");
selected(instance, "printingTestSelectedZpl", "Print a test label", "Each selected ZPL printer will receive one test label after you continue.");
selected(instance, "printingEnableSelectedPrinters", "Approve printers", "The selected printers will be approved for printing after you continue.");
@@ -86,6 +92,40 @@ public class PrintingProcesses implements BackendStep
/***************************************************************************
** Fixed native choices keep physical stock and resolution explicit.
***************************************************************************/
private static void registerProfiles(QInstance instance)
{
ArrayList<QPossibleValue<?>> pdf = new ArrayList<>();
ArrayList<QPossibleValue<?>> zpl = new ArrayList<>();
for(TestPrintProfile profile : TestPrintProfile.values())
{
QPossibleValue<String> option = new QPossibleValue<>(profile.name(), profile.getLabel());
pdf.add(option);
if(profile.getDpi() > 0)
{
zpl.add(option);
}
}
instance.addPossibleValueSource(new QPossibleValueSource().withName("printing_testProfilePdf").withType(QPossibleValueSourceType.ENUM).withEnumValues(pdf));
instance.addPossibleValueSource(new QPossibleValueSource().withName("printing_testProfileZpl").withType(QPossibleValueSourceType.ENUM).withEnumValues(zpl));
}
/***************************************************************************
** The same profile applies to every selected printer, so group matching stock.
***************************************************************************/
private static QFieldMetaData profileField(boolean pdf)
{
return (field("testProfile", "Test stock / printer resolution (match every selected printer)")
.withPossibleValueSourceName(pdf ? "printing_testProfilePdf" : "printing_testProfileZpl")
.withDefaultValue(pdf ? TestPrintProfile.LETTER.name() : TestPrintProfile.LABEL_4X6_203.name()));
}
/***************************************************************************
** Shared administrator permission for printing apps and processes.
***************************************************************************/
@@ -137,6 +177,11 @@ public class PrintingProcesses implements BackendStep
if("printingEnrollDevice".equals(name))
{
process.withTableName(PrintingTables.DEVICE).withMinInputRecords(0);
process.withStep(0, new QBackendStepMetaData().withName("prepareEnrollment").withCode(new QCodeReference(PrepareEnrollment.class)));
}
if(name.startsWith("printingTest"))
{
process.withStep(0, new QBackendStepMetaData().withName("prepareTest").withCode(new QCodeReference(PrepareTest.class)));
}
instance.addProcess(process);
}
@@ -154,8 +199,14 @@ public class PrintingProcesses implements BackendStep
values.put(StreamedETLWithFrontendProcess.FIELD_SUPPORTS_FULL_VALIDATION, true);
values.put(StreamedETLWithFrontendProcess.FIELD_DO_FULL_VALIDATION, true);
values.put(StreamedETLWithFrontendProcess.FIELD_PREVIEW_MESSAGE, preview);
QProcessMetaData process = StreamedETLWithFrontendProcess.defineProcessMetaData(ExtractViaQueryStep.class, SelectedTransform.class, SelectedLoad.class, values)
QProcessMetaData process = StreamedETLWithFrontendProcess.defineProcessMetaData(PrintingExtract.class, SelectedTransform.class, SelectedLoad.class, values)
.withName(name).withLabel(label).withTableName(PrintingTables.PRINTER).withMinInputRecords(1).withPermissionRules(permissionRules());
if(name.startsWith("printingTest"))
{
process.withStep(0, new QFrontendStepMetaData().withName("testProfile").withLabel("Choose matching stock and resolution")
.withFormFields(List.of(profileField(name.endsWith("Pdf")))).withComponent(new QFrontendComponentMetaData().withType(QComponentType.EDIT_FORM)));
process.withStep(0, new QBackendStepMetaData().withName("prepareTest").withCode(new QCodeReference(PrepareTest.class)));
}
instance.addProcess(process);
}
@@ -208,7 +259,8 @@ public class PrintingProcesses implements BackendStep
{
case "printingEnrollDevice" ->
{
JSONObject enrollment = service.createEnrollment(input.getValueString("facilityId"), input.getValueString("deviceName"));
JSONObject enrollment = service.createEnrollment(PrintingFacilities.validate(input.getValueString("facilityId")), input.getValueString("deviceName"),
input.getValueString("printingEnrollmentCode"), input.getValueString("printingEnrollmentExpires"));
output.addValue("result", "Enrollment code: " + enrollment.getString("enrollmentCode") + " (expires " + enrollment.getString("expiresAt") + ")");
}
case "printingEnablePrinter" ->
@@ -220,7 +272,7 @@ public class PrintingProcesses implements BackendStep
case "printingTestZpl", "printingTestPdf" ->
{
QRecord printer = resolvePrinter(input.getValueString("printerId"), input.getValueString("deviceId"));
String job = submitTest(printer, "printingTestPdf".equals(input.getProcessName()));
String job = submitTest(printer, "printingTestPdf".equals(input.getProcessName()), input.getValueString("testProfile"), testRequestKey(input, printer));
output.addValue("result", "Queued print job " + job + ". Check Print jobs for submission status.");
}
default -> throw new QException("Unknown printing action");
@@ -240,6 +292,7 @@ public class PrintingProcesses implements BackendStep
static QRecord resolvePrinter(String id, String deviceId) throws QException
{
GetInput get = new GetInput();
get.setPermissionEnforcement(com.kingsrook.qqq.backend.core.actions.permissions.PermissionEnforcement.ENFORCE);
get.setTableName(PrintingTables.PRINTER);
get.setPrimaryKey(id);
QRecord printer = new GetAction().execute(get).getRecord();
@@ -256,12 +309,48 @@ public class PrintingProcesses implements BackendStep
** Send one native test document through the normal durable queue.
***************************************************************************/
static String submitTest(QRecord printer, boolean pdf) throws QException
{
return (submitTest(printer, pdf, null));
}
/***************************************************************************
** All built-in document entrypoints share profile validation and generation.
***************************************************************************/
static String submitTest(QRecord printer, boolean pdf, String profileName) throws QException
{
return (submitTest(printer, pdf, profileName, "test:" + UUID.randomUUID()));
}
/***************************************************************************
** The native process persists its request identity before operator review.
***************************************************************************/
private static String testRequestKey(RunBackendStepInput input, QRecord printer) throws QException
{
String request = input.getValueString(TEST_REQUEST_ID);
if(request == null || request.isBlank())
{
throw new QException("Restart the test-print action to obtain a safe request identity");
}
return ("native-test:" + request + ":" + printer.getValueString("id"));
}
/***************************************************************************
** Generate one immutable document and deduplicate replays of a process load.
***************************************************************************/
private static String submitTest(QRecord printer, boolean pdf, String profileName, String key) throws QException
{
try
{
byte[] bytes = pdf ? testPdf() : "^XA^FO30,30^A0N,35,35^FDQQQ cloud printing test^FS^FO30,85^A0N,25,25^FDTest label - not for shipping^FS^XZ".getBytes(StandardCharsets.UTF_8);
TestPrintProfile profile = TestPrintProfile.resolve(pdf ? "PDF" : "ZPL", profileName);
byte[] bytes = pdf ? PrintingTestDocuments.pdf(profile) : PrintingTestDocuments.zpl(profile);
JSONObject job = currentService().submit(new JSONObject().put("deviceId", printer.getValueString("device_id")).put("printerId", printer.getValueString("printer_id"))
.put("title", "QQQ print test").put("format", pdf ? "PDF" : "ZPL").put("contentBase64", Base64.getEncoder().encodeToString(bytes)).put("idempotencyKey", "test:" + UUID.randomUUID()));
.put("title", "QQQ print test").put("format", pdf ? "PDF" : "ZPL").put("contentBase64", Base64.getEncoder().encodeToString(bytes)).put("idempotencyKey", key));
return (job.getString("jobId"));
}
catch(java.sql.SQLException | PrintingException exception)
@@ -272,6 +361,56 @@ public class PrintingProcesses implements BackendStep
/***************************************************************************
** Prepare once before forms/review; a replay reuses the persisted identity.
***************************************************************************/
public static class PrepareTest implements BackendStep
{
/************************************************************************
** Direct invocation also requires administrator and tenant access.
************************************************************************/
@Override
public void run(RunBackendStepInput input, RunBackendStepOutput output) throws QException
{
new PrintingAdminPermission().checkPermissionsThrowing(input, null);
currentService();
String request = input.getValueString(TEST_REQUEST_ID);
output.addValue(TEST_REQUEST_ID, request == null || request.isBlank() ? UUID.randomUUID().toString() : request);
}
}
/***************************************************************************
** Prepare one short-lived credential in the authorized process state. The
** database stores its hash and consumed receipt, never its plaintext value.
***************************************************************************/
public static class PrepareEnrollment implements BackendStep
{
/************************************************************************
** Keep credential and expiry stable across form and backend replay.
************************************************************************/
@Override
public void run(RunBackendStepInput input, RunBackendStepOutput output) throws QException
{
new PrintingAdminPermission().checkPermissionsThrowing(input, null);
currentService();
String code = input.getValueString("printingEnrollmentCode");
String expires = input.getValueString("printingEnrollmentExpires");
if(code == null && expires == null)
{
byte[] random = new byte[32];
new java.security.SecureRandom().nextBytes(random);
code = Base64.getUrlEncoder().withoutPadding().encodeToString(random);
expires = java.time.Instant.now().plusSeconds(900).toString();
}
output.addValue("printingEnrollmentCode", code);
output.addValue("printingEnrollmentExpires", expires);
}
}
/***************************************************************************
** Preview selected queues without printing or changing their approval.
***************************************************************************/
@@ -295,6 +434,14 @@ public class PrintingProcesses implements BackendStep
if(input.getProcessName().startsWith("printingTest"))
{
String format = input.getProcessName().endsWith("Pdf") ? "PDF" : "ZPL";
try
{
TestPrintProfile.resolve(format, input.getValueString("testProfile"));
}
catch(PrintingException exception)
{
throw new QException(exception.getMessage(), exception);
}
if(!Integer.valueOf(1).equals(printer.getValueInteger("enabled")) || !Integer.valueOf(1).equals(printer.getValueInteger("available"))
|| !new org.json.JSONArray(printer.getValueString("formats")).toList().contains(format))
{
@@ -344,8 +491,8 @@ public class PrintingProcesses implements BackendStep
{
switch(input.getProcessName())
{
case "printingTestSelectedPdf" -> submitTest(printer, true);
case "printingTestSelectedZpl" -> submitTest(printer, false);
case "printingTestSelectedPdf" -> submitTest(printer, true, input.getValueString("testProfile"), testRequestKey(input, printer));
case "printingTestSelectedZpl" -> submitTest(printer, false, input.getValueString("testProfile"), testRequestKey(input, printer));
case "printingEnableSelectedPrinters", "printingDisableSelectedPrinters" -> currentService().enablePrinter(printer.getValueString("device_id"), printer.getValueString("printer_id"), "printingEnableSelectedPrinters".equals(input.getProcessName()));
default -> throw new QException("Unknown selected printing action");
}
@@ -378,26 +525,7 @@ public class PrintingProcesses implements BackendStep
***************************************************************************/
static byte[] testPdf() throws QException
{
try(org.apache.pdfbox.pdmodel.PDDocument document = new org.apache.pdfbox.pdmodel.PDDocument())
{
org.apache.pdfbox.pdmodel.PDPage page = new org.apache.pdfbox.pdmodel.PDPage();
document.addPage(page);
try(org.apache.pdfbox.pdmodel.PDPageContentStream content = new org.apache.pdfbox.pdmodel.PDPageContentStream(document, page))
{
content.beginText();
content.setFont(org.apache.pdfbox.pdmodel.font.PDType1Font.HELVETICA, 24);
content.newLineAtOffset(72, 700);
content.showText("QQQ cloud printing test");
content.endText();
}
java.io.ByteArrayOutputStream bytes = new java.io.ByteArrayOutputStream();
document.save(bytes);
return (bytes.toByteArray());
}
catch(java.io.IOException exception)
{
throw new QException("Could not generate test PDF", exception);
}
return (PrintingTestDocuments.pdf());
}
}
@@ -31,6 +31,116 @@ public class PrintingQBitConfig implements QBitConfig
{
private String backendName;
private transient PrintingService service;
private PrintingAdmissionLimits admissionLimits = PrintingAdmissionLimits.defaults();
private PrintingRetentionPolicy retentionPolicy = new PrintingRetentionPolicy(true, 365, 200);
private String storageTableName;
private String schedulerName;
private String facilityPossibleValueSourceName;
/***************************************************************************
** Resource capacity is deployment-owned and independent of retention age.
***************************************************************************/
public PrintingAdmissionLimits getAdmissionLimits()
{
return (admissionLimits);
}
/***************************************************************************
** Positive tenant/device limits apply at the shared admission boundary.
***************************************************************************/
public PrintingQBitConfig withAdmissionLimits(PrintingAdmissionLimits value)
{
admissionLimits = java.util.Objects.requireNonNull(value);
return (this);
}
/***************************************************************************
** Reuse the host's facility selector and its existing record security.
***************************************************************************/
public PrintingQBitConfig withFacilityPossibleValueSourceName(String value)
{
facilityPossibleValueSourceName = value;
return (this);
}
/***************************************************************************
** Missing configuration uses the named standalone default facility.
***************************************************************************/
public String getFacilityPossibleValueSourceName()
{
return (facilityPossibleValueSourceName);
}
/***************************************************************************
** Deployment-owned dedicated S3 table; operators cannot retarget old files.
***************************************************************************/
public PrintingQBitConfig withStorageTableName(String value)
{
storageTableName = value;
return (this);
}
/***************************************************************************
** Existing storage metadata owns bucket, endpoint and credentials.
***************************************************************************/
public String getStorageTableName()
{
return (storageTableName);
}
/***************************************************************************
** Bind bounded five-minute maintenance to a scheduler already configured by the host.
***************************************************************************/
public PrintingQBitConfig withSchedulerName(String value)
{
schedulerName = value;
return (this);
}
/***************************************************************************
** Missing host scheduler means no automatic background maintenance.
***************************************************************************/
public String getSchedulerName()
{
return (schedulerName);
}
/***************************************************************************
** Host defaults are one year; setting policy does not itself run a purge.
***************************************************************************/
public PrintingQBitConfig withRetentionPolicy(PrintingRetentionPolicy value)
{
retentionPolicy = java.util.Objects.requireNonNull(value);
return (this);
}
/***************************************************************************
** The host authorizes and schedules bounded service maintenance explicitly.
***************************************************************************/
public PrintingRetentionPolicy getRetentionPolicy()
{
return (retentionPolicy);
}
@@ -22,11 +22,20 @@ package com.kingsrook.qbits.printing;
import java.util.List;
import com.kingsrook.qqq.backend.core.actions.customizers.TableCustomizers;
import com.kingsrook.qqq.backend.core.actions.dashboard.widgets.ChildRecordListRenderer;
import com.kingsrook.qqq.backend.core.exceptions.QException;
import com.kingsrook.qqq.backend.core.model.actions.tables.query.QCriteriaOperator;
import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterOrderBy;
import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference;
import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldMetaData;
import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldType;
import com.kingsrook.qqq.backend.core.model.metadata.fields.QVirtualFieldMetaData;
import com.kingsrook.qqq.backend.core.model.metadata.joins.JoinOn;
import com.kingsrook.qqq.backend.core.model.metadata.joins.JoinType;
import com.kingsrook.qqq.backend.core.model.metadata.joins.QJoinMetaData;
import com.kingsrook.qqq.backend.core.model.metadata.layout.QAppMetaData;
import com.kingsrook.qqq.backend.core.model.metadata.layout.QIcon;
import com.kingsrook.qqq.backend.core.model.metadata.permissions.QPermissionRules;
@@ -37,7 +46,9 @@ import com.kingsrook.qqq.backend.core.model.metadata.qbits.QBitMetaData;
import com.kingsrook.qqq.backend.core.model.metadata.qbits.QBitProducer;
import com.kingsrook.qqq.backend.core.model.metadata.security.QSecurityKeyType;
import com.kingsrook.qqq.backend.core.model.metadata.security.RecordSecurityLock;
import com.kingsrook.qqq.backend.core.model.metadata.tables.Association;
import com.kingsrook.qqq.backend.core.model.metadata.tables.Capability;
import com.kingsrook.qqq.backend.core.model.metadata.tables.ExposedJoin;
import com.kingsrook.qqq.backend.core.model.metadata.tables.QFieldSection;
import com.kingsrook.qqq.backend.core.model.metadata.tables.QSupplementalTableMetaData;
import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
@@ -79,15 +90,39 @@ public class PrintingQBitProducer implements QBitProducer
{
throw new QException("The initial printing QBit supports the printing namespace only");
}
instance.addQBit(new QBitMetaData().withGroupId("com.kingsrook.qbits").withArtifactId("qbit-printing").withVersion("0.1.0-rc.1").withNamespace("printing").withConfig(config));
config.getService().withRetentionPolicy(config.getRetentionPolicy()).withAdmissionLimits(config.getAdmissionLimits());
config.getService().configureStorage(instance, config.getStorageTableName());
instance.addQBit(new QBitMetaData().withGroupId("com.kingsrook.qbits").withArtifactId("qbit-printing").withVersion(version()).withNamespace("printing").withConfig(config));
instance.addSecurityKeyType(new QSecurityKeyType().withName("printing_tenant"));
QTableMetaData devices = table(PrintingTables.DEVICE, "Print devices", List.of("id", "tenant_id", "facility_id", "name", "display_name", "computer_name", "description", "location", "agent_version", "last_seen_at"));
devices.withField(new QFieldMetaData("enabled", QFieldType.INTEGER).withLabel("Enabled").withPossibleValueSourceName("printing_enabled"));
devices.withField(new QFieldMetaData("dispatch_paused", QFieldType.INTEGER).withLabel("Printing paused").withPossibleValueSourceName("printing_paused"));
devices.withField(new QFieldMetaData("connection_state", QFieldType.STRING).withLabel("Requested connection").withPossibleValueSourceName("printing_connectionState"));
devices.withField(new QFieldMetaData("control_revision", QFieldType.LONG).withLabel("Requested control revision"));
devices.withField(new QFieldMetaData("control_applied_revision", QFieldType.LONG).withLabel("Observed control revision"));
devices.withField(new QFieldMetaData("control_version", QFieldType.INTEGER).withLabel("Agent control version"));
devices.withField(new QFieldMetaData("control_capabilities", QFieldType.STRING).withLabel("Agent control capabilities"));
devices.withField(new QFieldMetaData("control_last_poll_at", QFieldType.STRING).withLabel("Last control connection"));
devices.withField(new QFieldMetaData("revoked_at", QFieldType.STRING).withLabel("Access revoked at"));
devices.withVirtualField(new QVirtualFieldMetaData("device_status", QFieldType.STRING).withLabel("Device status").withPossibleValueSourceName("printing_deviceStatus").withIsQuerySelectable(true));
devices.withVirtualField(new QVirtualFieldMetaData("control_status", QFieldType.STRING).withLabel("Control application").withPossibleValueSourceName("printing_controlApplication").withIsQuerySelectable(true));
devices.withCustomizer(TableCustomizers.POST_QUERY_RECORD, new QCodeReference(PrintingDeviceStatus.class));
devices.getField("facility_id").withLabel("Facility").withPossibleValueSourceName(PrintingFacilities.register(instance, config));
QTableMetaData printers = table(PrintingTables.PRINTER, "Printers", List.of("id", "tenant_id", "device_id", "printer_id", "name", "display_name", "queue_name", "description", "location", "driver_name", "port_name", "status", "formats", "last_seen_at"));
printers.withField(new QFieldMetaData("enabled", QFieldType.INTEGER).withLabel("Approved for printing").withPossibleValueSourceName("printing_approved"));
printers.withField(new QFieldMetaData("available", QFieldType.INTEGER).withLabel("Exposed by device").withPossibleValueSourceName("printing_available"));
QTableMetaData jobs = table(PrintingTables.JOB, "Print jobs", List.of("id", "tenant_id", "device_id", "printer_row_id", "title", "format", "content_hash", "options_json", "idempotency_key", "created_at", "status", "message", "spooler_job_id"));
jobs.withField(new QFieldMetaData("content_length", QFieldType.INTEGER).withLabel("Document size (bytes)"));
QTableMetaData commands = table(PrintingTables.COMMAND, "Device control history", List.of("id", "tenant_id", "device_id", "request_id", "action", "job_id", "actor", "status", "created_at", "expires_at", "result_code"));
commands.withField(new QFieldMetaData("cancelled_job_count", QFieldType.INTEGER).withLabel("Queued jobs canceled"));
commands.getField("device_id").withLabel("Print device").withPossibleValueSourceName(PrintingTables.DEVICE);
commands.getField("job_id").withLabel("Print job").withPossibleValueSourceName(PrintingTables.JOB);
commands.getField("action").withPossibleValueSourceName("printing_controlAction");
commands.getField("status").withLabel("Recorded status").withPossibleValueSourceName("printing_commandStatus");
commands.withVirtualField(new QVirtualFieldMetaData("command_status", QFieldType.STRING).withLabel("Current status")
.withPossibleValueSourceName("printing_commandStatus").withIsQuerySelectable(true));
commands.withCustomizer(TableCustomizers.POST_QUERY_RECORD, new QCodeReference(PrintingCommandStatus.class));
commands.withRecordLabelFormatAndFields("%s", "action");
jobs.getField("printer_row_id").withLabel("Printer").withPossibleValueSourceName(PrintingTables.PRINTER);
jobs.getField("format").withPossibleValueSourceName("printing_format");
jobs.getField("status").withPossibleValueSourceName("printing_jobStatus");
@@ -105,6 +140,12 @@ public class PrintingQBitProducer implements QBitProducer
binaryValues(instance, "printing_enabled", "Disabled", "Enabled");
binaryValues(instance, "printing_approved", "Not approved", "Approved");
binaryValues(instance, "printing_available", "Not exposed", "Exposed");
binaryValues(instance, "printing_paused", "Running", "Paused");
enumValues(instance, "printing_connectionState", List.of("CONNECTED", "DISCONNECTED"));
enumValues(instance, "printing_deviceStatus", List.of("ONLINE", "OFFLINE", "PAUSED", "DISCONNECTED", "REVOKED", "UNKNOWN"));
enumValues(instance, "printing_controlApplication", List.of("APPLIED", "PENDING", "UNKNOWN"));
enumValues(instance, "printing_commandStatus", List.of("PENDING", "SUCCEEDED", "FAILED", "EXPIRED", "OUTCOME_UNKNOWN", "UNKNOWN"));
enumValues(instance, "printing_controlAction", List.of("PAUSE_DISPATCH", "RESUME_DISPATCH", "DISCONNECT", "RECONNECT", "REVOKE", "REFRESH_INVENTORY", "CLEAR_QUEUE", "CANCEL_SPOOL"));
enumValues(instance, "printing_format", List.of("PDF", "ZPL"));
enumValues(instance, "printing_jobStatus", List.of("QUEUED", "CLAIMED", "RECEIVED", "SUBMITTING", "SPOOLED", "SPOOLER_COMPLETED", "FAILED", "OUTCOME_UNKNOWN"));
enumValues(instance, "printing_printerStatus", List.of("READY", "OFFLINE", "PAUSED", "ERROR", "UNKNOWN"));
@@ -116,15 +157,25 @@ public class PrintingQBitProducer implements QBitProducer
printers.getField("device_id").withLabel("Print device");
instance.addPossibleValueSource(com.kingsrook.qqq.backend.core.model.metadata.possiblevalues.QPossibleValueSource.newForTable(PrintingTables.DEVICE));
instance.addPossibleValueSource(com.kingsrook.qqq.backend.core.model.metadata.possiblevalues.QPossibleValueSource.newForTable(PrintingTables.PRINTER));
layout(devices, List.of("name", "location", "description", "facility_id", "enabled", "last_seen_at"));
instance.addPossibleValueSource(com.kingsrook.qqq.backend.core.model.metadata.possiblevalues.QPossibleValueSource.newForTable(PrintingTables.JOB));
layout(devices, List.of("name", "device_status", "control_status", "location", "facility_id", "last_seen_at"));
layout(printers, List.of("name", "location", "description", "device_id", "status", "enabled", "available", "last_seen_at"));
layout(jobs, List.of("title", "device_id", "printer_row_id", "status", "created_at", "format"));
layout(commands, List.of("device_id", "action", "command_status", "created_at", "expires_at", "result_code", "cancelled_job_count"));
instance.addTable(devices);
instance.addTable(printers);
instance.addTable(jobs);
QAppMetaData app = new QAppMetaData().withName("printing").withLabel("Printing").withIcon(new QIcon("print")).withChild(devices).withChild(printers).withChild(jobs);
instance.addTable(commands);
related(instance, devices, printers, "device_id", "Printers");
related(instance, devices, jobs, "device_id", "Jobs and queue");
related(instance, devices, commands, "device_id", "Control history");
related(instance, printers, jobs, "printer_row_id", "Jobs and queue");
QAppMetaData app = new QAppMetaData().withName("printing").withLabel("Printing").withIcon(new QIcon("print")).withChild(devices).withChild(printers).withChild(jobs).withChild(commands);
app.withPermissionRules(PrintingProcesses.permissionRules());
PrintingProcesses.register(instance, app);
PrintingDeviceProcesses.register(instance);
PrintingUiApi.register(instance);
PrintingRetentionProcesses.register(instance, config);
PrintingHome.register(instance, app);
instance.addApp(app);
QAppMetaData parent = instance.getApp("admin");
@@ -136,6 +187,42 @@ public class PrintingQBitProducer implements QBitProducer
/***************************************************************************
** Native related lists open the current device's work without raw-ID input.
***************************************************************************/
private static void related(QInstance instance, QTableMetaData parent, QTableMetaData child, String childField, String label)
{
QJoinMetaData join = new QJoinMetaData().withLeftTable(parent.getName()).withRightTable(child.getName())
.withType(JoinType.ONE_TO_MANY).withJoinOn(new JoinOn("id", childField)).withInferredName();
instance.addJoin(join);
parent.withAssociation(new Association().withName(child.getName()).withAssociatedTableName(child.getName()).withJoinName(join.getName()));
parent.withExposedJoin(new ExposedJoin().withJoinTable(child.getName()).withJoinPath(List.of(join.getName())).withLabel(label));
instance.addWidget(ChildRecordListRenderer.widgetMetaDataBuilder(join).withLabel(label).withCanAddChildRecord(false).withMaxRows(50).getWidgetMetaData());
parent.withSection(new QFieldSection(join.getName(), label, new QIcon("list"), Tier.T2, null).withWidgetName(join.getName()));
if(PrintingTables.JOB.equals(child.getName()))
{
String queueWidget = parent.getName() + "_queue";
var widget = ChildRecordListRenderer.widgetMetaDataBuilder(join).withLabel("Current print queue").withCanAddChildRecord(false).withMaxRows(50)
.withBaseFilter(new QQueryFilter().withCriteria("status", QCriteriaOperator.IN, List.of("QUEUED", "CLAIMED", "RECEIVED", "SUBMITTING")))
.withOrderBys(List.of(new QFilterOrderBy("created_at", true))).getWidgetMetaData().withName(queueWidget);
instance.addWidget(widget);
parent.withSection(new QFieldSection(queueWidget, "Current print queue", new QIcon("pending_actions"), Tier.T2, null).withWidgetName(queueWidget));
}
}
/***************************************************************************
** Read the build-produced JAR manifest; IDE/test class directories identify themselves honestly.
***************************************************************************/
private static String version()
{
String version = PrintingQBitProducer.class.getPackage().getImplementationVersion();
return (version == null || version.isBlank() ? "development" : version);
}
/***************************************************************************
** Produce read-only table metadata protected by tenant and administrator keys.
***************************************************************************/
@@ -188,10 +275,17 @@ public class PrintingQBitProducer implements QBitProducer
{
table.getField("tenant_id").withIsHidden(true);
java.util.LinkedHashMap<String, QFieldMetaData> ordered = new java.util.LinkedHashMap<>();
primary.forEach(name -> ordered.put(name, table.getField(name)));
primary.stream().filter(table.getFields()::containsKey).forEach(name -> ordered.put(name, table.getField(name)));
ordered.putAll(table.getFields());
table.setFields(ordered);
table.withSection(new QFieldSection(table.getName() + "_summary", "Summary", new QIcon("print"), Tier.T1, primary));
QFieldSection summary = new QFieldSection(table.getName() + "_summary", "Summary", new QIcon("print"), Tier.T1,
primary.stream().filter(table.getFields()::containsKey).toList());
if(table.getVirtualFields() != null && primary.stream().anyMatch(table.getVirtualFields()::containsKey))
{
summary.withAlternative(com.kingsrook.qqq.backend.core.model.metadata.tables.QFieldSectionAlternativeType.RECORD_VIEW,
section -> section.setFieldNames(primary));
}
table.withSection(summary);
List<String> details = table.getFields().keySet().stream().filter(name -> !primary.contains(name) && !Boolean.TRUE.equals(table.getField(name).getIsHidden())).toList();
table.withSection(new QFieldSection(table.getName() + "_details", "Details", new QIcon("info"), Tier.T3, details));
table.withSupplementalMetaData(new DefaultColumns(primary.stream().filter(name -> !"description".equals(name)).toList()));
@@ -0,0 +1,50 @@
/*
* QQQ - Low-code Application Framework for Engineers.
* Copyright (C) 2021-2025. Kingsrook, LLC
* 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
* contact@kingsrook.com
* https://github.com/Kingsrook/
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.kingsrook.qbits.printing;
/*******************************************************************************
** Bounded maintenance policy; the host separately binds a native scheduler.
*******************************************************************************/
public record PrintingRetentionPolicy(boolean enabled, int days, int batchSize)
{
/***************************************************************************
** Bound age and work per maintenance invocation before touching storage.
***************************************************************************/
public PrintingRetentionPolicy
{
if(days < 1 || days > 36500 || batchSize < 1 || batchSize > 200)
{
throw new IllegalArgumentException("Retention requires 1..36500 days and a batch of 1..200 jobs");
}
}
/***************************************************************************
** Explicitly disable removal while retaining the standard age and batch bounds.
***************************************************************************/
public static PrintingRetentionPolicy disabled()
{
return (new PrintingRetentionPolicy(false, 365, 200));
}
}
@@ -0,0 +1,231 @@
/*
* QQQ - Low-code Application Framework for Engineers.
* Copyright (C) 2021-2025. Kingsrook, LLC
* 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
* contact@kingsrook.com
* https://github.com/Kingsrook/
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.kingsrook.qbits.printing;
import java.util.List;
import com.kingsrook.qqq.backend.core.actions.processes.BackendStep;
import com.kingsrook.qqq.backend.core.context.QContext;
import com.kingsrook.qqq.backend.core.exceptions.QException;
import com.kingsrook.qqq.backend.core.exceptions.QPermissionDeniedException;
import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepInput;
import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepOutput;
import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference;
import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldMetaData;
import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldType;
import com.kingsrook.qqq.backend.core.model.metadata.processes.QBackendStepMetaData;
import com.kingsrook.qqq.backend.core.model.metadata.processes.QComponentType;
import com.kingsrook.qqq.backend.core.model.metadata.processes.QFrontendComponentMetaData;
import com.kingsrook.qqq.backend.core.model.metadata.processes.QFrontendStepMetaData;
import com.kingsrook.qqq.backend.core.model.metadata.processes.QProcessMetaData;
import com.kingsrook.qqq.backend.core.model.metadata.qbits.QBitMetaData;
import com.kingsrook.qqq.backend.core.model.metadata.scheduleing.QScheduleMetaData;
import com.kingsrook.qqq.backend.core.model.session.QSystemUserSession;
import org.json.JSONObject;
/*******************************************************************************
** Tenant-authorized retention settings and bounded document cleanup using QQQ.
*******************************************************************************/
public class PrintingRetentionProcesses implements BackendStep
{
public static final String SETTINGS = "printingRetentionSettings";
public static final String RUN_NOW = "printingRunRetention";
public static final String SCHEDULED = "printingScheduledRetention";
/***************************************************************************
** Register native settings and confirmation forms; schedule only on a host scheduler.
***************************************************************************/
public static void register(QInstance instance, PrintingQBitConfig config)
{
QProcessMetaData settings = manual(SETTINGS, "Printing retention settings")
.withStep(review("Current retention and storage"))
.withStep(new QFrontendStepMetaData().withName("settings").withLabel("Edit retention")
.withFormFields(List.of(new QFieldMetaData("days", QFieldType.INTEGER).withLabel("Keep successful job documents for days (1–36500)").withIsRequired(true),
new QFieldMetaData("enabled", QFieldType.BOOLEAN).withLabel("Enable document retention cleanup").withIsRequired(true)))
.withComponent(new QFrontendComponentMetaData().withType(QComponentType.EDIT_FORM)))
.withStep(backend("execute")).withStep(result());
instance.addProcess(settings);
instance.addProcess(manual(RUN_NOW, "Run printing retention cleanup")
.withStep(review("Review cleanup before continuing")).withStep(backend("execute")).withStep(result()));
if(config.getSchedulerName() != null && !config.getSchedulerName().isBlank())
{
instance.addProcess(new QProcessMetaData().withName(SCHEDULED).withLabel("Scheduled printing retention cleanup").withIsHidden(true)
.withPermissionRules(PrintingProcesses.permissionRules()).withStep(backend("execute"))
.withSchedule(new QScheduleMetaData().withSchedulerName(config.getSchedulerName())
.withCronExpression("0 */5 * * * ?").withCronTimeZoneId("UTC")
.withDescription("Remove one bounded batch of eligible successful print documents using the tenant retention policy.")));
}
}
/***************************************************************************
** Prepare each form from live tenant settings rather than stale metadata defaults.
***************************************************************************/
private static QProcessMetaData manual(String name, String label)
{
return (new QProcessMetaData().withName(name).withLabel(label).withPermissionRules(PrintingProcesses.permissionRules()).withStep(backend("prepare")));
}
/***************************************************************************
** All step entrypoints repeat permission checks, including direct backend invocation.
***************************************************************************/
private static QBackendStepMetaData backend(String name)
{
return (new QBackendStepMetaData().withName(name).withCode(new QCodeReference(PrintingRetentionProcesses.class)));
}
/***************************************************************************
** Read-only deployment details intentionally expose no editable backend IDs or credentials.
***************************************************************************/
private static QFrontendStepMetaData review(String label)
{
return (new QFrontendStepMetaData().withName("review").withLabel(label)
.withViewFields(List.of(text("policy", "Retention policy"), text("storage", "Document storage"), text("schedule", "Automatic schedule"), text("progress", "Cleanup progress"), text("safety", "What cleanup does")))
.withComponent(new QFrontendComponentMetaData().withType(QComponentType.VIEW_FORM)));
}
/***************************************************************************
** Keep native result rendering consistent with other printing processes.
***************************************************************************/
private static QFrontendStepMetaData result()
{
return (new QFrontendStepMetaData().withName("result").withLabel("Result").withViewFields(List.of(text("result", "Result")))
.withComponent(new QFrontendComponentMetaData().withType(QComponentType.VIEW_FORM)));
}
/***************************************************************************
** Plain text view fields cannot act as arbitrary storage selectors.
***************************************************************************/
private static QFieldMetaData text(String name, String label)
{
return (new QFieldMetaData(name, QFieldType.STRING).withLabel(label));
}
/***************************************************************************
** Scheduled system execution stays bound to this QQQ instance's configured tenant.
***************************************************************************/
@Override
public void run(RunBackendStepInput input, RunBackendStepOutput output) throws QException
{
boolean scheduled = SCHEDULED.equals(input.getProcessName());
PrintingService service;
if(scheduled)
{
if(!(QContext.getQSession() instanceof QSystemUserSession))
{
throw new QPermissionDeniedException("The scheduled retention entrypoint requires the system session; use Run retention cleanup instead");
}
service = configuration().getService();
}
else
{
new PrintingAdminPermission().checkPermissionsThrowing(input, null);
service = PrintingProcesses.currentService();
}
try
{
if("prepare".equals(input.getStepName()) && (SETTINGS.equals(input.getProcessName()) || RUN_NOW.equals(input.getProcessName())))
{
prepare(service, output);
}
else if("execute".equals(input.getStepName()) && SETTINGS.equals(input.getProcessName()))
{
Integer days = input.getValueInteger("days");
Boolean enabled = input.getValueBoolean("enabled");
if(days == null || enabled == null)
{
throw new QException("Specify retention days and whether cleanup is enabled");
}
service.saveRetentionSettings(days, enabled);
output.addValue("result", "Printing retention settings saved for this tenant. Changing the policy does not run cleanup immediately.");
}
else if("execute".equals(input.getStepName()) && (RUN_NOW.equals(input.getProcessName()) || scheduled))
{
int removed = service.runRetention();
output.addValue("result", "Removed " + removed + " eligible documents or abandoned uploads. Job receipts and uncertain or active work were preserved. Cleanup processes one bounded batch per run.");
}
else
{
throw new QException("Unknown printing retention action");
}
}
catch(java.sql.SQLException | PrintingException | IllegalArgumentException exception)
{
throw new QException("Printing retention action failed: " + exception.getMessage(), exception);
}
}
/***************************************************************************
** Show effective policy and resolved storage scope without exposing secrets.
***************************************************************************/
private static void prepare(PrintingService service, RunBackendStepOutput output) throws java.sql.SQLException, QException
{
JSONObject settings = service.getRetentionSettings();
output.addValue("days", settings.getInt("days"));
output.addValue("enabled", settings.getBoolean("enabled"));
output.addValue("policy", (settings.getBoolean("enabled") ? "Enabled" : "Disabled") + ": retain successful job documents for " + settings.getInt("days") + " days; at most " + settings.getInt("batchSize") + " documents per run.");
String table = settings.optString("storageTableName", "");
String label = QContext.getQInstance().getTable(table) == null ? table : QContext.getQInstance().getTable(table).getLabel();
output.addValue("storage", table.isBlank() ? "Dedicated printing storage is not configured. Ask the application administrator to bind an existing QQQ storage table and dedicated printing bucket."
: label + "; bucket: " + settings.optString("bucketName", "Configured by the host") + "; tenant prefix: " + settings.optString("storagePrefix", "Scoped by the service"));
String scheduler = configuration().getSchedulerName();
output.addValue("schedule", scheduler == null || scheduler.isBlank() ? "Not scheduled. Configure a host QQQ scheduler to enable automatic cleanup; Run cleanup remains available." : "Every five minutes (UTC) using the host QQQ scheduler; overlapping runs are prevented.");
String lastRun = settings.optString("lastRunAt", "");
output.addValue("progress", "Eligible documents waiting: " + settings.optLong("eligibleBacklog", 0)
+ "; last run: " + (lastRun.isBlank() ? "Not run yet" : lastRun) + "; removed: " + settings.optInt("lastRunCount", 0)
+ (settings.optString("lastRunError", "").isBlank() ? "" : "; last run problem: " + settings.optString("lastRunError")));
output.addValue("safety", "Cleanup removes only old successful-terminal document content. Active, failed and uncertain jobs, receipt metadata and deduplication records remain. Removed documents cannot be reprinted from history. Continue to edit the policy or run the selected cleanup action.");
}
/***************************************************************************
** Avoid static service caches and prevent a scheduler from crossing instance boundaries.
***************************************************************************/
private static PrintingQBitConfig configuration() throws QException
{
for(QBitMetaData metadata : QContext.getQInstance().getQBits().values())
{
if(metadata.getConfig() instanceof PrintingQBitConfig config && config.getService() != null)
{
return (config);
}
}
throw new QException("Printing QBit is not configured");
}
}
@@ -38,6 +38,13 @@ public class PrintingRoutes implements QJavalinRouteProviderInterface
public static final String BASE = "/printing/v1";
private final PrintingService service;
private final Predicate<Context> administrator;
private final LegacyEnrollment legacyEnrollment;
/** Legacy-only hosts must explicitly opt into bearer-only device enrollment. */
public enum LegacyEnrollment
{
DISABLED, ENABLED
}
@@ -45,9 +52,17 @@ public class PrintingRoutes implements QJavalinRouteProviderInterface
** Attach this route provider to the host's QApplicationJavalinServer.
***************************************************************************/
public PrintingRoutes(PrintingService service, Predicate<Context> administrator)
{
this(service, administrator, LegacyEnrollment.DISABLED);
}
/** Existing unbound devices may migrate; new legacy enrollment is an explicit host policy. */
public PrintingRoutes(PrintingService service, Predicate<Context> administrator, LegacyEnrollment legacyEnrollment)
{
this.service = service;
this.administrator = administrator;
this.legacyEnrollment = java.util.Objects.requireNonNull(legacyEnrollment);
}
@@ -69,18 +84,54 @@ public class PrintingRoutes implements QJavalinRouteProviderInterface
@Override
public void acceptJavalinConfig(JavalinConfig config)
{
config.routes.post(BASE + "/enroll", context -> handle(context, () -> service.enroll(body(context))));
config.routes.get(BASE + "/version", context -> handle(context, () -> new JSONObject().put("protocolVersion", 1).put("capabilities", new org.json.JSONArray().put("device-control-v1"))));
config.routes.post(BASE + "/device/control/poll", context -> handle(context, () -> service.deviceControlPoll(device(context), controlBody(context))));
config.routes.post(BASE + "/device/control/commands/{commandId}/receipt", context -> handle(context, () -> service.deviceControlReceipt(device(context), context.pathParam("commandId"), controlBody(context))));
config.routes.post(BASE + "/admin/devices/{deviceId}/actions", context -> handle(context, () ->
{
admin(context);
return service.deviceAction(context.pathParam("deviceId"), controlBody(context), "http-administrator");
}));
config.routes.get(BASE + "/admin/devices/{deviceId}/commands", context -> handle(context, () ->
{
admin(context);
String limit = context.queryParam("limit");
return service.deviceCommandsPage(context.pathParam("deviceId"), limit == null ? 50 : Integer.parseInt(limit), context.queryParam("before"));
}));
config.routes.get(BASE + "/admin/devices/{deviceId}/commands/{commandId}", context -> handle(context, () ->
{
admin(context);
return service.getDeviceCommand(context.pathParam("deviceId"), context.pathParam("commandId"));
}));
config.routes.post(BASE + "/enroll", context -> handle(context, () ->
{
if(legacyEnrollment != LegacyEnrollment.ENABLED)
{
throw new PrintingException(403, "Enrollment requires native QQQ authentication");
}
return service.enroll(body(context));
}));
config.routes.put(BASE + "/device/printers", context -> handle(context, () ->
{
service.inventory(device(context), body(context).getJSONArray("printers"));
return accepted();
}));
config.routes.post(BASE + "/device/heartbeat", context -> handle(context, () -> service.heartbeat(device(context), body(context))));
config.routes.post(BASE + "/device/jobs/claim", context -> handle(context, () -> service.claim(device(context))));
config.routes.post(BASE + "/device/jobs/claim", context -> handle(context, () ->
{
String device = device(context);
body(context);
return service.claim(device);
}));
config.routes.get(BASE + "/device/jobs/queued", context -> handle(context, () -> new JSONObject().put("jobs", service.queuedJobs(device(context)))));
config.routes.post(BASE + "/device/test-print", context -> handle(context, () -> service.testPrint(device(context), body(context))));
config.routes.post(BASE + "/device/jobs/{jobId}/retry", context -> handle(context, () -> service.retry(device(context), context.pathParam("jobId"), body(context))));
config.routes.post(BASE + "/device/jobs/{jobId}/cancel", context -> handle(context, () -> service.cancel(device(context), context.pathParam("jobId"))));
config.routes.post(BASE + "/device/jobs/{jobId}/cancel", context -> handle(context, () ->
{
String device = device(context);
body(context);
return service.cancel(device, context.pathParam("jobId"));
}));
config.routes.get(BASE + "/device/jobs/{jobId}/content", context -> handle(context, () ->
{
byte[] bytes = service.content(device(context), context.pathParam("jobId"));
@@ -107,7 +158,8 @@ public class PrintingRoutes implements QJavalinRouteProviderInterface
config.routes.get(BASE + "/admin/devices/{deviceId}/printers", context -> handle(context, () ->
{
admin(context);
return new JSONObject().put("printers", service.printers(context.pathParam("deviceId")));
String limit = context.queryParam("limit");
return service.printersPage(context.pathParam("deviceId"), limit == null ? 200 : Integer.parseInt(limit), context.queryParam("before"));
}));
config.routes.put(BASE + "/admin/devices/{deviceId}/printers/{printerId}", context -> handle(context, () ->
{
@@ -184,8 +236,19 @@ public class PrintingRoutes implements QJavalinRouteProviderInterface
/***************************************************************************
** Standard mutation acknowledgment.
** Control messages have their own small transport bound.
***************************************************************************/
private static JSONObject controlBody(Context context)
{
if(context.bodyAsBytes().length > 8192)
{
throw new PrintingException(413, "Control request is too large");
}
return (new JSONObject(context.body()));
}
/** Standard mutation acknowledgment. */
private static JSONObject accepted()
{
return (new JSONObject().put("accepted", true));
File diff suppressed because it is too large. Load diff
@@ -29,6 +29,7 @@ public final class PrintingTables
public static final String DEVICE = "printing_device";
public static final String PRINTER = "printing_printer";
public static final String JOB = "printing_job";
public static final String COMMAND = "printing_device_command";
@@ -0,0 +1,382 @@
/*
* QQQ - Low-code Application Framework for Engineers.
* Copyright (C) 2021-2025. Kingsrook, LLC
* 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
* contact@kingsrook.com
* https://github.com/Kingsrook/
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.kingsrook.qbits.printing;
import javax.imageio.ImageIO;
import java.awt.Color;
import java.awt.Font;
import java.awt.FontFormatException;
import java.awt.Graphics2D;
import java.awt.RenderingHints;
import java.awt.image.BufferedImage;
import java.io.ByteArrayOutputStream;
import java.io.IOException;
import java.io.InputStream;
import java.nio.charset.StandardCharsets;
import java.util.HexFormat;
import java.util.Set;
import com.kingsrook.qqq.backend.core.exceptions.QException;
import org.apache.pdfbox.cos.COSArray;
import org.apache.pdfbox.cos.COSName;
import org.apache.pdfbox.cos.COSString;
import org.apache.pdfbox.pdmodel.PDDocument;
import org.apache.pdfbox.pdmodel.PDPage;
import org.apache.pdfbox.pdmodel.PDPageContentStream;
import org.apache.pdfbox.pdmodel.common.PDRectangle;
import org.apache.pdfbox.pdmodel.font.PDType0Font;
import org.apache.pdfbox.pdmodel.graphics.image.LosslessFactory;
/*******************************************************************************
** Shared diagnostic documents. Font data travels with each job, never as a
** persistent printer download or an assumption about installed printer fonts.
*******************************************************************************/
public final class PrintingTestDocuments
{
static final String FONT_RESOURCE = "/com/kingsrook/qbits/printing/fonts/JetBrainsMono-Bold.ttf";
private static final String LOGO_RESOURCE = "/com/kingsrook/qbits/printing/images/query-mascot.png";
static final String BARCODE_VALUE = "QQQ-TEST-123456";
/***************************************************************************
** One vector Letter page with an embedded, subsetted warehouse test font.
***************************************************************************/
public static byte[] pdf() throws QException
{
return (pdf(TestPrintProfile.LETTER));
}
/***************************************************************************
** PDF media is explicit; label profiles retain their four-by-six-inch size.
***************************************************************************/
public static byte[] pdf(TestPrintProfile profile) throws QException
{
try(PDDocument document = new PDDocument(); InputStream fontStream = fontStream())
{
COSArray identifiers = new COSArray();
identifiers.add(new COSString("QQQ-TEST-" + profile.name()));
identifiers.add(new COSString("QQQ-TEST-" + profile.name()));
document.getDocument().getTrailer().setItem(COSName.ID, identifiers);
PDType0Font font = PDType0Font.load(document, fontStream, true);
PDRectangle media = profile.getDpi() > 0 ? new PDRectangle(288, 432) : (profile == TestPrintProfile.A4 ? PDRectangle.A4 : PDRectangle.LETTER);
PDPage page = new PDPage(media);
document.addPage(page);
try(PDPageContentStream content = new PDPageContentStream(document, page))
{
if(profile.getDpi() > 0)
{
pdfLabel(content, font);
content.drawImage(LosslessFactory.createFromImage(document, logo()), 210, 348, 54, 54);
}
else
{
pdfText(content, font, 56, 48, 690, "QQQ");
content.drawImage(LosslessFactory.createFromImage(document, logo()), media.getWidth() - 132, 660, 84, 84);
pdfText(content, font, 18, 48, 650, "WAREHOUSE PRINT CHECK");
pdfText(content, font, 14, 48, 620, "TEST PRINT - NOT POSTAGE");
pdfText(content, font, 11, 48, 590, (profile == TestPrintProfile.A4 ? "A4 210 x 297 mm" : "LETTER 8.5 x 11 in") + " / ACTUAL SIZE");
pdfText(content, font, 12, 48, 535, "READ EACH CHARACTER");
pdfText(content, font, 32, 48, 490, "0O 1Il 5S 8B 2Z 6G");
pdfText(content, font, 18, 48, 440, "BIN A01-I1 / SKU O0-5S8B");
pdfText(content, font, 18, 48, 410, "ORDER QQQ-123456 / QTY 02");
pdfText(content, font, 12, 48, 350, "Measure this line: 25.4 mm / 1 inch");
content.setLineWidth(1);
content.moveTo(48, 330);
content.lineTo(120, 330);
content.moveTo(48, 325);
content.lineTo(48, 335);
content.moveTo(120, 325);
content.lineTo(120, 335);
content.stroke();
pdfGrayBars(content);
pdfText(content, font, 10, 48, 195, "Check edges, solid fill and each gray level.");
pdfText(content, font, 10, 48, 170, "Confirm paper output; SPOOLED means submitted only.");
content.addRect(36, 36, media.getWidth() - 72, media.getHeight() - 72);
content.stroke();
}
}
ByteArrayOutputStream bytes = new ByteArrayOutputStream();
document.save(bytes);
return (bytes.toByteArray());
}
catch(IOException exception)
{
throw new QException("Could not generate branded test PDF", exception);
}
}
/***************************************************************************
** Compatibility default for callers that have no configured label density.
***************************************************************************/
public static byte[] zpl() throws QException
{
return (zpl(203));
}
/***************************************************************************
** Reject page-only profiles even when invoked outside the HTTP entrypoint.
***************************************************************************/
public static byte[] zpl(TestPrintProfile profile) throws QException
{
return (zpl(profile.getDpi()));
}
/***************************************************************************
** A four-by-six-inch label at the explicitly chosen printer resolution.
** Text uses the bundled font rasterized to one bit; Code 128 stays native.
***************************************************************************/
public static byte[] zpl(int dpi) throws QException
{
BufferedImage image = labelImage(dpi);
int rowBytes = (image.getWidth() + 7) / 8;
byte[] bitmap = new byte[rowBytes * image.getHeight()];
for(int y = 0; y < image.getHeight(); y++)
{
for(int x = 0; x < image.getWidth(); x++)
{
if((image.getRGB(x, y) & 0xffffff) == 0)
{
bitmap[y * rowBytes + x / 8] |= (byte) (0x80 >>> (x % 8));
}
}
}
int module = Math.max(2, dpi / 100);
StringBuilder zpl = new StringBuilder("^XA^PW" + image.getWidth() + "^LL" + image.getHeight() + "^LH0,0");
appendGraphicStrips(zpl, bitmap, rowBytes, image.getHeight());
zpl.append("^FO").append(dots(24, dpi)).append(',').append(dots(276, dpi)).append("^BY").append(module)
.append("^BCN,").append(dots(42, dpi)).append(",N,N,N^FD").append(BARCODE_VALUE).append("^FS^PQ1^XZ");
return (zpl.toString().getBytes(StandardCharsets.US_ASCII));
}
/***************************************************************************
** Zebra limits each graphic field to 99,999 bytes. Whole-row strips preserve
** padding and image coordinates without downloading persistent graphics.
***************************************************************************/
private static void appendGraphicStrips(StringBuilder zpl, byte[] bitmap, int rowBytes, int height)
{
int rowsPerStrip = 99999 / rowBytes;
for(int firstRow = 0; firstRow < height; firstRow += rowsPerStrip)
{
int rows = Math.min(rowsPerStrip, height - firstRow);
int length = rows * rowBytes;
int offset = firstRow * rowBytes;
zpl.append("^FO0,").append(firstRow).append("^GFA,").append(length).append(',').append(length).append(',').append(rowBytes).append(',')
.append(HexFormat.of().withUpperCase().formatHex(bitmap, offset, offset + length)).append("^FS");
}
}
/***************************************************************************
** Deterministic image also supports inspection without contacting a printer.
***************************************************************************/
static BufferedImage labelImage(int dpi) throws QException
{
if(!Set.of(203, 300, 600).contains(dpi))
{
throw new IllegalArgumentException("Label resolution must be 203, 300 or 600 dpi");
}
try(InputStream stream = fontStream())
{
Font font = Font.createFont(Font.TRUETYPE_FONT, stream);
BufferedImage image = new BufferedImage(dpi * 4, dpi * 6, BufferedImage.TYPE_BYTE_BINARY);
Graphics2D graphics = image.createGraphics();
try
{
graphics.setColor(Color.WHITE);
graphics.fillRect(0, 0, image.getWidth(), image.getHeight());
graphics.scale(dpi / 72.0, dpi / 72.0);
graphics.setColor(Color.BLACK);
graphics.setRenderingHint(RenderingHints.KEY_TEXT_ANTIALIASING, RenderingHints.VALUE_TEXT_ANTIALIAS_OFF);
graphics.drawRect(12, 12, 264, 408);
graphics.drawImage(logo(), 210, 30, 54, 54, null);
labelText(graphics, font, 43, 24, 58, "QQQ");
labelText(graphics, font, 10, 24, 79, "WAREHOUSE PRINT CHECK");
labelText(graphics, font, 12, 24, 101, "TEST PRINT - NOT POSTAGE");
labelText(graphics, font, 9, 24, 119, "4 x 6 in / " + dpi + " dpi / 1 copy");
graphics.drawLine(24, 130, 264, 130);
labelText(graphics, font, 9, 24, 148, "READ EACH CHARACTER");
labelText(graphics, font, 25, 24, 179, "0O 1Il 5S");
labelText(graphics, font, 25, 24, 210, "8B 2Z 6G");
labelText(graphics, font, 12, 24, 239, "BIN A01-I1 / SKU O0-5S8B");
labelText(graphics, font, 12, 24, 258, "ORDER QQQ-123456 / QTY 02");
labelText(graphics, font, 10, 24, 338, "SCAN: " + BARCODE_VALUE);
graphics.drawLine(24, 365, 96, 365);
graphics.drawLine(24, 361, 24, 369);
graphics.drawLine(96, 361, 96, 369);
labelText(graphics, font, 9, 106, 368, "25.4 mm / 1 inch");
labelText(graphics, font, 8, 24, 398, "Confirm output, size and barcode scan.");
}
finally
{
graphics.dispose();
}
return (image);
}
catch(IOException | FontFormatException exception)
{
throw new QException("Could not generate branded test label", exception);
}
}
/***************************************************************************
** Fail explicitly if packaging omitted the licensed font resource.
***************************************************************************/
private static InputStream fontStream() throws IOException
{
InputStream stream = PrintingTestDocuments.class.getResourceAsStream(FONT_RESOURCE);
if(stream == null)
{
throw new IOException("Bundled test-document font is missing");
}
return (stream);
}
/***************************************************************************
** Preserve Query's official artwork and aspect ratio inside square layout
** boxes, compositing transparency on white before monochrome printing.
***************************************************************************/
private static BufferedImage logo() throws IOException
{
try(InputStream stream = PrintingTestDocuments.class.getResourceAsStream(LOGO_RESOURCE))
{
if(stream == null)
{
throw new IOException("Bundled Query mascot is missing");
}
BufferedImage source = ImageIO.read(stream);
int size = Math.max(source.getWidth(), source.getHeight());
BufferedImage image = new BufferedImage(size, size, BufferedImage.TYPE_BYTE_BINARY);
Graphics2D graphics = image.createGraphics();
try
{
graphics.setColor(Color.WHITE);
graphics.fillRect(0, 0, image.getWidth(), image.getHeight());
graphics.drawImage(source, (size - source.getWidth()) / 2, (size - source.getHeight()) / 2, null);
}
finally
{
graphics.dispose();
}
return (image);
}
}
/***************************************************************************
** Convert layout points to printer dots without changing physical size.
***************************************************************************/
private static int dots(int points, int dpi)
{
return ((int) Math.round(points * dpi / 72.0));
}
/***************************************************************************
** Draw text using the same bundled face on both document formats.
***************************************************************************/
private static void labelText(Graphics2D graphics, Font font, int size, int x, int y, String text)
{
graphics.setFont(font.deriveFont((float) size));
graphics.drawString(text, x, y);
}
/***************************************************************************
** Vector PDF text remains searchable and carries its own font subset.
***************************************************************************/
private static void pdfText(PDPageContentStream content, PDType0Font font, int size, int x, int y, String text) throws IOException
{
content.beginText();
content.setFont(font, size);
content.newLineAtOffset(x, y);
content.showText(text);
content.endText();
}
/***************************************************************************
** Five vector gray levels expose missing toner and driver conversion.
***************************************************************************/
private static void pdfGrayBars(PDPageContentStream content) throws IOException
{
for(int index = 0; index < 5; index++)
{
content.setNonStrokingColor(index / 4.0f);
content.addRect(48 + index * 72, 240, 72, 48);
content.fill();
}
content.setNonStrokingColor(0f);
content.addRect(48, 240, 360, 48);
content.stroke();
}
/***************************************************************************
** Compact label PDF keeps vector glyphs and explicit physical media bounds.
***************************************************************************/
private static void pdfLabel(PDPageContentStream content, PDType0Font font) throws IOException
{
pdfText(content, font, 43, 24, 374, "QQQ");
pdfText(content, font, 10, 24, 353, "WAREHOUSE PRINT CHECK");
pdfText(content, font, 12, 24, 331, "TEST PRINT - NOT POSTAGE");
pdfText(content, font, 9, 24, 313, "4 x 6 in / PDF / ACTUAL SIZE");
pdfText(content, font, 9, 24, 284, "READ EACH CHARACTER");
pdfText(content, font, 25, 24, 253, "0O 1Il 5S");
pdfText(content, font, 25, 24, 222, "8B 2Z 6G");
pdfText(content, font, 12, 24, 193, "BIN A01-I1 / SKU O0-5S8B");
pdfText(content, font, 12, 24, 174, "ORDER QQQ-123456 / QTY 02");
pdfText(content, font, 11, 24, 132, "PDF FONT / SCALE CHECK");
pdfText(content, font, 9, 106, 64, "25.4 mm / 1 inch");
pdfText(content, font, 8, 24, 34, "Confirm output and measure the line.");
content.setLineWidth(1);
content.moveTo(24, 67);
content.lineTo(96, 67);
content.moveTo(24, 63);
content.lineTo(24, 71);
content.moveTo(96, 63);
content.lineTo(96, 71);
content.addRect(12, 12, 264, 408);
content.stroke();
}
}
@@ -0,0 +1,295 @@
/*
* QQQ - Low-code Application Framework for Engineers.
* Copyright (C) 2021-2025. Kingsrook, LLC
* 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
* contact@kingsrook.com
* https://github.com/Kingsrook/
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.kingsrook.qbits.printing;
import java.util.LinkedHashMap;
import java.util.Map;
import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
import com.kingsrook.qqq.middleware.javalin.specs.extensions.MiddlewareSpecExtension;
import com.kingsrook.qqq.middleware.javalin.specs.extensions.MiddlewareSpecExtensionsMetaData;
import com.kingsrook.qqq.openapi.model.HttpMethod;
import com.kingsrook.qqq.openapi.model.Response;
import com.kingsrook.qqq.openapi.model.Schema;
import com.kingsrook.qqq.openapi.model.Type;
import io.javalin.http.Context;
/** Native QQQ printing extension; core session authentication stays authoritative. */
public final class PrintingUiApi
{
public static final String PREFIX = "/qbit/printing";
/** Static registry. */
private PrintingUiApi()
{
}
/** Producer registration gives discovery, OpenAPI, session setup and credential scopes. */
public static void register(QInstance instance)
{
MiddlewareSpecExtensionsMetaData.ofOrWithNew(instance).withExtension(extension());
}
/** Semantic extension version 1.0.0 includes device-control-v1. */
public static MiddlewareSpecExtension extension()
{
return (new MiddlewareSpecExtension().withName("printing").withSemanticVersion("1.0.0")
.withDescription("Native current-user printing with secondary device proof and device-control-v1.")
.withSpec(Session.class)
.withSpec(Bind.class)
.withSpec(Enroll.class)
.withSpec(Heartbeat.class)
.withSpec(Inventory.class)
.withSpec(Claim.class)
.withSpec(Queued.class)
.withSpec(Content.class)
.withSpec(Event.class)
.withSpec(Test.class)
.withSpec(Retry.class)
.withSpec(Cancel.class)
.withSpec(Poll.class)
.withSpec(Receipt.class)
.withSpec(Action.class)
.withSpec(Commands.class)
.withSpec(Command.class));
}
/** Session native endpoint. */
public static class Session extends PrintingUiApiSpec
{
/** Public no-argument constructor required by the core extension registry. */
public Session()
{
super("Session", HttpMethod.GET, "/session", null, "Session");
}
}
/** Bind native endpoint. */
public static class Bind extends PrintingUiApiSpec
{
/** Public no-argument constructor required by the core extension registry. */
public Bind()
{
super("Bind", HttpMethod.POST, "/device/bind", "Empty", "Acknowledgment");
}
}
/** Enroll native endpoint. */
public static class Enroll extends PrintingUiApiSpec
{
/** Public no-argument constructor required by the core extension registry. */
public Enroll()
{
super("Enroll", HttpMethod.POST, "/devices/enroll", "EnrollmentRequest", "Enrollment");
}
}
/** Heartbeat native endpoint. */
public static class Heartbeat extends PrintingUiApiSpec
{
/** Public no-argument constructor required by the core extension registry. */
public Heartbeat()
{
super("Heartbeat", HttpMethod.POST, "/device/heartbeat", "HeartbeatRequest", "Heartbeat");
}
}
/** Inventory native endpoint. */
public static class Inventory extends PrintingUiApiSpec
{
/** Public no-argument constructor required by the core extension registry. */
public Inventory()
{
super("Inventory", HttpMethod.PUT, "/device/printers", "InventoryRequest", "Acknowledgment");
}
}
/** Claim native endpoint. */
public static class Claim extends PrintingUiApiSpec
{
/** Public no-argument constructor required by the core extension registry. */
public Claim()
{
super("Claim", HttpMethod.POST, "/device/jobs/claim", "Empty", "Claim");
}
}
/** Queued native endpoint. */
public static class Queued extends PrintingUiApiSpec
{
/** Public no-argument constructor required by the core extension registry. */
public Queued()
{
super("Queued", HttpMethod.GET, "/device/jobs/queued", null, "Jobs");
}
}
/** Content native endpoint. */
public static class Content extends PrintingUiApiSpec
{
/** Public no-argument constructor required by the core extension registry. */
public Content()
{
super("Content", HttpMethod.GET, "/device/jobs/{jobId}/content", null, "Empty");
}
/** Binary document bytes use an explicit octet-stream OpenAPI response. */
@Override
public Map<Integer, Response> defineResponses()
{
Map<Integer, Response> responses = new LinkedHashMap<>(super.defineResponses());
responses.put(200, new Response().withDescription("Verified retained document bytes")
.withContent(Map.of("application/octet-stream", new com.kingsrook.qqq.openapi.model.Content().withSchema(new Schema().withType(Type.STRING).withFormat("binary")))));
return (responses);
}
/** Do not JSON-serialize document contents or include them in logs. */
@Override
public void handleOutput(Context context, JsonOutput output)
{
context.header("Cache-Control", "no-store").contentType("application/octet-stream").result((byte[]) output.getResult());
}
}
/** Event native endpoint. */
public static class Event extends PrintingUiApiSpec
{
/** Public no-argument constructor required by the core extension registry. */
public Event()
{
super("Event", HttpMethod.POST, "/device/jobs/{jobId}/events", "EventRequest", "Acknowledgment");
}
}
/** Test native endpoint. */
public static class Test extends PrintingUiApiSpec
{
/** Public no-argument constructor required by the core extension registry. */
public Test()
{
super("Test", HttpMethod.POST, "/device/test-print", "TestRequest", "Job");
}
}
/** Retry native endpoint. */
public static class Retry extends PrintingUiApiSpec
{
/** Public no-argument constructor required by the core extension registry. */
public Retry()
{
super("Retry", HttpMethod.POST, "/device/jobs/{jobId}/retry", "RetryRequest", "Job");
}
}
/** Cancel native endpoint. */
public static class Cancel extends PrintingUiApiSpec
{
/** Public no-argument constructor required by the core extension registry. */
public Cancel()
{
super("Cancel", HttpMethod.POST, "/device/jobs/{jobId}/cancel", "Empty", "Acknowledgment");
}
}
/** Poll native endpoint. */
public static class Poll extends PrintingUiApiSpec
{
/** Public no-argument constructor required by the core extension registry. */
public Poll()
{
super("Poll", HttpMethod.POST, "/device/control/poll", "ControlPollRequest", "ControlPoll");
}
}
/** Receipt native endpoint. */
public static class Receipt extends PrintingUiApiSpec
{
/** Public no-argument constructor required by the core extension registry. */
public Receipt()
{
super("Receipt", HttpMethod.POST, "/device/control/commands/{commandId}/receipt", "ReceiptRequest", "Acknowledgment");
}
}
/** Action native endpoint. */
public static class Action extends PrintingUiApiSpec
{
/** Public no-argument constructor required by the core extension registry. */
public Action()
{
super("Action", HttpMethod.POST, "/admin/devices/{deviceId}/actions", "ActionRequest", "Action");
}
}
/** Commands native endpoint. */
public static class Commands extends PrintingUiApiSpec
{
/** Public no-argument constructor required by the core extension registry. */
public Commands()
{
super("Commands", HttpMethod.GET, "/admin/devices/{deviceId}/commands", null, "Actions");
}
}
/** Command native endpoint. */
public static class Command extends PrintingUiApiSpec
{
/** Public no-argument constructor required by the core extension registry. */
public Command()
{
super("Command", HttpMethod.GET, "/admin/devices/{deviceId}/commands/{commandId}", null, "Action");
}
}
}
@@ -0,0 +1,331 @@
/*
* QQQ - Low-code Application Framework for Engineers.
* Copyright (C) 2021-2025. Kingsrook, LLC
* 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
* contact@kingsrook.com
* https://github.com/Kingsrook/
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.kingsrook.qbits.printing;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;
import com.kingsrook.qqq.backend.core.exceptions.QAuthenticationException;
import com.kingsrook.qqq.backend.core.exceptions.QBadRequestException;
import com.kingsrook.qqq.backend.core.exceptions.QException;
import com.kingsrook.qqq.backend.core.exceptions.QPermissionDeniedException;
import com.kingsrook.qqq.backend.core.model.data.QRecord;
import com.kingsrook.qqq.middleware.javalin.QJavalinUtils;
import com.kingsrook.qqq.middleware.javalin.specs.BasicOperation;
import com.kingsrook.qqq.middleware.javalin.specs.BasicResponse;
import com.kingsrook.qqq.middleware.javalin.specs.extensions.AbstractJsonEndpointSpec;
import com.kingsrook.qqq.middleware.javalin.specs.v1.responses.BasicErrorResponseV1;
import com.kingsrook.qqq.openapi.model.HttpMethod;
import com.kingsrook.qqq.openapi.model.In;
import com.kingsrook.qqq.openapi.model.Parameter;
import com.kingsrook.qqq.openapi.model.Schema;
import com.kingsrook.qqq.openapi.model.Type;
import io.javalin.http.Context;
import io.javalin.http.HttpStatus;
import org.json.JSONArray;
import org.json.JSONObject;
/** Native secured QQQ specs: session setup and credential scope execute before request construction. */
public abstract class PrintingUiApiSpec extends AbstractJsonEndpointSpec
{
private final String operation;
private final String path;
private final HttpMethod method;
private final String requestSchema;
private final String responseSchema;
/** Immutable operation metadata; request credentials never live on shared spec instances. */
protected PrintingUiApiSpec(String operation, HttpMethod method, String path, String requestSchema, String responseSchema)
{
this.operation = operation;
this.method = method;
this.path = path;
this.requestSchema = requestSchema;
this.responseSchema = responseSchema;
}
/** All operations are discoverable under the registered extension namespace. */
@Override
public BasicOperation defineBasicOperation()
{
return (new BasicOperation().withHttpMethod(method).withPath(PrintingUiApi.PREFIX + path)
.withOperationId("printing" + operation).withShortSummary("Printing " + operation)
.withLongDescription("Requires the current QQQ user session, printing_admin permission and native record access. Device operations additionally require secondary device headers bound to this principal. No primary device-bearer authentication."));
}
/** Typed request bodies use the same wire vocabulary as the native client. */
@Override
protected Schema defineRequestBodySchema()
{
return (requestSchema == null ? null : PrintingApiSchemas.ref(requestSchema));
}
/** Typed response body. */
@Override
protected String getResponseSchemaName()
{
return (PrintingApiSchemas.name(responseSchema));
}
/** Complete namespaced component definitions are merged into the core OpenAPI document. */
@Override
public Map<String, Schema> defineComponentSchemas()
{
return (PrintingApiSchemas.components());
}
/** Document secondary proof independently from core session authentication. */
@Override
public List<Parameter> defineRequestParameters()
{
List<Parameter> parameters = new ArrayList<>();
if(path.startsWith("/device/") || "Session".equals(operation))
{
boolean required = !"Session".equals(operation);
parameters.add(new Parameter().withName(PrintingAgentAuthorization.DEVICE_HEADER).withIn(In.HEADER).withRequired(required).withSchema(PrintingApiSchemas.text(36)));
parameters.add(new Parameter().withName(PrintingAgentAuthorization.TOKEN_HEADER).withIn(In.HEADER).withRequired(required).withSchema(PrintingApiSchemas.text(128)).withDescription("Private secondary device proof; never log."));
}
for(String name : List.of("deviceId", "jobId", "commandId"))
{
if(path.contains("{" + name + "}"))
{
parameters.add(new Parameter().withName(name).withIn(In.PATH).withRequired(true).withSchema(PrintingApiSchemas.text(128)));
}
}
if("Commands".equals(operation))
{
parameters.add(new Parameter().withName("limit").withIn(In.QUERY).withSchema(new Schema().withType(Type.INTEGER)).withDescription("1 through 200; default 50."));
parameters.add(new Parameter().withName("before").withIn(In.QUERY).withSchema(PrintingApiSchemas.text(128)));
}
return (parameters);
}
/** Authenticate before processing, retain only the verified public device ID in the request input. */
@Override
public JsonInput buildInput(Context context) throws Exception
{
context.header("Cache-Control", "no-store");
PrintingControlAuthorization.principal();
if(context.bodyAsBytes().length > ("Inventory".equals(operation) ? 2097152 : 32768))
{
throw new PrintingException(413, "Printing request exceeds its size limit");
}
JsonInput input = super.buildInput(context);
if("Empty".equals(requestSchema) && !input.getBody().isEmpty())
{
throw new QBadRequestException("This operation requires an empty JSON object");
}
String id = context.header(PrintingAgentAuthorization.DEVICE_HEADER);
String token = context.header(PrintingAgentAuthorization.TOKEN_HEADER);
if(path.startsWith("/device/") || ("Session".equals(operation) && (id != null || token != null)))
{
input.getPathParams().put("_verifiedDevice", PrintingAgentAuthorization.device(id, token, "Bind".equals(operation)));
}
return (input);
}
/** Domain mutations follow native user/table/row/process checks, never generic table-write bypass flags. */
@Override
protected Object handle(JsonInput input) throws Exception
{
PrintingService service = PrintingProcesses.currentService();
String principal = PrintingControlAuthorization.principal();
String device = input.getPathParam("_verifiedDevice");
JSONObject body = new JSONObject(input.getBody());
String job = input.getPathParam("jobId");
Object result;
switch(operation)
{
case "Session" ->
{
result = new JSONObject().put("principalId", principal).put("tenantId", service.getTenantId()).put("deviceId", device);
}
case "Bind" -> result = accepted();
case "Enroll" ->
{
PrintingControlAuthorization.process("printingEnrollDevice");
PrintingControlAuthorization.table(PrintingTables.DEVICE);
String facility = service.enrollmentFacility(body.optString("enrollmentCode"));
try
{
PrintingFacilities.validate(facility);
}
catch(QException denied)
{
throw new QPermissionDeniedException("Enrollment facility is not accessible");
}
result = service.enrollForUser(body, principal);
}
case "Heartbeat" -> result = service.heartbeat(device, body);
case "Inventory" ->
{
service.inventory(device, body.getJSONArray("printers"), PrintingAgentAuthorization.inventory(device));
result = accepted();
}
case "Claim" -> result = PrintingAgentAuthorization.claim(device);
case "Queued" ->
{
PrintingControlAuthorization.table(PrintingTables.JOB);
JSONArray jobs = service.queuedJobs(device);
for(int index = 0; index < jobs.length(); index++)
{
PrintingControlAuthorization.job(device, jobs.getJSONObject(index).getString("jobId"));
}
result = new JSONObject().put("jobs", jobs);
}
case "Content" ->
{
PrintingControlAuthorization.job(device, job);
return (service.content(device, job));
}
case "Event" ->
{
PrintingControlAuthorization.job(device, job);
service.event(device, job, body);
result = accepted();
}
case "Test" ->
{
PrintingAgentAuthorization.printer(device, body.optString("printerId"));
PrintingControlAuthorization.process("PDF".equals(body.optString("format")) ? "printingTestPdf" : "printingTestZpl");
result = service.testPrint(device, body);
}
case "Retry" ->
{
PrintingControlAuthorization.job(device, job);
PrintingControlAuthorization.process(PrintingJobProcesses.RETRY);
result = service.retry(device, job, body);
}
case "Cancel" ->
{
PrintingControlAuthorization.job(device, job);
PrintingControlAuthorization.process(PrintingJobProcesses.CANCEL);
result = service.cancel(device, job);
}
case "Poll" ->
{
PrintingControlAuthorization.table(PrintingTables.COMMAND);
JSONObject poll = service.deviceControlPoll(device, body);
JSONArray commands = poll.getJSONArray("commands");
for(int index = 0; index < commands.length(); index++)
{
command(device, commands.getJSONObject(index).getString("commandId"));
}
result = poll;
}
case "Receipt" ->
{
command(device, input.getPathParam("commandId"));
result = service.deviceControlReceipt(device, input.getPathParam("commandId"), body);
}
case "Action" -> result = PrintingControlAuthorization.deviceAction(input.getPathParam("deviceId"), body);
case "Commands" ->
{
device = input.getPathParam("deviceId");
PrintingControlAuthorization.record(PrintingTables.DEVICE, device);
PrintingControlAuthorization.table(PrintingTables.COMMAND);
Integer limit = input.getQueryParamInteger("limit");
JSONObject page = service.deviceCommandsPage(device, limit == null ? 50 : limit, input.getQueryParam("before"));
JSONArray commands = page.getJSONArray("commands");
for(int index = 0; index < commands.length(); index++)
{
command(device, commands.getJSONObject(index).getString("commandId"));
}
result = page;
}
case "Command" ->
{
device = input.getPathParam("deviceId");
PrintingControlAuthorization.record(PrintingTables.DEVICE, device);
command(device, input.getPathParam("commandId"));
result = service.getDeviceCommand(device, input.getPathParam("commandId"));
}
default -> throw new PrintingException(400, "Unknown printing operation");
}
return (result instanceof JSONObject json ? json.toMap() : result);
}
/** Receipt and history access apply child-record security independently of device access. */
private static void command(String device, String id) throws Exception
{
QRecord command = PrintingControlAuthorization.record(PrintingTables.COMMAND, id);
if(!device.equals(command.getValueString("device_id")))
{
throw new QPermissionDeniedException("Command is not assigned to this device");
}
if(command.getValueString("job_id") != null)
{
PrintingControlAuthorization.job(device, command.getValueString("job_id"));
}
}
/** Mutation success does not assert a physical print outcome. */
private static JSONObject accepted()
{
return (new JSONObject().put("accepted", true));
}
/** Use the core error envelope and suppress backend/credential diagnostics. */
@Override
protected void handleException(Context context, Exception exception)
{
Throwable cause = exception;
while(cause.getCause() != null && !(cause instanceof PrintingException) && !(cause instanceof QAuthenticationException)
&& !(cause instanceof QPermissionDeniedException) && !(cause instanceof QBadRequestException))
{
cause = cause.getCause();
}
int status = cause instanceof PrintingException printing ? printing.getStatus()
: cause instanceof QAuthenticationException ? 401 : cause instanceof QPermissionDeniedException ? 403
: cause instanceof QBadRequestException || cause instanceof org.json.JSONException ? 400 : 500;
String message = status == 500 ? "The printing operation could not be completed"
: status == 401 ? "Sign in to continue" : status == 403 ? "User or device is not authorized" : cause.getMessage();
context.header("Cache-Control", "no-store").contentType("application/json");
QJavalinUtils.respondWithError(context, org.eclipse.jetty.http.HttpStatus.getCode(status), message);
}
/** Standard native authentication, authorization, conflict and capacity responses. */
@Override
public List<BasicResponse> defineAdditionalBasicResponses()
{
return (List.of(new BasicResponse(HttpStatus.BAD_REQUEST, "Invalid request", BasicErrorResponseV1.class.getSimpleName()),
new BasicResponse(HttpStatus.UNAUTHORIZED, "Native QQQ sign-in required", BasicErrorResponseV1.class.getSimpleName()),
new BasicResponse(HttpStatus.FORBIDDEN, "Permission, device proof or user binding denied", BasicErrorResponseV1.class.getSimpleName()),
new BasicResponse(HttpStatus.NOT_FOUND, "Record not found", BasicErrorResponseV1.class.getSimpleName()),
new BasicResponse(HttpStatus.CONFLICT, "State or request conflict", BasicErrorResponseV1.class.getSimpleName()),
new BasicResponse(HttpStatus.GONE, "Request or content expired", BasicErrorResponseV1.class.getSimpleName()),
new BasicResponse(HttpStatus.TOO_MANY_REQUESTS, "Bounded capacity reached", BasicErrorResponseV1.class.getSimpleName())));
}
}
@@ -0,0 +1,96 @@
/*
* QQQ - Low-code Application Framework for Engineers.
* Copyright (C) 2021-2025. Kingsrook, LLC
* 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
* contact@kingsrook.com
* https://github.com/Kingsrook/
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.kingsrook.qbits.printing;
/*******************************************************************************
** Explicit stock and resolution choices for built-in diagnostic documents.
*******************************************************************************/
public enum TestPrintProfile
{
LETTER("Letter - 8.5 x 11 in", 0),
A4("A4 - 210 x 297 mm", 0),
LABEL_4X6_203("4 x 6 in label - 203 dpi", 203),
LABEL_4X6_300("4 x 6 in label - 300 dpi", 300),
LABEL_4X6_600("4 x 6 in label - 600 dpi", 600);
private final String label;
private final int dpi;
/***************************************************************************
** Store a human label and printer density without guessing from a name.
***************************************************************************/
TestPrintProfile(String label, int dpi)
{
this.label = label;
this.dpi = dpi;
}
/***************************************************************************
** Validate before enqueueing. Omitted profiles retain legacy defaults.
***************************************************************************/
public static TestPrintProfile resolve(String format, String value) throws PrintingException
{
if(!"PDF".equals(format) && !"ZPL".equals(format))
{
throw new PrintingException(400, "Only PDF and ZPL are supported");
}
TestPrintProfile profile;
try
{
profile = value == null ? ("PDF".equals(format) ? LETTER : LABEL_4X6_203) : valueOf(value);
}
catch(IllegalArgumentException exception)
{
throw new PrintingException(400, "Unknown test profile");
}
if("ZPL".equals(format) && profile.dpi == 0)
{
throw new PrintingException(400, "ZPL test prints require a 4 x 6 label profile with the matching printer dpi");
}
return (profile);
}
/***************************************************************************
** Friendly choice label used by native QQQ forms.
***************************************************************************/
public String getLabel()
{
return (label);
}
/***************************************************************************
** Zero marks page profiles; label values are supported device resolutions.
***************************************************************************/
public int getDpi()
{
return (dpi);
}
}
@@ -0,0 +1,93 @@
Copyright 2020 The JetBrains Mono Project Authors (https://github.com/JetBrains/JetBrainsMono)
This Font Software is licensed under the SIL Open Font License, Version 1.1.
This license is copied below, and is also available with a FAQ at:
https://scripts.sil.org/OFL
-----------------------------------------------------------
SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
-----------------------------------------------------------
PREAMBLE
The goals of the Open Font License (OFL) are to stimulate worldwide
development of collaborative font projects, to support the font creation
efforts of academic and linguistic communities, and to provide a free and
open framework in which fonts may be shared and improved in partnership
with others.
The OFL allows the licensed fonts to be used, studied, modified and
redistributed freely as long as they are not sold by themselves. The
fonts, including any derivative works, can be bundled, embedded,
redistributed and/or sold with any software provided that any reserved
names are not used by derivative works. The fonts and derivatives,
however, cannot be released under any other type of license. The
requirement for fonts to remain under this license does not apply
to any document created using the fonts or their derivatives.
DEFINITIONS
"Font Software" refers to the set of files released by the Copyright
Holder(s) under this license and clearly marked as such. This may
include source files, build scripts and documentation.
"Reserved Font Name" refers to any names specified as such after the
copyright statement(s).
"Original Version" refers to the collection of Font Software components as
distributed by the Copyright Holder(s).
"Modified Version" refers to any derivative made by adding to, deleting,
or substituting -- in part or in whole -- any of the components of the
Original Version, by changing formats or by porting the Font Software to a
new environment.
"Author" refers to any designer, engineer, programmer, technical
writer or other person who contributed to the Font Software.
PERMISSION & CONDITIONS
Permission is hereby granted, free of charge, to any person obtaining
a copy of the Font Software, to use, study, copy, merge, embed, modify,
redistribute, and sell modified and unmodified copies of the Font
Software, subject to the following conditions:
1) Neither the Font Software nor any of its individual components,
in Original or Modified Versions, may be sold by itself.
2) Original or Modified Versions of the Font Software may be bundled,
redistributed and/or sold with any software, provided that each copy
contains the above copyright notice and this license. These can be
included either as stand-alone text files, human-readable headers or
in the appropriate machine-readable metadata fields within text or
binary files as long as those fields can be easily viewed by the user.
3) No Modified Version of the Font Software may use the Reserved Font
Name(s) unless explicit written permission is granted by the corresponding
Copyright Holder. This restriction only applies to the primary font name as
presented to the users.
4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
Software shall not be used to promote, endorse or advertise any
Modified Version, except to acknowledge the contribution(s) of the
Copyright Holder(s) and the Author(s) or with their explicit written
permission.
5) The Font Software, modified or unmodified, in part or in whole,
must be distributed entirely under this license, and must not be
distributed under any other license. The requirement for fonts to
remain under this license does not apply to any document created
using the Font Software.
TERMINATION
This license becomes null and void if any of the above conditions are
not met.
DISCLAIMER
THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
OTHER DEALINGS IN THE FONT SOFTWARE.
@@ -0,0 +1,25 @@
# Test-document font
`JetBrainsMono-Bold.ttf` is the unmodified static **JetBrains Mono Bold v2.304** font from JetBrains. It is bundled for the built-in PDF and rasterized ZPL test documents, so those paths use the same letterforms without relying on installed computer or printer fonts.
Copyright 2020 The JetBrains Mono Project Authors. The font is licensed under the **SIL Open Font License 1.1**, reproduced in [OFL.txt](OFL.txt); it is not covered by this repository's Apache license. Preserve that license and attribution when redistributing the font.
## Provenance
- [Official font design and character comparisons](https://www.jetbrains.com/lp/mono/)
- [Official tagged font source](https://github.com/JetBrains/JetBrainsMono/blob/v2.304/fonts/ttf/JetBrainsMono-Bold.ttf)
- [Official tagged license](https://github.com/JetBrains/JetBrainsMono/blob/v2.304/OFL.txt)
- Acquired and inspected: 2026-10-30. No modifications or font conversions.
- Font size: 277,828 bytes.
- Font SHA-256: `5590990c82e097397517f275f430af4546e1c45cff408bde4255dad142479dcb`
- License SHA-256: `30f0c136e3c88e422d0791acd97238870f9054a9729bc34cf2ff0d4ed8cac4ad`
## Rendering and readability
Visual inspection of the actual bundled font confirmed a dotted zero versus plain capital O, an angled top and baseline on digit 1, horizontal bars on capital I, and a curved foot on lowercase l. The 5/S, 2/Z, 8/B and 6/G pairs also have visibly different outlines. Inspection included nominal 12-point text rasterized at 203 and 300 dpi; physical printer acceptance remains a separate check. This does not guarantee error-free reading at every size or on damaged labels.
Use ordinary character drawing without programming ligatures for identifiers. Favor at least 12-point text for important warehouse identifiers, generous whitespace, and a larger explicit ambiguous-character proof row. Keep barcode generation separate from font rendering.
The file contains TrueType `glyf` outlines, has no variable-font `fvar` table, and its OS/2 `fsType` is zero. It therefore has the static TrueType structure expected by the project's PDFBox 2.x embedding path. Load the resource with `PDType0Font.load(document, inputStream, true)` to embed a subset. See the [official PDFBox 2.x API](https://pdfbox.apache.org/docs/2.0.13/javadocs/org/apache/pdfbox/pdmodel/font/PDType0Font.html). The resource inspection itself is not a substitute for the generator's PDFBox regression test.
For ZPL, load the same resource through `Font.createFont(Font.TRUETYPE_FONT, inputStream)`, derive the required pixel size from the selected printer dpi, render onto an opaque white background, and encode the monochrome result as document-local graphics. This preserves the distinctive glyphs without installing a font on the printer. Raster previews and physical output still need inspection at each supported resolution.
@@ -0,0 +1,29 @@
# Query mascot used in built-in print diagnostics
`query-mascot.png` is the official Query dog artwork, copied byte for byte from
QRun.IO's marketing source. It replaces the former interlocking-Q crown mark in
built-in test documents. Query is identified by the official
[mascot page](https://qrun.io/query), linked from
[dogfooding guidance](https://qrun.io/dogfooding).
- Source repository: [QRun-IO/marketing-website](https://github.com/QRun-IO/marketing-website).
- Asset source revision: `5ff7c1564f4fe28a7ce75436cf7c4a6eeaa4bf3f`.
- Source file: [`assets/Puppy Mark/exports/PNG/qqq-puppy@4x.png`](https://github.com/QRun-IO/marketing-website/blob/5ff7c1564f4fe28a7ce75436cf7c4a6eeaa4bf3f/assets/Puppy%20Mark/exports/PNG/qqq-puppy%404x.png).
- Dimensions: 1326 x 1394 pixels, transparent PNG.
- SHA256: `385a053e15e0a9fc6f8a965257e3917db827594ab46ecf8cdddb847770a25dbb`.
- Verified2026-10-31 against the official page: the two SVG paths in its Query
illustration match `public/images/qqq-puppy.svg` in the same repository.
The bundled PNG is unmodified. At document generation, transparent pixels are
composited onto white and the image is centered in a square white canvas. This
preserves the original aspect ratio inside existing PDF and thermal-label layout
boxes. The resulting document artwork is monochrome for warehouse printing;
there is no AI redraw, added outline, rotation or printer-persistent download.
Existing diagnostic text, font, media profiles, barcode data and quiet zones are
unchanged. The one shared generator supplies all native QQQ and device test-print
entrypoints, including Windows companion requests.
This resource brands QQQ's built-in diagnostic documents only. It does not
replace a customer's submitted document artwork, Windows application/tray icons
or future customer-specific branding configuration. Query remains QRun.IO/QQQ
branding; this provenance is not a separate trademark permission grant.
Binary file not shown.

After

Width:  |  Height:  |  Size: 46 KiB

File diff suppressed because it is too large. Load diff
@@ -0,0 +1,601 @@
/*
* QQQ - Low-code Application Framework for Engineers.
* Copyright (C) 2021-2025. Kingsrook, LLC
* 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
* contact@kingsrook.com
* https://github.com/Kingsrook/
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.kingsrook.qbits.printing;
import java.sql.SQLException;
import java.time.Instant;
import java.util.Base64;
import java.util.HashSet;
import java.util.List;
import java.util.Map;
import java.util.Set;
import java.util.UUID;
import java.util.concurrent.Callable;
import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.CountDownLatch;
import java.util.concurrent.Executors;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.atomic.AtomicInteger;
import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
import org.json.JSONArray;
import org.json.JSONObject;
import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.junit.jupiter.api.Assertions.assertTrue;
/*******************************************************************************
** Security regressions use isolated SQL and synthetic object storage only.
*******************************************************************************/
class PrintingAdmissionTest
{
private static final byte[] DOCUMENT = new byte[1024];
/***************************************************************************
** Tiny retry requests cannot accumulate unlimited retained terminal copies.
***************************************************************************/
@Test
void retainedRetryBudgetRejectsBeforeUploadAndPreservesReplayAfterCleanup() throws Exception
{
Fixture fixture = fixture(limits(10, 20, 100_000, 200_000, 2048, 4096, 100, 200, 10, 20));
String original = fixture.service.submit(request(fixture.first, "original")).getString("jobId");
spool(fixture.service, fixture.first, original);
JSONObject retryRequest = retry("same-retry");
String copy = fixture.service.retry(fixture.first, original, retryRequest).getString("jobId");
spool(fixture.service, fixture.first, copy);
int readsBeforeRejection = fixture.documents.gets.get();
assertQuota(() -> fixture.service.retry(fixture.first, original, retry("fresh-retry")));
assertEquals(readsBeforeRejection, fixture.documents.gets.get());
assertEquals(copy, fixture.service.retry(fixture.first, original, retryRequest).getString("jobId"));
assertEquals(2, fixture.documents.puts.get());
assertEquals(2, count(fixture.source, "printing_job"));
execute(fixture.source, "UPDATE printing_job SET completed_at=? WHERE id=?", Instant.now().minusSeconds(400L * 86400).toString(), original);
assertEquals(1, fixture.service.runRetention());
assertEquals(copy, fixture.service.retry(fixture.first, original, retryRequest).getString("jobId"));
assertEquals(410, assertThrows(PrintingException.class, () -> fixture.service.retry(fixture.first, original, retry("expired-source"))).getStatus());
fixture.service.submit(request(fixture.first, "after-cleanup"));
assertEquals(3, fixture.documents.puts.get());
assertEquals(2, fixture.documents.objects.size());
}
/***************************************************************************
** Tenant count and byte budgets serialize across service instances/devices.
***************************************************************************/
@Test
void concurrentDevicesCannotExceedTenantCountOrByteBudgets() throws Exception
{
List<PrintingAdmissionLimits> budgets = List.of(
limits(10, 1, 100_000, 200_000, 100_000, 200_000, 100, 200, 10, 20),
limits(10, 20, 100_000, DOCUMENT.length, 100_000, 200_000, 100, 200, 10, 20),
limits(10, 20, 100_000, 200_000, 100_000, DOCUMENT.length, 100, 200, 10, 20));
for(int attempt = 0; attempt < 10; attempt++)
{
for(PrintingAdmissionLimits budget : budgets)
{
Fixture fixture = fixture(budget);
PrintingService other = sibling(fixture, budget);
concurrentOneAccepted(() -> fixture.service.submit(request(fixture.first, "first")), () -> other.submit(request(fixture.second, "second")));
assertEquals(1, fixture.documents.puts.get());
assertEquals(1, count(fixture.source, "printing_job"));
assertEquals(0, count(fixture.source, "printing_document_orphan"));
}
}
}
/***************************************************************************
** Device budgets remain effective even when tenant capacity is available.
***************************************************************************/
@Test
void outstandingDeviceCountAndBytesReleaseOnlyWhenWorkFinishes() throws Exception
{
for(PrintingAdmissionLimits budget : List.of(
limits(1, 20, 100_000, 200_000, 100_000, 200_000, 100, 200, 10, 20),
limits(10, 20, DOCUMENT.length, 200_000, 100_000, 200_000, 100, 200, 10, 20)))
{
Fixture fixture = fixture(budget);
String original = fixture.service.submit(request(fixture.first, "original")).getString("jobId");
assertQuota(() -> fixture.service.submit(request(fixture.first, "overflow")));
assertEquals(original, fixture.service.submit(request(fixture.first, "original")).getString("jobId"));
fixture.service.submit(request(fixture.second, "other-device"));
assertEquals(2, fixture.documents.puts.get());
spool(fixture.service, fixture.first, original);
fixture.service.submit(request(fixture.first, "finished-slot"));
assertEquals(3, fixture.documents.puts.get());
}
}
/***************************************************************************
** Failed upload compensation keeps its full reservation until exact cleanup.
***************************************************************************/
@Test
void failedUploadIntentConsumesCapacityUntilCleanupSucceeds() throws Exception
{
Fixture fixture = fixture(limits(10, 20, 100_000, 200_000, DOCUMENT.length, DOCUMENT.length, 100, 200, 10, 20));
fixture.documents.failUpload = true;
fixture.documents.failDelete = true;
assertThrows(SQLException.class, () -> fixture.service.submit(request(fixture.first, "failed-upload")));
assertEquals(1, count(fixture.source, "printing_document_orphan"));
assertEquals(0, count(fixture.source, "printing_job"));
assertQuota(() -> fixture.service.submit(request(fixture.second, "blocked-by-reservation")));
assertEquals(1, fixture.documents.puts.get());
fixture.documents.failUpload = false;
fixture.documents.failDelete = false;
execute(fixture.source, "UPDATE printing_document_orphan SET created_at=?", Instant.now().minusSeconds(7200).toString());
assertEquals(1, fixture.service.runRetention());
fixture.service.submit(request(fixture.second, "after-recovery"));
assertEquals(2, fixture.documents.puts.get());
assertEquals(1, fixture.documents.objects.size());
assertEquals(0, count(fixture.source, "printing_document_orphan"));
}
/***************************************************************************
** Legacy upload intents with unknown size reserve the maximum allowed bytes.
***************************************************************************/
@Test
void legacyUnknownUploadChargesTenantCapacityUntilExactCleanup() throws Exception
{
long unknownBytes = 20L * 1024 * 1024;
Fixture fixture = fixture(limits(10, 20, 100_000_000, 200_000_000, 100_000_000, unknownBytes, 100, 200, 10, 20));
String orphan = UUID.randomUUID().toString();
String reference = fixture.documents.prefix() + orphan + ".zpl";
fixture.documents.objects.put(reference, DOCUMENT.clone());
execute(fixture.source, "INSERT INTO printing_document_orphan (id,tenant_id,storage_table,reference,binding,created_at) VALUES (?,?,?,?,?,?)",
orphan, "tenant-a", "printing_documents", reference, "quota-fixture", Instant.now().minusSeconds(7200).toString());
// Only isolated test accounting tables are removed to exercise upgrade backfill.
execute(fixture.source, "DROP TABLE printing_resource_usage");
execute(fixture.source, "DROP TABLE printing_admission_event");
fixture.service.initialize();
assertEquals(Long.toString(unknownBytes), scalar(fixture.source, "SELECT retained_bytes FROM printing_resource_usage WHERE tenant_id=? AND device_id=''", "tenant-a"));
assertEquals("0", scalar(fixture.source, "SELECT retained_bytes FROM printing_resource_usage WHERE tenant_id=? AND device_id=?", "tenant-a", fixture.first));
assertQuota(() -> fixture.service.submit(request(fixture.first, "blocked-by-legacy-upload")));
assertEquals(0, fixture.documents.puts.get());
assertEquals(0, fixture.documents.gets.get());
assertEquals(1, fixture.documents.objects.size());
assertTrue(fixture.documents.objects.containsKey(reference));
assertEquals(1, count(fixture.source, "printing_document_orphan"));
assertEquals(0, count(fixture.source, "printing_job"));
assertEquals(1, fixture.service.runRetention());
assertFalse(fixture.documents.objects.containsKey(reference));
assertEquals("0", scalar(fixture.source, "SELECT retained_bytes FROM printing_resource_usage WHERE tenant_id=? AND device_id=''", "tenant-a"));
fixture.service.submit(request(fixture.second, "after-legacy-cleanup"));
assertEquals(1, fixture.documents.puts.get());
assertEquals(1, fixture.documents.objects.size());
assertEquals(0, count(fixture.source, "printing_document_orphan"));
}
/***************************************************************************
** Finished jobs do not permit unlimited small-request amplification per hour.
***************************************************************************/
@Test
void hourlyCreationBudgetIncludesFinishedRetriesAndDirectSubmission() throws Exception
{
Fixture fixture = fixture(limits(10, 20, 100_000, 200_000, 100_000, 200_000, 2, 100, 10, 20));
String original = fixture.service.submit(request(fixture.first, "original")).getString("jobId");
spool(fixture.service, fixture.first, original);
JSONObject same = retry("first-copy");
String copy = fixture.service.retry(fixture.first, original, same).getString("jobId");
spool(fixture.service, fixture.first, copy);
int readsBeforeRejection = fixture.documents.gets.get();
assertQuota(() -> fixture.service.retry(fixture.first, original, retry("second-copy")));
assertEquals(readsBeforeRejection, fixture.documents.gets.get());
assertQuota(() -> fixture.service.submit(request(fixture.first, "direct-bypass")));
assertEquals(copy, fixture.service.retry(fixture.first, original, same).getString("jobId"));
assertEquals(2, fixture.documents.puts.get());
fixture.service.submit(request(fixture.second, "independent-device"));
assertEquals(3, fixture.documents.puts.get());
}
/***************************************************************************
** Rotated IDs cannot erase history or bypass cumulative device capacity.
***************************************************************************/
@Test
void inventoryRotationRejectsAtomicallyAndPreservesApprovalAndJobReference() throws Exception
{
Fixture fixture = fixture(limits(10, 20, 100_000, 200_000, 100_000, 200_000, 100, 200, 3, 20));
fixture.service.inventory(fixture.first, new JSONArray().put(printer("queue").put("displayName", "Approved queue").put("description", "Historical description")));
String job = fixture.service.submit(request(fixture.first, "history")).getString("jobId");
String rowId = scalar(fixture.source, "SELECT printer_row_id FROM printing_job WHERE id=?", job);
fixture.service.inventory(fixture.first, new JSONArray().put(printer("new-a")).put(printer("new-b")));
assertQuota(() ->
{
fixture.service.inventory(fixture.first, new JSONArray().put(printer("overflow")));
return null;
});
assertEquals("1", scalar(fixture.source, "SELECT available FROM printing_printer WHERE device_id=? AND printer_id=?", fixture.first, "new-a"));
assertEquals("1", scalar(fixture.source, "SELECT enabled FROM printing_printer WHERE id=?", rowId));
assertEquals("Historical description", scalar(fixture.source, "SELECT description FROM printing_printer WHERE id=?", rowId));
assertEquals(rowId, scalar(fixture.source, "SELECT printer_row_id FROM printing_job WHERE id=?", job));
fixture.service.inventory(fixture.first, new JSONArray().put(printer("queue").put("displayName", "Updated approved queue")));
assertEquals("Updated approved queue", scalar(fixture.source, "SELECT name FROM printing_printer WHERE id=?", rowId));
assertEquals("1", scalar(fixture.source, "SELECT enabled FROM printing_printer WHERE id=?", rowId));
assertEquals(4, count(fixture.source, "printing_printer"));
}
/***************************************************************************
** Two devices cannot simultaneously claim the last tenant inventory slot.
***************************************************************************/
@Test
void concurrentInventoriesEnforceTenantCapacityAcrossServiceInstances() throws Exception
{
PrintingAdmissionLimits budget = limits(10, 20, 100_000, 200_000, 100_000, 200_000, 100, 200, 10, 3);
Fixture fixture = fixture(budget);
PrintingService other = sibling(fixture, budget);
concurrentOneAccepted(() ->
{
fixture.service.inventory(fixture.first, new JSONArray().put(printer("new-first")));
return null;
}, () ->
{
other.inventory(fixture.second, new JSONArray().put(printer("new-second")));
return null;
});
assertEquals(3, count(fixture.source, "printing_printer"));
assertEquals("2", scalar(fixture.source, "SELECT COUNT(*) FROM printing_printer WHERE enabled=1"));
}
/***************************************************************************
** Legacy over-budget history remains accessible through bounded pages.
***************************************************************************/
@Test
void existingOversizedInventoryIsPagedWithoutDeletingHistoricalRows() throws Exception
{
Fixture fixture = fixture(limits(10, 20, 100_000, 200_000, 100_000, 200_000, 100, 200, 1000, 2000));
for(int batch = 0; batch < 2; batch++)
{
JSONArray printers = new JSONArray();
for(int index = 0; index < 150; index++)
{
printers.put(printer("historic-" + (batch * 150 + index)).put("name", "倉庫".repeat(510) + String.format(java.util.Locale.ROOT, "%04d", batch * 150 + index)));
}
fixture.service.inventory(fixture.first, printers);
}
fixture.service.withAdmissionLimits(limits(10, 20, 100_000, 200_000, 100_000, 200_000, 100, 200, 3, 5));
assertEquals(200, fixture.service.printers(fixture.first).length());
Set<String> ids = new HashSet<>();
String cursor = null;
int pages = 0;
do
{
JSONObject page = fixture.service.printersPage(fixture.first, 73, cursor);
JSONArray rows = page.getJSONArray("printers");
assertTrue(rows.length() <= 73);
for(int index = 0; index < rows.length(); index++)
{
assertTrue(ids.add(rows.getJSONObject(index).getString("printerId")));
}
cursor = page.optString("nextCursor", "");
assertTrue(++pages <= 10);
}
while(!cursor.isBlank());
assertEquals(301, ids.size());
assertEquals("0", scalar(fixture.source, "SELECT COUNT(*) FROM INFORMATION_SCHEMA.INDEX_COLUMNS WHERE UPPER(TABLE_NAME)='PRINTING_PRINTER' AND UPPER(COLUMN_NAME)='NAME'"));
fixture.service.inventory(fixture.first, new JSONArray().put(printer("queue")));
assertEquals(302, count(fixture.source, "printing_printer"));
assertQuota(() ->
{
fixture.service.inventory(fixture.first, new JSONArray().put(printer("extra")));
return null;
});
}
/***************************************************************************
** Exercise two independent service objects against one tenant database.
***************************************************************************/
private static PrintingService sibling(Fixture fixture, PrintingAdmissionLimits limits)
{
PrintingService service = new PrintingService(fixture.source, "tenant-a").withAdmissionLimits(limits);
service.configureStorage(fixture.documents, "printing_documents");
return (service);
}
/***************************************************************************
** Synthetic storage and isolated SQL never reach an installed print agent.
***************************************************************************/
private static Fixture fixture(PrintingAdmissionLimits limits) throws Exception
{
DriverDataSource source = new DriverDataSource("jdbc:h2:mem:admission-" + UUID.randomUUID() + ";DB_CLOSE_DELAY=-1;LOCK_TIMEOUT=5000", "sa", "");
PrintingService service = new PrintingService(source, "tenant-a").withAdmissionLimits(limits);
service.initialize();
CountingDocuments documents = new CountingDocuments();
service.configureStorage(documents, "printing_documents");
return (new Fixture(source, service, documents, enroll(service, "first"), enroll(service, "second")));
}
/***************************************************************************
** Every printer approval remains explicit in the fixture.
***************************************************************************/
private static String enroll(PrintingService service, String name) throws Exception
{
String device = service.enroll(service.createEnrollment("warehouse", name).put("deviceName", name).put("agentVersion", "test")).getString("deviceId");
service.inventory(device, new JSONArray().put(printer("queue")));
service.enablePrinter(device, "queue", true);
return (device);
}
/***************************************************************************
** A current queue identity, distinct from its display metadata.
***************************************************************************/
private static JSONObject printer(String id)
{
return (new JSONObject().put("printerId", id).put("name", "Synthetic " + id).put("status", "READY").put("formats", new JSONArray(List.of("ZPL"))));
}
/***************************************************************************
** Exact synthetic bytes make byte budgets independent of transport encoding.
***************************************************************************/
private static JSONObject request(String device, String key)
{
return (new JSONObject().put("deviceId", device).put("printerId", "queue").put("title", "Admission regression").put("format", "ZPL")
.put("contentBase64", Base64.getEncoder().encodeToString(DOCUMENT)).put("idempotencyKey", key));
}
/***************************************************************************
** Reprints retain explicit operator duplicate-risk consent.
***************************************************************************/
private static JSONObject retry(String key)
{
return (new JSONObject().put("requestId", key).put("confirmDuplicateRisk", true));
}
/***************************************************************************
** Use real event transitions so accounting sees the same production path.
***************************************************************************/
private static void spool(PrintingService service, String device, String job) throws Exception
{
assertEquals(job, service.claim(device).getJSONObject("job").getString("jobId"));
service.event(device, job, new JSONObject().put("eventId", UUID.randomUUID().toString()).put("status", "SPOOLED").put("spoolerJobId", "synthetic"));
}
/***************************************************************************
** Over-budget requests must fail as operator-visible backpressure.
***************************************************************************/
private static void assertQuota(Callable<?> operation)
{
PrintingException exception = assertThrows(PrintingException.class, operation::call);
assertEquals(429, exception.getStatus());
assertFalse(exception.getMessage().isBlank());
}
/***************************************************************************
** Start both calls together; only one may consume the final shared slot.
***************************************************************************/
private static void concurrentOneAccepted(Callable<?> first, Callable<?> second) throws Exception
{
CountDownLatch start = new CountDownLatch(1);
try(var pool = Executors.newFixedThreadPool(2))
{
var a = pool.submit(() -> outcome(start, first));
var b = pool.submit(() -> outcome(start, second));
start.countDown();
assertEquals(List.of("accepted", "quota"), List.of(a.get(10, TimeUnit.SECONDS), b.get(10, TimeUnit.SECONDS)).stream().sorted().toList());
}
}
/***************************************************************************
** Unexpected exceptions remain test failures rather than rejected admissions.
***************************************************************************/
private static String outcome(CountDownLatch start, Callable<?> operation) throws Exception
{
start.await();
try
{
operation.call();
return ("accepted");
}
catch(PrintingException exception)
{
assertEquals(429, exception.getStatus());
return ("quota");
}
}
/***************************************************************************
** Explicit arguments keep each boundary under test visible at its call site.
***************************************************************************/
private static PrintingAdmissionLimits limits(int deviceJobs, int tenantJobs, long deviceBytes, long tenantBytes, long deviceRetained,
long tenantRetained, int deviceRate, int tenantRate, int devicePrinters, int tenantPrinters)
{
return (new PrintingAdmissionLimits(deviceJobs, tenantJobs, deviceBytes, tenantBytes, deviceRetained, tenantRetained, deviceRate, tenantRate, devicePrinters, tenantPrinters));
}
/***************************************************************************
** Count only fixed test-owned tables.
***************************************************************************/
private static int count(DriverDataSource source, String table) throws Exception
{
return (Integer.parseInt(scalar(source, "SELECT COUNT(*) FROM " + table)));
}
/***************************************************************************
** Parameterized inspection avoids document reads when checking receipts.
***************************************************************************/
private static String scalar(DriverDataSource source, String sql, Object... values) throws Exception
{
try(var connection = source.getConnection(); var statement = connection.prepareStatement(sql))
{
for(int index = 0; index < values.length; index++)
{
statement.setObject(index + 1, values[index]);
}
try(var rows = statement.executeQuery())
{
assertTrue(rows.next());
return (rows.getString(1));
}
}
}
/***************************************************************************
** Age only isolated fixture rows to exercise retention recovery.
***************************************************************************/
private static void execute(DriverDataSource source, String sql, Object... values) throws Exception
{
try(var connection = source.getConnection(); var statement = connection.prepareStatement(sql))
{
for(int index = 0; index < values.length; index++)
{
statement.setObject(index + 1, values[index]);
}
statement.executeUpdate();
}
}
/***************************************************************************
** Isolated state shared only by one test and its two service instances.
***************************************************************************/
private record Fixture(DriverDataSource source, PrintingService service, CountingDocuments documents, String first, String second)
{
}
/***************************************************************************
** Count object writes and inject ambiguous storage failures without network.
***************************************************************************/
private static class CountingDocuments extends PrintingDocumentStorage
{
private final Map<String, byte[]> objects = new ConcurrentHashMap<>();
private final AtomicInteger puts = new AtomicInteger();
private final AtomicInteger gets = new AtomicInteger();
private boolean failUpload;
private boolean failDelete;
/***********************************************************************
** Reference ownership uses the same tenant prefix as production.
***********************************************************************/
CountingDocuments()
{
super(new QInstance(), "tenant-a", true);
}
/***********************************************************************
** Metadata validation belongs to the separate native storage tests.
***********************************************************************/
@Override
public String binding(String table)
{
return ("quota-fixture");
}
/***********************************************************************
** A failing upload can still have created the entire remote object.
***********************************************************************/
@Override
public void put(String table, String reference, String format, byte[] content) throws SQLException
{
puts.incrementAndGet();
objects.put(reference, content.clone());
if(failUpload)
{
throw new SQLException("Synthetic upload acknowledgement failure");
}
}
/***********************************************************************
** Read immutable synthetic bytes for the retry path.
***********************************************************************/
@Override
public byte[] get(String table, String reference) throws SQLException
{
gets.incrementAndGet();
byte[] content = objects.get(reference);
if(content == null)
{
throw new SQLException("Synthetic object was removed");
}
return (content.clone());
}
/***********************************************************************
** Failed cleanup must keep its reservation; successful deletion is exact.
***********************************************************************/
@Override
public void delete(String table, String reference) throws SQLException
{
if(failDelete)
{
throw new SQLException("Synthetic delete failure");
}
objects.remove(reference);
}
}
}
@@ -0,0 +1,218 @@
/*
* QQQ - Low-code Application Framework for Engineers.
* Copyright (C) 2021-2025. Kingsrook, LLC
* 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
* contact@kingsrook.com
* https://github.com/Kingsrook/
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.kingsrook.qbits.printing;
import java.sql.Connection;
import java.sql.PreparedStatement;
import java.time.Instant;
import java.util.List;
import java.util.Set;
import java.util.UUID;
import com.kingsrook.qqq.backend.core.actions.permissions.PermissionEnforcement;
import com.kingsrook.qqq.backend.core.actions.tables.GetAction;
import com.kingsrook.qqq.backend.core.actions.tables.QueryAction;
import com.kingsrook.qqq.backend.core.context.QContext;
import com.kingsrook.qqq.backend.core.exceptions.QException;
import com.kingsrook.qqq.backend.core.model.actions.tables.get.GetInput;
import com.kingsrook.qqq.backend.core.model.actions.tables.query.QCriteriaOperator;
import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryInput;
import com.kingsrook.qqq.backend.core.model.data.QRecord;
import com.kingsrook.qqq.backend.module.rdbms.model.metadata.RDBMSBackendMetaData;
import org.json.JSONObject;
import org.junit.jupiter.api.AfterEach;
import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertNull;
import static org.junit.jupiter.api.Assertions.assertThrows;
/*******************************************************************************
** Native reads derive expiry without an agent poll, mutation or tenant bypass.
*******************************************************************************/
class PrintingCommandStatusTest
{
/***************************************************************************
** Keep each synthetic fixture's authority local to that test.
***************************************************************************/
@AfterEach
void clearContext()
{
QContext.clear();
}
/***************************************************************************
** An offline stale row displays expired even though stored state stays pending.
***************************************************************************/
@Test
void fullGetAndProjectedQueryDeriveExpiryWithoutChangingRecordedState() throws Exception
{
var fixture = PrintingProcessesTest.fixture();
DriverDataSource source = source(fixture);
String id = seed(source, "tenant-a", fixture.device(), Instant.now().minusSeconds(60).toString());
QRecord record = get(id);
assertEquals("EXPIRED", record.getValueString("command_status"));
assertEquals("PENDING", record.getValueString("status"));
QueryInput query = new QueryInput().withTableName(PrintingTables.COMMAND)
.withFieldNamesToInclude(Set.of("id", "action", "command_status"))
.withFilter(new QQueryFilter().withCriteria("id", QCriteriaOperator.EQUALS, id));
query.setPermissionEnforcement(PermissionEnforcement.ENFORCE);
QRecord projected = new QueryAction().execute(query).getRecords().getFirst();
assertEquals("EXPIRED", projected.getValueString("command_status"));
assertFalse(projected.getValues().containsKey("status"));
assertFalse(projected.getValues().containsKey("expires_at"));
try(Connection connection = source.getConnection(); PreparedStatement statement = connection.prepareStatement("SELECT status FROM printing_device_command WHERE id=?"))
{
statement.setString(1, id);
try(var result = statement.executeQuery())
{
result.next();
assertEquals("PENDING", result.getString(1));
}
}
}
/***************************************************************************
** Hydration uses the same current native permissions and tenant row security.
***************************************************************************/
@Test
void selectedProjectionCannotExposeAnotherTenantsCommands() throws Exception
{
var fixture = PrintingProcessesTest.fixture();
DriverDataSource source = source(fixture);
String own = seed(source, "tenant-a", fixture.device(), Instant.now().minusSeconds(60).toString());
String foreign = seed(source, "tenant-b", fixture.foreignDevice(), Instant.now().minusSeconds(60).toString());
QueryInput query = new QueryInput().withTableName(PrintingTables.COMMAND)
.withFieldNamesToInclude(Set.of("id", "command_status"))
.withFilter(new QQueryFilter().withCriteria("id", QCriteriaOperator.IN, List.of(own, foreign)));
query.setPermissionEnforcement(PermissionEnforcement.ENFORCE);
List<QRecord> rows = new QueryAction().execute(query).getRecords();
assertEquals(List.of(own), rows.stream().map(row -> row.getValueString("id")).toList());
assertEquals("EXPIRED", rows.getFirst().getValueString("command_status"));
assertNull(get(foreign));
QContext.getQSession().setPermissions(Set.of());
assertThrows(QException.class, () -> new QueryAction().execute(query));
}
/***************************************************************************
** Arbitrary projections need a primary key to hydrate an authoritative value.
***************************************************************************/
@Test
void derivedStatusProjectionRequiresId() throws Exception
{
var fixture = PrintingProcessesTest.fixture();
seed(source(fixture), "tenant-a", fixture.device(), Instant.now().minusSeconds(60).toString());
QueryInput query = new QueryInput().withTableName(PrintingTables.COMMAND).withFieldNamesToInclude(Set.of("action", "command_status"));
query.setPermissionEnforcement(PermissionEnforcement.ENFORCE);
assertThrows(QException.class, () -> new QueryAction().execute(query));
}
/***************************************************************************
** Expiry cannot erase a receipt; missing or malformed pending expiry is unknown.
***************************************************************************/
@Test
void effectiveStatusKeepsTerminalReceiptsAndRejectsMalformedPendingExpiry()
{
Instant now = Instant.parse("2026-10-31T12:00:00Z");
QRecord row = new QRecord().withValue("status", "PENDING").withValue("expires_at", now.toString());
assertEquals("PENDING", PrintingCommandStatus.effective(row, now));
row.setValue("expires_at", now.minusSeconds(1).toString());
assertEquals("EXPIRED", PrintingCommandStatus.effective(row, now));
row.setValue("expires_at", "not-a-timestamp");
assertEquals("UNKNOWN", PrintingCommandStatus.effective(row, now));
row.setValue("expires_at", null);
assertEquals("UNKNOWN", PrintingCommandStatus.effective(row, now));
for(String status : List.of("SUCCEEDED", "FAILED", "EXPIRED", "OUTCOME_UNKNOWN"))
{
row.setValue("status", status);
assertEquals(status, PrintingCommandStatus.effective(row, now));
}
row.setValue("status", "unrecognized");
assertEquals("UNKNOWN", PrintingCommandStatus.effective(row, now));
}
/***************************************************************************
** Reuse the existing isolated native fixture without exposing new production APIs.
***************************************************************************/
private static DriverDataSource source(PrintingProcessesTest.Fixture fixture)
{
RDBMSBackendMetaData backend = (RDBMSBackendMetaData) fixture.instance().getBackend(fixture.instance().getTable(PrintingTables.COMMAND).getBackendName());
return (new DriverDataSource(backend.getJdbcUrl(), "sa", ""));
}
/***************************************************************************
** Direct fixture inserts represent a device that never polls after acceptance.
***************************************************************************/
private static String seed(DriverDataSource source, String tenant, String device, String expiresAt) throws Exception
{
String id = UUID.randomUUID().toString();
String issued = Instant.now().minusSeconds(960).toString();
JSONObject request = new JSONObject().put("requestId", id).put("issuedAt", issued).put("action", "REFRESH_INVENTORY");
try(Connection connection = source.getConnection();
PreparedStatement insert = connection.prepareStatement("INSERT INTO printing_device_command (id,tenant_id,device_id,request_id,action,actor,request_json,status,created_at,expires_at) VALUES (?,?,?,?,?,?,?,'PENDING',?,?)");
PreparedStatement offline = connection.prepareStatement("UPDATE printing_device SET last_seen_at=?,control_last_poll_at=NULL WHERE id=?"))
{
insert.setString(1, id);
insert.setString(2, tenant);
insert.setString(3, device);
insert.setString(4, id);
insert.setString(5, "REFRESH_INVENTORY");
insert.setString(6, "operator");
insert.setString(7, request.toString());
insert.setString(8, issued);
insert.setString(9, expiresAt);
insert.executeUpdate();
offline.setString(1, issued);
offline.setString(2, device);
offline.executeUpdate();
}
return (id);
}
/***************************************************************************
** Native get also runs the post-query customizer and ordinary record security.
***************************************************************************/
private static QRecord get(String id) throws QException
{
GetInput input = new GetInput();
input.setTableName(PrintingTables.COMMAND);
input.setPrimaryKey(id);
input.setPermissionEnforcement(PermissionEnforcement.ENFORCE);
return (new GetAction().execute(input).getRecord());
}
}
@@ -21,10 +21,13 @@
package com.kingsrook.qbits.printing;
import java.net.Socket;
import java.net.SocketTimeoutException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.security.MessageDigest;
@@ -36,6 +39,7 @@ import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.assertArrayEquals;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.junit.jupiter.api.Assertions.assertTrue;
@@ -48,6 +52,32 @@ class PrintingContractTest
private static final Path FIXTURES = Path.of(System.getProperty("printing.protocol.fixtures", "../qqq-print-protocol/fixtures"));
/** Default hosts cannot consume enrollment codes through the legacy bearer transport. */
@Test
void legacyEnrollmentRequiresExplicitHostOptIn() throws Exception
{
PrintingService service = new PrintingService(new DriverDataSource("jdbc:h2:mem:default-policy-" + UUID.randomUUID() + ";DB_CLOSE_DELAY=-1", "sa", ""), "contract-tenant");
service.initialize();
JSONObject enrollment = service.createEnrollment("default", "Migration").put("deviceName", "Migration").put("agentVersion", "test");
PrintingRoutes routes = new PrintingRoutes(service, context -> true);
Javalin app = Javalin.create(routes::acceptJavalinConfig).start("127.0.0.1", 0);
try(HttpClient client = HttpClient.newHttpClient())
{
String base = "http://127.0.0.1:" + app.port() + PrintingRoutes.BASE;
assertEquals(403, send(client, base, "POST", "/enroll", ADMIN, enrollment).statusCode());
assertEquals("default", service.enrollmentFacility(enrollment.getString("enrollmentCode")));
JSONObject existing = service.enroll(enrollment);
assertEquals(200, send(client, base, "POST", "/device/heartbeat", existing.getString("deviceToken"), new JSONObject().put("agentVersion", "test")).statusCode());
service.authorizeAgent(existing.getString("deviceId"), existing.getString("deviceToken"), "native-user", true);
assertEquals(401, send(client, base, "POST", "/device/heartbeat", existing.getString("deviceToken"), new JSONObject().put("agentVersion", "test")).statusCode());
}
finally
{
app.stop();
}
}
/***************************************************************************
** Enrollment through spool acknowledgment uses exactly the connector wire DTOs.
@@ -57,7 +87,7 @@ class PrintingContractTest
{
PrintingService service = new PrintingService(new DriverDataSource("jdbc:h2:mem:contract-" + UUID.randomUUID() + ";DB_CLOSE_DELAY=-1", "sa", ""), "contract-tenant");
service.initialize();
PrintingRoutes routes = new PrintingRoutes(service, context -> ADMIN.equals(PrintingRoutes.bearer(context)));
PrintingRoutes routes = new PrintingRoutes(service, context -> ADMIN.equals(PrintingRoutes.bearer(context)), PrintingRoutes.LegacyEnrollment.ENABLED);
Javalin app = Javalin.create(routes::acceptJavalinConfig).start("127.0.0.1", 0);
try(HttpClient client = HttpClient.newHttpClient())
{
@@ -122,6 +152,89 @@ class PrintingContractTest
/** Legacy compatibility transport preserves the same shared control contract and authorization boundary. */
@Test
void sharedControlFixturesRequireScopedAuthorizationAndPreserveReplay() throws Exception
{
PrintingService service = new PrintingService(new DriverDataSource("jdbc:h2:mem:control-contract-" + UUID.randomUUID() + ";DB_CLOSE_DELAY=-1", "sa", ""), "contract-tenant");
service.initialize();
PrintingRoutes routes = new PrintingRoutes(service, context -> ADMIN.equals(PrintingRoutes.bearer(context)), PrintingRoutes.LegacyEnrollment.ENABLED);
Javalin app = Javalin.create(routes::acceptJavalinConfig).start("127.0.0.1", 0);
try(HttpClient client = HttpClient.newHttpClient())
{
String base = "http://127.0.0.1:" + app.port() + PrintingRoutes.BASE;
JSONObject enrolled = service.enroll(fixture("enroll.request.json").put("enrollmentCode", service.createEnrollment("facility", "device").getString("enrollmentCode")));
String token = enrolled.getString("deviceToken");
String device = enrolled.getString("deviceId");
String actions = "/admin/devices/" + device + "/actions";
String history = "/admin/devices/" + device + "/commands";
assertEquals("device-control-v1", json(send(client, base, "GET", "/version", null, null), 200).getJSONArray("capabilities").getString(0));
JSONObject poll = fixture("control-poll.request.json").put("lastAppliedRevision", 0);
json(send(client, base, "POST", "/device/control/poll", null, poll), 401);
json(send(client, base, "POST", "/device/control/poll", token, poll), 200);
JSONObject refresh = fixture("action-refresh-inventory.request.json").put("issuedAt", java.time.Instant.now().toString());
json(send(client, base, "POST", actions, token, refresh), 403);
JSONObject command = json(send(client, base, "POST", actions, ADMIN, refresh), 200);
assertEquals(command.toString(), json(send(client, base, "POST", actions, ADMIN, refresh), 200).toString());
String commandId = command.getString("commandId");
assertEquals(commandId, json(send(client, base, "POST", "/device/control/poll", token, poll), 200).getJSONArray("commands").getJSONObject(0).getString("commandId"));
JSONObject receipt = fixture("control-inventory-refreshed.receipt.json");
String receiptPath = "/device/control/commands/" + commandId + "/receipt";
json(send(client, base, "POST", receiptPath, token, receipt), 200);
json(send(client, base, "POST", receiptPath, token, receipt), 200);
json(send(client, base, "POST", receiptPath, token, new JSONObject(receipt.toString()).put("message", "changed")), 409);
json(send(client, base, "POST", receiptPath, token, new JSONObject(receipt.toString()).put("message", "x".repeat(9000))), 413);
json(send(client, base, "GET", history, token, null), 403);
assertEquals("SUCCEEDED", json(send(client, base, "GET", history + "/" + commandId, ADMIN, null), 200).getString("status"));
json(send(client, base, "GET", history + "?limit=201", ADMIN, null), 400);
JSONObject revoke = fixture("action-revoke.request.json").put("issuedAt", java.time.Instant.now().toString());
json(send(client, base, "POST", actions, ADMIN, revoke), 200);
json(send(client, base, "POST", "/device/control/poll", token, poll), 401);
json(send(client, base, "POST", "/device/jobs/claim", token, new JSONObject()), 401);
assertEquals(2, json(send(client, base, "GET", history, ADMIN, null), 200).getJSONArray("commands").length());
}
finally
{
app.stop();
}
}
/***************************************************************************
** Claim waits for its bounded JSON body before committing the response.
***************************************************************************/
@Test
void claimConsumesSplitRequestBodyBeforeResponding() throws Exception
{
PrintingService service = new PrintingService(new DriverDataSource("jdbc:h2:mem:split-body-" + UUID.randomUUID() + ";DB_CLOSE_DELAY=-1", "sa", ""), "contract-tenant");
service.initialize();
String code = service.createEnrollment("default", "Synthetic device").getString("enrollmentCode");
String token = service.enroll(fixture("enroll.request.json").put("enrollmentCode", code)).getString("deviceToken");
PrintingRoutes routes = new PrintingRoutes(service, context -> false);
Javalin app = Javalin.create(routes::acceptJavalinConfig).start("127.0.0.1", 0);
try(Socket socket = new Socket("127.0.0.1", app.port()))
{
socket.setSoTimeout(250);
String headers = "POST " + PrintingRoutes.BASE + "/device/jobs/claim HTTP/1.1\r\nHost: 127.0.0.1:" + app.port()
+ "\r\nAuthorization: Bearer " + token + "\r\nContent-Type: application/json\r\nContent-Length: 2\r\nConnection: close\r\n\r\n{";
socket.getOutputStream().write(headers.getBytes(StandardCharsets.US_ASCII));
socket.getOutputStream().flush();
assertThrows(SocketTimeoutException.class, () -> socket.getInputStream().read());
socket.setSoTimeout(5000);
socket.getOutputStream().write('}');
socket.getOutputStream().flush();
String response = new String(socket.getInputStream().readAllBytes(), StandardCharsets.UTF_8);
assertTrue(response.startsWith("HTTP/1.1 200"));
assertTrue(response.contains("\"job\":null"));
}
finally
{
app.stop();
}
}
/***************************************************************************
** Load the same fixture consumed by the Windows protocol tests.
***************************************************************************/
@@ -0,0 +1,337 @@
/*
* QQQ - Low-code Application Framework for Engineers.
* Copyright (C) 2021-2025. Kingsrook, LLC
* 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
* contact@kingsrook.com
* https://github.com/Kingsrook/
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.kingsrook.qbits.printing;
import java.nio.charset.StandardCharsets;
import java.sql.Connection;
import java.time.Instant;
import java.util.Base64;
import java.util.List;
import java.util.UUID;
import java.util.concurrent.CountDownLatch;
import java.util.concurrent.Executors;
import org.h2.jdbcx.JdbcConnectionPool;
import org.json.JSONArray;
import org.json.JSONObject;
import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.junit.jupiter.api.Assertions.assertTrue;
/** Real durable controls, replay boundaries, tenant isolation and competing dispatch. */
class PrintingDeviceControlsTest
{
/** Regression: pauseDisconnectAndRevokeHaveDistinctDurableSemantics. */
@Test
void pauseDisconnectAndRevokeHaveDistinctDurableSemantics() throws Exception
{
Fixture f = new Fixture();
String job = f.submit("first");
JSONObject pause = action("PAUSE_DISPATCH");
JSONObject receipt = f.service.deviceAction(f.device, pause, "admin");
assertTrue(f.service.claim(f.device).isNull("job"));
assertEquals(receipt.toString(), f.service.deviceAction(f.device, pause, "admin").toString());
f.act("RESUME_DISPATCH");
f.act("DISCONNECT");
assertTrue(f.service.claim(f.device).isNull("job"));
JSONObject state = f.service.deviceControlPoll(f.device, poll()).getJSONObject("desiredState");
assertEquals("DISCONNECTED", state.getString("connectionState"));
assertFalse(state.getBoolean("dispatchPaused"));
f.act("RECONNECT");
assertEquals(job, f.service.claim(f.device).getJSONObject("job").getString("jobId"));
f.act("DISCONNECT");
f.service.event(f.device, job, new JSONObject().put("eventId", "received").put("status", "RECEIVED"));
assertEquals("RECEIVED", f.service.getJob(job).getString("status"));
f.act("REVOKE");
assertEquals(401, assertThrows(PrintingException.class, () -> f.service.authenticate(f.token)).getStatus());
assertThrows(PrintingException.class, () -> f.service.claim(f.device));
assertThrows(PrintingException.class, () -> f.service.deviceControlPoll(f.device, poll()));
assertEquals(409, assertThrows(PrintingException.class, () -> f.act("RESUME_DISPATCH")).getStatus());
assertEquals("RECEIVED", f.service.getJob(job).getString("status"));
assertFalse(f.service.deviceCommandsPage(f.device, 50, null).getJSONArray("commands").isEmpty());
}
/** Regression: clearQueueReplayNeverCancelsNewJobsOrInflightWork. */
@Test
void clearQueueReplayNeverCancelsNewJobsOrInflightWork() throws Exception
{
Fixture f = new Fixture();
String active = f.submit("active");
f.service.claim(f.device);
f.service.event(f.device, active, new JSONObject().put("eventId", "submitting").put("status", "SUBMITTING"));
String queued = f.submit("queued");
JSONObject request = action("CLEAR_QUEUE");
JSONObject first = f.service.deviceAction(f.device, request, "admin");
assertEquals(1, first.getInt("cancelledJobCount"));
assertEquals("SUBMITTING", f.service.getJob(active).getString("status"));
assertEquals("FAILED", f.service.getJob(queued).getString("status"));
try(Connection c = f.source.getConnection())
{
assertEquals(2, PrintingService.query(c, "SELECT id FROM printing_job WHERE tenant_id='tenant' AND content_available=1").size());
assertEquals(12, PrintingService.query(c, "SELECT retained_bytes FROM printing_resource_usage WHERE tenant_id='tenant' AND device_id='' ").getFirst().getLong("retained_bytes"));
assertEquals(0, PrintingService.query(c, "SELECT id FROM printing_document_orphan WHERE tenant_id='tenant'").size());
}
String later = f.submit("later");
assertEquals(first.toString(), f.service.deviceAction(f.device, request, "admin").toString());
assertEquals("QUEUED", f.service.getJob(later).getString("status"));
assertEquals(409, assertThrows(PrintingException.class, () -> f.service.deviceAction(f.device, new JSONObject(request.toString()).put("action", "PAUSE_DISPATCH"), "admin")).getStatus());
}
/** Regression: remoteCommandsRequireCapabilitiesAndReceiptsAreImmutable. */
@Test
void remoteCommandsRequireCapabilitiesAndReceiptsAreImmutable() throws Exception
{
Fixture f = new Fixture();
assertEquals(409, assertThrows(PrintingException.class, () -> f.act("REFRESH_INVENTORY")).getStatus());
f.service.deviceControlPoll(f.device, poll());
JSONObject command = f.act("REFRESH_INVENTORY");
assertEquals("PENDING", command.getString("status"));
f.act("DISCONNECT");
assertTrue(f.service.deviceControlPoll(f.device, poll()).getJSONArray("commands").isEmpty());
f.act("RECONNECT");
assertEquals(command.getString("commandId"), f.service.deviceControlPoll(f.device, poll()).getJSONArray("commands").getJSONObject(0).getString("commandId"));
JSONObject receipt = receipt("INVENTORY_REFRESHED");
f.service.deviceControlReceipt(f.device, command.getString("commandId"), receipt);
f.service.deviceControlReceipt(f.device, command.getString("commandId"), receipt);
assertEquals(409, assertThrows(PrintingException.class, () -> f.service.deviceControlReceipt(f.device, command.getString("commandId"), new JSONObject(receipt.toString()).put("outcome", "FAILED"))).getStatus());
assertEquals("SUCCEEDED", f.service.getDeviceCommand(f.device, command.getString("commandId")).getString("status"));
assertTrue(f.service.deviceControlPoll(f.device, poll()).getJSONArray("commands").isEmpty());
}
/** Regression: cancelSpoolRequiresOwnedReceiptAndNeverReclassifiesJob. */
@Test
void cancelSpoolRequiresOwnedReceiptAndNeverReclassifiesJob() throws Exception
{
Fixture f = new Fixture();
f.service.deviceControlPoll(f.device, poll());
String job = f.submit("spool");
assertEquals(409, assertThrows(PrintingException.class, () -> f.service.deviceAction(f.device, action("CANCEL_SPOOL").put("jobId", job), "admin")).getStatus());
f.service.claim(f.device);
f.service.event(f.device, job, new JSONObject().put("eventId", "spooled").put("status", "SPOOLED").put("spoolerJobId", "123"));
JSONObject command = f.service.deviceAction(f.device, action("CANCEL_SPOOL").put("jobId", job), "admin");
f.service.deviceControlReceipt(f.device, command.getString("commandId"), receipt("OWNERSHIP_MISMATCH"));
assertEquals("FAILED", f.service.getDeviceCommand(f.device, command.getString("commandId")).getString("status"));
assertEquals("SPOOLED", f.service.getJob(job).getString("status"));
assertEquals(400, assertThrows(PrintingException.class, () -> f.service.deviceAction(f.device, action("CANCEL_SPOOL").put("jobId", job).put("spoolerJobId", "999"), "admin")).getStatus());
}
/** Regression: tenantDeviceCursorAndReceiptBoundariesAreEnforced. */
@Test
void tenantDeviceCursorAndReceiptBoundariesAreEnforced() throws Exception
{
Fixture f = new Fixture();
String second = f.enroll().getString("deviceId");
JSONObject first = f.act("PAUSE_DISPATCH");
String id = first.getString("commandId");
assertEquals(404, assertThrows(PrintingException.class, () -> f.service.getDeviceCommand(second, id)).getStatus());
assertEquals(404, assertThrows(PrintingException.class, () -> f.service.deviceCommandsPage(second, 1, id)).getStatus());
assertEquals(404, assertThrows(PrintingException.class, () -> f.service.deviceControlReceipt(second, id, receipt("FAILED"))).getStatus());
PrintingService other = new PrintingService(f.source, "other-tenant");
assertEquals(404, assertThrows(PrintingException.class, () -> other.deviceAction(f.device, action("REVOKE"), "other-admin")).getStatus());
f.act("RESUME_DISPATCH");
JSONObject page = f.service.deviceCommandsPage(f.device, 1, null);
assertEquals(1, page.getJSONArray("commands").length());
assertEquals(id, f.service.deviceCommandsPage(f.device, 1, page.getString("nextCursor")).getJSONArray("commands").getJSONObject(0).getString("commandId"));
}
/** Regression: expiredCommandsAcceptLateActualOutcomeAndStaleActionsNeverExecute. */
@Test
void expiredCommandsAcceptLateActualOutcomeAndStaleActionsNeverExecute() throws Exception
{
Fixture f = new Fixture();
f.service.deviceControlPoll(f.device, poll());
JSONObject command = f.act("REFRESH_INVENTORY");
try(Connection c = f.source.getConnection())
{
PrintingService.update(c, "UPDATE printing_device_command SET expires_at=? WHERE id=?", Instant.now().minusSeconds(60).toString(), command.getString("commandId"));
}
assertTrue(f.service.deviceControlPoll(f.device, poll()).getJSONArray("commands").isEmpty());
assertEquals("EXPIRED", f.service.getDeviceCommand(f.device, command.getString("commandId")).getString("status"));
f.service.deviceControlReceipt(f.device, command.getString("commandId"), receipt("INVENTORY_REFRESHED"));
assertEquals("SUCCEEDED", f.service.getDeviceCommand(f.device, command.getString("commandId")).getString("status"));
JSONObject old = action("CLEAR_QUEUE").put("issuedAt", Instant.now().minusSeconds(901).toString());
assertEquals(410, assertThrows(PrintingException.class, () -> f.service.deviceAction(f.device, old, "admin")).getStatus());
JSONObject saved = action("PAUSE_DISPATCH");
f.service.deviceAction(f.device, saved, "admin");
saved.put("issuedAt", Instant.now().minusSeconds(8 * 86400).toString());
try(Connection c = f.source.getConnection())
{
PrintingService.update(c, "UPDATE printing_device_command SET created_at=?,expires_at=?,request_json=? WHERE request_id=?", saved.getString("issuedAt"), Instant.parse(saved.getString("issuedAt")).plusSeconds(900).toString(), saved.toString(), saved.getString("requestId"));
}
assertEquals("SUCCEEDED", f.service.deviceAction(f.device, saved, "admin").getString("status"));
f.act("RESUME_DISPATCH");
assertEquals(410, assertThrows(PrintingException.class, () -> f.service.deviceAction(f.device, saved, "admin")).getStatus());
assertFalse(f.service.deviceControlPoll(f.device, poll()).getJSONObject("desiredState").getBoolean("dispatchPaused"));
assertEquals(400, assertThrows(PrintingException.class, () -> f.service.deviceAction(f.device, action("PAUSE_DISPATCH").put("issuedAt", Instant.now().plusSeconds(120).toString()), "admin")).getStatus());
}
/** Regression: concurrentClearAndClaimCannotBothOwnTheSameQueuedJob. */
@Test
void concurrentClearAndClaimCannotBothOwnTheSameQueuedJob() throws Exception
{
Fixture f = new Fixture();
PrintingService second = new PrintingService(f.source, "tenant");
String job = f.submit("race");
CountDownLatch start = new CountDownLatch(1);
try(var executor = Executors.newFixedThreadPool(2))
{
var clear = executor.submit(() ->
{
start.await();
return f.act("CLEAR_QUEUE");
});
var claim = executor.submit(() ->
{
start.await();
return second.claim(f.device);
});
start.countDown();
int canceled = clear.get().getInt("cancelledJobCount");
boolean claimed = !claim.get().isNull("job");
assertEquals(canceled == 0, claimed);
assertEquals(claimed ? "CLAIMED" : "FAILED", f.service.getJob(job).getString("status"));
}
}
/** Regression: pendingAndHistoryBudgetsRetainEmergencyRevocation. */
@Test
void pendingAndHistoryBudgetsRetainEmergencyRevocation() throws Exception
{
Fixture f = new Fixture();
f.service.deviceControlPoll(f.device, poll());
for(int i = 0; i < 100; i++)
{
f.act("REFRESH_INVENTORY");
}
assertEquals(429, assertThrows(PrintingException.class, () -> f.act("REFRESH_INVENTORY")).getStatus());
assertEquals(20, f.service.deviceControlPoll(f.device, poll()).getJSONArray("commands").length());
for(int i = 100; i < 1000; i++)
{
f.act("PAUSE_DISPATCH");
}
assertEquals(429, assertThrows(PrintingException.class, () -> f.act("RESUME_DISPATCH")).getStatus());
assertEquals("CREDENTIAL_REVOKED", f.act("REVOKE").getString("resultCode"));
assertEquals(401, assertThrows(PrintingException.class, () -> f.service.authenticate(f.token)).getStatus());
}
/** All control paths work with a single real pooled connection and preserve escaped receipt data. */
@Test
void singleConnectionPreservesStateAndBoundedUnicodeReceipts() throws Exception
{
JdbcConnectionPool pool = JdbcConnectionPool.create("jdbc:h2:mem:controls-pool-" + UUID.randomUUID() + ";DB_CLOSE_DELAY=-1", "sa", "");
pool.setMaxConnections(1);
pool.setLoginTimeout(2);
try
{
PrintingService first = new PrintingService(pool, "tenant");
first.initialize();
String device = first.enroll(first.createEnrollment("facility", "device").put("deviceName", "device").put("agentVersion", "test")).getString("deviceId");
first.deviceControlPoll(device, poll());
JSONObject command = first.deviceAction(device, action("REFRESH_INVENTORY"), "actor");
JSONObject result = receipt("INVENTORY_REFRESHED").put("message", "\u0001".repeat(1024));
first.deviceControlReceipt(device, command.getString("commandId"), result);
PrintingService reopened = new PrintingService(pool, "tenant");
assertTrue(reopened.getDeviceCommand(device, command.getString("commandId")).getJSONObject("receipt").similar(result));
JSONObject paused = action("PAUSE_DISPATCH");
first.deviceAction(device, paused, "actor");
assertTrue(reopened.deviceControlPoll(device, poll()).getJSONObject("desiredState").getBoolean("dispatchPaused"));
assertEquals(2, reopened.deviceCommandsPage(device, 10, null).getJSONArray("commands").length());
assertEquals("SUCCEEDED", reopened.deviceAction(device, paused, "actor").getString("status"));
}
finally
{
pool.dispose();
}
}
/** Explicit fresh action identity, retained unchanged by callers when retrying. */
private static JSONObject action(String action)
{
return (new JSONObject().put("requestId", UUID.randomUUID().toString()).put("issuedAt", Instant.now().toString()).put("action", action));
}
/** Advertise only the two implemented remote operations. */
private static JSONObject poll()
{
return (new JSONObject().put("controlVersion", 1).put("agentVersion", "test").put("lastAppliedRevision", 0)
.put("capabilities", new JSONArray(List.of("REFRESH_INVENTORY", "CANCEL_SPOOL"))));
}
/** A synthetic command observation carries no arbitrary executable data. */
private static JSONObject receipt(String outcome)
{
return (new JSONObject().put("receiptId", UUID.randomUUID().toString()).put("outcome", outcome).put("completedAt", Instant.now().toString()));
}
/** Real isolated database and approved synthetic printer for each test. */
private static final class Fixture
{
private final DriverDataSource source = new DriverDataSource("jdbc:h2:mem:" + UUID.randomUUID() + ";DB_CLOSE_DELAY=-1", "sa", "");
private final PrintingService service = new PrintingService(source, "tenant");
private final String device;
private final String token;
/** Initialize once; new service instances must observe the same durable state. */
private Fixture() throws Exception
{
service.initialize();
JSONObject enrolled = enroll();
device = enrolled.getString("deviceId");
token = enrolled.getString("deviceToken");
service.inventory(device, new JSONArray().put(new JSONObject().put("printerId", "zebra").put("name", "Zebra").put("formats", new JSONArray(List.of("ZPL")))));
service.enablePrinter(device, "zebra", true);
}
/** Pair without sharing another device's credential. */
private JSONObject enroll() throws Exception
{
return (service.enroll(service.createEnrollment("warehouse", "station").put("deviceName", "station").put("agentVersion", "test")));
}
/** Use normal admission and retained document accounting. */
private String submit(String key) throws Exception
{
return (service.submit(new JSONObject().put("deviceId", device).put("printerId", "zebra").put("title", "Synthetic")
.put("format", "ZPL").put("contentBase64", Base64.getEncoder().encodeToString("^XA^XZ".getBytes(StandardCharsets.UTF_8))).put("idempotencyKey", key)).getString("jobId"));
}
/** Apply through the same facade used by authenticated native and HTTP adapters. */
private JSONObject act(String action) throws Exception
{
return (service.deviceAction(device, action(action), "admin"));
}
}
}
@@ -0,0 +1,313 @@
/*
* QQQ - Low-code Application Framework for Engineers.
* Copyright (C) 2021-2025. Kingsrook, LLC
* 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
* contact@kingsrook.com
* https://github.com/Kingsrook/
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.kingsrook.qbits.printing;
import java.nio.charset.StandardCharsets;
import java.time.Instant;
import java.util.Base64;
import java.util.List;
import java.util.Map;
import java.util.Set;
import java.util.UUID;
import com.kingsrook.qqq.backend.core.actions.dashboard.widgets.ChildRecordListRenderer;
import com.kingsrook.qqq.backend.core.actions.tables.GetAction;
import com.kingsrook.qqq.backend.core.actions.tables.QueryAction;
import com.kingsrook.qqq.backend.core.context.QContext;
import com.kingsrook.qqq.backend.core.exceptions.QException;
import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepInput;
import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepOutput;
import com.kingsrook.qqq.backend.core.model.actions.tables.get.GetInput;
import com.kingsrook.qqq.backend.core.model.actions.tables.query.QCriteriaOperator;
import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryInput;
import com.kingsrook.qqq.backend.core.model.actions.widgets.RenderWidgetInput;
import com.kingsrook.qqq.backend.core.model.dashboard.widgets.ChildRecordListData;
import com.kingsrook.qqq.backend.core.model.data.QRecord;
import org.json.JSONObject;
import org.junit.jupiter.api.AfterEach;
import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertNotNull;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.junit.jupiter.api.Assertions.assertTrue;
/*******************************************************************************
** Native control actions preserve identity, live permissions and row security.
** Fixtures use in-memory SQL and never contact Windows or physical printers.
*******************************************************************************/
class PrintingDeviceProcessesTest
{
/***************************************************************************
** Prevent one test's authority from leaking into another test.
***************************************************************************/
@AfterEach
void clearContext()
{
QContext.clear();
}
/***************************************************************************
** Every device control and late-job action is available on native selections.
***************************************************************************/
@Test
void metadataIncludesControlsHistoryAndDeviceQueue() throws Exception
{
var fixture = PrintingProcessesTest.fixture();
for(var action : PrintingDeviceProcesses.Action.values())
{
var process = fixture.instance().getProcess(action.process);
assertNotNull(process);
assertEquals(action.job ? PrintingTables.JOB : PrintingTables.DEVICE, process.getTableName());
assertNotNull(process.getStep("prepareControl"));
}
assertNotNull(fixture.instance().getWidget("printing_device_queue"));
assertNotNull(fixture.instance().getWidget("printing_printer_queue"));
assertTrue(fixture.instance().getTables().keySet().stream().allMatch(name -> name.startsWith("printing_")));
assertFalse(fixture.instance().getTable(PrintingTables.COMMAND).getFields().containsKey("request_json"));
assertFalse(fixture.instance().getTable(PrintingTables.COMMAND).getFields().containsKey("receipt_json"));
assertEquals(PrintingTables.DEVICE, fixture.instance().getTable(PrintingTables.COMMAND).getField("device_id").getPossibleValueSourceName());
}
/***************************************************************************
** Preparation/review cannot change a device, and revoked permissions block load.
***************************************************************************/
@Test
void previewDoesNotMutateAndPermissionRemovalBlocksExecution() throws Exception
{
var fixture = PrintingProcessesTest.fixture();
RunBackendStepInput input = prepared(PrintingDeviceProcesses.Action.PAUSE, fixture.device());
RunBackendStepOutput review = new RunBackendStepOutput();
new PrintingDeviceProcesses.Transform().runOnePage(input, review);
assertEquals(1, review.getRecords().size());
assertEquals(0, fixture.service().deviceCommandsPage(fixture.device(), 50, null).getJSONArray("commands").length());
QContext.getQSession().setPermissions(Set.of());
assertThrows(QException.class, () -> new PrintingDeviceProcesses.Load().runOnePage(input, new RunBackendStepOutput()));
}
/***************************************************************************
** Untrusted extracted values cannot select a foreign device or spoof the actor.
***************************************************************************/
@Test
void loadRechecksRowsAndRecordsTheAuthenticatedActor() throws Exception
{
var fixture = PrintingProcessesTest.fixture();
RunBackendStepInput forged = prepared(PrintingDeviceProcesses.Action.PAUSE, fixture.foreignDevice());
assertThrows(QException.class, () -> new PrintingDeviceProcesses.Load().runOnePage(forged, new RunBackendStepOutput()));
RunBackendStepInput input = prepared(PrintingDeviceProcesses.Action.PAUSE, fixture.device());
input.addValue("actor", "forged administrator");
new PrintingDeviceProcesses.Load().runOnePage(input, new RunBackendStepOutput());
assertEquals(1, get(PrintingTables.DEVICE, fixture.device()).getValueInteger("dispatch_paused"));
var command = fixture.service().deviceCommandsPage(fixture.device(), 50, null).getJSONArray("commands").getJSONObject(0);
assertEquals("operator", get(PrintingTables.COMMAND, command.getString("commandId")).getValueString("actor"));
new PrintingDeviceProcesses.Load().runOnePage(input, new RunBackendStepOutput());
assertEquals(1, fixture.service().deviceCommandsPage(fixture.device(), 50, null).getJSONArray("commands").length());
}
/***************************************************************************
** Selected late jobs produce valid, stable wire request IDs and one command.
***************************************************************************/
@Test
void nativeWindowsCancellationReplaysTheSameOwnedJobCommand() throws Exception
{
var fixture = PrintingProcessesTest.fixture();
fixture.service().deviceControlPoll(fixture.device(), new JSONObject().put("controlVersion", 1).put("agentVersion", "test")
.put("capabilities", new org.json.JSONArray(List.of("CANCEL_SPOOL"))).put("lastAppliedRevision", 0));
String job = submit(fixture.service(), fixture.device());
fixture.service().claim(fixture.device());
fixture.service().event(fixture.device(), job, new JSONObject().put("eventId", "test-spooled").put("status", "SPOOLED").put("spoolerJobId", "42"));
RunBackendStepInput input = prepared(PrintingDeviceProcesses.Action.CANCEL_WINDOWS, job);
input.addValue(PrintingDeviceProcesses.CONFIRM, true);
new PrintingDeviceProcesses.Load().runOnePage(input, new RunBackendStepOutput());
new PrintingDeviceProcesses.Load().runOnePage(input, new RunBackendStepOutput());
var commands = fixture.service().deviceCommandsPage(fixture.device(), 50, null).getJSONArray("commands");
assertEquals(1, commands.length());
assertEquals(job, commands.getJSONObject(0).getString("jobId"));
assertEquals("CANCEL_SPOOL", commands.getJSONObject(0).getString("action"));
assertEquals("PENDING", commands.getJSONObject(0).getString("status"));
assertEquals("SPOOLED", fixture.service().getJob(job).getString("status"));
}
/***************************************************************************
** Replaying a native clear action never cancels work added after its receipt.
***************************************************************************/
@Test
void nativeQueueClearReplayPreservesLaterWorkAndRequiresConsent() throws Exception
{
var fixture = PrintingProcessesTest.fixture();
String first = submit(fixture.service(), fixture.device());
RunBackendStepInput input = prepared(PrintingDeviceProcesses.Action.CLEAR, fixture.device());
assertThrows(QException.class, () -> new PrintingDeviceProcesses.Load().runOnePage(input, new RunBackendStepOutput()));
assertEquals("QUEUED", fixture.service().getJob(first).getString("status"));
input.addValue(PrintingDeviceProcesses.CONFIRM, true);
new PrintingDeviceProcesses.Load().runOnePage(input, new RunBackendStepOutput());
String later = submit(fixture.service(), fixture.device());
new PrintingDeviceProcesses.Load().runOnePage(input, new RunBackendStepOutput());
assertEquals("FAILED", fixture.service().getJob(first).getString("status"));
assertEquals("QUEUED", fixture.service().getJob(later).getString("status"));
assertEquals(1, fixture.service().deviceCommandsPage(fixture.device(), 50, null).getJSONArray("commands").length());
}
/***************************************************************************
** Short projections must use current scoped dependencies, without returning them.
***************************************************************************/
@Test
void deviceStatusProjectionReflectsPauseWithoutLeakingExtraColumns() throws Exception
{
var fixture = PrintingProcessesTest.fixture();
new PrintingDeviceProcesses.Load().runOnePage(prepared(PrintingDeviceProcesses.Action.PAUSE, fixture.device()), new RunBackendStepOutput());
QueryInput query = new QueryInput().withTableName(PrintingTables.DEVICE)
.withFieldNamesToInclude(Set.of("id", "name", "device_status", "control_status"))
.withFilter(new QQueryFilter().withCriteria("id", QCriteriaOperator.EQUALS, fixture.device()));
QRecord row = new QueryAction().execute(query).getRecords().getFirst();
assertEquals("PAUSED", row.getValueString("device_status"));
assertEquals("UNKNOWN", row.getValueString("control_status"));
assertFalse(row.getValues().containsKey("dispatch_paused"));
assertFalse(row.getValues().containsKey("control_revision"));
query.setFieldNamesToInclude(Set.of("name", "device_status"));
assertThrows(QException.class, () -> new QueryAction().execute(query));
}
/***************************************************************************
** The record's queue widget is scoped to that device and excludes old outcomes.
***************************************************************************/
@Test
void deviceQueueWidgetShowsOnlyItsPendingWork() throws Exception
{
var fixture = PrintingProcessesTest.fixture();
String queued = submit(fixture.service(), fixture.device());
String canceled = submit(fixture.service(), fixture.device());
fixture.service().cancel(fixture.device(), canceled);
submit(fixture.service(), fixture.otherDevice());
RenderWidgetInput input = new RenderWidgetInput().withWidgetMetaData(fixture.instance().getWidget("printing_device_queue"));
input.setQueryParams(Map.of("id", fixture.device(), "joinName", input.getWidgetMetaData().getDefaultValues().get("joinName").toString()));
var data = (ChildRecordListData) new ChildRecordListRenderer().render(input).getWidgetData();
assertEquals(List.of(queued), data.getQueryOutput().getRecords().stream().map(row -> row.getValueString("id")).toList());
input.setQueryParams(Map.of("id", fixture.foreignDevice(), "joinName", input.getWidgetMetaData().getDefaultValues().get("joinName").toString()));
assertThrows(QException.class, () -> new ChildRecordListRenderer().render(input));
}
/***************************************************************************
** State and observation differ; malformed/future timestamps never imply online.
***************************************************************************/
@Test
void statusDistinguishesPresenceDesiredStateAndObservedRevision()
{
Instant now = Instant.parse("2026-10-31T12:00:00Z");
QRecord row = new QRecord().withValue("enabled", 1).withValue("last_seen_at", now.minusSeconds(120).toString())
.withValue("control_last_poll_at", now.minusSeconds(2).toString()).withValue("control_version", 1)
.withValue("control_revision", 3L).withValue("control_applied_revision", 2L);
assertEquals("ONLINE", PrintingDeviceStatus.presence(row, now));
assertEquals("PENDING", PrintingDeviceStatus.application(row));
row.setValue("control_applied_revision", 3L);
assertEquals("APPLIED", PrintingDeviceStatus.application(row));
row.setValue("dispatch_paused", 1);
assertEquals("PAUSED", PrintingDeviceStatus.presence(row, now));
row.setValue("connection_state", "DISCONNECTED");
assertEquals("DISCONNECTED", PrintingDeviceStatus.presence(row, now));
row.setValue("enabled", 0);
assertEquals("REVOKED", PrintingDeviceStatus.presence(row, now));
row.setValue("enabled", 1);
row.setValue("connection_state", "CONNECTED");
row.setValue("control_last_poll_at", "malformed");
assertEquals("OFFLINE", PrintingDeviceStatus.presence(row, now));
row.setValue("last_seen_at", now.plusSeconds(120).toString());
assertEquals("UNKNOWN", PrintingDeviceStatus.presence(row, now));
}
/***************************************************************************
** Persist both identity fields; an old review cannot acquire a fresh timestamp.
***************************************************************************/
@Test
void preparationPreservesIdentityAndRejectsIncompleteOrExpiredRequests() throws Exception
{
var fixture = PrintingProcessesTest.fixture();
RunBackendStepInput input = prepared(PrintingDeviceProcesses.Action.PAUSE, fixture.device());
RunBackendStepOutput again = new RunBackendStepOutput();
new PrintingDeviceProcesses.Prepare().run(input, again);
assertEquals(input.getValueString(PrintingDeviceProcesses.REQUEST_ID), again.getValueString(PrintingDeviceProcesses.REQUEST_ID));
assertEquals(input.getValueString(PrintingDeviceProcesses.ISSUED_AT), again.getValueString(PrintingDeviceProcesses.ISSUED_AT));
input.addValue(PrintingDeviceProcesses.ISSUED_AT, Instant.now().minusSeconds(901).toString());
assertThrows(QException.class, () -> new PrintingDeviceProcesses.Load().runOnePage(input, new RunBackendStepOutput()));
input.addValue(PrintingDeviceProcesses.ISSUED_AT, null);
assertThrows(QException.class, () -> new PrintingDeviceProcesses.Prepare().run(input, new RunBackendStepOutput()));
}
/***************************************************************************
** Synthetic jobs never leave the in-memory server fixture.
***************************************************************************/
private static String submit(PrintingService service, String device) throws Exception
{
return (service.submit(new JSONObject().put("deviceId", device).put("printerId", "laser").put("title", "Control fixture")
.put("format", "PDF").put("contentBase64", Base64.getEncoder().encodeToString("%PDF-1.4 fixture".getBytes(StandardCharsets.UTF_8)))
.put("idempotencyKey", UUID.randomUUID().toString())).getString("jobId"));
}
/***************************************************************************
** Real native request preparation keeps tests independent of UUID generation.
***************************************************************************/
private static RunBackendStepInput prepared(PrintingDeviceProcesses.Action action, String id) throws QException
{
RunBackendStepInput input = new RunBackendStepInput().withProcessName(action.process).withRecords(List.of(new QRecord().withValue("id", id)));
RunBackendStepOutput output = new RunBackendStepOutput();
new PrintingDeviceProcesses.Prepare().run(input, output);
input.addValue(PrintingDeviceProcesses.REQUEST_ID, output.getValueString(PrintingDeviceProcesses.REQUEST_ID));
input.addValue(PrintingDeviceProcesses.ISSUED_AT, output.getValueString(PrintingDeviceProcesses.ISSUED_AT));
return (input);
}
/***************************************************************************
** Metadata reads are subject to normal native permission/record checks.
***************************************************************************/
private static QRecord get(String table, String id) throws QException
{
GetInput input = new GetInput();
input.setTableName(table);
input.setPrimaryKey(id);
return (new GetAction().execute(input).getRecord());
}
}
@@ -0,0 +1,391 @@
/*
* QQQ - Low-code Application Framework for Engineers.
* Copyright (C) 2021-2025. Kingsrook, LLC
* 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
* contact@kingsrook.com
* https://github.com/Kingsrook/
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.kingsrook.qbits.printing;
import java.nio.charset.StandardCharsets;
import java.sql.SQLException;
import java.time.Instant;
import java.util.Base64;
import java.util.List;
import java.util.UUID;
import com.kingsrook.qqq.backend.core.context.QContext;
import com.kingsrook.qqq.backend.core.model.metadata.QBackendMetaData;
import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldMetaData;
import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldType;
import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
import com.kingsrook.qqq.backend.module.filesystem.s3.model.metadata.S3BackendMetaData;
import com.kingsrook.qqq.backend.module.filesystem.s3.model.metadata.S3TableBackendDetails;
import org.json.JSONArray;
import org.json.JSONObject;
import org.junit.jupiter.api.AfterEach;
import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.assertArrayEquals;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertNotEquals;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.junit.jupiter.api.Assertions.assertTrue;
/*******************************************************************************
** Exercise the native storage abstraction with isolated in-memory objects.
** S3 metadata validation never contacts an endpoint or uses credentials.
*******************************************************************************/
class PrintingDocumentStorageTest
{
private static final byte[] DOCUMENT = "^XA^FO20,20^FDTest^FS^XZ".getBytes(StandardCharsets.US_ASCII);
/***************************************************************************
** New payloads are external; historical bindings survive target changes.
***************************************************************************/
@Test
void storesNativeObjectsAndReadsImmutableHistoricalBindings() throws Exception
{
Fixture fixture = fixture();
String id = fixture.service.submit(request(fixture.device, "first")).getString("jobId");
JSONObject stored = row(fixture.source, "SELECT * FROM printing_job WHERE id='" + id + "'");
fixture.service.claim(fixture.device);
assertTrue(stored.isNull("CONTENT_BASE64"));
assertEquals("printing_documents", stored.getString("CONTENT_STORAGE_TABLE"));
assertArrayEquals(DOCUMENT, fixture.service.content(fixture.device, id));
assertTrue(QContext.getQSession() == null);
fixture.service.configureStorage(fixture.storage, "printing_archive");
assertArrayEquals(DOCUMENT, fixture.service.content(fixture.device, id));
ageSuccess(fixture, id);
JSONObject retryRequest = new JSONObject().put("requestId", "retry").put("confirmDuplicateRisk", true);
String retry = fixture.service.retry(fixture.device, id, retryRequest).getString("jobId");
fixture.service.claim(fixture.device);
assertNotEquals(id, retry);
assertEquals("printing_archive", row(fixture.source, "SELECT * FROM printing_job WHERE id='" + retry + "'").getString("CONTENT_STORAGE_TABLE"));
assertEquals(1, fixture.service.runRetention());
assertEquals(retry, fixture.service.retry(fixture.device, id, retryRequest).getString("jobId"));
assertEquals(410, assertThrows(PrintingException.class, () -> fixture.service.retry(fixture.device, id, new JSONObject(retryRequest.toString()).put("requestId", "new"))).getStatus());
assertArrayEquals(DOCUMENT, fixture.service.content(fixture.device, retry));
assertEquals(1, fixture.service.getRetentionSettings().getInt("lastRunCount"));
assertEquals(0, fixture.service.getRetentionSettings().getLong("eligibleBacklog"));
}
/***************************************************************************
** Foreign tenant, sibling job and retargeted metadata fail before deletion.
***************************************************************************/
@Test
void rejectsForeignAndSiblingReferencesAndChangedBindings() throws Exception
{
Fixture fixture = fixture();
String first = fixture.service.submit(request(fixture.device, "first")).getString("jobId");
String second = fixture.service.submit(request(fixture.device, "second")).getString("jobId");
execute(fixture.source, "UPDATE printing_job SET status='CLAIMED'");
String own = fixture.storage.prefix() + first + ".zpl";
String sibling = fixture.storage.prefix() + second + ".zpl";
for(String invalid : List.of(sibling, new PrintingDocumentStorage(fixture.instance, "foreign", true).prefix() + first + ".zpl", "../foreign.zpl"))
{
execute(fixture.source, "UPDATE printing_job SET content_reference=? WHERE id=?", invalid, first);
assertEquals(409, assertThrows(PrintingException.class, () -> fixture.service.content(fixture.device, first)).getStatus());
ageSuccess(fixture, first);
assertThrows(PrintingException.class, fixture.service::runRetention);
assertArrayEquals(DOCUMENT, fixture.storage.get("printing_documents", own));
assertArrayEquals(DOCUMENT, fixture.service.content(fixture.device, second));
}
execute(fixture.source, "UPDATE printing_job SET content_reference=?,content_binding=? WHERE id=?", own, "incorrect", first);
assertEquals(409, assertThrows(PrintingException.class, () -> fixture.service.content(fixture.device, first)).getStatus());
}
/***************************************************************************
** Upload/delete failures leave durable exact references for later recovery.
***************************************************************************/
@Test
void uploadFailureAndOrphanRetryNeverDeleteAnotherJob() throws Exception
{
Fixture fixture = fixture();
fixture.storage.failUpload = true;
assertThrows(SQLException.class, () -> fixture.service.submit(request(fixture.device, "compensated")));
assertEquals(0, row(fixture.source, "SELECT COUNT(*) AS total FROM printing_document_orphan").getInt("TOTAL"));
assertThrows(SQLException.class, () -> fixture.storage.get("printing_documents", fixture.storage.lastReference));
fixture.storage.failDelete = true;
assertThrows(SQLException.class, () -> fixture.service.submit(request(fixture.device, "broken")));
assertEquals(0, fixture.service.jobs().length());
JSONObject orphan = row(fixture.source, "SELECT * FROM printing_document_orphan");
String reference = orphan.getString("REFERENCE");
assertArrayEquals(DOCUMENT, fixture.storage.get("printing_documents", reference));
fixture.storage.failUpload = false;
fixture.storage.failDelete = false;
String other = fixture.service.submit(request(fixture.device, "other")).getString("jobId");
fixture.service.claim(fixture.device);
execute(fixture.source, "UPDATE printing_document_orphan SET created_at=?,reference=?", Instant.now().minusSeconds(7200).toString(), fixture.storage.prefix() + other + ".zpl");
assertThrows(PrintingException.class, fixture.service::runRetention);
assertArrayEquals(DOCUMENT, fixture.service.content(fixture.device, other));
execute(fixture.source, "UPDATE printing_document_orphan SET reference=?", reference);
assertEquals(1, fixture.service.runRetention());
assertThrows(SQLException.class, () -> fixture.storage.get("printing_documents", reference));
assertArrayEquals(DOCUMENT, fixture.service.content(fixture.device, other));
}
/***************************************************************************
** A later failed removal cannot roll back a prior confirmed receipt.
***************************************************************************/
@Test
void commitsSuccessfulDeletionBeforeLaterFailure() throws Exception
{
Fixture fixture = fixture();
String first = fixture.service.submit(request(fixture.device, "first")).getString("jobId");
String second = fixture.service.submit(request(fixture.device, "second")).getString("jobId");
ageSuccess(fixture, first);
ageSuccess(fixture, second);
fixture.storage.failDeleteNumber = 2;
assertThrows(SQLException.class, fixture.service::runRetention);
assertEquals(1, row(fixture.source, "SELECT COUNT(*) AS total FROM printing_job WHERE content_available=0").getInt("TOTAL"));
assertEquals(1, fixture.service.getRetentionSettings().getInt("lastRunCount"));
assertFalse(fixture.service.getRetentionSettings().getString("lastRunError").isBlank());
fixture.storage.failDeleteNumber = -1;
assertEquals(1, fixture.service.runRetention());
assertEquals(0, fixture.service.runRetention());
}
/***************************************************************************
** Canonical bucket checks ignore region/path-style/default-port aliases.
***************************************************************************/
@Test
void validatesDedicatedS3BindingWithoutNetwork() throws Exception
{
QInstance instance = new QInstance();
S3BackendMetaData printing = new S3BackendMetaData().withName("printing").withBucketName("print-documents").withEndpoint("https://storage.example");
instance.addBackend(printing);
instance.addTable(new QTableMetaData().withName("printing_documents").withBackendName("printing").withBackendDetails(new S3TableBackendDetails()));
PrintingDocumentStorage storage = new PrintingDocumentStorage(instance, "tenant-a");
String original = storage.binding("printing_documents");
printing.setBucketName("another-bucket");
assertThrows(PrintingException.class, () -> storage.verifyBinding("printing_documents", original));
printing.setBucketName("print-documents");
S3BackendMetaData other = new S3BackendMetaData().withName("uploads").withBucketName("print-documents").withEndpoint("https://storage.example:443/");
other.setPathStyleAccess(true);
other.setRegion("different-region");
instance.addBackend(other);
instance.addTable(new QTableMetaData().withName("general_uploads").withBackendName("uploads").withBackendDetails(new S3TableBackendDetails()));
assertThrows(IllegalArgumentException.class, () -> storage.binding("printing_documents"));
other.setEndpoint("https://separate.example");
assertEquals(original, storage.binding("printing_documents"));
for(String endpoint : List.of("http://remote.example", "ftp://remote.example", "https://user:secret@storage.example", "https://storage.example?secret=value", "//storage.example"))
{
printing.setEndpoint(endpoint);
assertThrows(IllegalArgumentException.class, () -> storage.binding("printing_documents"));
}
printing.setEndpoint("http://127.0.0.1:9000");
assertFalse(storage.binding("printing_documents").isBlank());
}
/***************************************************************************
** Existing active documents get a full retention interval after completion.
***************************************************************************/
@Test
void completionAgeAndLegacyMigrationAreConservative() throws Exception
{
Fixture fixture = fixture();
String job = fixture.service.submit(request(fixture.device, "old-active")).getString("jobId");
execute(fixture.source, "UPDATE printing_job SET created_at=? WHERE id=?", Instant.now().minusSeconds(800 * 86400L).toString(), job);
fixture.service.claim(fixture.device);
fixture.service.event(fixture.device, job, new JSONObject().put("eventId", UUID.randomUUID().toString()).put("status", "SPOOLED"));
assertEquals(0, fixture.service.runRetention());
execute(fixture.source, "UPDATE printing_job SET completed_at=NULL WHERE id=?", job);
fixture.service.initialize();
assertEquals(0, fixture.service.runRetention());
assertFalse(row(fixture.source, "SELECT * FROM printing_job WHERE id='" + job + "'").isNull("COMPLETED_AT"));
execute(fixture.source, "DELETE FROM printing_event WHERE job_id=?", job);
execute(fixture.source, "UPDATE printing_job SET completed_at=NULL WHERE id=?", job);
fixture.service.initialize();
assertEquals(0, fixture.service.runRetention());
}
/***************************************************************************
** Shared synthetic fixture; no S3 bucket or printer is used.
***************************************************************************/
private static Fixture fixture() throws Exception
{
QContext.clear();
QInstance instance = new QInstance();
instance.withInstanceDefaultAuthentication(new com.kingsrook.qqq.backend.core.model.metadata.authentication.QAuthenticationMetaData().withName("mock").withType(com.kingsrook.qqq.backend.core.model.metadata.QAuthenticationType.MOCK));
instance.addBackend(new QBackendMetaData().withName("memory").withBackendType(com.kingsrook.qqq.backend.core.modules.backend.implementations.memory.MemoryBackendModule.class));
for(String table : List.of("printing_documents", "printing_archive"))
{
instance.addTable(new QTableMetaData().withName(table).withBackendName("memory").withPrimaryKeyField("id")
.withField(new QFieldMetaData("id", QFieldType.STRING)).withField(new QFieldMetaData("content", QFieldType.BLOB)));
}
DriverDataSource source = new DriverDataSource("jdbc:h2:mem:storage-" + UUID.randomUUID() + ";DB_CLOSE_DELAY=-1", "sa", "");
FaultStorage storage = new FaultStorage(instance);
PrintingService service = new PrintingService(source, "tenant-a");
service.initialize();
service.configureStorage(storage, "printing_documents");
String device = service.enroll(service.createEnrollment("warehouse", "station").put("deviceName", "station").put("agentVersion", "test")).getString("deviceId");
service.inventory(device, new JSONArray().put(new JSONObject().put("printerId", "queue").put("name", "Synthetic").put("formats", new JSONArray(List.of("ZPL")))));
service.enablePrinter(device, "queue", true);
return (new Fixture(source, service, storage, instance, device));
}
/***************************************************************************
** Synthetic bytes never leave the test process.
***************************************************************************/
private static JSONObject request(String device, String key)
{
return (new JSONObject().put("deviceId", device).put("printerId", "queue").put("title", "Synthetic").put("format", "ZPL")
.put("contentBase64", Base64.getEncoder().encodeToString(DOCUMENT)).put("idempotencyKey", key));
}
/***************************************************************************
** Explicitly age a synthetic successful receipt.
***************************************************************************/
private static void ageSuccess(Fixture fixture, String id) throws Exception
{
execute(fixture.source, "UPDATE printing_job SET status='SPOOLED',completed_at=? WHERE id=?", Instant.now().minusSeconds(400 * 86400L).toString(), id);
}
/***************************************************************************
** Isolated database mutations for fault and migration fixtures.
***************************************************************************/
private static void execute(DriverDataSource source, String sql, Object... values) throws Exception
{
try(var connection = source.getConnection(); var statement = connection.prepareStatement(sql))
{
for(int index = 0; index < values.length; index++)
{
statement.setObject(index + 1, values[index]);
}
statement.executeUpdate();
}
}
/***************************************************************************
** Read synthetic metadata without loading production state.
***************************************************************************/
private static JSONObject row(DriverDataSource source, String sql) throws Exception
{
try(var connection = source.getConnection(); var statement = connection.createStatement(); var rows = statement.executeQuery(sql))
{
assertTrue(rows.next());
JSONObject result = new JSONObject();
for(int index = 1; index <= rows.getMetaData().getColumnCount(); index++)
{
result.put(rows.getMetaData().getColumnLabel(index), rows.getObject(index) == null ? JSONObject.NULL : rows.getObject(index));
}
return (result);
}
}
/***************************************************************************
** Do not leak the memory backend context between tests.
***************************************************************************/
@AfterEach
void clear()
{
QContext.clear();
}
/***************************************************************************
** Compact isolated state owned by one test.
***************************************************************************/
private record Fixture(DriverDataSource source, PrintingService service, FaultStorage storage, QInstance instance, String device)
{
}
/***************************************************************************
** Fail after upload or at a selected deletion to exercise crash receipts.
***************************************************************************/
private static class FaultStorage extends PrintingDocumentStorage
{
private boolean failUpload;
private boolean failDelete;
private int failDeleteNumber = -1;
private int deletes;
private String lastReference;
/************************************************************************
** Use real QQQ memory storage underneath each injected failure.
************************************************************************/
private FaultStorage(QInstance instance)
{
super(instance, "tenant-a", true);
}
/************************************************************************
** Ambiguous upload failure may already have stored all bytes.
************************************************************************/
@Override
public void put(String table, String reference, String format, byte[] content) throws SQLException
{
lastReference = reference;
super.put(table, reference, format, content);
if(failUpload)
{
throw new SQLException("Synthetic upload acknowledgement failure");
}
}
/************************************************************************
** Failed deletes must retain a retryable database reference.
************************************************************************/
@Override
public void delete(String table, String reference) throws SQLException
{
deletes++;
if(failDelete || deletes == failDeleteNumber)
{
throw new SQLException("Synthetic deletion failure");
}
super.delete(table, reference);
}
}
}
@@ -0,0 +1,162 @@
/*
* QQQ - Low-code Application Framework for Engineers.
* Copyright (C) 2021-2025. Kingsrook, LLC
* 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
* contact@kingsrook.com
* https://github.com/Kingsrook/
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.kingsrook.qbits.printing;
import java.util.List;
import java.util.Set;
import java.util.concurrent.atomic.AtomicBoolean;
import java.util.stream.Collectors;
import com.kingsrook.qqq.backend.core.actions.permissions.PermissionEnforcement;
import com.kingsrook.qqq.backend.core.actions.processes.QProcessCallback;
import com.kingsrook.qqq.backend.core.actions.reporting.RecordPipe;
import com.kingsrook.qqq.backend.core.context.QContext;
import com.kingsrook.qqq.backend.core.exceptions.QException;
import com.kingsrook.qqq.backend.core.exceptions.QPermissionDeniedException;
import com.kingsrook.qqq.backend.core.model.actions.AbstractActionInput;
import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepInput;
import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepOutput;
import com.kingsrook.qqq.backend.core.model.actions.tables.count.CountInput;
import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryInput;
import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference;
import com.kingsrook.qqq.backend.core.model.metadata.permissions.MetaDataWithPermissionRules;
import com.kingsrook.qqq.backend.core.processes.implementations.etl.streamedwithfrontend.StreamedETLWithFrontendProcess;
import org.junit.jupiter.api.AfterEach;
import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.junit.jupiter.api.Assertions.assertTrue;
/** Exercise the actual frozen extract and record pipe, without relying on later Transform checks. */
class PrintingExtractTest
{
/** Each test owns its native context. */
@AfterEach
void clearContext()
{
QContext.clear();
}
/** A table-specific denial precedes both preview count and any streamed row. */
@Test
void tablePolicyBlocksCountAndExtractEvenWithPermissionWeakeningCallback() throws Exception
{
var fixture = PrintingProcessesTest.fixture();
fixture.instance().getTable(PrintingTables.DEVICE).getPermissionRules().withCustomPermissionChecker(new QCodeReference(DenyRead.class));
RunBackendStepInput input = input(fixture.device());
AtomicBoolean callback = new AtomicBoolean();
input.setCallback(new QProcessCallback()
{
@Override
public void customizeInputPreQuery(RunBackendStepInput step, QueryInput query)
{
callback.set(true);
query.setPermissionEnforcement(PermissionEnforcement.DEFAULT);
}
});
PrintingExtract extract = prepare(input);
assertThrows(QPermissionDeniedException.class, () -> extract.doCount(input));
assertThrows(QPermissionDeniedException.class, () -> extract.run(input, new RunBackendStepOutput()));
assertTrue(callback.get());
assertEquals(0, extract.getRecordPipe().countAvailableRecords());
}
/** Tenant row locks remain authoritative for both selected IDs and query selection. */
@Test
void nativeSelectionsCountAndStreamOnlyCurrentTenantRows() throws Exception
{
var fixture = PrintingProcessesTest.fixture();
RunBackendStepInput selected = input(fixture.device() + "," + fixture.foreignDevice());
PrintingExtract extract = prepare(selected);
assertEquals(1, extract.doCount(selected));
extract.run(selected, new RunBackendStepOutput());
assertEquals(List.of(fixture.device()), extract.getRecordPipe().consumeAvailableRecords().stream().map(row -> row.getValueString("id")).toList());
RunBackendStepInput query = input(null);
query.addValue(StreamedETLWithFrontendProcess.FIELD_DEFAULT_QUERY_FILTER, "{}");
PrintingExtract all = prepare(query);
assertEquals(2, all.doCount(query));
all.run(query, new RunBackendStepOutput());
assertEquals(Set.of(fixture.device(), fixture.otherDevice()), all.getRecordPipe().consumeAvailableRecords().stream().map(row -> row.getValueString("id")).collect(Collectors.toSet()));
QContext.getQSession().setPermissions(Set.of());
assertThrows(QPermissionDeniedException.class, () -> all.doCount(query));
assertThrows(QPermissionDeniedException.class, () -> all.run(query, new RunBackendStepOutput()));
}
/** Every printing streamed-selection process uses the enforced wrapper. */
@Test
void allPrintingSelectionRegistrationsUseEnforcedExtraction() throws Exception
{
var fixture = PrintingProcessesTest.fixture();
int checked = 0;
for(var process : fixture.instance().getProcesses().values())
{
var field = process.getInputField(StreamedETLWithFrontendProcess.FIELD_EXTRACT_CODE);
if(field.isPresent() && field.get().getDefaultValue() instanceof QCodeReference code)
{
assertEquals(PrintingExtract.class.getName(), code.getName());
checked++;
}
}
assertEquals(14, checked);
}
/** Real native input fields drive standard selected-ID or filter extraction. */
private static RunBackendStepInput input(String ids)
{
RunBackendStepInput input = new RunBackendStepInput().withProcessName(PrintingDeviceProcesses.Action.PAUSE.process)
.addValue(StreamedETLWithFrontendProcess.FIELD_SOURCE_TABLE, PrintingTables.DEVICE);
if(ids != null)
{
input.addValue("recordIds", ids);
}
return (input);
}
/** Bounded in-memory pipe removes asynchronous worker timing from the authorization assertion. */
private static PrintingExtract prepare(RunBackendStepInput input) throws QException
{
PrintingExtract extract = new PrintingExtract();
extract.preRun(input, new RunBackendStepOutput());
extract.setRecordPipe(new RecordPipe(20));
return (extract);
}
/** Permission varies by table independently of the user's process-administration grant. */
public static class DenyRead extends PrintingReadPermission
{
@Override
public void checkPermissionsThrowing(AbstractActionInput input, MetaDataWithPermissionRules metadata) throws QPermissionDeniedException
{
super.checkPermissionsThrowing(input, metadata);
if(input instanceof QueryInput || input instanceof CountInput)
{
throw new QPermissionDeniedException("Synthetic table read denied");
}
}
}
}
@@ -98,6 +98,48 @@ class PrintingHomeTest
/***************************************************************************
** Control polls prove liveness; explicit administrative intent stays visible.
***************************************************************************/
@Test
void controlConnectionAndPendingCommandsRemainVisible() throws Exception
{
DriverDataSource source = source();
QInstance instance = instance(source);
seed(source, "tenant-a");
QContext.init(instance, viewer("tenant-a", true));
try
{
PrintingService service = new PrintingService(source, "tenant-a");
String device = service.devices().getJSONObject(0).getString("deviceId");
service.deviceControlPoll(device, new JSONObject().put("controlVersion", 1).put("agentVersion", "test")
.put("capabilities", new JSONArray(List.of("REFRESH_INVENTORY"))).put("lastAppliedRevision", 0));
assertEquals(0, ((StatisticsData) render(instance, "printingHomeOffline")).getCount());
service.deviceAction(device, new JSONObject().put("requestId", UUID.randomUUID().toString()).put("issuedAt", java.time.Instant.now().toString())
.put("action", "REFRESH_INVENTORY"), "viewer");
assertEquals(1, ((StatisticsData) render(instance, "printingHomeControls")).getCount());
assertTrue(JsonUtils.toJson(render(instance, "printingHomeAttention")).contains("REFRESH_INVENTORY"));
try(Connection connection = source.getConnection(); PreparedStatement expired = connection.prepareStatement("UPDATE printing_device_command SET expires_at=? WHERE device_id=?"))
{
expired.setString(1, java.time.Instant.now().minusSeconds(1).toString());
expired.setString(2, device);
expired.executeUpdate();
}
assertEquals(0, ((StatisticsData) render(instance, "printingHomeControls")).getCount());
assertTrue(JsonUtils.toJson(render(instance, "printingHomeAttention")).contains("EXPIRED"));
service.deviceAction(device, new JSONObject().put("requestId", UUID.randomUUID().toString()).put("issuedAt", java.time.Instant.now().toString())
.put("action", "DISCONNECT"), "viewer");
assertEquals(1, ((StatisticsData) render(instance, "printingHomeOffline")).getCount());
assertTrue(JsonUtils.toJson(render(instance, "printingHomeAttention")).contains("Administratively disconnected"));
}
finally
{
QContext.clear();
}
}
/***************************************************************************
** Empty state guides setup; an unprivileged or unscoped caller gets no data.
***************************************************************************/
@@ -0,0 +1,268 @@
/*
* QQQ - Low-code Application Framework for Engineers.
* Copyright (C) 2021-2025. Kingsrook, LLC
* 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
* contact@kingsrook.com
* https://github.com/Kingsrook/
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.kingsrook.qbits.printing;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.nio.file.Path;
import java.util.Base64;
import java.util.List;
import java.util.Map;
import java.util.concurrent.atomic.AtomicReference;
import com.kingsrook.qqq.backend.core.actions.tables.QueryAction;
import com.kingsrook.qqq.backend.core.context.QContext;
import com.kingsrook.qqq.backend.core.exceptions.QAuthenticationException;
import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryInput;
import com.kingsrook.qqq.backend.core.modules.authentication.implementations.TableBasedAuthenticationModule;
import com.kingsrook.qqq.middleware.javalin.QApplicationLauncher;
import com.kingsrook.qqq.middleware.javalin.QApplicationLauncherConfig;
import io.javalin.Javalin;
import org.json.JSONArray;
import org.json.JSONObject;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.io.TempDir;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.junit.jupiter.api.Assertions.assertTrue;
/*******************************************************************************
** Isolated durable H2 and ephemeral HTTP prove native auth and shared records.
*******************************************************************************/
class PrintingLocalHostTest
{
private static final String TOKEN = "synthetic-admin-token-for-isolated-tests";
private static final String PASSWORD = "synthetic-login-password-12345";
@TempDir
Path directory;
/***************************************************************************
** Real native table auth, origin protection, scheduler and transport coexist.
***************************************************************************/
@Test
void nativeHostPreservesPairedDataAndRequiresVerifiedSameOriginAdministration() throws Exception
{
exerciseHost("legacy", "");
}
/***************************************************************************
** Explicit case-preserving H2 hosts retain their existing physical names too.
***************************************************************************/
@Test
void nativeHostSupportsCasePreservingDatabase() throws Exception
{
exerciseHost("case-preserving", ";DATABASE_TO_UPPER=FALSE");
}
/***************************************************************************
** The same acceptance checks apply to both supported H2 naming conventions.
***************************************************************************/
private void exerciseHost(String file, String options) throws Exception
{
String jdbc = "jdbc:h2:file:" + directory.resolve(file).toString().replace('\\', '/') + options;
DriverDataSource source = new DriverDataSource(jdbc, "sa", "");
PrintingService paired = new PrintingService(source, "demo");
paired.initialize();
JSONObject enrolled = paired.enroll(paired.createEnrollment("legacy-facility", "Synthetic station").put("deviceName", "Synthetic station").put("agentVersion", "test"));
String device = enrolled.getString("deviceId");
paired.inventory(device, new JSONArray().put(new JSONObject().put("printerId", "queue").put("name", "Synthetic laser").put("formats", new JSONArray(List.of("PDF")))));
PrintingLocalHost host = new PrintingLocalHost(settings(jdbc, PASSWORD));
AtomicReference<Javalin> javalin = new AtomicReference<>();
QApplicationLauncher launcher = QApplicationLauncher.run(host, new QApplicationLauncherConfig().withRegisterShutdownHook(false)
.withServerCustomizer(server ->
{
host.configure(server, false);
server.withJavalinConfigurationCustomizer(javalin::set);
}));
String base = "http://127.0.0.1:" + javalin.get().port();
try(HttpClient client = HttpClient.newHttpClient())
{
assertTrue(launcher.getStartedServiceNames().contains(QApplicationLauncher.SCHEDULE_MANAGER_SERVICE_NAME));
assertEquals("0 */5 * * * ?", launcher.getQInstance().getProcess(PrintingRetentionProcesses.SCHEDULED).getSchedule().getCronExpression());
assertRejectedHost(javalin.get().port());
assertEquals(401, send(client, base, "/qqq/v1/table/printing_device/count", null, null, null).statusCode());
assertEquals(401, send(client, base, "/qqq/v1/manageSession", basic("operator", "wrong"), null, null).statusCode());
HttpResponse<String> login = send(client, base, "/qqq/v1/manageSession", basic("operator", PASSWORD), null, base);
assertEquals(200, login.statusCode(), login.body());
String cookie = login.headers().allValues("set-cookie").stream().filter(value -> value.startsWith("sessionUUID=")).findFirst().orElseThrow().split(";", 2)[0];
String sessionId = cookie.substring("sessionUUID=".length());
assertTrue(login.headers().allValues("set-cookie").stream().anyMatch(value -> value.toLowerCase(java.util.Locale.ROOT).contains("httponly")));
assertFalse(login.body().contains("passwordHash"));
HttpResponse<String> count = send(client, base, "/qqq/v1/table/printing_device/count", null, cookie, base);
assertEquals(200, count.statusCode(), count.body());
assertEquals(1, new JSONObject(count.body()).getInt("count"));
assertEquals(403, send(client, base, "/qqq/v1/table/printing_device/count", null, cookie, "https://unrelated.invalid").statusCode());
assertEquals(403, send(client, base, "/qqq/v1/table/printing_device/count", null, cookie, null).statusCode());
assertEquals(403, send(client, base, "/qqq/v1/manageSession", basic("operator", PASSWORD), null, "null").statusCode());
assertEquals(403, send(client, base, "/qqq/v1/table/printing_admin_user/count", null, cookie, base).statusCode());
HttpResponse<String> transport = client.send(HttpRequest.newBuilder(URI.create(base + "/printing/v1/admin/devices")).header("Authorization", "Bearer " + TOKEN).GET().build(), HttpResponse.BodyHandlers.ofString());
assertEquals(200, transport.statusCode());
assertEquals(device, new JSONObject(transport.body()).getJSONArray("devices").getJSONObject(0).getString("deviceId"));
QContext.init(launcher.getQInstance(), null);
var session = new PrintingLocalAuthentication().createSession(launcher.getQInstance(), Map.of("sessionId", sessionId));
assertTrue(session.hasPermission("printing_admin"));
QContext.init(launcher.getQInstance(), session);
assertEquals(device, new QueryAction().execute(new QueryInput().withTableName(PrintingTables.DEVICE)).getRecords().getFirst().getValueString("id"));
assertEquals("legacy-facility", new QueryAction().execute(new QueryInput().withTableName(PrintingTables.DEVICE)).getRecords().getFirst().getValueString("facility_id"));
QContext.clear();
assertEquals(200, send(client, base, "/qqq/v1/logout", null, cookie, base).statusCode());
assertEquals(401, send(client, base, "/qqq/v1/table/printing_device/count", null, cookie, base).statusCode());
var heartbeat = HttpRequest.newBuilder(URI.create(base + "/printing/v1/device/heartbeat"))
.header("Authorization", "Bearer " + enrolled.getString("deviceToken")).header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(new JSONObject().put("agentVersion", "test").toString())).build();
assertEquals(200, client.send(heartbeat, HttpResponse.BodyHandlers.discarding()).statusCode());
assertEquals(device, paired.authenticate(enrolled.getString("deviceToken")));
assertEquals(0, paired.jobs().length());
verifyUnprivilegedAccountRejected(source, launcher);
}
finally
{
QContext.clear();
launcher.stop();
}
String originalHash = passwordHash(source);
new PrintingLocalHost(settings(jdbc, "a-different-password-must-never-reset"));
assertEquals(originalHash, passwordHash(source));
assertThrows(IllegalArgumentException.class, () -> new PrintingLocalHost(new PrintingLocalSettings(jdbc, "sa", "", "demo", 0, TOKEN, "different-user", PASSWORD)));
}
/***************************************************************************
** A hostile DNS name cannot turn a loopback listener into a trusted origin.
***************************************************************************/
private static void assertRejectedHost(int port) throws Exception
{
try(var socket = new java.net.Socket("127.0.0.1", port))
{
socket.setSoTimeout(5000);
socket.getOutputStream().write("GET / HTTP/1.1\r\nHost: unrelated.invalid\r\nConnection: close\r\n\r\n".getBytes(StandardCharsets.US_ASCII));
var reader = new java.io.BufferedReader(new java.io.InputStreamReader(socket.getInputStream(), StandardCharsets.US_ASCII));
assertTrue(reader.readLine().contains("403"));
}
}
/***************************************************************************
** A valid password alone never grants printing permissions to another user.
***************************************************************************/
private static void verifyUnprivilegedAccountRejected(DriverDataSource source, QApplicationLauncher launcher) throws Exception
{
try(var connection = source.getConnection(); var insert = connection.prepareStatement("INSERT INTO printing_admin_user(username,passwordHash,fullName) VALUES (?,?,?)"))
{
insert.setString(1, "viewer");
insert.setString(2, TableBasedAuthenticationModule.PasswordHasher.createHashedPassword(PASSWORD));
insert.setString(3, "Synthetic viewer");
insert.executeUpdate();
}
QContext.init(launcher.getQInstance(), null);
var verified = new TableBasedAuthenticationModule().createSession(launcher.getQInstance(), Map.of(TableBasedAuthenticationModule.BASIC_AUTH_KEY, basic("viewer", PASSWORD).substring(6)));
assertEquals("viewer", verified.getUser().getIdReference());
assertThrows(QAuthenticationException.class, () -> new PrintingLocalAuthentication().createSession(launcher.getQInstance(), Map.of("sessionId", verified.getUuid())));
QContext.clear();
}
/***************************************************************************
** Missing bootstrap credentials fail closed; no environment secret is echoed.
***************************************************************************/
@Test
void explicitConfigurationAndBootstrapAreRequired() throws Exception
{
assertThrows(IllegalArgumentException.class, () -> PrintingLocalSettings.fromEnvironment(Map.of()));
assertThrows(IllegalArgumentException.class, () -> PrintingLocalSettings.fromEnvironment(Map.of("QQQ_PRINT_JDBC_URL", "jdbc:h2:mem:wrong")));
String jdbc = "jdbc:h2:file:" + directory.resolve("empty").toString().replace('\\', '/');
assertThrows(IllegalArgumentException.class, () -> new PrintingLocalHost(settings(jdbc, null)));
assertFalse(settings(jdbc, PASSWORD).toString().contains(PASSWORD));
assertFalse(settings(jdbc, PASSWORD).toString().contains(TOKEN));
}
/***************************************************************************
** One synthetic account and ephemeral port, never physical printer access.
***************************************************************************/
private static PrintingLocalSettings settings(String jdbc, String password)
{
return (new PrintingLocalSettings(jdbc, "sa", "", "demo", 0, TOKEN, "operator", password));
}
/***************************************************************************
** Read only the synthetic hash to prove startup never changes it.
***************************************************************************/
private static String passwordHash(DriverDataSource source) throws Exception
{
try(var connection = source.getConnection(); var statement = connection.createStatement(); var rows = statement.executeQuery("SELECT passwordHash FROM printing_admin_user WHERE username='operator'"))
{
rows.next();
return (rows.getString(1));
}
}
/***************************************************************************
** Test credentials stay in request headers and never command-line arguments.
***************************************************************************/
private static String basic(String user, String password)
{
return ("Basic " + Base64.getEncoder().encodeToString((user + ":" + password).getBytes(StandardCharsets.UTF_8)));
}
/***************************************************************************
** Native routes use JSON POST and explicit cookies/origin in these fixtures.
***************************************************************************/
private static HttpResponse<String> send(HttpClient client, String base, String path, String authorization, String cookie, String origin) throws Exception
{
var request = HttpRequest.newBuilder(URI.create(base + path)).header("Content-Type", "application/json");
if(authorization != null)
{
request.header("Authorization", authorization);
}
if(cookie != null)
{
request.header("Cookie", cookie);
}
if(origin != null)
{
request.header("Origin", origin);
}
return (client.send(request.POST(HttpRequest.BodyPublishers.ofString("{}")).build(), HttpResponse.BodyHandlers.ofString()));
}
}
@@ -0,0 +1,172 @@
/*
* QQQ - Low-code Application Framework for Engineers.
* Copyright (C) 2021-2025. Kingsrook, LLC
* 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
* contact@kingsrook.com
* https://github.com/Kingsrook/
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.kingsrook.qbits.printing;
import java.time.Instant;
import java.util.Base64;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.UUID;
import java.util.concurrent.Callable;
import java.util.concurrent.Executors;
import org.json.JSONArray;
import org.json.JSONObject;
import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertNotEquals;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.junit.jupiter.api.Assertions.assertTrue;
/*******************************************************************************
** Isolated maintenance and concurrency regressions never use live print state.
*******************************************************************************/
class PrintingMaintenanceTest
{
/***************************************************************************
** Retention is bounded, tenant-scoped and preserves replay protection.
***************************************************************************/
@Test
void retentionPurgesOnlyOldSuccessAndKeepsIdempotencyReceipts() throws Exception
{
DriverDataSource source = source();
PrintingService service = new PrintingService(source, "tenant-a");
service.initialize();
String device = enroll(service);
Map<String, JSONObject> submitted = new HashMap<>();
for(String status : List.of("QUEUED", "CLAIMED", "RECEIVED", "SUBMITTING", "SPOOLED", "SPOOLER_COMPLETED", "FAILED", "OUTCOME_UNKNOWN"))
{
JSONObject request = request(device, status);
String id = service.submit(request).getString("jobId");
submitted.put(id, request);
try(var connection = source.getConnection(); var statement = connection.prepareStatement("UPDATE printing_job SET status=?,completed_at=? WHERE id=?"))
{
statement.setString(1, status);
statement.setString(2, Instant.now().minusSeconds(40 * 86400L).toString());
statement.setString(3, id);
statement.executeUpdate();
}
}
assertEquals(0, service.purgeCompletedContent(new PrintingQBitConfig().getRetentionPolicy()));
PrintingRetentionPolicy enabled = new PrintingRetentionPolicy(true, 30, 1);
PrintingService other = new PrintingService(source, "tenant-b");
assertEquals(0, other.purgeCompletedContent(enabled));
assertEquals(1, service.purgeCompletedContent(enabled));
String purged;
try(var connection = source.getConnection(); var statement = connection.prepareStatement("SELECT id FROM printing_job WHERE content_available=0"); var rows = statement.executeQuery())
{
assertTrue(rows.next());
purged = rows.getString(1);
}
assertEquals(purged, service.submit(submitted.get(purged)).getString("jobId"));
assertEquals(410, assertThrows(PrintingException.class, () -> service.content(device, purged)).getStatus());
assertEquals(410, assertThrows(PrintingException.class, () -> service.retry(device, purged, new JSONObject().put("requestId", "retry").put("confirmDuplicateRisk", true))).getStatus());
assertEquals(1, service.purgeCompletedContent(enabled));
assertEquals(0, service.purgeCompletedContent(enabled));
assertEquals(8, service.jobs().length());
assertThrows(IllegalArgumentException.class, () -> new PrintingRetentionPolicy(true, 0, 100));
assertThrows(IllegalArgumentException.class, () -> new PrintingRetentionPolicy(true, 30, 201));
}
/***************************************************************************
** Concurrent enrollment consumes one code; matching submissions deduplicate.
***************************************************************************/
@Test
void concurrentEnrollmentAndSubmissionPreserveSingleOwnership() throws Exception
{
PrintingService service = new PrintingService(source(), "tenant-a");
service.initialize();
JSONObject code = service.createEnrollment("warehouse", "station");
Callable<String> enroll = () ->
{
try
{
return service.enroll(new JSONObject(code.toString()).put("deviceName", "station").put("agentVersion", "test")).getString("deviceId");
}
catch(PrintingException exception)
{
assertEquals(401, exception.getStatus());
return "rejected";
}
};
try(var pool = Executors.newFixedThreadPool(2))
{
var outcomes = pool.invokeAll(List.of(enroll, enroll));
assertNotEquals(outcomes.get(0).get(), outcomes.get(1).get());
assertEquals(1, service.devices().length());
String device = service.devices().getJSONObject(0).getString("deviceId");
configure(service, device);
Callable<String> submit = () -> service.submit(request(device, "same-key")).getString("jobId");
var jobs = pool.invokeAll(List.of(submit, submit));
assertEquals(jobs.get(0).get(), jobs.get(1).get());
assertEquals(1, service.jobs().length());
}
}
/***************************************************************************
** In-memory data only; no production credentials or printer connections.
***************************************************************************/
private static DriverDataSource source()
{
return (new DriverDataSource("jdbc:h2:mem:audit-" + UUID.randomUUID() + ";DB_CLOSE_DELAY=-1", "sa", ""));
}
/***************************************************************************
** Register an isolated synthetic queue.
***************************************************************************/
private static String enroll(PrintingService service) throws Exception
{
String device = service.enroll(service.createEnrollment("warehouse", "station").put("deviceName", "station").put("agentVersion", "test")).getString("deviceId");
configure(service, device);
return (device);
}
/***************************************************************************
** Approval is explicit even in the test fixture.
***************************************************************************/
private static void configure(PrintingService service, String device) throws Exception
{
service.inventory(device, new JSONArray().put(new JSONObject().put("printerId", "queue").put("name", "Synthetic").put("formats", new JSONArray(List.of("ZPL")))));
service.enablePrinter(device, "queue", true);
}
/***************************************************************************
** A minimal synthetic document that is never dispatched to Windows.
***************************************************************************/
private static JSONObject request(String device, String key)
{
return (new JSONObject().put("deviceId", device).put("printerId", "queue").put("title", "Synthetic").put("format", "ZPL")
.put("contentBase64", Base64.getEncoder().encodeToString("^XA^XZ".getBytes(java.nio.charset.StandardCharsets.US_ASCII))).put("idempotencyKey", key));
}
}
@@ -21,6 +21,7 @@
package com.kingsrook.qbits.printing;
import java.nio.file.Path;
import java.sql.Connection;
import java.sql.PreparedStatement;
import java.sql.SQLException;
@@ -30,8 +31,10 @@ import java.util.UUID;
import org.json.JSONArray;
import org.json.JSONObject;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.io.TempDir;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.junit.jupiter.api.Assertions.assertTrue;
/*******************************************************************************
@@ -100,6 +103,42 @@ class PrintingMigrationTest
/***************************************************************************
** File-backed state survives last-connection closure without reinitialization.
** This checks cold reopen durability, not reproduction of every old-driver file.
***************************************************************************/
@Test
void preservesAuditSchemaAndSettingsAcrossColdReopens(@TempDir Path directory) throws Exception
{
String url = "jdbc:h2:file:" + directory.resolve("cold-reopen").toAbsolutePath();
DriverDataSource source = new DriverDataSource(url, "sa", "");
PrintingService service = new PrintingService(source, "tenant-a");
service.initialize();
assertEquals(365, service.getRetentionSettings().getInt("days"));
service.saveRetentionSettings(400, false);
JSONObject device = service.enroll(service.createEnrollment("default", "Synthetic station")
.put("deviceName", "Synthetic station").put("agentVersion", "test"));
for(int restart = 0; restart < 3; restart++)
{
DriverDataSource reopened = new DriverDataSource(url + ";IFEXISTS=TRUE", "sa", "");
PrintingService restarted = new PrintingService(reopened, "tenant-a");
assertEquals(400, restarted.getRetentionSettings().getInt("days"));
assertEquals(device.getString("deviceId"), restarted.authenticate(device.getString("deviceToken")));
try(Connection connection = reopened.getConnection())
{
for(String table : List.of("printing_settings", "printing_document_orphan", "printing_resource_usage", "printing_admission_event"))
{
try(PreparedStatement statement = connection.prepareStatement("SELECT COUNT(*) FROM " + table); java.sql.ResultSet rows = statement.executeQuery())
{
assertTrue(rows.next());
}
}
}
}
}
/***************************************************************************
** Mixed namespaces are not silently merged or discarded.
***************************************************************************/
@@ -0,0 +1,295 @@
/*
* QQQ - Low-code Application Framework for Engineers.
* Copyright (C) 2021-2025. Kingsrook, LLC
* 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
* contact@kingsrook.com
* https://github.com/Kingsrook/
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.kingsrook.qbits.printing;
import java.time.Instant;
import java.util.Base64;
import java.util.List;
import java.util.Map;
import java.util.UUID;
import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.CountDownLatch;
import java.util.concurrent.Executors;
import java.util.concurrent.TimeUnit;
import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
import org.h2.jdbcx.JdbcConnectionPool;
import org.json.JSONArray;
import org.json.JSONObject;
import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertNotEquals;
import static org.junit.jupiter.api.Assertions.assertNull;
import static org.junit.jupiter.api.Assertions.assertTrue;
/*******************************************************************************
** A bounded real JDBC pool exposes nested-acquisition deadlocks hidden by unpooled fixtures.
*******************************************************************************/
class PrintingPoolTest
{
/***************************************************************************
** A second scheduler invocation skips promptly while the first is deleting an object.
***************************************************************************/
@Test
void cleanupLeasePreventsOverlappingStorageDeletionAndReleasesAfterSuccess() throws Exception
{
JdbcConnectionPool pool = JdbcConnectionPool.create("jdbc:h2:mem:printing-lease-" + UUID.randomUUID() + ";DB_CLOSE_DELAY=-1", "sa", "");
pool.setMaxConnections(2);
pool.setLoginTimeout(2);
BlockingDocuments documents = new BlockingDocuments();
try
{
PrintingService service = new PrintingService(pool, "tenant-a");
service.initialize();
service.configureStorage(documents, "printing_documents");
String job = service.submit(request(enroll(service, "station"), "old")).getString("jobId");
try(var connection = pool.getConnection(); var statement = connection.prepareStatement("UPDATE printing_job SET status='SPOOLED',completed_at=? WHERE id=?"))
{
statement.setString(1, Instant.now().minusSeconds(400L * 86400).toString());
statement.setString(2, job);
statement.executeUpdate();
}
try(var executor = Executors.newFixedThreadPool(2))
{
var active = executor.submit(service::runRetention);
try
{
assertTrue(documents.entered.await(5, TimeUnit.SECONDS));
assertEquals(0, executor.submit(service::runRetention).get(3, TimeUnit.SECONDS));
assertEquals(1, documents.deletions.get());
}
finally
{
documents.release.countDown();
}
assertEquals(1, active.get(5, TimeUnit.SECONDS));
}
try(var connection = pool.getConnection(); var statement = connection.prepareStatement("SELECT lease_token,last_run_count FROM printing_settings WHERE tenant_id='tenant-a'"); var rows = statement.executeQuery())
{
assertTrue(rows.next());
assertNull(rows.getString("lease_token"));
assertEquals(1, rows.getInt("last_run_count"));
}
assertEquals(0, service.runRetention());
}
finally
{
documents.release.countDown();
pool.dispose();
}
}
/***************************************************************************
** A single connection must suffice even for the durable external-upload intent.
***************************************************************************/
@Test
void singleConnectionSupportsConcurrentSubmissionsAndMaintenance() throws Exception
{
verifyBoundedPool(1);
}
/***************************************************************************
** Two concurrent devices must not each hold one connection while waiting for another.
***************************************************************************/
@Test
void twoConnectionsSupportConcurrentSubmissionsAndMaintenance() throws Exception
{
verifyBoundedPool(2);
}
/***************************************************************************
** Exercise external-storage submission and cleanup concurrently, without network or printing.
***************************************************************************/
private static void verifyBoundedPool(int capacity) throws Exception
{
JdbcConnectionPool pool = JdbcConnectionPool.create("jdbc:h2:mem:printing-pool-" + UUID.randomUUID() + ";DB_CLOSE_DELAY=-1", "sa", "");
pool.setMaxConnections(capacity);
pool.setLoginTimeout(2);
try
{
PrintingService service = new PrintingService(pool, "tenant-a");
service.initialize();
MemoryDocuments documents = new MemoryDocuments();
service.configureStorage(documents, "printing_documents");
String first = enroll(service, "first");
String second = enroll(service, "second");
String old = service.submit(request(first, "old")).getString("jobId");
try(var connection = pool.getConnection(); var statement = connection.prepareStatement("UPDATE printing_job SET status='SPOOLED',completed_at=? WHERE id=?"))
{
statement.setString(1, Instant.now().minusSeconds(400L * 86400).toString());
statement.setString(2, old);
assertEquals(1, statement.executeUpdate());
}
CountDownLatch start = new CountDownLatch(1);
try(var executor = Executors.newFixedThreadPool(3))
{
var a = executor.submit(() ->
{
start.await();
return service.submit(request(first, "new-a")).getString("jobId");
});
var b = executor.submit(() ->
{
start.await();
return service.submit(request(second, "new-b")).getString("jobId");
});
var cleanup = executor.submit(() ->
{
start.await();
return service.runRetention();
});
start.countDown();
assertNotEquals(a.get(10, TimeUnit.SECONDS), b.get(10, TimeUnit.SECONDS));
assertEquals(1, cleanup.get(10, TimeUnit.SECONDS));
}
assertEquals(3, service.jobs().length());
assertEquals(2, documents.objects.size());
assertEquals(0, service.runRetention());
assertEquals(0, pool.getActiveConnections());
}
finally
{
pool.dispose();
}
}
/***************************************************************************
** Synthetic devices have independent database locks and explicitly approved queues.
***************************************************************************/
private static String enroll(PrintingService service, String name) throws Exception
{
String device = service.enroll(service.createEnrollment("warehouse", name).put("deviceName", name).put("agentVersion", "test")).getString("deviceId");
service.inventory(device, new JSONArray().put(new JSONObject().put("printerId", "queue").put("name", "Synthetic").put("formats", new JSONArray(List.of("ZPL")))));
service.enablePrinter(device, "queue", true);
return (device);
}
/***************************************************************************
** Valid synthetic bytes exercise storage writes but never reach a physical printer.
***************************************************************************/
private static JSONObject request(String device, String key)
{
return (new JSONObject().put("deviceId", device).put("printerId", "queue").put("title", "Pool regression").put("format", "ZPL")
.put("contentBase64", Base64.getEncoder().encodeToString(new byte[] { 1 })).put("idempotencyKey", key));
}
/***************************************************************************
** Only document I/O is fake; SQL pooling, transactions, intents and leases are real.
***************************************************************************/
private static class MemoryDocuments extends PrintingDocumentStorage
{
private final Map<String, byte[]> objects = new ConcurrentHashMap<>();
/***********************************************************************
** Bind the same tenant prefix used by production reference verification.
***********************************************************************/
MemoryDocuments()
{
super(new QInstance(), "tenant-a", true);
}
/***********************************************************************
** This test does not exercise S3 metadata validation; separate adapter tests do.
***********************************************************************/
@Override
public String binding(String table)
{
return ("fixture-binding");
}
/***********************************************************************
** Retain exact bytes by the generated object reference.
***********************************************************************/
@Override
public void put(String table, String reference, String format, byte[] content)
{
assertTrue(reference.startsWith(prefix()));
objects.put(reference, content.clone());
}
/***********************************************************************
** Deletion is idempotent, matching the external-storage contract.
***********************************************************************/
@Override
public void delete(String table, String reference)
{
objects.remove(reference);
}
}
/***************************************************************************
** Hold one real cleanup transaction at the external-storage boundary.
***************************************************************************/
private static class BlockingDocuments extends MemoryDocuments
{
private final CountDownLatch entered = new CountDownLatch(1);
private final CountDownLatch release = new CountDownLatch(1);
private final java.util.concurrent.atomic.AtomicInteger deletions = new java.util.concurrent.atomic.AtomicInteger();
/***********************************************************************
** A second deletion would reveal an ineffective cross-worker lease.
***********************************************************************/
@Override
public void delete(String table, String reference)
{
deletions.incrementAndGet();
entered.countDown();
try
{
if(!release.await(10, TimeUnit.SECONDS))
{
throw new IllegalStateException("Fixture deletion was not released");
}
}
catch(InterruptedException exception)
{
Thread.currentThread().interrupt();
throw new IllegalStateException(exception);
}
super.delete(table, reference);
}
}
}
@@ -47,6 +47,7 @@ import org.json.JSONArray;
import org.json.JSONObject;
import org.junit.jupiter.api.AfterEach;
import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.assertArrayEquals;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertThrows;
@@ -58,6 +59,221 @@ import static org.junit.jupiter.api.Assertions.assertTrue;
*******************************************************************************/
class PrintingProcessesTest
{
/***************************************************************************
** Standalone enrollment has a named default instead of accepting arbitrary raw IDs.
***************************************************************************/
@Test
void standaloneFacilitySelectorRejectsForgedValues() throws Exception
{
Fixture fixture = fixture();
QFieldMetaData field = ((QFrontendStepMetaData) fixture.instance().getProcess("printingEnrollDevice").getStep("details")).getFormField("facilityId");
assertEquals("printing_facility", field.getPossibleValueSourceName());
assertEquals("default", field.getDefaultValue());
assertEquals(field.getPossibleValueSourceName(), fixture.instance().getTable(PrintingTables.DEVICE).getField("facility_id").getPossibleValueSourceName());
var choices = new SearchPossibleValueSourceAction().execute(new SearchPossibleValueSourceInput().withPossibleValueSourceName(field.getPossibleValueSourceName()));
assertEquals(1, choices.getResults().size());
assertEquals("Default facility", choices.getResults().getFirst().getLabel());
assertEquals("default", PrintingFacilities.validate("default"));
RunBackendStepInput forged = new RunBackendStepInput().withProcessName("printingEnrollDevice")
.addValue("facilityId", "invented-id").addValue("deviceName", "station");
assertThrows(QException.class, () -> new PrintingProcesses().run(forged, new RunBackendStepOutput()));
assertThrows(QException.class, () -> PrintingFacilities.validate(null));
assertThrows(QException.class, () -> PrintingFacilities.validate(""));
assertThrows(QException.class, () -> PrintingFacilities.register(fixture.instance(), new PrintingQBitConfig().withFacilityPossibleValueSourceName("missing_source")));
}
/***************************************************************************
** A forged selection cannot bypass the host source's real tenant record lock.
***************************************************************************/
@Test
void configuredFacilitySelectorHonorsRecordSecurityAtEnrollment() throws Exception
{
Fixture fixture = fixture("host_facilities");
assertEquals("host_facilities", PrintingFacilities.field(fixture.instance()).getPossibleValueSourceName());
assertEquals("host_facilities", fixture.instance().getTable(PrintingTables.DEVICE).getField("facility_id").getPossibleValueSourceName());
assertEquals(fixture.device(), PrintingFacilities.validate(fixture.device()));
RunBackendStepInput input = new RunBackendStepInput().withProcessName("printingEnrollDevice")
.addValue("facilityId", fixture.foreignDevice()).addValue("deviceName", "station");
RunBackendStepOutput prepared = new RunBackendStepOutput();
new PrintingProcesses.PrepareEnrollment().run(input, prepared);
input.addValue("printingEnrollmentCode", prepared.getValueString("printingEnrollmentCode"))
.addValue("printingEnrollmentExpires", prepared.getValueString("printingEnrollmentExpires"));
assertThrows(QException.class, () -> new PrintingProcesses().run(input, new RunBackendStepOutput()));
input.addValue("facilityId", fixture.device());
RunBackendStepOutput accepted = new RunBackendStepOutput();
new PrintingProcesses().run(input, accepted);
assertTrue(accepted.getValueString("result").startsWith("Enrollment code:"));
}
/***************************************************************************
** The production QQQ host extension point mounts routes with host auth.
***************************************************************************/
@Test
void productionApplicationHostRegistersPrintingRoutesAndPreservesAdminGate() throws Exception
{
Fixture fixture = fixture();
var application = new com.kingsrook.qqq.backend.core.instances.AbstractQQQApplication()
{
@Override
public QInstance defineQInstance()
{
return (fixture.instance());
}
};
var javalin = new java.util.concurrent.atomic.AtomicReference<io.javalin.Javalin>();
var server = new com.kingsrook.qqq.middleware.javalin.QApplicationJavalinServer(application)
.withPort(0).withServeFrontendNext(false).withServeFrontendMaterialDashboard(false)
.withJavalinConfigCustomizer(config -> config.jetty.host = "127.0.0.1")
.withJavalinConfigurationCustomizer(javalin::set)
.withAdditionalRouteProviders(List.of(new PrintingRoutes(fixture.service(), context -> "allowed".equals(context.header("X-Test-Admin")))));
try(java.net.http.HttpClient client = java.net.http.HttpClient.newHttpClient())
{
server.start();
java.net.URI url = java.net.URI.create("http://127.0.0.1:" + javalin.get().port() + "/printing/v1/admin/devices");
assertEquals(403, client.send(java.net.http.HttpRequest.newBuilder(url).GET().build(), java.net.http.HttpResponse.BodyHandlers.discarding()).statusCode());
var response = client.send(java.net.http.HttpRequest.newBuilder(url).header("X-Test-Admin", "allowed").GET().build(), java.net.http.HttpResponse.BodyHandlers.ofString());
assertEquals(200, response.statusCode());
assertEquals(2, new JSONObject(response.body()).getJSONArray("devices").length());
assertFalse(response.body().contains("token_hash"));
}
finally
{
server.stop();
}
}
/***************************************************************************
** Real QQQ pause/resume phases review selections before any job is queued.
***************************************************************************/
@Test
void selectedTestPausesForProfileAndReviewThenSubmitsOnce() throws Exception
{
Fixture fixture = fixture();
String process = "printingTestSelectedPdf";
var profile = new RunProcessAction().execute(new RunProcessInput().withProcessName(process).withValue("recordIds", fixture.printerId()));
assertFalse(profile.getException().isPresent(), () -> profile.getException().toString());
assertEquals("testProfile", profile.getProcessState().getNextStepName().orElseThrow());
assertEquals(0, fixture.service().jobs().length());
var review = new RunProcessAction().execute(new RunProcessInput().withProcessName(process).withProcessUUID(profile.getProcessUUID())
.withStartAfterStep("testProfile").withValue("testProfile", "LETTER"));
assertFalse(review.getException().isPresent(), () -> review.getException().toString());
assertTrue(review.getProcessState().getNextStepName().isPresent());
assertEquals(0, fixture.service().jobs().length());
var submitted = new RunProcessAction().execute(new RunProcessInput().withProcessName(process).withProcessUUID(review.getProcessUUID())
.withStartAfterStep(review.getProcessState().getNextStepName().orElseThrow()).withFrontendStepBehavior(RunProcessInput.FrontendStepBehavior.SKIP));
assertFalse(submitted.getException().isPresent(), () -> submitted.getException().toString());
assertEquals(1, fixture.service().jobs().length());
}
/***************************************************************************
** Enrollment replay cannot issue extra codes or reactivate consumed ones.
***************************************************************************/
@Test
void nativeEnrollmentReplayRetainsCodeAndNeverReactivatesConsumedReceipt() throws Exception
{
Fixture fixture = fixture();
RunBackendStepInput input = new RunBackendStepInput().withProcessName("printingEnrollDevice")
.addValue("facilityId", "default").addValue("deviceName", "station");
RunBackendStepOutput prepared = new RunBackendStepOutput();
new PrintingProcesses.PrepareEnrollment().run(input, prepared);
input.addValue("printingEnrollmentCode", prepared.getValueString("printingEnrollmentCode"))
.addValue("printingEnrollmentExpires", prepared.getValueString("printingEnrollmentExpires"));
RunBackendStepOutput first = new RunBackendStepOutput();
RunBackendStepOutput second = new RunBackendStepOutput();
new PrintingProcesses().run(input, first);
new PrintingProcesses().run(input, second);
assertEquals(first.getValueString("result"), second.getValueString("result"));
JSONObject enrollment = new JSONObject().put("enrollmentCode", prepared.getValueString("printingEnrollmentCode")).put("deviceName", "station").put("agentVersion", "test");
fixture.service().enroll(enrollment);
assertThrows(QException.class, () -> new PrintingProcesses().run(input, new RunBackendStepOutput()));
assertThrows(PrintingException.class, () -> fixture.service().enroll(enrollment));
input.addValue("printingEnrollmentExpires", java.time.Instant.now().minusSeconds(1).toString());
assertThrows(QException.class, () -> new PrintingProcesses().run(input, new RunBackendStepOutput()));
}
/***************************************************************************
** A lost load response must not duplicate a physical test on process replay.
***************************************************************************/
@Test
void testActionsDeduplicateSingleAndSelectedLoadReplay() throws Exception
{
Fixture fixture = fixture();
RunBackendStepInput single = new RunBackendStepInput().withProcessName("printingTestPdf")
.addValue("deviceId", fixture.device()).addValue("printerId", fixture.printerId()).addValue("printingTestRequestId", "single-replay");
for(int attempt = 0; attempt < 2; attempt++)
{
new PrintingProcesses().run(single, new RunBackendStepOutput());
}
assertEquals(1, fixture.service().jobs().length());
RunBackendStepInput selected = new RunBackendStepInput().withProcessName("printingTestSelectedPdf")
.withRecords(List.of(new QRecord().withValue("id", fixture.printerId()), new QRecord().withValue("id", fixture.otherPrinterId())))
.addValue("printingTestRequestId", "selected-replay");
for(int attempt = 0; attempt < 2; attempt++)
{
new PrintingProcesses.SelectedLoad().runOnePage(selected, new RunBackendStepOutput());
}
assertEquals(3, fixture.service().jobs().length());
}
/***************************************************************************
** Native actions and device requests use identical bundled label documents.
***************************************************************************/
@Test
void builtInTestEntryPointsShareProfilesAndRejectChangedIdempotentRequests() throws Exception
{
Fixture fixture = fixture();
fixture.service().inventory(fixture.device(), new JSONArray().put(new JSONObject().put("printerId", "laser")
.put("name", "Packing test printer").put("formats", new JSONArray(List.of("PDF", "ZPL")))));
QRecord printer = PrintingProcesses.resolvePrinter(fixture.printerId(), fixture.device());
String nativeJob = PrintingProcesses.submitTest(printer, false, "LABEL_4X6_300");
JSONObject request = new JSONObject().put("printerId", "laser").put("format", "ZPL").put("testProfile", "LABEL_4X6_300").put("requestId", "label-profile-test");
String deviceJob = fixture.service().testPrint(fixture.device(), request).getString("jobId");
assertEquals(fixture.service().getJob(nativeJob).getString("contentSha256"), fixture.service().getJob(deviceJob).getString("contentSha256"));
assertEquals(deviceJob, fixture.service().testPrint(fixture.device(), request).getString("jobId"));
assertEquals(409, assertThrows(PrintingException.class, () -> fixture.service().testPrint(fixture.device(), request.put("testProfile", "LABEL_4X6_203"))).getStatus());
assertEquals(nativeJob, fixture.service().claim(fixture.device()).getJSONObject("job").getString("jobId"));
assertArrayEquals(PrintingTestDocuments.zpl(300), fixture.service().content(fixture.device(), nativeJob));
assertEquals(400, assertThrows(PrintingException.class, () -> fixture.service().testPrint(fixture.device(), request.put("testProfile", "LETTER"))).getStatus());
assertThrows(PrintingException.class, () -> fixture.service().testPrint(fixture.device(), request.put("testProfile", JSONObject.NULL)));
assertThrows(PrintingException.class, () -> fixture.service().testPrint(fixture.device(), request.put("format", "RAW")));
assertThrows(QException.class, () -> PrintingProcesses.submitTest(printer, false, "A4"));
assertEquals(1, fixture.service().queuedJobs(fixture.device()).length());
}
/***************************************************************************
** Stock/resolution choices are present before both native review flows.
***************************************************************************/
@Test
void nativeFormsOfferStockAndResolutionBeforeSelectedPrinterReview() throws Exception
{
Fixture fixture = fixture();
QFrontendStepMetaData single = (QFrontendStepMetaData) fixture.instance().getProcess("printingTestZpl").getStep("details");
assertEquals("printing_testProfileZpl", single.getFormField("testProfile").getPossibleValueSourceName());
var selected = fixture.instance().getProcess("printingTestSelectedPdf");
assertEquals("prepareTest", selected.getStepList().getFirst().getName());
assertEquals("testProfile", selected.getStepList().get(1).getName());
QFrontendStepMetaData form = (QFrontendStepMetaData) selected.getStep("testProfile");
assertEquals("printing_testProfilePdf", form.getFormField("testProfile").getPossibleValueSourceName());
assertEquals(3, fixture.instance().getPossibleValueSource("printing_testProfileZpl").getEnumValues().size());
assertEquals(5, fixture.instance().getPossibleValueSource("printing_testProfilePdf").getEnumValues().size());
}
/***************************************************************************
** Native record selection requires duplicate consent and preserves the source.
***************************************************************************/
@@ -112,6 +328,9 @@ class PrintingProcessesTest
assertFalse(result.getException().isPresent(), () -> result.getException().toString());
assertTrue(fixture.service().claim(fixture.device()).isNull("job"));
assertTrue(fixture.service().claim(fixture.otherDevice()).isNull("job"));
var replay = new RunProcessAction().execute(new RunProcessInput().withProcessName(PrintingJobProcesses.CANCEL)
.withValue("recordIds", first + "," + second).withFrontendStepBehavior(RunProcessInput.FrontendStepBehavior.SKIP));
assertFalse(replay.getException().isPresent(), () -> replay.getException().toString());
String claimed = PrintingProcesses.submitTest(PrintingProcesses.resolvePrinter(fixture.printerId(), fixture.device()), true);
fixture.service().claim(fixture.device());
RunBackendStepInput selection = new RunBackendStepInput().withProcessName(PrintingJobProcesses.CANCEL)
@@ -235,7 +454,7 @@ class PrintingProcessesTest
void enrollmentRejectsMissingAndWrongTenantDespiteAdminPermission() throws Exception
{
fixture();
RunBackendStepInput input = new RunBackendStepInput().withProcessName("printingEnrollDevice").addValue("facilityId", "warehouse").addValue("deviceName", "station");
RunBackendStepInput input = new RunBackendStepInput().withProcessName("printingEnrollDevice").addValue("facilityId", "default").addValue("deviceName", "station");
QContext.getQSession().setSecurityKeyValues(Map.of("printing_tenant", List.of("tenant-b")));
assertThrows(com.kingsrook.qqq.backend.core.exceptions.QPermissionDeniedException.class, () -> new PrintingProcesses().run(input, new RunBackendStepOutput()));
QContext.getQSession().setSecurityKeyValues(Map.of());
@@ -247,7 +466,17 @@ class PrintingProcessesTest
/***************************************************************************
** One database, two tenants and multiple devices exercise real query scoping.
***************************************************************************/
private static Fixture fixture() throws Exception
static Fixture fixture() throws Exception
{
return (fixture(null));
}
/***************************************************************************
** An optional host facility source reuses real tenant-scoped device rows as fixtures.
***************************************************************************/
private static Fixture fixture(String facilitySource) throws Exception
{
String database = "printing_process_" + UUID.randomUUID();
String jdbc = "jdbc:h2:mem:" + database + ";DB_CLOSE_DELAY=-1;DATABASE_TO_UPPER=FALSE";
@@ -265,7 +494,12 @@ class PrintingProcessesTest
QInstance instance = new QInstance();
instance.addBackend(new RDBMSBackendMetaData().withName(backendName).withVendor("h2").withHostName("mem").withDatabaseName(database).withJdbcUrl(jdbc).withUsername("sa").withPassword(""));
instance.withInstanceDefaultAuthentication(new QAuthenticationMetaData().withName("mock").withType(com.kingsrook.qqq.backend.core.model.metadata.QAuthenticationType.MOCK));
new PrintingQBitProducer().withConfig(new PrintingQBitConfig().withBackendName(backendName).withService(service)).produce(instance, "printing");
if(facilitySource != null)
{
instance.addPossibleValueSource(com.kingsrook.qqq.backend.core.model.metadata.possiblevalues.QPossibleValueSource.newForTable(PrintingTables.DEVICE).withName(facilitySource));
}
new PrintingQBitProducer().withConfig(new PrintingQBitConfig().withBackendName(backendName).withService(service)
.withFacilityPossibleValueSourceName(facilitySource)).produce(instance, "printing");
QContext.init(instance, new QSession().withUser(new QUser().withIdReference("operator")).withPermissions("printing_admin").withSecurityKeyValue("printing_tenant", "tenant-a"));
QueryInput query = new QueryInput();
query.setTableName(PrintingTables.PRINTER);
@@ -282,7 +516,7 @@ class PrintingProcessesTest
foreignId = result.getString(1);
}
}
return (new Fixture(instance, service, device, otherDevice, printerId, otherPrinterId, foreignId));
return (new Fixture(instance, service, device, otherDevice, printerId, otherPrinterId, foreignId, foreign));
}
@@ -311,7 +545,7 @@ class PrintingProcessesTest
/***************************************************************************
** Per-test handles, without exposed device tokens.
***************************************************************************/
private record Fixture(QInstance instance, PrintingService service, String device, String otherDevice, String printerId, String otherPrinterId, String foreignPrinterId)
record Fixture(QInstance instance, PrintingService service, String device, String otherDevice, String printerId, String otherPrinterId, String foreignPrinterId, String foreignDevice)
{
}
}
@@ -0,0 +1,188 @@
/*
* QQQ - Low-code Application Framework for Engineers.
* Copyright (C) 2021-2025. Kingsrook, LLC
* 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
* contact@kingsrook.com
* https://github.com/Kingsrook/
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.kingsrook.qbits.printing;
import java.util.List;
import java.util.Map;
import java.util.UUID;
import com.kingsrook.qqq.backend.core.actions.processes.RunProcessAction;
import com.kingsrook.qqq.backend.core.context.QContext;
import com.kingsrook.qqq.backend.core.exceptions.QException;
import com.kingsrook.qqq.backend.core.exceptions.QPermissionDeniedException;
import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepInput;
import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepOutput;
import com.kingsrook.qqq.backend.core.model.actions.processes.RunProcessInput;
import com.kingsrook.qqq.backend.core.model.metadata.QBackendMetaData;
import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
import com.kingsrook.qqq.backend.core.model.metadata.authentication.QAuthenticationMetaData;
import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldMetaData;
import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldType;
import com.kingsrook.qqq.backend.core.model.metadata.qbits.QBitMetaData;
import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
import com.kingsrook.qqq.backend.core.model.session.QSession;
import com.kingsrook.qqq.backend.core.model.session.QSystemUserSession;
import com.kingsrook.qqq.backend.core.model.session.QUser;
import org.junit.jupiter.api.AfterEach;
import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertNotNull;
import static org.junit.jupiter.api.Assertions.assertNull;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.junit.jupiter.api.Assertions.assertTrue;
/*******************************************************************************
** Native retention forms enforce administrator and tenant scope independently.
*******************************************************************************/
class PrintingRetentionProcessesTest
{
/***************************************************************************
** Opening native cleanup is read-only until the operator continues past review.
***************************************************************************/
@Test
void nativeCleanupPausesForReviewBeforeRunningMaintenance() throws Exception
{
PrintingService service = fixture();
var preview = new RunProcessAction().execute(new RunProcessInput().withProcessName(PrintingRetentionProcesses.RUN_NOW));
assertFalse(preview.getException().isPresent(), () -> preview.getException().toString());
assertEquals("review", preview.getProcessState().getNextStepName().orElseThrow());
assertTrue(service.getRetentionSettings().optString("lastRunAt").isBlank());
var completed = new RunProcessAction().execute(new RunProcessInput().withProcessName(PrintingRetentionProcesses.RUN_NOW)
.withProcessUUID(preview.getProcessUUID()).withStartAfterStep("review").withFrontendStepBehavior(RunProcessInput.FrontendStepBehavior.SKIP));
assertFalse(completed.getException().isPresent(), () -> completed.getException().toString());
assertFalse(service.getRetentionSettings().optString("lastRunAt").isBlank());
}
/***************************************************************************
** Registering a QBit never starts maintenance without a host scheduler binding.
***************************************************************************/
@Test
void scheduleRequiresExplicitHostBindingAndUsesBoundedFiveMinuteCadence()
{
QInstance manual = new QInstance();
PrintingRetentionProcesses.register(manual, new PrintingQBitConfig());
assertNotNull(manual.getProcess(PrintingRetentionProcesses.SETTINGS));
assertNotNull(manual.getProcess(PrintingRetentionProcesses.RUN_NOW));
assertNull(manual.getProcess(PrintingRetentionProcesses.SCHEDULED));
QInstance scheduled = new QInstance();
PrintingRetentionProcesses.register(scheduled, new PrintingQBitConfig().withSchedulerName("host-scheduler"));
var schedule = scheduled.getProcess(PrintingRetentionProcesses.SCHEDULED).getSchedule();
assertEquals("host-scheduler", schedule.getSchedulerName());
assertEquals("0 */5 * * * ?", schedule.getCronExpression());
assertEquals("UTC", schedule.getCronTimeZoneId());
assertTrue(scheduled.getProcess(PrintingRetentionProcesses.SCHEDULED).getIsHidden());
}
/***************************************************************************
** Backend direct invocation cannot bypass either permission or tenant checks.
***************************************************************************/
@Test
void settingsEnforceAdminTenantAndValidationAndReadPersistedPolicy() throws Exception
{
PrintingService service = fixture();
PrintingRetentionProcesses step = new PrintingRetentionProcesses();
RunBackendStepInput save = input(PrintingRetentionProcesses.SETTINGS, "execute").addValue("days", 730).addValue("enabled", false);
QContext.getQSession().setSecurityKeyValues(Map.of("printing_tenant", List.of("foreign")));
assertThrows(QPermissionDeniedException.class, () -> step.run(save, new RunBackendStepOutput()));
QContext.init(QContext.getQInstance(), new QSession().withSecurityKeyValue("printing_tenant", "tenant-a"));
assertThrows(QPermissionDeniedException.class, () -> step.run(save, new RunBackendStepOutput()));
QContext.init(QContext.getQInstance(), new QSession().withPermissions("printing_admin").withSecurityKeyValue("printing_tenant", "tenant-a"));
step.run(save, new RunBackendStepOutput());
assertEquals(730, service.getRetentionSettings().getInt("days"));
assertFalse(service.getRetentionSettings().getBoolean("enabled"));
RunBackendStepOutput prepared = new RunBackendStepOutput();
step.run(input(PrintingRetentionProcesses.SETTINGS, "prepare"), prepared);
assertEquals(730, prepared.getValueInteger("days"));
assertEquals(false, prepared.getValueBoolean("enabled"));
assertTrue(prepared.getValueString("storage").contains("not configured"));
assertTrue(prepared.getValueString("schedule").contains("Not scheduled"));
assertThrows(QException.class, () -> step.run(input(PrintingRetentionProcesses.SETTINGS, "execute").addValue("days", 0).addValue("enabled", true), new RunBackendStepOutput()));
assertEquals(730, service.getRetentionSettings().getInt("days"));
}
/***************************************************************************
** Only a true system session can call the hidden scheduled entrypoint.
***************************************************************************/
@Test
void scheduledEntryRejectsHumanAdminAndUsesInstanceBoundSystemService() throws Exception
{
fixture();
PrintingRetentionProcesses step = new PrintingRetentionProcesses();
RunBackendStepInput scheduled = input(PrintingRetentionProcesses.SCHEDULED, "execute");
assertThrows(QPermissionDeniedException.class, () -> step.run(scheduled, new RunBackendStepOutput()));
QContext.init(QContext.getQInstance(), new QSystemUserSession(QContext.getQInstance()));
RunBackendStepOutput result = new RunBackendStepOutput();
step.run(scheduled, result);
assertTrue(result.getValueString("result").contains("0 eligible"));
}
/***************************************************************************
** Each test owns an isolated database and tenant-specific instance binding.
***************************************************************************/
private static PrintingService fixture() throws Exception
{
DriverDataSource source = new DriverDataSource("jdbc:h2:mem:retention-ui-" + UUID.randomUUID() + ";DB_CLOSE_DELAY=-1", "sa", "");
PrintingService service = new PrintingService(source, "tenant-a");
service.initialize();
QInstance instance = new QInstance();
instance.addBackend(new QBackendMetaData().withName("memory").withBackendType(com.kingsrook.qqq.backend.core.modules.backend.implementations.memory.MemoryBackendModule.class));
instance.addTable(new QTableMetaData().withName("fixture").withBackendName("memory").withPrimaryKeyField("id").withField(new QFieldMetaData("id", QFieldType.STRING)));
PrintingQBitConfig config = new PrintingQBitConfig().withService(service);
instance.addQBit(new QBitMetaData().withGroupId("com.kingsrook.qbits").withArtifactId("qbit-printing").withVersion("test").withNamespace("printing").withConfig(config));
PrintingRetentionProcesses.register(instance, config);
instance.withInstanceDefaultAuthentication(new QAuthenticationMetaData().withName("mock").withType(com.kingsrook.qqq.backend.core.model.metadata.QAuthenticationType.MOCK));
QContext.init(instance, new QSession().withUser(new QUser().withIdReference("operator")).withPermissions("printing_admin").withSecurityKeyValue("printing_tenant", "tenant-a"));
return (service);
}
/***************************************************************************
** Explicit step names prevent a forged form from selecting another operation.
***************************************************************************/
private static RunBackendStepInput input(String process, String step)
{
RunBackendStepInput input = new RunBackendStepInput().withProcessName(process);
input.setStepName(step);
return (input);
}
/***************************************************************************
** Thread-local context must never carry tenant authorization between tests.
***************************************************************************/
@AfterEach
void cleanup()
{
QContext.clear();
}
}
@@ -44,6 +44,97 @@ import static org.junit.jupiter.api.Assertions.assertTrue;
*******************************************************************************/
class PrintingServiceTest
{
/***************************************************************************
** Protocol maximum event fields persist; malformed/oversized values fail400.
***************************************************************************/
@Test
void eventBoundsMatchProtocolAndInventoryRejectsUnsupportedEnums() throws Exception
{
PrintingService service = new PrintingService(source(), "tenant-a");
service.initialize();
String device = enroll(service);
configure(service, device);
String job = service.submit(request(device)).getString("jobId");
service.claim(device);
for(JSONObject bad : List.of(new JSONObject().put("message", "m".repeat(2049)), new JSONObject().put("spoolerJobId", "s".repeat(129)), new JSONObject().put("message", JSONObject.NULL)))
{
assertEquals(400, assertThrows(PrintingException.class, () -> service.event(device, job, bad.put("eventId", "invalid").put("status", "RECEIVED"))).getStatus());
}
service.event(device, job, new JSONObject().put("eventId", "e".repeat(128)).put("status", "SPOOLED").put("message", "m".repeat(2048)).put("spoolerJobId", "s".repeat(128)));
assertEquals(2048, service.getJob(job).getString("message").length());
assertEquals(128, service.getJob(job).getString("spoolerJobId").length());
for(JSONArray formats : List.of(new JSONArray(), new JSONArray(List.of("RAW")), new JSONArray(List.of("PDF", "PDF"))))
{
assertEquals(400, assertThrows(PrintingException.class, () -> service.inventory(device, new JSONArray().put(inventory().getJSONObject(0).put("formats", formats)))).getStatus());
}
assertTrue(service.printers(device).getJSONObject(0).getBoolean("available"));
}
/***************************************************************************
** Changing a driver's capabilities must block previously queued formats.
***************************************************************************/
@Test
void claimRechecksCurrentPrinterFormat() throws Exception
{
PrintingService service = new PrintingService(source(), "tenant-a");
service.initialize();
String device = enroll(service);
configure(service, device);
String job = service.submit(request(device)).getString("jobId");
service.inventory(device, new JSONArray().put(new JSONObject().put("printerId", "zebra").put("name", "New driver")
.put("formats", new JSONArray(List.of("PDF")))));
assertTrue(service.claim(device).isNull("job"));
assertEquals("QUEUED", service.getJob(job).getString("status"));
service.inventory(device, inventory());
assertEquals(job, service.claim(device).getJSONObject("job").getString("jobId"));
}
/***************************************************************************
** Invalid JSON option types must not silently change the requested output.
***************************************************************************/
@Test
void malformedPrintOptionsAreRejectedBeforeQueueing() throws Exception
{
PrintingService service = new PrintingService(source(), "tenant-a");
service.initialize();
String device = enroll(service);
configure(service, device);
for(Object options : List.of("invalid", new JSONArray(), JSONObject.NULL,
new JSONObject().put("copies", 1.5), new JSONObject().put("copies", "2"), new JSONObject().put("copies", JSONObject.NULL)))
{
assertEquals(400, assertThrows(PrintingException.class, () -> service.submit(request(device).put("options", options))).getStatus());
}
assertEquals(0, service.jobs().length());
}
/***************************************************************************
** A failed status cannot erase evidence that a job may already have printed.
***************************************************************************/
@Test
void failureAfterSubmissionStillRequiresDuplicateConsent() throws Exception
{
PrintingService service = new PrintingService(source(), "tenant-a");
service.initialize();
String device = enroll(service);
configure(service, device);
String id = service.submit(request(device)).getString("jobId");
service.claim(device);
service.event(device, id, new JSONObject().put("eventId", "spooled-before-failure").put("status", "SPOOLED").put("spoolerJobId", "42"));
service.event(device, id, new JSONObject().put("eventId", "later-failure").put("status", "FAILED"));
assertEquals(409, assertThrows(PrintingException.class, () -> service.retry(device, id, new JSONObject().put("requestId", "retry"))).getStatus());
assertEquals(1, service.jobs().length());
service.retry(device, id, new JSONObject().put("requestId", "retry").put("confirmDuplicateRisk", true));
assertEquals(2, service.jobs().length());
}
/***************************************************************************
** An independently reconstructed runtime reads durable jobs and credentials.
***************************************************************************/
@@ -172,7 +263,12 @@ class PrintingServiceTest
assertThrows(com.kingsrook.qqq.backend.core.exceptions.QPermissionDeniedException.class,
() -> new PrintingReadPermission().checkPermissionsThrowing(new com.kingsrook.qqq.backend.core.model.actions.tables.insert.InsertInput(), instance.getTable(PrintingTables.DEVICE)));
RunBackendStepOutput enrollment = new RunBackendStepOutput();
new PrintingProcesses().run(new RunBackendStepInput().withProcessName("printingEnrollDevice").addValue("facilityId", "warehouse").addValue("deviceName", "station"), enrollment);
RunBackendStepInput enrollmentInput = new RunBackendStepInput().withProcessName("printingEnrollDevice").addValue("facilityId", "default").addValue("deviceName", "station");
RunBackendStepOutput enrollmentPrepared = new RunBackendStepOutput();
new PrintingProcesses.PrepareEnrollment().run(enrollmentInput, enrollmentPrepared);
enrollmentInput.addValue("printingEnrollmentCode", enrollmentPrepared.getValueString("printingEnrollmentCode"))
.addValue("printingEnrollmentExpires", enrollmentPrepared.getValueString("printingEnrollmentExpires"));
new PrintingProcesses().run(enrollmentInput, enrollment);
assertTrue(enrollment.getValueString("result").startsWith("Enrollment code:"));
String device = enroll(service);
service.inventory(device, new JSONArray().put(new JSONObject().put("printerId", "laser").put("name", "Laser").put("formats", new JSONArray(List.of("PDF")))));
@@ -181,7 +277,11 @@ class PrintingServiceTest
query.setTableName(PrintingTables.PRINTER);
String printerRow = new com.kingsrook.qqq.backend.core.actions.tables.QueryAction().execute(query).getRecords().getFirst().getValueString("id");
RunBackendStepOutput result = new RunBackendStepOutput();
new PrintingProcesses().run(new RunBackendStepInput().withProcessName("printingTestPdf").addValue("deviceId", device).addValue("printerId", printerRow), result);
RunBackendStepInput printInput = new RunBackendStepInput().withProcessName("printingTestPdf").addValue("deviceId", device).addValue("printerId", printerRow);
RunBackendStepOutput prepared = new RunBackendStepOutput();
new PrintingProcesses.PrepareTest().run(printInput, prepared);
printInput.addValue("printingTestRequestId", prepared.getValueString("printingTestRequestId"));
new PrintingProcesses().run(printInput, result);
assertTrue(result.getValueString("result").startsWith("Queued print job"));
JSONObject job = service.claim(device).getJSONObject("job");
assertEquals("PDF", job.getString("format"));
@@ -0,0 +1,430 @@
/*
* QQQ - Low-code Application Framework for Engineers.
* Copyright (C) 2021-2025. Kingsrook, LLC
* 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
* contact@kingsrook.com
* https://github.com/Kingsrook/
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.kingsrook.qbits.printing;
import java.io.File;
import java.nio.charset.StandardCharsets;
import java.sql.SQLException;
import java.time.Instant;
import java.util.ArrayList;
import java.util.Base64;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.UUID;
import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
import com.kingsrook.qqq.backend.module.filesystem.s3.model.metadata.S3BackendMetaData;
import com.kingsrook.qqq.backend.module.filesystem.s3.model.metadata.S3TableBackendDetails;
import org.json.JSONArray;
import org.json.JSONObject;
import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.assertArrayEquals;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.junit.jupiter.api.Assertions.assertTrue;
/*******************************************************************************
** Persisted S3 binding contracts use real metadata and the production guard.
** Only object IO is recorded in memory; no endpoint or credentials are used.
*******************************************************************************/
class PrintingStorageBindingTest
{
private static final byte[] DOCUMENT = "^XA^FDLayout contract^FS^XZ".getBytes(StandardCharsets.US_ASCII);
private static final String LEGACY_BINDING = "120fbf86e305b3457c0ef9fd62829d974730506ceae267b2b96503475724935d";
private static final String POSIX_BINDING = "dd336d2ddced413ee7a9a35ffa92e40fc20eb0ab2bbced01cba76081482738a1";
private static final String WINDOWS_BINDING = "2981f67f05b02d4e32822a910e948d28ac565410780defe47f5ba1fd9bfd3667";
/***************************************************************************
** Golden hashes represent AWS/print-documents, us-east-1, false path-style,
** empty base paths, and reviewed qqq-s3-filesystem-v1 separators 47 or 92.
** Identity components use ordered JSON; the untagged hash predates this
** layout contract and is never adopted.
***************************************************************************/
@Test
void rejectsUntaggedAndOtherPlatformBindings()
{
RecordingStorage storage = new RecordingStorage();
for(String incompatible : incompatibleBindings())
{
assertEquals(409, assertThrows(PrintingException.class, () -> storage.verifyBinding("printing_documents", incompatible)).getStatus());
}
String current = File.separatorChar == '\\' ? WINDOWS_BINDING : POSIX_BINDING;
assertEquals(current, storage.binding("printing_documents"));
storage.verifyBinding("printing_documents", current);
assertTrue(storage.calls.isEmpty());
}
/***************************************************************************
** Valid multiline prefixes must not move delimiters between identity parts.
** RC.20 resolves these pairs to different physical S3 keys.
***************************************************************************/
@Test
void rejectsMultilinePrefixRetargeting()
{
QInstance instance = s3Instance();
S3BackendMetaData backend = (S3BackendMetaData) instance.getBackend("s3");
S3TableBackendDetails details = (S3TableBackendDetails) instance.getTable("printing_documents").getBackendDetails();
backend.setEndpoint("https://storage.example.invalid");
backend.setPathStyleAccess(true);
backend.setBasePath("alpha\nbeta");
details.setBasePath("gamma");
PrintingDocumentStorage storage = new PrintingDocumentStorage(instance, "tenant-a");
String persisted = storage.binding("printing_documents");
storage.verifyBinding("printing_documents", persisted);
backend.setBasePath("alpha");
details.setBasePath("beta\ngamma");
assertEquals(409, assertThrows(PrintingException.class, () -> storage.verifyBinding("printing_documents", persisted)).getStatus());
}
/***************************************************************************
** A wrong-layout source cannot be read, copied or acknowledged as deleted.
** A rejected retry must not allocate or compensate another upload intent.
***************************************************************************/
@Test
void preservesHistoricalContentAndAccountingOnBindingMismatch() throws Exception
{
for(String incompatible : incompatibleBindings())
{
Fixture fixture = fixture();
String id = fixture.service.submit(request(fixture.device, "original")).getString("jobId");
String reference = fixture.storage.prefix() + id + ".zpl";
ageSuccess(fixture, id);
assertArrayEquals(DOCUMENT, fixture.service.content(fixture.device, id));
execute(fixture.source, "UPDATE printing_job SET content_binding=? WHERE id=?", incompatible, id);
fixture.storage.calls.clear();
assertEquals(409, assertThrows(PrintingException.class, () -> fixture.service.content(fixture.device, id)).getStatus());
assertEquals(409, assertThrows(PrintingException.class, () -> fixture.service.retry(fixture.device, id, retryRequest())).getStatus());
assertEquals(409, assertThrows(PrintingException.class, fixture.service::runRetention).getStatus());
assertTrue(fixture.storage.calls.isEmpty());
assertArrayEquals(DOCUMENT, fixture.storage.objects.get(reference));
assertEquals(1, fixture.storage.objects.size());
JSONObject stored = row(fixture.source, "SELECT content_available,content_binding,content_reference FROM printing_job WHERE id=?", id);
assertEquals(1, stored.getInt("CONTENT_AVAILABLE"));
assertEquals(incompatible, stored.getString("CONTENT_BINDING"));
assertEquals(reference, stored.getString("CONTENT_REFERENCE"));
assertEquals(1, row(fixture.source, "SELECT COUNT(*) AS total FROM printing_job").getInt("TOTAL"));
assertEquals(0, row(fixture.source, "SELECT COUNT(*) AS total FROM printing_document_orphan").getInt("TOTAL"));
assertEquals(1, row(fixture.source, "SELECT COUNT(*) AS total FROM printing_admission_event").getInt("TOTAL"));
assertRetainedBytes(fixture, DOCUMENT.length);
assertEquals(0, fixture.service.getRetentionSettings().getInt("lastRunCount"));
assertFalse(fixture.service.getRetentionSettings().getString("lastRunError").isBlank());
execute(fixture.source, "UPDATE printing_job SET content_binding=? WHERE id=?", fixture.storage.binding("printing_documents"), id);
String retry = fixture.service.retry(fixture.device, id, retryRequest()).getString("jobId");
execute(fixture.source, "UPDATE printing_job SET content_binding=? WHERE id=?", incompatible, id);
fixture.storage.calls.clear();
assertEquals(retry, fixture.service.retry(fixture.device, id, retryRequest()).getString("jobId"));
assertTrue(fixture.storage.calls.isEmpty());
execute(fixture.source, "UPDATE printing_job SET content_binding=? WHERE id=?", fixture.storage.binding("printing_documents"), id);
fixture.service.claim(fixture.device);
assertArrayEquals(DOCUMENT, fixture.service.content(fixture.device, retry));
assertEquals(1, fixture.service.runRetention());
assertFalse(fixture.storage.objects.containsKey(reference));
assertRetainedBytes(fixture, DOCUMENT.length);
}
}
/***************************************************************************
** Abandoned uploads retain both their exact object and quota on mismatch.
***************************************************************************/
@Test
void preservesOrphanReservationBeforeStorageIo() throws Exception
{
for(String incompatible : incompatibleBindings())
{
Fixture fixture = fixture();
fixture.storage.failUpload = true;
fixture.storage.failDelete = true;
assertThrows(SQLException.class, () -> fixture.service.submit(request(fixture.device, "orphan")));
JSONObject orphan = row(fixture.source, "SELECT * FROM printing_document_orphan");
String reference = orphan.getString("REFERENCE");
execute(fixture.source, "UPDATE printing_document_orphan SET binding=?,created_at=?", incompatible, Instant.now().minusSeconds(7200).toString());
fixture.storage.failUpload = false;
fixture.storage.failDelete = false;
fixture.storage.calls.clear();
assertEquals(409, assertThrows(PrintingException.class, fixture.service::runRetention).getStatus());
assertTrue(fixture.storage.calls.isEmpty());
JSONObject retained = row(fixture.source, "SELECT * FROM printing_document_orphan");
assertEquals(orphan.getString("ID"), retained.getString("ID"));
assertEquals(reference, retained.getString("REFERENCE"));
assertEquals(incompatible, retained.getString("BINDING"));
assertEquals(orphan.getString("IDEMPOTENCY_KEY"), retained.getString("IDEMPOTENCY_KEY"));
assertArrayEquals(DOCUMENT, fixture.storage.objects.get(reference));
assertRetainedBytes(fixture, DOCUMENT.length);
assertEquals(0, fixture.service.getRetentionSettings().getInt("lastRunCount"));
execute(fixture.source, "UPDATE printing_document_orphan SET binding=?", fixture.storage.binding("printing_documents"));
assertEquals(1, fixture.service.runRetention());
assertTrue(fixture.storage.objects.isEmpty());
assertEquals(0, row(fixture.source, "SELECT COUNT(*) AS total FROM printing_document_orphan").getInt("TOTAL"));
assertRetainedBytes(fixture, 0);
}
}
/***************************************************************************
** Old inline documents do not require an external binding after enabling S3.
***************************************************************************/
@Test
void keepsInlineDatabaseDocumentsReadableAndRetryable() throws Exception
{
Fixture fixture = fixture();
PrintingService inline = new PrintingService(fixture.source, "tenant-a");
String id = inline.submit(request(fixture.device, "inline")).getString("jobId");
ageSuccess(fixture, id);
assertArrayEquals(DOCUMENT, inline.content(fixture.device, id));
assertArrayEquals(DOCUMENT, fixture.service.content(fixture.device, id));
assertTrue(fixture.storage.calls.isEmpty());
JSONObject original = row(fixture.source, "SELECT content_reference,content_binding FROM printing_job WHERE id=?", id);
assertTrue(original.isNull("CONTENT_REFERENCE"));
assertTrue(original.isNull("CONTENT_BINDING"));
String retry = fixture.service.retry(fixture.device, id, retryRequest()).getString("jobId");
fixture.service.claim(fixture.device);
assertArrayEquals(DOCUMENT, fixture.service.content(fixture.device, retry));
fixture.storage.calls.clear();
assertEquals(1, fixture.service.runRetention());
assertTrue(fixture.storage.calls.isEmpty());
assertEquals(1, fixture.storage.objects.size());
assertRetainedBytes(fixture, DOCUMENT.length);
}
/***************************************************************************
** Persisted foreign/experimental fixtures are never generated by the guard.
***************************************************************************/
private static List<String> incompatibleBindings()
{
return (List.of(LEGACY_BINDING, File.separatorChar == '\\' ? POSIX_BINDING : WINDOWS_BINDING));
}
/***************************************************************************
** Exercise real service transactions with an actual S3 metadata fingerprint.
***************************************************************************/
private static Fixture fixture() throws Exception
{
DriverDataSource source = new DriverDataSource("jdbc:h2:mem:binding-" + UUID.randomUUID() + ";DB_CLOSE_DELAY=-1", "sa", "");
PrintingService service = new PrintingService(source, "tenant-a");
service.initialize();
RecordingStorage storage = new RecordingStorage();
service.configureStorage(storage, "printing_documents");
String device = service.enroll(service.createEnrollment("warehouse", "station").put("deviceName", "station").put("agentVersion", "test")).getString("deviceId");
service.inventory(device, new JSONArray().put(new JSONObject().put("printerId", "queue").put("name", "Synthetic").put("formats", new JSONArray(List.of("ZPL")))));
service.enablePrinter(device, "queue", true);
return (new Fixture(source, service, storage, device));
}
/***************************************************************************
** Native metadata identity shared by the persisted golden fixtures.
***************************************************************************/
private static QInstance s3Instance()
{
QInstance instance = new QInstance();
S3BackendMetaData backend = new S3BackendMetaData().withName("s3").withBucketName("print-documents").withRegion("us-east-1");
backend.setPathStyleAccess(false);
instance.addBackend(backend);
instance.addTable(new QTableMetaData().withName("printing_documents").withBackendName("s3").withBackendDetails(new S3TableBackendDetails()));
return (instance);
}
/***************************************************************************
** Synthetic requests never contact a printer.
***************************************************************************/
private static JSONObject request(String device, String key)
{
return (new JSONObject().put("deviceId", device).put("printerId", "queue").put("title", "Synthetic").put("format", "ZPL")
.put("contentBase64", Base64.getEncoder().encodeToString(DOCUMENT)).put("idempotencyKey", key));
}
/***************************************************************************
** A fresh action identity must attempt the original document read.
***************************************************************************/
private static JSONObject retryRequest()
{
return (new JSONObject().put("requestId", "retry").put("confirmDuplicateRisk", true));
}
/***************************************************************************
** Synthetic completion makes one job eligible without a physical print.
***************************************************************************/
private static void ageSuccess(Fixture fixture, String id) throws Exception
{
execute(fixture.source, "UPDATE printing_job SET status='SPOOLED',completed_at=? WHERE id=?", Instant.now().minusSeconds(400 * 86400L).toString(), id);
}
/***************************************************************************
** Both tenant and device accounting must preserve the held bytes.
***************************************************************************/
private static void assertRetainedBytes(Fixture fixture, long expected) throws Exception
{
for(String device : List.of("", fixture.device))
{
assertEquals(expected, row(fixture.source, "SELECT retained_bytes FROM printing_resource_usage WHERE tenant_id='tenant-a' AND device_id=?", device).getLong("RETAINED_BYTES"));
}
}
/***************************************************************************
** Mutate only isolated persisted fixtures to represent migration boundaries.
***************************************************************************/
private static void execute(DriverDataSource source, String sql, Object... values) throws Exception
{
try(var connection = source.getConnection(); var statement = connection.prepareStatement(sql))
{
for(int index = 0; index < values.length; index++)
{
statement.setObject(index + 1, values[index]);
}
statement.executeUpdate();
}
}
/***************************************************************************
** Inspect durable state independently of service response summaries.
***************************************************************************/
private static JSONObject row(DriverDataSource source, String sql, Object... values) throws Exception
{
try(var connection = source.getConnection(); var statement = connection.prepareStatement(sql))
{
for(int index = 0; index < values.length; index++)
{
statement.setObject(index + 1, values[index]);
}
try(var rows = statement.executeQuery())
{
assertTrue(rows.next());
JSONObject result = new JSONObject();
for(int index = 1; index <= rows.getMetaData().getColumnCount(); index++)
{
result.put(rows.getMetaData().getColumnLabel(index), rows.getObject(index) == null ? JSONObject.NULL : rows.getObject(index));
}
return (result);
}
}
}
/***************************************************************************
** Keep each tenant, database and object collection isolated.
***************************************************************************/
private record Fixture(DriverDataSource source, PrintingService service, RecordingStorage storage, String device)
{
}
/***************************************************************************
** Preserve production binding checks; replace only external object IO.
***************************************************************************/
private static class RecordingStorage extends PrintingDocumentStorage
{
private final Map<String, byte[]> objects = new HashMap<>();
private final List<String> calls = new ArrayList<>();
private boolean failUpload;
private boolean failDelete;
/************************************************************************
** No memory-backend bypass or layout override is involved.
************************************************************************/
private RecordingStorage()
{
super(s3Instance(), "tenant-a");
}
/************************************************************************
** Record an upload, optionally losing its acknowledgement afterwards.
************************************************************************/
@Override
public void put(String table, String reference, String format, byte[] content) throws SQLException
{
calls.add("PUT " + reference);
objects.put(reference, content.clone());
if(failUpload)
{
throw new SQLException("Synthetic upload acknowledgement failure");
}
}
/************************************************************************
** Unexpected reads are observable independently of returned bytes.
************************************************************************/
@Override
public byte[] get(String table, String reference)
{
calls.add("GET " + reference);
return (objects.get(reference).clone());
}
/************************************************************************
** A missing-object delete succeeds, matching the dangerous S3 behavior.
************************************************************************/
@Override
public void delete(String table, String reference) throws SQLException
{
calls.add("DELETE " + reference);
if(failDelete)
{
throw new SQLException("Synthetic deletion failure");
}
objects.remove(reference);
}
}
}
@@ -0,0 +1,63 @@
/*
* QQQ - Low-code Application Framework for Engineers.
* Copyright (C) 2021-2025. Kingsrook, LLC
* 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
* contact@kingsrook.com
* https://github.com/Kingsrook/
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.kingsrook.qbits.printing;
import javax.imageio.ImageIO;
import java.nio.file.Files;
import java.nio.file.Path;
import org.apache.pdfbox.pdmodel.PDDocument;
import org.apache.pdfbox.rendering.PDFRenderer;
/*******************************************************************************
** Manual local preview export only; this utility never connects to a printer.
*******************************************************************************/
public final class PrintingTestDocumentsExport
{
/***************************************************************************
** Write diagnostic artifacts to the caller's explicit preview directory.
***************************************************************************/
public static void main(String[] args) throws Exception
{
if(args.length != 1)
{
throw new IllegalArgumentException("Pass one local preview output directory");
}
Path directory = Path.of(args[0]).toAbsolutePath();
Files.createDirectories(directory);
for(TestPrintProfile profile : TestPrintProfile.values())
{
byte[] pdf = PrintingTestDocuments.pdf(profile);
Files.write(directory.resolve(profile.name() + ".pdf"), pdf);
try(PDDocument document = PDDocument.load(pdf))
{
ImageIO.write(new PDFRenderer(document).renderImageWithDPI(0, 144), "png", directory.resolve(profile.name() + "-pdf.png").toFile());
}
if(profile.getDpi() > 0)
{
Files.write(directory.resolve(profile.name() + ".zpl"), PrintingTestDocuments.zpl(profile));
ImageIO.write(PrintingTestDocuments.labelImage(profile.getDpi()), "png", directory.resolve(profile.name() + "-raster.png").toFile());
}
}
}
}
@@ -0,0 +1,287 @@
/*
* QQQ - Low-code Application Framework for Engineers.
* Copyright (C) 2021-2025. Kingsrook, LLC
* 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
* contact@kingsrook.com
* https://github.com/Kingsrook/
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.kingsrook.qbits.printing;
import javax.imageio.ImageIO;
import java.awt.image.BufferedImage;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.util.HexFormat;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
import org.apache.pdfbox.pdmodel.PDDocument;
import org.apache.pdfbox.pdmodel.common.PDRectangle;
import org.apache.pdfbox.pdmodel.graphics.image.PDImageXObject;
import org.apache.pdfbox.text.PDFTextStripper;
import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.assertArrayEquals;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.junit.jupiter.api.Assertions.assertTrue;
/*******************************************************************************
** Verify portable font/media content and bounded monochrome printer payloads.
*******************************************************************************/
class PrintingTestDocumentsTest
{
/***************************************************************************
** The packaged mascot is the exact official asset, with an undistorted
** visible outline in every PDF and each supported thermal raster density.
***************************************************************************/
@Test
void officialQueryMascotPreservesAspectRatioAcrossFormats() throws Exception
{
byte[] asset;
try(var stream = getClass().getResourceAsStream("/com/kingsrook/qbits/printing/images/query-mascot.png"))
{
asset = stream.readAllBytes();
}
assertEquals("385a053e15e0a9fc6f8a965257e3917db827594ab46ecf8cdddb847770a25dbb", HexFormat.of().formatHex(MessageDigest.getInstance("SHA-256").digest(asset)));
BufferedImage official = ImageIO.read(new java.io.ByteArrayInputStream(asset));
assertEquals(1326, official.getWidth());
assertEquals(1394, official.getHeight());
double expectedRatio = visibleAspectRatio(official);
for(TestPrintProfile profile : TestPrintProfile.values())
{
try(PDDocument document = PDDocument.load(PrintingTestDocuments.pdf(profile)))
{
int images = 0;
var resources = document.getPage(0).getResources();
for(var name : resources.getXObjectNames())
{
if(resources.getXObject(name) instanceof PDImageXObject image)
{
images++;
assertEquals(image.getWidth(), image.getHeight());
assertEquals(expectedRatio, visibleAspectRatio(image.getImage()), 0.01);
}
}
assertEquals(1, images);
}
if(profile.getDpi() > 0)
{
double scale = profile.getDpi() / 72.0;
BufferedImage raster = PrintingTestDocuments.labelImage(profile.getDpi());
BufferedImage mascot = raster.getSubimage((int) Math.floor(210 * scale), (int) Math.floor(30 * scale), (int) Math.ceil(54 * scale), (int) Math.ceil(54 * scale));
assertEquals(expectedRatio, visibleAspectRatio(mascot), 0.03);
}
}
}
/***************************************************************************
** Compare the actual visible artwork, ignoring transparent/white padding.
***************************************************************************/
private static double visibleAspectRatio(BufferedImage image)
{
int left = image.getWidth();
int right = -1;
int top = image.getHeight();
int bottom = -1;
for(int y = 0; y < image.getHeight(); y++)
{
for(int x = 0; x < image.getWidth(); x++)
{
int pixel = image.getRGB(x, y);
if((pixel >>> 24) >= 128 && (pixel & 0xffffff) < 0x808080)
{
left = Math.min(left, x);
right = Math.max(right, x);
top = Math.min(top, y);
bottom = Math.max(bottom, y);
}
}
}
assertTrue(right > left && bottom > top);
return ((right - left + 1.0) / (bottom - top + 1.0));
}
/***************************************************************************
** Every PDF profile has searchable diagnostic text and an embedded font.
***************************************************************************/
@Test
void pdfProfilesEmbedFontAndUsePhysicalMedia() throws Exception
{
for(TestPrintProfile profile : TestPrintProfile.values())
{
byte[] bytes = PrintingTestDocuments.pdf(profile);
assertArrayEquals(bytes, PrintingTestDocuments.pdf(profile), "Identical requests must preserve the content hash");
try(PDDocument document = PDDocument.load(bytes))
{
assertEquals(1, document.getNumberOfPages());
PDRectangle size = document.getPage(0).getMediaBox();
PDRectangle expected = profile.getDpi() > 0 ? new PDRectangle(288, 432) : (profile == TestPrintProfile.A4 ? PDRectangle.A4 : PDRectangle.LETTER);
assertEquals(expected.getWidth(), size.getWidth(), 0.01);
assertEquals(expected.getHeight(), size.getHeight(), 0.01);
String text = new PDFTextStripper().getText(document);
assertTrue(text.contains("QQQ"));
assertTrue(text.contains("TEST PRINT - NOT POSTAGE"));
assertTrue(text.contains("0O 1Il 5S"));
assertTrue(text.contains("25.4 mm"));
var resources = document.getPage(0).getResources();
int fonts = 0;
for(var name : resources.getFontNames())
{
fonts++;
assertTrue(resources.getFont(name).isEmbedded());
assertTrue(resources.getFont(name).getName().contains("JetBrainsMono"));
}
assertEquals(1, fonts);
}
}
}
/***************************************************************************
** All supported densities preserve inches and carry valid bounded GFA data.
***************************************************************************/
@Test
void labelDensitiesCarryExactBitmapAndNativeBarcodeWithoutPersistentDownloads() throws Exception
{
for(int dpi : new int[] {203, 300, 600})
{
byte[] bytes = PrintingTestDocuments.zpl(dpi);
assertTrue(bytes.length < 3 * 1024 * 1024);
String zpl = new String(bytes, StandardCharsets.US_ASCII);
int width = dpi * 4;
int height = dpi * 6;
int rowBytes = (width + 7) / 8;
assertTrue(zpl.startsWith("^XA^PW" + width + "^LL" + height + "^LH0,0"));
byte[] bitmap = reconstructGraphicStrips(zpl, rowBytes, height);
BufferedImage expected = PrintingTestDocuments.labelImage(dpi);
for(int y = 0; y < height; y++)
{
for(int x = 0; x < rowBytes * 8; x++)
{
boolean black = (bitmap[y * rowBytes + x / 8] & (0x80 >>> (x % 8))) != 0;
boolean expectedBlack = x < width && (expected.getRGB(x, y) & 0xffffff) == 0;
assertEquals(expectedBlack, black, "Reconstructed raster and row padding must match");
}
}
assertEquals(0, bitmap[0]);
assertEquals(0, bitmap[bitmap.length - 1]);
assertTrue(zpl.contains("^FD" + PrintingTestDocuments.BARCODE_VALUE + "^FS"));
Matcher barcode = Pattern.compile("\\^FO(\\d+),(\\d+)\\^BY(\\d+)\\^BCN,(\\d+),N,N,N").matcher(zpl);
assertTrue(barcode.find());
int barcodeX = Integer.parseInt(barcode.group(1));
int barcodeY = Integer.parseInt(barcode.group(2));
int module = Integer.parseInt(barcode.group(3));
int barcodeHeight = Integer.parseInt(barcode.group(4));
int maximumModules = 11 * (PrintingTestDocuments.BARCODE_VALUE.length() + 2) + 13;
assertTrue(barcodeX >= 10 * module);
assertTrue(barcodeX + (maximumModules + 10) * module < width - dpi / 8);
assertTrue(barcodeY > 258 * dpi / 72);
assertTrue(barcodeY + barcodeHeight < 330 * dpi / 72);
assertTrue(zpl.endsWith("^PQ1^XZ"));
assertFalse(zpl.contains("~D"));
assertFalse(zpl.contains("^A0"));
}
assertArrayEquals(PrintingTestDocuments.zpl(203), PrintingTestDocuments.zpl());
}
/***************************************************************************
** Parse actual wire fields and reject any missing, overlapping or oversized
** strip before comparing the complete bitmap with the rendered source.
***************************************************************************/
private static byte[] reconstructGraphicStrips(String zpl, int rowBytes, int height)
{
Matcher matcher = Pattern.compile("\\^FO0,(\\d+)\\^GFA,(\\d+),(\\d+),(\\d+),([0-9A-F]+)\\^FS").matcher(zpl);
byte[] bitmap = new byte[rowBytes * height];
int nextRow = 0;
int strips = 0;
while(matcher.find())
{
strips++;
int firstRow = Integer.parseInt(matcher.group(1));
int length = Integer.parseInt(matcher.group(2));
assertEquals(nextRow, firstRow);
assertTrue(length > 0 && length <= 99999);
assertEquals(length, Integer.parseInt(matcher.group(3)));
assertEquals(rowBytes, Integer.parseInt(matcher.group(4)));
assertEquals(0, length % rowBytes);
assertEquals(length * 2, matcher.group(5).length());
byte[] strip = HexFormat.of().parseHex(matcher.group(5));
assertTrue(firstRow * rowBytes + strip.length <= bitmap.length);
System.arraycopy(strip, 0, bitmap, firstRow * rowBytes, strip.length);
nextRow += length / rowBytes;
}
assertEquals(height, nextRow);
assertTrue(strips > 1);
assertEquals(strips, zpl.split("\\^GFA,", -1).length - 1);
return (bitmap);
}
/***************************************************************************
** Visible text and border fit inside quiet margins at each device density.
***************************************************************************/
@Test
void rasterArtworkLeavesPhysicalMargins() throws Exception
{
for(int dpi : new int[] {203, 300, 600})
{
BufferedImage image = PrintingTestDocuments.labelImage(dpi);
int black = 0;
int margin = dpi / 8;
for(int y = 0; y < image.getHeight(); y++)
{
for(int x = 0; x < image.getWidth(); x++)
{
if((image.getRGB(x, y) & 0xffffff) == 0)
{
black++;
assertTrue(x >= margin && x < image.getWidth() - margin && y >= margin && y < image.getHeight() - margin);
}
}
}
assertTrue(black > dpi * dpi / 2);
}
}
/***************************************************************************
** Invalid combinations fail before a job can be created.
***************************************************************************/
@Test
void profilesRejectWrongFormatStockAndDensity() throws Exception
{
assertEquals(TestPrintProfile.LETTER, TestPrintProfile.resolve("PDF", null));
assertEquals(TestPrintProfile.LABEL_4X6_203, TestPrintProfile.resolve("ZPL", null));
assertEquals(TestPrintProfile.A4, TestPrintProfile.resolve("PDF", "A4"));
assertEquals(400, assertThrows(PrintingException.class, () -> TestPrintProfile.resolve("ZPL", "LETTER")).getStatus());
assertThrows(PrintingException.class, () -> TestPrintProfile.resolve("ZPL", "A4"));
assertThrows(PrintingException.class, () -> TestPrintProfile.resolve("PDF", "UNKNOWN"));
assertThrows(PrintingException.class, () -> TestPrintProfile.resolve("RAW", null));
assertThrows(IllegalArgumentException.class, () -> PrintingTestDocuments.zpl(200));
}
}
@@ -0,0 +1,80 @@
/*
* QQQ - Low-code Application Framework for Engineers.
* Copyright (C) 2021-2025. Kingsrook, LLC
* 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
* contact@kingsrook.com
* https://github.com/Kingsrook/
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.kingsrook.qbits.printing;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.List;
import java.util.Set;
import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
import com.kingsrook.qqq.middleware.javalin.specs.extensions.MiddlewareSpecExtensionsMetaData;
import com.kingsrook.qqq.middleware.javalin.specs.v1.MiddlewareVersionV1;
import com.kingsrook.qqq.middleware.javalin.tools.UiApiContract;
import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertTrue;
/** Published native extension contract and semantic compatibility baseline. */
class PrintingUiApiContractTest
{
/** Regeneration is explicit; ordinary builds detect accidental contract drift. */
@Test
void publishedContractMatchesRegisteredSpecs() throws Exception
{
var extension = PrintingUiApi.extension();
var version = new MiddlewareVersionV1();
String generated = UiApiContract.generateExtensionYaml(version, extension);
Path contract = Path.of("src/main/resources/openapi/qqq-v1/printing.yaml");
Path baseline = Path.of("src/test/resources/openapi/printing-1.0.0.yaml");
if(Boolean.getBoolean("printing.openapi.update"))
{
Files.createDirectories(contract.getParent());
Files.writeString(contract, generated);
}
if(Boolean.getBoolean("printing.openapi.initializeBaseline") && !Files.exists(baseline))
{
Files.createDirectories(baseline.getParent());
Files.writeString(baseline, generated);
}
assertEquals(List.of(), UiApiContract.check(generated, Files.readString(contract), Files.readString(baseline), 1,
"mvnw.cmd -Dtest=PrintingUiApiContractTest -Dprinting.openapi.update=true test"));
var model = version.generateExtensionOpenAPIModel("qqq", extension);
assertEquals(17, model.getPaths().size());
assertTrue(model.getPaths().keySet().stream().allMatch(path -> path.startsWith("/qqq/v1/qbit/printing/")));
assertEquals("1.0.0", extension.getSemanticVersion());
assertTrue(generated.contains("X-QQQ-Device-Token"));
assertTrue(generated.contains("application/octet-stream"));
assertTrue(generated.contains("principalId"));
}
/** Registration replaces this extension without duplicating its native routes. */
@Test
void registrationIsStable()
{
QInstance instance = new QInstance();
PrintingUiApi.register(instance);
PrintingUiApi.register(instance);
assertEquals(Set.of("printing"), MiddlewareSpecExtensionsMetaData.of(instance).getExtensions().keySet());
}
}
@@ -0,0 +1,375 @@
/*
* QQQ - Low-code Application Framework for Engineers.
* Copyright (C) 2021-2025. Kingsrook, LLC
* 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
* contact@kingsrook.com
* https://github.com/Kingsrook/
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.kingsrook.qbits.printing;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.nio.file.Path;
import java.time.Instant;
import java.util.Base64;
import java.util.List;
import java.util.Set;
import java.util.UUID;
import java.util.concurrent.atomic.AtomicInteger;
import java.util.concurrent.atomic.AtomicReference;
import com.kingsrook.qqq.backend.core.context.QContext;
import com.kingsrook.qqq.backend.core.exceptions.QException;
import com.kingsrook.qqq.backend.core.model.actions.AbstractActionInput;
import com.kingsrook.qqq.backend.core.model.actions.tables.get.GetInput;
import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference;
import com.kingsrook.qqq.backend.core.model.metadata.permissions.MetaDataWithPermissionRules;
import com.kingsrook.qqq.backend.core.model.metadata.security.QSecurityKeyType;
import com.kingsrook.qqq.backend.core.model.metadata.security.RecordSecurityLock;
import com.kingsrook.qqq.backend.core.model.session.QSession;
import com.kingsrook.qqq.backend.core.model.session.QUser;
import com.kingsrook.qqq.middleware.javalin.QApplicationLauncher;
import com.kingsrook.qqq.middleware.javalin.QApplicationLauncherConfig;
import io.javalin.Javalin;
import org.json.JSONArray;
import org.json.JSONObject;
import org.junit.jupiter.api.AfterEach;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.io.TempDir;
import static org.junit.jupiter.api.Assertions.assertAll;
import static org.junit.jupiter.api.Assertions.assertArrayEquals;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.junit.jupiter.api.Assertions.assertTrue;
/** Native session, proof, principal, tenant and child-record boundaries over real QQQ/H2. */
class PrintingUiApiTest
{
@TempDir
Path directory;
/** Each test owns its native context. */
@AfterEach
void clearContext()
{
QContext.clear();
}
/** Device proof cannot authorize native routes without a current authenticated QQQ user. */
@Test
void actualTableAuthHttpRequiresExplicitBindingAndPreservesBinaryContent() throws Exception
{
String jdbc = "jdbc:h2:file:" + directory.resolve("native-http").toString().replace('\\', '/');
DriverDataSource source = new DriverDataSource(jdbc, "sa", "");
String password = "synthetic-native-api-password-1234";
PrintingLocalHost host = new PrintingLocalHost(new PrintingLocalSettings(jdbc, "sa", "", "demo", 0, "synthetic-management-token-long-enough", "operator", password));
PrintingService service = new PrintingService(source, "demo");
JSONObject enrolled = service.enroll(service.createEnrollment("default", "Synthetic device").put("deviceName", "Synthetic device").put("agentVersion", "test"));
String device = enrolled.getString("deviceId");
String proof = enrolled.getString("deviceToken");
service.inventory(device, new JSONArray().put(new JSONObject().put("printerId", "queue").put("name", "Synthetic queue").put("formats", new JSONArray(List.of("ZPL")))));
service.enablePrinter(device, "queue", true);
byte[] content = "^XA^FO10,10^FDsynthetic^FS^XZ".getBytes(StandardCharsets.UTF_8);
String job = service.submit(new JSONObject().put("deviceId", device).put("printerId", "queue").put("title", "Synthetic")
.put("format", "ZPL").put("contentBase64", Base64.getEncoder().encodeToString(content)).put("idempotencyKey", "http")).getString("jobId");
AtomicReference<Javalin> javalin = new AtomicReference<>();
QApplicationLauncher launcher = QApplicationLauncher.run(host, new QApplicationLauncherConfig().withRegisterShutdownHook(false).withServerCustomizer(server ->
{
host.configure(server, false);
server.withJavalinConfigurationCustomizer(javalin::set);
}));
String base = "http://127.0.0.1:" + javalin.get().port();
String prefix = "/qqq/v1" + PrintingUiApi.PREFIX;
try(HttpClient client = HttpClient.newHttpClient())
{
assertEquals(401, send(client, base, prefix + "/device/jobs/claim", "POST", new JSONObject(), null, device, proof).statusCode());
HttpRequest bearerOnly = HttpRequest.newBuilder(URI.create(base + prefix + "/device/jobs/claim")).header("Authorization", "Bearer " + proof)
.header("Content-Type", "application/json").POST(HttpRequest.BodyPublishers.ofString("{}")).build();
assertEquals(401, client.send(bearerOnly, HttpResponse.BodyHandlers.discarding()).statusCode());
assertEquals("QUEUED", service.getJob(job).getString("status"));
HttpRequest login = HttpRequest.newBuilder(URI.create(base + "/qqq/v1/manageSession")).header("Origin", base)
.header("Authorization", "Basic " + Base64.getEncoder().encodeToString(("operator:" + password).getBytes(StandardCharsets.UTF_8)))
.header("Content-Type", "application/json").POST(HttpRequest.BodyPublishers.ofString("{}")).build();
HttpResponse<String> authenticated = client.send(login, HttpResponse.BodyHandlers.ofString());
assertEquals(200, authenticated.statusCode());
String cookie = authenticated.headers().allValues("set-cookie").stream().filter(value -> value.startsWith("sessionUUID=")).findFirst().orElseThrow().split(";", 2)[0];
JSONObject session = json(send(client, base, prefix + "/session", "GET", null, cookie, null, null), 200);
assertEquals("operator", session.getString("principalId"));
assertEquals("demo", session.getString("tenantId"));
assertFalse(session.has("deviceId"));
assertEquals(403, send(client, base, prefix + "/device/jobs/claim", "POST", new JSONObject(), cookie, device, proof).statusCode());
assertEquals(403, send(client, base, prefix + "/device/bind", "POST", new JSONObject(), cookie, device, "wrong").statusCode());
json(send(client, base, prefix + "/device/bind", "POST", new JSONObject(), cookie, device, proof), 200);
JSONObject codeForNative = service.createEnrollment("default", "Native-only code").put("deviceName", "Native-only code").put("agentVersion", "test");
assertAll("Native proof cannot authorize the legacy transport",
() -> assertEquals(401, legacy(client, base, "/device/jobs/claim", "POST", new JSONObject(), proof).statusCode()),
() -> assertEquals(401, legacy(client, base, "/device/jobs/" + job + "/content", "GET", null, proof).statusCode()),
() -> assertEquals(401, legacy(client, base, "/device/jobs/queued", "GET", null, proof).statusCode()),
() -> assertEquals(401, legacy(client, base, "/device/control/poll", "POST", new JSONObject(), proof).statusCode()),
() -> assertEquals(403, legacy(client, base, "/enroll", "POST", codeForNative, null).statusCode()));
assertEquals("QUEUED", service.getJob(job).getString("status"));
assertEquals("default", service.enrollmentFacility(codeForNative.getString("enrollmentCode")));
JSONObject nativeOnly = json(send(client, base, prefix + "/devices/enroll", "POST", codeForNative, cookie, null, null), 200);
service.authorizeAgent(nativeOnly.getString("deviceId"), nativeOnly.getString("deviceToken"), "operator", false);
assertEquals(401, legacy(client, base, "/device/jobs/queued", "GET", null, nativeOnly.getString("deviceToken")).statusCode());
assertEquals(403, send(client, base, prefix + "/device/jobs/claim", "POST", new JSONObject(), cookie, null, null).statusCode());
JSONObject others = service.enrollForUser(service.createEnrollment("default", "Other owner").put("deviceName", "Other owner").put("agentVersion", "test"), "another-principal");
assertEquals(403, send(client, base, prefix + "/device/heartbeat", "POST", new JSONObject().put("agentVersion", "test"), cookie, others.getString("deviceId"), others.getString("deviceToken")).statusCode());
assertEquals(device, json(send(client, base, prefix + "/session", "GET", null, cookie, device, proof), 200).getString("deviceId"));
assertEquals(job, json(send(client, base, prefix + "/device/jobs/claim", "POST", new JSONObject(), cookie, device, proof), 200).getJSONObject("job").getString("jobId"));
HttpResponse<byte[]> downloaded = send(client, base, prefix + "/device/jobs/" + job + "/content", "GET", null, cookie, device, proof);
assertEquals(200, downloaded.statusCode());
assertArrayEquals(content, downloaded.body());
JSONObject openApi = json(send(client, base, "/qqq/v1/openapi.json", "GET", null, null, null, null), 200);
assertTrue(openApi.getJSONObject("paths").has(prefix + "/devices/enroll"));
assertTrue(openApi.toString().contains("application/octet-stream"));
JSONObject action = action("REVOKE");
json(send(client, base, prefix + "/admin/devices/" + device + "/actions", "POST", action, cookie, null, null), 200);
assertEquals(403, send(client, base, prefix + "/device/heartbeat", "POST", new JSONObject().put("agentVersion", "test"), cookie, device, proof).statusCode());
JSONObject nativeEnrollment = service.createEnrollment("default", "Native enrollment").put("deviceName", "Native enrollment").put("agentVersion", "test");
JSONObject fresh = json(send(client, base, prefix + "/devices/enroll", "POST", nativeEnrollment, cookie, null, null), 200);
service.authorizeAgent(fresh.getString("deviceId"), fresh.getString("deviceToken"), "operator", false);
JSONObject unavailable = service.createEnrollment("inaccessible-facility", "Denied enrollment").put("deviceName", "Denied enrollment").put("agentVersion", "test");
assertEquals(403, send(client, base, prefix + "/devices/enroll", "POST", unavailable, cookie, null, null).statusCode());
assertEquals("inaccessible-facility", service.enrollmentFacility(unavailable.getString("enrollmentCode")));
}
finally
{
launcher.stop();
}
}
/** Native context permissions and principal ownership are re-evaluated on each adapter invocation. */
@Test
void currentPrincipalTenantPermissionAndRevocationAreAllRequired() throws Exception
{
var f = PrintingProcessesTest.fixture();
JSONObject enrolled = f.service().enroll(f.service().createEnrollment("default", "Bound").put("deviceName", "Bound").put("agentVersion", "test"));
String device = enrolled.getString("deviceId");
String proof = enrolled.getString("deviceToken");
assertThrows(PrintingException.class, () -> PrintingAgentAuthorization.device(device, proof, false));
PrintingAgentAuthorization.device(device, proof, true);
QContext.getQSession().setUser(new QUser().withIdReference("different-user"));
assertThrows(PrintingException.class, () -> PrintingAgentAuthorization.device(device, proof, false));
assertThrows(PrintingException.class, () -> PrintingAgentAuthorization.device(device, proof, true));
QContext.getQSession().setUser(new QUser().withIdReference("operator"));
QContext.getQSession().setPermissions(Set.of());
assertThrows(QException.class, () -> PrintingAgentAuthorization.device(device, proof, false));
QContext.setQSession(new QSession().withUser(new QUser().withIdReference("operator")).withPermissions("printing_admin").withSecurityKeyValue("printing_tenant", "tenant-b"));
assertThrows(QException.class, () -> PrintingAgentAuthorization.device(device, proof, false));
QContext.setQSession(new QSession().withUser(new QUser().withIdReference("operator")).withPermissions("printing_admin").withSecurityKeyValue("printing_tenant", "tenant-a"));
assertThrows(QException.class, () -> PrintingControlAuthorization.record(PrintingTables.DEVICE, f.foreignDevice()));
f.service().deviceAction(device, action("REVOKE"), "administrator");
assertThrows(PrintingException.class, () -> PrintingAgentAuthorization.device(device, proof, false));
}
/** An accessible device never grants hidden child jobs or lets claim choose a different job. */
@Test
void claimAndClearHonorJobRowsAndQueueSnapshotRace() throws Exception
{
var f = PrintingProcessesTest.fixture();
String hidden = submit(f.service(), f.device(), "hidden");
String visible = submit(f.service(), f.device(), "visible");
f.instance().addSecurityKeyType(new QSecurityKeyType().withName("job_scope"));
f.instance().getTable(PrintingTables.JOB).withRecordSecurityLock(new RecordSecurityLock().withFieldName("title").withSecurityKeyType("job_scope"));
QContext.getQSession().withSecurityKeyValue("job_scope", "visible");
assertThrows(QException.class, () -> PrintingControlAuthorization.deviceAction(f.device(), action("CLEAR_QUEUE")));
assertEquals("QUEUED", f.service().getJob(hidden).getString("status"));
assertEquals(visible, PrintingAgentAuthorization.claim(f.device()).getJSONObject("job").getString("jobId"));
assertEquals("QUEUED", f.service().getJob(hidden).getString("status"));
Set<String> expected = f.service().queuedJobIdsForControl(f.device());
String newcomer = submit(f.service(), f.device(), "newcomer");
assertEquals(409, assertThrows(PrintingException.class, () -> f.service().deviceAction(f.device(), action("CLEAR_QUEUE"), "operator", expected)).getStatus());
assertEquals("QUEUED", f.service().getJob(newcomer).getString("status"));
}
/** Shared-printer queue reviews retain Get-only policy with one printer lookup per request. */
@Test
void clearDeduplicatesPrinterReviewWithoutSkippingGetPolicy() throws Exception
{
var f = PrintingProcessesTest.fixture();
String first = submit(f.service(), f.device(), "first");
String second = submit(f.service(), f.device(), "second");
f.instance().getTable(PrintingTables.PRINTER).getPermissionRules().withCustomPermissionChecker(new QCodeReference(PrinterGetPolicy.class));
PrinterGetPolicy.calls.set(0);
PrinterGetPolicy.denied = true;
assertThrows(QException.class, () -> PrintingControlAuthorization.deviceAction(f.device(), action("CLEAR_QUEUE")));
assertEquals("QUEUED", f.service().getJob(first).getString("status"));
assertEquals("QUEUED", f.service().getJob(second).getString("status"));
PrinterGetPolicy.calls.set(0);
PrinterGetPolicy.denied = false;
assertEquals(2, PrintingControlAuthorization.deviceAction(f.device(), action("CLEAR_QUEUE")).getInt("cancelledJobCount"));
assertEquals(1, PrinterGetPolicy.calls.get());
}
/** A host can distinguish Get authority from query visibility; this must remain effective. */
public static class PrinterGetPolicy extends PrintingReadPermission
{
static final AtomicInteger calls = new AtomicInteger();
static boolean denied;
/** Apply the deliberately Get-only test policy. */
@Override
public void checkPermissionsThrowing(AbstractActionInput input, MetaDataWithPermissionRules metadata) throws com.kingsrook.qqq.backend.core.exceptions.QPermissionDeniedException
{
super.checkPermissionsThrowing(input, metadata);
if(input instanceof GetInput)
{
calls.incrementAndGet();
if(denied)
{
throw new com.kingsrook.qqq.backend.core.exceptions.QPermissionDeniedException("Synthetic Get-only policy");
}
}
}
}
/** Native selection preserves the oldest eligible job, including stable ID ordering on ties. */
@Test
void nativeClaimUsesDurableCreationOrder() throws Exception
{
var f = PrintingProcessesTest.fixture();
String newer = submit(f.service(), f.device(), "newer");
String older = submit(f.service(), f.device(), "older");
var backend = (com.kingsrook.qqq.backend.module.rdbms.model.metadata.RDBMSBackendMetaData) f.instance().getBackend(f.instance().getTable(PrintingTables.JOB).getBackendName());
try(var connection = new DriverDataSource(backend.getJdbcUrl(), "sa", "").getConnection())
{
PrintingService.update(connection, "UPDATE printing_job SET created_at=? WHERE id=?", "2026-01-02T00:00:00Z", newer);
PrintingService.update(connection, "UPDATE printing_job SET created_at=? WHERE id=?", "2026-01-01T00:00:00Z", older);
}
assertEquals(older, PrintingAgentAuthorization.claim(f.device()).getJSONObject("job").getString("jobId"));
f.service().event(f.device(), older, new JSONObject().put("eventId", "received-old").put("status", "RECEIVED"));
assertEquals(newer, PrintingAgentAuthorization.claim(f.device()).getJSONObject("job").getString("jobId"));
}
/** Printer eligibility is applied before the bounded candidate limit, not after it. */
@Test
void olderDisabledPrinterJobsCannotStarveEligibleClaim() throws Exception
{
var f = PrintingProcessesTest.fixture();
for(int index = 0; index < 20; index++)
{
submit(f.service(), f.device(), "disabled-" + index);
}
f.service().inventory(f.device(), new JSONArray()
.put(new JSONObject().put("printerId", "laser").put("name", "Disabled").put("formats", new JSONArray(List.of("PDF"))))
.put(new JSONObject().put("printerId", "ready").put("name", "Ready").put("formats", new JSONArray(List.of("PDF")))));
f.service().enablePrinter(f.device(), "laser", false);
f.service().enablePrinter(f.device(), "ready", true);
String ready = f.service().submit(new JSONObject().put("deviceId", f.device()).put("printerId", "ready").put("title", "eligible")
.put("format", "PDF").put("contentBase64", Base64.getEncoder().encodeToString("%PDF-synthetic".getBytes(StandardCharsets.UTF_8)))
.put("idempotencyKey", "eligible")).getString("jobId");
assertEquals(ready, PrintingAgentAuthorization.claim(f.device()).getJSONObject("job").getString("jobId"));
assertEquals(20, f.service().queuedJobs(f.device()).length());
}
/** Inventory omission cannot update hidden rows or a concurrent unreviewed row. */
@Test
void inventoryRequiresAllExistingRowsAndExactLockedSnapshot() throws Exception
{
var f = PrintingProcessesTest.fixture();
Set<String> before = PrintingAgentAuthorization.inventory(f.device());
JSONArray snapshot = new JSONArray().put(new JSONObject().put("printerId", "laser").put("name", "Packing laser").put("formats", new JSONArray(List.of("PDF"))))
.put(new JSONObject().put("printerId", "hidden").put("name", "Hidden printer").put("formats", new JSONArray(List.of("PDF"))));
f.service().inventory(f.device(), snapshot);
assertEquals(409, assertThrows(PrintingException.class, () -> f.service().inventory(f.device(), new JSONArray(), before)).getStatus());
assertTrue(f.service().printers(f.device()).getJSONObject(0).getBoolean("available"));
f.instance().addSecurityKeyType(new QSecurityKeyType().withName("printer_scope"));
f.instance().getTable(PrintingTables.PRINTER).withRecordSecurityLock(new RecordSecurityLock().withFieldName("name").withSecurityKeyType("printer_scope"));
QContext.getQSession().withSecurityKeyValue("printer_scope", "Packing laser");
assertThrows(QException.class, () -> PrintingAgentAuthorization.inventory(f.device()));
assertEquals(2, f.service().printers(f.device()).length());
}
/** Synthetic PDF bytes are queued only; no renderer or printer is invoked. */
private static String submit(PrintingService service, String device, String title) throws Exception
{
return (service.submit(new JSONObject().put("deviceId", device).put("printerId", "laser").put("title", title).put("format", "PDF")
.put("contentBase64", Base64.getEncoder().encodeToString("%PDF-synthetic".getBytes(StandardCharsets.UTF_8))).put("idempotencyKey", title)).getString("jobId"));
}
/** Preserve the same request across retries. */
private static JSONObject action(String action)
{
return (new JSONObject().put("requestId", UUID.randomUUID().toString()).put("issuedAt", Instant.now().toString()).put("action", action));
}
/** Real HTTP uses native session cookies plus separate device proof headers. */
private static HttpResponse<byte[]> send(HttpClient client, String base, String path, String method, JSONObject body, String cookie, String device, String proof) throws Exception
{
HttpRequest.Builder request = HttpRequest.newBuilder(URI.create(base + path)).header("Origin", base).header("X-QQQ-Client", "api/qqq-print-agent");
if(cookie != null)
{
request.header("Cookie", cookie);
}
if(device != null)
{
request.header(PrintingAgentAuthorization.DEVICE_HEADER, device);
}
if(proof != null)
{
request.header(PrintingAgentAuthorization.TOKEN_HEADER, proof);
}
request.method(method, body == null ? HttpRequest.BodyPublishers.noBody() : HttpRequest.BodyPublishers.ofString(body.toString()));
if(body != null)
{
request.header("Content-Type", "application/json");
}
return (client.send(request.build(), HttpResponse.BodyHandlers.ofByteArray()));
}
/** Legacy requests intentionally carry no QQQ cookie or native secondary-proof headers. */
private static HttpResponse<byte[]> legacy(HttpClient client, String base, String path, String method, JSONObject body, String token) throws Exception
{
HttpRequest.Builder request = HttpRequest.newBuilder(URI.create(base + PrintingRoutes.BASE + path)).header("Origin", base);
if(token != null)
{
request.header("Authorization", "Bearer " + token);
}
if(body != null)
{
request.header("Content-Type", "application/json");
}
request.method(method, body == null ? HttpRequest.BodyPublishers.noBody() : HttpRequest.BodyPublishers.ofString(body.toString()));
return (client.send(request.build(), HttpResponse.BodyHandlers.ofByteArray()));
}
/** Check status before interpreting success; no secret-bearing body is echoed on failure. */
private static JSONObject json(HttpResponse<byte[]> response, int status)
{
assertEquals(status, response.statusCode());
return (new JSONObject(new String(response.body(), StandardCharsets.UTF_8)));
}
}
File diff suppressed because it is too large. Load diff