diff --git a/.github/ISSUE_TEMPLATE/bug.yml b/.github/ISSUE_TEMPLATE/bug.yml index 8c25430..1581cc1 100644 --- a/.github/ISSUE_TEMPLATE/bug.yml +++ b/.github/ISSUE_TEMPLATE/bug.yml @@ -1,3 +1,6 @@ +# Copyright 2026 Kingsrook, LLC +# SPDX-License-Identifier: Apache-2.0 + name: Bug report description: Report a reproducible printing QBit issue. title: 'bug: ' diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index 7f95f00..6a075fb 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -1,3 +1,6 @@ +# Copyright 2026 Kingsrook, LLC +# SPDX-License-Identifier: Apache-2.0 + blank_issues_enabled: true contact_links: - name: Report a security vulnerability privately diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 8075d0f..413636c 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -1,3 +1,6 @@ +# Copyright 2026 Kingsrook, LLC +# SPDX-License-Identifier: Apache-2.0 + version: 2 updates: - package-ecosystem: maven diff --git a/.github/scripts/check-codeql-sarif.py b/.github/scripts/check-codeql-sarif.py new file mode 100644 index 0000000..8705490 --- /dev/null +++ b/.github/scripts/check-codeql-sarif.py @@ -0,0 +1,56 @@ +# Copyright 2026 Kingsrook, LLC +# SPDX-License-Identifier: Apache-2.0 + +"""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) diff --git a/.github/scripts/check-maven-inventory.py b/.github/scripts/check-maven-inventory.py new file mode 100644 index 0000000..ffaac49 --- /dev/null +++ b/.github/scripts/check-maven-inventory.py @@ -0,0 +1,128 @@ +# Copyright 2026 Kingsrook, LLC +# SPDX-License-Identifier: Apache-2.0 + +"""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() diff --git a/.github/scripts/check-source-headers.py b/.github/scripts/check-source-headers.py new file mode 100644 index 0000000..2392c7e --- /dev/null +++ b/.github/scripts/check-source-headers.py @@ -0,0 +1,128 @@ +# Copyright 2026 Kingsrook, LLC +# SPDX-License-Identifier: Apache-2.0 + +"""Check leading notices in explicitly owned, Git-tracked source families.""" + +import fnmatch +import json +import re +import subprocess +import sys +from pathlib import Path +from typing import Any + + +def selected(name: str, policy: dict[str, Any]) -> bool: + """Select owned paths, honoring documented exact/pattern exclusions first.""" + if any(fnmatch.fnmatchcase(name, item["pattern"]) for item in policy["exclusions"]): + return False + return any(fnmatch.fnmatchcase(name, pattern) for pattern in policy["includes"]) + + +def leading_comments(text: str, style: str) -> str: + """Read comments only, preserving required interpreter/XML directive ordering.""" + text = text.removeprefix("\ufeff") + if text.startswith("", text) + if style != "xml" or declaration is None: + raise ValueError("Invalid XML declaration") + text = text[declaration.end():] + elif text.startswith("#!"): + if style not in ("hash", "powershell", "slash"): + raise ValueError("Unexpected interpreter directive") + text = text.partition("\n")[2] + while re.match(r"#Requires\b", text, re.IGNORECASE): + if style != "powershell": + raise ValueError("Unexpected PowerShell directive") + text = text.partition("\n")[2] + comments = [] + while text.strip(): + text = text.lstrip() + if text.startswith(""), "powershell": ("<#", "#>")}[style] + body, separator, rest = text[len(opening):].partition(closing) + if not separator: + raise ValueError("Unterminated leading comment") + comments.append(body) + text = rest + else: + break + return "\n".join(re.sub(r"^\s*[*~]\s?", "", line).strip() for line in "\n".join(comments).splitlines()) + + +def check_notice(name: str, text: str, policy: dict[str, Any]) -> None: + """Require an approved holder/license pair in real leading comment syntax.""" + suffix = Path(name).suffix + style = policy["styles"].get(suffix) + if Path(name).name.startswith("Dockerfile."): + style = "hash" + if style is None: + raise ValueError("Selected path has no configured comment syntax") + comments = leading_comments(text, style) + approved = [item for item in policy["notices"] if any(fnmatch.fnmatchcase(name, pattern) for pattern in item["paths"])] + for notice in approved: + holder = re.escape(notice["holder"]) + copyright_pattern = rf"(?m)^Copyright\s+(?:\([cC]\)\s*)?\d{{4}}(?:[-–]\d{{4}})?\.?\s+{holder}(?:\s+\(KofTwentyTwo\))?\.?(?:\s+Licensed under the MIT License \(see LICENSE\)\.)?$" + if re.search(copyright_pattern, comments) is None: + continue + spdx = re.findall(r"(?m)^SPDX-License-Identifier:\s*(\S+)\s*$", comments) + if spdx and any(value != notice["license"] for value in spdx): + continue + apache = all(phrase in comments for phrase in ( + "Licensed under the Apache License, Version 2.0", + "you may not use this file except in compliance with the License.", + "https://www.apache.org/licenses/LICENSE-2.0", + "WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND", + "limitations under the License.", + )) + if suffix == ".java" and not apache: + continue + if notice["license"] in spdx or (notice["license"] == "Apache-2.0" and apache): + return + raise ValueError("Missing or mismatched leading copyright/license notice") + + +def check_repository(root: Path, policy: dict[str, Any]) -> int: + """Check tracked sources without scanning build outputs or executing source.""" + tracked = subprocess.run(["git", "-C", str(root), "ls-files", "-z"], check=True, capture_output=True).stdout.decode("utf-8").split("\u0000") + failures = [] + count = 0 + for name in tracked: + if not name or not selected(name, policy): + continue + count += 1 + try: + check_notice(name, (root / name).read_text(encoding="utf-8-sig"), policy) + except (ValueError, OSError) as error: + failures.append(f"{name}: {error}") + if count == 0: + raise ValueError("No owned source files selected") + if failures: + raise ValueError("\n".join(failures)) + return count + + +def main() -> None: + """Load the repository-specific reviewed scope and fail CI on a bad notice.""" + root = Path(__file__).resolve().parents[2] + policy = json.loads((root / ".github/source-headers.json").read_text(encoding="utf-8")) + count = check_repository(root, policy) + print(f"Leading source notices verified: {count} tracked files") + + +if __name__ == "__main__": + try: + main() + except (ValueError, OSError, subprocess.CalledProcessError) as error: + print(str(error), file=sys.stderr) + sys.exit(1) diff --git a/.github/scripts/test-maven-inventory.py b/.github/scripts/test-maven-inventory.py new file mode 100644 index 0000000..8bd5c77 --- /dev/null +++ b/.github/scripts/test-maven-inventory.py @@ -0,0 +1,108 @@ +# Copyright 2026 Kingsrook, LLC +# SPDX-License-Identifier: Apache-2.0 + +"""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() diff --git a/.github/scripts/test-scan-gates.py b/.github/scripts/test-scan-gates.py new file mode 100644 index 0000000..c8494eb --- /dev/null +++ b/.github/scripts/test-scan-gates.py @@ -0,0 +1,92 @@ +# Copyright 2026 Kingsrook, LLC +# SPDX-License-Identifier: Apache-2.0 + +"""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() diff --git a/.github/scripts/test-source-headers.py b/.github/scripts/test-source-headers.py new file mode 100644 index 0000000..8a04b44 --- /dev/null +++ b/.github/scripts/test-source-headers.py @@ -0,0 +1,156 @@ +# Copyright 2026 Kingsrook, LLC +# SPDX-License-Identifier: Apache-2.0 + +"""Exercise notice parsing, provenance, scope and real Git inventory rejection.""" + +import importlib.util +import json +import subprocess +import tempfile +import unittest +from pathlib import Path +from typing import Any + + +SPEC = importlib.util.spec_from_file_location("headers", Path(__file__).with_name("check-source-headers.py")) +assert SPEC is not None and SPEC.loader is not None +HEADERS = importlib.util.module_from_spec(SPEC) +SPEC.loader.exec_module(HEADERS) +POLICY = json.loads(Path(__file__).parents[1].joinpath("source-headers.json").read_text(encoding="utf-8")) +MIT = "Copyright (c) 2026 James Maes\nSPDX-License-Identifier: MIT" +APACHE = """Copyright (C) 2021-2025. Kingsrook, LLC +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.""" + + +def fixture_policy(holder: str = "James Maes", license_id: str = "MIT") -> dict[str, Any]: + """Use the production styles with a small explicit owned fixture scope.""" + return {"includes": ["src/*"], "exclusions": [], "styles": POLICY["styles"], + "notices": [{"holder": holder, "license": license_id, "paths": ["src/*"]}]} + + +class HeaderTests(unittest.TestCase): + """Ensure policy failures cannot pass through text-only copyright searches.""" + + def test_each_real_comment_syntax(self) -> None: + """Recognize hash, slash, block and XML notices in their own languages.""" + for name, text in ( + ("src/a.py", "# " + MIT.replace("\n", "\n# ") + "\nprint(1)"), + ("src/a.cs", "// " + MIT.replace("\n", "\n// ") + "\nclass A {}"), + ("src/a.mjs", "/*\n * " + MIT.replace("\n", "\n * ") + "\n */\nexport {};"), + ("src/a.xml", "\n"), + ("src/a.ps1", "<#\n" + MIT + "\n#>\nWrite-Output 1"), + ): + with self.subTest(name=name): + HEADERS.check_notice(name, text, fixture_policy()) + + def test_required_first_lines_and_bom(self) -> None: + """Accept shebangs, PowerShell requirements and XML declarations first.""" + for name, prefix, body in ( + ("src/a.sh", "#!/bin/sh\n", "# " + MIT.replace("\n", "\n# ")), + ("src/a.ps1", "#Requires -Version 7.4\n", "# " + MIT.replace("\n", "\n# ")), + ("src/a.xml", "\n", ""), + ("src/a.mjs", "#!/usr/bin/env node\n", "/*" + MIT + "*/"), + ): + with self.subTest(name=name): + HEADERS.check_notice(name, "\ufeff" + prefix + body, fixture_policy()) + + def test_misordered_required_first_lines_fail(self) -> None: + """A notice must not displace an interpreter or XML declaration.""" + for name, text in ( + ("src/a.sh", "# " + MIT.replace("\n", "\n# ") + "\n#!/bin/sh"), + ("src/a.ps1", "# " + MIT.replace("\n", "\n# ") + "\n#Requires -Version 7.4"), + ("src/a.xml", ""), + ): + with self.subTest(name=name), self.assertRaises(ValueError): + HEADERS.check_notice(name, text, fixture_policy()) + + def test_code_strings_and_late_comments_do_not_count(self) -> None: + """Reject docstrings and comments after executable declarations.""" + for text in ("notice = \"" + MIT.replace("\n", "\\n") + "\"", + "\"\"\"" + MIT + "\"\"\"", "import os\n# " + MIT.replace("\n", "\n# ")): + with self.subTest(text=text), self.assertRaises(ValueError): + HEADERS.check_notice("src/a.py", text, fixture_policy()) + + def test_wrong_syntax_and_unterminated_comments_fail(self) -> None: + """Notice text alone is insufficient without a complete language comment.""" + for text in ("# " + MIT, "/*" + MIT, "string text = \"" + MIT + "\";"): + with self.subTest(text=text), self.assertRaises(ValueError): + HEADERS.check_notice("src/a.cs", text, fixture_policy()) + with self.assertRaises(ValueError): + HEADERS.check_notice("src/a.py", "<#" + MIT + "#>", fixture_policy()) + + def test_wrong_holder_or_license_and_conflicting_spdx_fail(self) -> None: + """Do not conflate repository licenses or accept conflicting identifiers.""" + for text in (MIT.replace("James Maes", "Someone Else"), MIT.replace("MIT", "Apache-2.0"), + MIT + "\nSPDX-License-Identifier: Apache-2.0", MIT.splitlines()[0]): + with self.subTest(text=text), self.assertRaises(ValueError): + HEADERS.check_notice("src/a.cs", "/*" + text + "*/", fixture_policy()) + + def test_complete_legacy_apache_without_spdx(self) -> None: + """Retain valid legacy year ranges and complete Apache notices.""" + policy = fixture_policy("Kingsrook, LLC", "Apache-2.0") + HEADERS.check_notice("src/A.java", "/*" + APACHE + "*/\nclass A {}", policy) + HEADERS.check_notice("src/a.xml", "", policy) + + def test_java_requires_full_apache_block(self) -> None: + """An abbreviated SPDX-only Java notice cannot replace scoped convention.""" + policy = fixture_policy("Kingsrook, LLC", "Apache-2.0") + for notice in ("Copyright 2026 Kingsrook, LLC\nSPDX-License-Identifier: Apache-2.0", + APACHE.replace("limitations under the License.", "")): + with self.subTest(notice=notice), self.assertRaises(ValueError): + HEADERS.check_notice("src/A.java", "/*" + notice + "*/", policy) + + def test_virtual_agent_provenance_is_path_scoped(self) -> None: + """Only the owned virtual-agent family may use its existing QRun.IO holder.""" + policy = fixture_policy() + policy["notices"].append({"holder": "QRun.IO, Inc.", "license": "MIT", "paths": ["tools/virtual-agent/*"]}) + text = "/*Copyright 2026 QRun.IO, Inc. Licensed under the MIT License (see LICENSE).\nSPDX-License-Identifier: MIT*/" + HEADERS.check_notice("tools/virtual-agent/a.mjs", text, policy) + with self.assertRaises(ValueError): + HEADERS.check_notice("src/a.mjs", text, policy) + + def test_current_scope_and_documented_exclusions(self) -> None: + """New scripts enter the guard; data, generated and upstream files do not.""" + self.assertTrue(HEADERS.selected(".github/scripts/new-tool.py", POLICY)) + self.assertTrue(HEADERS.selected(".github/workflows/new-check.yml", POLICY)) + for name in (".mvn/wrapper/MavenWrapperDownloader.java", "mvnw", "schemas/new.json", + "src/main/resources/openapi/new.yaml", "src/test/resources/openapi/old.yaml", + "src/generated/Example.cs", "src/Example/obj/Generated.cs", "packages.lock.json"): + with self.subTest(name=name): + self.assertFalse(HEADERS.selected(name, POLICY)) + self.assertTrue(all(item["reason"].strip() for item in POLICY["exclusions"])) + + def test_guard_sources_match_this_repository_provenance(self) -> None: + """Check copied guard files against local policy even before Git staging.""" + for filename in ("check-source-headers.py", "test-source-headers.py"): + path = Path(__file__).with_name(filename) + name = ".github/scripts/" + filename + self.assertTrue(HEADERS.selected(name, POLICY)) + HEADERS.check_notice(name, path.read_text(encoding="utf-8"), POLICY) + + def test_real_git_inventory_rejects_missing_tracked_header(self) -> None: + """A tracked new source fails while untracked generated output is ignored.""" + with tempfile.TemporaryDirectory() as directory: + root = Path(directory) + subprocess.run(["git", "init", "-q", str(root)], check=True) + root.joinpath("src").mkdir() + source = root / "src/a.py" + source.write_text("print(1)", encoding="utf-8") + subprocess.run(["git", "-C", str(root), "add", "--", "src/a.py"], check=True) + with self.assertRaisesRegex(ValueError, "src/a.py"): + HEADERS.check_repository(root, fixture_policy()) + source.write_text("# " + MIT.replace("\n", "\n# ") + "\nprint(1)", encoding="utf-8") + root.joinpath("src/untracked.py").write_text("print(2)", encoding="utf-8") + self.assertEqual(1, HEADERS.check_repository(root, fixture_policy())) + + +if __name__ == "__main__": + unittest.main() diff --git a/.github/source-headers.json b/.github/source-headers.json new file mode 100644 index 0000000..71b19ee --- /dev/null +++ b/.github/source-headers.json @@ -0,0 +1,111 @@ +{ + "description": "Scope of the reviewed 2026-11-01 owned-source notice pass. Python fnmatch patterns match slash-containing relative paths. Native C# IDE0073 and full Java Apache conventions remain in force.", + "includes": [ + ".github/*.yml", + ".github/*.yaml", + ".github/scripts/*.py", + "pom.xml", + "checkstyle/*.xml", + "dev/*.ps1", + "dev/*.cs", + "dev/*.csproj", + "dev/*.java", + "dev/*.sh", + "dev/*.yaml", + "dev/*.xml", + "dev/Dockerfile.*", + "dev/native-auth/Dockerfile.*", + "src/main/java/*.java", + "src/test/java/*.java", + "src/test/resources/log4j2-test.xml" + ], + "exclusions": [ + { + "pattern": "*.json", + "reason": "Schema, fixtures, manifests and lock data: repository LICENSE/NOTICE, no comments." + }, + { + "pattern": "*.lock", + "reason": "Dependency lock data, not owned executable source." + }, + { + "pattern": "*/generated/*", + "reason": "Explicit generated-code directory." + }, + { + "pattern": "*/bin/*", + "reason": "Generated build output." + }, + { + "pattern": "*/obj/*", + "reason": "Generated build output." + }, + { + "pattern": "*/node_modules/*", + "reason": "Third-party dependency output." + }, + { + "pattern": ".mvn/*", + "reason": "Upstream Maven wrapper provenance." + }, + { + "pattern": "mvnw*", + "reason": "Upstream Maven wrapper provenance." + }, + { + "pattern": "Assets/Legal/*", + "reason": "Byte-exact third-party legal files." + }, + { + "pattern": "src/main/resources/*", + "reason": "Bundled font/legal assets and OpenAPI schema data." + }, + { + "pattern": "src/test/resources/openapi/*", + "reason": "Historical contract schema fixtures." + }, + { + "pattern": "*.slnx", + "reason": "Solution metadata outside the completed source-header pass; root LICENSE/NOTICE applies." + }, + { + "pattern": "*.manifest", + "reason": "Application activation metadata outside this pass; root LICENSE/NOTICE applies." + }, + { + "pattern": "*.runsettings", + "reason": "Test runner metadata outside this pass; root LICENSE/NOTICE applies." + }, + { + "pattern": ".editorconfig", + "reason": "Style configuration outside this pass; root LICENSE/NOTICE applies." + } + ], + "styles": { + ".py": "hash", + ".ps1": "powershell", + ".psd1": "powershell", + ".sh": "hash", + ".yml": "hash", + ".yaml": "hash", + ".cs": "slash", + ".java": "slash", + ".mjs": "slash", + ".js": "slash", + ".xml": "xml", + ".props": "xml", + ".csproj": "xml", + ".wxs": "xml", + ".wixproj": "xml", + ".xaml": "xml" + }, + "notices": [ + { + "paths": [ + "*" + ], + "license": "Apache-2.0", + "holder": "Kingsrook, LLC" + } + ] +} diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 2d39e58..7a41bce 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -1,3 +1,6 @@ +# Copyright 2026 Kingsrook, LLC +# SPDX-License-Identifier: Apache-2.0 + name: Build and prerelease on: @@ -26,15 +29,19 @@ jobs: uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: repository: QRun-IO/qqq-print-protocol - ref: a0de93b00e602abde9be77c1ec9103b670bf3c09 + ref: f3cbc02e9b0fb4fdfefaa59d976c04df747cc589 path: qqq-print-protocol persist-credentials: false - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5.2.0 with: distribution: temurin java-version: '21' + - name: Verify owned source notices and rejection paths + run: | + python3 .github/scripts/test-source-headers.py + python3 .github/scripts/check-source-headers.py - 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 +76,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 }} diff --git a/.github/workflows/codeql-analysis.yml b/.github/workflows/codeql-analysis.yml new file mode 100644 index 0000000..06ebaca --- /dev/null +++ b/.github/workflows/codeql-analysis.yml @@ -0,0 +1,128 @@ +# Copyright 2026 Kingsrook, LLC +# SPDX-License-Identifier: Apache-2.0 + +# 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@ # 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 ()` 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__") diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml index 368ce90..c75eaa0 100644 --- a/.github/workflows/codeql.yml +++ b/.github/workflows/codeql.yml @@ -1,3 +1,6 @@ +# Copyright 2026 Kingsrook, LLC +# SPDX-License-Identifier: Apache-2.0 + name: codeql on: pull_request: @@ -5,13 +8,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 \ No newline at end of file + build-mode: none diff --git a/.github/workflows/development.yml b/.github/workflows/development.yml new file mode 100644 index 0000000..cde4a9e --- /dev/null +++ b/.github/workflows/development.yml @@ -0,0 +1,67 @@ +# Copyright 2026 Kingsrook, LLC +# SPDX-License-Identifier: Apache-2.0 + +name: development + +on: + pull_request: + push: + branches: [main] + workflow_dispatch: + inputs: + native-auth: + description: Run the opt-in, unpublished native-auth candidate qualification + type: boolean + default: false + +permissions: + contents: read + +concurrency: + group: development-${{ github.ref }} + cancel-in-progress: false + +jobs: + scripts: + name: development-scripts (${{ matrix.os }}) + runs-on: ${{ matrix.os }} + timeout-minutes: 15 + strategy: + fail-fast: false + matrix: + os: [ubuntu-24.04, windows-latest] + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + - name: Analyze and test development scripts + shell: pwsh + run: | + $ErrorActionPreference = 'Stop' + Install-Module PSScriptAnalyzer -RequiredVersion 1.25.0 -Scope CurrentUser -Force + Install-Module Pester -RequiredVersion 5.7.1 -Scope CurrentUser -Force + Import-Module PSScriptAnalyzer -RequiredVersion 1.25.0 + Import-Module Pester -RequiredVersion 5.7.1 + $issues = @(Invoke-ScriptAnalyzer -Path dev -Recurse -Severity Warning,Error) + if ($issues.Count) { $issues | Format-Table; throw 'Development script analysis failed.' } + $configuration = New-PesterConfiguration + $configuration.Run.Path = './dev/tests' + $configuration.Run.Exit = $true + $configuration.TestRegistry.Enabled = $false + Invoke-Pester -Configuration $configuration + + docker: + name: development-docker + runs-on: ubuntu-24.04 + timeout-minutes: 50 + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + - name: Run disposable S3 and network printing smoke tests + shell: pwsh + run: ./dev/Invoke-Dev.ps1 -Action Test + - name: Run opt-in real native provider qualification + if: github.event_name == 'workflow_dispatch' && inputs.native-auth + shell: pwsh + run: ./dev/Invoke-Dev.ps1 -Action Test -ExperimentalNativeAuth diff --git a/.github/workflows/pr-gates.yml b/.github/workflows/pr-gates.yml new file mode 100644 index 0000000..e32bcf5 --- /dev/null +++ b/.github/workflows/pr-gates.yml @@ -0,0 +1,28 @@ +# Copyright 2026 Kingsrook, LLC +# SPDX-License-Identifier: Apache-2.0 + +# 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 diff --git a/.github/workflows/security.yml b/.github/workflows/security.yml index d623128..8da4dcc 100644 --- a/.github/workflows/security.yml +++ b/.github/workflows/security.yml @@ -1,7 +1,10 @@ +# Copyright 2026 Kingsrook, LLC +# SPDX-License-Identifier: Apache-2.0 + # 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 +62,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 +89,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 +118,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 +148,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 diff --git a/CHANGELOG.md b/CHANGELOG.md index 4d9d5f0..469ae87 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,108 @@ # Changelog +## Unreleased (0.4.0-SNAPSHOT) + +Printing extension **2.1.0** (additive; the agent contract is unchanged). + +- Print anything: `PrintingRecordProcesses.registerAll(instance)` adds **Print** to + every table that can be read one record at a time (call it after the host's + tables are in the instance). Hidden tables, tables without a primary key or + `TABLE_GET`, and tables carrying `PrintingTableSettings().withPrintable(false)` + are skipped. +- The record sheet now follows the table's metadata: field sections in tier order + with their labels, remaining fields under "Other fields", and a summary of each + child list (association): its label, row count and first ten rows. +- New `printingPrintTableList`: a table list (grid) of any readable table with the + caller's columns (in order) and widths, filter and sort, either the whole result + (`scope` `ALL`, the default: read a thousand rows at a time up to `maxRows`, + 10,000 by default and at most; a larger result prints its first rows and says + so in the header and in `printingMessage`) or the current page (`PAGE`, the + filter's skip/limit). Letter or A4; orientation `AUTO` (landscape when the + columns need it), portrait or landscape. The header repeats on every page; the + page header carries the table, the rows printed of the total, the filter text + and the sort, and the footer the table, time, user and "Page n of m". + `printingRowCount` reports the matching rows before printing. +- New `printingPrintText`: any text (a capture of a terminal screen) as a + monospace PDF, wrapped and broken across pages. +- All documents share one page writer with "Page n of m" footers and a running + title on later pages. Table and record reads enforce the user's permissions. + +## 0.3.1-SNAPSHOT + +- Add record printing: `PrintingRecordProcesses.register(instance, table)` adds a + **Print** process (`printingPrintRecords_{table}`) to a host table's records and + selections. It asks for an approved, exposed PDF printer and a copy count, shows + the standard review, then renders each selected record as a Letter record sheet + (`PrintingRecordDocuments`: heading, visible non-binary fields with display + values, wrapped and continued across pages) and queues one PDF job per record. + The queued job IDs are returned in the process value `printingJobIds`. +- Fix selection actions whose first step is a form (**Print a test page**, + **Print a test label** on selected printers, and **Print**): over the UI API the + record selection reaches only the init call, so the review answered "No records + were selected". The prepare step now keeps the selection as `queryFilterJson`. + +## 0.3.0-rc.1 — 2026-10-31 + +Upgrade the server before the matching Windows connector. Native printing API +2.0 requires synchronized authenticated WSS; old native clients cannot claim +without it, and there is no polling fallback. Wire payloads remain v1. + +- Add client-initiated realtime WebSocket delivery under native printing API 2.0, + with current QQQ session and record permissions revalidated during connection use. +- Deliver desired state, device commands, inventory, lifecycle events and receipts + over the socket; native claims require acknowledged current settings and state. +- Stream retained documents independently from controls and expose document, + concurrency, timing, admission and retention batch limits in native admin forms. +- Preserve durable job/command identities across reconnects. Installed Windows + realtime and physical-output acceptance remain separate from source/test gates. + +## 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. diff --git a/NOTICE b/NOTICE index 8416ea2..c446af9 100644 --- a/NOTICE +++ b/NOTICE @@ -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 diff --git a/README.md b/README.md index 6057658..db3e486 100644 --- a/README.md +++ b/README.md @@ -1,35 +1,46 @@ # QQQ Printing -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. +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 opens an outbound, authenticated two-way WebSocket; documents download separately over HTTPS. The cloud needs no inbound route into the facility. Release candidate **0.3.0-rc.1** requires native printing API **2.0**, with no job/control polling fallback. Upgrade the server before the matching Windows connector. -**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. Current release candidate: [**0.3.0-rc.1**](https://github.com/QRun-IO/qbit-printing/releases/tag/v0.3.0-rc.1). The previous [**0.2.0-rc.1**](https://github.com/QRun-IO/qbit-printing/releases/tag/v0.2.0-rc.1) 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 build attestations for all three assets. Verify the exact downloaded release; publication does not establish installed or physical-output acceptance. 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] - C[Windows service] -->|Outbound HTTPS polling| B + C[Windows service] <-->|Client-initiated WSS: commands and status| B + C -->|Separate outbound HTTPS document streams| B C --> D[Windows spooler] 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 [real-time host integration](docs/REALTIME.md), [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). + +## Local development + +Start an isolated native QQQ application, MinIO and optional Authentik with the +[Docker development commands](dev/README.md). The default test runs synthetic +Java/.NET WebSocket jobs and S3 checks without an installed connector or printer. ## 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 `f3cbc02e9b0fb4fdfefaa59d976c04df747cc589`; 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=`. -## 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 +54,30 @@ 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=` 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 is accepted with authentication and access-denial checks, preserved pairing/history, connector reconnection and 365-day retention. The previously accepted 0.1.4-rc.1 release passed 73 tests and zero Checkstyle violations; the user confirmed all three Query diagnostic outputs good. Production S3/IAM and remote deployment remain separate qualification work. The 0.2.0 controls/authentication release passed 25 real client/native QQQ interoperability checks; the user later confirmed installed Letter PDF and Zebra ZPL output, the Connected footer and both printers. These results do not qualify installed or physical behavior for 0.3. + ## 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.3.0-rc.1.jar' '-DpomFile=qbit-printing-0.3.0-rc.1.pom' ``` After the artifact is available in your configured repository, add: @@ -67,7 +86,7 @@ After the artifact is available in your configured repository, add: com.kingsrook.qbits qbit-printing - 0.1.0-rc.1 + 0.3.0-rc.1 ``` @@ -77,30 +96,38 @@ 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=` 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=` 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. Two independent settings govern dispatch: `available` means the queue is present in the latest locally selected inventory; `enabled` means a QQQ administrator approved it. New submissions and claims require both. Removing a queue from local selection makes it unavailable without deleting its approval/history. An empty inventory withdraws all queues. Withdrawing a queue cannot retract a job already accepted by Windows. -Application code calls `printing.submit(JSONObject)` with the shared `SubmitJobRequest` fields. A stable business idempotency key returns the same job when retried; changing document/options/target under the same key fails. PDF is sent as bytes encoded once in base64; ZPL is UTF-8 printer-ready bytes. Default limit is 20 MiB. Queue approval and format compatibility are checked before insertion. +Application code calls `printing.submit(JSONObject)` with the shared `SubmitJobRequest` fields. A stable business idempotency key returns the same job when retried; changing document/options/target under the same key fails. PDF is sent as bytes encoded once in base64; ZPL is UTF-8 printer-ready bytes. Default decoded limits are 100 MiB for PDF and 20 MiB for ZPL, both configurable in the native Printing connection and limits process. Queue approval and format compatibility are checked before insertion. ```java JSONObject job = printing.submit(new JSONObject() @@ -114,6 +141,8 @@ JSONObject job = printing.submit(new JSONObject() String printJobId = job.getString("jobId"); ``` +For terminal and web clients the QBit also offers ready-made print processes: `PrintingRecordProcesses.registerAll(instance)` (after all host tables are added) puts **Print** on every readable table, rendering a record sheet from the table's sections and child lists; `printingPrintTableList` prints a grid of any table (columns, filter, sort, page or all rows, paper and orientation); `printingPrintText` prints text such as a screen capture. Opt a table out with `PrintingTableSettings().withPrintable(false)`. Each returns the queued job id in `printingJobIds`. + The returned ID identifies durable queue acceptance. Check job status asynchronously. The [protocol v1 specification](https://github.com/QRun-IO/qqq-print-protocol/blob/f977bd01b62ceb7539190fd2861809537fcf504c/README.md) defines HTTP endpoints, JSON fields, integrity checks and lifecycle semantics. For durable QQQ jobs register `PrintEnqueueEffectTarget` as an `IDEMPOTENT_EXTERNAL` target in `DurableJobsMetaData`, then emit the submit-request payload. The target replaces the payload idempotency key with the durable effect key. Its SENT result means accepted into the queue, not physical output. This implementation uses its own JDBC transaction; do not register it as LOCAL_TX. Authorize the destination in the emitting process before writing the effect. QQQ's durable dispatcher runs with a `QSystemUserSession` and does not propagate the user's tenant keys. For that trusted outbox path only, the target resolves the service configured on the dispatcher's current QQQ instance; that service fixes the tenant and rejects devices belonging to another tenant. The payload cannot choose a service or tenant. A cached target resolves the current instance on every call. Inline user calls retain the `printing_tenant` scope check, and native management processes (including enrollment) still require both administrator permission and matching tenant scope. Do not expose direct effect emission through an arbitrary user-supplied target/payload endpoint. @@ -130,7 +159,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 +172,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. diff --git a/SECURITY.md b/SECURITY.md index a2981d7..b16f725 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -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. diff --git a/dev/AUTHENTIK.md b/dev/AUTHENTIK.md new file mode 100644 index 0000000..642f91e --- /dev/null +++ b/dev/AUTHENTIK.md @@ -0,0 +1,115 @@ +# Local Authentik reference + +Run the optional real-provider checks with Docker Compose and PowerShell 7.4+. +The pinned fixture images use Linux/amd64; other hosts need Docker's corresponding +Linux-container support or emulation: + +```powershell +pwsh ./dev/Invoke-Dev.ps1 -Action Test -Authentik +``` + +The command creates a fresh, owned development project, runs the normal QQQ and +MinIO smoke test plus the Authentik reference checks, then removes that project's +containers and volumes. It does not operate the installed Windows connector, +existing Docker stacks or physical printers. It needs no cloud account. + +For an environment that remains available for development, use `-Action Start` +with an explicit `-StateDirectory` outside the checkout. Use that same directory +with `-Action Test -Authentik`, then `-Action Stop` when finished. Stop destroys +only that owned project's synthetic databases and objects; retained private +reports are separate. See the [development command](Invoke-Dev.ps1) for port +overrides. Authentik defaults to `http://127.0.0.1:19010`; +its database port is not published. The QQQ host remains on standard TABLE +authentication. + +## What the automated check establishes + +- Real Authentik 2026.8.5 starts with a separate PostgreSQL 16 Alpine database. +- A synthetic confidential OAuth provider/application and development user are + configured through Authentik's API. The callback list is explicit and grants + are limited to authorization code and refresh. Access/refresh validity is + two/ten minutes for a future bounded renewal test. +- Actual provider discovery has the expected issuer, same-origin endpoints and + S256 capability. A valid state/S256 request with the registered callback + continues to the provider login flow without following it. Changing only that + callback to an unregistered redirect is rejected before any user login. +- The current QQQ RC.20 host advertises UI API 1.8 without `nativeSessionLogin`. + That expected absence is recorded as a native-client prerequisite failure, + not silently replaced by bearer authentication or an unpublished core. + +`auth-result.json` distinguishes those checks from browser login, renewal and +the Windows callback, which are **not run**. Provider setup/discovery is not an +OIDC user-session integration test. No password login dialog is automated. + +## Credentials and ownership + +The common entrypoint creates a protected state directory outside the checkout. +`Invoke-Authentik.ps1 -Action Initialize` appends only its `AUTHENTIK_*` settings +to `compose.env`, preserving the QQQ/MinIO settings. It records synthetic +credentials in private `auth-secrets.json`; neither file belongs in Git, a bug +report or terminal output. Bootstrap uses a Django password hash. The temporary +bootstrap API token remains confined to this disposable project and disappears +with its database at cleanup. Do not reuse these accounts outside the fixture. + +The Docker administrator can inspect container configuration. The scripts do not +print credentials or provider error bodies, follow redirects with an API token, +or request raw container logs. HTTP reads have a 15-second cancellation deadline +and a 512 KiB response limit. Startup has a bounded readiness loop. Initializer +replays retain credentials; conflicting or partial state is refused. + +Compose pins cached/public image digests, not floating tags: + + + +| Component | Image digest | +| --- | --- | +| Authentik server/worker 2026.8.5 | `ghcr.io/goauthentik/server@sha256:602227a86455d6772e3d16b7d852713c4f864f40df5df894abd1285bb53979a5` | +| PostgreSQL 16 Alpine | `postgres@sha256:721873c34ceb9f8d8fc265984940dc982404c105f19ad51be9fdc5970a6080ea` | + + + +There is no Redis requirement for this Authentik version, Docker socket mount, +outpost management, shared volume or automatic restart policy. Container and +volume labels identify the exact generated Compose project. The common cleanup +checks those labels before removing resources; it never performs a global prune. + +## Separate native-session qualification + +The Windows native path requires the centrally defined API 1.9 typed +`AUTHORIZATION_CODE_PKCE_SESSION` grant and trusted HTTPS on both QQQ and provider +origins. RC.20 does not supply that grant, and this HTTP development profile does +not weaken the client's HTTPS rules. The synthetic reference callback is only a +provider configuration value; no callback receiver or QQQ OAuth adapter is +claimed here. The TABLE host and installed pairing are unchanged. + +The separate [experimental native profile](native-auth/README.md) builds an exact +public, unreleased QQQ candidate inside Docker and uses private container-only +HTTPS trust. On 2026-11-01 it passed actual provider login, native permission +denials, logout replay rejection, renewal after expiry and provider revocation +with the production Core client. Its synthetic HTTP driver and HTTPS callback +receiver do not qualify the installed Windows browser UI or private URI callback. + +Production adoption still requires a compatible published central artifact +tuple. Provider refresh tokens stay on the server. The short lifetime test does +not prove months or years of unattended use. Do not route the private Windows +callback to a live companion whose connection must remain intact. + +The setup follows the official [2026.8 Compose definition](https://goauthentik.io/version/2026.8/lifecycle/container/compose.yml), +[bootstrap contract](https://docs.goauthentik.io/install-config/automated-install/) +and [OAuth provider contract](https://docs.goauthentik.io/add-secure-apps/providers/oauth2/). +The repository supplies the repeatable local setup; provider/browser acceptance +is reported separately from TABLE authentication and printing workload tests. + +## Initializer regression tests + +With Pester 5 available, run `dev/tests/Authentik.Tests.ps1`. They use temporary +files only: no Docker, HTTP, installed service or registry access is required. +Disable Pester's unrelated registry fixture on Windows: + +```powershell +$configuration = New-PesterConfiguration +$configuration.Run.Path = './dev/tests/Authentik.Tests.ps1' +$configuration.Run.Exit = $true +$configuration.TestRegistry.Enabled = $false +Invoke-Pester -Configuration $configuration +``` diff --git a/dev/Dockerfile.client b/dev/Dockerfile.client new file mode 100644 index 0000000..b2ac6bd --- /dev/null +++ b/dev/Dockerfile.client @@ -0,0 +1,19 @@ +# Copyright 2026 Kingsrook, LLC +# SPDX-License-Identifier: Apache-2.0 + +FROM mcr.microsoft.com/dotnet/sdk:10.0@sha256:de4fe90a98845d75910b9769662465c84de1a934665c431279d1382b2bddc02b AS build +# Exact reviewed published Core source; no workstation DLL or mutable branch. +ADD --checksum=sha256:82fcdbf7240760939a63b219aeb15a2333b3a8a02b52307a8a328500fca71fb6 https://github.com/QRun-IO/qqq-print-agent/archive/346fc285198908c47a2ee9db7b9adb53d5e88c3c.tar.gz /tmp/client.tar.gz +RUN mkdir /client && tar -xzf /tmp/client.tar.gz -C /client --strip-components=1 && rm /tmp/client.tar.gz +RUN dotnet build /client/src/Qqq.PrintAgent.Core/Qqq.PrintAgent.Core.csproj -c Release -p:Platform=x64 -p:Version=0.3.1-rc.1 -p:RestoreLockedMode=true --nologo +RUN mkdir /core && cp /client/src/Qqq.PrintAgent.Core/bin/x64/Release/net10.0/Qqq.PrintAgent.Core.dll /core/ +WORKDIR /fixture +COPY dev/client . +RUN dotnet build -c Release --nologo -o /out +RUN dotnet /out/Workload.dll --check-discovery +# SDK image is reused deliberately: one pinned image, no hidden host SDK dependency. +FROM mcr.microsoft.com/dotnet/sdk:10.0@sha256:de4fe90a98845d75910b9769662465c84de1a934665c431279d1382b2bddc02b +WORKDIR /app +COPY --from=build /out . +ENV DOTNET_EnableDiagnostics=0 +ENTRYPOINT ["dotnet","/app/Workload.dll"] diff --git a/dev/Dockerfile.server b/dev/Dockerfile.server new file mode 100644 index 0000000..6a1ced3 --- /dev/null +++ b/dev/Dockerfile.server @@ -0,0 +1,26 @@ +# Copyright 2026 Kingsrook, LLC +# SPDX-License-Identifier: Apache-2.0 + +FROM maven:3.9.11-eclipse-temurin-21@sha256:6fdc855a6ed81d288ca7ca37ac6ff5e9308b612485c0801d70b25a858c83d237 AS build +WORKDIR /source +COPY pom.xml mvnw ./ +COPY .mvn .mvn +COPY checkstyle checkstyle +COPY src src +COPY LICENSE NOTICE ./ +RUN chmod +x mvnw && ./mvnw -B -Pui-demo -DskipTests package dependency:copy-dependencies -DincludeScope=runtime -DoutputDirectory=target/runtime +COPY dev/java /fixture-src +RUN mkdir -p /fixture-classes && javac -proc:none -cp 'target/classes:target/runtime/*' -d /fixture-classes /fixture-src/*.java + +FROM eclipse-temurin:21-jdk-jammy@sha256:742daacb9316be4b6fc60258f6e4ac2a11882f6c597373c92290a57bfad0d2e0 +ARG SOURCE_COMMIT=unknown +ENV PRINTING_SOURCE_COMMIT=$SOURCE_COMMIT +WORKDIR /app +COPY --from=build /source/target/classes classes +COPY --from=build /source/target/runtime lib +COPY --from=build /fixture-classes fixture +COPY dev/log4j2.xml /app/log4j2.xml +COPY dev/run-tests.sh /app/run-tests.sh +RUN chmod 0555 /app/run-tests.sh +ENTRYPOINT ["java","-Xmx768m","-Dlog4j.configurationFile=/app/log4j2.xml","-cp","/app/classes:/app/lib/*:/app/fixture"] +CMD ["com.kingsrook.qbits.printing.DevHost"] diff --git a/dev/Invoke-Authentik.ps1 b/dev/Invoke-Authentik.ps1 new file mode 100644 index 0000000..b911fd6 --- /dev/null +++ b/dev/Invoke-Authentik.ps1 @@ -0,0 +1,397 @@ +#Requires -Version 7.4 +# Copyright 2026 Kingsrook, LLC +# SPDX-License-Identifier: Apache-2.0 + +<# +.SYNOPSIS +Prepares or checks the optional, owned Authentik development fixture. +.DESCRIPTION +Initialize only writes private state. Test configures a fresh synthetic provider +and checks its real HTTP discovery and rejection boundary; it never automates a +user login or changes QQQ authentication. The common development entrypoint owns +all Docker lifecycle operations. Provider response bodies and secrets are never +printed, including on errors. +#> +[CmdletBinding()] +param( + [Parameter(Mandatory)][ValidateSet('Initialize', 'Test')][string] $Action, + [Parameter(Mandatory)][string] $StateDirectory, + [Parameter(Mandatory)][ValidatePattern('^qbit-printing-dev-[a-z0-9-]{8,48}$')][string] $ProjectName, + [ValidateRange(1024, 65535)][int] $Port = 19010, + [ValidateRange(10, 300)][int] $ReadyTimeoutSeconds = 180 +) + +Set-StrictMode -Version Latest +$ErrorActionPreference = 'Stop' + +<# .SYNOPSIS Generates a private random value without placing it on a command line. #> +function Get-FixtureSecret +{ + [Convert]::ToBase64String([Security.Cryptography.RandomNumberGenerator]::GetBytes(32)).TrimEnd('=').Replace('+', '-').Replace('/', '_') +} + +<# .SYNOPSIS Limits the helper to an existing state directory outside the checkout. #> +function Get-FixtureState +{ + param([string] $Directory) + $state = [IO.Path]::GetFullPath($Directory) + $repository = [IO.Path]::GetFullPath((Join-Path $PSScriptRoot '..')) + $comparison = if($IsWindows) { [StringComparison]::OrdinalIgnoreCase } else { [StringComparison]::Ordinal } + if($state.Equals($repository, $comparison) -or $state.StartsWith($repository + [IO.Path]::DirectorySeparatorChar, $comparison)) + { + throw 'Development secrets must be outside the source checkout.' + } + if(-not (Test-Path -LiteralPath $state -PathType Container) -or -not (Test-Path -LiteralPath (Join-Path $state 'compose.env') -PathType Leaf)) + { + throw 'The common development entrypoint must create protected state and compose.env first.' + } + $ancestor = [IO.DirectoryInfo]::new($state) + while($null -ne $ancestor) + { + if(($ancestor.Attributes -band [IO.FileAttributes]::ReparsePoint) -ne 0) + { + throw 'Development state cannot use a symbolic link or reparse point.' + } + $ancestor = $ancestor.Parent + } + return $state +} + +<# .SYNOPSIS Reads private configuration without echoing malformed JSON or credential values. #> +function Get-FixtureConfiguration +{ + param([string] $Path) + try + { + $value = Get-Content -LiteralPath $Path -Raw | ConvertFrom-Json -AsHashtable + foreach($field in @('project', 'port', 'adminPassword', 'bootstrapToken', 'clientId', 'clientSecret', 'username', 'userPassword')) + { + if(-not $value.ContainsKey($field) -or $null -eq $value[$field]) { throw 'Missing field.' } + } + return $value + } + catch { throw 'The private Authentik configuration is unreadable or incomplete; its contents are withheld.' } +} + +<# .SYNOPSIS Performs bounded same-origin HTTP without redirects or response-body diagnostics. #> +function Invoke-FixtureHttp +{ + param( + [Parameter(Mandatory)][Net.Http.HttpClient] $Client, + [Parameter(Mandatory)][string] $Path, + [ValidateSet('GET', 'POST')][string] $Method = 'GET', + [object] $Body, + [string] $Token, + [int[]] $ExpectedStatus = @(200) + ) + if(-not $Path.StartsWith('/', [StringComparison]::Ordinal) -or $Path.StartsWith('//', [StringComparison]::Ordinal)) + { + throw 'Only an absolute path on the fixture origin is permitted.' + } + $request = [Net.Http.HttpRequestMessage]::new([Net.Http.HttpMethod]::new($Method), $Path) + $timeout = [Threading.CancellationTokenSource]::new([TimeSpan]::FromSeconds(15)) + $response = $null + $status = 0 + try + { + if($Token) + { + $request.Headers.Authorization = [Net.Http.Headers.AuthenticationHeaderValue]::new('Bearer', $Token) + } + if($null -ne $Body) + { + $request.Content = [Net.Http.StringContent]::new(($Body | ConvertTo-Json -Depth 12 -Compress), [Text.Encoding]::UTF8, 'application/json') + } + $response = $Client.SendAsync($request, [Net.Http.HttpCompletionOption]::ResponseHeadersRead, $timeout.Token).GetAwaiter().GetResult() + $status = [int]$response.StatusCode + if($status -notin $ExpectedStatus) + { + throw "Fixture HTTP status $status was not expected. Response content is withheld." + } + $stream = $response.Content.ReadAsStreamAsync($timeout.Token).GetAwaiter().GetResult() + $bytes = [IO.MemoryStream]::new() + try + { + $buffer = [byte[]]::new(8192) + while(($read = $stream.ReadAsync($buffer, 0, $buffer.Length, $timeout.Token).GetAwaiter().GetResult()) -gt 0) + { + if($bytes.Length + $read -gt 524288) + { + throw 'Fixture response exceeded the 512 KiB limit.' + } + $bytes.Write($buffer, 0, $read) + } + $text = [Text.Encoding]::UTF8.GetString($bytes.ToArray()) + $data = if($text.Length -gt 0 -and $response.Content.Headers.ContentType.MediaType -eq 'application/json') + { + ConvertFrom-Json -InputObject $text -AsHashtable + } + else { $null } + return @{ Status = $status; Data = $data; Location = $response.Headers.Location } + } + finally + { + $bytes.Dispose() + $stream.Dispose() + } + } + catch + { + # The failing API may contain passwords/tokens in its error response. + $operation = [uri]::new($Client.BaseAddress, $Path).AbsolutePath + throw "Fixture $Method $operation failed (HTTP $status; 0 means no response). Response content and authentication values are withheld." + } + finally + { + if($null -ne $response) { $response.Dispose() } + $request.Dispose() + $timeout.Dispose() + } +} + +<# .SYNOPSIS Requires one exact default object rather than choosing an arbitrary provider resource. #> +function Get-FixtureObject +{ + param([Net.Http.HttpClient] $Client, [string] $Path, [string] $Token) + $page = (Invoke-FixtureHttp -Client $Client -Path $Path -Token $Token).Data + if($null -eq $page -or $page.results.Count -ne 1) + { + throw 'A required Authentik default object is missing or ambiguous.' + } + return $page.results[0] +} + +$state = Get-FixtureState -Directory $StateDirectory +$envPath = Join-Path $state 'compose.env' +$secretPath = Join-Path $state 'auth-secrets.json' +foreach($path in @($envPath, $secretPath)) +{ + if((Test-Path -LiteralPath $path) -and ((Get-Item -LiteralPath $path -Force).Attributes -band [IO.FileAttributes]::ReparsePoint) -ne 0) + { + throw 'Development configuration cannot use a symbolic link or reparse point.' + } +} +if($Action -eq 'Initialize') +{ + if(Test-Path -LiteralPath $secretPath) + { + $existing = Get-FixtureConfiguration -Path $secretPath + if($existing.project -ne $ProjectName -or $existing.port -ne $Port) + { + throw 'Existing Authentik state belongs to a different project or port.' + } + $existingEnvironment = Get-Content -LiteralPath $envPath -Raw + foreach($key in @('AUTHENTIK_HTTP_PORT', 'AUTHENTIK_POSTGRES_PASSWORD', 'AUTHENTIK_SECRET_KEY', 'AUTHENTIK_BOOTSTRAP_PASSWORD_HASH', 'AUTHENTIK_BOOTSTRAP_TOKEN')) + { + if([regex]::Matches($existingEnvironment, '(?m)^' + $key + '=').Count -ne 1) + { + throw 'The private Authentik environment is incomplete or ambiguous; use a fresh owned state directory.' + } + } + return + } + $contents = Get-Content -LiteralPath $envPath -Raw + if($contents -match '(?m)^AUTHENTIK_') + { + throw 'Partial Authentik initialization exists. Use a fresh owned state directory.' + } + $adminPassword = Get-FixtureSecret + $salt = Get-FixtureSecret + $passwordHash = [Convert]::ToBase64String([Security.Cryptography.Rfc2898DeriveBytes]::Pbkdf2($adminPassword, [Text.Encoding]::UTF8.GetBytes($salt), 1000000, [Security.Cryptography.HashAlgorithmName]::SHA256, 32)) + $secrets = [ordered]@{ + project = $ProjectName + port = $Port + adminPassword = $adminPassword + bootstrapToken = Get-FixtureSecret + clientId = $ProjectName + clientSecret = Get-FixtureSecret + username = 'printing-developer' + userPassword = Get-FixtureSecret + } + $secrets | ConvertTo-Json | Set-Content -LiteralPath $secretPath -Encoding utf8 + $values = [ordered]@{ + AUTHENTIK_HTTP_PORT = $Port + AUTHENTIK_POSTGRES_PASSWORD = Get-FixtureSecret + AUTHENTIK_SECRET_KEY = Get-FixtureSecret + AUTHENTIK_BOOTSTRAP_PASSWORD_HASH = 'pbkdf2_sha256$1000000$' + $salt + '$' + $passwordHash + AUTHENTIK_BOOTSTRAP_TOKEN = $secrets.bootstrapToken + } + # Single quotes preserve the dollar signs in Django's password hash. + $lines = @('') + @($values.GetEnumerator() | ForEach-Object { $_.Key + "='" + $_.Value + "'" }) + Add-Content -LiteralPath $envPath -Value $lines -Encoding utf8 + if(-not $IsWindows) + { + [IO.File]::SetUnixFileMode($secretPath, [IO.UnixFileMode]::UserRead -bor [IO.UnixFileMode]::UserWrite) + } + return +} + +$secrets = Get-FixtureConfiguration -Path $secretPath +if($secrets.project -cne $ProjectName -or $secrets.port -ne $Port -or $secrets.clientId -cne $ProjectName -or $secrets.username -cne 'printing-developer') +{ + throw 'Authentik state does not match the owned development project.' +} +$handler = [Net.Http.HttpClientHandler]::new() +$handler.AllowAutoRedirect = $false +$handler.UseProxy = $false +$handler.UseCookies = $false +$client = [Net.Http.HttpClient]::new($handler) +$client.BaseAddress = [uri]"http://127.0.0.1:$Port" +$client.Timeout = [Threading.Timeout]::InfiniteTimeSpan +try +{ + $deadline = [DateTimeOffset]::UtcNow.AddSeconds($ReadyTimeoutSeconds) + $ready = $false + do + { + try + { + $authorization = Get-FixtureObject -Client $client -Path '/api/v3/flows/instances/?slug=default-provider-authorization-implicit-consent' -Token $secrets.bootstrapToken + $invalidation = Get-FixtureObject -Client $client -Path '/api/v3/flows/instances/?slug=default-provider-invalidation-flow' -Token $secrets.bootstrapToken + $ready = $true + } + catch + { + if([DateTimeOffset]::UtcNow -ge $deadline) { throw 'Authentik did not become ready before the bounded startup deadline.' } + Start-Sleep -Seconds 1 + } + } while(-not $ready) + + $mappingIds = @(foreach($scope in @('openid', 'profile', 'email', 'offline_access')) + { + (Get-FixtureObject -Client $client -Path "/api/v3/propertymappings/provider/scope/?scope_name=$scope" -Token $secrets.bootstrapToken).pk + }) + $providerPage = (Invoke-FixtureHttp -Client $client -Path ('/api/v3/providers/oauth2/?client_id=' + $secrets.clientId) -Token $secrets.bootstrapToken).Data + $callback = "http://127.0.0.1:$Port/reference-callback/" + if($providerPage.results.Count -eq 0) + { + $provider = (Invoke-FixtureHttp -Client $client -Method POST -Path '/api/v3/providers/oauth2/' -Token $secrets.bootstrapToken -ExpectedStatus @(201) -Body @{ + name = $ProjectName + authorization_flow = $authorization.pk + invalidation_flow = $invalidation.pk + client_type = 'confidential' + grant_types = @('authorization_code', 'refresh_token') + client_id = $secrets.clientId + client_secret = $secrets.clientSecret + access_code_validity = 'minutes=1' + access_token_validity = 'minutes=2' + refresh_token_validity = 'minutes=10' + redirect_uris = @(@{ matching_mode = 'strict'; url = $callback }) + property_mappings = $mappingIds + issuer_mode = 'per_provider' + }).Data + } + elseif($providerPage.results.Count -eq 1) + { + $provider = $providerPage.results[0] + if($provider.name -ne $ProjectName) { throw 'The fixture provider identity changed.' } + } + else { throw 'The fixture provider identity is ambiguous.' } + if($provider.redirect_uris.Count -ne 1 -or $provider.redirect_uris[0].matching_mode -cne 'strict' -or + $provider.redirect_uris[0].url -cne $callback -or $provider.client_type -cne 'confidential' -or + $provider.access_token_validity -cne 'minutes=2' -or $provider.refresh_token_validity -cne 'minutes=10' -or + (@($provider.grant_types | Sort-Object) -join ',') -cne 'authorization_code,refresh_token' -or + @($mappingIds | Where-Object { $_ -notin $provider.property_mappings }).Count -ne 0) + { + throw 'The existing provider configuration differs from the bounded reference settings.' + } + + $applicationPage = (Invoke-FixtureHttp -Client $client -Path ('/api/v3/core/applications/?slug=' + $ProjectName) -Token $secrets.bootstrapToken).Data + if($applicationPage.results.Count -eq 0) + { + $null = Invoke-FixtureHttp -Client $client -Method POST -Path '/api/v3/core/applications/' -Token $secrets.bootstrapToken -ExpectedStatus @(201) -Body @{ name = $ProjectName; slug = $ProjectName; provider = $provider.pk; policy_engine_mode = 'all' } + } + elseif($applicationPage.results.Count -ne 1 -or $applicationPage.results[0].provider -ne $provider.pk) + { + throw 'The fixture application does not match its provider.' + } + $userPage = (Invoke-FixtureHttp -Client $client -Path ('/api/v3/core/users/?username=' + $secrets.username) -Token $secrets.bootstrapToken).Data + if($userPage.results.Count -eq 0) + { + $user = (Invoke-FixtureHttp -Client $client -Method POST -Path '/api/v3/core/users/' -Token $secrets.bootstrapToken -ExpectedStatus @(201) -Body @{ username = $secrets.username; name = 'Printing development user'; email = 'printing-developer@example.invalid'; is_active = $true; type = 'internal' }).Data + } + elseif($userPage.results.Count -eq 1) + { + $user = $userPage.results[0] + if($user.name -cne 'Printing development user') { throw 'The synthetic user identity changed.' } + } + else { throw 'The synthetic user identity is ambiguous.' } + # Reusing the same generated value also recovers an interrupted first setup. + $null = Invoke-FixtureHttp -Client $client -Method POST -Path ("/api/v3/core/users/$($user.pk)/set_password/") -Token $secrets.bootstrapToken -ExpectedStatus @(204) -Body @{ password = $secrets.userPassword } + + $issuer = "http://127.0.0.1:$Port/application/o/$ProjectName/" + $discovery = (Invoke-FixtureHttp -Client $client -Path "/application/o/$ProjectName/.well-known/openid-configuration").Data + if($discovery.issuer -cne $issuer -or 'S256' -notin $discovery.code_challenge_methods_supported) + { + throw 'The real provider discovery does not match the fixture issuer and S256 capability.' + } + foreach($endpoint in @('authorization_endpoint', 'token_endpoint', 'userinfo_endpoint', 'jwks_uri')) + { + $uri = [uri]$discovery[$endpoint] + if($uri.GetLeftPart([UriPartial]::Authority) -cne "http://127.0.0.1:$Port") + { + throw 'Provider discovery returned an endpoint outside the fixture origin.' + } + } + $verifier = Get-FixtureSecret + $challenge = [Convert]::ToBase64String([Security.Cryptography.SHA256]::HashData([Text.Encoding]::ASCII.GetBytes($verifier))).TrimEnd('=').Replace('+', '-').Replace('/', '_') + $stateValue = Get-FixtureSecret + $authorize = "/application/o/authorize/?client_id=$($secrets.clientId)&response_type=code&scope=openid%20profile%20email%20offline_access&state=$stateValue&code_challenge=$challenge&code_challenge_method=S256&prompt=login&redirect_uri=" + $accepted = Invoke-FixtureHttp -Client $client -Path ($authorize + [uri]::EscapeDataString($callback)) -ExpectedStatus @(302, 303) + if($null -eq $accepted.Location) + { + throw 'The registered redirect did not continue to the real provider login flow.' + } + $login = [uri]::new($client.BaseAddress, $accepted.Location) + if($login.GetLeftPart([UriPartial]::Authority) -cne "http://127.0.0.1:$Port" -or -not $login.AbsolutePath.StartsWith('/if/flow/', [StringComparison]::Ordinal)) + { + throw 'The registered redirect did not continue to the same-origin provider login flow.' + } + # Change only the callback: a generic malformed authorization request is not proof. + $invalidRedirect = [uri]::EscapeDataString("http://127.0.0.1:$Port/not-registered/") + $null = Invoke-FixtureHttp -Client $client -Path ($authorize + $invalidRedirect) -ExpectedStatus @(400) + $qqqPortMatch = [regex]::Match((Get-Content -LiteralPath $envPath -Raw), '(?m)^QQQ_HTTP_PORT=[''"]?(\d+)[''"]?\s*$') + if(-not $qqqPortMatch.Success) { throw 'The common environment has no QQQ HTTP port.' } + $qqqHandler = [Net.Http.HttpClientHandler]::new() + $qqqHandler.AllowAutoRedirect = $false + $qqqHandler.UseProxy = $false + $qqqClient = [Net.Http.HttpClient]::new($qqqHandler) + try + { + $qqqClient.BaseAddress = [uri]("http://127.0.0.1:" + $qqqPortMatch.Groups[1].Value) + $qqqClient.Timeout = [Threading.Timeout]::InfiniteTimeSpan + $qqqClient.DefaultRequestHeaders.Add('X-QQQ-Client', 'api/printing-dev-reference') + $version = (Invoke-FixtureHttp -Client $qqqClient -Path '/qqq/v1/version').Data + } + finally { $qqqClient.Dispose() } + if($version.apiVersion -ne '1.8.0' -or 'nativeSessionLogin' -in $version.features) + { + throw 'The core capability baseline changed; review the Authentik qualification scope before proceeding.' + } + [ordered]@{ + status = 'PASS' + observedUtc = [DateTimeOffset]::UtcNow.ToString('O') + project = $ProjectName + providerOrigin = "http://127.0.0.1:$Port" + providerVersion = '2026.8.5' + discovery = 'PASS' + registeredRedirect = 'LOGIN_REQUIRED' + unregisteredRedirect = 'REJECTED' + qqqApiVersion = $version.apiVersion + nativeSessionLogin = 'UNAVAILABLE_EXPECTED' + browserLogin = 'NOT_RUN_OPERATOR_REQUIRED' + renewal = 'NOT_RUN' + windowsCallback = 'NOT_RUN_REQUIRES_QUALIFIED_CORE_AND_HTTPS' + } | ConvertTo-Json | Set-Content -LiteralPath (Join-Path $state 'auth-result.json') -Encoding utf8 + Write-Output 'Authentik reference discovery and redirect rejection passed; QQQ native browser login remains unavailable on RC.20.' +} +catch +{ + @{ status = 'FAILED'; observedUtc = [DateTimeOffset]::UtcNow.ToString('O'); project = $ProjectName; message = 'Reference checks failed; no browser or native-login success is claimed.' } | + ConvertTo-Json | Set-Content -LiteralPath (Join-Path $state 'auth-result.json') -Encoding utf8 + throw +} +finally +{ + $client.Dispose() +} diff --git a/dev/Invoke-Dev.ps1 b/dev/Invoke-Dev.ps1 new file mode 100644 index 0000000..83dd9be --- /dev/null +++ b/dev/Invoke-Dev.ps1 @@ -0,0 +1,502 @@ +#Requires -Version 7.4 +# Copyright 2026 Kingsrook, LLC +# SPDX-License-Identifier: Apache-2.0 + +<# +.SYNOPSIS +Starts, tests, or removes one owned local Docker printing environment. +.DESCRIPTION +Uses synthetic accounts and documents. Never imports installed device credentials, +contacts printers, changes host trust, or prunes shared Docker resources. +#> +[CmdletBinding()] +param( + [ValidateSet('Start', 'Test', 'Stop')][string]$Action = 'Test', + [string]$StateDirectory, + [switch]$Authentik, + [switch]$ExperimentalNativeAuth, + [ValidateSet(40, 10000)][int]$Workload = 40, + [ValidateRange(1024, 65535)][int]$QqqPort = 19081, + [ValidateRange(1024, 65535)][int]$MinioPort = 19095, + [ValidateRange(1024, 65535)][int]$AuthentikPort = 19010 +) +$ErrorActionPreference = 'Stop' +Set-StrictMode -Version Latest +$sourceRoot = [IO.Path]::GetFullPath((Join-Path $PSScriptRoot '..')) +$ephemeral = $Action -eq 'Test' -and [string]::IsNullOrWhiteSpace($StateDirectory) +if ($ExperimentalNativeAuth) +{ + if ($Action -ne 'Test') + { + throw 'Experimental native authentication is a disposable Test-only profile.' + } + $Authentik = $true +} + +function Assert-StateLocation([string]$Path) +{ + <# .SYNOPSIS Rejects links before any private state is read or written. #> + $ancestor = [IO.DirectoryInfo]::new($Path) + while ($null -ne $ancestor) + { + if (![string]::IsNullOrEmpty($ancestor.LinkTarget) -or ($ancestor.Exists -and ($ancestor.Attributes -band [IO.FileAttributes]::ReparsePoint) -ne 0)) + { + throw 'Development state cannot use a symbolic link or reparse point.' + } + $ancestor = $ancestor.Parent + } + foreach ($name in @('owner.json', 'compose.env', 'compose.yaml', 'compose.authentik.yaml', 'compose.native-auth.yaml', 'auth-secrets.json', 'qqq-result.json', 'auth-result.json', 'native-input.json', 'native-auth-result.json', 'native-auth-server-errors.json')) + { + $file = [IO.FileInfo]::new((Join-Path $Path $name)) + if (![string]::IsNullOrEmpty($file.LinkTarget) -or ($file.Exists -and ($file.Attributes -band [IO.FileAttributes]::ReparsePoint) -ne 0)) + { + throw 'Development state files cannot use symbolic links or reparse points.' + } + } +} +function Get-RecordedAuthentikPort +{ + <# .SYNOPSIS Restores the existing environment port without reading it from caller defaults. #> + $lines = @(Get-Content -LiteralPath $script:envFile | Where-Object { $_.StartsWith('AUTHENTIK_HTTP_PORT=', [StringComparison]::Ordinal) }) + if ($lines.Count -ne 1 -or $lines[0] -cnotmatch '^AUTHENTIK_HTTP_PORT=([0-9]{4,5})$') + { + throw 'Recorded Authentik port is missing or invalid.' + } + $port = [int]$Matches[1] + if ($port -lt 1024 -or $port -gt 65535) + { + throw 'Recorded Authentik port is outside the supported range.' + } + return $port +} +function Get-FixtureSecret +{ + <# .SYNOPSIS Generates only disposable local credentials. #> + return [Convert]::ToHexString([Security.Cryptography.RandomNumberGenerator]::GetBytes(32)) +} +function Protect-State([string]$Path) +{ + <# .SYNOPSIS Restricts the generated state to its user and local administrators. #> + if ($IsWindows) + { + $acl = [Security.AccessControl.DirectorySecurity]::new() + $acl.SetAccessRuleProtection($true, $false) + foreach ($sid in @([Security.Principal.WindowsIdentity]::GetCurrent().User, + [Security.Principal.SecurityIdentifier]::new('S-1-5-18'), [Security.Principal.SecurityIdentifier]::new('S-1-5-32-544'))) + { + $acl.AddAccessRule([Security.AccessControl.FileSystemAccessRule]::new($sid, 'FullControl', 'ContainerInherit,ObjectInherit', 'None', 'Allow')) + } + Set-Acl -LiteralPath $Path -AclObject $acl + } + else + { + [IO.File]::SetUnixFileMode($Path, [IO.UnixFileMode]::UserRead -bor [IO.UnixFileMode]::UserWrite -bor [IO.UnixFileMode]::UserExecute) + } +} +function Set-FixtureEnvironment +{ + [CmdletBinding(SupportsShouldProcess)] + param([string]$Name, [string]$Value) + <# .SYNOPSIS Updates one safe dotenv field without displaying secret values. #> + if ($Name -cnotmatch '^[A-Z_]+$' -or $Value -match '[\r\n]') + { + throw 'Unsafe generated environment field.' + } + if (!$PSCmdlet.ShouldProcess($Name, 'Write protected fixture setting')) + { + return + } + $lines = @() + if (Test-Path -LiteralPath $script:envFile) + { + $lines = @(Get-Content -LiteralPath $script:envFile | Where-Object { !$_.StartsWith($Name + '=', [StringComparison]::Ordinal) }) + } + [IO.File]::WriteAllLines($script:envFile, @($lines) + @($Name + '=' + $Value)) +} +function Invoke-Compose([string[]]$Arguments) +{ + <# .SYNOPSIS Runs only this recorded Compose project. #> + & docker compose @script:composeArguments @Arguments + if ($LASTEXITCODE -ne 0) + { + throw 'Owned Docker Compose operation failed; inspect local command output.' + } +} +function Assert-OwnedResource +{ + <# .SYNOPSIS Refuses cleanup if any project resource lacks the ownership label. #> + $ids = @(& docker ps -aq --filter "label=com.docker.compose.project=$script:project") + if ($LASTEXITCODE -ne 0) + { + throw 'Cannot inspect owned Docker containers.' + } + foreach ($id in $ids) + { + $label = & docker inspect $id --format '{{index .Config.Labels "io.qrun.printing.dev"}}' + if ($LASTEXITCODE -ne 0 -or $label -cne $script:project) + { + throw 'Container ownership mismatch; cleanup refused.' + } + } + $networks = @(& docker network ls -q --filter "label=com.docker.compose.project=$script:project") + if ($LASTEXITCODE -ne 0) + { + throw 'Cannot inspect owned Docker networks.' + } + foreach ($network in $networks) + { + $label = & docker network inspect $network --format '{{index .Labels "io.qrun.printing.dev"}}' + if ($LASTEXITCODE -ne 0 -or $label -cne $script:project) + { + throw 'Network ownership mismatch; cleanup refused.' + } + } + $volumes = @(& docker volume ls -q --filter "label=com.docker.compose.project=$script:project") + if ($LASTEXITCODE -ne 0) + { + throw 'Cannot inspect owned Docker volumes.' + } + foreach ($volume in $volumes) + { + $label = & docker volume inspect $volume --format '{{index .Labels "io.qrun.printing.dev"}}' + if ($LASTEXITCODE -ne 0 -or $label -cne $script:project) + { + throw 'Volume ownership mismatch; cleanup refused.' + } + } +} +function Stop-OwnedEnvironment +{ + [CmdletBinding(SupportsShouldProcess)] + param() + <# .SYNOPSIS Removes only this environment's containers, network and synthetic volumes. #> + if (!$PSCmdlet.ShouldProcess($script:project, 'Remove this owned development environment and its synthetic data')) + { + return + } + Assert-OwnedResource + Invoke-Compose @('--profile', 'test', '--profile', 'auth', '--profile', 'native-auth', 'down', '--remove-orphans', '--volumes', '--timeout', '30') +} +function ConvertTo-ProviderErrorSummary([string[]]$Lines) +{ + <# .SYNOPSIS Retains only exception types and bounded source-frame coordinates. #> + $types = [Collections.Generic.HashSet[string]]::new([StringComparer]::Ordinal) + $frames = [Collections.Generic.List[object]]::new() + $warnings = @{invalidClientIdentifier = $false; nonApplicableAuthenticationFlow = $false; failedToResolveApplication = $false} + foreach ($line in ($Lines | Select-Object -Last 1000)) + { + if ($line.Length -gt 65536) { continue } + $warnings.invalidClientIdentifier = $warnings.invalidClientIdentifier -or $line.Contains('Invalid client identifier', [StringComparison]::Ordinal) + $warnings.nonApplicableAuthenticationFlow = $warnings.nonApplicableAuthenticationFlow -or $line.Contains('Non-applicable authentication flow', [StringComparison]::Ordinal) + $warnings.failedToResolveApplication = $warnings.failedToResolveApplication -or $line.Contains('failed to resolve application', [StringComparison]::Ordinal) + try { $record = ConvertFrom-Json -InputObject $line -AsHashtable -ErrorAction Stop } + catch { continue } + if ($record -isnot [Collections.IDictionary]) { continue } + foreach ($exception in @($record['exception'])) + { + if ($exception -isnot [Collections.IDictionary]) { continue } + $type = [string]$exception['exc_type'] + if ($types.Count -lt 16 -and ($type -cmatch '^[A-Za-z_][A-Za-z0-9_.]{0,119}(Error|Exception)$' -or $type -cin @('PermissionDenied', 'NotAuthenticated', 'AuthenticationFailed', 'Throttled'))) { [void]$types.Add($type) } + foreach ($frame in @($exception['frames'])) + { + if ($frames.Count -ge 12 -or $frame -isnot [Collections.IDictionary]) { continue } + $filename = [string]$frame['filename'] + $function = [string]$frame['name'] + $lineNumber = 0 + if ($filename.Length -le 300 -and $filename -cmatch '^/authentik/[A-Za-z0-9_./-]+\.py$' -and + $function -cmatch '^[A-Za-z0-9_<>.]{1,120}$' -and + [int]::TryParse([string]$frame['lineno'], [ref]$lineNumber) -and $lineNumber -gt 0) + { + $frames.Add(@{filename = $filename; line = $lineNumber; function = $function}) + } + } + } + } + return @{exceptionTypes = @($types | Sort-Object); frames = @($frames.ToArray()); warnings = $warnings} +} +function Save-ProviderErrorSummary +{ + <# .SYNOPSIS Reads bounded logs only from the exact owned synthetic provider. #> + $ids = @(& docker ps -aq --filter "label=com.docker.compose.project=$script:project" --filter 'label=com.docker.compose.service=authentik-server') + if ($LASTEXITCODE -ne 0 -or $ids.Count -ne 1 -or $ids[0] -cnotmatch '^[a-f0-9]{12,64}$') { return } + $label = & docker inspect $ids[0] --format '{{index .Config.Labels "io.qrun.printing.dev"}}' + if ($LASTEXITCODE -ne 0 -or $label -cne $script:project) { throw 'Provider diagnostic ownership mismatch.' } + $lines = @(& docker logs --tail 1000 $ids[0] 2>&1 | ForEach-Object { $_.ToString() }) + if ($LASTEXITCODE -ne 0) { return } + $summary = ConvertTo-ProviderErrorSummary $lines + $lines = $null + Assert-StateLocation $StateDirectory + $summary | ConvertTo-Json -Depth 5 | Set-Content -LiteralPath (Join-Path $StateDirectory 'native-auth-server-errors.json') +} +function Wait-OwnedContainer([string]$Id, [int]$Seconds) +{ + <# .SYNOPSIS Observes bounded completion without accessing application data. #> + $deadline = [DateTime]::UtcNow.AddSeconds($Seconds) + do + { + $state = & docker inspect $Id --format '{{.State.Running}}|{{.State.ExitCode}}' + if ($LASTEXITCODE -ne 0) + { + throw 'Owned fixture container disappeared.' + } + if ($state.StartsWith('false|', [StringComparison]::Ordinal)) + { + return [int]$state.Split('|')[1] + } + Start-Sleep -Seconds 1 + } while ([DateTime]::UtcNow -lt $deadline) + throw 'Bounded fixture deadline expired; owned resources will be cleaned.' +} +function Assert-WorkloadClientSucceeded([string]$Id, [int]$ExitCode, [string]$Run, [string]$Reports) +{ + <# .SYNOPSIS Preserves private client evidence and reports only fixed failure classifications. #> + if ($ExitCode -eq 0) { return } + $stage = 'unknown' + $failureType = 'UnknownFailure' + try + { + $path = Join-Path $Reports 'result.json' + & docker cp "${Id}:/work/$Run/result.json" $path 2>&1 | Out-Null + if ($LASTEXITCODE -eq 0 -and (Test-Path -LiteralPath $path -PathType Leaf) -and (Get-Item -LiteralPath $path).Length -le 65536) + { + $result = Get-Content -LiteralPath $path -Raw | ConvertFrom-Json -AsHashtable + if ($result -is [Collections.IDictionary] -and $result['success'] -ceq $false) + { + if ($result['stage'] -is [string] -and $result['stage'] -cin @('input', 'native_login_and_channels', 'workload', 'logout')) + { + $stage = $result['stage'] + } + if ($result['error'] -is [string] -and $result['error'] -cin @('QqqSessionException', 'HttpRequestException', 'IOException', 'InvalidDataException', 'JsonException', 'OperationCanceledException', 'TaskCanceledException', 'UnauthorizedAccessException', 'WebSocketException', 'TimeoutException', 'InvalidOperationException')) + { + $failureType = $result['error'] + } + } + } + } + catch + { + # Missing or malformed diagnostics must not hide the failed client or expose raw exception text. + $stage = 'unknown' + $failureType = 'UnknownFailure' + } + throw "Workload client failed at $stage ($failureType); see protected results." +} + +if ([string]::IsNullOrWhiteSpace($StateDirectory)) +{ + if ($Action -eq 'Stop') + { + throw 'Stop requires the state directory printed by Start.' + } + $base = if ($IsWindows) + { + Join-Path $env:LOCALAPPDATA 'QQQ/PrintingDevelopment' + } + else + { + Join-Path $HOME '.local/state/qqq-printing-development' + } + $StateDirectory = Join-Path $base ('environment-' + [Guid]::NewGuid().ToString('N')) +} +$StateDirectory = [IO.Path]::GetFullPath($StateDirectory) +if ($StateDirectory.StartsWith($sourceRoot + [IO.Path]::DirectorySeparatorChar, [StringComparison]::OrdinalIgnoreCase)) +{ + throw 'Keep secret state outside the repository.' +} +Assert-StateLocation $StateDirectory +$ownerFile = Join-Path $StateDirectory 'owner.json' +$script:envFile = Join-Path $StateDirectory 'compose.env' +$createdState = $false +if (Test-Path -LiteralPath $StateDirectory) +{ + if (!(Test-Path -LiteralPath $ownerFile)) + { + throw 'Existing state directory lacks this tool ownership record.' + } + $owner = Get-Content -LiteralPath $ownerFile -Raw | ConvertFrom-Json + if ($owner.sourceRoot -cne $sourceRoot -or $owner.project -cnotmatch '^qbit-printing-dev-[a-f0-9]{32}$') + { + throw 'State ownership mismatch.' + } + $script:project = $owner.project + $Authentik = [bool]$owner.authentik + $savedNativeProfile = $null -ne $owner.PSObject.Properties['experimentalNativeAuth'] -and [bool]$owner.experimentalNativeAuth + if ($ExperimentalNativeAuth -and !$savedNativeProfile) + { + throw 'An existing standard environment cannot be repurposed for experimental native authentication.' + } + $ExperimentalNativeAuth = $savedNativeProfile + if ($ExperimentalNativeAuth -and $Action -eq 'Start') + { + throw 'Experimental native authentication is a disposable Test-only profile.' + } +} +else +{ + if ($Action -eq 'Stop') + { + throw 'Owned state directory does not exist.' + } + [IO.Directory]::CreateDirectory($StateDirectory) | Out-Null + Protect-State $StateDirectory + $createdState = $true + $script:project = 'qbit-printing-dev-' + [Guid]::NewGuid().ToString('N') + $commit = (& git -C $sourceRoot rev-parse HEAD).Trim() + if ($LASTEXITCODE -ne 0 -or $commit -cnotmatch '^[a-f0-9]{40}$') + { + throw 'Cannot record source identity.' + } + foreach ($field in @{PRINTING_DEV_PROJECT = $project; DEV_SOURCE_DIR = $sourceRoot.Replace('\', '/'); SOURCE_COMMIT = $commit; QQQ_HTTP_PORT = "$QqqPort"; MINIO_HTTP_PORT = "$MinioPort"; MINIO_ROOT_USER = 'printing-development'; MINIO_ROOT_PASSWORD = (Get-FixtureSecret); QQQ_DATABASE_PASSWORD = (Get-FixtureSecret); QQQ_ADMIN_PASSWORD = (Get-FixtureSecret); QQQ_MANAGEMENT_TOKEN = (Get-FixtureSecret) }.GetEnumerator()) + { + Set-FixtureEnvironment $field.Key $field.Value + } + Copy-Item -LiteralPath (Join-Path $PSScriptRoot 'compose.yaml') -Destination (Join-Path $StateDirectory 'compose.yaml') + if ($Authentik) + { + & (Join-Path $PSScriptRoot 'Invoke-Authentik.ps1') -Action Initialize -StateDirectory $StateDirectory -ProjectName $project -Port $AuthentikPort + Copy-Item -LiteralPath (Join-Path $PSScriptRoot 'compose.authentik.yaml') -Destination (Join-Path $StateDirectory 'compose.authentik.yaml') + } + if ($ExperimentalNativeAuth) + { + & (Join-Path $PSScriptRoot 'Invoke-NativeAuth.ps1') -Action Initialize -StateDirectory $StateDirectory -ProjectName $project + Copy-Item -LiteralPath (Join-Path $PSScriptRoot 'compose.native-auth.yaml') -Destination (Join-Path $StateDirectory 'compose.native-auth.yaml') + } + @{project = $project; sourceRoot = $sourceRoot; sourceCommit = $commit; authentik = [bool]$Authentik; experimentalNativeAuth = [bool]$ExperimentalNativeAuth; createdAt = [DateTime]::UtcNow.ToString('O') } | ConvertTo-Json | Set-Content -LiteralPath $ownerFile +} +$script:composeArguments = @('--project-name', $project, '--env-file', $envFile, '-f', (Join-Path $StateDirectory 'compose.yaml')) +if ($Authentik) +{ + $script:composeArguments += @('-f', (Join-Path $StateDirectory 'compose.authentik.yaml')) +} +if ($ExperimentalNativeAuth) +{ + $script:composeArguments += @('-f', (Join-Path $StateDirectory 'compose.native-auth.yaml')) +} +if ($Action -eq 'Stop') +{ + Stop-OwnedEnvironment + Write-Output "Stopped owned development environment. Reports remain in $StateDirectory" + return +} + +if ($ExperimentalNativeAuth) +{ + $nativePassed = $false + try + { + Invoke-Compose @('--profile', 'auth', '--profile', 'native-auth', 'build', 'native-qqq', 'native-client') + Invoke-Compose @('--profile', 'auth', '--profile', 'native-auth', 'up', '-d', 'authentik-server', 'authentik-worker', 'native-tls') + Invoke-Compose @('exec', '-T', 'native-tls', '/bin/sh', '/etc/caddy/copy-root.sh') + Invoke-Compose @('--profile', 'auth', '--profile', 'native-auth', 'up', '-d', 'native-qqq') + Invoke-Compose @('--profile', 'auth', '--profile', 'native-auth', 'run', '--rm', '--use-aliases', 'native-client') + & (Join-Path $PSScriptRoot 'Invoke-NativeAuth.ps1') -Action VerifyResult -StateDirectory $StateDirectory -ProjectName $project + $nativePassed = $true + } + finally + { + try + { + if (!$nativePassed) { Save-ProviderErrorSummary } + } + finally { Stop-OwnedEnvironment } + Write-Output "Protected experimental native-auth result: $(Join-Path $StateDirectory 'native-auth-result.json')" + } + return +} + +if ($Action -eq 'Start') +{ + $services = @('minio', 'qqq') + $profiles = @() + if ($Authentik) + { + $profiles = @('--profile', 'auth'); $services += @('authentik-server', 'authentik-worker') + } + try + { + Invoke-Compose ($profiles + @('up', '-d', '--build') + $services); & (Join-Path $PSScriptRoot 'Test-DevelopmentHost.ps1') -StateDirectory $StateDirectory + } + catch + { + if ($createdState) + { + Stop-OwnedEnvironment + }; throw + } + Write-Output "Owned environment: $StateDirectory" + Write-Output 'Read QQQ_ADMIN_PASSWORD in its protected compose.env; username is developer. No password is logged.' + return +} + +$testRun = 'run-' + [Guid]::NewGuid().ToString('N') +Set-FixtureEnvironment 'TEST_RUN' $testRun +Set-FixtureEnvironment 'WORKLOAD_MODE' $(if ($Workload -eq 10000) + { + 'burst' + } + else + { + 'idle' + }) +$reports = Join-Path $StateDirectory $testRun +[IO.Directory]::CreateDirectory($reports) | Out-Null +$passed = $false +try +{ + if ($Authentik) + { + Invoke-Compose @('--profile', 'auth', 'up', '-d', '--build', 'qqq', 'authentik-server', 'authentik-worker') + & (Join-Path $PSScriptRoot 'Test-DevelopmentHost.ps1') -StateDirectory $StateDirectory + & (Join-Path $PSScriptRoot 'Invoke-Authentik.ps1') -Action Test -StateDirectory $StateDirectory -ProjectName $project -Port (Get-RecordedAuthentikPort) + } + Invoke-Compose @('--profile', 'test', 'up', '-d', '--build', 'test-client') + $client = (& docker compose @composeArguments ps -a -q test-client).Trim() + $server = (& docker compose @composeArguments ps -a -q test-server).Trim() + if ($client -cnotmatch '^[a-f0-9]{64}$' -or $server -cnotmatch '^[a-f0-9]{64}$') + { + throw 'Owned fixture identity missing.' + } + $clientExit = Wait-OwnedContainer $client 1200 + Assert-WorkloadClientSucceeded -Id $client -ExitCode $clientExit -Run $testRun -Reports $reports + $serverExit = Wait-OwnedContainer $server 45 + foreach ($file in @('result.json', 'server-result.json', 'stopped.json', 's3/results.json', 's3/completed-checks.json')) + { + $destination = Join-Path $reports $file.Replace('/', '-') + & docker cp "${server}:/work/$testRun/$file" $destination + if ($LASTEXITCODE -ne 0) + { + throw 'Required sanitized fixture result missing.' + } + } + if ($clientExit -ne 0 -or $serverExit -ne 0) + { + throw 'Fixture failed; see protected results.' + } + $clientResult = Get-Content (Join-Path $reports 'result.json') -Raw | ConvertFrom-Json + $serverResult = Get-Content (Join-Path $reports 'server-result.json') -Raw | ConvertFrom-Json + $s3Result = Get-Content (Join-Path $reports 's3-results.json') -Raw | ConvertFrom-Json + if (!$clientResult.success -or !$serverResult.success -or !$s3Result.passed -or $clientResult.jobs -ne $Workload -or @($s3Result.checks).Count -ne 65) + { + throw 'Result invariants failed.' + } + $passed = $true +} +finally +{ + & docker compose @composeArguments logs --no-color --no-log-prefix test-server test-client 2>&1 | Set-Content -LiteralPath (Join-Path $reports 'fixture.log') + if ($ephemeral) + { + Stop-OwnedEnvironment + } + else + { + Assert-OwnedResource + Invoke-Compose @('--profile', 'test', 'rm', '--stop', '--force', 'test-client', 'test-server', 'minio-test') + } + @{passed = $passed; workload = $Workload; physicalPrinting = $false; tlsQualified = $false; finishedAt = [DateTime]::UtcNow.ToString('O') } | ConvertTo-Json | Set-Content -LiteralPath (Join-Path $reports 'execution.json') + Write-Output "Protected developer-test results: $reports" +} +if (!$passed) +{ + throw 'Development qualification did not pass.' +} diff --git a/dev/Invoke-NativeAuth.ps1 b/dev/Invoke-NativeAuth.ps1 new file mode 100644 index 0000000..2798255 --- /dev/null +++ b/dev/Invoke-NativeAuth.ps1 @@ -0,0 +1,110 @@ +#Requires -Version 7.4 +# Copyright 2026 Kingsrook, LLC +# SPDX-License-Identifier: Apache-2.0 + +<# +.SYNOPSIS +Prepares or verifies the opt-in, unpublished native-session Docker qualification. +.DESCRIPTION +Docker lifecycle belongs to Invoke-Dev.ps1. This helper creates only protected +synthetic input and reads a bounded sanitized report. It never installs trust, +uses host Maven caches, starts a browser, or operates the installed connector. +#> +[CmdletBinding()] +param( + [Parameter(Mandatory)][ValidateSet('Initialize', 'VerifyResult')][string] $Action, + [Parameter(Mandatory)][string] $StateDirectory, + [Parameter(Mandatory)][ValidatePattern('^qbit-printing-dev-[a-z0-9-]{8,48}$')][string] $ProjectName +) + +Set-StrictMode -Version Latest +$ErrorActionPreference = 'Stop' +$coreSource = 'ecf0f550a0357cec6387c2b54efca128a405a629' +$clientSource = '346fc285198908c47a2ee9db7b9adb53d5e88c3c' +$state = [IO.Path]::GetFullPath($StateDirectory) +$repository = [IO.Path]::GetFullPath((Join-Path $PSScriptRoot '..')) +$comparison = if($IsWindows) { [StringComparison]::OrdinalIgnoreCase } else { [StringComparison]::Ordinal } +if($state.Equals($repository, $comparison) -or $state.StartsWith($repository + [IO.Path]::DirectorySeparatorChar, $comparison)) +{ + throw 'Experimental credentials must be outside the checkout.' +} +$envFile = Join-Path $state 'compose.env' +$inputFile = Join-Path $state 'native-input.json' +$resultFile = Join-Path $state 'native-auth-result.json' +if(-not (Test-Path -LiteralPath $envFile -PathType Leaf)) +{ + throw 'The common entrypoint must initialize protected owned state first.' +} + +if($Action -eq 'VerifyResult') +{ + if(-not (Test-Path -LiteralPath $resultFile -PathType Leaf) -or (Get-Item -LiteralPath $resultFile).Length -gt 65536) + { + throw 'The experimental result is missing or exceeds its bounded size.' + } + try { $report = Get-Content -LiteralPath $resultFile -Raw | ConvertFrom-Json -AsHashtable } + catch { throw 'The experimental result is malformed; its contents are withheld.' } + $required = @('untrusted-tls-refused', 'typed-native-grant', 'real-provider-login', 'wrong-origin-cookie-denied', 'permission-denied-user', 'logout-replay-denied', 'server-refresh-after-expiry', 'provider-revocation-denied') + if($report.status -cne 'PASS' -or $report.scope -cne 'DEVELOPMENT_ONLY_UNRELEASED' -or + $report.coreSource -cne $coreSource -or $report.clientSource -cne $clientSource -or + $report.project -cne $ProjectName -or @($required | Where-Object { $_ -notin $report.checks }).Count -ne 0) + { + throw 'The experimental native-session qualification did not pass its exact source and required checks.' + } + Write-Output 'Experimental native-session provider checks passed; the candidate is unpublished and no installed/browser-UI acceptance is claimed.' + return +} + +if((Test-Path -LiteralPath $inputFile) -or (Get-Content -LiteralPath $envFile -Raw) -match '(?m)^NATIVE_') +{ + throw 'Experimental native tests require a fresh owned environment; partial state is not reused.' +} +try +{ + $auth = Get-Content -LiteralPath (Join-Path $state 'auth-secrets.json') -Raw | ConvertFrom-Json -AsHashtable + if($auth.project -cne $ProjectName -or $auth.clientId -cne $ProjectName) { throw 'Wrong owner.' } +} +catch { throw 'Private Authentik bootstrap state is absent or does not match this project.' } +$random = [Security.Cryptography.RandomNumberGenerator]::GetBytes(32) +$deniedPassword = [Convert]::ToBase64String($random).TrimEnd('=').Replace('+', '-').Replace('/', '_') +$issuer = "https://auth.printing.internal/application/o/$ProjectName/" +$inputData = [ordered]@{ + project = $ProjectName + coreSource = $coreSource + clientSource = $clientSource + providerOrigin = 'https://auth.printing.internal' + qqqOrigin = 'https://qqq.printing.internal' + issuer = $issuer + callback = 'https://callback.printing.internal/oauth/callback' + adminToken = $auth.bootstrapToken + clientId = $auth.clientId + clientSecret = $auth.clientSecret + authorizedUsername = 'printing-authorized' + authorizedPassword = $auth.userPassword + deniedUsername = 'printing-denied' + deniedPassword = $deniedPassword +} +$inputData | ConvertTo-Json | Set-Content -LiteralPath $inputFile -Encoding utf8 +@{ status = 'NOT_RUN'; scope = 'DEVELOPMENT_ONLY_UNRELEASED'; project = $ProjectName } | + ConvertTo-Json | Set-Content -LiteralPath $resultFile -Encoding utf8 +$values = [ordered]@{ + NATIVE_QQQ_DATABASE_PASSWORD = [Convert]::ToHexString([Security.Cryptography.RandomNumberGenerator]::GetBytes(32)) + NATIVE_QQQ_REFRESH_KEY = [Convert]::ToBase64String([Security.Cryptography.RandomNumberGenerator]::GetBytes(32)) + NATIVE_AUTH_ISSUER = $issuer + NATIVE_AUTH_CLIENT_ID = $auth.clientId + NATIVE_AUTH_CLIENT_SECRET = $auth.clientSecret + NATIVE_AUTH_INPUT_FILE = $inputFile.Replace('\', '/') + NATIVE_AUTH_RESULT_FILE = $resultFile.Replace('\', '/') +} +foreach($entry in $values.GetEnumerator()) +{ + if($entry.Value -match '[\r\n'']') { throw 'Unsupported experimental environment value.' } +} +Add-Content -LiteralPath $envFile -Value @($values.GetEnumerator() | ForEach-Object { $_.Key + "='" + $_.Value + "'" }) -Encoding utf8 +if(-not $IsWindows) +{ + foreach($file in @($inputFile, $resultFile)) + { + [IO.File]::SetUnixFileMode($file, [IO.UnixFileMode]::UserRead -bor [IO.UnixFileMode]::UserWrite) + } +} diff --git a/dev/README.md b/dev/README.md new file mode 100644 index 0000000..6cb00d4 --- /dev/null +++ b/dev/README.md @@ -0,0 +1,133 @@ +# Local Docker development + +Use this repository to start a separate QQQ application or run synthetic printing +checks. Nothing imports an installed connector's pairing, accesses physical +printers, or needs a cloud account. Docker Compose and PowerShell 7.4+ are required; +Git identifies the checkout. Docker must support Linux/amd64 containers. The first +build downloads pinned public images, Maven dependencies and the verified Windows +Core source archive. Java and .NET run inside Docker; neither host SDK is required. + +## Start, test and stop + +From the repository root, the default command runs 65 S3 checks and 40 network +jobs, saves protected reports, and removes its containers and synthetic volumes: + +```powershell +pwsh ./dev/Invoke-Dev.ps1 -Action Test +``` + +For a persistent development application, start it and keep the state-directory +path printed by the command: + +```powershell +pwsh ./dev/Invoke-Dev.ps1 -Action Start +pwsh ./dev/Invoke-Dev.ps1 -Action Test -StateDirectory '' +pwsh ./dev/Invoke-Dev.ps1 -Action Stop -StateDirectory '' +``` + +Open `http://127.0.0.1:19081`. The standard QQQ TABLE login username is `developer`. +Read `QQQ_ADMIN_PASSWORD` from the generated, protected `compose.env` locally; +never paste that file into an issue or commit it. There is no default password. +The host provides native printing screens, settings, a dedicated MinIO document +bucket and scheduled retention. No printer is enrolled automatically in this host. +The test workload uses a separate disposable database and object store. + +Add `-Authentik` when creating an environment or running a fresh test to include +real Authentik/PostgreSQL. See [the provider checks and remaining native grant +prerequisite](AUTHENTIK.md). Provider discovery does not establish successful OIDC +user login or refresh; the current QQQ RC.20 API lacks that native-client grant. + +```powershell +pwsh ./dev/Invoke-Dev.ps1 -Action Test -Authentik +pwsh ./dev/Invoke-Dev.ps1 -Action Test -Workload 10000 +``` + +The optional 10,000-job run keeps admission limits enabled, uses eight synthetic +clients across two tenants, and reports client process memory, latency and +receipt counts. It is a bounded burst, not a day-long soak or physical throughput +claim. The default 40-job run measures idle event delivery one job at a time. + +## Isolation and cleanup + +Each environment has a unique `qbit-printing-dev-` Compose project and +matching ownership labels. All published ports bind only to `127.0.0.1`: QQQ19081, +MinIO19095 and optional Authentik19010. Override them with `-QqqPort`, `-MinioPort` +and `-AuthentikPort` when creating a new environment. Occupied ports fail startup; +the command never stops another service to free them. PostgreSQL is not published. + +State defaults to the current user's application-data directory, outside the +checkout, with private filesystem permissions. A custom `-StateDirectory` must +also be outside the checkout. It holds generated fixture credentials, frozen +Compose files, ownership records and sanitized result files. Docker administrators +can inspect container configuration; use these credentials only for this fixture. + +`Stop` validates container, network and volume ownership before removing that +project's resources. **It deletes that environment's synthetic databases and +objects.** It leaves reports and ordinary image/build caches in place and never +runs a global prune. A fresh one-command `Test` performs this cleanup in `finally`, +including on failure. Tests against an existing environment remove only their +three test containers; finish with `Stop` to remove its disposable test volume and +the persistent development environment. Do not edit its frozen ownership files. + +Images are pinned by digest in Compose/Dockerfiles. Containers have bounded CPU +and memory, no automatic restart, and no Docker socket. The default profile has +no host credential or source mounts. QQQ/test containers additionally cap process +counts. Builds copy +only explicit source inputs. The QQQ and MinIO containers share their own network +namespace so the existing loopback S3 backend can be used without relaxing +production endpoint validation. + +## What the results mean + +- The S3 fixture exercises the actual QQQ `StorageAction`/S3 backend and AWS SDK, + including a multipart-size document, hashes, tenant namespaces, immutable + binding checks, retention and unrelated-object preservation. +- The workload uses the real current Java server and pinned Windows Core client: + native TABLE authentication, outbound WebSocket notifications, event-driven + claims, document downloads and durable server receipts. A fake file printer + verifies bytes and rejects duplicate submission. It cannot produce paper. +- The fixture's client receipt journal is intentionally simple; these results do + not replace production SQLite crash-recovery tests. MinIO fixture credentials + are unrestricted within their owned store and do not qualify production IAM. +- Connections here are HTTP/WebSocket on an isolated local project. TLS, provider + browser consent/renewal, real deployment policies and hardware behavior are + separate qualifications. No silent bearer-authentication fallback is added. + +Results include `result.json`, `server-result.json`, `s3-results.json` and +`execution.json` under a run directory. The persistent host also writes +`qqq-result.json`; optional provider checks write `auth-result.json`. Treat raw +fixture logs as private even though only synthetic accounts/documents are used. + +The client Dockerfile pins commit `346fc285198908c47a2ee9db7b9adb53d5e88c3c` +and verifies its source archive SHA-256 before compilation. The Java image builds +this checkout, including local edits, and records its Git HEAD for context; a Git +HEAD alone does not certify a dirty tree as that released artifact. This tooling +is outside the production JAR and adds no application runtime dependency. + +## Script regressions + +With Pester 5 installed, the initializer and cleanup-ownership tests need no Docker +or network. Disable Pester's unrelated registry fixture on Windows: + +```powershell +$configuration = New-PesterConfiguration +$configuration.Run.Path = './dev/tests' +$configuration.Run.Exit = $true +$configuration.TestRegistry.Enabled = $false +Invoke-Pester -Configuration $configuration +``` + +## Experimental native sign-in + +The separate [native sign-in profile](native-auth/README.md) builds an explicitly +selected upstream candidate and uses container-private TLS trust. It mounts only +public Caddy configuration and specific protected fixture input/result files. +It is opt-in, Test-only, and does not change the default released QQQ dependency. + +## Continuous integration + +The development workflow runs the Pester and PowerShell analysis checks on +Windows and Ubuntu for every pull request and main-branch push. Ubuntu also runs +the real 40-job/S3 Docker smoke. The longer experimental native-auth profile is +an explicit manual workflow option; it is not silently substituted for the +released dependency baseline. diff --git a/dev/Test-DevelopmentHost.ps1 b/dev/Test-DevelopmentHost.ps1 new file mode 100644 index 0000000..7a4c444 --- /dev/null +++ b/dev/Test-DevelopmentHost.ps1 @@ -0,0 +1,140 @@ +#Requires -Version 7.4 +# Copyright 2026 Kingsrook, LLC +# SPDX-License-Identifier: Apache-2.0 + +<# .SYNOPSIS Checks the owned local QQQ development host without enrolling or printing. #> +[CmdletBinding()] +param([Parameter(Mandatory)][string]$StateDirectory) +$ErrorActionPreference = 'Stop' +Set-StrictMode -Version Latest +$state = [IO.Path]::GetFullPath($StateDirectory) +$owner = Get-Content -LiteralPath (Join-Path $state 'owner.json') -Raw | ConvertFrom-Json +if ($owner.project -cnotmatch '^qbit-printing-dev-[a-f0-9]{32}$') +{ + throw 'Expected an owned development environment.' +} +$values = @{} +foreach ($line in Get-Content -LiteralPath (Join-Path $state 'compose.env')) +{ + if ($line -match '^([A-Z_]+)=(.*)$') + { + $values[$Matches[1]] = $Matches[2] + } +} +$port = [int]$values.QQQ_HTTP_PORT +if ($port -lt 1024 -or $port -gt 65535 -or $port -in @(18081, 18086)) +{ + throw 'Expected a separate development port.' +} +$origin = "http://127.0.0.1:$port" +$handler = [Net.Http.HttpClientHandler]::new() +$handler.UseProxy = $false +$handler.AllowAutoRedirect = $false +$handler.CookieContainer = [Net.CookieContainer]::new() +$client = [Net.Http.HttpClient]::new($handler) +$client.BaseAddress = [Uri]$origin +$client.Timeout = [TimeSpan]::FromSeconds(15) +$client.MaxResponseContentBufferSize = 1048576 +$client.DefaultRequestHeaders.Add('X-QQQ-Client', 'api/printing-development-check') +$client.DefaultRequestHeaders.Add('Origin', $origin) +$loggedIn = $false + +function Invoke-DevelopmentRequest([string]$Path, [string]$Method = 'GET', [string]$Authorization) +{ + <# .SYNOPSIS Sends one bounded native request, without returning credentials. #> + $request = [Net.Http.HttpRequestMessage]::new([Net.Http.HttpMethod]::new($Method), $Path) + if ($Method -eq 'POST') + { + $request.Content = [Net.Http.StringContent]::new('{}', [Text.Encoding]::UTF8, 'application/json') + } + if ($Authorization) + { + $request.Headers.TryAddWithoutValidation('Authorization', $Authorization) | Out-Null + } + $response = $null + try + { + $response = $client.SendAsync($request).GetAwaiter().GetResult() + if (!$response.IsSuccessStatusCode) + { + throw 'Owned native endpoint returned an unsuccessful status.' + } + return $response.Content.ReadAsStringAsync().GetAwaiter().GetResult() + } + finally + { + if ($null -ne $response) + { + $response.Dispose() + }; $request.Dispose() + } +} +try +{ + $deadline = [DateTime]::UtcNow.AddSeconds(90) + do + { + try + { + $version = (Invoke-DevelopmentRequest '/qqq/v1/version') | ConvertFrom-Json; break + } + catch [Net.Http.HttpRequestException] + { + if ([DateTime]::UtcNow -ge $deadline) + { + throw + }; Start-Sleep -Seconds 1 + } + } while ($true) + if (@($version.extensions | Where-Object { $_.name -ceq 'printing' -and $_.version -ceq '2.0.0' }).Count -ne 1) + { + throw 'Expected current printing extension.' + } + $metadata = (Invoke-DevelopmentRequest '/qqq/v1/metaData/authentication') | ConvertFrom-Json + if ($metadata.type -cne 'TABLE_BASED') + { + throw 'Development host must retain standard TABLE authentication.' + } + $basic = 'Basic ' + [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes('developer:' + $values.QQQ_ADMIN_PASSWORD)) + try + { + $null = Invoke-DevelopmentRequest -Path '/qqq/v1/manageSession' -Method POST -Authorization $basic + } + finally + { + $basic = $null; $values = $null + } + $cookies = $handler.CookieContainer.GetCookies([Uri]$origin) + $cookie = $cookies['sessionId']; if ($null -eq $cookie) + { + $cookie = $cookies['sessionUUID'] + } + $loggedIn = $null -ne $cookie + if (!$loggedIn -or !$cookie.HttpOnly) + { + throw 'Native HttpOnly session was not established.' + } + $identity = (Invoke-DevelopmentRequest '/qqq/v1/qbit/printing/session') | ConvertFrom-Json + if ($identity.principalId -cne 'developer' -or $identity.tenantId -cne 'development') + { + throw 'Native development identity mismatch.' + } + $html = Invoke-DevelopmentRequest '/' + if (!$html.Contains(' SendAsync(HttpRequestMessage request, CancellationToken cancellationToken) + { + if(request.Method != HttpMethod.Get || request.RequestUri?.AbsolutePath != "/qqq/v1/version" + || request.Headers.Contains("Cookie") || request.Headers.Contains("Authorization")) + { + throw new InvalidOperationException("Discovery must precede authentication."); + } + Requests++; + string json = JsonSerializer.Serialize(new + { + apiVersion = "1.8.0", + features = new[] { "version", "metaData", "processes", "processCancel", "extensions", "widgets" }, + clientChannels = new[] { "api" }, + extensions = new[] { new { name = "printing", version, pathPrefix = "/qbit/printing" } } + }); + return Task.FromResult(new HttpResponseMessage(HttpStatusCode.OK) { Content = new StringContent(json) }); + } + } +} diff --git a/dev/client/Program.cs b/dev/client/Program.cs new file mode 100644 index 0000000..ef446f4 --- /dev/null +++ b/dev/client/Program.cs @@ -0,0 +1,149 @@ +// Copyright 2026 Kingsrook, LLC + +// SPDX-License-Identifier: Apache-2.0 +using System.Collections.Concurrent; +using System.Diagnostics; +using System.Globalization; +using System.Net.WebSockets; +using System.Text; +using System.Text.Json; +using System.Threading.Channels; +using Qqq.PrintAgent.Core.Authentication; +using Qqq.PrintAgent.Core.Printing; +internal static class Program { + static int Completed; static readonly byte[] Expected=Encoding.ASCII.GetBytes("^XA^FO20,20^FDSYNTHETIC NOT PRINTED^FS"+new string(' ',980)+"^XZ"); + static async Task Main(string[] args) { + if(args is ["--check-discovery"]) { await DiscoveryChecks.RunAsync(); return 0; } + string folder=Path.GetFullPath(args[0]); string stage="input"; + using var timeout=new CancellationTokenSource(TimeSpan.FromMinutes(18)); + List lanes=[]; long peak=0; var timer=Stopwatch.StartNew(); + try { + using JsonDocument input=JsonDocument.Parse(await File.ReadAllTextAsync(Path.Combine(folder,"input.json"))); + stage="native_login_and_channels"; + bool idle=input.RootElement.GetProperty("idle").GetBoolean(); int perLane=input.RootElement.GetProperty("jobsPerLane").GetInt32(); int total=perLane*8; int index=0; + foreach(var value in input.RootElement.GetProperty("lanes").EnumerateArray()) { + Uri origin=new(value.GetProperty("origin").GetString()!); + Require(origin.IsLoopback && origin.Port is not (18081 or 18086),"disposable origin"); + var client=new QqqSessionClient(origin,allowLoopbackHttp:true); + await WorkloadDiscovery.DiscoverRealtimeAsync(client,timeout.Token); + await client.GetAuthenticationMetadataAsync(timeout.Token); + await client.SignInWithPasswordAsync(value.GetProperty("username").GetString()!,value.GetProperty("password").GetString()!,timeout.Token); + await client.BindDeviceAsync(new(value.GetProperty("deviceId").GetString()!,value.GetProperty("deviceToken").GetString()!),cancellationToken:timeout.Token); + var binding=await client.GetSessionIdentityAsync(timeout.Token); + Require(binding.TenantId==value.GetProperty("tenant").GetString(),"authoritative tenant"); + var connection=await Connection.Open(client,timeout.Token); + lanes.Add(new(client,connection,Path.Combine(folder,"lane-"+index++),perLane,folder)); + } + Require(lanes.Count==8,"eight lanes"); + // Authoritative native proof check: tenant A cannot bind a real tenant B device. + var foreign=input.RootElement.GetProperty("lanes")[4]; bool denied=false; + using(var outsider=new QqqSessionClient(new Uri(input.RootElement.GetProperty("lanes")[0].GetProperty("origin").GetString()!),allowLoopbackHttp:true)) { + await outsider.DiscoverAsync(timeout.Token);await outsider.GetAuthenticationMetadataAsync(timeout.Token); + await outsider.SignInWithPasswordAsync("operator",input.RootElement.GetProperty("lanes")[0].GetProperty("password").GetString()!,timeout.Token); + try {await outsider.BindDeviceAsync(new(foreign.GetProperty("deviceId").GetString()!,foreign.GetProperty("deviceToken").GetString()!),cancellationToken:timeout.Token);}catch(QqqSessionException){denied=true;} + Require(denied,"cross tenant proof refused");await outsider.SignOutAsync(timeout.Token); + } + stage="workload"; + var tasks=lanes.Select(lane=>lane.Run(timeout.Token)).ToArray(); + await File.WriteAllTextAsync(Path.Combine(folder,"ready"),"ready",timeout.Token); + Task all=Task.WhenAll(tasks); + while(!all.IsCompleted) { + peak=Math.Max(peak,Process.GetCurrentProcess().WorkingSet64); + await Task.WhenAny(all,Task.Delay(1000,timeout.Token));timeout.Token.ThrowIfCancellationRequested(); + } + await all; + Require(lanes.Sum(l=>l.Printer.Count)==total,"exact fake submission count"); + Require(lanes.All(l=>l.Journal.Pending().Count==0),"no unacknowledged receipts"); + stage="logout";foreach(var lane in lanes)await lane.Client.SignOutAsync(timeout.Token); + double[] latencies=lanes.SelectMany(l=>l.Latencies).Order().ToArray(); + await File.WriteAllTextAsync(Path.Combine(folder,"result.json"),JsonSerializer.Serialize(new { + success=true,jobs=total,idle,tenants=2,devices=8,elapsedSeconds=timer.Elapsed.TotalSeconds,jobsPerSecond=total/timer.Elapsed.TotalSeconds, + peakClientWorkingSetBytes=peak,p50EnqueueToAckMillis=latencies[total/2],p95EnqueueToAckMillis=latencies[(int)(total*0.95)],p99EnqueueToAckMillis=latencies[(int)(total*0.99)], + realCoreWorker=true,fakePrinterBackend=true,fixtureJournal=true,serverReceiptsDurable=true,crossTenantProofRefused=denied, + submissionReplays=idle?0:400,receiptReplays=idle?0:400,notificationToClaimMillis=lanes.SelectMany(l=>l.ClaimLatency).ToArray(),notificationToDownloadCompletedMillis=lanes.SelectMany(l=>l.DownloadLatency).ToArray(),periodicJobPolling=false,transport="HTTP/WS loopback; no TLS qualification",realPrinterCalls=0, + runtime=Environment.Version.ToString(),coreVersion=typeof(PrintWorker).Assembly.GetName().Version?.ToString() + },new JsonSerializerOptions{WriteIndented=true})); + Console.WriteLine("PASS real Core/Java network lifecycles; fake printer only");return 0; + } catch(Exception error) { + await File.WriteAllTextAsync(Path.Combine(folder,"result.json"),JsonSerializer.Serialize(new{success=false,stage,error=error.GetType().Name,reason=error is InvalidDataException?error.Message:null,completed=lanes.Sum(l=>l.Printer.Count)})); + Console.Error.WriteLine("FAIL "+stage+": "+error.GetType().Name);return 1; + } finally { + foreach(var lane in lanes)await lane.DisposeAsync(); + await File.WriteAllTextAsync(Path.Combine(folder,"done"),"done"); + } + } + static void Require(bool ok,string reason){if(!ok)throw new InvalidDataException(reason);} + sealed class Lane: IAsyncDisposable { + public QqqSessionClient Client{get;} public Connection Connection{get;} + public FakePrinter Printer{get;}=new(); public Journal Journal{get;} public List Latencies{get;}=[]; + readonly PrintApiClient api;readonly PrintWorker worker; readonly int target; readonly string root; long wakeAt; public List ClaimLatency{get;}=[]; public List DownloadLatency{get;}=[]; + public Lane(QqqSessionClient client,Connection connection,string folder,int target,string root) { + Client=client;Connection=connection;this.target=target;this.root=root;Printer.OnDownload=()=>DownloadLatency.Add(Stopwatch.GetElapsedTime(wakeAt).TotalMilliseconds);Directory.CreateDirectory(folder);Journal=new(folder); + api=PrintApiClient.ForSession(client).WithRealtime(connection.Channel,connection.Settings); + worker=new PrintWorker(api,Printer,Journal,options:new PrintWorkerOptions{Settings=connection.Settings,StagingDirectory=Path.Combine(folder,"staging"),SynchronizeInventory=false,RecoverIncomplete=false,ActiveJobChanged=job=>{if(job is not null)ClaimLatency.Add(Stopwatch.GetElapsedTime(wakeAt).TotalMilliseconds);}}); + } + public async Task Run(CancellationToken token) { + using var stop=CancellationTokenSource.CreateLinkedTokenSource(token); + Task ping=Liveness(stop.Token); + try { + while(Printer.Count seen=new(StringComparer.Ordinal);public int Count=>seen.Count; public Action? OnDownload{get;set;} + public IReadOnlyList Discover()=>[new("synthetic","No physical printer","fixture","none","READY",["ZPL"])]; + public async Task PrintFileAsync(PrintJob job,string path,CancellationToken token) {OnDownload?.Invoke();return await PrintAsync(job,await File.ReadAllBytesAsync(path,token),token);} + public Task PrintAsync(PrintJob job,byte[] content,CancellationToken token) { + Require(content.AsSpan().SequenceEqual(Expected),"downloaded bytes exact");Require(seen.Add(job.JobId),"no duplicate physical action");return Task.FromResult("synthetic-"+Count); + } + } + // Fixture journal is deliberately separate from the installed Windows SQLite journal. + sealed class Journal: IJobJournal,IDisposable { + readonly Dictionary states=new(StringComparer.Ordinal);readonly Dictionary pending=new(StringComparer.Ordinal);readonly StreamWriter log; + public PrintJob? LastJob{get;private set;}public (string JobId,PrintEvent Event) Last{get;private set;} + public Journal(string folder){log=new StreamWriter(new FileStream(Path.Combine(folder,"synthetic-receipts.jsonl"),FileMode.CreateNew,FileAccess.Write,FileShare.Read)){AutoFlush=true};} + public void TrackJob(PrintJob job,string? printer){LastJob=job;} + public string? GetState(string id)=>states.GetValueOrDefault(id); + public void Record(string id,PrintEvent evt){log.WriteLine(JsonSerializer.Serialize(new{jobId=id,@event=evt}));states[id]=evt.Status;pending.Add(evt.EventId,(id,evt));Last=(id,evt);} + public IReadOnlyList<(string JobId,PrintEvent Event)> Pending()=>pending.Values.ToList(); + public void Acknowledge(string id){pending.Remove(id);} + public IReadOnlyList<(string JobId,string State)> Incomplete()=>[]; + public void Dispose()=>log.Dispose(); + } + sealed class Connection:IAsyncDisposable { + public required PrintingRealtimeChannel Channel{get;init;}public required Task Reader{get;init;}public required CancellationTokenSource Lifetime{get;init;} + public required Channel Messages{get;init;}public required Channel Wakes{get;init;}public RealtimeSettings Settings{get;private set;}=new(); + public static async Task Open(QqqSessionClient client,CancellationToken token) { + var lifetime=CancellationTokenSource.CreateLinkedTokenSource(token);WebSocket socket=await client.ConnectPrintingAsync(TimeSpan.FromSeconds(20),TimeSpan.FromSeconds(60),token); + var channel=new PrintingRealtimeChannel(socket,new RealtimeSettings());var messages=System.Threading.Channels.Channel.CreateBounded(8); + var wakes=System.Threading.Channels.Channel.CreateBounded(new BoundedChannelOptions(1){FullMode=BoundedChannelFullMode.DropWrite}); + Task reader=channel.RunAsync(e=>{ + if(e.Type=="JOB_AVAILABLE"){wakes.Writer.TryWrite(Stopwatch.GetTimestamp());return;} + if(e.Type is "SETTINGS" or "DESIRED_STATE") {long revision=e.Payload.GetProperty("revision").GetInt64();if(revision!=0)throw new InvalidDataException("Unexpected policy change");return;} + if(e.Type is "PONG" or "ACK")return; + if(!messages.Writer.TryWrite(e))throw new IOException("Fixture envelope inbox full"); + },lifetime.Token); + _=reader.ContinueWith(t=>{wakes.Writer.TryComplete(t.Exception);messages.Writer.TryComplete(t.Exception);},TaskScheduler.Default); + var result=new Connection{Channel=channel,Reader=reader,Lifetime=lifetime,Messages=messages,Wakes=wakes}; + await channel.SendAsync("HELLO",new{agentVersion=PrintApiClient.AgentVersion,capabilities=new[]{"realtime-v1","REFRESH_INVENTORY","CANCEL_SPOOL"},lastAppliedRevision=0,lastSettingsRevision=0,limits=RealtimeSettings.ClientLimits},token:token); + RealtimeEnvelope welcome=await messages.Reader.ReadAsync(token);Require(welcome.Type=="WELCOME","welcome"); + result.Settings=welcome.Payload.GetProperty("settings").Deserialize(PrintApiClient.JsonOptions)!;result.Settings.Validate();channel.UpdateSettings(result.Settings); + await channel.SendAsync("STATE_APPLIED",new{lastAppliedRevision=welcome.Payload.GetProperty("desiredState").GetProperty("revision").GetInt64(),lastSettingsRevision=result.Settings.Revision},acknowledged:true,token:token);return result; + } + public async ValueTask DisposeAsync(){await Lifetime.CancelAsync();try{await Reader;}catch(Exception e)when(e is OperationCanceledException or IOException or WebSocketException){}Channel.Dispose();Lifetime.Dispose();} + } +} diff --git a/dev/client/Workload.csproj b/dev/client/Workload.csproj new file mode 100644 index 0000000..9a2c168 --- /dev/null +++ b/dev/client/Workload.csproj @@ -0,0 +1,15 @@ + + + + + Exenet10.0 + enableenable + true + + + /core/Qqq.PrintAgent.Core.dll + + diff --git a/dev/client/WorkloadDiscovery.cs b/dev/client/WorkloadDiscovery.cs new file mode 100644 index 0000000..b70169d --- /dev/null +++ b/dev/client/WorkloadDiscovery.cs @@ -0,0 +1,19 @@ +// Copyright 2026 Kingsrook, LLC + +// SPDX-License-Identifier: Apache-2.0 +using Qqq.PrintAgent.Core.Authentication; + +internal static class WorkloadDiscovery +{ + internal static async Task DiscoverRealtimeAsync(QqqSessionClient client, CancellationToken cancellationToken) + { + QqqApiDiscovery discovery = await client.DiscoverAsync(cancellationToken); + // Core discovery validates strict stable SemVer; realtime uses the same major gate as ConnectPrintingAsync. + QqqApiDiscovery.Extension extension = discovery.Extensions.Single(item => string.Equals(item.Name, "printing", StringComparison.Ordinal)); + if(!Version.TryParse(extension.Version, out Version? version) || version.Major != 2) + { + throw new InvalidDataException("Native realtime printing API required."); + } + return discovery; + } +} diff --git a/dev/compose.authentik.yaml b/dev/compose.authentik.yaml new file mode 100644 index 0000000..6076db5 --- /dev/null +++ b/dev/compose.authentik.yaml @@ -0,0 +1,80 @@ +# Copyright 2026 Kingsrook, LLC +# SPDX-License-Identifier: Apache-2.0 + +# Optional real provider reference. No Docker socket or published database port. +services: + authentik-postgres: + profiles: [auth] + platform: linux/amd64 + image: postgres@sha256:721873c34ceb9f8d8fc265984940dc982404c105f19ad51be9fdc5970a6080ea + environment: + POSTGRES_DB: authentik + POSTGRES_USER: authentik + POSTGRES_PASSWORD: ${AUTHENTIK_POSTGRES_PASSWORD:?Run the development initializer first} + volumes: + - authentik-database:/var/lib/postgresql/data + healthcheck: + test: [CMD-SHELL, "pg_isready -U authentik -d authentik"] + interval: 5s + timeout: 5s + retries: 30 + labels: + io.qrun.printing.dev: ${PRINTING_DEV_PROJECT:?Run the development initializer first} + mem_limit: 512m + cpus: 1.0 + + authentik-server: + profiles: [auth] + platform: linux/amd64 + image: ghcr.io/goauthentik/server@sha256:602227a86455d6772e3d16b7d852713c4f864f40df5df894abd1285bb53979a5 + command: server + depends_on: + authentik-postgres: + condition: service_healthy + environment: &authentik-environment + AUTHENTIK_POSTGRESQL__HOST: authentik-postgres + AUTHENTIK_POSTGRESQL__NAME: authentik + AUTHENTIK_POSTGRESQL__USER: authentik + AUTHENTIK_POSTGRESQL__PASSWORD: ${AUTHENTIK_POSTGRES_PASSWORD:?Run the development initializer first} + AUTHENTIK_SECRET_KEY: ${AUTHENTIK_SECRET_KEY:?Run the development initializer first} + AUTHENTIK_ERROR_REPORTING__ENABLED: "false" + AUTHENTIK_DISABLE_UPDATE_CHECK: "true" + AUTHENTIK_LOG_LEVEL: warning + ports: + - "127.0.0.1:${AUTHENTIK_HTTP_PORT:-19010}:9000" + volumes: + - authentik-data:/data + labels: + io.qrun.printing.dev: ${PRINTING_DEV_PROJECT:?Run the development initializer first} + shm_size: 256mb + mem_limit: 1536m + cpus: 2.0 + + authentik-worker: + profiles: [auth] + platform: linux/amd64 + image: ghcr.io/goauthentik/server@sha256:602227a86455d6772e3d16b7d852713c4f864f40df5df894abd1285bb53979a5 + command: worker + depends_on: + authentik-postgres: + condition: service_healthy + environment: + <<: *authentik-environment + AUTHENTIK_BOOTSTRAP_PASSWORD_HASH: ${AUTHENTIK_BOOTSTRAP_PASSWORD_HASH:?Run the development initializer first} + AUTHENTIK_BOOTSTRAP_TOKEN: ${AUTHENTIK_BOOTSTRAP_TOKEN:?Run the development initializer first} + AUTHENTIK_BOOTSTRAP_EMAIL: developer@example.invalid + volumes: + - authentik-data:/data + labels: + io.qrun.printing.dev: ${PRINTING_DEV_PROJECT:?Run the development initializer first} + shm_size: 256mb + mem_limit: 1536m + cpus: 2.0 + +volumes: + authentik-database: + labels: + io.qrun.printing.dev: ${PRINTING_DEV_PROJECT:?Run the development initializer first} + authentik-data: + labels: + io.qrun.printing.dev: ${PRINTING_DEV_PROJECT:?Run the development initializer first} diff --git a/dev/compose.native-auth.yaml b/dev/compose.native-auth.yaml new file mode 100644 index 0000000..fff0207 --- /dev/null +++ b/dev/compose.native-auth.yaml @@ -0,0 +1,78 @@ +# Copyright 2026 Kingsrook, LLC +# SPDX-License-Identifier: Apache-2.0 + +# Opt-in unpublished core qualification. No service is a replacement for the +# released RC.20 TABLE development host or an installed printing deployment. +services: + authentik-server: + networks: + default: + aliases: + - auth.printing.internal + - qqq.printing.internal + - callback.printing.internal + + native-tls: + profiles: [native-auth] + image: caddy@sha256:5f5c8640aae01df9654968d946d8f1a56c497f1dd5c5cda4cf95ab7c14d58648 + platform: linux/amd64 + network_mode: service:authentik-server + depends_on: [authentik-server] + volumes: + - ${DEV_SOURCE_DIR}/dev/native-auth/Caddyfile:/etc/caddy/Caddyfile:ro + - ${DEV_SOURCE_DIR}/dev/native-auth/copy-root.sh:/etc/caddy/copy-root.sh:ro + - native-ca:/data + - native-trust:/trust + labels: + io.qrun.printing.dev: ${PRINTING_DEV_PROJECT} + cpus: 1 + mem_limit: 256m + + native-qqq: + profiles: [native-auth] + build: + context: ${DEV_SOURCE_DIR} + dockerfile: dev/native-auth/Dockerfile.server + image: ${PRINTING_DEV_PROJECT}-native-server:local + environment: + NATIVE_QQQ_PORT: "19082" + NATIVE_QQQ_ORIGIN: https://qqq.printing.internal + NATIVE_QQQ_DATABASE_PASSWORD: ${NATIVE_QQQ_DATABASE_PASSWORD:?Initialize experimental state first} + NATIVE_QQQ_REFRESH_KEY: ${NATIVE_QQQ_REFRESH_KEY:?Initialize experimental state first} + NATIVE_AUTH_ISSUER: ${NATIVE_AUTH_ISSUER:?Initialize experimental state first} + NATIVE_AUTH_CLIENT_ID: ${NATIVE_AUTH_CLIENT_ID:?Initialize experimental state first} + NATIVE_AUTH_CLIENT_SECRET: ${NATIVE_AUTH_CLIENT_SECRET:?Initialize experimental state first} + NATIVE_AUTH_REDIRECT_URI: https://callback.printing.internal/oauth/callback + volumes: + - native-trust:/trust:ro + - native-qqq-data:/data + labels: + io.qrun.printing.dev: ${PRINTING_DEV_PROJECT} + cpus: 2 + mem_limit: 1g + + native-client: + profiles: [native-auth] + build: + context: ${DEV_SOURCE_DIR} + dockerfile: dev/native-auth/Dockerfile.client + image: ${PRINTING_DEV_PROJECT}-native-client:local + volumes: + - native-trust:/trust:ro + - ${NATIVE_AUTH_INPUT_FILE:?Initialize experimental state first}:/work/input.json:ro + - ${NATIVE_AUTH_RESULT_FILE:?Initialize experimental state first}:/work/result.json + labels: + io.qrun.printing.dev: ${PRINTING_DEV_PROJECT} + cpus: 2 + mem_limit: 512m + +volumes: + native-ca: + labels: + io.qrun.printing.dev: ${PRINTING_DEV_PROJECT} + native-trust: + labels: + io.qrun.printing.dev: ${PRINTING_DEV_PROJECT} + native-qqq-data: + labels: + io.qrun.printing.dev: ${PRINTING_DEV_PROJECT} diff --git a/dev/compose.yaml b/dev/compose.yaml new file mode 100644 index 0000000..0ac49bf --- /dev/null +++ b/dev/compose.yaml @@ -0,0 +1,108 @@ +# Copyright 2026 Kingsrook, LLC +# SPDX-License-Identifier: Apache-2.0 + +# Every published port is bound to host loopback; no live printing configuration is imported. +x-owned: &owned + labels: + io.qrun.printing.dev: ${PRINTING_DEV_PROJECT:?owned project required} + restart: "no" + cpus: 2 + mem_limit: 1g + pids_limit: 256 + cap_drop: [ALL] + security_opt: [no-new-privileges:true] + read_only: true + tmpfs: ["/tmp:rw,noexec,nosuid,size=128m,mode=1777"] + +services: + minio: + <<: *owned + image: cgr.dev/chainguard/minio@sha256:dc455cdd4db6e390b1b26514f15ff37681a777bf8dab41aac445a0259f751e56 + user: "0:0" + command: [server, /data, --address, ":9000"] + environment: + MINIO_ROOT_USER: ${MINIO_ROOT_USER:?fixture secret required} + MINIO_ROOT_PASSWORD: ${MINIO_ROOT_PASSWORD:?fixture secret required} + volumes: [minio-data:/data] + ports: + - "127.0.0.1:${MINIO_HTTP_PORT:-19095}:9000" + - "127.0.0.1:${QQQ_HTTP_PORT:-19081}:${QQQ_HTTP_PORT:-19081}" + qqq: + <<: *owned + build: + context: ${DEV_SOURCE_DIR:?source required} + dockerfile: dev/Dockerfile.server + args: + SOURCE_COMMIT: ${SOURCE_COMMIT:?source identity required} + image: ${PRINTING_DEV_PROJECT}-server:local + network_mode: service:minio + depends_on: [minio] + environment: + QQQ_HTTP_PORT: ${QQQ_HTTP_PORT:-19081} + QQQ_DATABASE_PASSWORD: ${QQQ_DATABASE_PASSWORD:?fixture secret required} + QQQ_ADMIN_PASSWORD: ${QQQ_ADMIN_PASSWORD:?fixture secret required} + QQQ_MANAGEMENT_TOKEN: ${QQQ_MANAGEMENT_TOKEN:?fixture secret required} + MINIO_ROOT_USER: ${MINIO_ROOT_USER} + MINIO_ROOT_PASSWORD: ${MINIO_ROOT_PASSWORD} + volumes: [qqq-data:/data] + minio-test: + <<: *owned + profiles: [test] + image: cgr.dev/chainguard/minio@sha256:dc455cdd4db6e390b1b26514f15ff37681a777bf8dab41aac445a0259f751e56 + user: "0:0" + command: [server, /data, --address, ":9000"] + environment: + MINIO_ROOT_USER: ${MINIO_ROOT_USER} + MINIO_ROOT_PASSWORD: ${MINIO_ROOT_PASSWORD} + tmpfs: ["/tmp:rw,noexec,nosuid,size=64m,mode=1777", "/data:rw,noexec,nosuid,size=900m,mode=1777"] + test-server: + <<: *owned + profiles: [test] + build: + context: ${DEV_SOURCE_DIR} + dockerfile: dev/Dockerfile.server + args: + SOURCE_COMMIT: ${SOURCE_COMMIT} + image: ${PRINTING_DEV_PROJECT}-server:local + network_mode: service:minio-test + depends_on: [minio-test] + environment: + MINIO_ROOT_USER: ${MINIO_ROOT_USER} + MINIO_ROOT_PASSWORD: ${MINIO_ROOT_PASSWORD} + TEST_RUN: ${TEST_RUN:-run-uninitialized} + WORKLOAD_MODE: ${WORKLOAD_MODE:-idle} + volumes: [test-data:/work] + entrypoint: [/bin/sh, /app/run-tests.sh] + healthcheck: + test: [CMD-SHELL, 'test -f "/work/$$TEST_RUN/input.json"'] + interval: 1s + timeout: 2s + retries: 120 + test-client: + <<: *owned + profiles: [test] + build: + context: ${DEV_SOURCE_DIR} + dockerfile: dev/Dockerfile.client + image: ${PRINTING_DEV_PROJECT}-client:local + network_mode: service:minio-test + depends_on: + test-server: + condition: service_healthy + volumes: [test-data:/work] + command: ["/work/${TEST_RUN:-run-uninitialized}"] + +volumes: + minio-data: + labels: + io.qrun.printing.dev: ${PRINTING_DEV_PROJECT} + qqq-data: + labels: + io.qrun.printing.dev: ${PRINTING_DEV_PROJECT} + test-data: + labels: + io.qrun.printing.dev: ${PRINTING_DEV_PROJECT} +networks: + default: + labels: + io.qrun.printing.dev: ${PRINTING_DEV_PROJECT} diff --git a/dev/java/DevHost.java b/dev/java/DevHost.java new file mode 100644 index 0000000..4d7677d --- /dev/null +++ b/dev/java/DevHost.java @@ -0,0 +1,145 @@ +/* + * QQQ - Low-code Application Framework for Engineers. + * Copyright (C) 2026. 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. + */ + +// SPDX-License-Identifier: Apache-2.0 +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.time.Duration; +import com.kingsrook.qqq.backend.core.exceptions.QException; +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.base.model.metadata.Cardinality; +import com.kingsrook.qqq.backend.module.filesystem.s3.model.metadata.S3BackendMetaData; +import com.kingsrook.qqq.backend.module.filesystem.s3.model.metadata.S3TableBackendDetails; +import com.kingsrook.qqq.backend.module.filesystem.s3.utils.S3ClientFactory; +import com.kingsrook.qqq.middleware.javalin.QApplicationLauncher; +import com.kingsrook.qqq.middleware.javalin.QApplicationLauncherConfig; +import software.amazon.awssdk.services.s3.model.CreateBucketRequest; +import software.amazon.awssdk.services.s3.model.HeadBucketRequest; +import software.amazon.awssdk.services.s3.model.S3Exception; + +/** Docker-only developer host. Compose publishes its port to host loopback only. */ +public final class DevHost extends PrintingLocalHost +{ + private static final String TABLE = "printing_documents"; + + private DevHost() throws Exception + { + super(new PrintingLocalSettings("jdbc:h2:file:/data/printing", "sa", required("QQQ_DATABASE_PASSWORD"), "development", + Integer.parseInt(required("QQQ_HTTP_PORT")), required("QQQ_MANAGEMENT_TOKEN"), "developer", required("QQQ_ADMIN_PASSWORD"))); + } + + public static void main(String[] args) throws Exception + { + waitStorage(); + if(args.length == 1 && "--wait-storage".equals(args[0])) + { + return; + } + DevHost host = new DevHost(); + QApplicationLauncher.run(host, new QApplicationLauncherConfig().withServerCustomizer(server -> + { + host.configure(server, true); + // Container interface only. The immutable Compose mapping binds host 127.0.0.1. + var original = server.getJavalinConfigCustomizer(); + server.withJavalinConfigCustomizer(config -> + { + original.accept(config); + config.jetty.host = "0.0.0.0"; + }); + })); + } + + @Override + public QInstance defineQInstance() throws QException + { + QInstance instance = super.defineQInstance(); + S3BackendMetaData backend = new S3BackendMetaData().withName("printing_development_storage").withBucketName("printing-development") + .withEndpoint("http://127.0.0.1:9000").withPathStyleAccess(true).withRegion("us-east-1") + .withAccessKey(required("MINIO_ROOT_USER")).withSecretKey(required("MINIO_ROOT_PASSWORD")); + backend.setConnectTimeoutMillis(3000); + backend.setSocketTimeoutMillis(15000); + instance.addBackend(backend); + instance.addTable(new QTableMetaData().withName(TABLE).withBackendName(backend.getName()) + .withBackendDetails(new S3TableBackendDetails().withCardinality(Cardinality.ONE).withFileNameFieldName("id").withContentsFieldName("content")) + .withPrimaryKeyField("id").withField(new QFieldMetaData("id", QFieldType.STRING)).withField(new QFieldMetaData("content", QFieldType.BLOB))); + var storage = S3ClientFactory.getClient(backend); + { + try + { + storage.headBucket(HeadBucketRequest.builder().bucket("printing-development").build()); + } + catch(S3Exception missing) + { + if(missing.statusCode() != 404) + { + throw missing; + } + storage.createBucket(CreateBucketRequest.builder().bucket("printing-development").build()); + } + } + PrintingQBitConfig config = instance.getQBits().values().stream().map(value -> value.getConfig()) + .filter(PrintingQBitConfig.class::isInstance).map(PrintingQBitConfig.class::cast).findFirst().orElseThrow(); + config.withStorageTableName(TABLE); + config.getService().configureStorage(instance, TABLE); + return instance; + } + + private static void waitStorage() throws Exception + { + try(HttpClient client = HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(2)).build()) + { + long deadline = System.nanoTime() + Duration.ofSeconds(60).toNanos(); + while(System.nanoTime() < deadline) + { + try + { + if(client.send(HttpRequest.newBuilder(URI.create("http://127.0.0.1:9000/minio/health/live")) + .timeout(Duration.ofSeconds(2)).GET().build(), HttpResponse.BodyHandlers.discarding()).statusCode() == 200) + { + return; + } + } + catch(java.io.IOException notReady) + { + // Only the fixture startup window retries; application work is never retried here. + } + Thread.sleep(200); + } + throw new IllegalStateException("Owned MinIO startup timed out"); + } + } + + private static String required(String name) + { + String value = System.getenv(name); + if(value == null || value.isBlank()) + { + throw new IllegalArgumentException("Missing development environment setting: " + name); + } + return value; + } +} diff --git a/dev/java/S3PrintingQualification.java b/dev/java/S3PrintingQualification.java new file mode 100644 index 0000000..8ebd807 --- /dev/null +++ b/dev/java/S3PrintingQualification.java @@ -0,0 +1,220 @@ +/* + * QQQ - Low-code Application Framework for Engineers. + * Copyright (C) 2026. 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. + */ + +// SPDX-License-Identifier: Apache-2.0 +import com.kingsrook.qbits.printing.*; +import com.kingsrook.qqq.backend.core.context.QContext; +import com.kingsrook.qqq.backend.core.model.metadata.*; +import com.kingsrook.qqq.backend.core.model.metadata.authentication.QAuthenticationMetaData; +import com.kingsrook.qqq.backend.core.model.metadata.fields.*; +import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData; +import com.kingsrook.qqq.backend.module.filesystem.s3.model.metadata.*; +import com.kingsrook.qqq.backend.module.filesystem.base.model.metadata.Cardinality; +import com.kingsrook.qqq.backend.module.filesystem.s3.utils.S3ClientFactory; +import java.nio.charset.StandardCharsets; +import java.nio.file.*; +import java.security.MessageDigest; +import java.sql.*; +import java.time.Instant; +import java.util.*; +import org.json.*; +import software.amazon.awssdk.core.sync.RequestBody; +import software.amazon.awssdk.services.s3.S3Client; +import software.amazon.awssdk.services.s3.model.*; + +/** Non-listening synthetic harness. Never routes work to a Windows device. */ +public final class S3PrintingQualification { + private static final String TABLE = "printing_documents"; + private static final JSONArray CHECKS = new JSONArray(); + private static final JSONArray DOCUMENTS = new JSONArray(); + private static final Map OBJECT_KEYS = new HashMap<>(); + private static DriverDataSource database; + private static S3Client s3; + private static String bucket; + private static String otherBucket; + + public static void main(String[] args) throws Exception { + Path output = Path.of(args[0]).toAbsolutePath(); + Files.createDirectories(output); + String run = args[2]; + bucket = "printing-fixture-" + run; + otherBucket = "printing-canary-" + run; + S3BackendMetaData backend = new S3BackendMetaData().withName("printing_s3_" + run) + .withBucketName(bucket).withEndpoint(args[1]).withPathStyleAccess(true).withRegion("us-east-1") + .withAccessKey(System.getenv("MINIO_ROOT_USER")).withSecretKey(System.getenv("MINIO_ROOT_PASSWORD")); + backend.setConnectTimeoutMillis(3000); + backend.setSocketTimeoutMillis(15000); + QInstance instance = new QInstance(); + // Required metadata only: this harness opens no HTTP endpoint or user session. + instance.withInstanceDefaultAuthentication(new QAuthenticationMetaData().withName("fixture").withType(QAuthenticationType.MOCK)); + instance.addBackend(backend); + instance.addTable(new QTableMetaData().withName(TABLE).withBackendName(backend.getName()) + .withBackendDetails(new S3TableBackendDetails().withCardinality(Cardinality.ONE) + .withFileNameFieldName("id").withContentsFieldName("content")).withPrimaryKeyField("id") + .withField(new QFieldMetaData("id", QFieldType.STRING)).withField(new QFieldMetaData("content", QFieldType.BLOB))); + database = new DriverDataSource("jdbc:h2:file:" + output.resolve("synthetic-data").toString().replace('\\', '/'), "sa", ""); + try { + s3 = S3ClientFactory.getClient(backend); + s3.createBucket(CreateBucketRequest.builder().bucket(bucket).build()); + s3.createBucket(CreateBucketRequest.builder().bucket(otherBucket).build()); + s3.putObject(PutObjectRequest.builder().bucket(bucket).key("unrelated/canary.txt").build(), RequestBody.fromString("synthetic unrelated object")); + s3.putObject(PutObjectRequest.builder().bucket(otherBucket).key("canary.txt").build(), RequestBody.fromString("synthetic separate bucket")); + PrintingService a = service(instance, "fixture-tenant-a"); + PrintingService b = service(instance, "fixture-tenant-b"); + String deviceA = enroll(a); + String deviceB = enroll(b); + byte[] pdf = PrintingTestDocuments.pdf(); + byte[] zpl = "^XA^FO20,20^ADN,30,18^FDSYNTHETIC STORAGE TEST ONLY^FS^XZ".getBytes(StandardCharsets.US_ASCII); + byte[] large = new byte[6 * 1024 * 1024 + 71]; + Arrays.fill(large, (byte)'A'); + System.arraycopy("^XA^FX".getBytes(StandardCharsets.US_ASCII), 0, large, 0, 6); + System.arraycopy("^FS^XZ".getBytes(StandardCharsets.US_ASCII), 0, large, large.length - 6, 6); + String pdfJob = submitCheck(a, deviceA, "small-pdf", "PDF", pdf, false); + finish(a, deviceA, pdfJob, "SPOOLED"); + String zplJob = submitCheck(a, deviceA, "small-zpl", "ZPL", zpl, false); + finish(a, deviceA, zplJob, "SPOOLED"); + String largeJob = submitCheck(a, deviceA, "multipart-zpl", "ZPL", large, true); + finish(a, deviceA, largeJob, "SPOOLED"); + String foreignJob = submitCheck(b, deviceB, "foreign-zpl", "ZPL", zpl, false); + finish(b, deviceB, foreignJob, "SPOOLED"); + String foreignRef = reference(foreignJob); + String ownRef = reference(pdfJob); + check(!ownRef.split("/")[1].equals(foreignRef.split("/")[1]), "tenant prefixes differ"); + expectStatus(404, () -> a.content(deviceA, foreignJob), "foreign tenant job download denied"); + expectStatus(404, () -> a.content(deviceB, foreignJob), "foreign tenant device rejected"); + execute("UPDATE printing_job SET content_reference=? WHERE id=?", foreignRef, pdfJob); + expectStatus(409, () -> a.content(deviceA, pdfJob), "foreign stored reference rejected"); + execute("UPDATE printing_job SET content_reference=? WHERE id=?", ownRef, pdfJob); + check(Arrays.equals(zpl, b.content(deviceB, foreignJob)), "foreign object unchanged after rejection"); + String failed = submitCheck(a, deviceA, "protected-failed", "ZPL", zpl, false); + finish(a, deviceA, failed, "FAILED"); + String unknown = submitCheck(a, deviceA, "protected-unknown", "ZPL", zpl, false); + finish(a, deviceA, unknown, "OUTCOME_UNKNOWN"); + String active = a.submit(request(deviceA, "protected-queued", "ZPL", zpl)).getString("jobId"); + String old = Instant.now().minusSeconds(400L * 86400).toString(); + for(String id : List.of(pdfJob, largeJob, foreignJob, failed, unknown, active)) { + execute("UPDATE printing_job SET created_at=?,completed_at=? WHERE id=?", old, old, id); + } + int before = objectCount(); + check(a.runRetention() == 2, "tenant A retention removes exactly two aged successful documents"); + check(objectCount() == before - 2, "object count reflects exact two removals"); + missing(OBJECT_KEYS.get(ownRef)); + missing(OBJECT_KEYS.get(reference(largeJob))); + expectStatus(410, () -> a.content(deviceA, pdfJob), "expired document returns 410"); + check(a.submit(request(deviceA, "small-pdf", "PDF", pdf)).getString("jobId").equals(pdfJob), "idempotent replay survives retention without reupload"); + check(objectCount() == before - 2, "post-retention replay creates no object"); + for(String id : List.of(zplJob, foreignJob, failed, unknown, active)) { + check(s3.headObject(HeadObjectRequest.builder().bucket(bucket).key(objectKey(reference(id))).build()).contentLength() == zpl.length, + "protected object retained: " + status(id)); + } + check(s3.getObjectAsBytes(GetObjectRequest.builder().bucket(bucket).key("unrelated/canary.txt").build()).asUtf8String().equals("synthetic unrelated object"), "unrelated same-bucket canary preserved"); + check(s3.getObjectAsBytes(GetObjectRequest.builder().bucket(otherBucket).key("canary.txt").build()).asUtf8String().equals("synthetic separate bucket"), "separate bucket canary preserved"); + check(a.runRetention() == 0, "repeated cleanup is idempotent"); + check(b.runRetention() == 1, "tenant B cleanup independently removes its one eligible document"); + check(s3.listMultipartUploads(ListMultipartUploadsRequest.builder().bucket(bucket).build()).uploads().isEmpty(), "no incomplete multipart uploads remain"); + check(QContext.getQSession() == null, "storage restores original absent QQQ session"); + JSONObject result = new JSONObject().put("passed", true).put("timestamp", Instant.now().toString()) + .put("checks", CHECKS).put("documents", DOCUMENTS).put("runtimeJarCount", 204) + .put("appRevision", System.getenv("PRINTING_SOURCE_COMMIT")) + .put("h2Version", org.h2.engine.Constants.VERSION).put("retentionDays", a.getRetentionSettings().getInt("days")) + .put("transport", "loopback HTTP S3-compatible only").put("hardwarePrinting", false) + .put("qualifies", "QQQ StorageAction / AWS SDK v2 S3 data-plane behavior against disposable MinIO") + .put("doesNotQualify", new JSONArray(List.of("AWS IAM", "remote TLS", "production bucket ownership", "Object Lock/version lifecycle", "remote deployment", "hardware printing"))); + Files.writeString(output.resolve("results.json"), result.toString(2) + "\n"); + System.out.println("PASS " + CHECKS.length() + " checks; " + DOCUMENTS.length() + " synthetic document round trips"); + } finally { + Files.writeString(output.resolve("completed-checks.json"), new JSONObject().put("checks", CHECKS).put("documents", DOCUMENTS).toString(2) + "\n"); + S3ClientFactory.clearCache(); + QContext.clear(); + } + } + private static PrintingService service(QInstance instance, String tenant) throws Exception { + PrintingService service = new PrintingService(database, tenant); + service.initialize(); service.configureStorage(instance, TABLE); return service; + } + private static String enroll(PrintingService service) throws Exception { + String id = service.enroll(service.createEnrollment("fixture", "Synthetic station") + .put("deviceName", "Synthetic station").put("agentVersion", "isolated-storage-fixture")).getString("deviceId"); + service.inventory(id, new JSONArray().put(new JSONObject().put("printerId", "synthetic-never-dispatched") + .put("name", "Synthetic storage-only destination").put("status", "READY").put("formats", new JSONArray(List.of("PDF", "ZPL"))))); + service.enablePrinter(id, "synthetic-never-dispatched", true); return id; + } + private static JSONObject request(String device, String key, String format, byte[] bytes) { + return new JSONObject().put("deviceId", device).put("printerId", "synthetic-never-dispatched").put("title", "Synthetic storage qualification") + .put("format", format).put("contentBase64", Base64.getEncoder().encodeToString(bytes)).put("idempotencyKey", key); + } + private static String submitCheck(PrintingService service, String device, String key, String format, byte[] bytes, boolean multipart) throws Exception { + JSONObject request = request(device, key, format, bytes); + String id = service.submit(request).getString("jobId"); + int count = objectCount(); + check(id.equals(service.submit(request).getString("jobId")) && count == objectCount(), key + " stable replay creates no object"); + check(service.claim(device).getJSONObject("job").getString("jobId").equals(id), key + " claimed through production service"); + byte[] actual = service.content(device, id); + check(Arrays.equals(bytes, actual) && sha(bytes).equals(sha(actual)), key + " download bytes and SHA256 match"); + String ref = reference(id); + String actualKey = objectKey(ref); + HeadObjectResponse head = s3.headObject(HeadObjectRequest.builder().bucket(bucket).key(actualKey).build()); + check(head.contentLength() == bytes.length, key + " object length exact"); + check(head.contentType().equals(format.equals("PDF") ? "application/pdf" : "application/vnd.zebra-zpl"), key + " content type correct"); + check(head.eTag().contains("-2") == multipart, key + " expected single/multipart object ETag"); + try(var c = database.getConnection(); var statement = c.prepareStatement("SELECT content_base64,content_storage_table FROM printing_job WHERE id=?")) { + statement.setString(1, id); try(var rows = statement.executeQuery()) { check(rows.next() && rows.getString(1) == null && TABLE.equals(rows.getString(2)), key + " payload external, no inline database copy"); } + } + DOCUMENTS.put(new JSONObject().put("case", key).put("format", format).put("bytes", bytes.length).put("sha256", sha(bytes)).put("multipart", multipart).put("etag", head.eTag()) + .put("objectKeyEqualsStoredReference", actualKey.equals(ref)).put("objectKeyPrefixBeforeReference", actualKey.substring(0, actualKey.length() - ref.length()))); + return id; + } + private static void finish(PrintingService service, String device, String id, String status) throws Exception { + for(String phase : List.of("RECEIVED", "SUBMITTING", status)) service.event(device, id, new JSONObject().put("eventId", UUID.randomUUID().toString()).put("status", phase).put("message", "Synthetic receipt; no physical device or spooler used")); + } + private static String sha(byte[] bytes) throws Exception { return HexFormat.of().formatHex(MessageDigest.getInstance("SHA-256").digest(bytes)); } + private static int objectCount() { return s3.listObjectsV2(ListObjectsV2Request.builder().bucket(bucket).build()).contents().size(); } + private static String objectKey(String reference) { + String known = OBJECT_KEYS.get(reference); + if(known != null) return known; + List matches = s3.listObjectsV2(ListObjectsV2Request.builder().bucket(bucket).build()).contents().stream() + .map(S3Object::key).filter(key -> key.endsWith(reference)).toList(); + if(matches.size() != 1) throw new AssertionError("Expected exactly one synthetic object for stored reference"); + String key = matches.getFirst(); + String prefix = key.substring(0, key.length() - reference.length()); + if(!prefix.isEmpty() && !prefix.matches("\\\\+")) throw new AssertionError("Unexpected physical S3 key prefix"); + OBJECT_KEYS.put(reference, key); + return key; + } + private static String reference(String id) throws Exception { return field(id, "content_reference"); } + private static String status(String id) throws Exception { return field(id, "status"); } + private static String field(String id, String field) throws Exception { + try(var c = database.getConnection(); var statement = c.prepareStatement("SELECT " + field + " FROM printing_job WHERE id=?")) { + statement.setString(1,id); try(var rows=statement.executeQuery()) { if(!rows.next()) throw new AssertionError("Missing synthetic job"); return rows.getString(1); } + } + } + private static void execute(String sql, String... args) throws Exception { + try(var c = database.getConnection(); var statement = c.prepareStatement(sql)) { for(int i=0; i launches=new ArrayList<>(); List services=new ArrayList<>(); + List devices=new ArrayList<>(); JSONArray inputs=new JSONArray(); + boolean idle=args.length>1 && args[1].equals("idle"); int total=idle?40:10000; long started=System.nanoTime(); int exit=1; + try { + for(int tenant=0;tenant<2;tenant++) { + PrintingLocalHost host=new PrintingLocalHost(new PrintingLocalSettings(jdbc,"sa","","tenant-"+tenant,0,"fixture-only-management-token-123456","operator",password)); + AtomicReference app=new AtomicReference<>(); + QApplicationLauncher launch=QApplicationLauncher.run(host,new QApplicationLauncherConfig().withRegisterShutdownHook(false).withServerCustomizer(server->{host.configure(server,false);server.withJavalinConfigurationCustomizer(app::set);})); + launches.add(launch); + PrintingService service=launch.getQInstance().getQBits().values().stream().map(v->v.getConfig()).filter(PrintingQBitConfig.class::isInstance).map(PrintingQBitConfig.class::cast).findFirst().orElseThrow().getService(); + services.add(service); + for(int lane=0;lane<4;lane++) { + JSONObject enrolled=service.enrollForUser(service.createEnrollment("default","Synthetic lane").put("deviceName","Synthetic lane").put("agentVersion","qualification"),"operator"); + String device=enrolled.getString("deviceId");devices.add(device); + service.inventory(device,new JSONArray().put(new JSONObject().put("printerId","synthetic").put("name","No physical printer").put("status","READY").put("formats",new JSONArray().put("ZPL"))));service.enablePrinter(device,"synthetic",true); + inputs.put(new JSONObject().put("origin","http://127.0.0.1:"+app.get().port()+"/").put("username","operator").put("password",password).put("tenant","tenant-"+tenant).put("deviceId",device).put("deviceToken",enrolled.getString("deviceToken"))); + } + } + // Only synthetic credentials inside the already protected run directory. + Files.writeString(dir.resolve("input.json"),new JSONObject().put("lanes",inputs).put("idle",idle).put("jobsPerLane",total/8).toString()); + await(dir.resolve("ready"),Duration.ofMinutes(2)); + byte[] payload=("^XA^FO20,20^FDSYNTHETIC NOT PRINTED^FS"+" ".repeat(980)+"^XZ").getBytes(StandardCharsets.US_ASCII); + String encoded=Base64.getEncoder().encodeToString(payload); + long producing=System.nanoTime(); + if(idle) { for(int job=0;job> futures=new ArrayList<>(); + for(int lane=0;lane<8;lane++) { final int index=lane; + futures.add(executor.submit(()->{try{ + PrintingService service=services.get(index/4); + for(int job=0;job<1250;job++) { + JSONObject request=new JSONObject().put("deviceId",devices.get(index)).put("printerId","synthetic").put("title","Synthetic workload "+job).put("format","ZPL").put("contentBase64",encoded).put("idempotencyKey","lane-"+index+"-"+job); + JSONObject submitted=service.submit(request); + if(job%25==0 && !submitted.getString("jobId").equals(service.submit(request).getString("jobId")))throw new IllegalStateException("Replay duplicated job"); + } + }catch(Exception e){throw new RuntimeException(e);}})); + } + for(var future:futures)future.get(15,TimeUnit.MINUTES); + } + double producerSeconds=(System.nanoTime()-producing)/1e9; + Files.writeString(dir.resolve("producer-done"),"done"); + await(dir.resolve("done"),Duration.ofMinutes(15)); + JSONObject client=new JSONObject(Files.readString(dir.resolve("result.json"))); + if(!client.getBoolean("success"))throw new IllegalStateException("Client reported failure"); + JSONObject report=new JSONObject().put("success",true).put("jobs",total).put("receipts",total*3).put("idle",idle).put("producerSeconds",producerSeconds).put("elapsedSeconds",(System.nanoTime()-started)/1e9).put("realPrinterCalls",0); + try(Connection connection=DriverManager.getConnection(jdbc,"sa","");Statement query=connection.createStatement()) { + require(query,"SELECT COUNT(*) FROM printing_job",total); + require(query,"SELECT COUNT(*) FROM printing_job WHERE status='SPOOLED'",total); + require(query,"SELECT COUNT(*) FROM printing_event",total*3); + require(query,"SELECT COUNT(*) FROM printing_document_orphan",0); + for(int tenant=0;tenant<2;tenant++) { + require(query,"SELECT COUNT(*) FROM printing_job WHERE tenant_id='tenant-"+tenant+"'",total/2); + require(query,"SELECT retained_bytes FROM printing_resource_usage WHERE tenant_id='tenant-"+tenant+"' AND device_id=''",(total/2L)*payload.length); + } + JSONArray cross=new JSONArray();for(int tenant=0;tenant<2;tenant++) { + String foreign=services.get(1-tenant).jobsPage(1,null).getJSONArray("jobs").getJSONObject(0).getString("jobId"); + try {services.get(tenant).getJob(foreign);throw new IllegalStateException("Foreign job visible");}catch(PrintingException denied){if(denied.getStatus()!=404)throw denied;} + cross.put(true); + } + report.put("tenantIsolation",cross).put("retainedAccountingVerified",true).put("bytesPerDocument",payload.length); + } + Files.writeString(dir.resolve("server-result.json"),report.toString(2));exit=0; + } catch(Throwable failure) { + Files.writeString(dir.resolve("server-error.json"),new JSONObject().put("error",failure.getClass().getName()).put("cause",failure.getCause()==null?"":failure.getCause().getClass().getName()).toString()); + } finally { + for(int i=launches.size()-1;i>=0;i--)launches.get(i).stop(); + try(Connection connection=DriverManager.getConnection(jdbc,"sa","");Statement query=connection.createStatement()){query.execute("SHUTDOWN");} + Files.writeString(dir.resolve("stopped.json"),new JSONObject().put("normalStop",true).put("exitCode",exit).toString()); + } + System.exit(exit); + } + static void await(Path file,Duration limit)throws Exception {long deadline=System.nanoTime()+limit.toNanos();while(!Files.exists(file)){if(System.nanoTime()>deadline)throw new TimeoutException("Fixture deadline");Thread.sleep(100);}} + static void require(Statement query,String sql,long expected)throws Exception {try(ResultSet rows=query.executeQuery(sql)){if(!rows.next()||rows.getLong(1)!=expected)throw new IllegalStateException("Synthetic count/accounting mismatch");}} +} diff --git a/dev/log4j2.xml b/dev/log4j2.xml new file mode 100644 index 0000000..88817ee --- /dev/null +++ b/dev/log4j2.xml @@ -0,0 +1,14 @@ + + + + + + + + + + + diff --git a/dev/native-auth/Caddyfile b/dev/native-auth/Caddyfile new file mode 100644 index 0000000..2451363 --- /dev/null +++ b/dev/native-auth/Caddyfile @@ -0,0 +1,20 @@ +{ + admin off + skip_install_trust + auto_https disable_redirects +} + +https://auth.printing.internal { + tls internal + reverse_proxy 127.0.0.1:9000 +} + +https://qqq.printing.internal { + tls internal + reverse_proxy native-qqq:19082 +} + +https://callback.printing.internal { + tls internal + reverse_proxy native-client:8088 +} diff --git a/dev/native-auth/Dockerfile.client b/dev/native-auth/Dockerfile.client new file mode 100644 index 0000000..ab03c27 --- /dev/null +++ b/dev/native-auth/Dockerfile.client @@ -0,0 +1,22 @@ +# Copyright 2026 Kingsrook, LLC +# SPDX-License-Identifier: Apache-2.0 + +FROM mcr.microsoft.com/dotnet/sdk:10.0@sha256:de4fe90a98845d75910b9769662465c84de1a934665c431279d1382b2bddc02b AS build +# Same exact published production Core source as the normal development workload. +ADD --checksum=sha256:82fcdbf7240760939a63b219aeb15a2333b3a8a02b52307a8a328500fca71fb6 https://github.com/QRun-IO/qqq-print-agent/archive/346fc285198908c47a2ee9db7b9adb53d5e88c3c.tar.gz /tmp/client.tar.gz +RUN mkdir /client && tar -xzf /tmp/client.tar.gz -C /client --strip-components=1 && rm /tmp/client.tar.gz +RUN dotnet build /client/src/Qqq.PrintAgent.Core/Qqq.PrintAgent.Core.csproj -c Release -p:Platform=x64 -p:Version=0.3.1-rc.1 -p:RestoreLockedMode=true --nologo +RUN mkdir /core && cp /client/src/Qqq.PrintAgent.Core/bin/x64/Release/net10.0/Qqq.PrintAgent.Core.dll /core/ +WORKDIR /fixture/dev/native-auth/client +COPY dev/native-auth/client . +COPY dev/client/WorkloadDiscovery.cs /fixture/dev/client/WorkloadDiscovery.cs +RUN dotnet build -c Release --nologo -o /out +RUN dotnet /out/NativeAuth.dll --check-discovery + +FROM mcr.microsoft.com/dotnet/sdk:10.0@sha256:de4fe90a98845d75910b9769662465c84de1a934665c431279d1382b2bddc02b +WORKDIR /app +COPY --from=build /out . +COPY dev/native-auth/start-client.sh /app/start-client.sh +RUN chmod 0555 /app/start-client.sh +ENV DOTNET_EnableDiagnostics=0 +ENTRYPOINT ["/app/start-client.sh"] diff --git a/dev/native-auth/Dockerfile.server b/dev/native-auth/Dockerfile.server new file mode 100644 index 0000000..f68c627 --- /dev/null +++ b/dev/native-auth/Dockerfile.server @@ -0,0 +1,29 @@ +# Copyright 2026 Kingsrook, LLC +# SPDX-License-Identifier: Apache-2.0 + +FROM maven:3.9.11-eclipse-temurin-21@sha256:6fdc855a6ed81d288ca7ca37ac6ff5e9308b612485c0801d70b25a858c83d237 AS build +# DEVELOPMENT ONLY: exact public candidate, never installed into a host Maven cache. +ADD --checksum=sha256:d99bafdf5520d0dc039b598787c003f23505cec3a652eb8ded496a24c6ed6060 https://github.com/QRun-IO/qqq/archive/ecf0f550a0357cec6387c2b54efca128a405a629.tar.gz /tmp/core.tar.gz +RUN mkdir /candidate && tar -xzf /tmp/core.tar.gz -C /candidate --strip-components=1 && rm /tmp/core.tar.gz +WORKDIR /candidate +RUN mvn -B -Dmaven.repo.local=/candidate-maven -Drevision=4.1.0-native-dev-ecf0f550 -Dmaven.test.skip=true -pl qqq-bom,qqq-backend-core,qqq-backend-module-rdbms,qqq-backend-module-filesystem,qqq-middleware-javalin -am install +WORKDIR /printing +COPY pom.xml mvnw ./ +COPY .mvn .mvn +COPY checkstyle checkstyle +COPY src src +COPY LICENSE NOTICE ./ +RUN chmod +x mvnw && ./mvnw -B -Dmaven.repo.local=/candidate-maven -Dqqq.version=4.1.0-native-dev-ecf0f550 -Dmaven.test.skip=true package dependency:copy-dependencies -DincludeScope=runtime -DoutputDirectory=target/runtime +COPY dev/native-auth/java /fixture-src +RUN mkdir /fixture-classes && javac -proc:none -cp 'target/classes:target/runtime/*' -d /fixture-classes /fixture-src/*.java + +FROM eclipse-temurin:21-jdk-jammy@sha256:742daacb9316be4b6fc60258f6e4ac2a11882f6c597373c92290a57bfad0d2e0 +WORKDIR /app +COPY --from=build /printing/target/classes classes +COPY --from=build /printing/target/runtime lib +COPY --from=build /fixture-classes fixture +COPY dev/log4j2.xml /app/log4j2.xml +COPY dev/native-auth/start-server.sh /app/start-server.sh +RUN chmod 0555 /app/start-server.sh +ENV NATIVE_CORE_SOURCE=ecf0f550a0357cec6387c2b54efca128a405a629 +ENTRYPOINT ["/app/start-server.sh"] diff --git a/dev/native-auth/README.md b/dev/native-auth/README.md new file mode 100644 index 0000000..233b116 --- /dev/null +++ b/dev/native-auth/README.md @@ -0,0 +1,96 @@ +# Experimental native Authentik qualification + +This optional profile tests an **unreleased upstream QQQ candidate**. It does +not replace the default released RC.20 TABLE/MinIO development environment, +install a connector, or qualify the Windows browser callback UI. + +From the repository root, with Docker and PowerShell 7.4 or later: + +```powershell +pwsh ./dev/Invoke-Dev.ps1 -Action Test -ExperimentalNativeAuth +``` + +The command creates a fresh owned project, builds the pinned sources, runs the +test, and removes its containers, network and synthetic database volumes in +`finally`. Protected input and sanitized result files remain outside the +checkout. Do not print or commit the private input or Compose environment. +An explicit fresh `-StateDirectory` preserves the same cleanup behavior. +Persistent `Start` and conversion of an existing standard environment are +refused for this profile. + +The test uses actual Authentik login stages with generated synthetic accounts, +the standard QQQ OAuth2 code/session/refresh handlers, and the published .NET +Core PKCE/session client. The provider issues the authorization codes. The +client receives a real HTTPS callback and stores only the opaque QQQ session +in process; provider refresh tokens remain on the QQQ server. + +The required checks are: + +- Ordinary TLS rejects the fixture before its private CA is installed. +- Actual API discovery advertises the typed native session grant. +- Authorized real provider login resolves a server-derived native identity. +- A wrong-Origin cookie request and an authenticated subject without the + printing permission are rejected. +- A logged-out QQQ session cannot be replayed. +- After the 20-second provider access grant expires, standard QQQ renewal + obtains a new provider grant and preserves the principal and tenant. +- Revoking the synthetic subject's provider refresh grants prevents renewal + after the next access-grant expiry. + +Success is recorded only when every check passes. A failure report contains +the stage and exception type, without callback URLs, credentials or response +bodies. This short renewal test does not prove months of unattended operation. + +Printing discovery accepts stable semantic versions in major 2, including +2.0.0 and 2.1.0, through the same production Core validation and shared major +gate as the default workload. The experimental upstream API must still be +exactly 1.9.0 with `nativeSessionLogin`; typed metadata, PKCE, TLS, callback and +permission checks are unchanged. The native-client image build runs 12 fake-HTTP +compatibility checks before any provider or fixture input is used. + +## Isolation and source pins + +The upstream source is +[`ecf0f550a0357cec6387c2b54efca128a405a629`](https://github.com/QRun-IO/qqq/commit/ecf0f550a0357cec6387c2b54efca128a405a629). +Its archive checksum is pinned in `Dockerfile.server`. Maven installs the +development build only into `/candidate-maven` inside the image; no host Maven +cache or installed runtime is mounted or changed. Printing source is compiled +against that candidate solely for this test. + +The production .NET Core client is pinned to published source +[`346fc285198908c47a2ee9db7b9adb53d5e88c3c`](https://github.com/QRun-IO/qqq-print-agent/commit/346fc285198908c47a2ee9db7b9adb53d5e88c3c) +with a checked archive hash. Authentik, PostgreSQL, Caddy, Java and .NET images +are pinned by digest in the Compose files and Dockerfiles. + +Caddy issues the three fixture HTTPS hostnames using its private local CA. +`skip_install_trust` prevents automatic trust installation. Only the public +root certificate is copied to the Java and .NET containers' trust stores; +ordinary chain and hostname validation remain enabled. CA private keys stay +in the TLS container's owned volume. No Windows or browser trust store changes +occur. See [Caddy's local HTTPS documentation](https://caddyserver.com/docs/automatic-https#local-https). + +The HTTPS callback receiver is internal to the Compose network. It is separate +from the installed connector's private URI callback. No callback host port is +published. The profile mounts public Caddy configuration and the two specific +private input/result files, rather than a host home or credential directory. + +The QQQ fixture uses fresh standard session, redirect-state and encrypted +refresh-token tables. Its customizer maps the verified provider's synthetic +`printing_admin` group to the existing native permission. It creates no device +pairing, job, print operation or fabricated user session. Released RC.20 lacks +the native-session grant; this experiment must stay opt-in until an appropriate +immutable upstream tuple is published and separately adopted. + +## Recorded local qualification + +On 2026-11-01 the full disposable profile passed all eight checks and exited zero. +Independent inventory confirmed zero owned containers, volumes and networks after +cleanup. This is evidence for the pinned experimental tuple above, not adoption +into the default released runtime or installed Windows UI acceptance. + +A fresh run against server source `3592dec` (printing API 2.1.0) and the reviewed +probe compatibility correction also passed all eight checks on 2026-11-01. +All source files matched the pre-run hash manifest through completion, and +independent cleanup again found no owned containers, volumes or networks. +The native image's 12 discovery checks and default workload's nine checks pass. +The unreleased upstream and installed-browser limitations above still apply. diff --git a/dev/native-auth/client/CallbackReceiver.cs b/dev/native-auth/client/CallbackReceiver.cs new file mode 100644 index 0000000..0aa7138 --- /dev/null +++ b/dev/native-auth/client/CallbackReceiver.cs @@ -0,0 +1,54 @@ +// Copyright 2026 Kingsrook, LLC +// SPDX-License-Identifier: Apache-2.0 + +using System.Net; +using System.Threading.Channels; + +namespace Printing.NativeAuth; + +/// Receives the actual HTTPS-proxied callback only inside this test network. +internal sealed class CallbackReceiver : IDisposable +{ + private readonly HttpListener _listener = new(); + private readonly Channel _callbacks = Channel.CreateBounded(1); + private readonly Uri _callback; + + internal CallbackReceiver(Uri callback) + { + _callback = callback; + _listener.Prefixes.Add("http://+:8088/"); + _listener.Start(); + _ = ReceiveAsync(); + } + + private async Task ReceiveAsync() + { + try + { + while(_listener.IsListening) + { + HttpListenerContext context = await _listener.GetContextAsync(); + Uri? request = context.Request.Url; + bool valid = request is not null && request.AbsolutePath == _callback.AbsolutePath + && context.Request.Headers["Host"] == _callback.Authority + && context.Request.Headers["X-Forwarded-Proto"] == "https" + && context.Request.HttpMethod == "GET" && request.Query.Length is > 0 and < 16384; + if(valid) + { + var actual = new UriBuilder(_callback) { Query = request!.Query.TrimStart('?') }; + valid = _callbacks.Writer.TryWrite(actual.Uri); + } + context.Response.StatusCode = valid ? 200 : 400; + context.Response.ContentLength64 = 0; + context.Response.Close(); + } + } + catch(Exception exception) when(exception is HttpListenerException or ObjectDisposedException) + { + _callbacks.Writer.TryComplete(); + } + } + + internal ValueTask ReadAsync(CancellationToken token) => _callbacks.Reader.ReadAsync(token); + public void Dispose() => _listener.Close(); +} diff --git a/dev/native-auth/client/FixtureHttp.cs b/dev/native-auth/client/FixtureHttp.cs new file mode 100644 index 0000000..38c7ee9 --- /dev/null +++ b/dev/native-auth/client/FixtureHttp.cs @@ -0,0 +1,87 @@ +// Copyright 2026 Kingsrook, LLC +// SPDX-License-Identifier: Apache-2.0 + +using System.Net; +using System.Net.Http.Headers; +using System.Text; +using System.Text.Json.Nodes; + +namespace Printing.NativeAuth; + +/// Small bounded fixture transport; no redirects, proxy or response-body diagnostics. +internal sealed class FixtureHttp : IDisposable +{ + internal sealed record Reply(HttpStatusCode Status, JsonObject? Json, Uri? Location); + internal sealed record TraceEntry(string Kind, int Status, bool HasQuery, string? LocationKind, bool LocationHasQuery); + internal static List Trace { get; } = []; + internal static string? LastRequestKind { get; private set; } + internal static int? LastStatus { get; private set; } + private readonly HttpClient _client; + private readonly CookieContainer _cookies = new(); + private readonly Uri _origin; + private readonly string? _adminToken; + + internal FixtureHttp(Uri origin, bool cookies = false, string? adminToken = null) + { + _origin = origin; + _adminToken = adminToken; + _client = new HttpClient(new HttpClientHandler { AllowAutoRedirect = false, UseProxy = false, UseCookies = cookies, CookieContainer = _cookies }) + { + Timeout = TimeSpan.FromSeconds(15), + MaxResponseContentBufferSize = 524288, + }; + } + + internal async Task SendAsync(string method, Uri uri, JsonObject? body, CancellationToken cancellationToken) + { + if(uri.Scheme != "https" || uri.GetLeftPart(UriPartial.Authority) != _origin.GetLeftPart(UriPartial.Authority)) + { + throw new InvalidOperationException("A fixture request left its configured HTTPS origin."); + } + using var request = new HttpRequestMessage(new HttpMethod(method), uri); + // Fixed classifications only: never retain a query, callback, identifier or body. + LastRequestKind = Classify(uri, method); + LastStatus = null; + if(_adminToken is not null) + { + if(!uri.AbsolutePath.StartsWith("/api/v3/", StringComparison.Ordinal)) { throw new InvalidOperationException("Administrative credential scope refused."); } + request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", _adminToken); + } + if(body is not null) + { + request.Content = new StringContent(body.ToJsonString(), Encoding.UTF8, "application/json"); + request.Headers.Add("Origin", _origin.GetLeftPart(UriPartial.Authority)); + request.Headers.Referrer = _origin; + Cookie? csrf = _cookies.GetCookies(_origin).Cast().SingleOrDefault(cookie => cookie.Name == "authentik_csrf"); + csrf ??= _cookies.GetCookies(_origin).Cast().SingleOrDefault(cookie => cookie.Name == "csrftoken"); + if(csrf is not null) { request.Headers.Add("X-authentik-CSRF", csrf.Value); } + } + using HttpResponseMessage response = await _client.SendAsync(request, cancellationToken); + LastStatus = (int)response.StatusCode; + Uri? location = response.Headers.Location is null ? null : new Uri(_origin, response.Headers.Location); + if(Trace.Count == 32) { Trace.RemoveAt(0); } + Trace.Add(new TraceEntry(LastRequestKind, (int)response.StatusCode, uri.Query.Length != 0, + location is null ? null : Classify(location, "GET"), location?.Query.Length > 0)); + string content = await response.Content.ReadAsStringAsync(cancellationToken); + JsonObject? json = response.Content.Headers.ContentType?.MediaType == "application/json" && content.Length != 0 + ? JsonNode.Parse(content)?.AsObject() : null; + return new Reply(response.StatusCode, json, response.Headers.Location); + } + + internal Task SendAsync(string method, string path, JsonObject? body, CancellationToken cancellationToken) + => SendAsync(method, new Uri(_origin, path), body, cancellationToken); + + private static string Classify(Uri uri, string method) => uri.Host == "callback.printing.internal" ? "callback" + : uri.AbsolutePath.StartsWith("/application/o/authorize", StringComparison.Ordinal) ? "provider-authorization" + : uri.AbsolutePath.StartsWith("/if/flow/", StringComparison.Ordinal) ? "provider-flow-page" + : uri.AbsolutePath.StartsWith("/api/v3/flows/executor/", StringComparison.Ordinal) ? "provider-flow-executor-" + method + : "fixture-api"; + + internal static JsonObject RequireJson(Reply reply, HttpStatusCode expected) + { + if(reply.Status != expected || reply.Json is null) { throw new InvalidOperationException("Unexpected fixture API status or document shape."); } + return reply.Json; + } + + public void Dispose() => _client.Dispose(); +} diff --git a/dev/native-auth/client/NativeAuth.csproj b/dev/native-auth/client/NativeAuth.csproj new file mode 100644 index 0000000..4e8ac0d --- /dev/null +++ b/dev/native-auth/client/NativeAuth.csproj @@ -0,0 +1,18 @@ + + + + + Exe + net10.0 + enable + enable + true + + + /core/Qqq.PrintAgent.Core.dll + + + diff --git a/dev/native-auth/client/NativeAuthDiscovery.cs b/dev/native-auth/client/NativeAuthDiscovery.cs new file mode 100644 index 0000000..839e5f7 --- /dev/null +++ b/dev/native-auth/client/NativeAuthDiscovery.cs @@ -0,0 +1,22 @@ +/* + * Copyright 2026 Kingsrook, LLC + * SPDX-License-Identifier: Apache-2.0 + */ + +using Qqq.PrintAgent.Core.Authentication; + +namespace Printing.NativeAuth; + +/// Requires the pinned experimental native grant before provider authentication. +internal static class NativeAuthDiscovery +{ + /// Checks actual production discovery without sending credentials. + internal static async Task DiscoverAsync(QqqSessionClient client, CancellationToken token) + { + QqqApiDiscovery discovery = await WorkloadDiscovery.DiscoverRealtimeAsync(client, token); + if(discovery.ApiVersion != "1.9.0" || !discovery.Features.Contains("nativeSessionLogin", StringComparer.Ordinal)) + { + throw new InvalidOperationException("The actual server did not advertise the pinned native-session API."); + } + } +} diff --git a/dev/native-auth/client/NativeAuthDiscoveryChecks.cs b/dev/native-auth/client/NativeAuthDiscoveryChecks.cs new file mode 100644 index 0000000..57a2d5f --- /dev/null +++ b/dev/native-auth/client/NativeAuthDiscoveryChecks.cs @@ -0,0 +1,93 @@ +/* + * Copyright 2026 Kingsrook, LLC + * SPDX-License-Identifier: Apache-2.0 + */ + +using System.Net; +using System.Text.Json; +using Qqq.PrintAgent.Core.Authentication; + +namespace Printing.NativeAuth; + +/// Exercises the real native probe gate against bounded, credential-free HTTP responses. +internal static class NativeAuthDiscoveryChecks +{ + /// Accepts compatible printing releases while preserving the exact upstream grant requirement. + internal static async Task RunAsync() + { + (string PrintingVersion, string ApiVersion, bool NativeGrant, bool Accepted)[] cases = + [ + ("2.0.0", "1.9.0", true, true), + ("2.1.0", "1.9.0", true, true), + ("2.9.17", "1.9.0", true, true), + ("1.9.0", "1.9.0", true, false), + ("3.0.0", "1.9.0", true, false), + ("2.1", "1.9.0", true, false), + ("2.01.0", "1.9.0", true, false), + ("2.1.0-rc.1", "1.9.0", true, false), + ("not-a-version", "1.9.0", true, false), + ("2.1.0", "1.8.0", true, false), + ("2.1.0", "1.10.0", true, false), + ("2.1.0", "1.9.0", false, false), + ]; + foreach((string printingVersion, string apiVersion, bool nativeGrant, bool expected) in cases) + { + using var handler = new DiscoveryHandler(printingVersion, apiVersion, nativeGrant); + using var client = new QqqSessionClient(new Uri("https://printing.example.invalid"), handler); + bool accepted = false; + try + { + await NativeAuthDiscovery.DiscoverAsync(client, CancellationToken.None); + accepted = true; + } + catch(QqqSessionException error) when(error.Failure == QqqSessionException.FailureKind.ConfigurationRequired) + { + } + catch(InvalidDataException) + { + } + catch(InvalidOperationException) + { + } + if(accepted != expected || handler.Requests != 1) + { + throw new InvalidDataException($"Native discovery compatibility case {printingVersion}/{apiVersion}/grant={nativeGrant} failed."); + } + } + Console.WriteLine($"Native discovery compatibility checks passed: {cases.Length}."); + } + + + + /// Supplies discovery only and fails if the probe attempts authenticated traffic. + private sealed class DiscoveryHandler(string printingVersion, string apiVersion, bool nativeGrant) : HttpMessageHandler + { + /// Ensures rejected metadata still traversed the public HTTP discovery boundary. + internal int Requests { get; private set; } + + + + /// Refuses any credential or request outside the public discovery boundary. + protected override Task SendAsync(HttpRequestMessage request, CancellationToken cancellationToken) + { + if(request.Method != HttpMethod.Get || request.RequestUri?.AbsoluteUri != "https://printing.example.invalid/qqq/v1/version" + || request.Headers.Contains("Cookie") || request.Headers.Contains("Authorization") + || request.Headers.Contains("X-QQQ-Device-Id") || request.Headers.Contains("X-QQQ-Device-Token")) + { + throw new InvalidOperationException("Native discovery must precede authentication and device proof."); + } + Requests++; + string[] features = nativeGrant + ? ["version", "metaData", "processes", "processCancel", "extensions", "widgets", "nativeSessionLogin"] + : ["version", "metaData", "processes", "processCancel", "extensions", "widgets"]; + string json = JsonSerializer.Serialize(new + { + apiVersion, + features, + clientChannels = new[] { "api" }, + extensions = new[] { new { name = "printing", version = printingVersion, pathPrefix = "/qbit/printing" } } + }); + return Task.FromResult(new HttpResponseMessage(HttpStatusCode.OK) { Content = new StringContent(json) }); + } + } +} diff --git a/dev/native-auth/client/Program.cs b/dev/native-auth/client/Program.cs new file mode 100644 index 0000000..a61fe33 --- /dev/null +++ b/dev/native-auth/client/Program.cs @@ -0,0 +1,241 @@ +// Copyright 2026 Kingsrook, LLC +// SPDX-License-Identifier: Apache-2.0 + +using System.Net; +using System.Security.Authentication; +using System.Text.Json; +using System.Text.Json.Nodes; +using System.Text.RegularExpressions; +using Qqq.PrintAgent.Core.Authentication; + +namespace Printing.NativeAuth; + +internal static class Program +{ + private const string CoreSource = "ecf0f550a0357cec6387c2b54efca128a405a629"; + private const string ClientSource = "346fc285198908c47a2ee9db7b9adb53d5e88c3c"; + private const string InputPath = "/work/input.json"; + private const string ResultPath = "/work/result.json"; + private const string TlsMarker = "/tmp/printing-native-untrusted-tls-passed"; + private static readonly List Checks = []; + private static string _stage = "input"; + private static bool? _authorizationRequestMatches; + + public static async Task Main(string[] arguments) + { + if(arguments is ["--check-discovery"]) + { + await NativeAuthDiscoveryChecks.RunAsync(); + return 0; + } + JsonObject? input = null; + try + { + if(arguments.Length != 1 || arguments[0] is not ("assert-untrusted" or "test")) + { throw new InvalidOperationException("An explicit fixture action is required."); } + if(new FileInfo(InputPath).Length is <= 0 or > 65536) + { throw new InvalidOperationException("Fixture input size is invalid."); } + input = JsonNode.Parse(await File.ReadAllTextAsync(InputPath))!.AsObject(); + ValidateInput(input); + using var deadline = new CancellationTokenSource(TimeSpan.FromMinutes(5)); + if(arguments[0] == "assert-untrusted") + { + _stage = "untrusted-tls"; + await AssertUntrustedAsync(new Uri(ProviderSetup.Text(input, "providerOrigin")), deadline.Token); + await File.WriteAllTextAsync(TlsMarker, "passed", deadline.Token); + return 0; + } + if(!File.Exists(TlsMarker)) { throw new InvalidOperationException("The ordinary TLS negative control did not run."); } + Checks.Add("untrusted-tls-refused"); + await QualifyAsync(input, deadline.Token); + await WriteResultAsync(input, "PASS", null, null); + Console.WriteLine("Experimental native Authentik qualification passed; development-only unpublished core."); + return 0; + } + catch(Exception exception) + { + // Exception messages, response bodies, callback URLs and credentials are deliberately withheld. + await WriteResultAsync(input, "FAILED", exception.GetType().Name, + exception is QqqSessionException sessionException ? sessionException.Failure.ToString() : null); + Console.Error.WriteLine("Experimental native Authentik qualification failed at " + _stage + " (" + exception.GetType().Name + ")."); + return 1; + } + } + + private static void ValidateInput(JsonObject input) + { + if(!Regex.IsMatch(ProviderSetup.Text(input, "project"), "^qbit-printing-dev-[a-f0-9]{32}$", RegexOptions.CultureInvariant) + || ProviderSetup.Text(input, "coreSource") != CoreSource || ProviderSetup.Text(input, "clientSource") != ClientSource + || ProviderSetup.Text(input, "providerOrigin") != "https://auth.printing.internal" + || ProviderSetup.Text(input, "qqqOrigin") != "https://qqq.printing.internal" + || ProviderSetup.Text(input, "callback") != "https://callback.printing.internal/oauth/callback" + || ProviderSetup.Text(input, "issuer") != "https://auth.printing.internal/application/o/" + ProviderSetup.Text(input, "project") + "/" + || ProviderSetup.Text(input, "clientId") != ProviderSetup.Text(input, "project")) + { throw new InvalidOperationException("Fixture identity or destination differs from the pinned local contract."); } + } + + private static QqqSessionClient Session(Uri origin) => new(origin, + new HttpClientHandler { AllowAutoRedirect = false, UseCookies = false, UseProxy = false }); + + private static async Task AssertUntrustedAsync(Uri origin, CancellationToken token) + { + using var transport = new FixtureHttp(origin); + try { await transport.SendAsync("GET", "/-/health/live/", null, token); } + catch(HttpRequestException exception) + { + for(Exception? cause = exception; cause is not null; cause = cause.InnerException) + { + if(cause is AuthenticationException) { return; } + } + throw new InvalidOperationException("The negative TLS control failed for a reason other than certificate authentication."); + } + throw new InvalidOperationException("The test unexpectedly trusted its private CA before scoped installation."); + } + + private static async Task QualifyAsync(JsonObject input, CancellationToken token) + { + var origin = new Uri(ProviderSetup.Text(input, "qqqOrigin")); + var providerOrigin = new Uri(ProviderSetup.Text(input, "providerOrigin")); + var callback = new Uri(ProviderSetup.Text(input, "callback")); + _stage = "readiness"; + await WaitForQqqAsync(origin, token); + using var provider = new ProviderSetup(input); + _stage = "provider-readiness"; + await provider.WaitReadyAsync(token); + _stage = "provider-configuration"; + await provider.ConfigureAsync(token); + using var receiver = new CallbackReceiver(callback); + using var first = Session(origin); + _stage = "typed-native-discovery"; + await NativeAuthDiscovery.DiscoverAsync(first, token); + QqqAuthenticationMetadata metadata = await first.GetAuthenticationMetadataAsync(token); + if(metadata.Values?.ClientId != ProviderSetup.Text(input, "clientId")) + { throw new InvalidOperationException("Native metadata did not retain the configured client identifier."); } + Checks.Add("typed-native-grant"); + + _stage = "real-provider-login"; + await LoginAsync(first, receiver, input, providerOrigin, callback, authorized: true, token); + _stage = "authorized-native-identity"; + QqqSessionBinding identity = await first.GetSessionIdentityAsync(token); + if(string.IsNullOrWhiteSpace(identity.PrincipalId) || identity.TenantId != "printing-native-dev" || identity.DeviceId is not null) + { throw new InvalidOperationException("The native subject did not receive the intended server-derived identity."); } + Checks.Add("real-provider-login"); + _stage = "wrong-origin-cookie"; + await AssertWrongOriginAsync(origin, first.ExportCredential(), token); + await first.GetSessionIdentityAsync(token); + Checks.Add("wrong-origin-cookie-denied"); + + _stage = "permission-denied-user"; + using(var denied = Session(origin)) + { + await LoginAsync(denied, receiver, input, providerOrigin, callback, authorized: false, token); + await ExpectFailureAsync(() => denied.GetSessionIdentityAsync(token), QqqSessionException.FailureKind.PermissionDenied); + await denied.SignOutAsync(token); + } + Checks.Add("permission-denied-user"); + + _stage = "logout-replay"; + QqqSessionCredential retired = first.ExportCredential(); + await first.SignOutAsync(token); + using(var replay = Session(origin)) + { await ExpectFailureAsync(() => replay.RestoreSessionAsync(retired, token), QqqSessionException.FailureKind.AuthenticationRequired); } + Checks.Add("logout-replay-denied"); + + _stage = "fresh-login-for-renewal"; + using var renewable = Session(origin); + await LoginAsync(renewable, receiver, input, providerOrigin, callback, authorized: true, token); + QqqSessionBinding before = await renewable.GetSessionIdentityAsync(token); + HashSet previousGrants = await provider.AccessGrantIdsAsync(token); + _stage = "server-refresh-after-expiry"; + await Task.Delay(TimeSpan.FromSeconds(22), token); + await renewable.ResumeSessionAsync(token); + QqqSessionBinding after = await renewable.GetSessionIdentityAsync(token); + HashSet refreshedGrants = await provider.AccessGrantIdsAsync(token); + if(before != after || !refreshedGrants.Except(previousGrants, StringComparer.Ordinal).Any()) + { throw new InvalidOperationException("Renewal did not preserve the identity and obtain a new actual provider grant."); } + Checks.Add("server-refresh-after-expiry"); + + _stage = "provider-revocation-after-expiry"; + await provider.RevokeRefreshGrantsAsync(token); + await Task.Delay(TimeSpan.FromSeconds(22), token); + await ExpectFailureAsync(() => renewable.ResumeSessionAsync(token), QqqSessionException.FailureKind.AuthenticationRequired); + Checks.Add("provider-revocation-denied"); + _stage = "complete"; + } + + private static async Task LoginAsync(QqqSessionClient client, CallbackReceiver receiver, JsonObject input, + Uri providerOrigin, Uri callback, bool authorized, CancellationToken token) + { + string role = authorized ? "authorized" : "denied"; + _stage = role + "-begin-pkce"; + QqqBrowserLogin attempt = await client.BeginBrowserLoginAsync(callback, token); + _stage = role + "-generated-authorization-request"; + Dictionary parameters = attempt.AuthorizationUri.Query.TrimStart('?').Split('&') + .Select(entry => entry.Split('=', 2)).ToDictionary(pair => Uri.UnescapeDataString(pair[0]), pair => Uri.UnescapeDataString(pair[1]), StringComparer.Ordinal); + _authorizationRequestMatches = attempt.AuthorizationUri.AbsolutePath == "/application/o/authorize/" + && parameters.GetValueOrDefault("client_id") == ProviderSetup.Text(input, "clientId") + && parameters.GetValueOrDefault("redirect_uri") == callback.AbsoluteUri + && parameters.GetValueOrDefault("response_type") == "code" + && parameters.GetValueOrDefault("code_challenge_method") == "S256" + && parameters.GetValueOrDefault("state")?.Length == 43; + if(_authorizationRequestMatches != true) + { throw new InvalidOperationException("The generated authorization request differs from the exact provider registration."); } + _stage = role + "-provider-flow"; + await ProviderFlow.AuthenticateAsync(attempt.AuthorizationUri, providerOrigin, callback, + ProviderSetup.Text(input, role + "Username"), ProviderSetup.Text(input, role + "Password"), token); + _stage = role + "-callback"; + Uri actualCallback = await receiver.ReadAsync(token); + _stage = role + "-exchange"; + await client.CompleteBrowserLoginAsync(attempt, actualCallback, token); + } + + private static async Task ExpectFailureAsync(Func operation, QqqSessionException.FailureKind expected) + { + try { await operation(); } + catch(QqqSessionException exception) when(exception.Failure == expected) { return; } + throw new InvalidOperationException("The expected native authentication or permission denial did not occur."); + } + + private static async Task AssertWrongOriginAsync(Uri origin, QqqSessionCredential credential, CancellationToken token) + { + using var http = new HttpClient(new HttpClientHandler { AllowAutoRedirect = false, UseCookies = false, UseProxy = false }) + { Timeout = TimeSpan.FromSeconds(15), MaxResponseContentBufferSize = 65536 }; + using var request = new HttpRequestMessage(HttpMethod.Get, new Uri(origin, "/qqq/v1/qbit/printing/session")); + request.Headers.Add("X-QQQ-Client", QqqSessionClient.ClientChannel); + request.Headers.Add("Cookie", "sessionUUID=" + credential.SessionToken); + request.Headers.Add("Origin", "https://wrong-origin.invalid"); + using HttpResponseMessage response = await http.SendAsync(request, token); + if(response.StatusCode != HttpStatusCode.Forbidden) + { throw new InvalidOperationException("The fixture did not reject a wrong-Origin cookie request."); } + } + + private static async Task WaitForQqqAsync(Uri origin, CancellationToken token) + { + using var http = new FixtureHttp(origin); + for(int attempt = 0; attempt < 45; attempt++) + { + try + { + FixtureHttp.Reply response = await http.SendAsync("GET", "/qqq/v1/version", null, token); + if(response.Status == HttpStatusCode.OK && response.Json is not null) { return; } + } + catch(HttpRequestException) { } + await Task.Delay(TimeSpan.FromSeconds(2), token); + } + throw new InvalidOperationException("The owned native host did not become ready."); + } + + private static Task WriteResultAsync(JsonObject? input, string status, string? failureType, string? sessionFailure) + => File.WriteAllTextAsync(ResultPath, JsonSerializer.Serialize(new + { + status, scope = "DEVELOPMENT_ONLY_UNRELEASED", coreSource = CoreSource, clientSource = ClientSource, + project = input?["project"]?.ToString(), observedUtc = DateTimeOffset.UtcNow, stage = _stage, failureType, + sessionFailure, lastRequestKind = FixtureHttp.LastRequestKind, lastHttpStatus = FixtureHttp.LastStatus, + lastProviderComponent = ProviderFlow.LastComponent, + authorizationRequestMatches = _authorizationRequestMatches, + requestClassifications = FixtureHttp.Trace, + providerLookupKind = ProviderSetup.LastLookupKind, providerLookupCount = ProviderSetup.LastLookupCount, + providerReadinessCounts = ProviderSetup.ReadinessCounts, + checks = Checks, installedUiAcceptance = false, providerRefreshTokensInClient = false, + }, new JsonSerializerOptions { WriteIndented = true })); +} diff --git a/dev/native-auth/client/ProviderFlow.cs b/dev/native-auth/client/ProviderFlow.cs new file mode 100644 index 0000000..0ac26d5 --- /dev/null +++ b/dev/native-auth/client/ProviderFlow.cs @@ -0,0 +1,95 @@ +// Copyright 2026 Kingsrook, LLC +// SPDX-License-Identifier: Apache-2.0 + +using System.Net; +using System.Text.Json.Nodes; + +namespace Printing.NativeAuth; + +/// Uses Authentik's real synthetic-user login stages; never fabricates a session or code. +internal static class ProviderFlow +{ + internal static string? LastComponent { get; private set; } + internal static async Task AuthenticateAsync(Uri authorization, Uri origin, Uri callback, string username, string password, CancellationToken token) + { + using var browser = new FixtureHttp(origin, cookies: true); + using var callbackHttp = new FixtureHttp(new Uri(callback.GetLeftPart(UriPartial.Authority))); + Uri next = authorization; + for(int hop = 0; hop < 24; hop++) + { + if(next.GetLeftPart(UriPartial.Authority) == callback.GetLeftPart(UriPartial.Authority)) + { + if(next.AbsolutePath != callback.AbsolutePath) { throw new InvalidOperationException("Unexpected callback path."); } + FixtureHttp.Reply result = await callbackHttp.SendAsync("GET", next, null, token); + if(result.Status != HttpStatusCode.OK) { throw new InvalidOperationException("The HTTPS callback receiver refused the provider redirect."); } + return; + } + if(next.GetLeftPart(UriPartial.Authority) != origin.GetLeftPart(UriPartial.Authority)) + { throw new InvalidOperationException("A provider redirect left the fixture."); } + FixtureHttp.Reply page = await browser.SendAsync("GET", next, null, token); + if(page.Status is HttpStatusCode.Redirect or HttpStatusCode.SeeOther or HttpStatusCode.TemporaryRedirect) + { + next = new Uri(next, page.Location ?? throw new InvalidOperationException("Missing provider redirect.")); + continue; + } + if(page.Status != HttpStatusCode.OK || !next.AbsolutePath.StartsWith("/if/flow/", StringComparison.Ordinal)) + { throw new InvalidOperationException("Unexpected provider login navigation."); } + string slug = next.AbsolutePath["/if/flow/".Length..].Trim('/'); + if(slug.Length == 0 || slug.Any(character => !char.IsAsciiLetterOrDigit(character) && character != '-')) + { throw new InvalidOperationException("Unexpected provider flow identifier."); } + var executor = new Uri(origin, "/api/v3/flows/executor/" + slug + "/?query=" + Uri.EscapeDataString(next.Query.TrimStart('?'))); + JsonObject challenge = await ChallengeAsync(browser, executor, await browser.SendAsync("GET", executor, null, token), token); + bool redirected = false; + for(int stage = 0; stage < 10; stage++) + { + string component = ProviderSetup.Text(challenge, "component"); + LastComponent = component switch + { + "ak-stage-identification" => "identification", + "ak-stage-password" => "password", + "ak-stage-consent" => "consent", + "xak-flow-redirect" => "redirect", + "ak-stage-access-denied" => "access-denied", + "ak-stage-flow-error" => "flow-error", + _ => "unsupported", + }; + if(component == "xak-flow-redirect") + { + next = new Uri(origin, ProviderSetup.Text(challenge, "to")); + redirected = true; + break; + } + JsonObject response = component switch + { + "ak-stage-identification" => new JsonObject { ["component"] = component, ["uid_field"] = username }, + "ak-stage-password" => new JsonObject { ["component"] = component, ["password"] = password }, + "ak-stage-consent" => new JsonObject { ["component"] = component, ["consent"] = true }, + _ => throw new InvalidOperationException("The provider requested an unsupported test login stage."), + }; + challenge = await ChallengeAsync(browser, executor, await browser.SendAsync("POST", executor, response, token), token); + if(challenge["response_errors"] is JsonObject errors && errors.Count != 0) + { throw new InvalidOperationException("The real provider rejected the synthetic login response."); } + } + if(!redirected) { throw new InvalidOperationException("Provider stage bound exceeded."); } + } + throw new InvalidOperationException("Provider redirect bound exceeded."); + } + + private static async Task ChallengeAsync(FixtureHttp browser, Uri executor, FixtureHttp.Reply response, CancellationToken token) + { + // Authentik uses POST/redirect/GET when a real stage accepts its answer. + // Follow only that same HTTPS executor; other navigation uses typed flow redirects. + for(int redirect = 0; redirect < 8; redirect++) + { + if(response.Status == HttpStatusCode.OK) { return FixtureHttp.RequireJson(response, HttpStatusCode.OK); } + if(response.Status is not (HttpStatusCode.Redirect or HttpStatusCode.SeeOther) || response.Location is null) + { throw new InvalidOperationException("Unexpected provider stage response."); } + var location = new Uri(executor, response.Location); + if(location.GetLeftPart(UriPartial.Authority) != executor.GetLeftPart(UriPartial.Authority) + || location.AbsolutePath != executor.AbsolutePath) + { throw new InvalidOperationException("A stage redirect left its exact HTTPS executor."); } + response = await browser.SendAsync("GET", location, null, token); + } + throw new InvalidOperationException("Provider stage redirect bound exceeded."); + } +} diff --git a/dev/native-auth/client/ProviderSetup.cs b/dev/native-auth/client/ProviderSetup.cs new file mode 100644 index 0000000..226f617 --- /dev/null +++ b/dev/native-auth/client/ProviderSetup.cs @@ -0,0 +1,184 @@ +// Copyright 2026 Kingsrook, LLC +// SPDX-License-Identifier: Apache-2.0 + +using System.Net; +using System.Text.Json.Nodes; + +namespace Printing.NativeAuth; + +/// Configures only the fresh project's synthetic provider and subjects. +internal sealed class ProviderSetup : IDisposable +{ + internal static string? LastLookupKind { get; private set; } + internal static int? LastLookupCount { get; private set; } + internal static Dictionary ReadinessCounts { get; } = new(StringComparer.Ordinal); + private readonly JsonObject _input; + private readonly FixtureHttp _admin; + private string _provider = ""; + private string _authorizedUser = ""; + + internal ProviderSetup(JsonObject input) + { + _input = input; + _admin = new FixtureHttp(new Uri(Text(input, "providerOrigin")), adminToken: Text(input, "adminToken")); + } + + internal static string Text(JsonObject document, string key) => document[key]?.ToString() ?? throw new InvalidOperationException("Required fixture field is absent."); + + private async Task ExactAsync(string path, CancellationToken token) + { + JsonObject page = FixtureHttp.RequireJson(await _admin.SendAsync("GET", path, null, token), HttpStatusCode.OK); + JsonArray records = page["results"]!.AsArray(); + LastLookupKind = LookupKind(path); + LastLookupCount = records.Count; + if(records.Count != 1) { throw new InvalidOperationException("Required provider object is absent or ambiguous."); } + return records[0]!.AsObject(); + } + + private async Task CreateAsync(string path, JsonObject body, CancellationToken token) + => FixtureHttp.RequireJson(await _admin.SendAsync("POST", path, body, token), HttpStatusCode.Created); + + internal async Task WaitReadyAsync(CancellationToken token) + { + string[] paths = ["/api/v3/flows/instances/?slug=default-authentication-flow", + "/api/v3/flows/instances/?slug=default-provider-authorization-implicit-consent", + "/api/v3/flows/instances/?slug=default-provider-invalidation-flow", + "/api/v3/propertymappings/provider/scope/?scope_name=openid", + "/api/v3/propertymappings/provider/scope/?scope_name=profile", + "/api/v3/propertymappings/provider/scope/?scope_name=email", + "/api/v3/propertymappings/provider/scope/?scope_name=offline_access"]; + for(int attempt = 0; attempt < 60; attempt++) + { + bool ready = true; + try + { + foreach(string path in paths) + { + FixtureHttp.Reply reply = await _admin.SendAsync("GET", path, null, token); + JsonArray? records = reply.Status == HttpStatusCode.OK ? reply.Json?["results"] as JsonArray : null; + string kind = LookupKind(path); + ReadinessCounts[kind] = records?.Count ?? -1; + if(records?.Count > 1) { throw new InvalidOperationException("An owned provider bootstrap dependency is ambiguous."); } + bool present = records is { Count: 1 }; + if(kind == "authentication-flow") + { present &= records is { Count: 1 } && records[0]?["stages"] is JsonArray { Count: >= 4 }; } + ready &= present; + } + if(ready) { return; } + } + catch(HttpRequestException) { } + await Task.Delay(TimeSpan.FromSeconds(2), token); + } + throw new InvalidOperationException("The owned provider bootstrap did not become ready."); + } + + private static string LookupKind(string path) => path switch + { + "/api/v3/flows/instances/?slug=default-authentication-flow" => "authentication-flow", + "/api/v3/flows/instances/?slug=default-provider-authorization-implicit-consent" => "authorization-flow", + "/api/v3/flows/instances/?slug=default-provider-invalidation-flow" => "invalidation-flow", + "/api/v3/propertymappings/provider/scope/?scope_name=openid" => "scope-openid", + "/api/v3/propertymappings/provider/scope/?scope_name=profile" => "scope-profile", + "/api/v3/propertymappings/provider/scope/?scope_name=email" => "scope-email", + "/api/v3/propertymappings/provider/scope/?scope_name=offline_access" => "scope-offline-access", + _ => "other", + }; + + internal async Task ConfigureAsync(CancellationToken token) + { + JsonObject authentication = await ExactAsync("/api/v3/flows/instances/?slug=default-authentication-flow", token); + JsonObject authorization = await ExactAsync("/api/v3/flows/instances/?slug=default-provider-authorization-implicit-consent", token); + JsonObject invalidation = await ExactAsync("/api/v3/flows/instances/?slug=default-provider-invalidation-flow", token); + var mappings = new JsonArray(); + foreach(string scope in new[] { "openid", "profile", "email", "offline_access" }) + { + mappings.Add((await ExactAsync("/api/v3/propertymappings/provider/scope/?scope_name=" + scope, token))["pk"]!.DeepClone()); + } + JsonObject groupsMapping = await CreateAsync("/api/v3/propertymappings/provider/scope/", new JsonObject + { + ["name"] = Text(_input, "project") + "-groups", + ["scope_name"] = "profile", + ["expression"] = "return {\"groups\": [group.name for group in user.ak_groups.all()]}", + }, token); + mappings.Add(groupsMapping["pk"]!.DeepClone()); + JsonObject group = await CreateAsync("/api/v3/core/groups/", new JsonObject { ["name"] = "printing_admin", ["is_superuser"] = false }, token); + JsonObject user = await CreateUserAsync("authorizedUsername", "authorizedPassword", new JsonArray(group["pk"]!.DeepClone()), token); + _authorizedUser = Text(user, "pk"); + await CreateUserAsync("deniedUsername", "deniedPassword", new JsonArray(), token); + JsonObject provider = await CreateAsync("/api/v3/providers/oauth2/", new JsonObject + { + ["name"] = Text(_input, "project"), + ["authentication_flow"] = authentication["pk"]!.DeepClone(), + ["authorization_flow"] = authorization["pk"]!.DeepClone(), + ["invalidation_flow"] = invalidation["pk"]!.DeepClone(), + ["client_type"] = "confidential", + ["grant_types"] = new JsonArray("authorization_code", "refresh_token"), + ["client_id"] = Text(_input, "clientId"), + ["client_secret"] = Text(_input, "clientSecret"), + ["access_code_validity"] = "minutes=1", + ["access_token_validity"] = "seconds=20", + ["refresh_token_validity"] = "minutes=5", + ["refresh_token_threshold"] = "minutes=4", + ["redirect_uris"] = new JsonArray(new JsonObject { ["matching_mode"] = "strict", ["url"] = Text(_input, "callback") }), + ["property_mappings"] = mappings, + ["issuer_mode"] = "per_provider", + ["include_claims_in_id_token"] = true, + }, token); + _provider = Text(provider, "pk"); + if(Text(provider, "client_id") != Text(_input, "clientId") + || Text(provider, "authentication_flow") != Text(authentication, "pk")) + { throw new InvalidOperationException("The real provider did not retain the configured client identifier."); } + JsonObject application = await CreateAsync("/api/v3/core/applications/", new JsonObject + { + ["name"] = Text(_input, "project"), ["slug"] = Text(_input, "project"), + ["provider"] = provider["pk"]!.DeepClone(), ["policy_engine_mode"] = "all", + }, token); + if(Text(application, "provider") != _provider) + { throw new InvalidOperationException("The real provider application binding differs from the configured provider."); } + } + + private async Task CreateUserAsync(string usernameKey, string passwordKey, JsonArray groups, CancellationToken token) + { + JsonObject user = await CreateAsync("/api/v3/core/users/", new JsonObject + { + ["username"] = Text(_input, usernameKey), ["name"] = "Synthetic native qualification subject", + ["email"] = Text(_input, usernameKey) + "@example.invalid", ["is_active"] = true, + ["type"] = "internal", ["groups"] = groups, + }, token); + FixtureHttp.Reply response = await _admin.SendAsync("POST", "/api/v3/core/users/" + Text(user, "pk") + "/set_password/", + new JsonObject { ["password"] = Text(_input, passwordKey) }, token); + if(response.Status != HttpStatusCode.NoContent) { throw new InvalidOperationException("Synthetic account password configuration failed."); } + return user; + } + + private async Task GrantsAsync(string kind, CancellationToken token) + { + JsonObject page = FixtureHttp.RequireJson(await _admin.SendAsync("GET", "/api/v3/oauth2/" + kind + "/?provider=" + _provider + "&user=" + _authorizedUser, null, token), HttpStatusCode.OK); + JsonArray records = page["results"]!.AsArray(); + if(records.Count is 0 or > 20) { throw new InvalidOperationException("The synthetic provider grant set is missing or unexpectedly large."); } + foreach(JsonNode? node in records) + { + JsonObject record = node!.AsObject(); + string provider = record["provider"] is JsonObject nested ? Text(nested, "pk") : Text(record, "provider"); + if(provider != _provider || Text(record["user"]!.AsObject(), "pk") != _authorizedUser) + { throw new InvalidOperationException("The provider grant escaped the synthetic subject scope."); } + } + return records; + } + + internal async Task> AccessGrantIdsAsync(CancellationToken token) + => (await GrantsAsync("access_tokens", token)).Select(node => Text(node!.AsObject(), "pk")).ToHashSet(StringComparer.Ordinal); + + internal async Task RevokeRefreshGrantsAsync(CancellationToken token) + { + foreach(JsonNode? node in await GrantsAsync("refresh_tokens", token)) + { + string id = Text(node!.AsObject(), "pk"); + if(!Guid.TryParse(id, out _) && !long.TryParse(id, out _)) { throw new InvalidOperationException("Unexpected provider grant identifier."); } + FixtureHttp.Reply response = await _admin.SendAsync("DELETE", "/api/v3/oauth2/refresh_tokens/" + id + "/", null, token); + if(response.Status != HttpStatusCode.NoContent) { throw new InvalidOperationException("Synthetic provider revocation failed."); } + } + } + + public void Dispose() => _admin.Dispose(); +} diff --git a/dev/native-auth/copy-root.sh b/dev/native-auth/copy-root.sh new file mode 100644 index 0000000..fd15407 --- /dev/null +++ b/dev/native-auth/copy-root.sh @@ -0,0 +1,17 @@ +#!/bin/sh +# Copyright 2026 Kingsrook, LLC +# SPDX-License-Identifier: Apache-2.0 + +set -eu +attempt=0 +while [ ! -s /data/caddy/pki/authorities/local/root.crt ]; do + attempt=$((attempt + 1)) + if [ "$attempt" -ge 60 ]; then + echo 'The fixture public CA certificate did not become ready.' >&2 + exit 1 + fi + sleep 1 +done +# Never copy the key or mount the private CA volume into a client/server. +cp /data/caddy/pki/authorities/local/root.crt /trust/root.crt +chmod 0644 /trust/root.crt diff --git a/dev/native-auth/java/NativeAuthHost.java b/dev/native-auth/java/NativeAuthHost.java new file mode 100644 index 0000000..9b4f8ff --- /dev/null +++ b/dev/native-auth/java/NativeAuthHost.java @@ -0,0 +1,224 @@ +/* + * QQQ - Low-code Application Framework for Engineers. + * Copyright (C) 2026. 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. + */ + +// SPDX-License-Identifier: Apache-2.0 +package com.kingsrook.qbits.printing; + +import java.net.URI; +import java.sql.Connection; +import java.util.List; +import java.util.Locale; +import java.util.Map; +import java.util.Set; +import java.util.UUID; +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.authentication.OAuth2AuthenticationMetaData; +import com.kingsrook.qqq.backend.core.model.metadata.authentication.OAuth2NativeSessionLoginMetaData; +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.tables.QTableMetaData; +import com.kingsrook.qqq.backend.core.model.session.QSession; +import com.kingsrook.qqq.backend.core.modules.authentication.QAuthenticationModuleCustomizerInterface; +import com.kingsrook.qqq.backend.core.modules.authentication.implementations.metadata.RedirectStateMetaDataProducer; +import com.kingsrook.qqq.backend.core.modules.authentication.implementations.metadata.UserSessionMetaDataProducer; +import com.kingsrook.qqq.backend.core.modules.authentication.implementations.metadata.UserSessionRefreshTokenMetaDataProducer; +import com.kingsrook.qqq.backend.core.modules.authentication.implementations.model.UserSession; +import com.kingsrook.qqq.backend.core.modules.authentication.implementations.model.UserSessionRefreshToken; +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; +import org.json.JSONArray; +import org.json.JSONObject; + +/** + * Opt-in container fixture for the pinned upstream native-session candidate. + * Standard OAuth2 code exchange, session storage and encrypted renewal are used + * unchanged. No installed pairing, password authentication double or printer. + */ +public final class NativeAuthHost extends AbstractQQQApplication +{ + private static final String TENANT = "printing-native-dev"; + private final String backendName = "printing-native-auth-" + UUID.randomUUID(); + private final String jdbcUrl = "jdbc:h2:file:/data/printing-native-auth"; + private final String databasePassword = required("NATIVE_QQQ_DATABASE_PASSWORD"); + private final URI origin = httpsOrigin(required("NATIVE_QQQ_ORIGIN")); + private final int port = Integer.parseInt(required("NATIVE_QQQ_PORT")); + private final DriverDataSource source = new DriverDataSource(jdbcUrl, "sa", databasePassword); + private final PrintingService service = new PrintingService(source, TENANT); + + private NativeAuthHost() throws Exception + { + if(port < 1024 || port > 65535) + { + throw new IllegalArgumentException("Unsupported internal fixture port"); + } + service.initialize(); + try(Connection connection = source.getConnection(); var statement = connection.createStatement()) + { + statement.execute("CREATE TABLE IF NOT EXISTS userSession (id INTEGER GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY, uuid VARCHAR(40) NOT NULL UNIQUE, userId VARCHAR(100), accessToken CLOB, createDate TIMESTAMP WITH TIME ZONE, modifyDate TIMESTAMP WITH TIME ZONE)"); + statement.execute("CREATE TABLE IF NOT EXISTS redirectState (id INTEGER GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY, state VARCHAR(45) NOT NULL UNIQUE, redirectUri VARCHAR(4096), createDate TIMESTAMP WITH TIME ZONE)"); + statement.execute("CREATE TABLE IF NOT EXISTS userSessionRefreshToken (id INTEGER GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY, sessionUuid VARCHAR(40) NOT NULL UNIQUE, refreshToken CLOB, refreshTokenExpiresAt TIMESTAMP WITH TIME ZONE, sessionStartedAt TIMESTAMP WITH TIME ZONE, createDate TIMESTAMP WITH TIME ZONE, modifyDate TIMESTAMP WITH TIME ZONE)"); + } + } + + public static void main(String[] args) throws Exception + { + NativeAuthHost host = new NativeAuthHost(); + QApplicationLauncher.run(host, new QApplicationLauncherConfig() + .withServerCustomizer(host::configure)); + } + + @Override + public QInstance defineQInstance() throws QException + { + QInstance instance = new QInstance(); + instance.setFailOnMetaDataProducerError(true); + instance.setHomeAppName("printing"); + instance.setBranding(new QBrandingMetaData().withAppName("QQQ native authentication fixture")); + instance.addBackend(new RDBMSBackendMetaData().withName(backendName).withVendor("h2").withHostName("fixture") + .withDatabaseName("printing-native-auth").withUsername("sa").withPassword(databasePassword).withJdbcUrl(jdbcUrl)); + instance.addTable(new UserSessionMetaDataProducer(backendName).produce(instance)); + instance.addTable(new RedirectStateMetaDataProducer(backendName).produce(instance)); + instance.addTable(new UserSessionRefreshTokenMetaDataProducer(backendName).produce(instance)); + + String issuer = required("NATIVE_AUTH_ISSUER"); + URI issuerUri = URI.create(issuer); + if(!"https".equals(issuerUri.getScheme()) || issuerUri.getHost() == null + || issuerUri.getRawUserInfo() != null || issuerUri.getRawQuery() != null || issuerUri.getRawFragment() != null || !issuer.endsWith("/")) + { + throw new IllegalArgumentException("An explicit HTTPS fixture issuer ending in slash is required"); + } + OAuth2AuthenticationMetaData authentication = new OAuth2AuthenticationMetaData() + .withBaseUrl(issuer).withExternalBaseUrl(issuer) + .withClientId(required("NATIVE_AUTH_CLIENT_ID")).withClientSecret(required("NATIVE_AUTH_CLIENT_SECRET")) + .withScopes("openid profile email offline_access") + .withUserSessionTableName(UserSession.TABLE_NAME).withRedirectStateTableName(RedirectStateMetaDataProducer.TABLE_NAME) + .withRefreshTokenTableName(UserSessionRefreshToken.TABLE_NAME) + .withRefreshTokensEnabled(true).withRefreshTokenSkewSeconds(0).withMaxSessionLifetimeSeconds(3600) + .withRefreshTokenEncryptionKey(required("NATIVE_QQQ_REFRESH_KEY")).withRefreshTokenEncryptionKeyId("fixture-1") + .withNativeSessionLogin(new OAuth2NativeSessionLoginMetaData().withIssuer(issuer) + .withDiscoveryUrl(issuer + ".well-known/openid-configuration") + .withRedirectUris(List.of(required("NATIVE_AUTH_REDIRECT_URI")))); + authentication.withName("printing-native-provider").withSessionStoreEnabled(false) + .withCustomizer(new QCodeReference(PrintingPermissions.class)); + instance.registerAuthenticationProvider(AuthScope.instanceDefault(), authentication); + new PrintingQBitProducer().withConfig(new PrintingQBitConfig().withBackendName(backendName).withService(service)) + .produce(instance, "printing"); + for(QTableMetaData table : instance.getTables().values()) + { + if(backendName.equals(table.getBackendName())) + { + table.withBackendDetails(new RDBMSTableBackendDetails().withTableName(table.getName().toUpperCase(Locale.ROOT))); + for(var field : table.getFields().values()) + { + field.withBackendName(field.getName().toUpperCase(Locale.ROOT)); + } + } + } + return instance; + } + + private void configure(QApplicationJavalinServer server) + { + // Only the owned TLS proxy is published; this HTTP listener remains inside + // the Compose network. Forwarded HTTPS is required even for discovery. + server.withPort(port).withServeFrontendNext(false).withServeFrontendMaterialDashboard(false) + .withAdditionalRouteProviders(List.of(new PrintingRealtimeRoutes(service))) + .withJavalinConfigCustomizer(config -> + { + config.jetty.host = "0.0.0.0"; + config.http.maxRequestSize = 1048576; + config.routes.before(this::guardOrigin); + }); + } + + private void guardOrigin(Context context) + { + if(!origin.getRawAuthority().equalsIgnoreCase(context.header("Host")) + || !"https".equals(context.header("X-Forwarded-Proto"))) + { + throw new ForbiddenResponse("The fixture requires its configured HTTPS proxy origin"); + } + String suppliedOrigin = context.header("Origin"); + if(suppliedOrigin != null && !origin.toString().equals(suppliedOrigin)) + { + throw new ForbiddenResponse("Cross-origin fixture requests are not allowed"); + } + if("cross-site".equalsIgnoreCase(context.header("Sec-Fetch-Site")) + || context.header("X-QQQ-In-Process-Session") != null) + { + throw new ForbiddenResponse("Only standard native session authentication is 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 && suppliedOrigin == null) + { + throw new ForbiddenResponse("Cookie mutations require the configured Origin"); + } + } + + /** Only maps claims after the unchanged standard OAuth2 module authenticates. */ + public static final class PrintingPermissions implements QAuthenticationModuleCustomizerInterface + { + @Override + public void customizeSession(QInstance instance, QSession session, Map context) + { + session.setPermissions(Set.of()); + session.withSecurityKeyValue("printing_tenant", TENANT); + Object claims = context.get("jwtPayloadJsonObject"); + if(session.getUser() != null && claims instanceof JSONObject payload) + { + JSONArray groups = payload.optJSONArray("groups"); + if(groups != null && groups.toList().contains("printing_admin")) + { + session.setPermissions(Set.of("printing_admin")); + } + } + } + } + + private static URI httpsOrigin(String value) + { + URI parsed = URI.create(value); + if(!"https".equals(parsed.getScheme()) || parsed.getHost() == null || parsed.getRawUserInfo() != null + || parsed.getRawQuery() != null || parsed.getRawFragment() != null || !parsed.getRawPath().isEmpty()) + { + throw new IllegalArgumentException("A root HTTPS fixture origin without trailing slash is required"); + } + return parsed; + } + + private static String required(String name) + { + String value = System.getenv(name); + if(value == null || value.isBlank()) + { + throw new IllegalArgumentException("Set the synthetic fixture variable " + name); + } + return value; + } +} diff --git a/dev/native-auth/start-client.sh b/dev/native-auth/start-client.sh new file mode 100644 index 0000000..51b0742 --- /dev/null +++ b/dev/native-auth/start-client.sh @@ -0,0 +1,11 @@ +#!/bin/sh +# Copyright 2026 Kingsrook, LLC +# SPDX-License-Identifier: Apache-2.0 + +set -eu +# This first request must fail with the ordinary TLS validator, before trust. +dotnet /app/NativeAuth.dll assert-untrusted +test -s /trust/root.crt +cp /trust/root.crt /usr/local/share/ca-certificates/printing-native-fixture.crt +update-ca-certificates >/dev/null 2>&1 +exec dotnet /app/NativeAuth.dll test diff --git a/dev/native-auth/start-server.sh b/dev/native-auth/start-server.sh new file mode 100644 index 0000000..42ccdee --- /dev/null +++ b/dev/native-auth/start-server.sh @@ -0,0 +1,10 @@ +#!/bin/sh +# Copyright 2026 Kingsrook, LLC +# SPDX-License-Identifier: Apache-2.0 + +set -eu +# Only this disposable container's JRE trust store is changed. The mounted file +# is the public root certificate; the CA private key is never mounted here. +test -s /trust/root.crt +keytool -importcert -noprompt -alias printing-native-fixture -file /trust/root.crt -cacerts -storepass changeit >/dev/null 2>&1 +exec java -Xmx768m -Dlog4j.configurationFile=/app/log4j2.xml -cp '/app/classes:/app/lib/*:/app/fixture' com.kingsrook.qbits.printing.NativeAuthHost diff --git a/dev/run-tests.sh b/dev/run-tests.sh new file mode 100644 index 0000000..500f884 --- /dev/null +++ b/dev/run-tests.sh @@ -0,0 +1,10 @@ +#!/bin/sh +# Copyright 2026 Kingsrook, LLC +# SPDX-License-Identifier: Apache-2.0 + +set -eu +case "$TEST_RUN" in run-[a-f0-9]*) ;; *) echo 'Invalid owned test run' >&2; exit 2;; esac +mkdir -p "/work/$TEST_RUN/s3" +java -Xmx768m -Dlog4j.configurationFile=/app/log4j2.xml -cp '/app/classes:/app/lib/*:/app/fixture' com.kingsrook.qbits.printing.DevHost --wait-storage +java -Xmx768m -Dlog4j.configurationFile=/app/log4j2.xml -cp '/app/classes:/app/lib/*:/app/fixture' S3PrintingQualification "/work/$TEST_RUN/s3" http://127.0.0.1:9000 "$TEST_RUN" +exec java -Xmx768m -Dlog4j.configurationFile=/app/log4j2.xml -cp '/app/classes:/app/lib/*:/app/fixture' com.kingsrook.qbits.printing.WorkloadFixture "/work/$TEST_RUN" "$WORKLOAD_MODE" diff --git a/dev/tests/Authentik.Tests.ps1 b/dev/tests/Authentik.Tests.ps1 new file mode 100644 index 0000000..6c5bc42 --- /dev/null +++ b/dev/tests/Authentik.Tests.ps1 @@ -0,0 +1,71 @@ +#Requires -Version 7.4 +# Copyright 2026 Kingsrook, LLC +# SPDX-License-Identifier: Apache-2.0 + +# No Docker or HTTP calls: these regressions exercise private bootstrap state. +BeforeAll { + $script:authScript = Join-Path $PSScriptRoot '../Invoke-Authentik.ps1' + $script:project = 'qbit-printing-dev-0123456789abcdef0123456789abcdef' +} + +Describe 'Authentik development bootstrap' { + BeforeEach { + $state = Join-Path $TestDrive ([Guid]::NewGuid().ToString('N')) + New-Item -ItemType Directory -Path $state | Out-Null + $envFile = Join-Path $state 'compose.env' + $prefix = "PRINTING_DEV_PROJECT=$project`nMINIO_ROOT_USER=synthetic`nQQQ_HTTP_PORT=19081`n" + [IO.File]::WriteAllText($envFile, $prefix) + } + + It 'preserves common environment values and creates a matching hashed admin password without console output' { + $output = @(& $authScript -Action Initialize -StateDirectory $state -ProjectName $project) + $output.Count | Should -Be 0 + $environment = Get-Content -LiteralPath $envFile -Raw + $environment.StartsWith($prefix, [StringComparison]::Ordinal) | Should -BeTrue + [regex]::Matches($environment, '(?m)^AUTHENTIK_[A-Z_]+=').Count | Should -Be 5 + $private = Get-Content -LiteralPath (Join-Path $state 'auth-secrets.json') -Raw | ConvertFrom-Json + $match = [regex]::Match($environment, '(?m)^AUTHENTIK_BOOTSTRAP_PASSWORD_HASH=''pbkdf2_sha256\$1000000\$([^$]+)\$([^'']+)''') + $match.Success | Should -BeTrue + $actual = [Convert]::ToBase64String([Security.Cryptography.Rfc2898DeriveBytes]::Pbkdf2($private.adminPassword, [Text.Encoding]::UTF8.GetBytes($match.Groups[1].Value), 1000000, [Security.Cryptography.HashAlgorithmName]::SHA256, 32)) + [string]::Equals($actual, $match.Groups[2].Value, [StringComparison]::Ordinal) | Should -BeTrue + } + + It 'does not rotate credentials or append duplicate keys on repeated initialization' { + & $authScript -Action Initialize -StateDirectory $state -ProjectName $project + $beforeEnvironment = (Get-FileHash -LiteralPath $envFile).Hash + $beforeSecrets = (Get-FileHash -LiteralPath (Join-Path $state 'auth-secrets.json')).Hash + & $authScript -Action Initialize -StateDirectory $state -ProjectName $project + (Get-FileHash -LiteralPath $envFile).Hash | Should -Be $beforeEnvironment + (Get-FileHash -LiteralPath (Join-Path $state 'auth-secrets.json')).Hash | Should -Be $beforeSecrets + } + + It 'rejects a changed project or port without overwriting private state' { + & $authScript -Action Initialize -StateDirectory $state -ProjectName $project + $before = (Get-FileHash -LiteralPath $envFile).Hash + { & $authScript -Action Initialize -StateDirectory $state -ProjectName $project -Port 19011 } | Should -Throw '*different project or port*' + { & $authScript -Action Initialize -StateDirectory $state -ProjectName 'qbit-printing-dev-aaaaaaaa' } | Should -Throw '*different project or port*' + (Get-FileHash -LiteralPath $envFile).Hash | Should -Be $before + } + + It 'rejects partial initialization rather than assigning different secrets to an existing database' { + Add-Content -LiteralPath $envFile -Value 'AUTHENTIK_SECRET_KEY=synthetic' + { & $authScript -Action Initialize -StateDirectory $state -ProjectName $project } | Should -Throw '*Partial Authentik initialization*' + Test-Path -LiteralPath (Join-Path $state 'auth-secrets.json') | Should -BeFalse + } + + It 'rejects missing environment keys after initialization' { + & $authScript -Action Initialize -StateDirectory $state -ProjectName $project + [IO.File]::WriteAllText($envFile, $prefix) + { & $authScript -Action Initialize -StateDirectory $state -ProjectName $project } | Should -Throw '*incomplete or ambiguous*' + } + + It 'withholds malformed private configuration contents' { + [IO.File]::WriteAllText((Join-Path $state 'auth-secrets.json'), '{"private":"synthetic-value-to-withhold"') + { & $authScript -Action Initialize -StateDirectory $state -ProjectName $project } | Should -Throw '*contents are withheld*' + } + + It 'refuses a state directory inside the source checkout before writing' { + $repository = [IO.Path]::GetFullPath((Join-Path $PSScriptRoot '../..')) + { & $authScript -Action Initialize -StateDirectory $repository -ProjectName $project } | Should -Throw '*outside the source checkout*' + } +} diff --git a/dev/tests/Lifecycle.Tests.ps1 b/dev/tests/Lifecycle.Tests.ps1 new file mode 100644 index 0000000..274ad94 --- /dev/null +++ b/dev/tests/Lifecycle.Tests.ps1 @@ -0,0 +1,129 @@ +#Requires -Version 7.4 +# Copyright 2026 Kingsrook, LLC +# SPDX-License-Identifier: Apache-2.0 + +# Ownership regressions use mocked Docker metadata; no containers or network calls. +BeforeAll { + $script:entrypoint = Join-Path $PSScriptRoot '../Invoke-Dev.ps1' + $tokens = $null + $errors = $null + $ast = [Management.Automation.Language.Parser]::ParseFile($entrypoint, [ref]$tokens, [ref]$errors) + if ($errors.Count) + { + throw 'Entrypoint parsing failed.' + } + foreach ($name in @('Assert-OwnedResource', 'Get-RecordedAuthentikPort')) + { + $guard = $ast.Find({ param($node) $node -is [Management.Automation.Language.FunctionDefinitionAst] -and $node.Name -eq $name }, $true) + . ([scriptblock]::Create($guard.Extent.Text)) + } + $script:project = 'qbit-printing-dev-0123456789abcdef0123456789abcdef' + function docker + { + throw 'Unmocked Docker call refused.' + } +} + +Describe 'Development lifecycle ownership' { + BeforeEach { + $script:wrongResource = '' + Mock docker { + $global:LASTEXITCODE = 0 + $command = $args -join ' ' + if ($command.StartsWith('ps -aq', [StringComparison]::Ordinal)) + { + return 'container-id' + } + if ($command.StartsWith('network ls', [StringComparison]::Ordinal)) + { + return 'network-id' + } + if ($command.StartsWith('volume ls', [StringComparison]::Ordinal)) + { + return 'volume-id' + } + if ($script:wrongResource -and $command.Contains($script:wrongResource, [StringComparison]::Ordinal)) + { + return 'another-project' + } + return $script:project + } + } + It 'accepts only consistently labeled containers, networks and volumes' { + { Assert-OwnedResource } | Should -Not -Throw + Should -Invoke docker -Times 6 -Exactly + } + It 'rejects a foreign container before any cleanup' { + $script:wrongResource = 'container-id' + { Assert-OwnedResource } | Should -Throw '*Container ownership mismatch*' + Should -Invoke docker -ParameterFilter { ($args -join ' ') -match 'down|remove|prune' } -Times 0 + } + It 'rejects a foreign network before any cleanup' { + $script:wrongResource = 'network-id' + { Assert-OwnedResource } | Should -Throw '*Network ownership mismatch*' + Should -Invoke docker -ParameterFilter { ($args -join ' ') -match 'down|remove|prune' } -Times 0 + } + It 'rejects a foreign volume before any cleanup' { + $script:wrongResource = 'volume-id' + { Assert-OwnedResource } | Should -Throw '*Volume ownership mismatch*' + Should -Invoke docker -ParameterFilter { ($args -join ' ') -match 'down|remove|prune' } -Times 0 + } + It 'refuses an existing unowned state directory before contacting Docker' { + { & $entrypoint -Action Stop -StateDirectory $TestDrive } | Should -Throw '*lacks this tool ownership record*' + Should -Invoke docker -Times 0 + } + It 'rejects persistent experimental startup before any state creation' { + $path = Join-Path $TestDrive 'experimental-start' + { & $entrypoint -Action Start -ExperimentalNativeAuth -StateDirectory $path } | Should -Throw '*Test-only profile*' + Test-Path -LiteralPath $path | Should -BeFalse + Should -Invoke docker -Times 0 + } + It 'does not repurpose a saved standard environment for experimental authentication' { + $path = Join-Path $TestDrive 'standard-environment' + [IO.Directory]::CreateDirectory($path) | Out-Null + @{sourceRoot = [IO.Path]::GetFullPath((Join-Path $PSScriptRoot '../..')); project = $project; authentik = $false } | + ConvertTo-Json | Set-Content (Join-Path $path 'owner.json') + { & $entrypoint -Action Test -ExperimentalNativeAuth -StateDirectory $path } | Should -Throw '*cannot be repurposed*' + Should -Invoke docker -Times 0 + } + It 'refuses a forged project name before contacting Docker' { + $path = Join-Path $TestDrive 'forged' + [IO.Directory]::CreateDirectory($path) | Out-Null + @{sourceRoot = [IO.Path]::GetFullPath((Join-Path $PSScriptRoot '../..')); project = 'unrelated'; authentik = $false } | ConvertTo-Json | Set-Content (Join-Path $path 'owner.json') + { & $entrypoint -Action Stop -StateDirectory $path } | Should -Throw '*State ownership mismatch*' + Should -Invoke docker -Times 0 + } + It 'restores a nondefault Authentik port from saved state' { + $script:envFile = Join-Path $TestDrive 'ports.env' + [IO.File]::WriteAllText($envFile, "QQQ_HTTP_PORT=19081`nAUTHENTIK_HTTP_PORT=19011`n") + Get-RecordedAuthentikPort | Should -Be 19011 + } + It 'rejects ambiguous saved port configuration' { + $script:envFile = Join-Path $TestDrive 'ambiguous.env' + [IO.File]::WriteAllText($envFile, "AUTHENTIK_HTTP_PORT=19010`nAUTHENTIK_HTTP_PORT=19011`n") + { Get-RecordedAuthentikPort } | Should -Throw '*missing or invalid*' + } + It 'rejects a state ancestor junction or symlink before writing or contacting Docker' { + $target = Join-Path $TestDrive 'target' + $link = Join-Path $TestDrive 'linked' + [IO.Directory]::CreateDirectory($target) | Out-Null + if ($IsWindows) + { + New-Item -ItemType Junction -Path $link -Target $target -ErrorAction Stop | Out-Null + } + else + { + New-Item -ItemType SymbolicLink -Path $link -Target $target -ErrorAction Stop | Out-Null + } + try + { + { & $entrypoint -Action Start -StateDirectory (Join-Path $link 'new-state') } | Should -Throw '*symbolic link or reparse point*' + Test-Path -LiteralPath (Join-Path $target 'new-state') | Should -BeFalse + Should -Invoke docker -Times 0 + } + finally + { + [IO.Directory]::Delete($link) + } + } +} diff --git a/dev/tests/NativeAuth.Tests.ps1 b/dev/tests/NativeAuth.Tests.ps1 new file mode 100644 index 0000000..1435ea6 --- /dev/null +++ b/dev/tests/NativeAuth.Tests.ps1 @@ -0,0 +1,71 @@ +#Requires -Version 7.4 +# Copyright 2026 Kingsrook, LLC +# SPDX-License-Identifier: Apache-2.0 + +# No Docker, TLS, provider or QQQ calls; only private input and result validation. +BeforeAll { + $script:nativeScript = Join-Path $PSScriptRoot '../Invoke-NativeAuth.ps1' + $script:project = 'qbit-printing-dev-0123456789abcdef0123456789abcdef' + $script:requiredChecks = @('untrusted-tls-refused', 'typed-native-grant', 'real-provider-login', 'wrong-origin-cookie-denied', 'permission-denied-user', 'logout-replay-denied', 'server-refresh-after-expiry', 'provider-revocation-denied') +} + +Describe 'Experimental native provider qualification state' { + BeforeEach { + $state = Join-Path $TestDrive ([Guid]::NewGuid().ToString('N')) + New-Item -ItemType Directory -Path $state | Out-Null + $envFile = Join-Path $state 'compose.env' + $prefix = "PRINTING_DEV_PROJECT=$project`nMINIO_ROOT_USER=synthetic`n" + [IO.File]::WriteAllText($envFile, $prefix) + @{ project = $project; clientId = $project; bootstrapToken = 'synthetic-admin'; clientSecret = 'synthetic-client'; userPassword = 'synthetic-user' } | + ConvertTo-Json | Set-Content -LiteralPath (Join-Path $state 'auth-secrets.json') + $script:report = @{ + status = 'PASS'; scope = 'DEVELOPMENT_ONLY_UNRELEASED'; project = $project + coreSource = 'ecf0f550a0357cec6387c2b54efca128a405a629' + clientSource = '346fc285198908c47a2ee9db7b9adb53d5e88c3c'; checks = $requiredChecks + } + $script:resultFile = Join-Path $state 'native-auth-result.json' + } + + It 'preserves common state and creates only the exact owned destinations without console secrets' { + $output = @(& $nativeScript -Action Initialize -StateDirectory $state -ProjectName $project) + $output.Count | Should -Be 0 + (Get-Content -LiteralPath $envFile -Raw).StartsWith($prefix, [StringComparison]::Ordinal) | Should -BeTrue + $inputData = Get-Content -LiteralPath (Join-Path $state 'native-input.json') -Raw | ConvertFrom-Json + $inputData.qqqOrigin | Should -Be 'https://qqq.printing.internal' + $inputData.callback | Should -Be 'https://callback.printing.internal/oauth/callback' + $inputData.project | Should -Be $project + (Get-Content -LiteralPath $script:resultFile -Raw | ConvertFrom-Json).status | Should -Be 'NOT_RUN' + $before = (Get-FileHash -LiteralPath $envFile).Hash + { & $nativeScript -Action Initialize -StateDirectory $state -ProjectName $project } | Should -Throw '*fresh owned environment*' + (Get-FileHash -LiteralPath $envFile).Hash | Should -Be $before + } + + It 'refuses credentials owned by another project before writing native input' { + { & $nativeScript -Action Initialize -StateDirectory $state -ProjectName 'qbit-printing-dev-aaaaaaaa' } | Should -Throw '*does not match*' + Test-Path -LiteralPath (Join-Path $state 'native-input.json') | Should -BeFalse + } + + It 'accepts the exact source and complete bounded report' { + $script:report | ConvertTo-Json | Set-Content -LiteralPath $script:resultFile + & $nativeScript -Action VerifyResult -StateDirectory $state -ProjectName $project | Should -Match 'candidate is unpublished' + } + + It 'rejects a passing report from a different source' { + $script:report.coreSource = '0000000000000000000000000000000000000000' + $script:report | ConvertTo-Json | Set-Content -LiteralPath $script:resultFile + { & $nativeScript -Action VerifyResult -StateDirectory $state -ProjectName $project } | Should -Throw '*exact source*' + } + + It 'rejects missing renewal evidence instead of treating successful login as complete' { + $script:report.checks = @($requiredChecks | Where-Object { $_ -ne 'server-refresh-after-expiry' }) + $script:report | ConvertTo-Json | Set-Content -LiteralPath $script:resultFile + { & $nativeScript -Action VerifyResult -StateDirectory $state -ProjectName $project } | Should -Throw '*required checks*' + } + + It 'rejects malformed or oversized reports without echoing their contents' { + [IO.File]::WriteAllText($script:resultFile, '{"private":"do-not-echo"') + { & $nativeScript -Action VerifyResult -StateDirectory $state -ProjectName $project } | Should -Throw '*contents are withheld*' + [IO.File]::WriteAllText($script:resultFile, ('x' * 65537)) + { & $nativeScript -Action VerifyResult -StateDirectory $state -ProjectName $project } | Should -Throw '*bounded size*' + } +} diff --git a/dev/tests/ProviderDiagnostics.Tests.ps1 b/dev/tests/ProviderDiagnostics.Tests.ps1 new file mode 100644 index 0000000..5928b92 --- /dev/null +++ b/dev/tests/ProviderDiagnostics.Tests.ps1 @@ -0,0 +1,51 @@ +#Requires -Version 7.4 +# Copyright 2026 Kingsrook, LLC +# SPDX-License-Identifier: Apache-2.0 + +BeforeAll { + $path = Join-Path $PSScriptRoot '../Invoke-Dev.ps1' + $tokens = $null + $errors = $null + $ast = [Management.Automation.Language.Parser]::ParseFile($path, [ref]$tokens, [ref]$errors) + if ($errors.Count) { throw 'Entrypoint parsing failed.' } + $function = $ast.Find({ param($node) $node -is [Management.Automation.Language.FunctionDefinitionAst] -and $node.Name -eq 'ConvertTo-ProviderErrorSummary' }, $true) + . ([scriptblock]::Create($function.Extent.Text)) +} + +Describe 'Private provider diagnostic redaction' { + It 'retains source coordinates but excludes exception values, locals and request data' { + $record = @{event = 'secret-request'; exception = @(@{exc_type = 'KeyError'; exc_value = 'secret-value'; frames = @( + @{filename = '/authentik/flows/views/executor.py'; lineno = 42; name = 'post'; locals = @{password = 'secret-password'}; source = 'secret-source'}, + @{filename = '/outside/secret-path.py'; lineno = 3; name = 'unsafe'} + ) + }) + } | ConvertTo-Json -Depth 8 -Compress + $result = ConvertTo-ProviderErrorSummary @($record, 'secret-unstructured-line') + $result.exceptionTypes | Should -Be @('KeyError') + $result.frames.Count | Should -Be 1 + $result.frames[0].function | Should -Be 'post' + $result | ConvertTo-Json -Depth 6 | Should -Not -Match 'secret|password|outside|locals|source' + } + It 'bounds frames and does not retain malformed or query-bearing coordinates' { + $frames = @(1..20 | ForEach-Object { @{filename = '/authentik/test.py'; lineno = $_; name = 'get'} }) + $record = @{exception = @(@{exc_type = 'ValueError'; frames = $frames})} | ConvertTo-Json -Depth 8 -Compress + (ConvertTo-ProviderErrorSummary @($record)).frames.Count | Should -Be 12 + $bad = @{exception = @(@{exc_type = 'secret?Error'; frames = @(@{filename = '/authentik/test.py?secret'; lineno = 1; name = 'get'})})} | ConvertTo-Json -Depth 8 -Compress + $result = ConvertTo-ProviderErrorSummary @($bad, '{broken', 'null') + $result.exceptionTypes.Count | Should -Be 0 + $result.frames.Count | Should -Be 0 + } + It 'records only fixed known warning flags from unstructured output' { + $result = ConvertTo-ProviderErrorSummary @('Invalid client identifier secret-query', 'Non-applicable authentication flow secret', 'failed to resolve application secret') + $result.warnings.invalidClientIdentifier | Should -BeTrue + $result.warnings.nonApplicableAuthenticationFlow | Should -BeTrue + $result.warnings.failedToResolveApplication | Should -BeTrue + $result | ConvertTo-Json -Depth 6 | Should -Not -Match 'secret' + } + It 'retains fixed DRF exception names without their messages' { + $record = @{exception = @(@{exc_type = 'PermissionDenied'; exc_value = 'secret-csrf-value'; frames = @()})} | ConvertTo-Json -Depth 5 -Compress + $result = ConvertTo-ProviderErrorSummary @($record) + $result.exceptionTypes | Should -Be @('PermissionDenied') + $result | ConvertTo-Json -Depth 6 | Should -Not -Match 'secret' + } +} diff --git a/dev/tests/WorkloadFailure.Tests.ps1 b/dev/tests/WorkloadFailure.Tests.ps1 new file mode 100644 index 0000000..bbb8256 --- /dev/null +++ b/dev/tests/WorkloadFailure.Tests.ps1 @@ -0,0 +1,63 @@ +#Requires -Version 7.4 +# Copyright 2026 Kingsrook, LLC +# SPDX-License-Identifier: Apache-2.0 + +BeforeAll { + $script:entrypoint = Join-Path $PSScriptRoot '../Invoke-Dev.ps1' + function docker { throw 'Unmocked Docker call refused.' } +} + +Describe 'Early workload client failure' { + BeforeEach { + $script:state = Join-Path $TestDrive ([Guid]::NewGuid().ToString('N')) + @{success = $false; stage = 'native_login_and_channels'; error = 'QqqSessionException'; reason = 'secret-value https://private.invalid/?token=secret'; completed = 0} | ConvertTo-Json | Set-Content (Join-Path $TestDrive 'client-fixture.json') + Mock docker { + $global:LASTEXITCODE = 0 + if ($args[0] -eq 'compose') + { + if ($args -contains 'ps') + { + if ($args[-1] -eq 'test-client') { return ('c' * 64) } + if ($args[-1] -eq 'test-server') { return ('b' * 64) } + } + return + } + if ($args[0] -eq 'inspect') + { + if ($args[1] -eq ('c' * 64)) { return 'false|17' } + throw 'SERVER_WAIT_REACHED' + } + if ($args[0] -eq 'cp') + { + $fixtureRoot = [IO.Directory]::GetParent([IO.Directory]::GetParent([IO.Directory]::GetParent($args[-1]).FullName).FullName).FullName + Copy-Item -LiteralPath (Join-Path $fixtureRoot 'client-fixture.json') -Destination $args[-1] + return + } + if ($args[0] -in @('ps', 'network', 'volume')) { return } + throw 'Unexpected fake Docker operation.' + } + } + It 'surfaces the client failure before server waiting and still cleans owned containers' { + { & $entrypoint -Action Test -StateDirectory $script:state } | Should -Throw '*Workload client failed at native_login_and_channels (QqqSessionException)*' + Should -Invoke docker -ParameterFilter { $args[0] -eq 'inspect' -and $args[1] -eq ('b' * 64) } -Times 0 + Should -Invoke docker -ParameterFilter { $args[0] -eq 'compose' -and $args -contains 'rm' -and $args -contains '--stop' } -Times 1 -Exactly + $result = Get-ChildItem -LiteralPath $script:state -Filter result.json -Recurse + (Get-Content -LiteralPath $result.FullName -Raw | ConvertFrom-Json).reason | Should -Be 'secret-value https://private.invalid/?token=secret' + } + It 'does not print unrecognized stage or exception text' { + @{success = $false; stage = 'secret-stage https://private.invalid/'; error = 'secret-error'} | ConvertTo-Json | Set-Content (Join-Path $TestDrive 'client-fixture.json') + { & $entrypoint -Action Test -StateDirectory $script:state } | Should -Throw '*Workload client failed at unknown (UnknownFailure)*' + Should -Invoke docker -ParameterFilter { $args[0] -eq 'inspect' -and $args[1] -eq ('b' * 64) } -Times 0 + } + It 'fails safely for diagnostics and still cleans owned containers' -TestCases @( + @{Kind = 'malformed'; Content = '{secret-malformed-json'}, + @{Kind = 'null'; Content = 'null'}, + @{Kind = 'oversized'; Content = (@{success = $false; stage = 'input'; error = 'JsonException'; reason = ('s' * 65536)} | ConvertTo-Json -Compress)} + ) { + param($Content) + $Content | Set-Content (Join-Path $TestDrive 'client-fixture.json') + { & $entrypoint -Action Test -StateDirectory $script:state } | Should -Throw '*Workload client failed at unknown (UnknownFailure)*' + Should -Invoke docker -ParameterFilter { $args[0] -eq 'inspect' -and $args[1] -eq ('b' * 64) } -Times 0 + Should -Invoke docker -ParameterFilter { $args[0] -eq 'compose' -and $args -contains 'rm' -and $args -contains '--stop' } -Times 1 -Exactly + } +} diff --git a/docs/AUDIT-2026-10-30.md b/docs/AUDIT-2026-10-30.md new file mode 100644 index 0000000..6c5793a --- /dev/null +++ b/docs/AUDIT-2026-10-30.md @@ -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. diff --git a/docs/CI-COMPATIBILITY.md b/docs/CI-COMPATIBILITY.md new file mode 100644 index 0000000..5d94912 --- /dev/null +++ b/docs/CI-COMPATIBILITY.md @@ -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). + diff --git a/docs/H2-LICENSE-REVIEW.md b/docs/H2-LICENSE-REVIEW.md new file mode 100644 index 0000000..1d1453f --- /dev/null +++ b/docs/H2-LICENSE-REVIEW.md @@ -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. diff --git a/docs/LOCAL-HOST.md b/docs/LOCAL-HOST.md new file mode 100644 index 0000000..16fdfc1 --- /dev/null +++ b/docs/LOCAL-HOST.md @@ -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. diff --git a/docs/OPERATIONS.md b/docs/OPERATIONS.md index 6d028c6..02d2f15 100644 --- a/docs/OPERATIONS.md +++ b/docs/OPERATIONS.md @@ -24,7 +24,145 @@ 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 block new allocations until exact cleanup resolves them; a fixed-size guess cannot safely account for configurable document limits. 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 stops dispatch and inventory publication while +the authenticated control WebSocket remains available for a reconnect command. +Neither operation cancels an already submitted spooler job. Resume preserves +connection state; reconnect preserves pause. Revocation invalidates device proof, +closes its channel and requires separate local re-enrollment. It cannot be undone +with resume/reconnect. Desired state, observed revision and last contact 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 @@ -32,7 +170,7 @@ Documents are stored as base64 in the database. Set a host-specific retention an | --- | --- | | Enrollment rejected | Code expiration/single use, correct server, administrator-created facility/device enrollment | | No printers in QQQ | Service access to Windows queues; local exposure selection; connector enrollment and inventory publication | -| Printer listed but submission rejected | Both `available` and `enabled`, format capability and 20 MiB decoded-size limit | +| Printer listed but submission rejected | Both `available` and `enabled`, format capability and configured PDF/ZPL decoded-size limits | | Job stays queued | Connector connectivity, selected queue availability and device assignment | | Job stays received/submitting after restart | Inspect local journal/spooler; automatic uncertain-output replay is intentionally absent | | Printing app missing or access denied | QBit registration, `printing_admin`, matching `printing_tenant`, and correct QQQ backend | @@ -42,4 +180,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. diff --git a/docs/QUALIFICATION-2026-11-01.md b/docs/QUALIFICATION-2026-11-01.md new file mode 100644 index 0000000..4e3c7d8 --- /dev/null +++ b/docs/QUALIFICATION-2026-11-01.md @@ -0,0 +1,104 @@ +# Server qualification — 2026-11-01 + +The published server **0.3.0-rc.1** and published Windows **0.3.1-rc.1** Core runtime +completed the following isolated qualification. No live server, installed service, +real document, physical printer or external cloud bucket was changed. + +## Network workload + +These measurements describe the earlier released-artifact fixture runs. The +portable [Docker developer tooling](../dev/README.md) records its own per-run +measurements and includes separate default smoke and opt-in burst commands. + +The existing Java/.NET interoperability fixture was extended with synthetic work. +It used the actual QQQ table-authenticated host, native session/device binding, +WebSocket channel, released Core `PrintWorker`, HTTPS-client code over explicitly +allowed loopback HTTP, file downloads, and WebSocket receipt acknowledgements. +Only the physical printer and local fixture journal were substitutes. The server +persisted real SQL jobs and receipts. Admission limits remained enabled. + +| Check | Observed result | +| --- | --- | +| Burst workload | 10,000 jobs; two tenants; eight devices | +| Documents | 1,021-byte synthetic ZPL; exact downloaded bytes checked | +| Completion | 10,000 SPOOLED rows; 30,000 durable event rows; no pending work | +| Replay | 400 submit and 400 receipt replays; no duplicates | +| Isolation | Foreign device binding and tenant job access refused | +| Accounting | Retained bytes exact; no orphan upload rows | +| Duration | 96.12 seconds including setup; about 104 jobs/second | +| Maximum backlog | 7,798 committed jobs; final backlog zero | +| Working set | Server peak 680 MiB; client peak approximately 85 MiB | +| Cold persistence | 10,000 rows present; read-only check left DB unchanged | + +Burst enqueue-to-terminal-ACK latency was p50 43.30 seconds, p95 62.84 seconds, +p99 64.66 seconds. These values include intentional queue backlog; they are not +idle notification latency. + +A separate **40-job one-at-a-time** run measured: + +| Interval | Median | 95th percentile | +| --- | ---: | ---: | +| Received notification to claim completion | 8.72 ms | 27.18 ms | +| Received notification to verified download completion | 29.74 ms | 49.07 ms | +| Enqueue to durable terminal receipt acknowledgement | 49.65 ms | 76.56 ms | + +The fixture does not periodically poll for jobs. A received notification wakes a +finite claim/drain operation. Liveness PING messages do not query jobs. These are +HTTP/WS loopback results, **not HTTPS/WSS, remote network, physical print-speed, +large-document sustained throughput, or long-duration soak qualification**. +The fixture journal is not the installed Windows SQLite journal; its recovery +behavior is covered separately by the Windows tests. + +## Existing storage path, current release + +The existing S3 qualification harness was rerun against this exact published +server and its unchanged 204-JAR runtime. All **65 checks / six document round +trips** passed through native QQQ `StorageAction`, `S3StorageAction`, and AWS SDK +against one disposable local MinIO container. The run includes actual multipart +upload above 5 MiB, exact length/hash/MIME, tenant namespaces, immutable-reference +validation, stable replay, completion-age retention, and protection of active, +failed, uncertain, fresh, foreign and unrelated objects. The owned container and +its ephemeral data were removed after identity verification. + +This is S3-compatible data-plane evidence. It does not qualify AWS IAM, remote +TLS, bucket policies, versioning/Object Lock, or a configured production storage +target. The existing platform-specific key-layout binding guard remains required; +no shared QQQ library or cross-OS migration behavior was changed. + +## Repeatable service regression + +`PrintingWorkloadTest` is an opt-in file-backed regression, separate from the +network fixture. It runs 10,000 real service lifecycles through four pooled SQL +connections, tests replay and tenant pagination, verifies exact event/byte counts, +and closes every connection before reopening without schema initialization. + +```powershell +./mvnw.cmd -Pui-demo -Dprinting.qualification.load=true verify +``` + +The protocol fixtures must be present at the usual sibling checkout; alternatively +set `-Dprinting.protocol.fixtures=/path/to/reviewed/fixtures`. +The full gate passed **119 tests, zero skips and zero Checkstyle violations**. +A subsequent exact event-count assertion improvement passed its focused workload +rerun. Default builds skip this explicit workload test; ordinary regression tests +remain unchanged. The separate development workflow runs cross-platform script +checks and the real 40-job/S3 Docker smoke on pull requests and main pushes; its +experimental native-auth run is manual. Hosted results must be checked on the +submitted commit. No application implementation or dependency changed. + +## Scope boundaries + +The user's current development/test target is local Docker. AWS/account/IAM or +remote deployment provisioning is not a prerequisite for this change. + +The separate [experimental native-auth profile](../dev/native-auth/README.md) +passed real Authentik login, denied-user/wrong-Origin checks, logout, short token +renewal and provider revocation using container-private HTTPS and the pinned +unreleased QQQ API 1.9 candidate. It does not upgrade this regression's released +RC.20 dependency or qualify the installed Windows browser callback. The workload +and S3 measurements above remain HTTP/WS and MinIO evidence, respectively. + +Long-duration soak, mid-session account/role changes and sustained physical +throughput remain separate from these bounded tests and previously confirmed +individual physical prints. No application implementation, dependency or +published package version changes in this test/developer-tooling change. diff --git a/docs/REALTIME.md b/docs/REALTIME.md new file mode 100644 index 0000000..ef4cbdb --- /dev/null +++ b/docs/REALTIME.md @@ -0,0 +1,109 @@ +# Real-time printing host integration + +Release candidate [0.3.0-rc.1](https://github.com/QRun-IO/qbit-printing/releases/tag/v0.3.0-rc.1) +implements printing extension **2.0.0** (wire envelope v1). Upgrade the server +before the matching Windows connector; a real-time connector rejects a server that advertises only extension +1.x. There is no timed job/control polling fallback. + +## Connection and authorization + +The Windows service initiates `wss:///qqq/v1/qbit/printing/device/realtime` +using subprotocol `qqq-printing.v1`. No facility listener or inbound firewall rule +is required. Plain WebSocket is allowed only for explicit loopback development. +Configure the cloud ingress to forward WebSocket upgrades, preserve the original +HTTPS origin and allow the configured heartbeat interval/timeout. + +The service discovers authentication through the QQQ UI/UX API and uses the +standard current QQQ session, client channel and approved bound-device proof. +Credentials are not URL parameters. Device proof does not replace the user's +authority. The server validates the current session, user/tenant, channel policy +and operation permissions; socket establishment does not grant permanent rights. +Session expiry, logout, revocation and permission denial require correction or +sign-in through the configured QQQ provider. Reconnect cannot bypass them. + +Register the route provider alongside the ordinary native QQQ endpoints: + +```java +server.withAdditionalRouteProviders(List.of(existingHttpRoutes, + new PrintingRealtimeRoutes(printingService))); +``` + +Use the **same PrintingService instance** in the QBit configuration and route +provider. `PrintingLocalHost.configure` shows the complete launcher integration. +The native HTTP claim route requires a connected socket that has applied the +current desired state and settings. Registering just the older HTTP provider is +insufficient. Close the provider when its host stops. + +## Independent control and document lanes + +The socket carries small JSON state, commands, inventory, heartbeats, job events +and durable receipts. A job notification triggers a finite HTTP claim drain; +an empty queue waits for another push. No timer repeatedly fetches claims or +commands. Heartbeats, session renewal and reconnect backoff are lifecycle work, +not job polling. + +Documents use separate outbound same-origin HTTPS transfers. The Windows service +streams them to protected staging files and checks declared length and SHA-256 +before native submission. The socket reader remains active during a slow download. +PDF rendering and ZPL spooling receive the verified file rather than a base64 +payload in the control pipe. Limits bound staging, messages and concurrency. + +Receipts remain on disk until the server acknowledges their committed IDs. A +reconnect resynchronizes current state/settings and replays retained receipts. +An interrupted native submission remains uncertain and is never automatically +reprinted. A successful spooler submission does not prove paper physically printed. + +## Native administrator settings + +Printing home links to two standard QQQ processes. They enforce current +administrator and tenant access on the backend as well as in metadata: + +- **Printing connection and limits**: PDF/ZPL size, copies, staging space, + concurrent downloads/prints, bandwidth, request/download timeouts, heartbeat, + reconnect backoff/jitter, acknowledgment timeout and control message queues. + Defaults are 100 MiB PDF, 20 MiB ZPL and one download/print lane. Saved policy + changes have a durable revision and are pushed to connected devices. +- **Printing queue and storage limits**: device/tenant outstanding counts and + bytes, retained bytes, hourly allocations and printer counts. New admissions + use the persisted policy inside their SQL transaction. Reducing limits preserves + existing jobs and history; it does not silently remove documents. + +Fields use readable MiB/GiB/seconds with exact conversion, required values and +cross-field validation. Unsupported client ceilings fail explicitly rather than +silently clamping. Storage retention remains in the separate native retention +process, with a one-year default. + +HTTP ingress/body limits remain host-owned. The local host derives its upload +body ceiling at startup from the persisted document limits (including base64 +expansion for legacy submission). Raising a document limit above the running +transport ceiling requires a host restart or corresponding production ingress +configuration. Download streaming does not base64-expand documents. + +## Host ownership and deployment boundary + +Commit wakeups are emitted after SQL commit. A subscription exists before initial +state reconstruction, closing the empty-claim/reconnect notification race. +`PrintingRealtimeBus` is an explicit host-owned notification and connection +ownership seam. The default implementation is in-process; this source does **not** +provide a distributed broker or claim tested multi-node production support. + +Use one writer/application host with its configured service/bus. Multiple route +providers sharing that explicit in-process bus fence a device's prior connection. +A multi-node deployment needs a host-provided shared implementation preserving +both post-commit notifications and single-channel ownership, and its own +qualification. Separate independent service instances do not magically publish +notifications to one another. + +The existing `/printing/v1` routes remain explicit legacy diagnostic compatibility. +They are not a real-time fallback and cannot authorize a native bound device. +The full message and settings contract is in +[the shared protocol](https://github.com/QRun-IO/qqq-print-protocol). + +## Printing API major upgrade + +The extension is **2.0.0** because native HTTP claims now require a synchronized +WebSocket. A published 1.0 HTTP-only connector no longer meets that precondition; +this is a breaking behavior change even though request bodies remain wire v1. +The QQQ framework API `/qqq/v1`, extension path `/qbit/printing` and WebSocket +subprotocol `qqq-printing.v1` remain unchanged. Upgrade server and client together; +an older client must report upgrade-required instead of using polling fallback. diff --git a/docs/SESSION-STATE.md b/docs/SESSION-STATE.md index b5bc7ef..5f6a5af 100644 --- a/docs/SESSION-STATE.md +++ b/docs/SESSION-STATE.md @@ -1,6 +1,137 @@ -# 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. +## Local Docker development — 2026-11-01 + +The optional native-auth probe now shares production Core discovery and the +default workload's printing-major-2 gate, accepting stable 2.1.0 while retaining +the exact experimental API 1.9/native grant requirement. Its previous exact-2.0.0 +check reproduced a rejection before the fix. Native and default client image +builds pass 12 and nine fake-HTTP compatibility checks respectively, with zero +warnings/errors. One fresh provider run against server source `3592dec` +(printing API 2.1.0) and the reviewed probe correction passed all eight checks. +All source hashes remained unchanged through completion; independent cleanup +found zero owned containers, volumes and networks. No installed runtime, +physical printer or host trust setting changed. + +The developer tooling is published on `main` through [PR #21](https://github.com/QRun-IO/qbit-printing/pull/21), +merged as `3592decba8087439aff5d1b75a9726c72f460cb9`; its tree matches tested +head `def8d961f3d82a1235f8e45ffbeacb0fbe79c421`. The final hosted +[development run](https://github.com/QRun-IO/qbit-printing/actions/runs/41324370247) +passed the actual 40-job HTTP/WS smoke and 65 S3 checks, nine pinned-Core discovery +compatibility cases, and all 33 script tests on each of Windows and Ubuntu. +The [Java run](https://github.com/QRun-IO/qbit-printing/actions/runs/41324370253) +reported 133 tests: 132 executed, one intentionally skipped opt-in workload test, +zero failures/errors, and zero Checkstyle violations. That workload separately +passed on the combined source. These are development-tooling publication results, +not a server release or live runtime upgrade. The experimental API 1.9 candidate +remains opt-in and is not adopted into the released application dependencies. + +The current qualification scope is local Docker only. The new `dev/Invoke-Dev.ps1` +provides owned Start/Test/Stop commands for a native QQQ TABLE host, dedicated +MinIO storage and optional real Authentik/PostgreSQL. Source images and the client +Core archive are pinned. Generated credentials stay in private state outside the +checkout; no installed connector, live database or physical printer is used. + +Portable Docker checks passed: the default 40-job smoke, 65 actual QQQ S3 backend +checks, and an opt-in 10,000-job/two-tenant/eight-client run with 30,000 durable +server receipts and 400 submission plus 400 receipt replays. The burst completed +in 147.856 seconds (about 67.63 jobs/second); its enqueue-to-ACK p95 was 32.984 +seconds while work intentionally queued. This is HTTP/WS with a fake file printer +and a simple fixture client journal, not TLS, hardware or a long soak claim. + +Native TABLE login, identity, frontend asset and logout passed. Real Authentik +configuration/discovery passed; a registered redirect continued to login and the +otherwise-identical unregistered redirect was rejected. The released RC.20 host +still advertises API 1.8 without the native session grant: browser login, renewal +and the Windows callback are not established by these checks. All owned test +containers, volumes and networks were removed. Lifecycle/bootstrap regressions +passed 28 cases including experimental-profile refusal and diagnostic-redaction +checks; scripts passed parser and PSScriptAnalyzer checks. + +The separate opt-in native-auth profile passed eight actual checks against the +immutable upstream API 1.9 candidate `ecf0f550a0357cec6387c2b54efca128a405a629`: +ordinary TLS refusal before container-only CA installation, typed-grant discovery, +real Authentik login through the production Core PKCE client, wrong-Origin cookie +rejection, denied-user permissions, logout replay refusal, server-side renewal +after access-token expiry and denial after provider refresh-token revocation. +The final run exited zero and all owned containers, volumes and networks were +removed. Earlier failed fixture attempts remain in private evidence; their fixes +were standard-flow readiness/binding, bounded provider redirects and the correct +Authentik CSRF header. No authentication check was disabled. + +This experimental candidate is not the default released RC.20 runtime or a +published production dependency upgrade. Container HTTPS and automated real +provider flows do not qualify the Windows browser callback UI, host trust, +months-long operation or physical printing. See [local development](../dev/README.md), +[provider limits](../dev/AUTHENTIK.md) and [native qualification](../dev/native-auth/README.md). +Earlier release checkpoints below are historical. This developer-tooling merge +did not publish a new server product release or change the live paired runtime. + +## Opt-in service workload regression — 2026-11-01 + +The combined test/development change also includes a 10,000-job, two-tenant, +eight-lane file-backed service regression with replay, exact accounting, +pagination and cold reopen checks. It is opt-in and never accesses a printer. +The original isolated full gate passed 119 tests with zero Checkstyle violations; +the final exact receipt-count assertion passed its focused rerun. Its source is +unchanged when integrated here, and the combined checkout passed one focused +workload test with zero Checkstyle violations. The earlier released-artifact +network run and +40-job idle latency measurements are recorded in +[qualification evidence](QUALIFICATION-2026-11-01.md), separately from the portable +Docker run above. No runtime source, dependencies or version changed. + +## Active device controls and standard QQQ authentication + +Implementation is in the isolated device-controls worktree. Native device/table actions support 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 final isolated 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 23 native table-based authentication/binding/control/logout checks without printers or jobs. Current protected CI and installed/provider acceptance remain pending. No new feature release or local installation has occurred. + +The user confirmed all three current Query test prints good. Barcode catalog expansion was removed from 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 +141,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. @@ -32,3 +163,21 @@ Final QBit UI pass: metadata uses printing_* table/data-source names, printing-p Durable target correction: core DurableJobsRuntime.effectLoop constructs a system session without user tenant keys. PrintEnqueueEffectTarget now has a private trusted resolver for that system-only outbox path, bound to the current instance PrintingQBitConfig service and its fixed tenant. Inline users retain scope checks; native process authorization is unchanged. Registered-target tests cover system deliver/reconcile, idempotent replay, foreign-tenant device rejection, cached target reuse across instances, and inline wrong/missing-tenant denial. `mvnw.cmd -o verify -Pui-demo dependency:build-classpath` passed all 16 tests and zero Checkstyle violations after the durable target correction, explicit disabled table writes, final dashboard timestamps, and frontend RC.37 profile update. UI runtime classpath regenerated at target/ui-runtime-classpath.txt. Primary identifiers remain non-hidden because QQQ excludes hidden fields from ordinary query results; explicit frontend column hints keep them out of the default operational grid. + +## Real-time transport implementation resumed — 2026-10-31 + +User resumed implementation after explicitly rejecting periodic job/control polling. Active isolated worktrees: qbit-printing-wt-realtime, qqq-print-protocol-wt-realtime, qqq-print-agent-wt-job-table (all branch feat/realtime-printing-20261031). Installed 0.2.0-rc.1 remains unchanged and is still polling; do not claim it is real-time. + +Protocol extension 1.1.0: client-initiated authenticated WSS, qqq-printing.v1 subprotocol, current QQQ session and secondary bound-device proof. Small state/commands/events/receipts travel directly over WebSocket; separate HTTPS documents stream to protected files. No timed polling fallback. Commit notifications and finite event-triggered claims, bounded concurrency, persistent receipts and reconnect reconciliation are being implemented. Tenant administrator forms expose document, transfer, connection, queue/rate/printer/storage limits. Default PDF limit100MiB, ZPL20MiB; both configurable. Root owns native forms/admission settings, server agent owns route/storage/service, Windows agent owns transport/pipeline, inventory agent completed protocol70definitions/72fixtures and now owns Jobs UI expansion/sorting. No live install or new physical print yet. New-source gates/integration are in progress; previous0.2 gates do not qualify these changes. + +## Real-time source verification — 2026-10-31 + +Server source0.3.0-rc.1 passes117 Java tests and zero Checkstyle violations, including real native-session WebSocket lifecycle, sessionId/sessionUUID, logout/channel rejection, replacement fencing, partial revision acknowledgments, no idle-inventory feedback, and21MiB native storage streaming/integrity. Protocol70definitions/72fixtures passes; both consumer workflows pin signed protocol67be986cb76d6b5d9a9f72cad054193b0d11b0d5. Native admin policy tests cover permission/tenant checks, exact250.5MiB conversion, revision persistence and invalid-capacity rejection. A private actual.NET/Java fixture passed13 functional checks with25MiB content, durable receipt replay, channel replacement and sign-out denial; its initial fixture JVM needed explicit maintenance-thread shutdown handling, so this is not installed lifecycle qualification. Root is preparing the final refreshed fixture run. Current installed0.2 remains unchanged; release/install acceptance is pending. + +## Final real-time API gate — 2026-10-31 + +Native printing extension is now2.0.0, because requiring a synchronized WebSocket for previously HTTP-only native claims is a breaking behavior change. Framework/qqq/v1, wirev1 and qqq-printing.v1 remain unchanged; product0.3.0-rc.1. Full final-source verify passed118tests, zero failures/errors/skips and zero Checkstyle violations. Configured heartbeat timeout now determines dashboard freshness (90s legacy floor) and authorized PING records control-only contact. Published1.0 OpenAPI baseline remains preserved. Protocol repin and final Windows verification are pending; no live deployment. + +## Coordinated protocol and cross-runtime verification — 2026-10-31 + +Current immutable consumer pin is df3729ac632d4a34a3fb8423acef465042a624fc (71definitions/73fixtures); it supersedes earlier67be986 pre-major-correction checkpoints. Final API2.0 Java/Release.NET interoperability passed13 checks with25MiB content and exact durable replay, temporary host stopped and wrapper exit0. Installed0.2 remains unchanged. Windows source gate398tests passed before one final startup recovery regression was added; its definitive gate is still pending. No release/install acceptance claim. diff --git a/docs/SOURCE-HEADERS.md b/docs/SOURCE-HEADERS.md new file mode 100644 index 0000000..bde6a98 --- /dev/null +++ b/docs/SOURCE-HEADERS.md @@ -0,0 +1,17 @@ +# Owned source notice check + +Run these commands from the repository root with the existing Python 3 interpreter: + +```text +python3 .github/scripts/test-source-headers.py +python3 .github/scripts/check-source-headers.py +``` + +The standard-library checker enforces the scope of the reviewed 2026-11-01 header pass, not an estate-wide licensing or formatting audit. `.github/source-headers.json` names the owned source/config path families, comment syntax, accepted holder/license pairs and explicit exclusion reasons. Python `fnmatch` patterns match slash-containing relative Git paths; new files in those families are covered after they are tracked. Empty selections fail. The checker does not scan untracked build output or modify files. + +Only leading language comments count. Copyright text in a string, Python docstring or comment after code is rejected. UTF-8 BOMs, initial shebangs, PowerShell `#Requires` directives and XML declarations are handled before the notice. These declarations cannot be displaced beneath a new notice. PowerShell block comments are recognized only for PowerShell files. Existing years and holders are not rewritten. Complete canonical Apache notices are valid without redundant SPDX; Java still requires the full Apache block. A contradictory SPDX identifier fails. + +JSON/schema/fixture/lock data, explicit generated output directories, vendor legal assets and upstream Maven wrappers are excluded with reasons in the policy. Solution/activation/test-runner metadata and `.editorconfig` remain outside this completed pass; their applicable root LICENSE/NOTICE remains authoritative. No broad claim about third-party licensing follows from this check. New owned file types or provenance must be reviewed before changing the allowlist; do not add blanket exclusions to make a failure disappear. + +The implementation and its negative tests are intentionally maintained copies across the three printing repositories, with each repository's own copyright/license header and independently reviewed scope. They do not fetch policy or execute source. CI invokes them in existing jobs using the runner's available Python, with no new package or workflow context. Existing native C# IDE0073 and Java Checkstyle conventions remain unchanged. +This repository accepts Kingsrook, LLC / Apache-2.0 for its reviewed source/build/config families. The existing CI verify job runs the guard. diff --git a/docs/STORAGE-AND-RETENTION.md b/docs/STORAGE-AND-RETENTION.md new file mode 100644 index 0000000..e4de0b5 --- /dev/null +++ b/docs/STORAGE-AND-RETENTION.md @@ -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//.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. diff --git a/docs/TODO.md b/docs/TODO.md index a907e92..958bdf9 100644 --- a/docs/TODO.md +++ b/docs/TODO.md @@ -1,35 +1,118 @@ # Follow-up +## Current local development qualification + +- [x] Reuse production discovery and the shared major-2 gate in the optional + native-auth probe; reproduce the old 2.1.0 rejection, then pass 12 native and + nine default workload fake-HTTP compatibility checks without provider launch. +- [x] Rerun the eight-check native provider profile once against printing API 2.1.0 + after review; all eight passed with unchanged source hashes and owned cleanup. +- [x] Supply portable, owned Docker Start/Test/Stop commands with private synthetic + credentials and explicit cleanup; leave the installed pairing untouched. +- [x] Run the 40-job smoke, 65 real S3 backend checks and 10,000 network jobs with + 30,000 durable server receipts and replay/isolation assertions. +- [x] Qualify real Authentik provider discovery and registered/unregistered redirect + controls while reporting the released QQQ 1.8 native-grant absence honestly. +- [x] Qualify the separate experimental API 1.9/container-TLS native login, + denied-user/wrong-Origin permissions, logout, short renewal and provider revocation. +- [x] Include the opt-in 10,000-job pooled-SQL/cold-reopen service regression and + preserve separate released-artifact network/idle-latency evidence. +- [x] Publish developer tooling through PR #21, merged as + `3592decba8087439aff5d1b75a9726c72f460cb9`: hosted 40-job/65-S3 checks, + 33 script tests on both Windows and Ubuntu, and the ordinary Java gate + (133 reported, 132 executed, one opt-in skip, zero failures/Checkstyle violations). + Keep experimental API 1.9 artifacts opt-in; this merge does not adopt them into + the released application or upgrade the live paired runtime. + +The older release checklists below are historical context. AWS/cloud-account +provisioning is outside the user's current local-Docker-only request. + +- [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. +- [ ] Complete installed candidate acceptance after protected CI. +- [ ] Complete standard QQQ discovery/session/device-binding security checks and Windows auth integration; qualify the shared Authentik native grant without a private authentication fork. +- [x] Review and merge immutable protocol inputs (cc3c4e5), pass protected CI and merge the server and Windows implementations normally. Release tagging and installed acceptance remain separate. + +- [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 long-duration soak and sustained physical throughput separately + from the completed bounded network/fake-printer workloads; see + [qualification evidence](QUALIFICATION-2026-11-01.md). - [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. + +## Real-time upgrade (active) + +- [ ] Complete authenticated outbound WebSocket transport and automatic durable recovery; remove production job/control polling fallback. +- [ ] Verify concurrent control while large streamed documents download, bounds/cleanup, real concurrency and exact event replay. +- [ ] Verify native administrator limits forms, live policy delivery, admission overrides and configurable document sizes. +- [ ] Complete consistent sortable/expandable Windows Jobs and Printers tables. +- [ ] Run coordinated server/client/protocol gates and cross-runtime native integration before packaging/installing. diff --git a/pom.xml b/pom.xml index 0db2395..5843294 100644 --- a/pom.xml +++ b/pom.xml @@ -1,10 +1,15 @@ + + 4.0.0 com.kingsrookqbit-build-parent2.0.0 com.kingsrook.qbits qbit-printing - 0.1.2-rc.1 + 0.4.0-SNAPSHOT QQQ Printing Apache License, Version 2.0https://www.apache.org/licenses/LICENSE-2.0 @@ -22,14 +27,26 @@ com.kingsrook.qqqqqq-backend-core${qqq.version} com.kingsrook.qqqqqq-backend-module-rdbms${qqq.version} + com.kingsrook.qqqqqq-backend-module-filesystem${qqq.version} com.kingsrook.qqqqqq-middleware-javalin${qqq.version} - com.h2databaseh22.3.232runtime + + com.h2databaseh22.4.240runtime org.junit.jupiterjunit-jupiter6.0.1test ui-demo com.kingsrook.qqqqqq-frontend-next1.0.0-RC.37runtime - + + + src/main/resources + + ${project.basedir} + META-INF + LICENSENOTICE + false + + + org.apache.maven.pluginsmaven-checkstyle-plugin3.3.1 com.puppycrawl.toolscheckstyle10.12.6 checkstyle/config.xmltruetruewarningtrue @@ -37,6 +54,7 @@ org.apache.maven.pluginsmaven-compiler-plugin3.14.1 org.apache.maven.pluginsmaven-surefire-plugin3.5.4 + org.apache.maven.pluginsmaven-jar-plugin3.4.2${project.version} org.codehaus.mojoexec-maven-plugin3.6.4com.kingsrook.qbits.printing.PrintingDemo diff --git a/src/main/java/com/kingsrook/qbits/printing/PrintingAdmission.java b/src/main/java/com/kingsrook/qbits/printing/PrintingAdmission.java new file mode 100644 index 0000000..b1bb55d --- /dev/null +++ b/src/main/java/com/kingsrook/qbits/printing/PrintingAdmission.java @@ -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.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_document_orphan WHERE tenant_id=? AND content_length IS NULL", tenant) != 0) + { + throw new PrintingException(429, "An old upload has an unknown document size; complete exact orphan cleanup before admitting new documents"); + } + 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=?", 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 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()); + } + } +} diff --git a/src/main/java/com/kingsrook/qbits/printing/PrintingAdmissionLimits.java b/src/main/java/com/kingsrook/qbits/printing/PrintingAdmissionLimits.java new file mode 100644 index 0000000..2ed6395 --- /dev/null +++ b/src/main/java/com/kingsrook/qbits/printing/PrintingAdmissionLimits.java @@ -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)); + } +} diff --git a/src/main/java/com/kingsrook/qbits/printing/PrintingAdmissionSettings.java b/src/main/java/com/kingsrook/qbits/printing/PrintingAdmissionSettings.java new file mode 100644 index 0000000..254ce07 --- /dev/null +++ b/src/main/java/com/kingsrook/qbits/printing/PrintingAdmissionSettings.java @@ -0,0 +1,178 @@ +/* + * 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.math.BigDecimal; +import java.sql.Connection; +import java.sql.SQLException; +import java.util.List; +import java.util.Objects; +import org.json.JSONObject; + + +/******************************************************************************* + ** Tenant admission overrides are read in the same transaction as admission. + *******************************************************************************/ +public class PrintingAdmissionSettings +{ + private static final List FIELDS = List.of("deviceOutstandingJobs", "tenantOutstandingJobs", "deviceOutstandingBytes", "tenantOutstandingBytes", + "deviceRetainedBytes", "tenantRetainedBytes", "deviceJobsPerHour", "tenantJobsPerHour", "devicePrinters", "tenantPrinters"); + private static final long MAX_EXACT_JSON_INTEGER = 9_007_199_254_740_991L; + private final DataSource source; + private final String tenant; + private final PrintingAdmissionLimits defaults; + + + + /*************************************************************************** + ** The host supplies immutable defaults until an administrator saves an override. + ***************************************************************************/ + public PrintingAdmissionSettings(DataSource source, String tenant, PrintingAdmissionLimits defaults) + { + this.source = Objects.requireNonNull(source); + this.tenant = Objects.requireNonNull(tenant); + this.defaults = Objects.requireNonNull(defaults); + } + + + + /*************************************************************************** + ** The enclosing service ensures the tenant settings row before public reads. + ***************************************************************************/ + public JSONObject get() throws SQLException + { + try(Connection connection = source.getConnection()) + { + return (json(effective(connection))); + } + } + + + + /*************************************************************************** + ** Validate all limits before one atomic tenant-scoped update. + ***************************************************************************/ + public JSONObject save(JSONObject requested) throws SQLException + { + PrintingAdmissionLimits limits = parse(requested); + JSONObject value = json(limits); + try(Connection connection = source.getConnection(); var update = connection.prepareStatement("UPDATE printing_settings SET admission_policy_json=? WHERE tenant_id=?")) + { + update.setString(1, value.toString()); + update.setString(2, tenant); + if(update.executeUpdate() != 1) + { + throw new SQLException("The tenant admission settings row is unavailable"); + } + } + return (value); + } + + + + /*************************************************************************** + ** Do not open a nested connection while a queue transaction holds its locks. + ***************************************************************************/ + public PrintingAdmissionLimits effective(Connection connection) throws SQLException + { + try(var query = connection.prepareStatement("SELECT admission_policy_json FROM printing_settings WHERE tenant_id=?")) + { + query.setString(1, tenant); + try(var rows = query.executeQuery()) + { + if(!rows.next()) + { + return (defaults); + } + String stored = rows.getString(1); + return (stored == null ? defaults : parse(new JSONObject(stored))); + } + } + } + + + + /*************************************************************************** + ** Every configured limit is explicit, positive and exactly representable. + ***************************************************************************/ + private static PrintingAdmissionLimits parse(JSONObject value) + { + if(!value.keySet().equals(java.util.Set.copyOf(FIELDS))) + { + throw new IllegalArgumentException("Specify all admission limits without unknown fields"); + } + try + { + return (new PrintingAdmissionLimits(integer(value, "deviceOutstandingJobs"), integer(value, "tenantOutstandingJobs"), + number(value, "deviceOutstandingBytes"), number(value, "tenantOutstandingBytes"), number(value, "deviceRetainedBytes"), number(value, "tenantRetainedBytes"), + integer(value, "deviceJobsPerHour"), integer(value, "tenantJobsPerHour"), integer(value, "devicePrinters"), integer(value, "tenantPrinters"))); + } + catch(ArithmeticException exception) + { + throw new IllegalArgumentException("Admission counts must fit the supported integer range", exception); + } + } + + + + /*************************************************************************** + ** Counts follow the database's integer representation without truncation. + ***************************************************************************/ + private static int integer(JSONObject value, String field) + { + return (Math.toIntExact(number(value, field))); + } + + + + /*************************************************************************** + ** Reject quoted numbers, fractions, overflow and disabled capacity boundaries. + ***************************************************************************/ + private static long number(JSONObject value, String field) + { + if(!(value.opt(field) instanceof Number number)) + { + throw new IllegalArgumentException(field + " must be a positive integer"); + } + long parsed = new BigDecimal(number.toString()).longValueExact(); + if(parsed < 1 || parsed > MAX_EXACT_JSON_INTEGER) + { + throw new IllegalArgumentException(field + " is outside the supported positive range"); + } + return (parsed); + } + + + + /*************************************************************************** + ** Native forms and host defaults share one stable field vocabulary. + ***************************************************************************/ + private static JSONObject json(PrintingAdmissionLimits value) + { + return (new JSONObject().put("deviceOutstandingJobs", value.deviceOutstandingJobs()).put("tenantOutstandingJobs", value.tenantOutstandingJobs()) + .put("deviceOutstandingBytes", value.deviceOutstandingBytes()).put("tenantOutstandingBytes", value.tenantOutstandingBytes()) + .put("deviceRetainedBytes", value.deviceRetainedBytes()).put("tenantRetainedBytes", value.tenantRetainedBytes()) + .put("deviceJobsPerHour", value.deviceJobsPerHour()).put("tenantJobsPerHour", value.tenantJobsPerHour()) + .put("devicePrinters", value.devicePrinters()).put("tenantPrinters", value.tenantPrinters())); + } +} diff --git a/src/main/java/com/kingsrook/qbits/printing/PrintingAgentAuthorization.java b/src/main/java/com/kingsrook/qbits/printing/PrintingAgentAuthorization.java new file mode 100644 index 0000000..93005e4 --- /dev/null +++ b/src/main/java/com/kingsrook/qbits/printing/PrintingAgentAuthorization.java @@ -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 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 inventory(String device) throws Exception + { + Set 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 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)); + } +} diff --git a/src/main/java/com/kingsrook/qbits/printing/PrintingApiSchemas.java b/src/main/java/com/kingsrook/qbits/printing/PrintingApiSchemas.java new file mode 100644 index 0000000..e84015b --- /dev/null +++ b/src/main/java/com/kingsrook/qbits/printing/PrintingApiSchemas.java @@ -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 components() + { + Map 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 properties, List 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 required; + + /** Retain the explicit protocol field requirements. */ + public RequiredSchema(List required) + { + this.required = required; + } + + /** Published by the core Jackson schema serializer. */ + public List getRequired() + { + return (required); + } + } + + + /** Build typed object fields without map arity limits. */ + private static Map fields(Object... pairs) + { + Map 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 target, String name, Map 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)); + } +} diff --git a/src/main/java/com/kingsrook/qbits/printing/PrintingCommandStatus.java b/src/main/java/com/kingsrook/qbits/printing/PrintingCommandStatus.java new file mode 100644 index 0000000..b853cc7 --- /dev/null +++ b/src/main/java/com/kingsrook/qbits/printing/PrintingCommandStatus.java @@ -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 DEPENDENCIES = Set.of("id", "status", "expires_at"); + private static final Set TERMINAL = Set.of("SUCCEEDED", "FAILED", "EXPIRED", "OUTCOME_UNKNOWN"); + + + + /*************************************************************************** + ** Enrich only the requested virtual field, preserving the caller's projection. + ***************************************************************************/ + @Override + public List postQuery(QueryOrGetInputInterface input, List records) throws QException + { + Set 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 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 dependencies(List records) throws QException + { + ArrayList ids = new ArrayList<>(); + for(QRecord record : records) + { + if(!record.getValues().keySet().containsAll(DEPENDENCIES) && record.getValueString("id") != null) + { + ids.add(record.getValueString("id")); + } + } + Map result = new HashMap<>(); + for(int first = 0; first < ids.size(); first += 200) + { + List 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"); + } + } +} diff --git a/src/main/java/com/kingsrook/qbits/printing/PrintingControlAuthorization.java b/src/main/java/com/kingsrook/qbits/printing/PrintingControlAuthorization.java new file mode 100644 index 0000000..2398a5e --- /dev/null +++ b/src/main/java/com/kingsrook/qbits/printing/PrintingControlAuthorization.java @@ -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 queue = null; + if("CLEAR_QUEUE".equals(selected.wire)) + { + queue = service.queuedJobIdsForControl(deviceId); + Set 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)); + } +} diff --git a/src/main/java/com/kingsrook/qbits/printing/PrintingDemo.java b/src/main/java/com/kingsrook/qbits/printing/PrintingDemo.java index 35fbc31..0940132 100644 --- a/src/main/java/com/kingsrook/qbits/printing/PrintingDemo.java +++ b/src/main/java/com/kingsrook/qbits/printing/PrintingDemo.java @@ -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; diff --git a/src/main/java/com/kingsrook/qbits/printing/PrintingDeviceControls.java b/src/main/java/com/kingsrook/qbits/printing/PrintingDeviceControls.java new file mode 100644 index 0000000..beb3cf2 --- /dev/null +++ b/src/main/java/com/kingsrook/qbits/printing/PrintingDeviceControls.java @@ -0,0 +1,542 @@ +/* + * 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 ACTIONS = Set.of("PAUSE_DISPATCH", "RESUME_DISPATCH", "DISCONNECT", "RECONNECT", "REVOKE", "REFRESH_INVENTORY", "CLEAR_QUEUE", "CANCEL_SPOOL"); + private static final Set 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 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 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= 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 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 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"); + } + applied = Math.max(applied, device.getLong("control_applied_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 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 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 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 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 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 allowed) + { + if(!allowed.containsAll(object.keySet())) + { + throw new PrintingException(400, "Unknown control field"); + } + } +} diff --git a/src/main/java/com/kingsrook/qbits/printing/PrintingDeviceProcesses.java b/src/main/java/com/kingsrook/qbits/printing/PrintingDeviceProcesses.java new file mode 100644 index 0000000..89a75dd --- /dev/null +++ b/src/main/java/com/kingsrook/qbits/printing/PrintingDeviceProcesses.java @@ -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 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 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 getProcessSummary(RunBackendStepOutput output, boolean isForResultScreen) + { + return (new ArrayList<>(List.of(applied, pending, unresolved))); + } + } +} diff --git a/src/main/java/com/kingsrook/qbits/printing/PrintingDeviceStatus.java b/src/main/java/com/kingsrook/qbits/printing/PrintingDeviceStatus.java new file mode 100644 index 0000000..f732e03 --- /dev/null +++ b/src/main/java/com/kingsrook/qbits/printing/PrintingDeviceStatus.java @@ -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 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 postQuery(QueryOrGetInputInterface input, List records) throws QException + { + Set 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 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 dependencies(List records) throws QException + { + ArrayList ids = new ArrayList<>(); + for(QRecord record : records) + { + if(!record.getValues().keySet().containsAll(DEPENDENCIES) && record.getValueString("id") != null) + { + ids.add(record.getValueString("id")); + } + } + Map result = new HashMap<>(); + for(int first = 0; first < ids.size(); first += 200) + { + List 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); + } + } +} diff --git a/src/main/java/com/kingsrook/qbits/printing/PrintingDocumentStorage.java b/src/main/java/com/kingsrook/qbits/printing/PrintingDocumentStorage.java new file mode 100644 index 0000000..7445564 --- /dev/null +++ b/src/main/java/com/kingsrook/qbits/printing/PrintingDocumentStorage.java @@ -0,0 +1,307 @@ +/* + * 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 (get(table, reference, Math.toIntExact(PrintingRealtimePolicy.defaults().get("maxPdfBytes")))); + } + + + /** Internal retry callers supply the exact persisted length, independent of the current format policy. */ + public byte[] get(String table, String reference, int maximum) throws SQLException + { + return (execute(() -> + { + try(InputStream stream = new StorageAction().getInputStream(input(table, reference))) + { + byte[] bytes = stream.readNBytes(maximum); + if(stream.read() != -1) + { + throw new PrintingException(502, "Stored print document exceeds its declared length"); + } + return bytes; + } + })); + } + + + /** Return the native backend stream; the request owns closing it and enforcing its declared length. */ + public InputStream open(String table, String reference) throws SQLException + { + return (execute(() -> new StorageAction().getInputStream(input(table, reference)))); + } + + + + /*************************************************************************** + ** 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 execute(Callable 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); + } + } +} + diff --git a/src/main/java/com/kingsrook/qbits/printing/PrintingDocumentStream.java b/src/main/java/com/kingsrook/qbits/printing/PrintingDocumentStream.java new file mode 100644 index 0000000..91e6d06 --- /dev/null +++ b/src/main/java/com/kingsrook/qbits/printing/PrintingDocumentStream.java @@ -0,0 +1,90 @@ +/* + * 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.FilterInputStream; +import java.io.IOException; +import java.io.InputStream; +import java.security.MessageDigest; +import java.security.NoSuchAlgorithmException; +import java.util.HexFormat; + + +/** Length and digest verification remains bounded while transferring a retained object. */ +final class PrintingDocumentStream extends FilterInputStream +{ + private final long length; + private final String expectedHash; + private final MessageDigest digest; + private long received; + private boolean verified; + + + /** Wrap a source with immutable document integrity metadata. */ + PrintingDocumentStream(InputStream input, long length, String expectedHash) + { + super(input); + this.length = length; + this.expectedHash = expectedHash; + try + { + digest = MessageDigest.getInstance("SHA-256"); + } + catch(NoSuchAlgorithmException exception) + { + throw new IllegalStateException(exception); + } + } + + + @Override + public int read() throws IOException + { + byte[] one = new byte[1]; + return (read(one, 0, 1) == -1 ? -1 : Byte.toUnsignedInt(one[0])); + } + + + @Override + public int read(byte[] bytes, int offset, int count) throws IOException + { + int read = in.read(bytes, offset, (int) Math.min(count, Math.max(1, length - received + 1))); + if(read > 0) + { + received += read; + if(received > length) + { + throw new IOException("Stored print document exceeds its declared length"); + } + digest.update(bytes, offset, read); + } + else if(read == -1 && !verified) + { + verified = true; + if(received != length || !HexFormat.of().formatHex(digest.digest()).equals(expectedHash)) + { + throw new IOException("Stored print document integrity check failed"); + } + } + return (read); + } +} \ No newline at end of file diff --git a/src/main/java/com/kingsrook/qbits/printing/PrintingExtract.java b/src/main/java/com/kingsrook/qbits/printing/PrintingExtract.java new file mode 100644 index 0000000..59e792b --- /dev/null +++ b/src/main/java/com/kingsrook/qbits/printing/PrintingExtract.java @@ -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)); + } +} diff --git a/src/main/java/com/kingsrook/qbits/printing/PrintingFacilities.java b/src/main/java/com/kingsrook/qbits/printing/PrintingFacilities.java new file mode 100644 index 0000000..59f64ec --- /dev/null +++ b/src/main/java/com/kingsrook/qbits/printing/PrintingFacilities.java @@ -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); + } +} diff --git a/src/main/java/com/kingsrook/qbits/printing/PrintingHome.java b/src/main/java/com/kingsrook/qbits/printing/PrintingHome.java index 1dc7f3d..d3f8a1c 100644 --- a/src/main/java/com/kingsrook/qbits/printing/PrintingHome.java +++ b/src/main/java/com/kingsrook/qbits/printing/PrintingHome.java @@ -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); } @@ -127,11 +128,13 @@ public class PrintingHome extends AbstractWidgetRenderer QWidgetData data = switch(input.getWidgetMetaData().getName()) { case "printingHomeHeader" -> header(); - case "printingHomeAttention" -> attention(now); - case "printingHomeOffline" -> statistic(DEVICE, offline(now), "Devices · now · target 0 without heartbeat for 90 seconds"); + case "printingHomeAttention" -> attention(now, freshnessSeconds()); + case "printingHomeOffline" -> offlineStatistic(now); 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,10 @@ 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("Printing connection and limits").withLink(new BlockLink("/app/printingRealtimeSettings/?returnTo=%2Fapp%2Fprinting%2F"))) + .withBlock(text("Printing queue and storage limits").withLink(new BlockLink("/app/printingAdmissionSettings/?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) { @@ -162,16 +169,30 @@ public class PrintingHome extends AbstractWidgetRenderer /*************************************************************************** ** Severity order: failed work, disconnected devices, then printer issues. ***************************************************************************/ - private static TableData attention(Instant now) throws QException + private static TableData attention(Instant now, long freshnessSeconds) throws QException { List> 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))) + for(QRecord device : query(DEVICE, offline(now, freshnessSeconds).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 " + freshnessSeconds + " 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 +244,9 @@ public class PrintingHome extends AbstractWidgetRenderer ***************************************************************************/ private static List 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 +256,61 @@ 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. + ** Current tenant policy controls freshness, retaining the legacy grace period. ***************************************************************************/ - private static QQueryFilter offline(Instant now) + private static long freshnessSeconds() throws QException { - return (new QQueryFilter().withCriteria("enabled", QCriteriaOperator.EQUALS, 1).withCriteria("last_seen_at", QCriteriaOperator.LESS_THAN, now.minusSeconds(90).toString())); + try + { + return (Math.max(90, PrintingProcesses.currentService().realtimePolicy().get("heartbeatTimeoutSeconds"))); + } + catch(java.sql.SQLException exception) + { + throw new QException("Could not read printing connection freshness settings", exception); + } + } + + + + /*************************************************************************** + ** Explain the exact threshold used by the linked native filter. + ***************************************************************************/ + private static StatisticsData offlineStatistic(Instant now) throws QException + { + long seconds = freshnessSeconds(); + return (statistic(DEVICE, offline(now, seconds), "Enabled devices · now · disconnected by an administrator or unseen for " + seconds + " seconds")); + } + + + + /*************************************************************************** + ** Either authenticated connection proves liveness; requested disconnect stays visible. + ***************************************************************************/ + private static QQueryFilter offline(Instant now, long freshnessSeconds) + { + QQueryFilter unseen = new QQueryFilter().withSubFilter(stale("last_seen_at", now, freshnessSeconds)).withSubFilter(stale("control_last_poll_at", now, freshnessSeconds)); + 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, long freshnessSeconds) + { + return (new QQueryFilter().withBooleanOperator(QQueryFilter.BooleanOperator.OR) + .withCriteria(field, QCriteriaOperator.IS_BLANK).withCriteria(field, QCriteriaOperator.LESS_THAN, now.minusSeconds(freshnessSeconds).toString())); } diff --git a/src/main/java/com/kingsrook/qbits/printing/PrintingJobProcesses.java b/src/main/java/com/kingsrook/qbits/printing/PrintingJobProcesses.java index 8a77e30..27da2fa 100644 --- a/src/main/java/com/kingsrook/qbits/printing/PrintingJobProcesses.java +++ b/src/main/java/com/kingsrook/qbits/printing/PrintingJobProcesses.java @@ -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"); } diff --git a/src/main/java/com/kingsrook/qbits/printing/PrintingLayout.java b/src/main/java/com/kingsrook/qbits/printing/PrintingLayout.java new file mode 100644 index 0000000..fd5723a --- /dev/null +++ b/src/main/java/com/kingsrook/qbits/printing/PrintingLayout.java @@ -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.ByteArrayOutputStream; +import java.io.IOException; +import java.io.InputStream; +import java.util.ArrayList; +import java.util.List; +import java.util.Locale; +import com.kingsrook.qqq.backend.core.exceptions.QException; +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; + + +/******************************************************************************* + ** A small monospace page writer shared by the record, table-list and text + ** documents: a heading on the first page, a running title on later pages, + ** lines that break onto new pages (optionally repeating a header), and + ** "Page n of m" footers. Characters the bundled font cannot encode print as ?. + *******************************************************************************/ +final class PrintingLayout implements AutoCloseable +{ + static final float MARGIN = 40; + static final int MAX_PAGES = 500; + + private final PDDocument document = new PDDocument(); + private final PDType0Font font; + private final PDRectangle size; + private final String title; + private PDPageContentStream content; + private float y; + private List repeatHeader = List.of(); + private int repeatSize = 8; + private String footer = ""; + private float leading = 1.35f; + + + + /*************************************************************************** + ** Page size LETTER or A4, portrait or landscape; the first page carries + ** the title and subtitle. + ***************************************************************************/ + PrintingLayout(String pageSize, boolean landscape, String title, String subtitle) throws QException + { + try(InputStream stream = PrintingLayout.class.getResourceAsStream(PrintingTestDocuments.FONT_RESOURCE)) + { + if(stream == null) + { + throw new IOException("Bundled document font is missing"); + } + font = PDType0Font.load(document, stream, true); + PDRectangle base = "A4".equals(pageSize == null ? null : pageSize.toUpperCase(Locale.ROOT)) ? PDRectangle.A4 : PDRectangle.LETTER; + size = landscape ? new PDRectangle(base.getHeight(), base.getWidth()) : base; + this.title = title == null ? "" : title; + newPage(); + line(this.title, 15); + y -= 4; + if(subtitle != null && !subtitle.isBlank()) + { + line(subtitle, 9); + } + y -= 4; + rule(); + y -= 6; + } + catch(IOException exception) + { + close(); + throw new QException("Could not start the print document", exception); + } + } + + + + /*************************************************************************** + ** How many monospace characters fit across the page at a font size. + ***************************************************************************/ + int columns(float fontSize) + { + return (Math.max(20, (int) ((size.getWidth() - 2 * MARGIN) / (0.6f * fontSize)))); + } + + + + /*************************************************************************** + ** Line spacing as a multiple of the font size (1.35 by default; text + ** captures use less so box-drawing characters join up). + ***************************************************************************/ + void leading(float factor) + { + leading = factor; + } + + + + /*************************************************************************** + ** Text at the bottom left of every page (who printed it and when). + ***************************************************************************/ + void footer(String text) + { + footer = text == null ? "" : text; + } + + + + /*************************************************************************** + ** Lines repeated at the top of every following page (a table header). + ***************************************************************************/ + void repeatOnNewPages(List lines, int fontSize) + { + repeatHeader = List.copyOf(lines); + repeatSize = fontSize; + } + + + + /*************************************************************************** + ** One line at a font size; breaks the page first when it does not fit. + ***************************************************************************/ + void line(String text, float fontSize) throws IOException + { + float step = fontSize * leading; + if(y - step < MARGIN + 14) + { + newPage(); + for(String header : repeatHeader) + { + draw(header, repeatSize, repeatSize * leading); + } + } + draw(text, fontSize, step); + } + + + + /*************************************************************************** + ** Keep at least this many lines together (a heading with its first rows). + ***************************************************************************/ + void keep(int lines, int fontSize) throws IOException + { + if(y - lines * fontSize * 1.35f < MARGIN + 14) + { + newPage(); + } + } + + + + /*************************************************************************** + ** Vertical space. + ***************************************************************************/ + void gap(float points) + { + y -= points; + } + + + + /*************************************************************************** + ** A thin rule across the page. + ***************************************************************************/ + void rule() throws IOException + { + content.moveTo(MARGIN, y); + content.lineTo(size.getWidth() - MARGIN, y); + content.stroke(); + y -= 4; + } + + + + /*************************************************************************** + ** Footers on every page, then the PDF bytes. + ***************************************************************************/ + byte[] finish() throws QException + { + try + { + content.close(); + content = null; + int total = document.getNumberOfPages(); + for(int i = 0; i < total; i++) + { + PDPage page = document.getPage(i); + try(PDPageContentStream footer = new PDPageContentStream(document, page, PDPageContentStream.AppendMode.APPEND, true, true)) + { + String text = "Page " + (i + 1) + " of " + total; + footer.beginText(); + footer.setFont(font, 8); + footer.newLineAtOffset(size.getWidth() - MARGIN - text.length() * 4.8f, MARGIN - 14); + footer.showText(text); + footer.endText(); + if(!this.footer.isEmpty()) + { + footer.beginText(); + footer.setFont(font, 8); + footer.newLineAtOffset(MARGIN, MARGIN - 14); + footer.showText(safe(PrintingRecordDocuments.truncate(this.footer, Math.max(10, columns(8) - text.length() - 2)))); + footer.endText(); + } + } + } + ByteArrayOutputStream output = new ByteArrayOutputStream(); + document.save(output); + return (output.toByteArray()); + } + catch(IOException exception) + { + throw new QException("Could not render the print document", exception); + } + } + + + + /*************************************************************************** + ** Release the document. + ***************************************************************************/ + @Override + public void close() + { + try + { + if(content != null) + { + content.close(); + } + document.close(); + } + catch(IOException exception) + { + // nothing more to release + } + } + + + + /*************************************************************************** + ** Start a page; later pages show the running title. + ***************************************************************************/ + private void newPage() throws IOException + { + if(document.getNumberOfPages() >= MAX_PAGES) + { + throw new IOException("The document would exceed " + MAX_PAGES + " pages; print fewer rows"); + } + if(content != null) + { + content.close(); + } + PDPage page = new PDPage(size); + document.addPage(page); + content = new PDPageContentStream(document, page); + y = size.getHeight() - MARGIN; + if(document.getNumberOfPages() > 1) + { + draw(PrintingRecordDocuments.truncate(title, columns(8)) + " (continued)", 8, 12); + y -= 4; + } + } + + + + /*************************************************************************** + ** Draw one line at the current position. + ***************************************************************************/ + private void draw(String text, float fontSize, float step) throws IOException + { + y -= step; + content.beginText(); + content.setFont(font, fontSize); + content.newLineAtOffset(MARGIN, y); + content.showText(safe(PrintingRecordDocuments.truncate(text, columns(fontSize)))); + content.endText(); + } + + + + /*************************************************************************** + ** Replace characters the font cannot encode, and control characters. + ***************************************************************************/ + private String safe(String text) + { + StringBuilder out = new StringBuilder(); + text.codePoints().forEach(codePoint -> + { + String character = new String(Character.toChars(codePoint)); + if(Character.isISOControl(codePoint)) + { + out.append(' '); + return; + } + try + { + font.encode(character); + out.append(character); + } + catch(IllegalArgumentException | IOException exception) + { + out.append('?'); + } + }); + return (out.toString()); + } + + + + /*************************************************************************** + ** Width-limited columns for a table: natural widths shrunk to the line. + ***************************************************************************/ + static int[] columnWidths(List headers, List> rows, int available) + { + return (fit(naturalWidths(headers, rows), available)); + } + + + + /*************************************************************************** + ** Each column's natural width: the header or the 90th percentile of its + ** cells, between 4 and 60 characters. + ***************************************************************************/ + static int[] naturalWidths(List headers, List> rows) + { + int count = headers.size(); + int[] widths = new int[count]; + for(int c = 0; c < count; c++) + { + List lengths = new ArrayList<>(); + for(List row : rows) + { + lengths.add(c < row.size() && row.get(c) != null ? row.get(c).length() : 0); + } + lengths.sort(null); + int typical = lengths.isEmpty() ? 0 : lengths.get(Math.max(0, (int) Math.ceil(lengths.size() * 0.9) - 1)); + widths[c] = Math.max(4, Math.min(60, Math.max(headers.get(c).length(), typical))); + } + return (widths); + } + + + + /*************************************************************************** + ** The width a row of these columns takes, with two-space gaps. + ***************************************************************************/ + static int lineWidth(int[] widths) + { + return (sum(widths) + Math.max(0, widths.length - 1) * 2); + } + + + + /*************************************************************************** + ** Shrink widths (widest first, never below 4) until a row fits. + ***************************************************************************/ + static int[] fit(int[] start, int available) + { + int[] widths = start.clone(); + while(lineWidth(widths) > available) + { + int widest = 0; + for(int c = 1; c < widths.length; c++) + { + if(widths[c] > widths[widest]) + { + widest = c; + } + } + if(widths[widest] <= 4) + { + break; + } + widths[widest]--; + } + return (widths); + } + + + + /*************************************************************************** + ** Sum of widths. + ***************************************************************************/ + private static int sum(int[] values) + { + int total = 0; + for(int value : values) + { + total += value; + } + return (total); + } + + + + /*************************************************************************** + ** One table row laid out in fixed-width columns. + ***************************************************************************/ + static String row(List cells, int[] widths) + { + StringBuilder out = new StringBuilder(); + for(int c = 0; c < widths.length; c++) + { + String cell = c < cells.size() && cells.get(c) != null ? cells.get(c).replace('\n', ' ').replace('\r', ' ') : ""; + cell = PrintingRecordDocuments.truncate(cell, widths[c]); + out.append(c == 0 ? "" : " ").append(String.format("%-" + widths[c] + "s", cell)); + } + return (out.toString().stripTrailing()); + } +} diff --git a/src/main/java/com/kingsrook/qbits/printing/PrintingListProcesses.java b/src/main/java/com/kingsrook/qbits/printing/PrintingListProcesses.java new file mode 100644 index 0000000..82bd24e --- /dev/null +++ b/src/main/java/com/kingsrook/qbits/printing/PrintingListProcesses.java @@ -0,0 +1,425 @@ +/* + * 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.util.ArrayList; +import java.util.Arrays; +import java.util.List; +import java.util.Locale; +import java.util.UUID; +import com.kingsrook.qqq.backend.core.actions.permissions.PermissionEnforcement; +import com.kingsrook.qqq.backend.core.actions.processes.BackendStep; +import com.kingsrook.qqq.backend.core.actions.tables.CountAction; +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.count.CountInput; +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.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.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; +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.tables.QTableMetaData; +import com.kingsrook.qqq.backend.core.utils.JsonUtils; + + +/******************************************************************************* + ** Two print processes that are not bound to one table: + ** + ** - printingPrintTableList: a table list (grid) of any readable table. Values: + ** tableName, columns (comma separated, in order; default the visible + ** fields), filterJSON (a QQueryFilter with orderBys; its skip/limit are the + ** page), scope PAGE (the filter's skip/limit) or ALL (the whole result, + ** read a thousand rows at a time, up to maxRows: default and most 10,000; + ** a larger result prints its first rows and says so), columnWidths (the + ** grid's widths in characters, comma separated, same order), pageSize + ** LETTER/A4, orientation PORTRAIT/LANDSCAPE/AUTO (landscape when the + ** columns need it; the default), title, filterDescription (the filter as + ** the user sees it), then the printer and copies. + ** - printingPrintText: any text as a monospace PDF (a capture of a terminal + ** screen). Values: title, text, subtitle, pageSize, orientation, printer, + ** copies. + ** + ** Both ask for the printer on an options form (prefilled from the init + ** values), queue one PDF job and return its id in printingJobIds. Reading the + ** table enforces the user's table and record permissions. + *******************************************************************************/ +public final class PrintingListProcesses +{ + public static final String TABLE_LIST = "printingPrintTableList"; + public static final String TEXT = "printingPrintText"; + public static final int MAX_ROWS = 10_000; + public static final int DEFAULT_MAX_ROWS = MAX_ROWS; + static final int QUERY_PAGE = 1000; + static final String REQUEST_ID = "printingListRequestId"; + + + + /*************************************************************************** + ** Utility class. + ***************************************************************************/ + private PrintingListProcesses() + { + } + + + + /*************************************************************************** + ** Register both processes and their choice lists. + ***************************************************************************/ + public static void register(QInstance instance) + { + choices(instance, "printing_pageSize", List.of("LETTER", "A4"), List.of("Letter", "A4")); + choices(instance, "printing_orientation", List.of("AUTO", "PORTRAIT", "LANDSCAPE"), List.of("Automatic (landscape when the columns need it)", "Portrait", "Landscape")); + choices(instance, "printing_listScope", List.of("ALL", "PAGE"), List.of("All rows (current filter and sort)", "The current page")); + instance.addProcess(process(TABLE_LIST, "Print a table list", List.of( + new QFieldMetaData("tableName", QFieldType.STRING).withLabel("Table").withIsRequired(true), + new QFieldMetaData("scope", QFieldType.STRING).withLabel("Rows").withPossibleValueSourceName("printing_listScope").withDefaultValue("ALL"), + new QFieldMetaData("maxRows", QFieldType.INTEGER).withLabel("Most rows (all rows)").withDefaultValue(DEFAULT_MAX_ROWS), + new QFieldMetaData("orientation", QFieldType.STRING).withLabel("Orientation").withPossibleValueSourceName("printing_orientation").withDefaultValue("AUTO")))); + instance.addProcess(process(TEXT, "Print text", List.of( + new QFieldMetaData("title", QFieldType.STRING).withLabel("Title"), + new QFieldMetaData("orientation", QFieldType.STRING).withLabel("Orientation").withPossibleValueSourceName("printing_orientation").withDefaultValue("PORTRAIT")))); + } + + + + /*************************************************************************** + ** prepare, options (printer and layout), execute, result. + ***************************************************************************/ + private static QProcessMetaData process(String name, String label, List extra) + { + List fields = new ArrayList<>(extra); + fields.add(PrintingRecordProcesses.printerField()); + fields.add(new QFieldMetaData(PrintingRecordProcesses.COPIES_FIELD, QFieldType.INTEGER).withLabel("Copies").withIsRequired(true).withDefaultValue(1)); + fields.add(new QFieldMetaData("pageSize", QFieldType.STRING).withLabel("Paper").withPossibleValueSourceName("printing_pageSize").withDefaultValue("LETTER")); + return (new QProcessMetaData().withName(name).withLabel(label).withPermissionRules(PrintingProcesses.permissionRules()) + .withStep(new QBackendStepMetaData().withName("prepare").withCode(new QCodeReference(Prepare.class))) + .withStep(new QFrontendStepMetaData().withName("options").withLabel("Choose a printer").withFormFields(fields) + .withComponent(new QFrontendComponentMetaData().withType(QComponentType.EDIT_FORM))) + .withStep(new QBackendStepMetaData().withName("execute").withCode(new QCodeReference(Execute.class))) + .withStep(new QFrontendStepMetaData().withName("result").withLabel("Result") + .withViewFields(List.of(new QFieldMetaData("result", QFieldType.STRING).withLabel("Result"))) + .withComponent(new QFrontendComponentMetaData().withType(QComponentType.VIEW_FORM)))); + } + + + + /*************************************************************************** + ** A fixed enum choice list. + ***************************************************************************/ + private static void choices(QInstance instance, String name, List ids, List labels) + { + ArrayList> values = new ArrayList<>(); + for(int i = 0; i < ids.size(); i++) + { + values.add(new QPossibleValue<>(ids.get(i), labels.get(i))); + } + instance.addPossibleValueSource(new QPossibleValueSource().withName(name).withType(QPossibleValueSourceType.ENUM).withEnumValues(values)); + } + + + + /*************************************************************************** + ** The table a table list reads, checked readable. + ***************************************************************************/ + static QTableMetaData table(RunBackendStepInput input) throws QException + { + String name = input.getValueString("tableName"); + QTableMetaData table = name == null ? null : QContext.getQInstance().getTable(name); + if(table == null) + { + throw new QException("Choose a table to print (unknown table " + name + ")"); + } + PrintingTableSettings settings = PrintingTableSettings.of(table); + if(settings != null && !settings.getPrintable()) + { + throw new QException(table.getLabel() + " is not printable"); + } + return (table); + } + + + + /*************************************************************************** + ** The filter from filterJSON (or everything), with the page or the row limit. + ***************************************************************************/ + static QQueryFilter filter(RunBackendStepInput input) throws QException + { + String json = input.getValueString("filterJSON"); + QQueryFilter filter; + try + { + filter = json == null || json.isBlank() ? new QQueryFilter() : JsonUtils.toObject(json, QQueryFilter.class); + } + catch(Exception exception) + { + throw new QException("The filter is not valid: " + exception.getMessage(), exception); + } + if("ALL".equalsIgnoreCase(input.getValueString("scope"))) + { + Integer max = input.getValueInteger("maxRows"); + int limit = max == null ? DEFAULT_MAX_ROWS : max; + if(limit < 1 || limit > MAX_ROWS) + { + throw new QException("Most rows must be between 1 and " + MAX_ROWS); + } + filter.setSkip(0); + filter.setLimit(limit); + } + else + { + if(filter.getLimit() == null || filter.getLimit() > MAX_ROWS) + { + filter.setLimit(filter.getLimit() == null ? 50 : MAX_ROWS); + } + } + return (filter); + } + + + + /*************************************************************************** + ** The columns to print: given (unknown names refused), else visible fields. + ***************************************************************************/ + static List columns(QTableMetaData table, String given) throws QException + { + List out = new ArrayList<>(); + if(given == null || given.isBlank()) + { + table.getFields().values().stream().filter(PrintingRecordProcesses::printable).forEach(out::add); + return (out); + } + for(String name : Arrays.stream(given.split(",")).map(String::trim).filter(n -> !n.isEmpty()).toList()) + { + QFieldMetaData field = table.getFields().get(name); + if(field == null) + { + throw new QException("Table " + table.getName() + " has no field " + name); + } + if(PrintingRecordProcesses.printable(field)) + { + out.add(field); + } + } + if(out.isEmpty()) + { + throw new QException("None of the columns can be printed"); + } + return (out); + } + + + + /*************************************************************************** + ** The rows to print: the page as given, or the whole result read a page at + ** a time up to the filter's limit (the print limit). + ***************************************************************************/ + static List read(QTableMetaData table, QQueryFilter filter, boolean all) throws QException + { + List out = new ArrayList<>(); + int limit = filter.getLimit() == null ? 50 : filter.getLimit(); + int skip = filter.getSkip() == null ? 0 : filter.getSkip(); + while(out.size() < limit) + { + int size = all ? Math.min(QUERY_PAGE, limit - out.size()) : limit; + QueryInput query = new QueryInput(); + query.setTableName(table.getName()); + query.setFilter(filter.clone().withSkip(skip + out.size()).withLimit(size)); + query.setPermissionEnforcement(PermissionEnforcement.ENFORCE); + query.setShouldGenerateDisplayValues(true); + query.setShouldTranslatePossibleValues(true); + List page = new QueryAction().execute(query).getRecords(); + out.addAll(page); + if(!all || page.size() < size) + { + break; + } + } + return (out); + } + + + + /*************************************************************************** + ** The sort as labels: "Last name, First name descending". + ***************************************************************************/ + static String sortText(QTableMetaData table, QQueryFilter filter) + { + if(filter.getOrderBys() == null) + { + return (""); + } + List parts = new ArrayList<>(); + for(var orderBy : filter.getOrderBys()) + { + String name = orderBy.getFieldName(); + QFieldMetaData field = name == null ? null : table.getFields().get(name); + parts.add((field == null || field.getLabel() == null ? name : field.getLabel()) + (orderBy.getIsAscending() ? "" : " descending")); + } + return (String.join(", ", parts)); + } + + + + /*************************************************************************** + ** The grid's column widths ("12,30,8"), or null. + ***************************************************************************/ + static int[] widths(String text) + { + if(text == null || text.isBlank()) + { + return (null); + } + try + { + return (Arrays.stream(text.split(",")).map(String::trim).mapToInt(Integer::parseInt).toArray()); + } + catch(NumberFormatException exception) + { + return (null); + } + } + + + + /*************************************************************************** + ** AUTO unless PORTRAIT or LANDSCAPE was chosen. + ***************************************************************************/ + static String orientation(RunBackendStepInput input) + { + String value = input.getValueString("orientation"); + return (value == null || value.isBlank() ? "AUTO" : value.toUpperCase(Locale.ROOT)); + } + + + + /*************************************************************************** + ** Request identity, and for a table list the number of rows it would print. + ***************************************************************************/ + public static class Prepare implements BackendStep + { + /*************************************************************************** + ** Check access early so the form is not shown to someone who may not print. + ***************************************************************************/ + @Override + public void run(RunBackendStepInput input, RunBackendStepOutput output) throws QException + { + new PrintingAdminPermission().checkPermissionsThrowing(input, null); + PrintingProcesses.currentService(); + String request = input.getValueString(REQUEST_ID); + output.addValue(REQUEST_ID, request == null || request.isBlank() ? UUID.randomUUID().toString() : request); + if(TABLE_LIST.equals(input.getProcessName())) + { + QTableMetaData table = table(input); + CountInput count = new CountInput(); + count.setTableName(table.getName()); + count.setFilter(filter(input).clone().withSkip(null).withLimit(null)); + count.setPermissionEnforcement(PermissionEnforcement.ENFORCE); + output.addValue("printingRowCount", new CountAction().execute(count).getCount()); + if(input.getValueString("title") == null) + { + output.addValue("title", table.getLabel() == null ? table.getName() : table.getLabel()); + } + } + } + } + + + + /*************************************************************************** + ** Render and queue. + ***************************************************************************/ + public static class Execute implements BackendStep + { + /*************************************************************************** + ** One PDF job on the chosen printer. + ***************************************************************************/ + @Override + public void run(RunBackendStepInput input, RunBackendStepOutput output) throws QException + { + new PrintingAdminPermission().checkPermissionsThrowing(input, null); + QRecord printer = PrintingRecordProcesses.printer(input); + int copies = PrintingRecordProcesses.copies(input); + String request = input.getValueString(REQUEST_ID); + if(request == null || request.isBlank()) + { + throw new QException("Restart the print to obtain a safe request identity"); + } + String pageSize = input.getValueString("pageSize") == null ? "LETTER" : input.getValueString("pageSize").toUpperCase(Locale.ROOT); + String title; + byte[] bytes; + if(TABLE_LIST.equals(input.getProcessName())) + { + QTableMetaData table = table(input); + List columns = columns(table, input.getValueString("columns")); + QQueryFilter filter = filter(input); + boolean all = "ALL".equalsIgnoreCase(input.getValueString("scope")); + List records = read(table, filter, all); + List> rows = new ArrayList<>(); + for(QRecord record : records) + { + List row = new ArrayList<>(); + columns.forEach(field -> row.add(PrintingRecordProcesses.text(record, field))); + rows.add(row); + } + title = input.getValueString("title") != null ? input.getValueString("title") : table.getLabel(); + Integer total = input.getValueInteger("printingRowCount"); + int skip = filter.getSkip() == null ? 0 : filter.getSkip(); + String scope = all ? (total != null && total > records.size() ? "first " + records.size() + " of " + total + " rows (print limit " + filter.getLimit() + ")" : "all " + records.size() + " rows") + : "rows " + (records.isEmpty() ? 0 : skip + 1) + "-" + (skip + records.size()) + (total != null ? " of " + total : ""); + String described = input.getValueString("filterDescription"); + String sort = sortText(table, filter); + String subtitle = scope + " - " + (described != null && !described.isBlank() ? "filter " + described : "no filter") + (sort.isEmpty() ? "" : " - sort " + sort); + bytes = PrintingTableDocuments.pdf(title, subtitle, (table.getLabel() == null ? table.getName() : table.getLabel()) + " - " + PrintingRecordProcesses.printedBy(), + columns.stream().map(field -> field.getLabel() == null ? field.getName() : field.getLabel()).toList(), rows, widths(input.getValueString("columnWidths")), pageSize, orientation(input)); + if(all && total != null && total > records.size()) + { + output.addValue("printingTruncated", true); + output.addValue("printingMessage", "Printed the first " + records.size() + " of " + total + " rows: the print limit is " + filter.getLimit() + " rows. Narrow the filter to print the rest."); + } + } + else + { + title = input.getValueString("title") == null || input.getValueString("title").isBlank() ? "Screen" : input.getValueString("title"); + String subtitle = input.getValueString("subtitle"); + bytes = PrintingTextDocuments.pdf(title, (subtitle == null || subtitle.isBlank() ? "" : subtitle + " - ") + PrintingRecordProcesses.printedBy(), input.getValueString("text"), pageSize, "LANDSCAPE".equalsIgnoreCase(input.getValueString("orientation"))); + } + String job = PrintingRecordProcesses.queue(printer, title, bytes, copies, "list-print:" + request + ":" + input.getProcessName() + ":" + printer.getValueString("id")); + output.addValue(PrintingRecordProcesses.JOB_IDS, job); + output.addValue("result", "Queued print job " + job + ". Check Print jobs for its status." + (output.getValue("printingMessage") != null ? " " + output.getValue("printingMessage") : "")); + } + } +} diff --git a/src/main/java/com/kingsrook/qbits/printing/PrintingLocalAuthentication.java b/src/main/java/com/kingsrook/qbits/printing/PrintingLocalAuthentication.java new file mode 100644 index 0000000..94d4f8e --- /dev/null +++ b/src/main/java/com/kingsrook/qbits/printing/PrintingLocalAuthentication.java @@ -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 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; + } + } +} diff --git a/src/main/java/com/kingsrook/qbits/printing/PrintingLocalHost.java b/src/main/java/com/kingsrook/qbits/printing/PrintingLocalHost.java new file mode 100644 index 0000000..b90eafc --- /dev/null +++ b/src/main/java/com/kingsrook/qbits/printing/PrintingLocalHost.java @@ -0,0 +1,256 @@ +/* + * 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) + { + long uploadBodyLimit; + try + { + PrintingRealtimePolicy policy = service.realtimePolicy(); + uploadBodyLimit = ((Math.max(policy.get("maxPdfBytes"), policy.get("maxZplBytes")) + 2) / 3) * 4 + 65536; + } + catch(java.sql.SQLException exception) + { + throw new IllegalStateException("Cannot load printing transport limits", exception); + } + 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, new PrintingRealtimeRoutes(service))).withJavalinConfigCustomizer(config -> + { + config.jetty.host = "127.0.0.1"; + config.http.maxRequestSize = uploadBodyLimit; + 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 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()); + } + } + } + } + } +} diff --git a/src/main/java/com/kingsrook/qbits/printing/PrintingLocalSettings.java b/src/main/java/com/kingsrook/qbits/printing/PrintingLocalSettings.java new file mode 100644 index 0000000..16362d3 --- /dev/null +++ b/src/main/java/com/kingsrook/qbits/printing/PrintingLocalSettings.java @@ -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 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 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]"); + } +} diff --git a/src/main/java/com/kingsrook/qbits/printing/PrintingProcesses.java b/src/main/java/com/kingsrook/qbits/printing/PrintingProcesses.java index 3b13489..c35e8e4 100644 --- a/src/main/java/com/kingsrook/qbits/printing/PrintingProcesses.java +++ b/src/main/java/com/kingsrook/qbits/printing/PrintingProcesses.java @@ -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> pdf = new ArrayList<>(); + ArrayList> zpl = new ArrayList<>(); + for(TestPrintProfile profile : TestPrintProfile.values()) + { + QPossibleValue 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,74 @@ 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); + keepSelection(input, output); + } + } + + + + /*************************************************************************** + ** A selection action whose first step is a form loses the init request's + ** record selection: the UI API passes it only to the init call (as the + ** callback filter) and the extract step, which would store it, runs after + ** the form. Keep it as the extract step's own queryFilterJson value. + ***************************************************************************/ + static void keepSelection(RunBackendStepInput input, RunBackendStepOutput output) + { + String kept = input.getValueString("queryFilterJson"); + if((kept == null || kept.isBlank()) && input.getCallback() != null && input.getCallback().getQueryFilter() != null) + { + output.addValue("queryFilterJson", com.kingsrook.qqq.backend.core.utils.JsonUtils.toJson(input.getCallback().getQueryFilter())); + } + } + + + + /*************************************************************************** + ** 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 +452,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 +509,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 +543,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()); } } diff --git a/src/main/java/com/kingsrook/qbits/printing/PrintingQBitConfig.java b/src/main/java/com/kingsrook/qbits/printing/PrintingQBitConfig.java index 652847b..a0b0efa 100644 --- a/src/main/java/com/kingsrook/qbits/printing/PrintingQBitConfig.java +++ b/src/main/java/com/kingsrook/qbits/printing/PrintingQBitConfig.java @@ -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); + } diff --git a/src/main/java/com/kingsrook/qbits/printing/PrintingQBitProducer.java b/src/main/java/com/kingsrook/qbits/printing/PrintingQBitProducer.java index e42fc1e..af3f693 100644 --- a/src/main/java/com/kingsrook/qbits/printing/PrintingQBitProducer.java +++ b/src/main/java/com/kingsrook/qbits/printing/PrintingQBitProducer.java @@ -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,27 @@ 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); + PrintingListProcesses.register(instance); + PrintingDeviceProcesses.register(instance); + PrintingUiApi.register(instance); + PrintingRetentionProcesses.register(instance, config); + PrintingRealtimeProcesses.register(instance, app); PrintingHome.register(instance, app); instance.addApp(app); QAppMetaData parent = instance.getApp("admin"); @@ -136,6 +189,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 +277,17 @@ public class PrintingQBitProducer implements QBitProducer { table.getField("tenant_id").withIsHidden(true); java.util.LinkedHashMap 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 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())); diff --git a/src/main/java/com/kingsrook/qbits/printing/PrintingRealtimeBus.java b/src/main/java/com/kingsrook/qbits/printing/PrintingRealtimeBus.java new file mode 100644 index 0000000..5662ec8 --- /dev/null +++ b/src/main/java/com/kingsrook/qbits/printing/PrintingRealtimeBus.java @@ -0,0 +1,91 @@ +/* + * 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.concurrent.CopyOnWriteArrayList; +import java.util.function.BiConsumer; + + +/** Host-owned commit notification bridge. Callbacks only schedule bounded work. */ +public class PrintingRealtimeBus +{ + private final CopyOnWriteArrayList> listeners = new CopyOnWriteArrayList<>(); + private final java.util.concurrent.ConcurrentHashMap owners = new java.util.concurrent.ConcurrentHashMap<>(); + + + /** Atomically fence the preceding connection across route providers sharing this host bus. */ + public void acquire(String tenant, String device, String generation, Runnable replaced) + { + Owner previous = owners.put(tenant + ":" + device, new Owner(generation, replaced)); + if(previous != null) + { + previous.replaced().run(); + } + } + + + /** A replaced connection cannot claim or send even if its local close callback is delayed. */ + public boolean owns(String tenant, String device, String generation) + { + Owner current = owners.get(tenant + ":" + device); + return (current != null && current.generation().equals(generation)); + } + + + /** Release only the exact generation; old disconnects cannot remove a replacement. */ + public void release(String tenant, String device, String generation) + { + owners.computeIfPresent(tenant + ":" + device, (key, owner) -> owner.generation().equals(generation) ? null : owner); + } + + + /** Ownership contains no device token or user credential. */ + private record Owner(String generation, Runnable replaced) + { + } + + + /** Register before reading the durable snapshot to avoid a reconnect lost wakeup. */ + public AutoCloseable subscribe(BiConsumer listener) + { + listeners.add(listener); + return (() -> listeners.remove(listener)); + } + + + /** Publish only after commit. Shared-host implementations must preserve this nonblocking contract. */ + public void publish(String tenant, String device) + { + for(BiConsumer listener : listeners) + { + try + { + listener.accept(tenant, device); + } + catch(RuntimeException ignored) + { + // A stopped listener must not turn a successful commit into an apparent failure. + // Reconnection always reconstructs work from the durable database. + } + } + } +} diff --git a/src/main/java/com/kingsrook/qbits/printing/PrintingRealtimePolicy.java b/src/main/java/com/kingsrook/qbits/printing/PrintingRealtimePolicy.java new file mode 100644 index 0000000..5116fb6 --- /dev/null +++ b/src/main/java/com/kingsrook/qbits/printing/PrintingRealtimePolicy.java @@ -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.util.LinkedHashMap; +import java.util.Map; +import org.json.JSONObject; + + +/** Validated administrator policy, independent of any individual client connection. */ +public final class PrintingRealtimePolicy +{ + /** Canonical policy defaults and validation ranges. */ + private static final Map FIELDS = fields(); + private final JSONObject values; + + + /** Keep the validated policy private. */ + private PrintingRealtimePolicy(JSONObject values) + { + this.values = values; + } + + + /** Operational defaults; administrators can explicitly change every limit. */ + public static PrintingRealtimePolicy defaults() + { + JSONObject values = new JSONObject(); + FIELDS.forEach((name, range) -> values.put(name, range[0])); + return (new PrintingRealtimePolicy(values)); + } + + + /** Require a complete policy and reject unknown, fractional or out-of-range values. */ + public static PrintingRealtimePolicy fromJson(JSONObject input) + { + if(!input.keySet().equals(FIELDS.keySet())) + { + throw new PrintingException(400, "Realtime settings require exactly the documented policy fields"); + } + JSONObject values = new JSONObject(); + FIELDS.forEach((name, range) -> + { + Object raw = input.get(name); + if(!(raw instanceof Number number) || !number.toString().matches("[0-9]+")) + { + throw new PrintingException(400, "Realtime setting must be an integer: " + name); + } + long value; + try + { + value = Long.parseLong(number.toString()); + } + catch(NumberFormatException exception) + { + throw new PrintingException(400, "Realtime setting exceeds its range: " + name); + } + if(value < range[1] || value > range[2]) + { + throw new PrintingException(400, "Realtime setting exceeds its range: " + name); + } + values.put(name, value); + }); + PrintingRealtimePolicy policy = new PrintingRealtimePolicy(values); + policy.atLeast("maxQueuedFrameBytes", policy.get("maxFrameBytes")); + policy.atLeast("maxStagedBytes", Math.max(policy.get("maxPdfBytes"), policy.get("maxZplBytes"))); + policy.atLeast("downloadTimeoutMillis", Math.max(policy.get("downloadConnectTimeoutMillis"), policy.get("downloadIdleTimeoutMillis"))); + policy.atLeast("heartbeatTimeoutSeconds", 2 * policy.get("heartbeatIntervalSeconds")); + policy.atLeast("reconnectMaxDelayMillis", policy.get("reconnectMinDelayMillis")); + return (policy); + } + + + /** Read a validated named setting without exposing mutable JSON. */ + public long get(String name) + { + return (values.getLong(name)); + } + + + /** Wire settings include a server-generated durable revision. */ + public JSONObject toJson(long revision) + { + return (new JSONObject(values.toString()).put("revision", revision)); + } + + + /** Submission and retained-document retrieval use the configured format bound. */ + public long documentLimit(String format) + { + if(!"PDF".equals(format) && !"ZPL".equals(format)) + { + throw new PrintingException(400, "Only PDF and ZPL are supported"); + } + return (get("PDF".equals(format) ? "maxPdfBytes" : "maxZplBytes")); + } + + + /** A client must explicitly support the policy; never silently lower administrator limits. */ + public void requireClientLimits(JSONObject limits) + { + for(String name : new String[] {"maxPdfBytes", "maxZplBytes", "maxFrameBytes", "maxQueuedFrames", "maxQueuedFrameBytes", "maxConcurrentDownloads", "maxConcurrentPrints", "maxStagedBytes", "maxCopies"}) + { + Object value = limits.opt(name); + if(!(value instanceof Number number) || !number.toString().matches("[0-9]+") || number.longValue() < get(name)) + { + throw new PrintingException(409, "Client cannot support configured realtime limit: " + name); + } + } + } + + + /** Validate a cross-field lower bound. */ + + + private void atLeast(String name, long minimum) + { + if(get(name) < minimum) + { + throw new PrintingException(400, "Realtime settings conflict at " + name); + } + } + + + /** Canonical policy defaults and validation ranges. */ + private static Map fields() + { + Map fields = new LinkedHashMap<>(); + fields.put("maxPdfBytes", new long[] {104857600, 1, Integer.MAX_VALUE}); + fields.put("maxCopies", new long[] {100, 1, 32767}); + fields.put("maxZplBytes", new long[] {20971520, 1, Integer.MAX_VALUE}); + fields.put("maxFrameBytes", new long[] {1048576, 8192, 16777216}); + fields.put("maxQueuedFrames", new long[] {64, 8, 4096}); + fields.put("maxQueuedFrameBytes", new long[] {4194304, 8192, 67108864}); + fields.put("maxConcurrentDownloads", new long[] {1, 1, 16}); + fields.put("maxConcurrentPrints", new long[] {1, 1, 16}); + fields.put("maxStagedBytes", new long[] {536870912, 1, 9007199254740991L}); + fields.put("maxDownloadBytesPerSecond", new long[] {0, 0, Integer.MAX_VALUE}); + fields.put("requestTimeoutMillis", new long[] {30000, 1000, 300000}); + fields.put("downloadConnectTimeoutMillis", new long[] {30000, 1000, 300000}); + fields.put("webSocketHandshakeTimeoutMillis", new long[] {30000, 1000, 300000}); + fields.put("ackTimeoutMillis", new long[] {15000, 1000, 300000}); + fields.put("downloadIdleTimeoutMillis", new long[] {30000, 1000, 3600000}); + fields.put("downloadTimeoutMillis", new long[] {600000, 1000, 86400000}); + fields.put("nativeSubmissionTimeoutMillis", new long[] {120000, 1000, 86400000}); + fields.put("heartbeatIntervalSeconds", new long[] {20, 5, 300}); + fields.put("heartbeatTimeoutSeconds", new long[] {60, 10, 900}); + fields.put("reconnectMinDelayMillis", new long[] {1000, 100, 60000}); + fields.put("reconnectMaxDelayMillis", new long[] {30000, 1000, 300000}); + fields.put("reconnectJitterPercent", new long[] {20, 0, 50}); + return (java.util.Collections.unmodifiableMap(fields)); + } +} diff --git a/src/main/java/com/kingsrook/qbits/printing/PrintingRealtimeProcesses.java b/src/main/java/com/kingsrook/qbits/printing/PrintingRealtimeProcesses.java new file mode 100644 index 0000000..064db94 --- /dev/null +++ b/src/main/java/com/kingsrook/qbits/printing/PrintingRealtimeProcesses.java @@ -0,0 +1,256 @@ +/* + * 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.math.BigDecimal; +import java.sql.SQLException; +import java.util.List; +import com.kingsrook.qqq.backend.core.actions.processes.BackendStep; +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.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.layout.QAppMetaData; +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 org.json.JSONObject; + + +/******************************************************************************* + ** Native tenant settings use human units without exposing connection secrets. + *******************************************************************************/ +public class PrintingRealtimeProcesses implements BackendStep +{ + public static final String SETTINGS = "printingRealtimeSettings"; + public static final String ADMISSION = "printingAdmissionSettings"; + private static final long MEBIBYTE = 1024L * 1024; + private static final List DOCUMENTS = List.of( + new Setting("maxPdfMiB", "maxPdfBytes", "Maximum PDF size (MiB)", MEBIBYTE), + new Setting("maxZplMiB", "maxZplBytes", "Maximum ZPL size (MiB)", MEBIBYTE), + new Setting("maxCopies", "maxCopies", "Maximum copies per job", 1), + new Setting("maxStagedMiB", "maxStagedBytes", "Maximum staged documents on each device (MiB)", MEBIBYTE)); + private static final List TRANSFERS = List.of( + new Setting("maxConcurrentDownloads", "maxConcurrentDownloads", "Concurrent document downloads", 1), + new Setting("maxConcurrentPrints", "maxConcurrentPrints", "Concurrent printer submissions", 1), + new Setting("downloadKiBPerSecond", "maxDownloadBytesPerSecond", "Download bandwidth (KiB/second; 0 means unlimited)", 1024), + new Setting("requestTimeoutSeconds", "requestTimeoutMillis", "Request timeout (seconds)", 1000), + new Setting("downloadConnectSeconds", "downloadConnectTimeoutMillis", "Download connection timeout (seconds)", 1000), + new Setting("downloadIdleSeconds", "downloadIdleTimeoutMillis", "Download idle timeout (seconds)", 1000), + new Setting("downloadTotalSeconds", "downloadTimeoutMillis", "Total download timeout (seconds)", 1000), + new Setting("nativeSubmissionSeconds", "nativeSubmissionTimeoutMillis", "Native printer submission timeout (seconds)", 1000)); + private static final List CONNECTION = List.of( + new Setting("handshakeSeconds", "webSocketHandshakeTimeoutMillis", "WebSocket connection timeout (seconds)", 1000), + new Setting("heartbeatIntervalSeconds", "heartbeatIntervalSeconds", "Connection heartbeat interval (seconds)", 1), + new Setting("heartbeatTimeoutSeconds", "heartbeatTimeoutSeconds", "Unresponsive connection timeout (seconds)", 1), + new Setting("reconnectMinSeconds", "reconnectMinDelayMillis", "Initial reconnect delay (seconds)", 1000), + new Setting("reconnectMaxSeconds", "reconnectMaxDelayMillis", "Maximum reconnect delay (seconds)", 1000), + new Setting("reconnectJitterPercent", "reconnectJitterPercent", "Reconnect jitter (%)", 1), + new Setting("ackTimeoutSeconds", "ackTimeoutMillis", "Acknowledgment timeout (seconds)", 1000)); + private static final List CONTROL = List.of( + new Setting("maxFrameKiB", "maxFrameBytes", "Maximum control message (KiB)", 1024), + new Setting("maxQueuedFrames", "maxQueuedFrames", "Maximum queued control messages", 1), + new Setting("maxQueuedControlMiB", "maxQueuedFrameBytes", "Maximum queued control message data (MiB)", MEBIBYTE)); + private static final List ADMISSION_COUNTS = List.of( + new Setting("deviceOutstandingJobs", "deviceOutstandingJobs", "Outstanding jobs per device", 1), + new Setting("tenantOutstandingJobs", "tenantOutstandingJobs", "Outstanding jobs across this tenant", 1), + new Setting("deviceJobsPerHour", "deviceJobsPerHour", "Jobs allocated per device per hour", 1), + new Setting("tenantJobsPerHour", "tenantJobsPerHour", "Jobs allocated across this tenant per hour", 1), + new Setting("devicePrinters", "devicePrinters", "Printers per device", 1), + new Setting("tenantPrinters", "tenantPrinters", "Printers across this tenant", 1)); + private static final List ADMISSION_STORAGE = List.of( + new Setting("deviceOutstandingMiB", "deviceOutstandingBytes", "Outstanding document data per device (MiB)", MEBIBYTE), + new Setting("tenantOutstandingMiB", "tenantOutstandingBytes", "Outstanding document data across this tenant (MiB)", MEBIBYTE), + new Setting("deviceRetainedGiB", "deviceRetainedBytes", "Retained document data per device (GiB)", 1024 * MEBIBYTE), + new Setting("tenantRetainedGiB", "tenantRetainedBytes", "Retained document data across this tenant (GiB)", 1024 * MEBIBYTE)); + + + + /*************************************************************************** + ** Typed native forms group limits by purpose and reuse normal QQQ permissions. + ***************************************************************************/ + public static void register(QInstance instance, QAppMetaData app) + { + QProcessMetaData process = new QProcessMetaData().withName(SETTINGS).withLabel("Printing connection and limits") + .withPermissionRules(PrintingProcesses.permissionRules()) + .withStep(backend("prepare")) + .withStep(new QFrontendStepMetaData().withName("review").withLabel("Current connection policy") + .withViewFields(List.of(text("transport", "Connection"), text("scope", "Settings scope"), text("revisionLabel", "Current policy"))) + .withComponent(new QFrontendComponentMetaData().withType(QComponentType.VIEW_FORM))) + .withStep(form("documents", "Document limits", DOCUMENTS)) + .withStep(form("transfers", "Document transfers", TRANSFERS)) + .withStep(form("connection", "Connection recovery", CONNECTION)) + .withStep(form("control", "Control channel capacity", CONTROL)) + .withStep(backend("execute")) + .withStep(new QFrontendStepMetaData().withName("result").withLabel("Result").withViewFields(List.of(text("result", "Result"))) + .withComponent(new QFrontendComponentMetaData().withType(QComponentType.VIEW_FORM))); + instance.addProcess(process); + app.withChild(process); + QProcessMetaData admission = new QProcessMetaData().withName(ADMISSION).withLabel("Printing queue and storage limits") + .withPermissionRules(PrintingProcesses.permissionRules()).withStep(backend("prepare")) + .withStep(new QFrontendStepMetaData().withName("review").withLabel("Current admission policy") + .withViewFields(List.of(text("scope", "Settings scope"))).withComponent(new QFrontendComponentMetaData().withType(QComponentType.VIEW_FORM))) + .withStep(form("counts", "Queue, rate and printer limits", ADMISSION_COUNTS)) + .withStep(form("capacity", "Document storage capacity", ADMISSION_STORAGE)) + .withStep(backend("execute")) + .withStep(new QFrontendStepMetaData().withName("result").withLabel("Result").withViewFields(List.of(text("result", "Result"))) + .withComponent(new QFrontendComponentMetaData().withType(QComponentType.VIEW_FORM))); + instance.addProcess(admission); + app.withChild(admission); + } + + + + /*************************************************************************** + ** Each backend entrypoint independently checks the current user and tenant. + ***************************************************************************/ + @Override + public void run(RunBackendStepInput input, RunBackendStepOutput output) throws QException + { + PrintingControlAuthorization.principal(); + boolean admission = ADMISSION.equals(input.getProcessName()); + if(!SETTINGS.equals(input.getProcessName()) && !admission) + { + throw new QException("Unknown printing connection settings action"); + } + PrintingService service = PrintingProcesses.currentService(); + try + { + if("prepare".equals(input.getStepName())) + { + JSONObject policy = admission ? service.getAdmissionSettings() : service.getRealtimeSettings(); + for(List group : groups(admission)) + { + for(Setting setting : group) + { + output.addValue(setting.input(), BigDecimal.valueOf(policy.getLong(setting.policy())).divide(BigDecimal.valueOf(setting.unit()))); + } + } + output.addValue("transport", "The device opens a two-way WebSocket to this server. Documents use separate HTTPS transfers; job and command polling is not used."); + output.addValue("scope", admission ? "These limits apply to this tenant. Capacity is checked when jobs and printers are admitted. Changing a limit does not remove existing jobs, documents or history." + : "These settings apply to this tenant. Saved changes are sent to connected devices. Unsupported device limits require an explicit configuration correction; they are not silently reduced."); + output.addValue("revisionLabel", admission ? "Tenant admission policy" : "Policy revision " + policy.getLong("revision")); + } + else if("execute".equals(input.getStepName())) + { + JSONObject requested = new JSONObject(); + for(List group : groups(admission)) + { + for(Setting setting : group) + { + requested.put(setting.policy(), number(input, setting)); + } + } + JSONObject saved = admission ? service.saveAdmissionSettings(requested) : service.saveRealtimeSettings(requested); + output.addValue("result", admission ? "Queue, rate, printer and storage limits saved for this tenant. Existing jobs and history were preserved." + : "Connection and document limits saved as policy revision " + saved.getLong("revision") + ". Connected devices receive the update over their existing WebSocket; no documents or job history were removed."); + } + else + { + throw new QException("Unknown printing connection settings step"); + } + } + catch(SQLException | PrintingException | IllegalArgumentException exception) + { + throw new QException("Connection settings were not saved: " + exception.getMessage(), exception); + } + } + + + + /*************************************************************************** + ** Numeric conversions reject missing, rounded and overflowing input values. + ***************************************************************************/ + private static long number(RunBackendStepInput input, Setting setting) throws QException + { + Object value = input.getValue(setting.input()); + if(value == null) + { + throw new QException("Specify " + setting.label().toLowerCase(java.util.Locale.ROOT)); + } + try + { + return (new BigDecimal(value.toString()).multiply(BigDecimal.valueOf(setting.unit())).longValueExact()); + } + catch(NumberFormatException | ArithmeticException exception) + { + throw new QException(setting.label() + " must be a valid number within the supported range", exception); + } + } + + + + /*************************************************************************** + ** Keep reading and writing the same complete set of advertised policy fields. + ***************************************************************************/ + private static List> groups(boolean admission) + { + return (admission ? List.of(ADMISSION_COUNTS, ADMISSION_STORAGE) : List.of(DOCUMENTS, TRANSFERS, CONNECTION, CONTROL)); + } + + + + /*************************************************************************** + ** Human-readable units remain local to the form, never part of wire identity. + ***************************************************************************/ + private static QFrontendStepMetaData form(String name, String label, List settings) + { + return (new QFrontendStepMetaData().withName(name).withLabel(label) + .withFormFields(settings.stream().map(setting -> new QFieldMetaData(setting.input(), setting.unit() == 1 ? QFieldType.INTEGER : QFieldType.DECIMAL) + .withLabel(setting.label()).withIsRequired(true)).toList()) + .withComponent(new QFrontendComponentMetaData().withType(QComponentType.EDIT_FORM))); + } + + + + /*************************************************************************** + ** Every step uses the same native backend and read-only result widgets. + ***************************************************************************/ + private static QBackendStepMetaData backend(String name) + { + return (new QBackendStepMetaData().withName(name).withCode(new QCodeReference(PrintingRealtimeProcesses.class))); + } + + + + /*************************************************************************** + ** View fields contain policy descriptions rather than editable identifiers. + ***************************************************************************/ + private static QFieldMetaData text(String name, String label) + { + return (new QFieldMetaData(name, QFieldType.STRING).withLabel(label)); + } + + + + /*************************************************************************** + ** Unit factors make the form reversible without losing byte precision. + ***************************************************************************/ + private record Setting(String input, String policy, String label, long unit) + { + } +} diff --git a/src/main/java/com/kingsrook/qbits/printing/PrintingRealtimeRoutes.java b/src/main/java/com/kingsrook/qbits/printing/PrintingRealtimeRoutes.java new file mode 100644 index 0000000..44834b5 --- /dev/null +++ b/src/main/java/com/kingsrook/qbits/printing/PrintingRealtimeRoutes.java @@ -0,0 +1,670 @@ +/* + * 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.nio.charset.StandardCharsets; +import java.time.Duration; +import java.time.Instant; +import java.util.ArrayDeque; +import java.util.Map; +import java.util.Set; +import java.util.UUID; +import java.util.concurrent.CompletableFuture; +import java.util.concurrent.ConcurrentHashMap; +import java.util.concurrent.ExecutorService; +import java.util.concurrent.Executors; +import java.util.concurrent.TimeUnit; +import com.kingsrook.qqq.backend.core.actions.profile.UserProfiles; +import com.kingsrook.qqq.backend.core.context.QContext; +import com.kingsrook.qqq.backend.core.exceptions.QAuthenticationException; +import com.kingsrook.qqq.backend.core.exceptions.QPermissionDeniedException; +import com.kingsrook.qqq.backend.core.model.metadata.QInstance; +import com.kingsrook.qqq.backend.core.model.metadata.permissions.ClientChannelsMetaData; +import com.kingsrook.qqq.backend.core.modules.authentication.QAuthenticationModuleDispatcher; +import com.kingsrook.qqq.middleware.javalin.QJavalinRouteProviderInterface; +import com.kingsrook.qqq.middleware.javalin.executors.ExecutorSessionUtils; +import io.javalin.config.JavalinConfig; +import io.javalin.http.Context; +import io.javalin.http.HttpResponseException; +import io.javalin.websocket.WsContext; +import org.eclipse.jetty.websocket.api.Callback; +import org.json.JSONArray; +import org.json.JSONObject; + + +/** Current-user authenticated outbound channels. SQL is authoritative; notifications are only wakeups. */ +public final class PrintingRealtimeRoutes implements QJavalinRouteProviderInterface, AutoCloseable +{ + public static final String PATH = "/qqq/v1/qbit/printing/device/realtime"; + public static final String SUBPROTOCOL = "qqq-printing.v1"; + private final PrintingService service; + private final Map channels = new ConcurrentHashMap<>(); + private final ExecutorService workers = Executors.newVirtualThreadPerTaskExecutor(); + private final AutoCloseable subscription; + private QInstance instance; + + + /** Register this provider alongside the host's ordinary native QQQ endpoints. */ + public PrintingRealtimeRoutes(PrintingService service) + { + this.service = java.util.Objects.requireNonNull(service); + service.withRealtimeClaimGuard(this::requireReady); + subscription = service.getRealtimeBus().subscribe((tenant, device) -> + { + if(service.getTenantId().equals(tenant)) + { + channels.values().stream().filter(channel -> device == null || device.equals(channel.device)).forEach(Channel::changed); + } + }); + } + + + @Override + public void setQInstance(QInstance value) + { + instance = value; + } + + + @Override + public void acceptJavalinConfig(JavalinConfig config) + { + config.routes.wsBeforeUpgrade(PATH, context -> + { + try + { + validateUpgrade(context); + authorize(context); + String cookieName = context.cookie("sessionId") != null && !context.cookie("sessionId").isBlank() ? "sessionId" : "sessionUUID"; + context.attribute("printingRealtimeCredential", new Credential(cookieName, context.cookie(cookieName), context.header(PrintingAgentAuthorization.TOKEN_HEADER), context.header("X-QQQ-Client"))); + } + catch(Exception exception) + { + throw new HttpResponseException(exception instanceof QAuthenticationException ? 401 : 403, "Realtime authentication or origin denied", Map.of()); + } + finally + { + QContext.clear(); + } + }); + config.routes.ws(PATH, socket -> + { + socket.onConnect(context -> + { + String device = context.header(PrintingAgentAuthorization.DEVICE_HEADER); + Channel next = new Channel(context, device, context.attribute("printingRealtimeCredential")); + next.policy = service.realtimePolicy(); + Channel previous = channels.put(device, next); + if(previous != null) + { + previous.stop("Connection replaced"); + } + service.getRealtimeBus().acquire(service.getTenantId(), device, next.generation, () -> next.stop("Connection replaced")); + context.session.setMaxTextMessageSize(next.policy.get("maxFrameBytes")); + context.session.setMaxBinaryMessageSize(0); + context.session.setIdleTimeout(Duration.ofMillis(next.policy.get("webSocketHandshakeTimeoutMillis"))); + }); + socket.onMessage(context -> + { + Channel channel = current(context); + if(channel != null) + { + channel.accept(context.message()); + } + }); + socket.onBinaryMessage(context -> context.closeSession(1003, "Only JSON text is supported")); + socket.onClose(context -> remove(context)); + socket.onError(context -> remove(context)); + }); + config.events.serverStopping(this::close); + } + + + /** Resolve only the current socket generation. */ + + + private Channel current(WsContext context) + { + Channel channel = channels.get(context.header(PrintingAgentAuthorization.DEVICE_HEADER)); + return (channel != null && channel.socket.session == context.session ? channel : null); + } + + + /** Remove only the closing socket generation. */ + + + private void remove(WsContext context) + { + Channel channel = current(context); + if(channel != null) + { + channel.stop("Connection closed"); + } + } + + + /** Gate native claims on acknowledged current settings. */ + + + private void requireReady(String device) throws java.sql.SQLException + { + Channel channel = channels.get(device); + if(channel == null || !channel.ready(service.getRealtimeSettings().getLong("revision"))) + { + throw new PrintingException(409, "An authenticated realtime connection must apply current state and settings before claiming work"); + } + } + + + /** Reject query credentials, non-session authentication and foreign origins. */ + + + private static void validateUpgrade(Context context) + { + if(context.queryString() != null || !SUBPROTOCOL.equals(context.header("Sec-WebSocket-Protocol")) + || ((context.cookie("sessionUUID") == null || context.cookie("sessionUUID").isBlank()) && (context.cookie("sessionId") == null || context.cookie("sessionId").isBlank())) + || context.header("Authorization") != null || context.header("x-api-key") != null || context.header("X-QQQ-In-Process-Session") != null) + { + throw new PrintingException(403, "A standard QQQ session and the printing subprotocol are required"); + } + URI request = URI.create(context.url()); + URI origin = URI.create(java.util.Objects.toString(context.header("Origin"), "")); + boolean loopback = Set.of("localhost", "127.0.0.1", "[::1]", "::1").contains(request.getHost()); + if(!("https".equals(request.getScheme()) || (loopback && "http".equals(request.getScheme()))) + || !java.util.Objects.equals(request.getScheme(), origin.getScheme()) + || !java.util.Objects.equals(request.getRawAuthority(), origin.getRawAuthority()) + || origin.getRawUserInfo() != null || origin.getRawQuery() != null || origin.getRawFragment() != null + || !(origin.getPath().isEmpty() || "/".equals(origin.getPath()))) + { + throw new PrintingException(403, "Realtime origin must match the authenticated server origin"); + } + } + + + /** Revalidate the standard current QQQ session and secondary device ownership. */ + + + private void authorize(Context context) throws Exception + { + ExecutorSessionUtils.setupSession(context, instance); + PrintingAgentAuthorization.device(context.header(PrintingAgentAuthorization.DEVICE_HEADER), context.header(PrintingAgentAuthorization.TOKEN_HEADER), false); + } + + + /** Only transport credentials survive upgrade; user roles and session authority are never cached. */ + private static final class Credential + { + private final String cookie; + private final String cookieName; + private final String proof; + private final String clientChannel; + + + /** Capture immutable authenticated transport inputs before Jetty releases the HTTP request. */ + private Credential(String cookieName, String cookie, String proof, String clientChannel) + { + this.cookieName = cookieName; + this.cookie = cookie; + this.proof = proof; + this.clientChannel = clientChannel; + } + + + @Override + public String toString() + { + return ("Printing realtime credential [redacted]"); + } + } + + + @Override + public void close() + { + channels.values().forEach(channel -> channel.stop("Server stopping")); + try + { + subscription.close(); + } + catch(Exception exception) + { + throw new IllegalStateException("Unable to remove realtime subscription", exception); + } + finally + { + workers.shutdown(); + } + } + + + /** One serial bounded mailbox per socket; network waits never run on the committing caller. */ + private final class Channel + { + private final WsContext socket; + private final String device; + private final String generation = UUID.randomUUID().toString(); + private final Credential credential; + private final ArrayDeque mailbox = new ArrayDeque<>(); + private PrintingRealtimePolicy policy = PrintingRealtimePolicy.defaults(); + private JSONObject hello; + private boolean running; + private boolean dirty; + private boolean stopped; + private long queuedBytes; + private long appliedState = -1; + private long appliedSettings = -1; + private long sentState = -1; + private long sentSettings = -1; + + + /** Bind one mailbox to its authenticated socket. */ + + + private Channel(WsContext socket, String device, Credential credential) + { + this.socket = socket; + this.device = device; + this.credential = credential; + } + + + /** Re-enter the configured native authentication module for every operation after HTTP upgrade. */ + private void authorizeCurrent() throws Exception + { + QContext.init(instance, null); + var module = new QAuthenticationModuleDispatcher().getQModule(instance.getAuthentication()); + var session = module.createSession(instance, Map.of(credential.cookieName, credential.cookie)); + UserProfiles.applyIfInstalled(instance, session); + QContext.init(instance, session, null, null); + if(session.getCredentialScope() != null) + { + throw new QAuthenticationException("Realtime printing requires a current user session"); + } + String channel = credential.clientChannel == null || credential.clientChannel.isBlank() ? null : credential.clientChannel.strip(); + if(channel != null && (!ClientChannelsMetaData.of(instance).isAllowedChannel(ClientChannelsMetaData.channelName(channel)) || channel.length() > 200)) + { + throw new QPermissionDeniedException("The current client channel is not allowed"); + } + session.setClientChannel(channel == null ? null : channel.strip()); + PrintingAgentAuthorization.device(device, credential.proof, false); + } + + + /** Read synchronized connection application state. */ + + + private synchronized boolean ready(long revision) + { + return (!stopped && socket.session.isOpen() && service.getRealtimeBus().owns(service.getTenantId(), device, generation) + && hello != null && appliedState == sentState && appliedSettings == sentSettings && appliedSettings == revision); + } + + + /** Bound inbound work before scheduling any database operation. */ + + + private synchronized void accept(String frame) + { + int bytes = frame.getBytes(StandardCharsets.UTF_8).length; + if(bytes > policy.get("maxFrameBytes") || mailbox.size() >= policy.get("maxQueuedFrames") || queuedBytes + bytes > policy.get("maxQueuedFrameBytes")) + { + stop("Realtime mailbox limit exceeded"); + return; + } + mailbox.add(frame); + queuedBytes += bytes; + schedule(); + } + + + /** Coalesce commit wakeups without blocking the committing caller. */ + + + private synchronized void changed() + { + dirty = true; + schedule(); + } + + + /** Start at most one serial worker for this connection. */ + + + private void schedule() + { + if(!running && !stopped) + { + running = true; + workers.execute(this::drain); + } + } + + + /** Process bounded inbound work and coalesced durable-state wakeups. */ + + + private void drain() + { + while(true) + { + String frame; + synchronized(this) + { + frame = mailbox.poll(); + if(frame != null) + { + queuedBytes -= frame.getBytes(StandardCharsets.UTF_8).length; + } + else if(!dirty || hello == null || stopped) + { + running = false; + return; + } + else + { + dirty = false; + } + } + try + { + if(channels.get(device) != this || stopped || !service.getRealtimeBus().owns(service.getTenantId(), device, generation)) + { + return; + } + authorizeCurrent(); + if(frame == null) + { + snapshot(false); + } + else + { + receive(new JSONObject(frame)); + } + } + catch(Exception exception) + { + if(reject(frame, exception)) + { + return; + } + } + finally + { + QContext.clear(); + } + } + } + + + /** Apply one authenticated protocol operation. */ + + + private void receive(JSONObject frame) throws Exception + { + if(!frame.keySet().equals(Set.of("type", "messageId", "payload")) || !(frame.opt("messageId") instanceof String messageId) + || !messageId.matches("[A-Za-z0-9._-]{1,200}") || !(frame.opt("payload") instanceof JSONObject payload)) + { + throw new PrintingException(400, "Invalid realtime envelope"); + } + String type = frame.getString("type"); + if(hello == null && !"HELLO".equals(type)) + { + throw new PrintingException(409, "HELLO is required first"); + } + switch(type) + { + case "HELLO" -> + { + if(hello != null || !payload.keySet().equals(Set.of("agentVersion", "capabilities", "lastAppliedRevision", "lastSettingsRevision", "limits")) + || !payload.getJSONArray("capabilities").toList().contains("realtime-v1") + || payload.getJSONArray("capabilities").length() > 3 + || !Set.of("realtime-v1", "REFRESH_INVENTORY", "CANCEL_SPOOL").containsAll(payload.getJSONArray("capabilities").toList())) + { + throw new PrintingException(409, "Realtime capability is required"); + } + hello = payload; + snapshot(true); + return; + } + case "STATE_APPLIED" -> + { + long state = integer(payload, "lastAppliedRevision"); + long settings = integer(payload, "lastSettingsRevision"); + if(state > sentState || settings > sentSettings || state < appliedState || settings < appliedSettings) + { + throw new PrintingException(409, "Only the current delivered state and settings may be acknowledged"); + } + service.applyRealtimeState(device, controlRequest(state), settings); + synchronized(this) + { + appliedState = state; + appliedSettings = settings; + } + changed(); + } + case "JOB_EVENT" -> + { + String job = payload.getString("jobId"); + PrintingControlAuthorization.job(device, job); + service.event(device, job, payload.getJSONObject("event")); + } + case "COMMAND_RECEIPT" -> + { + String command = payload.getString("commandId"); + PrintingControlAuthorization.table(PrintingTables.COMMAND); + service.getDeviceCommand(device, command); + PrintingUiApiSpec.command(device, command); + service.deviceControlReceipt(device, command, payload.getJSONObject("receipt")); + changed(); + } + case "HEARTBEAT" -> service.heartbeat(device, payload); + case "INVENTORY" -> service.inventory(device, payload.getJSONArray("printers"), PrintingAgentAuthorization.inventory(device)); + case "PING" -> + { + service.realtimeContact(device); + send("PONG", new JSONObject().put("serverTime", Instant.now().toString())); + return; + } + default -> throw new PrintingException(400, "Unsupported realtime message"); + } + send("ACK", new JSONObject().put("acknowledgedMessageId", messageId)); + } + + + /** Domain errors retain their identity and never masquerade as a durable acknowledgment. */ + private boolean reject(String request, Exception exception) + { + System.getLogger(PrintingRealtimeRoutes.class.getName()).log(System.Logger.Level.WARNING, + "Realtime operation rejected: " + exception.getClass().getSimpleName() + " at " + (exception.getStackTrace().length == 0 ? "unknown" : exception.getStackTrace()[0])); + boolean authorization = exception instanceof QAuthenticationException || exception instanceof QPermissionDeniedException; + int status = exception instanceof PrintingException printing ? printing.getStatus() : authorization ? 403 : exception instanceof org.json.JSONException ? 400 : 500; + boolean connectionError = request == null || hello == null || sentSettings < 0 || status == 401 || status == 403 || status >= 500; + String code = switch(status) + { + case 401, 403 -> "AUTHORIZATION_REQUIRED"; + case 404 -> "NOT_FOUND"; + case 410 -> "EXPIRED"; + case 409 -> connectionError ? "CONFIGURATION_REQUIRED" : "CONFLICT"; + case 400, 413 -> "INVALID_MESSAGE"; + default -> "OPERATION_FAILED"; + }; + String id = UUID.randomUUID().toString(); + try + { + if(request != null) + { + String requested = new JSONObject(request).optString("messageId"); + if(requested.matches("[A-Za-z0-9._-]{1,200}")) + { + id = requested; + } + } + String error = new JSONObject().put("type", "ERROR").put("messageId", id).put("payload", new JSONObject().put("code", code) + .put("message", "The realtime operation was rejected; inspect the current state before retrying").put("retryable", status >= 500)).toString(); + CompletableFuture sent = new CompletableFuture<>(); + socket.session.sendText(error, Callback.from(() -> sent.complete(null), sent::completeExceptionally)); + sent.get(policy.get("ackTimeoutMillis"), TimeUnit.MILLISECONDS); + } + catch(Exception failure) + { + connectionError = true; + } + if(connectionError) + { + stop("Realtime operation rejected"); + } + return (connectionError); + } + + + /** Reuse the durable control protocol with advertised supported operations. */ + + + private JSONObject controlRequest(long state) + { + JSONArray capabilities = new JSONArray(); + for(Object value : hello.getJSONArray("capabilities")) + { + if(Set.of("REFRESH_INVENTORY", "CANCEL_SPOOL").contains(value)) + { + capabilities.put(value); + } + } + return (new JSONObject().put("controlVersion", 1).put("agentVersion", hello.getString("agentVersion")) + .put("capabilities", capabilities).put("lastAppliedRevision", state)); + } + + + /** Reconstruct current state and pending commands after registration or commit. */ + + + private void snapshot(boolean initial) throws Exception + { + JSONObject settings = service.getRealtimeSettings(); + if(initial && integer(hello, "lastSettingsRevision") > settings.getLong("revision")) + { + throw new PrintingException(409, "Unknown realtime settings revision"); + } + JSONObject values = new JSONObject(settings.toString()); + values.remove("revision"); + policy = PrintingRealtimePolicy.fromJson(values); + policy.requireClientLimits(hello.getJSONObject("limits")); + socket.session.setMaxTextMessageSize(policy.get("maxFrameBytes")); + socket.session.setIdleTimeout(Duration.ofSeconds(policy.get("heartbeatTimeoutSeconds"))); + JSONObject state = service.deviceControlPoll(device, controlRequest(initial ? integer(hello, "lastAppliedRevision") : Math.max(0, appliedState))); + PrintingControlAuthorization.table(PrintingTables.COMMAND); + JSONObject desired = state.getJSONObject("desiredState"); + long previousState; + long previousSettings; + synchronized(this) + { + previousState = sentState; + previousSettings = sentSettings; + sentState = desired.getLong("revision"); + sentSettings = settings.getLong("revision"); + } + if(initial) + { + send("WELCOME", new JSONObject().put("connectionId", UUID.randomUUID().toString()).put("serverTime", Instant.now().toString()) + .put("desiredState", desired).put("settings", settings)); + } + else + { + if(previousSettings != sentSettings) + { + send("SETTINGS", settings); + } + if(previousState != sentState) + { + send("DESIRED_STATE", desired); + } + } + if(!ready(sentSettings)) + { + return; + } + for(Object item : state.getJSONArray("commands")) + { + JSONObject command = (JSONObject) item; + PrintingUiApiSpec.command(device, command.getString("commandId")); + send("COMMAND", command); + } + send("JOB_AVAILABLE", new JSONObject()); + } + + + /** Revalidate authority and await one bounded asynchronous socket write. */ + + + private void send(String type, JSONObject payload) throws Exception + { + authorizeCurrent(); + synchronized(this) + { + if(stopped || channels.get(device) != this || !service.getRealtimeBus().owns(service.getTenantId(), device, generation)) + { + throw new PrintingException(409, "Connection was replaced"); + } + } + String frame = new JSONObject().put("type", type).put("messageId", UUID.randomUUID().toString()).put("payload", payload).toString(); + if(frame.getBytes(StandardCharsets.UTF_8).length > policy.get("maxFrameBytes")) + { + throw new PrintingException(413, "Realtime frame limit exceeded"); + } + CompletableFuture sent = new CompletableFuture<>(); + socket.session.sendText(frame, Callback.from(() -> sent.complete(null), sent::completeExceptionally)); + sent.get(policy.get("ackTimeoutMillis"), TimeUnit.MILLISECONDS); + } + + + /** Fence and remove this connection without affecting a replacement. */ + + + private synchronized void stop(String reason) + { + if(!stopped) + { + stopped = true; + mailbox.clear(); + queuedBytes = 0; + channels.remove(device, this); + service.getRealtimeBus().release(service.getTenantId(), device, generation); + socket.closeSession(1008, reason); + } + } + } + + + /** Reject absent, fractional and negative revision values. */ + + + private static long integer(JSONObject value, String name) + { + Object raw = value.get(name); + if(!(raw instanceof Number number) || !number.toString().matches("[0-9]+")) + { + throw new PrintingException(400, "Expected nonnegative integer " + name); + } + return (number.longValue()); + } +} diff --git a/src/main/java/com/kingsrook/qbits/printing/PrintingRecordDocuments.java b/src/main/java/com/kingsrook/qbits/printing/PrintingRecordDocuments.java new file mode 100644 index 0000000..29b7fc6 --- /dev/null +++ b/src/main/java/com/kingsrook/qbits/printing/PrintingRecordDocuments.java @@ -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.io.IOException; +import java.util.ArrayList; +import java.util.List; +import java.util.Map; +import com.kingsrook.qqq.backend.core.exceptions.QException; + + +/******************************************************************************* + ** A Letter "record sheet": a heading and subtitle, then each section of the + ** record (label/value lines, wrapped and continued across pages), then a + ** summary of each child list (its label, how many rows, and the first rows as + ** a small table). It is the generic document a record print renders when the + ** host supplies no template of its own. + *******************************************************************************/ +public final class PrintingRecordDocuments +{ + static final int MAX_LINES = 4000; + private static final int BODY_SIZE = 10; + private static final int CHILD_SIZE = 8; + + + + /*************************************************************************** + ** Utility class. + ***************************************************************************/ + private PrintingRecordDocuments() + { + } + + + + /*************************************************************************** + ** One section: a label (blank for none) and label/value lines in order. + ***************************************************************************/ + public record Section(String label, Map fields) + { + } + + + + /*************************************************************************** + ** One child list: its label, total row count, column headings and the + ** first rows (display text). + ***************************************************************************/ + public record ChildList(String label, int total, List columns, List> rows) + { + } + + + + /*************************************************************************** + ** One section without children (the original record sheet). + ***************************************************************************/ + public static byte[] pdf(String title, String subtitle, Map fields) throws QException + { + return (pdf(title, subtitle, List.of(new Section("", fields)), List.of())); + } + + + + /*************************************************************************** + ** Render sections and child list summaries as a PDF. + ***************************************************************************/ + public static byte[] pdf(String title, String subtitle, List
sections, List children) throws QException + { + try(PrintingLayout layout = new PrintingLayout("LETTER", false, title, subtitle)) + { + int columns = layout.columns(BODY_SIZE); + int labelWidth = Math.min(28, Math.max(8, sections.stream().flatMap(s -> s.fields().keySet().stream()).mapToInt(String::length).max().orElse(8) + 1)); + int lines = 0; + for(Section section : sections) + { + if(section.fields().isEmpty()) + { + continue; + } + if(section.label() != null && !section.label().isBlank()) + { + layout.gap(4); + layout.keep(3, BODY_SIZE); + layout.line(section.label(), BODY_SIZE + 1); + } + for(Map.Entry field : section.fields().entrySet()) + { + List wrapped = wrap(field.getValue() == null ? "" : field.getValue(), columns - labelWidth - 1); + for(int i = 0; i < wrapped.size() && lines++ < MAX_LINES; i++) + { + layout.line(String.format("%-" + labelWidth + "s %s", i == 0 ? truncate(field.getKey(), labelWidth - 1) : "", wrapped.get(i)), BODY_SIZE); + } + } + } + for(ChildList child : children) + { + layout.gap(8); + layout.keep(4, CHILD_SIZE); + layout.line(child.label() + " (" + child.total() + ")", BODY_SIZE + 1); + if(child.rows().isEmpty()) + { + layout.line("(none)", CHILD_SIZE); + continue; + } + int[] widths = PrintingLayout.columnWidths(child.columns(), child.rows(), layout.columns(CHILD_SIZE)); + layout.line(PrintingLayout.row(child.columns(), widths), CHILD_SIZE); + for(List row : child.rows()) + { + layout.line(PrintingLayout.row(row, widths), CHILD_SIZE); + } + if(child.total() > child.rows().size()) + { + layout.line("... and " + (child.total() - child.rows().size()) + " more", CHILD_SIZE); + } + } + return (layout.finish()); + } + catch(IOException exception) + { + throw new QException("Could not render the record document: " + exception.getMessage(), exception); + } + } + + + + /*************************************************************************** + ** Break text at spaces (or hard, for long words) into lines of at most + ** width characters; embedded line breaks start new lines. + ***************************************************************************/ + static List wrap(String text, int width) + { + List lines = new ArrayList<>(); + for(String paragraph : text.replace("\r\n", "\n").replace('\r', '\n').replace('\t', ' ').split("\n", -1)) + { + String rest = paragraph.strip(); + if(rest.isEmpty()) + { + lines.add(""); + continue; + } + while(rest.length() > width) + { + int cut = rest.lastIndexOf(' ', width); + if(cut <= 0) + { + cut = width; + } + lines.add(rest.substring(0, cut).stripTrailing()); + rest = rest.substring(cut).stripLeading(); + } + lines.add(rest); + } + return (lines); + } + + + + /*************************************************************************** + ** Shorten to at most length characters, marking the cut. + ***************************************************************************/ + static String truncate(String text, int length) + { + String value = text == null ? "" : text.replace('\n', ' ').replace('\r', ' '); + return (value.length() <= length ? value : value.substring(0, Math.max(0, length - 1)) + "~"); + } +} diff --git a/src/main/java/com/kingsrook/qbits/printing/PrintingRecordProcesses.java b/src/main/java/com/kingsrook/qbits/printing/PrintingRecordProcesses.java new file mode 100644 index 0000000..4ed48dd --- /dev/null +++ b/src/main/java/com/kingsrook/qbits/printing/PrintingRecordProcesses.java @@ -0,0 +1,515 @@ +/* + * 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.time.temporal.ChronoUnit; +import java.util.ArrayList; +import java.util.Base64; +import java.util.HashMap; +import java.util.LinkedHashMap; +import java.util.List; +import java.util.Map; +import java.util.UUID; +import com.kingsrook.qqq.backend.core.actions.permissions.PermissionEnforcement; +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.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.QQueryFilter; +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.model.metadata.tables.QTableMetaData; +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; + + +/******************************************************************************* + ** "Print" on the records of a host table: choose an approved, exposed PDF + ** printer and a copy count, review the selection, then each selected record is + ** rendered as a record sheet (PrintingRecordDocuments) and queued as its own + ** print job through the ordinary durable queue. The queued job IDs are returned + ** in the process value printingJobIds (comma separated) so clients can follow + ** each job's status in Print jobs. + ** + ** Register per table with register(instance, tableName); the process is named + ** printingPrintRecords_{tableName} (processName(tableName)). + *******************************************************************************/ +public final class PrintingRecordProcesses +{ + public static final String PREFIX = "printingPrintRecords_"; + public static final String PRINTER_FIELD = "printingPrinterId"; + public static final String COPIES_FIELD = "printingCopies"; + public static final String JOB_IDS = "printingJobIds"; + static final String REQUEST_ID = "printingRecordRequestId"; + static final int CHILD_ROWS = 10; + + + + /*************************************************************************** + ** Utility class. + ***************************************************************************/ + private PrintingRecordProcesses() + { + } + + + + /*************************************************************************** + ** The record-print process name of a table. + ***************************************************************************/ + public static String processName(String tableName) + { + return (PREFIX + tableName); + } + + + + /*************************************************************************** + ** Add the Print action to a table's records and selections. + ***************************************************************************/ + public static void register(QInstance instance, String tableName) throws QException + { + QTableMetaData table = instance.getTable(tableName); + if(table == null) + { + throw new QException("Cannot add printing to unknown table " + tableName); + } + Map values = new HashMap<>(); + values.put(StreamedETLWithFrontendProcess.FIELD_SOURCE_TABLE, tableName); + values.put(StreamedETLWithFrontendProcess.FIELD_DESTINATION_TABLE, tableName); + values.put(StreamedETLWithFrontendProcess.FIELD_SUPPORTS_FULL_VALIDATION, true); + values.put(StreamedETLWithFrontendProcess.FIELD_DO_FULL_VALIDATION, true); + values.put(StreamedETLWithFrontendProcess.FIELD_PREVIEW_MESSAGE, "Each selected record will be printed as its own job on the chosen printer after you continue."); + QProcessMetaData process = StreamedETLWithFrontendProcess.defineProcessMetaData(PrintingExtract.class, Transform.class, Load.class, values) + .withName(processName(tableName)).withLabel("Print").withTableName(tableName).withMinInputRecords(1) + .withPermissionRules(PrintingProcesses.permissionRules()); + process.withStep(0, new QFrontendStepMetaData().withName("printer").withLabel("Choose a printer") + .withFormFields(List.of(printerField(), new QFieldMetaData(COPIES_FIELD, QFieldType.INTEGER).withLabel("Copies").withIsRequired(true).withDefaultValue(1))) + .withComponent(new QFrontendComponentMetaData().withType(QComponentType.EDIT_FORM))); + process.withStep(0, new QBackendStepMetaData().withName("preparePrint").withCode(new QCodeReference(Prepare.class))); + instance.addProcess(process); + } + + + + /*************************************************************************** + ** Add Print to every table of the instance that can be read one record at + ** a time: skips hidden tables, tables without a primary key or without + ** TABLE_GET, tables that already have Print, and tables whose + ** PrintingTableSettings say printable false. Call it after every table is + ** in the instance. Returns the tables that got Print. + ***************************************************************************/ + public static List registerAll(QInstance instance) throws QException + { + List added = new ArrayList<>(); + for(QTableMetaData table : new ArrayList<>(instance.getTables().values())) + { + PrintingTableSettings settings = PrintingTableSettings.of(table); + boolean readable = table.isCapabilityEnabled(instance.getBackendForTable(table.getName()), com.kingsrook.qqq.backend.core.model.metadata.tables.Capability.TABLE_GET); + if(Boolean.TRUE.equals(table.getIsHidden()) || table.getPrimaryKeyField() == null || !readable + || (settings != null && !settings.getPrintable()) || instance.getProcess(processName(table.getName())) != null) + { + continue; + } + register(instance, table.getName()); + added.add(table.getName()); + } + return (added); + } + + + + /*************************************************************************** + ** Only approved printers that the device currently exposes and that take PDF. + ***************************************************************************/ + static QFieldMetaData printerField() + { + QQueryFilter filter = new QQueryFilter(new QFilterCriteria("enabled", QCriteriaOperator.EQUALS, 1)) + .withCriteria(new QFilterCriteria("available", QCriteriaOperator.EQUALS, 1)) + .withCriteria(new QFilterCriteria("formats", QCriteriaOperator.CONTAINS, "PDF")); + return (new QFieldMetaData(PRINTER_FIELD, QFieldType.STRING).withLabel("Printer").withIsRequired(true) + .withPossibleValueSourceName(PrintingTables.PRINTER).withPossibleValueSourceFilter(filter)); + } + + + + /*************************************************************************** + ** The chosen printer, re-read with the caller's permissions and checked. + ***************************************************************************/ + static QRecord printer(RunBackendStepInput input) throws QException + { + String id = input.getValueString(PRINTER_FIELD); + if(id == null || id.isBlank()) + { + throw new QException("Choose a printer"); + } + QRecord printer = PrintingProcesses.resolvePrinter(id, null); + if(!Integer.valueOf(1).equals(printer.getValueInteger("enabled")) || !Integer.valueOf(1).equals(printer.getValueInteger("available")) + || printer.getValueString("formats") == null || !new org.json.JSONArray(printer.getValueString("formats")).toList().contains("PDF")) + { + throw new QException("Printer " + printer.getValueString("name") + " must be exposed by its device, approved, and support PDF"); + } + return (printer); + } + + + + /*************************************************************************** + ** 1 when unset; 1 to 100 otherwise (the protocol's copies range). + ***************************************************************************/ + static int copies(RunBackendStepInput input) throws QException + { + Integer copies = input.getValueInteger(COPIES_FIELD); + if(copies == null) + { + return (1); + } + if(copies < 1 || copies > 100) + { + throw new QException("Copies must be between 1 and 100"); + } + return (copies); + } + + + + /*************************************************************************** + ** Render one record (display values, visible non-binary fields) and queue it. + ***************************************************************************/ + static String submit(QTableMetaData table, QRecord selected, QRecord printer, int copies, String request) throws QException + { + Serializable primaryKey = selected.getValue(table.getPrimaryKeyField()); + GetInput get = new GetInput(); + get.setPermissionEnforcement(PermissionEnforcement.ENFORCE); + get.setTableName(table.getName()); + get.setPrimaryKey(primaryKey); + get.setShouldGenerateDisplayValues(true); + get.setShouldTranslatePossibleValues(true); + QRecord record = new GetAction().execute(get).getRecord(); + if(record == null) + { + throw new QException("Record " + primaryKey + " of " + table.getLabel() + " is not accessible"); + } + String label = record.getRecordLabel() != null ? record.getRecordLabel() : String.valueOf(primaryKey); + String tableLabel = table.getLabel() == null ? table.getName() : table.getLabel(); + String subtitle = tableLabel + " " + primaryKey + " - " + printedBy(); + byte[] bytes = PrintingRecordDocuments.pdf(tableLabel + ": " + label, subtitle, sections(table, record), children(table, record)); + return (queue(printer, tableLabel + ": " + label, bytes, copies, "record-print:" + request + ":" + table.getName() + ":" + primaryKey + ":" + printer.getValueString("id"))); + } + + + + /*************************************************************************** + ** "printed by " for subtitles. + ***************************************************************************/ + static String printedBy() + { + String user = QContext.getQSession() == null || QContext.getQSession().getUser() == null ? null : QContext.getQSession().getUser().getFullName(); + return ("printed " + Instant.now().truncatedTo(ChronoUnit.SECONDS) + (user == null ? "" : " by " + user)); + } + + + + /*************************************************************************** + ** Display text of one field of a record (display value, else raw value). + ***************************************************************************/ + static String text(QRecord record, QFieldMetaData field) + { + String display = record.getDisplayValue(field.getName()); + Serializable raw = record.getValue(field.getName()); + return (display != null ? display : raw == null ? null : String.valueOf(raw)); + } + + + + /*************************************************************************** + ** Whether a field belongs on paper: visible and not binary. + ***************************************************************************/ + static boolean printable(QFieldMetaData field) + { + return (field != null && !Boolean.TRUE.equals(field.getIsHidden()) && field.getType() != QFieldType.BLOB); + } + + + + /*************************************************************************** + ** The record's field sections in tier order (T1, T2, T3), as the record + ** view shows them; fields in no section follow under "Other fields". A + ** table without sections prints one unlabeled section of every field. + ***************************************************************************/ + static List sections(QTableMetaData table, QRecord record) + { + List out = new ArrayList<>(); + java.util.Set placed = new java.util.HashSet<>(); + List sections = new ArrayList<>(table.getSections() == null ? List.of() : table.getSections()); + sections.removeIf(section -> Boolean.TRUE.equals(section.getIsHidden()) || section.getFieldNames() == null || section.getFieldNames().isEmpty()); + sections.sort(java.util.Comparator.comparing(section -> section.getTier() == null ? 9 : section.getTier().ordinal())); + for(var section : sections) + { + Map fields = new LinkedHashMap<>(); + for(String name : section.getFieldNames()) + { + QFieldMetaData field = table.getFields().get(name); + if(printable(field) && placed.add(name)) + { + fields.put(field.getLabel() == null ? name : field.getLabel(), text(record, field)); + } + } + out.add(new PrintingRecordDocuments.Section(sections.size() == 1 ? "" : section.getLabel(), fields)); + } + Map rest = new LinkedHashMap<>(); + for(QFieldMetaData field : table.getFields().values()) + { + if(printable(field) && !placed.contains(field.getName())) + { + rest.put(field.getLabel() == null ? field.getName() : field.getLabel(), text(record, field)); + } + } + if(!rest.isEmpty()) + { + out.add(new PrintingRecordDocuments.Section(out.isEmpty() ? "" : "Other fields", rest)); + } + return (out); + } + + + + /*************************************************************************** + ** Each association of the table: its label, how many child rows, and the + ** first rows with up to five visible columns. Children the user may not + ** read, or that fail to load, are left out rather than failing the print. + ***************************************************************************/ + static List children(QTableMetaData table, QRecord record) + { + List out = new ArrayList<>(); + for(var association : table.getAssociations() == null ? List.of() : table.getAssociations()) + { + try + { + var join = QContext.getQInstance().getJoin(association.getJoinName()); + QTableMetaData child = QContext.getQInstance().getTable(association.getAssociatedTableName()); + if(join == null || child == null || join.getJoinOns() == null || join.getJoinOns().isEmpty()) + { + continue; + } + boolean forward = table.getName().equals(join.getLeftTable()); + QQueryFilter filter = new QQueryFilter(); + for(var on : join.getJoinOns()) + { + Serializable value = record.getValue(forward ? on.getLeftField() : on.getRightField()); + filter.withCriteria(new QFilterCriteria(forward ? on.getRightField() : on.getLeftField(), QCriteriaOperator.EQUALS, value)); + } + var count = new com.kingsrook.qqq.backend.core.model.actions.tables.count.CountInput(); + count.setTableName(child.getName()); + count.setFilter(filter); + count.setPermissionEnforcement(PermissionEnforcement.ENFORCE); + Integer total = new com.kingsrook.qqq.backend.core.actions.tables.CountAction().execute(count).getCount(); + var query = new com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryInput(); + query.setTableName(child.getName()); + query.setFilter(filter.clone().withLimit(CHILD_ROWS)); + query.setPermissionEnforcement(PermissionEnforcement.ENFORCE); + query.setShouldGenerateDisplayValues(true); + query.setShouldTranslatePossibleValues(true); + List rows = new com.kingsrook.qqq.backend.core.actions.tables.QueryAction().execute(query).getRecords(); + java.util.Set joinFields = new java.util.HashSet<>(); + join.getJoinOns().forEach(on -> joinFields.add(forward ? on.getRightField() : on.getLeftField())); + List columns = child.getFields().values().stream() + .filter(field -> printable(field) && !joinFields.contains(field.getName())).limit(5).toList(); + List> cells = new ArrayList<>(); + for(QRecord row : rows) + { + List line = new ArrayList<>(); + columns.forEach(field -> line.add(text(row, field))); + cells.add(line); + } + String label = association.getName().equals(child.getName()) && child.getLabel() != null ? child.getLabel() : com.kingsrook.qqq.backend.core.instances.QInstanceEnricher.nameToLabel(association.getName()); + out.add(new PrintingRecordDocuments.ChildList(label, total == null ? rows.size() : total, + columns.stream().map(field -> field.getLabel() == null ? field.getName() : field.getLabel()).toList(), cells)); + } + catch(Exception exception) + { + // a child list the user may not read (or that cannot load) is left out of the sheet + } + } + return (out); + } + + + + /*************************************************************************** + ** Queue one PDF on a printer through the durable queue; returns the job id. + ***************************************************************************/ + static String queue(QRecord printer, String title, byte[] bytes, int copies, String idempotencyKey) throws QException + { + try + { + JSONObject job = PrintingProcesses.currentService().submit(new JSONObject() + .put("deviceId", printer.getValueString("device_id")).put("printerId", printer.getValueString("printer_id")) + .put("title", PrintingRecordDocuments.truncate(title, 200)).put("format", "PDF") + .put("contentBase64", Base64.getEncoder().encodeToString(bytes)) + .put("idempotencyKey", idempotencyKey) + .put("options", new JSONObject().put("copies", copies).put("scale", "FIT"))); + return (job.getString("jobId")); + } + catch(java.sql.SQLException | PrintingException exception) + { + throw new QException("Could not queue the print job: " + exception.getMessage(), exception); + } + } + + + + /*************************************************************************** + ** One request identity per process run, so a replayed load does not print twice. + ***************************************************************************/ + public static class Prepare implements BackendStep + { + /*************************************************************************** + ** Require printing access before any form is shown. + ***************************************************************************/ + @Override + public void run(RunBackendStepInput input, RunBackendStepOutput output) throws QException + { + new PrintingAdminPermission().checkPermissionsThrowing(input, null); + PrintingProcesses.currentService(); + String request = input.getValueString(REQUEST_ID); + output.addValue(REQUEST_ID, request == null || request.isBlank() ? UUID.randomUUID().toString() : request); + PrintingProcesses.keepSelection(input, output); + } + } + + + + /*************************************************************************** + ** Review: the printer is still usable; the selected records pass through. + ***************************************************************************/ + public static class Transform extends AbstractTransformStep implements ProcessSummaryProviderInterface + { + private final ProcessSummaryLine ready = new ProcessSummaryLine(Status.OK, 0, null) + .withSingularFutureMessage("record will be printed").withPluralFutureMessage("records will be printed"); + + + + /*************************************************************************** + ** Check the printer and copies once per page; keep the records. + ***************************************************************************/ + @Override + public void runOnePage(RunBackendStepInput input, RunBackendStepOutput output) throws QException + { + new PrintingAdminPermission().checkPermissionsThrowing(input, null); + printer(input); + copies(input); + QTableMetaData table = QContext.getQInstance().getTable(input.getValueString(StreamedETLWithFrontendProcess.FIELD_SOURCE_TABLE)); + for(QRecord record : input.getRecords()) + { + ready.incrementCountAndAddPrimaryKey(record.getValue(table.getPrimaryKeyField())); + output.getRecords().add(record); + } + } + + + + /*************************************************************************** + ** Standard review summary. + ***************************************************************************/ + @Override + public ArrayList getProcessSummary(RunBackendStepOutput output, boolean isForResultScreen) + { + return (new ArrayList<>(List.of(ready))); + } + } + + + + /*************************************************************************** + ** Execute: render and queue each record; report the job IDs. + ***************************************************************************/ + public static class Load extends AbstractLoadStep implements ProcessSummaryProviderInterface + { + private final ProcessSummaryLine done = new ProcessSummaryLine(Status.OK, 0, null) + .withSingularPastMessage("record was sent to the printer").withPluralPastMessage("records were sent to the printer"); + private final List jobIds = new ArrayList<>(); + + + + /*************************************************************************** + ** Resolve the printer again (access may have changed since review). + ***************************************************************************/ + @Override + public void runOnePage(RunBackendStepInput input, RunBackendStepOutput output) throws QException + { + new PrintingAdminPermission().checkPermissionsThrowing(input, null); + QRecord printer = printer(input); + int copies = copies(input); + String request = input.getValueString(REQUEST_ID); + if(request == null || request.isBlank()) + { + throw new QException("Restart Print to obtain a safe request identity"); + } + QTableMetaData table = QContext.getQInstance().getTable(input.getValueString(StreamedETLWithFrontendProcess.FIELD_SOURCE_TABLE)); + for(QRecord record : input.getRecords()) + { + jobIds.add(submit(table, record, printer, copies, request)); + done.incrementCountAndAddPrimaryKey(record.getValue(table.getPrimaryKeyField())); + output.getRecords().add(record); + } + output.addValue(JOB_IDS, String.join(",", jobIds)); + } + + + + /*************************************************************************** + ** Result summary: what was sent, and the job IDs to follow. + ***************************************************************************/ + @Override + public ArrayList getProcessSummary(RunBackendStepOutput output, boolean isForResultScreen) + { + ArrayList lines = new ArrayList<>(List.of(done)); + if(!jobIds.isEmpty()) + { + lines.add(new ProcessSummaryLine(Status.INFO, null, "Print job" + (jobIds.size() == 1 ? " " : "s ") + String.join(", ", jobIds) + " queued; follow them in Print jobs.")); + } + return (lines); + } + } +} diff --git a/src/main/java/com/kingsrook/qbits/printing/PrintingRetentionPolicy.java b/src/main/java/com/kingsrook/qbits/printing/PrintingRetentionPolicy.java new file mode 100644 index 0000000..0750e50 --- /dev/null +++ b/src/main/java/com/kingsrook/qbits/printing/PrintingRetentionPolicy.java @@ -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)); + } +} + diff --git a/src/main/java/com/kingsrook/qbits/printing/PrintingRetentionProcesses.java b/src/main/java/com/kingsrook/qbits/printing/PrintingRetentionProcesses.java new file mode 100644 index 0000000..785af57 --- /dev/null +++ b/src/main/java/com/kingsrook/qbits/printing/PrintingRetentionProcesses.java @@ -0,0 +1,234 @@ +/* + * 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("batchSize", QFieldType.INTEGER).withLabel("Maximum documents per cleanup run (1–200)").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"); + Integer batchSize = input.getValueInteger("batchSize"); + if(days == null || enabled == null || batchSize == null) + { + throw new QException("Specify retention days and whether cleanup is enabled"); + } + service.saveRetentionSettings(days, enabled, batchSize); + 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("batchSize", settings.getInt("batchSize")); + 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"); + } +} diff --git a/src/main/java/com/kingsrook/qbits/printing/PrintingRoutes.java b/src/main/java/com/kingsrook/qbits/printing/PrintingRoutes.java index d206eea..485390b 100644 --- a/src/main/java/com/kingsrook/qbits/printing/PrintingRoutes.java +++ b/src/main/java/com/kingsrook/qbits/printing/PrintingRoutes.java @@ -38,6 +38,13 @@ public class PrintingRoutes implements QJavalinRouteProviderInterface public static final String BASE = "/printing/v1"; private final PrintingService service; private final Predicate 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 administrator) + { + this(service, administrator, LegacyEnrollment.DISABLED); + } + + + /** Existing unbound devices may migrate; new legacy enrollment is an explicit host policy. */ + public PrintingRoutes(PrintingService service, Predicate 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, () -> { @@ -172,9 +224,12 @@ public class PrintingRoutes implements QJavalinRouteProviderInterface /*************************************************************************** ** Parse bounded protocol JSON; the server also configures request limits. ***************************************************************************/ - private static JSONObject body(Context context) + private JSONObject body(Context context) throws java.sql.SQLException { - if(context.bodyAsBytes().length > 29 * 1024 * 1024) + PrintingRealtimePolicy policy = service.realtimePolicy(); + long maximum = context.path().equals(BASE + "/admin/jobs") + ? ((Math.max(policy.get("maxPdfBytes"), policy.get("maxZplBytes")) + 2) / 3) * 4 + 65536 : 2097152; + if((context.req().getContentLengthLong() > maximum) || context.bodyAsBytes().length > maximum) { throw new PrintingException(413, "Request is too large"); } @@ -184,8 +239,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)); diff --git a/src/main/java/com/kingsrook/qbits/printing/PrintingService.java b/src/main/java/com/kingsrook/qbits/printing/PrintingService.java index 2620229..9543efd 100644 --- a/src/main/java/com/kingsrook/qbits/printing/PrintingService.java +++ b/src/main/java/com/kingsrook/qbits/printing/PrintingService.java @@ -46,10 +46,212 @@ import org.json.JSONObject; *******************************************************************************/ public class PrintingService { - private static final int MAX_CONTENT_BYTES = 20 * 1024 * 1024; + static final String CANCELED_BEFORE_DISPATCH = "Canceled by operator before dispatch"; private static final String JOB_COLUMNS = "id, tenant_id, device_id, printer_id, title, format, content_hash, content_length, options_json, idempotency_key, created_at, status, message, spooler_job_id, printer_row_id"; private final DataSource dataSource; private final String tenantId; + private PrintingDocumentStorage documentStorage; + private PrintingAdmissionLimits admissionLimits = PrintingAdmissionLimits.defaults(); + private String storageTableName; + private PrintingRetentionPolicy defaultRetentionPolicy = new PrintingRetentionPolicy(true, 365, 200); + private PrintingRealtimeBus realtimeBus = new PrintingRealtimeBus(); + private RealtimeClaimGuard realtimeClaimGuard = device -> + { + throw new PrintingException(503, "The host has not registered the realtime printing route provider"); + }; + + + /** Native claims require a synchronized current-user channel, not a polling fallback. */ + @FunctionalInterface + public interface RealtimeClaimGuard + { + /** Check this connection's authoritative applied state. */ + void requireReady(String device) throws SQLException; + } + + + /** Route-provider lifecycle owns the readiness guard. */ + void withRealtimeClaimGuard(RealtimeClaimGuard guard) + { + realtimeClaimGuard = guard; + } + + + /** Enforce readiness on native HTTP claims before selecting any job. */ + public void requireRealtimeReady(String device) throws SQLException + { + realtimeClaimGuard.requireReady(device); + } + + + /** Persist application observations before the WebSocket acknowledgment is emitted. */ + void applyRealtimeState(String device, JSONObject control, long settings) throws SQLException + { + if(settings > getRealtimeSettings().getLong("revision")) + { + throw new PrintingException(409, "Realtime settings changed before acknowledgment"); + } + deviceControlPoll(device, control); + try(Connection connection = dataSource.getConnection()) + { + if(update(connection, "UPDATE printing_device SET realtime_applied_revision=CASE WHEN realtime_applied_revision=?)", settings, settings, tenantId, device, tenantId, settings) != 1) + { + throw new PrintingException(409, "Realtime settings changed before acknowledgment"); + } + } + } + + + /** Authenticated transport contact does not imply applied controls or normal device traffic. */ + void realtimeContact(String device) throws SQLException + { + try(Connection connection = dataSource.getConnection()) + { + requireDevice(connection, device); + update(connection, "UPDATE printing_device SET control_last_poll_at=? WHERE tenant_id=? AND id=? AND enabled=1", Instant.now().toString(), tenantId, device); + } + } + + + /** A host may share this event bus across services using the same database. */ + public PrintingService withRealtimeBus(PrintingRealtimeBus bus) + { + realtimeBus = java.util.Objects.requireNonNull(bus); + return (this); + } + + + /** Instance-owned notifications never contain credentials or document bytes. */ + public PrintingRealtimeBus getRealtimeBus() + { + return (realtimeBus); + } + + + /** Complete persisted tenant settings; defaults apply until the first administrator edit. */ + public JSONObject getRealtimeSettings() throws SQLException + { + ensureRetentionSettings(); + try(Connection connection = dataSource.getConnection()) + { + JSONObject row = query(connection, "SELECT realtime_policy_json, realtime_revision FROM printing_settings WHERE tenant_id=?", tenantId).getFirst(); + PrintingRealtimePolicy policy = row.isNull("realtime_policy_json") ? PrintingRealtimePolicy.defaults() + : PrintingRealtimePolicy.fromJson(new JSONObject(row.getString("realtime_policy_json"))); + return (policy.toJson(row.getLong("realtime_revision"))); + } + } + + + /** The native adapter authorizes the administrator before this atomic update. */ + public JSONObject saveRealtimeSettings(JSONObject request) throws SQLException + { + PrintingRealtimePolicy policy = PrintingRealtimePolicy.fromJson(request); + ensureRetentionSettings(); + JSONObject result; + try(Connection connection = dataSource.getConnection()) + { + connection.setAutoCommit(false); + try + { + long revision = query(connection, "SELECT realtime_revision FROM printing_settings WHERE tenant_id=? FOR UPDATE", tenantId).getFirst().getLong("realtime_revision") + 1; + if(revision < 1 || revision > 9007199254740991L) + { + throw new PrintingException(409, "Realtime settings revision capacity is exhausted"); + } + update(connection, "UPDATE printing_settings SET realtime_policy_json=?, realtime_revision=? WHERE tenant_id=?", request.toString(), revision, tenantId); + connection.commit(); + result = policy.toJson(revision); + } + catch(Exception exception) + { + connection.rollback(); + throw exception; + } + } + realtimeBus.publish(tenantId, null); + return (result); + } + + + /** Resolve immutable validated policy values for one request. */ + public PrintingRealtimePolicy realtimePolicy() throws SQLException + { + JSONObject settings = getRealtimeSettings(); + settings.remove("revision"); + return (PrintingRealtimePolicy.fromJson(settings)); + } + + + + /*************************************************************************** + ** Deployment-owned limits apply equally to native, HTTP and outbox callers. + ***************************************************************************/ + public PrintingService withAdmissionLimits(PrintingAdmissionLimits limits) + { + admissionLimits = java.util.Objects.requireNonNull(limits); + return (this); + } + + + /** Native tenant administrator admission settings. */ + public JSONObject getAdmissionSettings() throws SQLException + { + ensureRetentionSettings(); + return (new PrintingAdmissionSettings(dataSource, tenantId, admissionLimits).get()); + } + + + /** Save validated tenant overrides without changing retained job receipts. */ + public JSONObject saveAdmissionSettings(JSONObject request) throws SQLException + { + ensureRetentionSettings(); + JSONObject result = new PrintingAdmissionSettings(dataSource, tenantId, admissionLimits).save(request); + realtimeBus.publish(tenantId, null); + return (result); + } + + + + /*************************************************************************** + ** Bind a host-owned storage table before exposing this service to requests. + ***************************************************************************/ + public void configureStorage(com.kingsrook.qqq.backend.core.model.metadata.QInstance instance, String table) throws com.kingsrook.qqq.backend.core.exceptions.QException + { + try + { + configureStorage(new PrintingDocumentStorage(instance, tenantId), table); + } + catch(IllegalArgumentException exception) + { + throw new com.kingsrook.qqq.backend.core.exceptions.QException(exception.getMessage(), exception); + } + } + + + + /*************************************************************************** + ** Package-scoped adapter seam supports storage failure tests without S3. + ***************************************************************************/ + void configureStorage(PrintingDocumentStorage storage, String table) + { + if(table != null) + { + storage.binding(table); + } + documentStorage = storage; + storageTableName = table; + } + + + + /*************************************************************************** + ** Defaults are host-owned; a persisted administrator setting takes priority. + ***************************************************************************/ + public PrintingService withRetentionPolicy(PrintingRetentionPolicy policy) + { + defaultRetentionPolicy = java.util.Objects.requireNonNull(policy); + return (this); + } @@ -71,17 +273,35 @@ public class PrintingService { String[] statements = { "CREATE TABLE IF NOT EXISTS printing_enrollment (code_hash VARCHAR(64) PRIMARY KEY, tenant_id VARCHAR(200) NOT NULL, facility_id VARCHAR(200) NOT NULL, device_name VARCHAR(200) NOT NULL, expires_at VARCHAR(40) NOT NULL)", + "ALTER TABLE printing_enrollment ADD COLUMN IF NOT EXISTS consumed INTEGER DEFAULT 0 NOT NULL", "CREATE TABLE IF NOT EXISTS printing_device (id VARCHAR(36) PRIMARY KEY, tenant_id VARCHAR(200) NOT NULL, facility_id VARCHAR(200) NOT NULL, name VARCHAR(200) NOT NULL, agent_version VARCHAR(100) NOT NULL, token_hash VARCHAR(64) UNIQUE NOT NULL, last_seen_at VARCHAR(40) NOT NULL, enabled INTEGER NOT NULL)", "CREATE TABLE IF NOT EXISTS printing_printer (id VARCHAR(36) PRIMARY KEY, tenant_id VARCHAR(200) NOT NULL, device_id VARCHAR(36) NOT NULL REFERENCES printing_device(id), printer_id VARCHAR(200) NOT NULL, name VARCHAR(300) NOT NULL, driver_name VARCHAR(300), port_name VARCHAR(300), status VARCHAR(40) NOT NULL, formats VARCHAR(100) NOT NULL, enabled INTEGER NOT NULL, last_seen_at VARCHAR(40) NOT NULL, UNIQUE(device_id, printer_id))", "ALTER TABLE printing_printer ADD COLUMN IF NOT EXISTS available INTEGER DEFAULT 0 NOT NULL", "CREATE TABLE IF NOT EXISTS printing_job (id VARCHAR(36) PRIMARY KEY, tenant_id VARCHAR(200) NOT NULL, device_id VARCHAR(36) NOT NULL REFERENCES printing_device(id), printer_id VARCHAR(200) NOT NULL, title VARCHAR(300) NOT NULL, format VARCHAR(10) NOT NULL, content_hash VARCHAR(64) NOT NULL, content_base64 TEXT NOT NULL, content_length INTEGER NOT NULL, options_json VARCHAR(2000) NOT NULL, idempotency_key VARCHAR(300) NOT NULL, created_at VARCHAR(40) NOT NULL, status VARCHAR(40) NOT NULL, message VARCHAR(2000), spooler_job_id VARCHAR(100), UNIQUE(tenant_id, idempotency_key))", "CREATE TABLE IF NOT EXISTS printing_event (id VARCHAR(100) PRIMARY KEY, job_id VARCHAR(36) NOT NULL REFERENCES printing_job(id), status VARCHAR(40) NOT NULL, event_json VARCHAR(4000) NOT NULL, created_at VARCHAR(40) NOT NULL)", "ALTER TABLE printing_job ADD COLUMN IF NOT EXISTS printer_row_id VARCHAR(36)", + "ALTER TABLE printing_job ALTER COLUMN content_base64 DROP NOT NULL", + "ALTER TABLE printing_job ADD COLUMN IF NOT EXISTS content_available INTEGER DEFAULT 1 NOT NULL", + "ALTER TABLE printing_job ADD COLUMN IF NOT EXISTS completed_at VARCHAR(40)", + "UPDATE printing_job SET completed_at=(SELECT MAX(e.created_at) FROM printing_event e WHERE e.job_id=printing_job.id AND e.status IN ('SPOOLED','SPOOLER_COMPLETED')) WHERE completed_at IS NULL AND status IN ('SPOOLED','SPOOLER_COMPLETED')", + "ALTER TABLE printing_job ADD COLUMN IF NOT EXISTS content_storage_table VARCHAR(200)", + "ALTER TABLE printing_job ADD COLUMN IF NOT EXISTS content_reference VARCHAR(500)", + "ALTER TABLE printing_job ADD COLUMN IF NOT EXISTS content_binding VARCHAR(64)", + "CREATE TABLE IF NOT EXISTS printing_settings (tenant_id VARCHAR(200) PRIMARY KEY, retention_days INTEGER NOT NULL, retention_enabled INTEGER NOT NULL, last_run_at VARCHAR(40), last_run_count INTEGER, last_run_error VARCHAR(500))", + "ALTER TABLE printing_settings ADD COLUMN IF NOT EXISTS lease_token VARCHAR(36)", + "ALTER TABLE printing_settings ADD COLUMN IF NOT EXISTS lease_expires_at VARCHAR(40)", + "ALTER TABLE printing_settings ADD COLUMN IF NOT EXISTS realtime_policy_json VARCHAR(8000)", + "ALTER TABLE printing_settings ADD COLUMN IF NOT EXISTS realtime_revision BIGINT DEFAULT 0 NOT NULL", + "ALTER TABLE printing_settings ADD COLUMN IF NOT EXISTS admission_policy_json VARCHAR(8000)", + "ALTER TABLE printing_settings ADD COLUMN IF NOT EXISTS retention_batch_size INTEGER", + "CREATE TABLE IF NOT EXISTS printing_document_orphan (id VARCHAR(36) PRIMARY KEY, tenant_id VARCHAR(200) NOT NULL, storage_table VARCHAR(200) NOT NULL, reference VARCHAR(500) NOT NULL, binding VARCHAR(64) NOT NULL, created_at VARCHAR(40) NOT NULL)", + "CREATE INDEX IF NOT EXISTS printing_orphan_tenant_idx ON printing_document_orphan(tenant_id, created_at, id)", "UPDATE printing_job SET printer_row_id=(SELECT p.id FROM printing_printer p WHERE p.device_id=printing_job.device_id AND p.printer_id=printing_job.printer_id AND p.tenant_id=printing_job.tenant_id) WHERE printer_row_id IS NULL", "ALTER TABLE printing_device ADD COLUMN IF NOT EXISTS computer_name VARCHAR(1024)", "ALTER TABLE printing_device ADD COLUMN IF NOT EXISTS display_name VARCHAR(512)", "ALTER TABLE printing_device ADD COLUMN IF NOT EXISTS description VARCHAR(4096)", "ALTER TABLE printing_device ADD COLUMN IF NOT EXISTS location VARCHAR(512)", + "ALTER TABLE printing_device ADD COLUMN IF NOT EXISTS realtime_applied_revision BIGINT DEFAULT -1 NOT NULL", "ALTER TABLE printing_printer ADD COLUMN IF NOT EXISTS queue_name VARCHAR(1024)", "ALTER TABLE printing_printer ADD COLUMN IF NOT EXISTS display_name VARCHAR(512)", "ALTER TABLE printing_printer ADD COLUMN IF NOT EXISTS description VARCHAR(4096)", @@ -90,6 +310,7 @@ public class PrintingService "UPDATE printing_printer SET queue_name=name WHERE queue_name IS NULL", "CREATE INDEX IF NOT EXISTS printing_job_dispatch_idx ON printing_job(tenant_id, device_id, status, created_at, id)", "CREATE INDEX IF NOT EXISTS printing_job_history_idx ON printing_job(tenant_id, created_at, id)", + "CREATE INDEX IF NOT EXISTS printing_job_retention_completed_idx ON printing_job(tenant_id, content_available, status, completed_at, id)", "CREATE INDEX IF NOT EXISTS printing_event_job_idx ON printing_event(job_id)", "CREATE INDEX IF NOT EXISTS printing_device_tenant_idx ON printing_device(tenant_id, last_seen_at)", "CREATE INDEX IF NOT EXISTS printing_printer_tenant_idx ON printing_printer(tenant_id, status)" @@ -104,12 +325,19 @@ public class PrintingService statement.execute(); } } + PrintingAdmission.initialize(connection, tenantId); + PrintingDeviceControls.initialize(connection); + update(connection, "ALTER TABLE printing_device ADD COLUMN IF NOT EXISTS bound_user_id VARCHAR(200)"); widenColumn(connection, "printing_device", "name", 1024); widenColumn(connection, "printing_enrollment", "device_name", 1024); widenColumn(connection, "printing_printer", "name", 1024); widenColumn(connection, "printing_printer", "driver_name", 1024); widenColumn(connection, "printing_printer", "port_name", 1024); widenColumn(connection, "printing_job", "title", 1024); + widenColumn(connection, "printing_job", "message", 2048); + widenColumn(connection, "printing_job", "spooler_job_id", 128); + widenColumn(connection, "printing_event", "id", 128); + widenColumn(connection, "printing_event", "event_json", 16000); } } @@ -143,8 +371,85 @@ public class PrintingService /*************************************************************************** - ** The immutable tenant scope used by host authorization and native actions. + ** Apply one audited action after the adapter authorizes the current actor. ***************************************************************************/ + public JSONObject deviceAction(String deviceId, JSONObject request, String actor) throws SQLException + { + JSONObject result = new PrintingDeviceControls(dataSource, tenantId).action(deviceId, request, actor); + realtimeBus.publish(tenantId, deviceId); + return (result); + } + + + /** Native authorization supplies the exact reviewed queue identity set, never a predicate executed inside SQL locks. */ + JSONObject deviceAction(String deviceId, JSONObject request, String actor, Set authorizedQueue) throws SQLException + { + JSONObject result = new PrintingDeviceControls(dataSource, tenantId).action(deviceId, request, actor, authorizedQueue); + realtimeBus.publish(tenantId, deviceId); + return (result); + } + + + /** Resolve a retained action receipt without treating new queue contents as part of a replay. */ + String existingDeviceAction(String deviceId, String requestId) throws SQLException + { + try(Connection connection = dataSource.getConnection()) + { + List rows = query(connection, "SELECT id FROM printing_device_command WHERE tenant_id=? AND device_id=? AND request_id=?", tenantId, deviceId, requestId); + return (rows.isEmpty() ? null : rows.getFirst().getString("id")); + } + } + + + /** Bounded identifiers permit native row authorization before bulk queue cancellation. */ + Set queuedJobIdsForControl(String deviceId) throws SQLException + { + try(Connection connection = dataSource.getConnection()) + { + requireDevice(connection, deviceId); + Set ids = 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", tenantId, deviceId)) + { + ids.add(row.getString("id")); + } + if(ids.size() > 10000) + { + throw new PrintingException(429, "The queue exceeds the bounded native review limit"); + } + return (ids); + } + } + + + /** Independently poll desired state and pending commands using device authentication. */ + public JSONObject deviceControlPoll(String deviceId, JSONObject request) throws SQLException + { + return (new PrintingDeviceControls(dataSource, tenantId).poll(deviceId, request)); + } + + + /** Persist one immutable device observation without inferring physical output. */ + public JSONObject deviceControlReceipt(String deviceId, String commandId, JSONObject receipt) throws SQLException + { + return (new PrintingDeviceControls(dataSource, tenantId).receipt(deviceId, commandId, receipt)); + } + + + /** Tenant/device scoped history remains visible after credential revocation. */ + public JSONObject deviceCommandsPage(String deviceId, int limit, String before) throws SQLException + { + return (new PrintingDeviceControls(dataSource, tenantId).page(deviceId, limit, before)); + } + + + /** Read the exact durable receipt for a native or HTTP management action. */ + public JSONObject getDeviceCommand(String deviceId, String commandId) throws SQLException + { + return (new PrintingDeviceControls(dataSource, tenantId).get(deviceId, commandId)); + } + + + /** The immutable tenant scope used by host authorization and native actions. */ public String getTenantId() { return (tenantId); @@ -192,11 +497,62 @@ public class PrintingService ***************************************************************************/ public JSONObject createEnrollment(String facilityId, String deviceName) throws SQLException { - String code = secret(); - String expires = Instant.now().plusSeconds(900).toString(); + return (createEnrollment(facilityId, deviceName, secret(), Instant.now().plusSeconds(900).toString())); + } + + + + /*************************************************************************** + ** Native processes persist a prepared random code before the insert step. + ** Replay reuses only an identical, unexpired, unconsumed hashed receipt. + ***************************************************************************/ + JSONObject createEnrollment(String facilityId, String deviceName, String code, String expires) throws SQLException + { + required(facilityId, "facilityId"); + required(deviceName, "deviceName"); + try + { + if(code == null || !code.matches("[A-Za-z0-9_-]{43}") || Base64.getUrlDecoder().decode(code).length != 32 + || expires == null || !Instant.parse(expires).isAfter(Instant.now()) || Instant.parse(expires).isAfter(Instant.now().plusSeconds(901))) + { + throw new IllegalArgumentException("Invalid prepared enrollment"); + } + } + catch(IllegalArgumentException | java.time.format.DateTimeParseException exception) + { + throw new PrintingException(400, "Enrollment request is invalid or expired; restart enrollment"); + } try(Connection connection = dataSource.getConnection()) { - update(connection, "INSERT INTO printing_enrollment VALUES (?, ?, ?, ?, ?)", hash(code), tenantId, required(facilityId, "facilityId"), required(deviceName, "deviceName"), expires); + List previous = query(connection, "SELECT * FROM printing_enrollment WHERE code_hash=?", hash(code)); + if(previous.isEmpty()) + { + try + { + update(connection, "INSERT INTO printing_enrollment (code_hash, tenant_id, facility_id, device_name, expires_at) VALUES (?, ?, ?, ?, ?)", hash(code), tenantId, facilityId, deviceName, expires); + } + catch(SQLException exception) + { + if(!"23505".equals(exception.getSQLState())) + { + throw exception; + } + previous = query(connection, "SELECT * FROM printing_enrollment WHERE code_hash=?", hash(code)); + if(previous.isEmpty()) + { + throw exception; + } + } + } + if(!previous.isEmpty()) + { + JSONObject old = previous.getFirst(); + if(old.getInt("consumed") != 0 || !tenantId.equals(old.getString("tenant_id")) || !facilityId.equals(old.getString("facility_id")) + || !deviceName.equals(old.getString("device_name")) || !expires.equals(old.getString("expires_at"))) + { + throw new PrintingException(409, "Enrollment request was already consumed or changed; restart enrollment"); + } + } } return (new JSONObject().put("enrollmentCode", code).put("expiresAt", expires)); } @@ -208,6 +564,32 @@ public class PrintingService ***************************************************************************/ public JSONObject enroll(JSONObject request) throws SQLException { + return (enrollForUser(request, null)); + } + + + /** Native enrollment checks facility visibility before consuming the immutable enrollment code. */ + String enrollmentFacility(String code) throws SQLException + { + try(Connection connection = dataSource.getConnection()) + { + List rows = query(connection, "SELECT facility_id FROM printing_enrollment WHERE tenant_id=? AND code_hash=? AND consumed=0 AND expires_at>?", tenantId, hash(required(code, "enrollmentCode")), Instant.now().toString()); + if(rows.isEmpty()) + { + throw new PrintingException(401, "Enrollment code is invalid or expired"); + } + return (rows.getFirst().getString("facility_id")); + } + } + + + /** Native enrollment binds the core-authenticated principal in the credential transaction. */ + public JSONObject enrollForUser(JSONObject request, String principalId) throws SQLException + { + if(principalId != null && (principalId.isBlank() || principalId.length() > 200)) + { + throw new PrintingException(403, "Invalid authenticated principal"); + } String codeHash = hash(required(request.optString("enrollmentCode"), "enrollmentCode")); try(Connection connection = dataSource.getConnection()) { @@ -215,7 +597,7 @@ public class PrintingService try { List codes = query(connection, "SELECT * FROM printing_enrollment WHERE code_hash=? AND tenant_id=? FOR UPDATE", codeHash, tenantId); - if(codes.isEmpty() || Instant.parse(codes.getFirst().getString("expires_at")).isBefore(Instant.now())) + if(codes.isEmpty() || codes.getFirst().getInt("consumed") != 0 || !Instant.parse(codes.getFirst().getString("expires_at")).isAfter(Instant.now())) { throw new PrintingException(401, "Enrollment code is invalid or expired"); } @@ -223,8 +605,8 @@ public class PrintingService String id = UUID.randomUUID().toString(); String token = secret(); String computerName = required(request.optString("deviceName"), "deviceName"); - update(connection, "INSERT INTO printing_device (id, tenant_id, facility_id, name, agent_version, token_hash, last_seen_at, enabled, computer_name) VALUES (?, ?, ?, ?, ?, ?, ?, 1, ?)", id, tenantId, code.getString("facility_id"), computerName, required(request.optString("agentVersion"), "agentVersion"), hash(token), Instant.now().toString(), computerName); - update(connection, "DELETE FROM printing_enrollment WHERE code_hash=?", codeHash); + update(connection, "INSERT INTO printing_device (id, tenant_id, facility_id, name, agent_version, token_hash, last_seen_at, enabled, computer_name, bound_user_id) VALUES (?, ?, ?, ?, ?, ?, ?, 1, ?, ?)", id, tenantId, code.getString("facility_id"), computerName, required(request.optString("agentVersion"), "agentVersion"), hash(token), Instant.now().toString(), computerName, principalId); + update(connection, "UPDATE printing_enrollment SET consumed=1 WHERE code_hash=?", codeHash); connection.commit(); return (new JSONObject().put("protocolVersion", 1).put("deviceId", id).put("deviceToken", token).put("pollIntervalSeconds", 5)); } @@ -239,13 +621,13 @@ public class PrintingService /*************************************************************************** - ** Resolve an active device credential without exposing its verifier. + ** Legacy primary credentials are valid only until native user binding. ***************************************************************************/ public String authenticate(String token) throws SQLException { try(Connection connection = dataSource.getConnection()) { - List devices = query(connection, "SELECT id FROM printing_device WHERE tenant_id=? AND token_hash=? AND enabled=1", tenantId, hash(token == null ? "" : token)); + List devices = query(connection, "SELECT id FROM printing_device WHERE tenant_id=? AND token_hash=? AND enabled=1 AND revoked_at IS NULL AND bound_user_id IS NULL", tenantId, hash(token == null ? "" : token)); if(devices.isEmpty()) { throw new PrintingException(401, "Invalid device credential"); @@ -255,6 +637,43 @@ public class PrintingService } + /** Secondary device proof never replaces the caller's native QQQ authentication and row permission. */ + public void authorizeAgent(String deviceId, String token, String principalId, boolean bind) throws SQLException + { + if(deviceId == null || token == null || token.length() > 128 || principalId == null || principalId.isBlank() || principalId.length() > 200) + { + throw new PrintingException(403, "User or device is not authorized"); + } + try(Connection connection = dataSource.getConnection()) + { + connection.setAutoCommit(false); + try + { + List rows = query(connection, "SELECT token_hash,bound_user_id FROM printing_device WHERE tenant_id=? AND id=? AND enabled=1 AND revoked_at IS NULL FOR UPDATE", tenantId, deviceId); + if(rows.isEmpty() || !MessageDigest.isEqual(rows.getFirst().getString("token_hash").getBytes(StandardCharsets.UTF_8), hash(token).getBytes(StandardCharsets.UTF_8))) + { + throw new PrintingException(403, "User or device is not authorized"); + } + String owner = rows.getFirst().optString("bound_user_id", null); + if(owner == null && bind) + { + update(connection, "UPDATE printing_device SET bound_user_id=? WHERE tenant_id=? AND id=? AND bound_user_id IS NULL", principalId, tenantId, deviceId); + } + else if(!principalId.equals(owner)) + { + throw new PrintingException(403, "User or device is not authorized"); + } + connection.commit(); + } + catch(Exception exception) + { + connection.rollback(); + throw exception; + } + } + } + + /*************************************************************************** ** Record reachability; queue/hardware health remains a separate observation. @@ -267,6 +686,8 @@ public class PrintingService connection.setAutoCommit(false); try { + requireDevice(connection, deviceId); + query(connection, "SELECT id FROM printing_device WHERE id=? FOR UPDATE", deviceId); requireDevice(connection, deviceId); update(connection, "UPDATE printing_device SET last_seen_at=?, agent_version=? WHERE id=?", now, required(request.optString("agentVersion"), "agentVersion"), deviceId); JSONObject profile = request.optJSONObject("profile"); @@ -295,6 +716,13 @@ public class PrintingService ** Replace observed inventory while retaining administrator approval. ***************************************************************************/ public void inventory(String deviceId, JSONArray printers) throws SQLException + { + inventory(deviceId, printers, null); + } + + + /** Native inventory changes exactly the existing row set authorized before opening this transaction. */ + void inventory(String deviceId, JSONArray printers, Set authorizedRows) throws SQLException { if(printers.length() > 200) { @@ -302,11 +730,34 @@ public class PrintingService } try(Connection connection = dataSource.getConnection()) { + requireDevice(connection, deviceId); + PrintingAdmission.initializeTenant(connection, tenantId); connection.setAutoCommit(false); try { + PrintingAdmission.lock(connection, tenantId); requireDevice(connection, deviceId); - update(connection, "UPDATE printing_printer SET status='UNKNOWN', available=0 WHERE device_id=?", deviceId); + query(connection, "SELECT id FROM printing_device WHERE id=? FOR UPDATE", deviceId); + requireDevice(connection, deviceId); + if(authorizedRows != null) + { + Set currentRows = new java.util.HashSet<>(); + for(JSONObject row : query(connection, "SELECT id FROM printing_printer WHERE tenant_id=? AND device_id=? LIMIT 10001", tenantId, deviceId)) + { + currentRows.add(row.getString("id")); + } + if(!currentRows.equals(authorizedRows)) + { + throw new PrintingException(409, "Inventory changed; authorize its current rows before retrying"); + } + } + Set incoming = new java.util.HashSet<>(); + for(int index = 0; index < printers.length(); index++) + { + incoming.add(required(printers.getJSONObject(index).optString("printerId"), "printerId")); + } + PrintingAdmission.inventory(connection, tenantId, deviceId, incoming, new PrintingAdmissionSettings(dataSource, tenantId, admissionLimits).effective(connection)); + update(connection, "UPDATE printing_printer SET status='UNKNOWN', available=0 WHERE device_id=? AND available=1", deviceId); for(int index = 0; index < printers.length(); index++) { JSONObject printer = printers.getJSONObject(index); @@ -314,6 +765,12 @@ public class PrintingService String name = required(printer.optString("name"), "name"); String formats = printer.getJSONArray("formats").toString(); String status = printer.optString("status", "UNKNOWN"); + List supported = printer.getJSONArray("formats").toList(); + if(supported.isEmpty() || supported.size() > 2 || new java.util.HashSet<>(supported).size() != supported.size() + || !Set.of("PDF", "ZPL").containsAll(supported) || !Set.of("READY", "OFFLINE", "PAUSED", "ERROR", "UNKNOWN").contains(status)) + { + throw new PrintingException(400, "Invalid printer status or supported formats"); + } String now = Instant.now().toString(); String driver = optionalText(printer.optString("driverName"), "driverName", 1024); String port = optionalText(printer.optString("portName"), "portName", 1024); @@ -351,6 +808,7 @@ public class PrintingService throw new PrintingException(404, "Printer not found"); } } + realtimeBus.publish(tenantId, deviceId); } @@ -360,14 +818,11 @@ public class PrintingService ***************************************************************************/ public JSONObject submit(JSONObject request) throws SQLException { - String deviceId = required(request.optString("deviceId"), "deviceId"); - String printerId = required(request.optString("printerId"), "printerId"); - String key = required(request.optString("idempotencyKey"), "idempotencyKey"); - String title = required(request.optString("title"), "title"); String format = required(request.optString("format"), "format"); - if(!Set.of("PDF", "ZPL").contains(format)) + long maximum = realtimePolicy().documentLimit(format); + if(request.getString("contentBase64").length() > ((maximum + 2) / 3) * 4) { - throw new PrintingException(400, "Only PDF and ZPL are supported"); + throw new PrintingException(413, "Encoded document exceeds its configured format limit"); } byte[] content; try @@ -378,68 +833,159 @@ public class PrintingService { throw new PrintingException(400, "Invalid document encoding"); } - if(content.length > MAX_CONTENT_BYTES) + if(content.length > maximum) { - throw new PrintingException(413, "Document exceeds 20971520 bytes"); + throw new PrintingException(413, "Document exceeds configured " + format + " limit of " + maximum + " bytes"); } if(content.length == 0) { - throw new PrintingException(400, "Document must contain 1 to 20971520 bytes"); + throw new PrintingException(400, "Document must contain at least one byte"); } if("PDF".equals(format) && !new String(content, 0, Math.min(5, content.length), StandardCharsets.US_ASCII).equals("%PDF-")) { throw new PrintingException(400, "PDF header is missing"); } - JSONObject options = request.optJSONObject("options"); - if(options == null) + return (submitPrepared(request, hash(content), content.length, connection -> content)); + } + + + + /*************************************************************************** + ** Delay stored-document reads until atomic admission has succeeded. + ***************************************************************************/ + @FunctionalInterface + private interface DocumentLoader + { + /*********************************************************************** + ** Read the immutable document after capacity is reserved. + ***********************************************************************/ + byte[] load(Connection connection) throws SQLException; + } + + + + /*************************************************************************** + ** All producers share durable admission before object storage allocation. + ***************************************************************************/ + private JSONObject submitPrepared(JSONObject request, String digest, int contentLength, DocumentLoader loader) throws SQLException + { + String deviceId = required(request.optString("deviceId"), "deviceId"); + String printerId = required(request.optString("printerId"), "printerId"); + String key = required(request.optString("idempotencyKey"), "idempotencyKey"); + String title = required(request.optString("title"), "title"); + String format = required(request.optString("format"), "format"); + if(!Set.of("PDF", "ZPL").contains(format)) { - options = new JSONObject(); + throw new PrintingException(400, "Only PDF and ZPL are supported"); } - options = new JSONObject(options.toString()); - options.put("copies", options.optInt("copies", 1)); - options.put("scale", options.optString("scale", "ACTUAL_SIZE")); - if(options.has("paperWidthMm") || options.has("paperHeightMm")) - { - throw new PrintingException(400, "Custom paper dimensions are not supported yet; configure the Windows queue"); - } - if(options.getInt("copies") < 1 || options.getInt("copies") > 100 || !Set.of("ACTUAL_SIZE", "FIT").contains(options.getString("scale"))) - { - throw new PrintingException(400, "Invalid print options"); - } - String digest = hash(content); + JSONObject options = printOptions(request); + long contentLimit = realtimePolicy().documentLimit(format); + String id = UUID.randomUUID().toString(); + String reference = storageTableName == null ? null : documentStorage.prefix() + id + "." + format.toLowerCase(java.util.Locale.ROOT); + String binding = storageTableName == null ? null : documentStorage.binding(storageTableName); + String uploadedId = null; try(Connection connection = dataSource.getConnection()) { + requireDevice(connection, deviceId); + PrintingAdmission.initializeTenant(connection, tenantId); connection.setAutoCommit(false); try { - // Serialize submissions per device; the unique key also protects cross-device races. - requireDevice(connection, deviceId); - query(connection, "SELECT id FROM printing_device WHERE id=? FOR UPDATE", deviceId); - List previous = query(connection, "SELECT " + JOB_COLUMNS + " FROM printing_job WHERE tenant_id=? AND idempotency_key=?", tenantId, key); - if(!previous.isEmpty()) + long pendingDeadline = System.nanoTime() + java.util.concurrent.TimeUnit.SECONDS.toNanos(30); + while(true) { - JSONObject old = previous.getFirst(); - if(!old.getString("device_id").equals(deviceId) || !old.getString("printer_id").equals(printerId) || !old.getString("content_hash").equals(digest) || !old.getString("format").equals(format) || !new JSONObject(old.getString("options_json")).similar(options)) + PrintingAdmission.lock(connection, tenantId); + requireDevice(connection, deviceId); + query(connection, "SELECT id FROM printing_device WHERE id=? FOR UPDATE", deviceId); + requireDevice(connection, deviceId); + List previous = query(connection, "SELECT " + JOB_COLUMNS + " FROM printing_job WHERE tenant_id=? AND idempotency_key=?", tenantId, key); + if(!previous.isEmpty()) { - throw new PrintingException(409, "Idempotency key was already used for a different request"); + JSONObject old = previous.getFirst(); + if(!old.getString("device_id").equals(deviceId) || !old.getString("printer_id").equals(printerId) || !old.getString("content_hash").equals(digest) || !old.getString("format").equals(format) || !new JSONObject(old.getString("options_json")).similar(options)) + { + throw new PrintingException(409, "Idempotency key was already used for a different request"); + } + connection.commit(); + return (job(old)); + } + if(query(connection, "SELECT id FROM printing_document_orphan WHERE tenant_id=? AND idempotency_key=? LIMIT 1", tenantId, key).isEmpty()) + { + break; } connection.commit(); - return (job(old)); + if(System.nanoTime() >= pendingDeadline) + { + throw new PrintingException(429, "This request already has an upload in progress or awaiting recovery; retry later using the same request identity"); + } + try + { + Thread.sleep(25); + } + catch(InterruptedException exception) + { + Thread.currentThread().interrupt(); + throw new SQLException("Interrupted while waiting for the existing submission", exception); + } } List printers = query(connection, "SELECT * FROM printing_printer WHERE device_id=? AND printer_id=? AND enabled=1 AND available=1", deviceId, printerId); if(printers.isEmpty() || !new JSONArray(printers.getFirst().getString("formats")).toList().contains(format)) { throw new PrintingException(400, "Printer is not enabled for this format"); } - String id = UUID.randomUUID().toString(); - update(connection, "INSERT INTO printing_job (id, tenant_id, device_id, printer_id, title, format, content_hash, content_base64, content_length, options_json, idempotency_key, created_at, status, printer_row_id) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'QUEUED', ?)", id, tenantId, deviceId, printerId, title, format, digest, Base64.getEncoder().encodeToString(content), content.length, options.toString(), key, Instant.now().toString(), printers.getFirst().getString("id")); + if(contentLength > contentLimit) + { + throw new PrintingException(413, "Document exceeds the current configured format limit"); + } + PrintingAdmission.reserve(connection, tenantId, deviceId, id, contentLength, new PrintingAdmissionSettings(dataSource, tenantId, admissionLimits).effective(connection)); + if(storageTableName != null) + { + reserveUpload(connection, id, storageTableName, reference, binding, deviceId, contentLength, key); + connection.commit(); + uploadedId = id; + if(query(connection, "SELECT id FROM printing_document_orphan WHERE id=? FOR UPDATE", id).isEmpty()) + { + throw new PrintingException(409, "Upload reservation expired; retry submission"); + } + requireDevice(connection, deviceId); + query(connection, "SELECT id FROM printing_device WHERE id=? FOR UPDATE", deviceId); + requireDevice(connection, deviceId); + printers = query(connection, "SELECT * FROM printing_printer WHERE device_id=? AND printer_id=? AND enabled=1 AND available=1", deviceId, printerId); + if(printers.isEmpty() || !new JSONArray(printers.getFirst().getString("formats")).toList().contains(format)) + { + throw new PrintingException(400, "Printer is not enabled for this format"); + } + } + byte[] content = loader.load(connection); + if(content.length != contentLength || !hash(content).equals(digest)) + { + throw new PrintingException(409, "Stored print document integrity validation failed"); + } + if(storageTableName != null) + { + documentStorage.put(storageTableName, reference, format, content); + } + update(connection, "INSERT INTO printing_job (id, tenant_id, device_id, printer_id, title, format, content_hash, content_base64, content_length, options_json, idempotency_key, created_at, status, printer_row_id, content_storage_table, content_reference, content_binding) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'QUEUED', ?, ?, ?, ?)", id, tenantId, deviceId, printerId, title, format, digest, storageTableName == null ? Base64.getEncoder().encodeToString(content) : null, content.length, options.toString(), key, Instant.now().toString(), printers.getFirst().getString("id"), storageTableName, reference, binding); + update(connection, "DELETE FROM printing_document_orphan WHERE id=? AND tenant_id=?", id, tenantId); JSONObject result = job(query(connection, "SELECT " + JOB_COLUMNS + " FROM printing_job WHERE id=?", id).getFirst()); connection.commit(); + realtimeBus.publish(tenantId, deviceId); return (result); } catch(Exception exception) { connection.rollback(); + if(uploadedId != null) + { + try + { + cleanupOrphan(connection, uploadedId); + } + catch(Exception cleanupFailure) + { + exception.addSuppressed(cleanupFailure); + } + } throw exception; } } @@ -447,17 +993,60 @@ public class PrintingService + /*************************************************************************** + ** Preserve request intent: reject malformed types instead of coercing them. + ***************************************************************************/ + private JSONObject printOptions(JSONObject request) throws SQLException + { + if(request.has("options") && !(request.opt("options") instanceof JSONObject)) + { + throw new PrintingException(400, "Print options must be an object"); + } + JSONObject options = request.has("options") ? new JSONObject(request.getJSONObject("options").toString()) : new JSONObject(); + Object copies = options.opt("copies"); + int count = 1; + if(options.has("copies")) + { + if(!(copies instanceof Number number)) + { + throw new PrintingException(400, "Copies must be an integer within the configured limit"); + } + try + { + count = new java.math.BigDecimal(number.toString()).intValueExact(); + } + catch(ArithmeticException | NumberFormatException exception) + { + throw new PrintingException(400, "Copies must be an integer within the configured limit"); + } + } + Object scale = options.has("scale") ? options.opt("scale") : "ACTUAL_SIZE"; + if(count < 1 || count > realtimePolicy().get("maxCopies") || !(scale instanceof String) || !Set.of("ACTUAL_SIZE", "FIT").contains(scale)) + { + throw new PrintingException(400, "Invalid print options"); + } + if(options.has("paperWidthMm") || options.has("paperHeightMm")) + { + throw new PrintingException(400, "Custom paper dimensions are not supported yet; configure the Windows queue"); + } + options.put("copies", count).put("scale", scale); + if(options.toString().length() > 2000) + { + throw new PrintingException(400, "Print options are too large"); + } + return (options); + } + + + /*************************************************************************** ** Claim one job; replay the same assignment until the device advances it. ***************************************************************************/ public JSONObject testPrint(String deviceId, JSONObject request) throws Exception { String format = required(request.optString("format"), "format"); - if(!Set.of("PDF", "ZPL").contains(format)) - { - throw new PrintingException(400, "Only PDF and ZPL are supported"); - } - byte[] bytes = "PDF".equals(format) ? PrintingProcesses.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(format, request.has("testProfile") ? request.optString("testProfile") : null); + byte[] bytes = "PDF".equals(format) ? PrintingTestDocuments.pdf(profile) : PrintingTestDocuments.zpl(profile); return (submit(new JSONObject().put("deviceId", deviceId).put("printerId", required(request.optString("printerId"), "printerId")) .put("title", "QQQ print test").put("format", format).put("contentBase64", Base64.getEncoder().encodeToString(bytes)) .put("idempotencyKey", "device-test:" + deviceId + ":" + required(request.optString("requestId"), "requestId")))); @@ -490,24 +1079,44 @@ public class PrintingService public JSONObject retry(String deviceId, String jobId, JSONObject request) throws SQLException { JSONObject row; + boolean mayHavePrinted; + String retryKey = "device-retry:" + deviceId + ":" + jobId + ":" + required(request.optString("requestId"), "requestId"); try(Connection connection = dataSource.getConnection()) { requireDevice(connection, deviceId); - row = deviceJob(connection, deviceId, jobId, true); + row = deviceJob(connection, deviceId, jobId); + JSONObject document = query(connection, "SELECT content_available, content_storage_table, content_reference, content_binding FROM printing_job WHERE id=? AND tenant_id=? AND device_id=?", jobId, tenantId, deviceId).getFirst(); + row.put("content_available", document.getInt("content_available")).put("content_storage_table", document.opt("content_storage_table")) + .put("content_reference", document.opt("content_reference")).put("content_binding", document.opt("content_binding")); + List previous = query(connection, "SELECT " + JOB_COLUMNS + " FROM printing_job WHERE tenant_id=? AND device_id=? AND idempotency_key=?", tenantId, deviceId, retryKey); + if(!previous.isEmpty()) + { + return (job(previous.getFirst())); + } + if(row.getInt("content_available") == 0) + { + throw new PrintingException(410, "Print document expired under the host retention policy; submit a new document explicitly"); + } + mayHavePrinted = !row.optString("spooler_job_id").isBlank() + || !query(connection, "SELECT id FROM printing_event WHERE job_id=? AND status IN ('SUBMITTING','SPOOLED','SPOOLER_COMPLETED','OUTCOME_UNKNOWN') LIMIT 1", jobId).isEmpty(); } String state = row.getString("status"); if(!Set.of("FAILED", "OUTCOME_UNKNOWN", "SPOOLED", "SPOOLER_COMPLETED").contains(state)) { throw new PrintingException(409, "Only a finished or uncertain job can be reprinted"); } - if(!"FAILED".equals(state) && !request.optBoolean("confirmDuplicateRisk", false)) + if((!"FAILED".equals(state) || mayHavePrinted) && !Boolean.TRUE.equals(request.opt("confirmDuplicateRisk"))) { throw new PrintingException(409, "Inspect the printer and confirm the risk of duplicate output before reprinting"); } - return (submit(new JSONObject().put("deviceId", deviceId).put("printerId", row.getString("printer_id")) - .put("title", row.getString("title")).put("format", row.getString("format")).put("contentBase64", row.getString("content_base64")) + if(!row.isNull("content_reference")) + { + verifyStoredReference(row); + } + return (submitPrepared(new JSONObject().put("deviceId", deviceId).put("printerId", row.getString("printer_id")) + .put("title", row.getString("title")).put("format", row.getString("format")) .put("options", new JSONObject(row.getString("options_json"))) - .put("idempotencyKey", "device-retry:" + deviceId + ":" + jobId + ":" + required(request.optString("requestId"), "requestId")))); + .put("idempotencyKey", retryKey), row.getString("content_hash"), row.getInt("content_length"), connection -> documentBytes(deviceJob(connection, deviceId, jobId, true)))); } @@ -524,13 +1133,20 @@ public class PrintingService { requireDevice(connection, deviceId); query(connection, "SELECT id FROM printing_device WHERE id=? FOR UPDATE", deviceId); + requireDevice(connection, deviceId); JSONObject row = deviceJob(connection, deviceId, jobId); + if("FAILED".equals(row.getString("status")) && CANCELED_BEFORE_DISPATCH.equals(row.optString("message"))) + { + connection.commit(); + return (new JSONObject().put("accepted", true)); + } if(!"QUEUED".equals(row.getString("status"))) { throw new PrintingException(409, "Job already reached the device; inspect or cancel its Windows spooler job"); } - update(connection, "UPDATE printing_job SET status='FAILED', message='Canceled by operator before dispatch' WHERE id=?", jobId); + update(connection, "UPDATE printing_job SET status='FAILED', message=? WHERE id=?", CANCELED_BEFORE_DISPATCH, jobId); connection.commit(); + realtimeBus.publish(tenantId, deviceId); return (new JSONObject().put("accepted", true)); } catch(Exception exception) @@ -547,6 +1163,13 @@ public class PrintingService ** Claim one job; replay the same assignment until the device advances it. ***************************************************************************/ public JSONObject claim(String deviceId) throws SQLException + { + return (claimForJob(deviceId, null)); + } + + + /** Native adapters authorize one exact job and printer before this locked dispatch transition. */ + public JSONObject claimForJob(String deviceId, String authorizedJobId) throws SQLException { try(Connection connection = dataSource.getConnection()) { @@ -555,7 +1178,14 @@ public class PrintingService { requireDevice(connection, deviceId); query(connection, "SELECT id FROM printing_device WHERE id=? FOR UPDATE", deviceId); - List candidates = query(connection, "SELECT j." + JOB_COLUMNS.replace(", ", ", j.") + " FROM printing_job j JOIN printing_printer p ON p.device_id=j.device_id AND p.printer_id=j.printer_id WHERE j.tenant_id=? AND j.device_id=? AND p.enabled=1 AND p.available=1 AND j.status IN ('QUEUED','CLAIMED') ORDER BY j.created_at, j.id LIMIT 1", tenantId, deviceId); + requireDevice(connection, deviceId); + JSONObject control = query(connection, "SELECT dispatch_paused,connection_state FROM printing_device WHERE tenant_id=? AND id=?", tenantId, deviceId).getFirst(); + if(control.getInt("dispatch_paused") == 1 || !"CONNECTED".equals(control.getString("connection_state"))) + { + connection.commit(); + return (new JSONObject().put("job", JSONObject.NULL)); + } + List candidates = query(connection, "SELECT j." + JOB_COLUMNS.replace(", ", ", j.") + " FROM printing_job j JOIN printing_printer p ON p.device_id=j.device_id AND p.printer_id=j.printer_id WHERE j.tenant_id=? AND j.device_id=? AND p.enabled=1 AND p.available=1 AND j.status IN ('QUEUED','CLAIMED') AND ((j.format='PDF' AND p.formats LIKE '%\"PDF\"%') OR (j.format='ZPL' AND p.formats LIKE '%\"ZPL\"%'))" + (authorizedJobId == null ? "" : " AND j.id=?") + " ORDER BY j.created_at, j.id LIMIT 1", authorizedJobId == null ? new Object[] { tenantId, deviceId } : new Object[] { tenantId, deviceId, authorizedJobId }); if(candidates.isEmpty()) { connection.commit(); @@ -593,11 +1223,50 @@ public class PrintingService { throw new PrintingException(409, "Claim the job before downloading"); } - return (Base64.getDecoder().decode(row.getString("content_base64"))); + if(row.getInt("content_available") == 0) + { + throw new PrintingException(410, "Print document expired under the host retention policy"); + } + return (documentBytes(row)); } } + /** Stream external documents without holding a database connection or buffering the entire body. */ + public java.io.InputStream openContent(String deviceId, String jobId) throws SQLException + { + JSONObject row; + try(Connection connection = dataSource.getConnection()) + { + requireDevice(connection, deviceId); + row = deviceJob(connection, deviceId, jobId, true); + if("QUEUED".equals(row.getString("status"))) + { + throw new PrintingException(409, "Claim the job before downloading"); + } + if(row.getInt("content_available") == 0) + { + throw new PrintingException(410, "Print document expired under the host retention policy"); + } + } + if(row.getLong("content_length") > realtimePolicy().documentLimit(row.getString("format"))) + { + throw new PrintingException(413, "Document exceeds the current configured format limit"); + } + java.io.InputStream input; + if(row.isNull("content_reference")) + { + input = new java.io.ByteArrayInputStream(Base64.getDecoder().decode(row.getString("content_base64"))); + } + else + { + verifyStoredReference(row); + input = documentStorage.open(row.getString("content_storage_table"), row.getString("content_reference")); + } + return (new PrintingDocumentStream(input, row.getLong("content_length"), row.getString("content_hash"))); + } + + /*************************************************************************** ** Record a replay-safe lifecycle event without reprinting ambiguous jobs. @@ -606,6 +1275,12 @@ public class PrintingService { String eventId = required(event.optString("eventId"), "eventId"); String status = required(event.optString("status"), "status"); + String message = event.has("message") ? eventText(event, "message", 2048) : ""; + String spooler = event.has("spoolerJobId") ? eventText(event, "spoolerJobId", 128) : null; + if(event.toString().length() > 16000) + { + throw new PrintingException(400, "Event is too large"); + } List states = List.of("CLAIMED", "RECEIVED", "SUBMITTING", "SPOOLED", "SPOOLER_COMPLETED"); if(!Set.of("RECEIVED", "SUBMITTING", "SPOOLED", "SPOOLER_COMPLETED", "FAILED", "OUTCOME_UNKNOWN").contains(status)) { @@ -616,6 +1291,8 @@ public class PrintingService connection.setAutoCommit(false); try { + requireDevice(connection, deviceId); + query(connection, "SELECT id FROM printing_device WHERE id=? FOR UPDATE", deviceId); requireDevice(connection, deviceId); deviceJob(connection, deviceId, jobId); query(connection, "SELECT id FROM printing_job WHERE id=? FOR UPDATE", jobId); @@ -635,9 +1312,15 @@ public class PrintingService { throw new PrintingException(409, "Invalid state transition"); } - update(connection, "INSERT INTO printing_event VALUES (?, ?, ?, ?, ?)", eventId, jobId, status, event.toString(), Instant.now().toString()); - update(connection, "UPDATE printing_job SET status=?, message=?, spooler_job_id=? WHERE id=?", status, event.optString("message"), event.optString("spoolerJobId", row.optString("spooler_job_id")), jobId); + String eventTime = Instant.now().toString(); + update(connection, "INSERT INTO printing_event VALUES (?, ?, ?, ?, ?)", eventId, jobId, status, event.toString(), eventTime); + if(Set.of("SPOOLED", "SPOOLER_COMPLETED").contains(status)) + { + update(connection, "UPDATE printing_job SET completed_at=? WHERE id=?", eventTime, jobId); + } + update(connection, "UPDATE printing_job SET status=?, message=?, spooler_job_id=? WHERE id=?", status, message, spooler == null ? row.optString("spooler_job_id") : spooler, jobId); connection.commit(); + realtimeBus.publish(tenantId, deviceId); } catch(Exception exception) { @@ -661,7 +1344,7 @@ public class PrintingService { result.put(new JSONObject().put("deviceId", row.getString("id")).put("facilityId", row.getString("facility_id")).put("deviceName", row.getString("name")).put("computerName", row.getString("computer_name")) .put("profile", new JSONObject().put("name", row.optString("display_name")).put("description", row.optString("description")).put("location", row.optString("location"))) - .put("agentVersion", row.getString("agent_version")).put("lastSeenAt", row.getString("last_seen_at")).put("enabled", row.getInt("enabled") == 1)); + .put("agentVersion", row.getString("agent_version")).put("lastSeenAt", row.getString("last_seen_at")).put("enabled", row.getInt("enabled") == 1).put("control", PrintingDeviceControls.state(row))); } return (result); } @@ -670,25 +1353,68 @@ public class PrintingService /*************************************************************************** - ** Return printers for a device owned by this tenant. + ** Bounded inventory history for management clients. ***************************************************************************/ - public JSONArray printers(String deviceId) throws SQLException + public JSONObject printersPage(String deviceId, int limit, String before) throws SQLException { + if(limit < 1 || limit > 200) + { + throw new PrintingException(400, "Printer page limit must be between 1 and 200"); + } + String name = null; + String id = null; + if(before != null && !before.isEmpty()) + { + try + { + if(before.length() > 12000) + { + throw new IllegalArgumentException("Cursor too long"); + } + JSONObject cursor = new JSONObject(new String(Base64.getUrlDecoder().decode(before), StandardCharsets.UTF_8)); + name = optionalText(cursor.getString("name"), "cursor name", 1024); + id = UUID.fromString(cursor.getString("id")).toString(); + } + catch(RuntimeException exception) + { + throw new PrintingException(400, "Invalid printer cursor"); + } + } try(Connection connection = dataSource.getConnection()) { requireDevice(connection, deviceId); + String sql = "SELECT * FROM printing_printer WHERE tenant_id=? AND device_id=?"; + List rows = name == null ? query(connection, sql + " ORDER BY name,id LIMIT ?", tenantId, deviceId, limit + 1) + : query(connection, sql + " AND (name>? OR (name=? AND id>?)) ORDER BY name,id LIMIT ?", tenantId, deviceId, name, name, id, limit + 1); JSONArray result = new JSONArray(); - for(JSONObject row : query(connection, "SELECT * FROM printing_printer WHERE device_id=? ORDER BY name", deviceId)) + for(JSONObject row : rows.subList(0, Math.min(limit, rows.size()))) { result.put(new JSONObject().put("printerId", row.getString("printer_id")).put("name", row.getString("queue_name")).put("displayName", row.optString("display_name")).put("description", row.optString("description")).put("location", row.optString("location")) .put("driverName", row.optString("driver_name")).put("portName", row.optString("port_name")).put("status", row.getString("status")).put("formats", new JSONArray(row.getString("formats"))).put("enabled", row.getInt("enabled") == 1).put("available", row.getInt("available") == 1).put("lastSeenAt", row.getString("last_seen_at"))); } - return (result); + JSONObject response = new JSONObject().put("printers", result).put("nextCursor", JSONObject.NULL); + if(rows.size() > limit) + { + JSONObject last = rows.get(limit - 1); + String cursor = new JSONObject().put("name", last.getString("name")).put("id", last.getString("id")).toString(); + response.put("nextCursor", Base64.getUrlEncoder().withoutPadding().encodeToString(cursor.getBytes(StandardCharsets.UTF_8))); + } + return (response); } } + /*************************************************************************** + ** Existing callers retain their array contract with a bounded first page. + ***************************************************************************/ + public JSONArray printers(String deviceId) throws SQLException + { + return (printersPage(deviceId, 200, null).getJSONArray("printers")); + } + + + /*************************************************************************** ** Return recent jobs; content is excluded from management lists. ***************************************************************************/ @@ -784,12 +1510,82 @@ public class PrintingService + /*************************************************************************** + ** Host-authorized maintenance only, never called by device routes. Purge a + ** bounded batch of old successful payloads while preserving all receipts, + ** hashes and idempotency keys. Failed and uncertain jobs are never selected. + ***************************************************************************/ + public int purgeCompletedContent(PrintingRetentionPolicy policy) throws SQLException + { + try(Connection connection = dataSource.getConnection()) + { + return (purgeCompletedContent(connection, policy, new int[1], null)); + } + } + + + + /*************************************************************************** + ** Commit each confirmed removal so a later failure cannot undo its receipt. + ***************************************************************************/ + private int purgeCompletedContent(Connection connection, PrintingRetentionPolicy policy, int[] progress, String leaseToken) throws SQLException + { + java.util.Objects.requireNonNull(policy); + if(!policy.enabled()) + { + return (0); + } + String cutoff = Instant.now().minusSeconds(policy.days() * 86400L).toString(); + { + PrintingAdmission.initializeTenant(connection, tenantId); + connection.setAutoCommit(false); + try + { + List rows = query(connection, "SELECT id FROM printing_job WHERE tenant_id=? AND content_available=1 AND status IN ('SPOOLED','SPOOLER_COMPLETED') AND completed_at locked = query(connection, "SELECT id, device_id, content_length, format, content_storage_table, content_reference, content_binding FROM printing_job WHERE tenant_id=? AND id=? AND content_available=1 AND status IN ('SPOOLED','SPOOLER_COMPLETED') AND completed_at orphans = query(connection, "SELECT id FROM printing_document_orphan WHERE tenant_id=? AND created_at rows = query(connection, "SELECT * FROM printing_document_orphan WHERE tenant_id=? AND id=? FOR UPDATE", tenantId, id); + if(rows.isEmpty()) + { + connection.commit(); + return (0); + } + JSONObject orphan = rows.getFirst(); + if(query(connection, "SELECT id FROM printing_job WHERE id=? AND tenant_id=?", id, tenantId).isEmpty()) + { + if(documentStorage == null) + { + throw new PrintingException(503, "The host printing storage adapter is not configured"); + } + documentStorage.verifyBinding(orphan.getString("storage_table"), orphan.getString("binding")); + String reference = orphan.getString("reference"); + String expected = documentStorage.prefix() + id; + if(!reference.equals(expected + ".pdf") && !reference.equals(expected + ".zpl")) + { + throw new PrintingException(409, "Orphan reference does not match its owned upload identity"); + } + documentStorage.delete(orphan.getString("storage_table"), orphan.getString("reference")); + PrintingAdmission.release(connection, tenantId, orphan.isNull("device_id") ? null : orphan.getString("device_id"), orphan.isNull("content_length") ? PrintingAdmission.UNKNOWN_UPLOAD_BYTES : orphan.getLong("content_length")); + } + update(connection, "DELETE FROM printing_document_orphan WHERE id=? AND tenant_id=?", id, tenantId); + connection.commit(); + return (1); + } + catch(Exception exception) + { + connection.rollback(); + throw exception; + } + } + } + + + /*************************************************************************** ** Restrict content and event access to the assigned device. ***************************************************************************/ @@ -812,7 +1854,7 @@ public class PrintingService ***************************************************************************/ private JSONObject deviceJob(Connection connection, String deviceId, String jobId, boolean includeContent) throws SQLException { - List rows = query(connection, "SELECT " + JOB_COLUMNS + (includeContent ? ", content_base64" : "") + " FROM printing_job WHERE id=? AND tenant_id=? AND device_id=?", jobId, tenantId, deviceId); + List rows = query(connection, "SELECT " + JOB_COLUMNS + (includeContent ? ", content_base64, content_available, content_storage_table, content_reference, content_binding" : "") + " FROM printing_job WHERE id=? AND tenant_id=? AND device_id=?", jobId, tenantId, deviceId); if(rows.isEmpty()) { throw new PrintingException(404, "Job not found"); @@ -835,7 +1877,7 @@ public class PrintingService /*************************************************************************** ** Run a bounded, parameterized query with lower-case column names. ***************************************************************************/ - private static List query(Connection connection, String sql, Object... values) throws SQLException + static List query(Connection connection, String sql, Object... values) throws SQLException { try(PreparedStatement statement = connection.prepareStatement(sql)) { @@ -862,7 +1904,7 @@ public class PrintingService /*************************************************************************** ** Execute a parameterized mutation. ***************************************************************************/ - private static int update(Connection connection, String sql, Object... values) throws SQLException + static int update(Connection connection, String sql, Object... values) throws SQLException { try(PreparedStatement statement = connection.prepareStatement(sql)) { @@ -895,7 +1937,8 @@ public class PrintingService { case "name", "deviceName", "title" -> 1024; case "tenantId", "facilityId", "printerId" -> 200; - case "agentVersion", "eventId" -> 100; + case "agentVersion" -> 100; + case "eventId" -> 128; default -> 300; }; if(value == null || value.isBlank() || value.length() > maximum) @@ -907,6 +1950,20 @@ public class PrintingService + /*************************************************************************** + ** Bound event fields before persistence without coercing invalid JSON types. + ***************************************************************************/ + private static String eventText(JSONObject event, String name, int maximum) + { + if(!(event.opt(name) instanceof String value)) + { + throw new PrintingException(400, "Invalid " + name); + } + return (optionalText(value, name, maximum)); + } + + + /*************************************************************************** ** Client-owned metadata synchronizes without changing technical identity. ***************************************************************************/ diff --git a/src/main/java/com/kingsrook/qbits/printing/PrintingTableDocuments.java b/src/main/java/com/kingsrook/qbits/printing/PrintingTableDocuments.java new file mode 100644 index 0000000..2a45b56 --- /dev/null +++ b/src/main/java/com/kingsrook/qbits/printing/PrintingTableDocuments.java @@ -0,0 +1,124 @@ +/* + * 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.IOException; +import java.util.List; +import com.kingsrook.qqq.backend.core.exceptions.QException; + + +/******************************************************************************* + ** A table list: a grid of rows under a repeated column header, in fixed-width + ** monospace columns sized from the content and shrunk to fit the page. + *******************************************************************************/ +public final class PrintingTableDocuments +{ + static final int FONT_SIZE = 8; + + + + /*************************************************************************** + ** Utility class. + ***************************************************************************/ + private PrintingTableDocuments() + { + } + + + + /*************************************************************************** + ** Render columns and rows (display text) on LETTER or A4, portrait or + ** landscape, without preferred widths or a footer. + ***************************************************************************/ + public static byte[] pdf(String title, String subtitle, List columns, List> rows, String pageSize, boolean landscape) throws QException + { + return (pdf(title, subtitle, null, columns, rows, null, pageSize, landscape ? "LANDSCAPE" : "PORTRAIT")); + } + + + + /*************************************************************************** + ** Render a table list. Preferred widths (the grid's, in characters) are + ** the starting column widths, else the content decides; either way they + ** shrink to fit the page. Orientation AUTO turns the page landscape when + ** the columns do not fit portrait. The header repeats on every page; the + ** footer text goes at the bottom left of every page. + ***************************************************************************/ + public static byte[] pdf(String title, String subtitle, String footer, List columns, List> rows, int[] preferredWidths, String pageSize, String orientation) throws QException + { + if(columns.isEmpty()) + { + throw new QException("A table list needs at least one column"); + } + int[] natural = PrintingLayout.naturalWidths(columns, rows); + if(preferredWidths != null && preferredWidths.length == columns.size()) + { + for(int c = 0; c < natural.length; c++) + { + natural[c] = Math.max(4, Math.min(60, preferredWidths[c])); + } + } + boolean landscape = isLandscape(orientation, natural, pageSize); + try(PrintingLayout layout = new PrintingLayout(pageSize, landscape, title, subtitle)) + { + layout.footer(footer); + int[] widths = PrintingLayout.fit(natural, layout.columns(FONT_SIZE)); + String header = PrintingLayout.row(columns, widths); + String rule = "-".repeat(Math.min(layout.columns(FONT_SIZE), Math.max(1, header.length()))); + layout.line(header, FONT_SIZE); + layout.line(rule, FONT_SIZE); + layout.repeatOnNewPages(List.of(header, rule), FONT_SIZE); + for(List row : rows) + { + layout.line(PrintingLayout.row(row, widths), FONT_SIZE); + } + layout.repeatOnNewPages(List.of(), FONT_SIZE); + layout.gap(4); + layout.line(rows.size() + (rows.size() == 1 ? " row" : " rows"), FONT_SIZE); + return (layout.finish()); + } + catch(IOException exception) + { + throw new QException("Could not render the table list: " + exception.getMessage(), exception); + } + } + + + + /*************************************************************************** + ** PORTRAIT, LANDSCAPE, or AUTO: landscape when the natural widths do not + ** fit across a portrait page. + ***************************************************************************/ + static boolean isLandscape(String orientation, int[] natural, String pageSize) + { + if("LANDSCAPE".equalsIgnoreCase(orientation)) + { + return (true); + } + if(!"AUTO".equalsIgnoreCase(orientation)) + { + return (false); + } + float width = ("A4".equalsIgnoreCase(pageSize) ? 595.28f : 612f) - 2 * PrintingLayout.MARGIN; + return (PrintingLayout.lineWidth(natural) > (int) (width / (0.6f * FONT_SIZE))); + } +} diff --git a/src/main/java/com/kingsrook/qbits/printing/PrintingTableSettings.java b/src/main/java/com/kingsrook/qbits/printing/PrintingTableSettings.java new file mode 100644 index 0000000..914ed81 --- /dev/null +++ b/src/main/java/com/kingsrook/qbits/printing/PrintingTableSettings.java @@ -0,0 +1,91 @@ +/* + * 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.model.metadata.tables.QSupplementalTableMetaData; +import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData; + + +/******************************************************************************* + ** Per-table printing metadata. A table carrying it with printable false gets + ** no Print process from PrintingRecordProcesses.registerAll: + ** {@code table.withSupplementalMetaData(new PrintingTableSettings().withPrintable(false))}. + *******************************************************************************/ +public class PrintingTableSettings extends QSupplementalTableMetaData +{ + public static final String TYPE = "printing"; + + private boolean printable = true; + + + + /*************************************************************************** + ** The settings of a table, or null when it has none. + ***************************************************************************/ + public static PrintingTableSettings of(QTableMetaData table) + { + return (table.getSupplementalMetaData() == null ? null : (PrintingTableSettings) table.getSupplementalMetaData(TYPE)); + } + + + + /*************************************************************************** + ** Supplemental metadata type. + ***************************************************************************/ + @Override + public String getType() + { + return (TYPE); + } + + + + /*************************************************************************** + ** Whether the table's records and lists may be printed (default true). + ***************************************************************************/ + public boolean getPrintable() + { + return (printable); + } + + + + /*************************************************************************** + ** Fluent setter. + ***************************************************************************/ + public PrintingTableSettings withPrintable(boolean value) + { + printable = value; + return (this); + } + + + + /*************************************************************************** + ** No mutable references beyond the flag, which the base clone copies. + ***************************************************************************/ + @Override + protected QSupplementalTableMetaData finishClone(QSupplementalTableMetaData clone) + { + return (clone); + } +} diff --git a/src/main/java/com/kingsrook/qbits/printing/PrintingTables.java b/src/main/java/com/kingsrook/qbits/printing/PrintingTables.java index 5e6d5a9..e6438cc 100644 --- a/src/main/java/com/kingsrook/qbits/printing/PrintingTables.java +++ b/src/main/java/com/kingsrook/qbits/printing/PrintingTables.java @@ -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"; diff --git a/src/main/java/com/kingsrook/qbits/printing/PrintingTestDocuments.java b/src/main/java/com/kingsrook/qbits/printing/PrintingTestDocuments.java new file mode 100644 index 0000000..e915ac3 --- /dev/null +++ b/src/main/java/com/kingsrook/qbits/printing/PrintingTestDocuments.java @@ -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(); + } +} + diff --git a/src/main/java/com/kingsrook/qbits/printing/PrintingTextDocuments.java b/src/main/java/com/kingsrook/qbits/printing/PrintingTextDocuments.java new file mode 100644 index 0000000..5e2f83a --- /dev/null +++ b/src/main/java/com/kingsrook/qbits/printing/PrintingTextDocuments.java @@ -0,0 +1,102 @@ +/* + * 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.IOException; +import com.kingsrook.qqq.backend.core.exceptions.QException; + + +/******************************************************************************* + ** Plain text as a PDF: monospace, long lines hard-wrapped, broken across + ** pages. Used to print a capture of a terminal screen (or any text). + *******************************************************************************/ +public final class PrintingTextDocuments +{ + static final int FONT_SIZE = 8; + static final float MIN_FONT_SIZE = 5.5f; + static final int MAX_CHARACTERS = 2_000_000; + + + + /*************************************************************************** + ** Utility class. + ***************************************************************************/ + private PrintingTextDocuments() + { + } + + + + /*************************************************************************** + ** Render text on LETTER or A4, portrait or landscape. + ***************************************************************************/ + public static byte[] pdf(String title, String subtitle, String text, String pageSize, boolean landscape) throws QException + { + if(text == null || text.isEmpty()) + { + throw new QException("There is no text to print"); + } + if(text.length() > MAX_CHARACTERS) + { + throw new QException("The text is too long to print (at most " + MAX_CHARACTERS + " characters)"); + } + try(PrintingLayout layout = new PrintingLayout(pageSize, landscape, title, subtitle)) + { + String[] lines = text.replace("\r\n", "\n").replace('\r', '\n').replace("\t", " ").split("\n", -1); + float size = fontSize(lines, layout.columns(1) * 1f); + int width = layout.columns(size); + layout.leading(1.2f); + for(String line : lines) + { + String rest = line.stripTrailing(); + do + { + layout.line(rest.length() > width ? rest.substring(0, width) : rest, size); + rest = rest.length() > width ? rest.substring(width) : ""; + } + while(!rest.isEmpty()); + } + return (layout.finish()); + } + catch(IOException exception) + { + throw new QException("Could not render the text: " + exception.getMessage(), exception); + } + } + + + + /*************************************************************************** + ** The font size (8 down to 5.5 points) at which the widest line fits, so a + ** screen capture keeps its layout; wider text still wraps at 5.5. + ***************************************************************************/ + static float fontSize(String[] lines, float charactersAtOnePoint) + { + int widest = 1; + for(String line : lines) + { + widest = Math.max(widest, line.stripTrailing().length()); + } + float fits = charactersAtOnePoint / widest; + return (Math.max(MIN_FONT_SIZE, Math.min(FONT_SIZE, (float) Math.floor(fits * 2) / 2))); + } +} diff --git a/src/main/java/com/kingsrook/qbits/printing/PrintingUiApi.java b/src/main/java/com/kingsrook/qbits/printing/PrintingUiApi.java new file mode 100644 index 0000000..a5ed708 --- /dev/null +++ b/src/main/java/com/kingsrook/qbits/printing/PrintingUiApi.java @@ -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 2.0.0 requires authenticated realtime delivery for native claims; 2.1.0 adds the record, table-list and text print processes. */ + public static MiddlewareSpecExtension extension() + { + return (new MiddlewareSpecExtension().withName("printing").withSemanticVersion("2.1.0") + .withDescription("Native current-user printing with secondary device proof, device-control-v1 and realtime-v1; record, table-list and text printing processes.") + .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 defineResponses() + { + Map 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((java.io.InputStream) 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"); + } + + } +} diff --git a/src/main/java/com/kingsrook/qbits/printing/PrintingUiApiSpec.java b/src/main/java/com/kingsrook/qbits/printing/PrintingUiApiSpec.java new file mode 100644 index 0000000..1e4a7ce --- /dev/null +++ b/src/main/java/com/kingsrook/qbits/printing/PrintingUiApiSpec.java @@ -0,0 +1,335 @@ +/* + * 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 defineComponentSchemas() + { + return (PrintingApiSchemas.components()); + } + + + /** Document secondary proof independently from core session authentication. */ + @Override + public List defineRequestParameters() + { + List 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" -> + { + service.requireRealtimeReady(device); + 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.openContent(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. */ + 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 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()))); + } +} diff --git a/src/main/java/com/kingsrook/qbits/printing/TestPrintProfile.java b/src/main/java/com/kingsrook/qbits/printing/TestPrintProfile.java new file mode 100644 index 0000000..ae5d79d --- /dev/null +++ b/src/main/java/com/kingsrook/qbits/printing/TestPrintProfile.java @@ -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); + } +} + diff --git a/src/main/resources/com/kingsrook/qbits/printing/fonts/JetBrainsMono-Bold.ttf b/src/main/resources/com/kingsrook/qbits/printing/fonts/JetBrainsMono-Bold.ttf new file mode 100644 index 0000000..8c93043 Binary files /dev/null and b/src/main/resources/com/kingsrook/qbits/printing/fonts/JetBrainsMono-Bold.ttf differ diff --git a/src/main/resources/com/kingsrook/qbits/printing/fonts/OFL.txt b/src/main/resources/com/kingsrook/qbits/printing/fonts/OFL.txt new file mode 100644 index 0000000..8bee414 --- /dev/null +++ b/src/main/resources/com/kingsrook/qbits/printing/fonts/OFL.txt @@ -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. diff --git a/src/main/resources/com/kingsrook/qbits/printing/fonts/README.md b/src/main/resources/com/kingsrook/qbits/printing/fonts/README.md new file mode 100644 index 0000000..6e54476 --- /dev/null +++ b/src/main/resources/com/kingsrook/qbits/printing/fonts/README.md @@ -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. diff --git a/src/main/resources/com/kingsrook/qbits/printing/images/README.md b/src/main/resources/com/kingsrook/qbits/printing/images/README.md new file mode 100644 index 0000000..dd2cd63 --- /dev/null +++ b/src/main/resources/com/kingsrook/qbits/printing/images/README.md @@ -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. diff --git a/src/main/resources/com/kingsrook/qbits/printing/images/query-mascot.png b/src/main/resources/com/kingsrook/qbits/printing/images/query-mascot.png new file mode 100644 index 0000000..688b460 Binary files /dev/null and b/src/main/resources/com/kingsrook/qbits/printing/images/query-mascot.png differ diff --git a/src/main/resources/openapi/qqq-v1/printing.yaml b/src/main/resources/openapi/qqq-v1/printing.yaml new file mode 100644 index 0000000..33ce14d --- /dev/null +++ b/src/main/resources/openapi/qqq-v1/printing.yaml @@ -0,0 +1,2079 @@ +components: + schemas: + BasicErrorResponseV1: + description: "The error body of every UI API operation (core and extensions)." + properties: + error: + description: "The error message (the same as message; kept for clients of\ + \ UI API 1.0 to 1.5)." + type: "string" + code: + description: "A stable, machine-readable code. Well-known values: BAD_REQUEST\ + \ (400), UNAUTHENTICATED (401),\nPERMISSION_DENIED (403), NOT_FOUND (404),\ + \ CONFLICT (409), RATE_LIMITED (429), INTERNAL_ERROR (500),\nERROR (other).\ + \ Extensions may add codes; treat an unknown code by the HTTP status.\ + \ Since 1.6.0." + type: "string" + message: + description: "A message to show the user. Since 1.6.0." + type: "string" + fieldErrors: + description: "Errors about particular request fields, when known. Since\ + \ 1.6.0." + items: + properties: + field: + description: "The field (or parameter) name." + type: "string" + message: + description: "The error about that field." + type: "string" + code: + description: "An optional machine-readable code, e.g. REQUIRED, TOO_LONG,\ + \ PATTERN." + type: "string" + type: "object" + type: "array" + traceId: + description: "Identifies this request in the server logs (also the X-QQQ-Trace-Id\ + \ response header); quote it when reporting a problem. Since 1.6.0." + type: "string" + type: "object" + PrintingAcknowledgmentV1: + properties: + accepted: + type: "boolean" + required: + - "accepted" + type: "object" + PrintingActionRequestV1: + properties: + requestId: + maxLength: 128 + type: "string" + issuedAt: + description: "RFC3339 UTC ending in uppercase Z." + format: "date-time" + maxLength: 40 + type: "string" + action: + enum: + - "PAUSE_DISPATCH" + - "RESUME_DISPATCH" + - "DISCONNECT" + - "RECONNECT" + - "REVOKE" + - "REFRESH_INVENTORY" + - "CLEAR_QUEUE" + - "CANCEL_SPOOL" + type: "string" + jobId: + maxLength: 128 + type: "string" + required: + - "requestId" + - "issuedAt" + - "action" + type: "object" + PrintingActionV1: + properties: + commandId: + maxLength: 128 + type: "string" + requestId: + maxLength: 128 + type: "string" + issuedAt: + description: "RFC3339 UTC ending in uppercase Z." + format: "date-time" + maxLength: 40 + type: "string" + deviceId: + maxLength: 128 + type: "string" + action: + enum: + - "PAUSE_DISPATCH" + - "RESUME_DISPATCH" + - "DISCONNECT" + - "RECONNECT" + - "REVOKE" + - "REFRESH_INVENTORY" + - "CLEAR_QUEUE" + - "CANCEL_SPOOL" + type: "string" + status: + enum: + - "PENDING" + - "SUCCEEDED" + - "FAILED" + - "EXPIRED" + - "OUTCOME_UNKNOWN" + type: "string" + createdAt: + description: "RFC3339 UTC ending in uppercase Z." + format: "date-time" + maxLength: 40 + type: "string" + expiresAt: + description: "RFC3339 UTC ending in uppercase Z." + format: "date-time" + maxLength: 40 + type: "string" + jobId: + maxLength: 128 + type: "string" + resultCode: + maxLength: 80 + type: "string" + cancelledJobCount: + type: "integer" + receipt: + $ref: "#/components/schemas/PrintingReceiptRequestV1" + required: + - "commandId" + - "requestId" + - "issuedAt" + - "deviceId" + - "action" + - "status" + - "createdAt" + - "expiresAt" + type: "object" + PrintingActionsV1: + properties: + commands: + items: + $ref: "#/components/schemas/PrintingActionV1" + type: "array" + nextCursor: + maxLength: 128 + nullable: true + type: "string" + required: + - "commands" + - "nextCursor" + type: "object" + PrintingClaimV1: + properties: + job: + $ref: "#/components/schemas/PrintingJobV1" + nullable: true + required: + - "job" + type: "object" + PrintingCommandV1: + properties: + commandId: + maxLength: 128 + type: "string" + requestId: + maxLength: 128 + type: "string" + action: + enum: + - "REFRESH_INVENTORY" + - "CANCEL_SPOOL" + type: "string" + createdAt: + description: "RFC3339 UTC ending in uppercase Z." + format: "date-time" + maxLength: 40 + type: "string" + expiresAt: + description: "RFC3339 UTC ending in uppercase Z." + format: "date-time" + maxLength: 40 + type: "string" + jobId: + maxLength: 128 + type: "string" + required: + - "commandId" + - "requestId" + - "action" + - "createdAt" + - "expiresAt" + type: "object" + PrintingControlPollRequestV1: + properties: + controlVersion: + type: "integer" + agentVersion: + maxLength: 100 + type: "string" + capabilities: + items: + enum: + - "REFRESH_INVENTORY" + - "CANCEL_SPOOL" + type: "string" + type: "array" + lastAppliedRevision: + type: "integer" + required: + - "controlVersion" + - "agentVersion" + - "capabilities" + - "lastAppliedRevision" + type: "object" + PrintingControlPollV1: + properties: + controlVersion: + type: "integer" + serverTime: + description: "RFC3339 UTC ending in uppercase Z." + format: "date-time" + maxLength: 40 + type: "string" + pollIntervalSeconds: + type: "integer" + desiredState: + $ref: "#/components/schemas/PrintingDesiredStateV1" + commands: + items: + $ref: "#/components/schemas/PrintingCommandV1" + type: "array" + required: + - "controlVersion" + - "serverTime" + - "pollIntervalSeconds" + - "desiredState" + - "commands" + type: "object" + PrintingDesiredStateV1: + properties: + revision: + type: "integer" + dispatchPaused: + type: "boolean" + connectionState: + enum: + - "CONNECTED" + - "DISCONNECTED" + type: "string" + required: + - "revision" + - "dispatchPaused" + - "connectionState" + type: "object" + PrintingEmptyV1: + type: "object" + PrintingEnrollmentRequestV1: + properties: + enrollmentCode: + maxLength: 128 + type: "string" + deviceName: + maxLength: 1024 + type: "string" + agentVersion: + maxLength: 100 + type: "string" + required: + - "enrollmentCode" + - "deviceName" + - "agentVersion" + type: "object" + PrintingEnrollmentV1: + properties: + protocolVersion: + type: "integer" + deviceId: + maxLength: 128 + type: "string" + deviceToken: + description: "Private device proof, returned once; never log." + maxLength: 128 + type: "string" + pollIntervalSeconds: + type: "integer" + required: + - "protocolVersion" + - "deviceId" + - "deviceToken" + - "pollIntervalSeconds" + type: "object" + PrintingEventRequestV1: + properties: + eventId: + maxLength: 128 + type: "string" + status: + enum: + - "RECEIVED" + - "SUBMITTING" + - "SPOOLED" + - "SPOOLER_COMPLETED" + - "FAILED" + - "OUTCOME_UNKNOWN" + type: "string" + message: + maxLength: 2048 + type: "string" + spoolerJobId: + maxLength: 128 + type: "string" + required: + - "eventId" + - "status" + type: "object" + PrintingHeartbeatRequestV1: + properties: + agentVersion: + maxLength: 100 + type: "string" + profile: + $ref: "#/components/schemas/PrintingProfileV1" + required: + - "agentVersion" + type: "object" + PrintingHeartbeatV1: + properties: + serverTime: + description: "RFC3339 UTC ending in uppercase Z." + format: "date-time" + maxLength: 40 + type: "string" + required: + - "serverTime" + type: "object" + PrintingInventoryRequestV1: + properties: + printers: + items: + $ref: "#/components/schemas/PrintingPrinterV1" + type: "array" + required: + - "printers" + type: "object" + PrintingJobV1: + properties: + jobId: + maxLength: 128 + type: "string" + deviceId: + maxLength: 128 + type: "string" + printerId: + maxLength: 128 + type: "string" + title: + maxLength: 1024 + type: "string" + format: + enum: + - "PDF" + - "ZPL" + type: "string" + contentSha256: + maxLength: 64 + type: "string" + contentLength: + type: "integer" + options: + $ref: "#/components/schemas/PrintingOptionsV1" + createdAt: + description: "RFC3339 UTC ending in uppercase Z." + format: "date-time" + maxLength: 40 + type: "string" + status: + enum: + - "QUEUED" + - "CLAIMED" + - "RECEIVED" + - "SUBMITTING" + - "SPOOLED" + - "SPOOLER_COMPLETED" + - "FAILED" + - "OUTCOME_UNKNOWN" + type: "string" + message: + maxLength: 2048 + type: "string" + spoolerJobId: + maxLength: 128 + type: "string" + required: + - "jobId" + - "deviceId" + - "printerId" + - "title" + - "format" + - "contentSha256" + - "contentLength" + - "options" + - "createdAt" + - "status" + type: "object" + PrintingJobsV1: + properties: + jobs: + items: + $ref: "#/components/schemas/PrintingJobV1" + type: "array" + required: + - "jobs" + type: "object" + PrintingOptionsV1: + properties: + copies: + type: "integer" + scale: + enum: + - "ACTUAL_SIZE" + - "FIT" + type: "string" + paperWidthMm: + type: "number" + paperHeightMm: + type: "number" + type: "object" + PrintingPrinterV1: + properties: + printerId: + maxLength: 128 + type: "string" + name: + maxLength: 1024 + type: "string" + driverName: + maxLength: 1024 + type: "string" + portName: + maxLength: 1024 + type: "string" + status: + enum: + - "READY" + - "OFFLINE" + - "PAUSED" + - "ERROR" + - "UNKNOWN" + type: "string" + formats: + items: + enum: + - "PDF" + - "ZPL" + type: "string" + type: "array" + displayName: + maxLength: 512 + type: "string" + description: + maxLength: 4096 + type: "string" + location: + maxLength: 512 + type: "string" + required: + - "printerId" + - "name" + - "formats" + type: "object" + PrintingProfileV1: + properties: + name: + maxLength: 512 + nullable: true + type: "string" + description: + maxLength: 4096 + nullable: true + type: "string" + location: + maxLength: 512 + nullable: true + type: "string" + type: "object" + PrintingReceiptRequestV1: + properties: + receiptId: + maxLength: 128 + type: "string" + outcome: + enum: + - "INVENTORY_REFRESHED" + - "CANCEL_REQUESTED" + - "ALREADY_ABSENT" + - "OWNERSHIP_MISMATCH" + - "UNSUPPORTED" + - "FAILED" + - "EXPIRED" + - "OUTCOME_UNKNOWN" + type: "string" + completedAt: + description: "RFC3339 UTC ending in uppercase Z." + format: "date-time" + maxLength: 40 + type: "string" + message: + maxLength: 1024 + type: "string" + required: + - "receiptId" + - "outcome" + - "completedAt" + type: "object" + PrintingRetryRequestV1: + properties: + requestId: + maxLength: 128 + type: "string" + confirmDuplicateRisk: + type: "boolean" + required: + - "requestId" + type: "object" + PrintingSessionV1: + properties: + principalId: + maxLength: 200 + type: "string" + tenantId: + maxLength: 200 + type: "string" + deviceId: + maxLength: 128 + type: "string" + required: + - "principalId" + - "tenantId" + type: "object" + PrintingTestRequestV1: + properties: + requestId: + maxLength: 128 + type: "string" + printerId: + maxLength: 128 + type: "string" + format: + enum: + - "PDF" + - "ZPL" + type: "string" + testProfile: + maxLength: 40 + type: "string" + required: + - "requestId" + - "printerId" + - "format" + type: "object" + securitySchemes: + sessionUuidCookie: + description: "The session cookie set by POST /qqq/v1/manageSession (web clients)." + in: "cookie" + name: "sessionUUID" + type: "apiKey" + bearerAuth: + bearerFormat: "JWT or session UUID" + description: "`Authorization: Bearer `, where the token is either\n-\ + \ an OAuth2 access token (a signed JWT) issued by the app's identity provider\ + \ to the app's client,\n or to its native client (`values.nativeClientId`\ + \ in GET /qqq/v1/metaData/authentication), for\n example from the device-authorization\ + \ grant or auth-code + PKCE. It is verified against the\n provider's keys\ + \ (issuer, audience, expiry, signature) and gives the same user and permissions\n\ + \ as signing in on the web. When it expires (401), refresh it at the provider\ + \ and retry; or\n- a session UUID returned by POST /qqq/v1/manageSession,\ + \ which the server keeps refreshed." + scheme: "bearer" + type: "http" + oauth2: + description: "The app's OAuth2 / OpenID Connect provider. The real endpoints\ + \ come from the provider's discovery\ndocument: `{values.baseUrl}.well-known/openid-configuration`,\ + \ with values from\nGET /qqq/v1/metaData/authentication. Native clients use\ + \ `values.nativeClientId` (a public client)\nwith auth-code + PKCE (loopback\ + \ or custom-scheme redirect URI registered at the provider) or the\ndevice-authorization\ + \ grant (`device_authorization_endpoint`, RFC 8628), then send the access\ + \ token\nas `Authorization: Bearer`." + flows: + authorizationCode: + authorizationUrl: "/authorize" + scopes: + email: "Email address" + offline_access: "A refresh token, to renew the access token without signing\ + \ in again" + openid: "OpenID Connect sign-in" + profile: "Name, username and groups (permissions come from the groups)" + tokenUrl: "/token" + type: "oauth2" +info: + contact: + email: "contact@kingsrook.com" + description: "Native current-user printing with secondary device proof, device-control-v1\ + \ and realtime-v1; record, table-list and text printing processes." + title: "QQQ Middleware API extension: printing" + version: "2.1.0" +openapi: "3.0.3" +paths: + /qqq/v1/qbit/printing/session: + get: + description: "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." + operationId: "printingSession" + parameters: + - in: "header" + name: "X-QQQ-Device-Id" + required: false + schema: + maxLength: 36 + type: "string" + - description: "Private secondary device proof; never log." + in: "header" + name: "X-QQQ-Device-Token" + required: false + schema: + maxLength: 128 + type: "string" + responses: + 400: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Invalid request" + 401: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Native QQQ sign-in required" + 403: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Permission, device proof or user binding denied" + 404: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Record not found" + 200: + content: + application/json: + schema: + $ref: "#/components/schemas/PrintingSessionV1" + description: "Successful Response" + 409: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "State or request conflict" + 410: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Request or content expired" + 429: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Bounded capacity reached" + security: + - sessionUuidCookie: + - "N/A" + - bearerAuth: + - "N/A" + - oauth2: + - "openid" + - "profile" + - "email" + summary: "Printing Session" + tags: + - "printing" + /qqq/v1/qbit/printing/device/bind: + post: + description: "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." + operationId: "printingBind" + parameters: + - in: "header" + name: "X-QQQ-Device-Id" + required: true + schema: + maxLength: 36 + type: "string" + - description: "Private secondary device proof; never log." + in: "header" + name: "X-QQQ-Device-Token" + required: true + schema: + maxLength: 128 + type: "string" + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/PrintingEmptyV1" + required: true + responses: + 400: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Invalid request" + 401: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Native QQQ sign-in required" + 403: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Permission, device proof or user binding denied" + 404: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Record not found" + 200: + content: + application/json: + schema: + $ref: "#/components/schemas/PrintingAcknowledgmentV1" + description: "Successful Response" + 409: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "State or request conflict" + 410: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Request or content expired" + 429: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Bounded capacity reached" + security: + - sessionUuidCookie: + - "N/A" + - bearerAuth: + - "N/A" + - oauth2: + - "openid" + - "profile" + - "email" + summary: "Printing Bind" + tags: + - "printing" + /qqq/v1/qbit/printing/devices/enroll: + post: + description: "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." + operationId: "printingEnroll" + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/PrintingEnrollmentRequestV1" + required: true + responses: + 400: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Invalid request" + 401: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Native QQQ sign-in required" + 403: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Permission, device proof or user binding denied" + 404: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Record not found" + 200: + content: + application/json: + schema: + $ref: "#/components/schemas/PrintingEnrollmentV1" + description: "Successful Response" + 409: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "State or request conflict" + 410: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Request or content expired" + 429: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Bounded capacity reached" + security: + - sessionUuidCookie: + - "N/A" + - bearerAuth: + - "N/A" + - oauth2: + - "openid" + - "profile" + - "email" + summary: "Printing Enroll" + tags: + - "printing" + /qqq/v1/qbit/printing/device/heartbeat: + post: + description: "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." + operationId: "printingHeartbeat" + parameters: + - in: "header" + name: "X-QQQ-Device-Id" + required: true + schema: + maxLength: 36 + type: "string" + - description: "Private secondary device proof; never log." + in: "header" + name: "X-QQQ-Device-Token" + required: true + schema: + maxLength: 128 + type: "string" + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/PrintingHeartbeatRequestV1" + required: true + responses: + 400: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Invalid request" + 401: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Native QQQ sign-in required" + 403: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Permission, device proof or user binding denied" + 404: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Record not found" + 200: + content: + application/json: + schema: + $ref: "#/components/schemas/PrintingHeartbeatV1" + description: "Successful Response" + 409: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "State or request conflict" + 410: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Request or content expired" + 429: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Bounded capacity reached" + security: + - sessionUuidCookie: + - "N/A" + - bearerAuth: + - "N/A" + - oauth2: + - "openid" + - "profile" + - "email" + summary: "Printing Heartbeat" + tags: + - "printing" + /qqq/v1/qbit/printing/device/printers: + put: + description: "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." + operationId: "printingInventory" + parameters: + - in: "header" + name: "X-QQQ-Device-Id" + required: true + schema: + maxLength: 36 + type: "string" + - description: "Private secondary device proof; never log." + in: "header" + name: "X-QQQ-Device-Token" + required: true + schema: + maxLength: 128 + type: "string" + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/PrintingInventoryRequestV1" + required: true + responses: + 400: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Invalid request" + 401: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Native QQQ sign-in required" + 403: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Permission, device proof or user binding denied" + 404: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Record not found" + 200: + content: + application/json: + schema: + $ref: "#/components/schemas/PrintingAcknowledgmentV1" + description: "Successful Response" + 409: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "State or request conflict" + 410: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Request or content expired" + 429: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Bounded capacity reached" + security: + - sessionUuidCookie: + - "N/A" + - bearerAuth: + - "N/A" + - oauth2: + - "openid" + - "profile" + - "email" + summary: "Printing Inventory" + tags: + - "printing" + /qqq/v1/qbit/printing/device/jobs/claim: + post: + description: "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." + operationId: "printingClaim" + parameters: + - in: "header" + name: "X-QQQ-Device-Id" + required: true + schema: + maxLength: 36 + type: "string" + - description: "Private secondary device proof; never log." + in: "header" + name: "X-QQQ-Device-Token" + required: true + schema: + maxLength: 128 + type: "string" + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/PrintingEmptyV1" + required: true + responses: + 400: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Invalid request" + 401: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Native QQQ sign-in required" + 403: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Permission, device proof or user binding denied" + 404: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Record not found" + 200: + content: + application/json: + schema: + $ref: "#/components/schemas/PrintingClaimV1" + description: "Successful Response" + 409: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "State or request conflict" + 410: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Request or content expired" + 429: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Bounded capacity reached" + security: + - sessionUuidCookie: + - "N/A" + - bearerAuth: + - "N/A" + - oauth2: + - "openid" + - "profile" + - "email" + summary: "Printing Claim" + tags: + - "printing" + /qqq/v1/qbit/printing/device/jobs/queued: + get: + description: "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." + operationId: "printingQueued" + parameters: + - in: "header" + name: "X-QQQ-Device-Id" + required: true + schema: + maxLength: 36 + type: "string" + - description: "Private secondary device proof; never log." + in: "header" + name: "X-QQQ-Device-Token" + required: true + schema: + maxLength: 128 + type: "string" + responses: + 400: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Invalid request" + 401: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Native QQQ sign-in required" + 403: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Permission, device proof or user binding denied" + 404: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Record not found" + 200: + content: + application/json: + schema: + $ref: "#/components/schemas/PrintingJobsV1" + description: "Successful Response" + 409: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "State or request conflict" + 410: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Request or content expired" + 429: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Bounded capacity reached" + security: + - sessionUuidCookie: + - "N/A" + - bearerAuth: + - "N/A" + - oauth2: + - "openid" + - "profile" + - "email" + summary: "Printing Queued" + tags: + - "printing" + /qqq/v1/qbit/printing/device/jobs/{jobId}/content: + get: + description: "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." + operationId: "printingContent" + parameters: + - in: "header" + name: "X-QQQ-Device-Id" + required: true + schema: + maxLength: 36 + type: "string" + - description: "Private secondary device proof; never log." + in: "header" + name: "X-QQQ-Device-Token" + required: true + schema: + maxLength: 128 + type: "string" + - in: "path" + name: "jobId" + required: true + schema: + maxLength: 128 + type: "string" + responses: + 400: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Invalid request" + 401: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Native QQQ sign-in required" + 403: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Permission, device proof or user binding denied" + 404: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Record not found" + 200: + content: + application/octet-stream: + schema: + format: "binary" + type: "string" + description: "Verified retained document bytes" + 409: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "State or request conflict" + 410: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Request or content expired" + 429: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Bounded capacity reached" + security: + - sessionUuidCookie: + - "N/A" + - bearerAuth: + - "N/A" + - oauth2: + - "openid" + - "profile" + - "email" + summary: "Printing Content" + tags: + - "printing" + /qqq/v1/qbit/printing/device/jobs/{jobId}/events: + post: + description: "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." + operationId: "printingEvent" + parameters: + - in: "header" + name: "X-QQQ-Device-Id" + required: true + schema: + maxLength: 36 + type: "string" + - description: "Private secondary device proof; never log." + in: "header" + name: "X-QQQ-Device-Token" + required: true + schema: + maxLength: 128 + type: "string" + - in: "path" + name: "jobId" + required: true + schema: + maxLength: 128 + type: "string" + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/PrintingEventRequestV1" + required: true + responses: + 400: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Invalid request" + 401: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Native QQQ sign-in required" + 403: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Permission, device proof or user binding denied" + 404: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Record not found" + 200: + content: + application/json: + schema: + $ref: "#/components/schemas/PrintingAcknowledgmentV1" + description: "Successful Response" + 409: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "State or request conflict" + 410: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Request or content expired" + 429: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Bounded capacity reached" + security: + - sessionUuidCookie: + - "N/A" + - bearerAuth: + - "N/A" + - oauth2: + - "openid" + - "profile" + - "email" + summary: "Printing Event" + tags: + - "printing" + /qqq/v1/qbit/printing/device/test-print: + post: + description: "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." + operationId: "printingTest" + parameters: + - in: "header" + name: "X-QQQ-Device-Id" + required: true + schema: + maxLength: 36 + type: "string" + - description: "Private secondary device proof; never log." + in: "header" + name: "X-QQQ-Device-Token" + required: true + schema: + maxLength: 128 + type: "string" + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/PrintingTestRequestV1" + required: true + responses: + 400: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Invalid request" + 401: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Native QQQ sign-in required" + 403: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Permission, device proof or user binding denied" + 404: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Record not found" + 200: + content: + application/json: + schema: + $ref: "#/components/schemas/PrintingJobV1" + description: "Successful Response" + 409: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "State or request conflict" + 410: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Request or content expired" + 429: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Bounded capacity reached" + security: + - sessionUuidCookie: + - "N/A" + - bearerAuth: + - "N/A" + - oauth2: + - "openid" + - "profile" + - "email" + summary: "Printing Test" + tags: + - "printing" + /qqq/v1/qbit/printing/device/jobs/{jobId}/retry: + post: + description: "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." + operationId: "printingRetry" + parameters: + - in: "header" + name: "X-QQQ-Device-Id" + required: true + schema: + maxLength: 36 + type: "string" + - description: "Private secondary device proof; never log." + in: "header" + name: "X-QQQ-Device-Token" + required: true + schema: + maxLength: 128 + type: "string" + - in: "path" + name: "jobId" + required: true + schema: + maxLength: 128 + type: "string" + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/PrintingRetryRequestV1" + required: true + responses: + 400: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Invalid request" + 401: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Native QQQ sign-in required" + 403: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Permission, device proof or user binding denied" + 404: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Record not found" + 200: + content: + application/json: + schema: + $ref: "#/components/schemas/PrintingJobV1" + description: "Successful Response" + 409: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "State or request conflict" + 410: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Request or content expired" + 429: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Bounded capacity reached" + security: + - sessionUuidCookie: + - "N/A" + - bearerAuth: + - "N/A" + - oauth2: + - "openid" + - "profile" + - "email" + summary: "Printing Retry" + tags: + - "printing" + /qqq/v1/qbit/printing/device/jobs/{jobId}/cancel: + post: + description: "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." + operationId: "printingCancel" + parameters: + - in: "header" + name: "X-QQQ-Device-Id" + required: true + schema: + maxLength: 36 + type: "string" + - description: "Private secondary device proof; never log." + in: "header" + name: "X-QQQ-Device-Token" + required: true + schema: + maxLength: 128 + type: "string" + - in: "path" + name: "jobId" + required: true + schema: + maxLength: 128 + type: "string" + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/PrintingEmptyV1" + required: true + responses: + 400: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Invalid request" + 401: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Native QQQ sign-in required" + 403: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Permission, device proof or user binding denied" + 404: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Record not found" + 200: + content: + application/json: + schema: + $ref: "#/components/schemas/PrintingAcknowledgmentV1" + description: "Successful Response" + 409: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "State or request conflict" + 410: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Request or content expired" + 429: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Bounded capacity reached" + security: + - sessionUuidCookie: + - "N/A" + - bearerAuth: + - "N/A" + - oauth2: + - "openid" + - "profile" + - "email" + summary: "Printing Cancel" + tags: + - "printing" + /qqq/v1/qbit/printing/device/control/poll: + post: + description: "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." + operationId: "printingPoll" + parameters: + - in: "header" + name: "X-QQQ-Device-Id" + required: true + schema: + maxLength: 36 + type: "string" + - description: "Private secondary device proof; never log." + in: "header" + name: "X-QQQ-Device-Token" + required: true + schema: + maxLength: 128 + type: "string" + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/PrintingControlPollRequestV1" + required: true + responses: + 400: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Invalid request" + 401: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Native QQQ sign-in required" + 403: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Permission, device proof or user binding denied" + 404: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Record not found" + 200: + content: + application/json: + schema: + $ref: "#/components/schemas/PrintingControlPollV1" + description: "Successful Response" + 409: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "State or request conflict" + 410: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Request or content expired" + 429: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Bounded capacity reached" + security: + - sessionUuidCookie: + - "N/A" + - bearerAuth: + - "N/A" + - oauth2: + - "openid" + - "profile" + - "email" + summary: "Printing Poll" + tags: + - "printing" + /qqq/v1/qbit/printing/device/control/commands/{commandId}/receipt: + post: + description: "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." + operationId: "printingReceipt" + parameters: + - in: "header" + name: "X-QQQ-Device-Id" + required: true + schema: + maxLength: 36 + type: "string" + - description: "Private secondary device proof; never log." + in: "header" + name: "X-QQQ-Device-Token" + required: true + schema: + maxLength: 128 + type: "string" + - in: "path" + name: "commandId" + required: true + schema: + maxLength: 128 + type: "string" + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/PrintingReceiptRequestV1" + required: true + responses: + 400: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Invalid request" + 401: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Native QQQ sign-in required" + 403: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Permission, device proof or user binding denied" + 404: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Record not found" + 200: + content: + application/json: + schema: + $ref: "#/components/schemas/PrintingAcknowledgmentV1" + description: "Successful Response" + 409: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "State or request conflict" + 410: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Request or content expired" + 429: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Bounded capacity reached" + security: + - sessionUuidCookie: + - "N/A" + - bearerAuth: + - "N/A" + - oauth2: + - "openid" + - "profile" + - "email" + summary: "Printing Receipt" + tags: + - "printing" + /qqq/v1/qbit/printing/admin/devices/{deviceId}/actions: + post: + description: "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." + operationId: "printingAction" + parameters: + - in: "path" + name: "deviceId" + required: true + schema: + maxLength: 128 + type: "string" + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/PrintingActionRequestV1" + required: true + responses: + 400: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Invalid request" + 401: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Native QQQ sign-in required" + 403: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Permission, device proof or user binding denied" + 404: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Record not found" + 200: + content: + application/json: + schema: + $ref: "#/components/schemas/PrintingActionV1" + description: "Successful Response" + 409: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "State or request conflict" + 410: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Request or content expired" + 429: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Bounded capacity reached" + security: + - sessionUuidCookie: + - "N/A" + - bearerAuth: + - "N/A" + - oauth2: + - "openid" + - "profile" + - "email" + summary: "Printing Action" + tags: + - "printing" + /qqq/v1/qbit/printing/admin/devices/{deviceId}/commands: + get: + description: "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." + operationId: "printingCommands" + parameters: + - in: "path" + name: "deviceId" + required: true + schema: + maxLength: 128 + type: "string" + - description: "1 through 200; default 50." + in: "query" + name: "limit" + schema: + type: "integer" + - in: "query" + name: "before" + schema: + maxLength: 128 + type: "string" + responses: + 400: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Invalid request" + 401: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Native QQQ sign-in required" + 403: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Permission, device proof or user binding denied" + 404: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Record not found" + 200: + content: + application/json: + schema: + $ref: "#/components/schemas/PrintingActionsV1" + description: "Successful Response" + 409: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "State or request conflict" + 410: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Request or content expired" + 429: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Bounded capacity reached" + security: + - sessionUuidCookie: + - "N/A" + - bearerAuth: + - "N/A" + - oauth2: + - "openid" + - "profile" + - "email" + summary: "Printing Commands" + tags: + - "printing" + /qqq/v1/qbit/printing/admin/devices/{deviceId}/commands/{commandId}: + get: + description: "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." + operationId: "printingCommand" + parameters: + - in: "path" + name: "deviceId" + required: true + schema: + maxLength: 128 + type: "string" + - in: "path" + name: "commandId" + required: true + schema: + maxLength: 128 + type: "string" + responses: + 400: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Invalid request" + 401: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Native QQQ sign-in required" + 403: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Permission, device proof or user binding denied" + 404: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Record not found" + 200: + content: + application/json: + schema: + $ref: "#/components/schemas/PrintingActionV1" + description: "Successful Response" + 409: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "State or request conflict" + 410: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Request or content expired" + 429: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Bounded capacity reached" + security: + - sessionUuidCookie: + - "N/A" + - bearerAuth: + - "N/A" + - oauth2: + - "openid" + - "profile" + - "email" + summary: "Printing Command" + tags: + - "printing" +servers: +- description: "The QQQ server that serves this document (paths include /qqq/v1)." + url: "/" +tags: +- description: "Operations of the printing extension." + name: "printing" diff --git a/src/test/java/com/kingsrook/qbits/printing/PrintingAdmissionTest.java b/src/test/java/com/kingsrook/qbits/printing/PrintingAdmissionTest.java new file mode 100644 index 0000000..8c4e666 --- /dev/null +++ b/src/test/java/com/kingsrook/qbits/printing/PrintingAdmissionTest.java @@ -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 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 unknown sizes block new admission even when current capacity exceeds their historical estimate. + ***************************************************************************/ + @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, 200_000_000, 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 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 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, int maximum) 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); + } + } +} diff --git a/src/test/java/com/kingsrook/qbits/printing/PrintingCommandStatusTest.java b/src/test/java/com/kingsrook/qbits/printing/PrintingCommandStatusTest.java new file mode 100644 index 0000000..cd923b6 --- /dev/null +++ b/src/test/java/com/kingsrook/qbits/printing/PrintingCommandStatusTest.java @@ -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 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()); + } +} diff --git a/src/test/java/com/kingsrook/qbits/printing/PrintingContractTest.java b/src/test/java/com/kingsrook/qbits/printing/PrintingContractTest.java index cd60556..ce26e74 100644 --- a/src/test/java/com/kingsrook/qbits/printing/PrintingContractTest.java +++ b/src/test/java/com/kingsrook/qbits/printing/PrintingContractTest.java @@ -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. ***************************************************************************/ diff --git a/src/test/java/com/kingsrook/qbits/printing/PrintingDeviceControlsTest.java b/src/test/java/com/kingsrook/qbits/printing/PrintingDeviceControlsTest.java new file mode 100644 index 0000000..0839c5b --- /dev/null +++ b/src/test/java/com/kingsrook/qbits/printing/PrintingDeviceControlsTest.java @@ -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")); + } + } +} diff --git a/src/test/java/com/kingsrook/qbits/printing/PrintingDeviceProcessesTest.java b/src/test/java/com/kingsrook/qbits/printing/PrintingDeviceProcessesTest.java new file mode 100644 index 0000000..09815b5 --- /dev/null +++ b/src/test/java/com/kingsrook/qbits/printing/PrintingDeviceProcessesTest.java @@ -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()); + } +} diff --git a/src/test/java/com/kingsrook/qbits/printing/PrintingDocumentStorageTest.java b/src/test/java/com/kingsrook/qbits/printing/PrintingDocumentStorageTest.java new file mode 100644 index 0000000..eacbf68 --- /dev/null +++ b/src/test/java/com/kingsrook/qbits/printing/PrintingDocumentStorageTest.java @@ -0,0 +1,425 @@ +/* + * 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)); + } + + + /** Native StorageAction content larger than the old cap is consumed incrementally and verified. */ + @Test + void streamsLargePdfAndRejectsChangedLengthWithoutBufferingInTheAdapter() throws Exception + { + Fixture fixture = fixture(); + fixture.service.inventory(fixture.device, new JSONArray().put(new JSONObject().put("printerId", "queue").put("name", "Synthetic") + .put("formats", new JSONArray(List.of("PDF"))))); + byte[] document = new byte[21 * 1024 * 1024]; + System.arraycopy("%PDF-1.7\n".getBytes(java.nio.charset.StandardCharsets.US_ASCII), 0, document, 0, 9); + JSONObject submitted = fixture.service.submit(new JSONObject().put("deviceId", fixture.device).put("printerId", "queue").put("title", "Large synthetic PDF") + .put("format", "PDF").put("contentBase64", Base64.getEncoder().encodeToString(document)).put("idempotencyKey", "large-pdf")); + fixture.service.claim(fixture.device); + java.security.MessageDigest digest = java.security.MessageDigest.getInstance("SHA-256"); + long count = 0; + try(var stream = fixture.service.openContent(fixture.device, submitted.getString("jobId"))) + { + byte[] buffer = new byte[65536]; + int read; + while((read = stream.read(buffer)) != -1) + { + count += read; + digest.update(buffer, 0, read); + } + } + assertEquals(document.length, count); + assertEquals(submitted.getString("contentSha256"), java.util.HexFormat.of().formatHex(digest.digest())); + fixture.storage.put("printing_documents", fixture.storage.lastReference, "PDF", new byte[] {1, 2, 3}); + try(var stream = fixture.service.openContent(fixture.device, submitted.getString("jobId"))) + { + assertThrows(java.io.IOException.class, stream::readAllBytes); + } + } + + + + /*************************************************************************** + ** 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); + } + } +} + + diff --git a/src/test/java/com/kingsrook/qbits/printing/PrintingExtractTest.java b/src/test/java/com/kingsrook/qbits/printing/PrintingExtractTest.java new file mode 100644 index 0000000..2e8b8c7 --- /dev/null +++ b/src/test/java/com/kingsrook/qbits/printing/PrintingExtractTest.java @@ -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"); + } + } + } +} diff --git a/src/test/java/com/kingsrook/qbits/printing/PrintingHomeTest.java b/src/test/java/com/kingsrook/qbits/printing/PrintingHomeTest.java index 6b7447d..331a664 100644 --- a/src/test/java/com/kingsrook/qbits/printing/PrintingHomeTest.java +++ b/src/test/java/com/kingsrook/qbits/printing/PrintingHomeTest.java @@ -98,6 +98,88 @@ 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(); + } + } + + + + /*************************************************************************** + ** Slow configured heartbeats remain healthy and every explanation matches. + ***************************************************************************/ + @Test + void configuredHeartbeatTimeoutControlsFreshness() throws Exception + { + DriverDataSource source = source(); + QInstance instance = instance(source); + seed(source, "tenant-a"); + QContext.init(instance, viewer("tenant-a", true)); + try + { + PrintingService service = PrintingProcesses.currentService(); + JSONObject policy = service.getRealtimeSettings(); + policy.remove("revision"); + service.saveRealtimeSettings(policy.put("heartbeatIntervalSeconds", 300).put("heartbeatTimeoutSeconds", 900)); + try(Connection connection = source.getConnection(); PreparedStatement contact = connection.prepareStatement("UPDATE printing_device SET control_last_poll_at=? WHERE tenant_id=?")) + { + contact.setString(1, java.time.Instant.now().minusSeconds(400).toString()); + contact.setString(2, "tenant-a"); + contact.executeUpdate(); + } + StatisticsData healthy = (StatisticsData) render(instance, "printingHomeOffline"); + assertEquals(0, healthy.getCount()); + assertTrue(healthy.getCountContext().contains("900 seconds")); + assertFalse(JsonUtils.toJson(render(instance, "printingHomeAttention")).contains("No connection for")); + service.saveRealtimeSettings(policy.put("heartbeatIntervalSeconds", 20).put("heartbeatTimeoutSeconds", 60)); + StatisticsData stale = (StatisticsData) render(instance, "printingHomeOffline"); + assertEquals(1, stale.getCount()); + assertTrue(stale.getCountContext().contains("90 seconds")); + assertTrue(JsonUtils.toJson(render(instance, "printingHomeAttention")).contains("No connection for 90 seconds")); + } + finally + { + QContext.clear(); + } + } + + + /*************************************************************************** ** Empty state guides setup; an unprivileged or unscoped caller gets no data. ***************************************************************************/ @@ -105,7 +187,7 @@ class PrintingHomeTest void guidedEmptyStateAndAuthorization() throws Exception { QInstance instance = instance(source()); - QContext.init(instance, viewer("tenant-empty", true)); + QContext.init(instance, viewer("tenant-a", true)); try { String header = JsonUtils.toJson(render(instance, "printingHomeHeader")); @@ -116,7 +198,7 @@ class PrintingHomeTest TableData attention = (TableData) render(instance, "printingHomeAttention"); assertTrue(attention.getRows().isEmpty()); assertTrue(attention.getNoRowsFoundHTML().contains("No issues")); - QContext.init(instance, viewer("tenant-empty", false)); + QContext.init(instance, viewer("tenant-a", false)); assertThrows(QPermissionDeniedException.class, () -> render(instance, "printingHomeFailures")); QContext.init(instance, new QSession().withUser(new QUser().withIdReference("unscoped")).withPermission("printing_admin")); assertThrows(QPermissionDeniedException.class, () -> render(instance, "printingHomeFailures")); diff --git a/src/test/java/com/kingsrook/qbits/printing/PrintingListProcessesTest.java b/src/test/java/com/kingsrook/qbits/printing/PrintingListProcessesTest.java new file mode 100644 index 0000000..c716a82 --- /dev/null +++ b/src/test/java/com/kingsrook/qbits/printing/PrintingListProcessesTest.java @@ -0,0 +1,357 @@ +/* + * 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.util.List; +import java.util.Map; +import com.kingsrook.qqq.backend.core.actions.processes.RunProcessAction; +import com.kingsrook.qqq.backend.core.actions.tables.InsertAction; +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.RunProcessInput; +import com.kingsrook.qqq.backend.core.model.actions.processes.RunProcessOutput; +import com.kingsrook.qqq.backend.core.model.actions.tables.insert.InsertInput; +import com.kingsrook.qqq.backend.core.model.data.QRecord; +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.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.tables.Association; +import com.kingsrook.qqq.backend.core.model.metadata.tables.QFieldSection; +import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData; +import com.kingsrook.qqq.backend.core.model.metadata.tables.Tier; +import com.kingsrook.qqq.backend.core.modules.backend.implementations.memory.MemoryBackendModule; +import com.kingsrook.qqq.backend.core.modules.backend.implementations.memory.MemoryRecordStore; +import org.apache.pdfbox.pdmodel.PDDocument; +import org.apache.pdfbox.text.PDFTextStripper; +import org.json.JSONArray; +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; +import static org.junit.jupiter.api.Assertions.assertTrue; + + +/******************************************************************************* + ** Print anything: Print on every table (registerAll, opt-out), the metadata + ** record sheet with sections and child lists, the table list and text prints. + *******************************************************************************/ +class PrintingListProcessesTest +{ + /*************************************************************************** + ** Clear the memory store and context. + ***************************************************************************/ + @AfterEach + void clear() + { + MemoryRecordStore.getInstance().reset(); + QContext.clear(); + } + + + + /*************************************************************************** + ** registerAll adds Print to readable tables and honors the opt-out. + ***************************************************************************/ + @Test + void registerAllAddsPrintToEveryTableButHiddenAndOptedOut() throws Exception + { + PrintingProcessesTest.Fixture fixture = fixture(); + List added = PrintingRecordProcesses.registerAll(fixture.instance()); + assertTrue(added.contains("pet"), added::toString); + assertFalse(added.contains("person"), "person already had Print"); + assertFalse(added.contains("hiddenThing")); + assertFalse(added.contains("secretThing")); + assertTrue(fixture.instance().getProcess("printingPrintRecords_pet") != null); + assertTrue(fixture.instance().getProcess("printingPrintRecords_secretThing") == null); + assertEquals(List.of(), PrintingRecordProcesses.registerAll(fixture.instance()), "a second call adds nothing"); + assertTrue(fixture.instance().getProcess(PrintingListProcesses.TABLE_LIST) != null); + assertTrue(fixture.instance().getProcess(PrintingListProcesses.TEXT) != null); + } + + + + /*************************************************************************** + ** The record sheet follows the sections in tier order and summarizes child lists. + ***************************************************************************/ + @Test + void recordSheetHasSectionsAndChildLists() throws Exception + { + PrintingProcessesTest.Fixture fixture = fixture(); + String process = PrintingRecordProcesses.processName("person"); + var form = new RunProcessAction().execute(new RunProcessInput().withProcessName(process).withValue("recordIds", "1")); + var review = new RunProcessAction().execute(new RunProcessInput().withProcessName(process).withProcessUUID(form.getProcessUUID()) + .withStartAfterStep("printer").withValue(PrintingRecordProcesses.PRINTER_FIELD, fixture.printerId())); + new RunProcessAction().execute(new RunProcessInput().withProcessName(process).withProcessUUID(review.getProcessUUID()) + .withStartAfterStep(review.getProcessState().getNextStepName().orElseThrow()).withFrontendStepBehavior(RunProcessInput.FrontendStepBehavior.SKIP)); + String text = jobText(fixture, 0); + assertTrue(text.indexOf("Identity") < text.indexOf("Contact"), text); + assertTrue(text.contains("Email"), text); + assertTrue(text.contains("ada@example.test"), text); + assertTrue(text.contains("Other fields"), text); + assertTrue(text.contains("Pets (2)"), text); + assertTrue(text.contains("Rex") && text.contains("Tom"), text); + assertFalse(text.contains("Secret"), text); + } + + + + /*************************************************************************** + ** All rows, in the given column order and sort, with the count. + ***************************************************************************/ + @Test + void tableListOfAllRowsInColumnOrder() throws Exception + { + PrintingProcessesTest.Fixture fixture = fixture(); + RunProcessOutput output = run(PrintingListProcesses.TABLE_LIST, Map.of("tableName", "person", "columns", "lastName,firstName", "scope", "ALL", + "filterJSON", "{\"criteria\":[],\"orderBys\":[{\"fieldName\":\"lastName\",\"isAscending\":true}]}", "orientation", "PORTRAIT", + PrintingRecordProcesses.PRINTER_FIELD, fixture.printerId())); + assertEquals(1, String.valueOf(output.getValues().get(PrintingRecordProcesses.JOB_IDS)).split(",").length); + String text = jobText(fixture, 0); + assertTrue(text.contains("Last name"), text); + assertTrue(text.indexOf("Last name") < text.indexOf("First name"), text); + assertTrue(text.indexOf("Hopper") < text.indexOf("Lovelace"), text); + assertTrue(text.contains("all 2 rows"), text); + assertTrue(text.contains("sort Last name"), text); + assertTrue(text.contains("Person - printed "), "the footer names the table, time and user"); + assertTrue(text.contains("2 rows"), text); + assertTrue(fixture.service().jobs().getJSONObject(0).getString("title").startsWith("Person")); + } + + + + /*************************************************************************** + ** The current page only: the filter's skip and limit. + ***************************************************************************/ + @Test + void tableListOfThePageOnly() throws Exception + { + PrintingProcessesTest.Fixture fixture = fixture(); + run(PrintingListProcesses.TABLE_LIST, Map.of("tableName", "person", "scope", "PAGE", "title", "People page 2", + "filterJSON", "{\"criteria\":[],\"orderBys\":[{\"fieldName\":\"id\",\"isAscending\":true}],\"skip\":1,\"limit\":1}", + PrintingRecordProcesses.PRINTER_FIELD, fixture.printerId())); + String text = jobText(fixture, 0); + assertTrue(text.contains("People page 2"), text); + assertTrue(text.contains("rows 2-2 of 2"), text); + assertTrue(text.contains("Grace") && !text.contains("Lovelace"), text); + assertTrue(text.contains("Email"), "default columns are the visible fields"); + assertFalse(text.contains("Secret"), text); + } + + + + /*************************************************************************** + ** All rows of a result larger than the limit: the first rows, read a page + ** at a time, with a message saying how many were left out; the grid's + ** widths are used and AUTO turns wide lists landscape. + ***************************************************************************/ + @Test + void tableListOfAllRowsBeyondTheLimitSaysSo() throws Exception + { + PrintingProcessesTest.Fixture fixture = fixture(); + List more = new java.util.ArrayList<>(); + for(int i = 3; i <= 2500; i++) + { + more.add(new QRecord().withValue("id", i).withValue("firstName", "First" + i).withValue("lastName", "Last" + i).withValue("email", "p" + i + "@example.test").withValue("note", "note " + i)); + } + new InsertAction().execute(new InsertInput("person").withRecords(more)); + RunProcessOutput output = run(PrintingListProcesses.TABLE_LIST, Map.of("tableName", "person", "scope", "ALL", "maxRows", 2100, + "columnWidths", "4,40,40,40,40", "filterDescription", "id > 0", PrintingRecordProcesses.PRINTER_FIELD, fixture.printerId())); + assertEquals(true, output.getValues().get("printingTruncated")); + assertTrue(String.valueOf(output.getValues().get("printingMessage")).contains("first 2100 of 2500 rows"), () -> String.valueOf(output.getValues())); + String job = fixture.service().jobs().getJSONObject(0).getString("jobId"); + fixture.service().claimForJob(fixture.device(), job); + try(PDDocument document = PDDocument.load(fixture.service().content(fixture.device(), job))) + { + assertTrue(document.getPage(0).getMediaBox().getWidth() > document.getPage(0).getMediaBox().getHeight(), "AUTO chose landscape"); + assertTrue(document.getNumberOfPages() > 30, "pages: " + document.getNumberOfPages()); + String text = new PDFTextStripper().getText(document); + assertTrue(text.contains("first 2100 of 2500 rows (print limit 2100)"), text.substring(0, 400)); + assertTrue(text.contains("filter id > 0")); + assertTrue(text.contains("2100 rows")); + assertTrue(text.contains("First2100") && !text.contains("First2101 "), "rows stop at the limit"); + PDFTextStripper last = new PDFTextStripper(); + last.setStartPage(document.getNumberOfPages()); + String lastPage = last.getText(document); + assertTrue(lastPage.contains("Id") && lastPage.contains("First name"), "the header repeats on every page"); + } + } + + + + /*************************************************************************** + ** Unknown columns, opted-out tables and too many rows are refused. + ***************************************************************************/ + @Test + void tableListRefusals() throws Exception + { + PrintingProcessesTest.Fixture fixture = fixture(); + assertThrows(QException.class, () -> run(PrintingListProcesses.TABLE_LIST, Map.of("tableName", "person", "columns", "nope", PrintingRecordProcesses.PRINTER_FIELD, fixture.printerId()))); + assertThrows(QException.class, () -> run(PrintingListProcesses.TABLE_LIST, Map.of("tableName", "secretThing", PrintingRecordProcesses.PRINTER_FIELD, fixture.printerId()))); + assertThrows(QException.class, () -> run(PrintingListProcesses.TABLE_LIST, Map.of("tableName", "person", "scope", "ALL", "maxRows", 999999, PrintingRecordProcesses.PRINTER_FIELD, fixture.printerId()))); + assertEquals(0, fixture.service().jobs().length()); + } + + + + /*************************************************************************** + ** Text prints monospace, wraps long lines and breaks pages. + ***************************************************************************/ + @Test + void textPrintsAScreenCapture() throws Exception + { + PrintingProcessesTest.Fixture fixture = fixture(); + StringBuilder screen = new StringBuilder("+-- Dashboard --+\n| sales 1,234 |\n" + "x".repeat(300) + "\n"); + for(int i = 0; i < 150; i++) + { + screen.append("line ").append(i).append('\n'); + } + run(PrintingListProcesses.TEXT, Map.of("title", "Dashboard", "subtitle", "qqq ui", "text", screen.toString(), PrintingRecordProcesses.PRINTER_FIELD, fixture.printerId())); + JSONArray jobs = fixture.service().jobs(); + assertEquals("Dashboard", jobs.getJSONObject(0).getString("title")); + fixture.service().claimForJob(fixture.device(), jobs.getJSONObject(0).getString("jobId")); + try(PDDocument document = PDDocument.load(fixture.service().content(fixture.device(), jobs.getJSONObject(0).getString("jobId")))) + { + assertTrue(document.getNumberOfPages() > 1); + String text = new PDFTextStripper().getText(document); + assertTrue(text.contains("| sales 1,234 |"), text); + assertTrue(text.contains("line 149"), text); + } + assertThrows(QException.class, () -> run(PrintingListProcesses.TEXT, Map.of("text", "", PrintingRecordProcesses.PRINTER_FIELD, fixture.printerId()))); + } + + + + /*************************************************************************** + ** A 150-column terminal capture keeps its lines on a landscape page (the + ** font shrinks to fit); much wider text still wraps at the smallest size. + ***************************************************************************/ + @Test + void wideScreenCaptureFitsWithoutWrapping() throws Exception + { + String wide = "| " + "y".repeat(146) + " |"; + try(PDDocument document = PDDocument.load(PrintingTextDocuments.pdf("Screen", "", wide + "\n" + wide, "LETTER", true))) + { + assertTrue(new PDFTextStripper().getText(document).contains(wide)); + } + assertEquals(8f, PrintingTextDocuments.fontSize(new String[] {"short"}, 1000), 0.01); + assertEquals(PrintingTextDocuments.MIN_FONT_SIZE, PrintingTextDocuments.fontSize(new String[] {"z".repeat(5000)}, 1000), 0.01); + } + + + + /*************************************************************************** + ** Column widths shrink widest-first to fit, never below four. + ***************************************************************************/ + @Test + void columnWidthsFitTheLine() + { + int[] widths = PrintingLayout.columnWidths(List.of("Id", "Name", "Notes"), List.of(List.of("1", "Ada", "x".repeat(200))), 40); + assertTrue(widths[0] + widths[1] + widths[2] + 4 <= 40); + assertEquals(4, widths[0]); + assertArrayEquals(new int[] {4, 4}, PrintingLayout.columnWidths(List.of("A", "B"), List.of(), 3)); + assertEquals("1 Ada", PrintingLayout.row(List.of("1", "Ada"), new int[] {4, 4})); + } + + + + /*************************************************************************** + ** Run a process straight through with values. + ***************************************************************************/ + private static RunProcessOutput run(String process, Map values) throws QException + { + RunProcessInput input = new RunProcessInput().withProcessName(process).withFrontendStepBehavior(RunProcessInput.FrontendStepBehavior.SKIP); + // as the UI API runs it: user input, so server-configured inputs would be refused + input.setInputSource(com.kingsrook.qqq.backend.core.model.actions.tables.QInputSource.USER); + values.forEach(input::withValue); + RunProcessOutput output = new RunProcessAction().execute(input); + if(output.getException().isPresent()) + { + throw new QException(output.getException().get()); + } + return (output); + } + + + + /*************************************************************************** + ** The text of the n-th newest job's PDF. + ***************************************************************************/ + private static String jobText(PrintingProcessesTest.Fixture fixture, int index) throws Exception + { + String job = fixture.service().jobs().getJSONObject(index).getString("jobId"); + fixture.service().claimForJob(fixture.device(), job); + try(PDDocument document = PDDocument.load(fixture.service().content(fixture.device(), job))) + { + return (new PDFTextStripper().getText(document)); + } + } + + + + /*************************************************************************** + ** The process fixture plus person (sections, pets), pet, a hidden and an + ** opted-out table, on the memory backend. + ***************************************************************************/ + private static PrintingProcessesTest.Fixture fixture() throws Exception + { + PrintingProcessesTest.Fixture fixture = PrintingProcessesTest.fixture(); + QInstance instance = fixture.instance(); + instance.addBackend(new QBackendMetaData().withName("memory").withBackendType(MemoryBackendModule.class)); + instance.addTable(new QTableMetaData().withName("person").withLabel("Person").withBackendName("memory").withPrimaryKeyField("id") + .withRecordLabelFormat("%s %s").withRecordLabelFields(List.of("firstName", "lastName")) + .withField(new QFieldMetaData("id", QFieldType.INTEGER).withLabel("Id")) + .withField(new QFieldMetaData("firstName", QFieldType.STRING).withLabel("First name")) + .withField(new QFieldMetaData("lastName", QFieldType.STRING).withLabel("Last name")) + .withField(new QFieldMetaData("email", QFieldType.STRING).withLabel("Email")) + .withField(new QFieldMetaData("note", QFieldType.STRING).withLabel("Note")) + .withField(new QFieldMetaData("secret", QFieldType.STRING).withLabel("Secret").withIsHidden(true)) + .withSection(new QFieldSection("contact", "Contact", null, Tier.T2, List.of("email"))) + .withSection(new QFieldSection("identity", "Identity", null, Tier.T1, List.of("id", "firstName", "lastName"))) + .withAssociation(new Association().withName("pets").withAssociatedTableName("pet").withJoinName("personPet"))); + instance.addTable(new QTableMetaData().withName("pet").withLabel("Pet").withBackendName("memory").withPrimaryKeyField("id") + .withField(new QFieldMetaData("id", QFieldType.INTEGER).withLabel("Id")) + .withField(new QFieldMetaData("personId", QFieldType.INTEGER).withLabel("Owner")) + .withField(new QFieldMetaData("name", QFieldType.STRING).withLabel("Name"))); + instance.addJoin(new QJoinMetaData().withName("personPet").withLeftTable("person").withRightTable("pet").withType(JoinType.ONE_TO_MANY).withJoinOn(new JoinOn("id", "personId"))); + instance.addTable(new QTableMetaData().withName("hiddenThing").withBackendName("memory").withPrimaryKeyField("id").withIsHidden(true) + .withField(new QFieldMetaData("id", QFieldType.INTEGER))); + instance.addTable(new QTableMetaData().withName("secretThing").withLabel("Secret thing").withBackendName("memory").withPrimaryKeyField("id") + .withSupplementalMetaData(new PrintingTableSettings().withPrintable(false)) + .withField(new QFieldMetaData("id", QFieldType.INTEGER))); + PrintingRecordProcesses.register(instance, "person"); + new InsertAction().execute(new InsertInput("person").withRecords(List.of( + new QRecord().withValue("id", 1).withValue("firstName", "Ada").withValue("lastName", "Lovelace").withValue("email", "ada@example.test").withValue("note", "n").withValue("secret", "x"), + new QRecord().withValue("id", 2).withValue("firstName", "Grace").withValue("lastName", "Hopper").withValue("email", "grace@example.test")))); + new InsertAction().execute(new InsertInput("pet").withRecords(List.of( + new QRecord().withValue("id", 1).withValue("personId", 1).withValue("name", "Rex"), + new QRecord().withValue("id", 2).withValue("personId", 1).withValue("name", "Tom"), + new QRecord().withValue("id", 3).withValue("personId", 2).withValue("name", "Kit")))); + return (fixture); + } +} diff --git a/src/test/java/com/kingsrook/qbits/printing/PrintingLocalHostTest.java b/src/test/java/com/kingsrook/qbits/printing/PrintingLocalHostTest.java new file mode 100644 index 0000000..39b31d2 --- /dev/null +++ b/src/test/java/com/kingsrook/qbits/printing/PrintingLocalHostTest.java @@ -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 = 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 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 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 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 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())); + } +} diff --git a/src/test/java/com/kingsrook/qbits/printing/PrintingMaintenanceTest.java b/src/test/java/com/kingsrook/qbits/printing/PrintingMaintenanceTest.java new file mode 100644 index 0000000..7c23d43 --- /dev/null +++ b/src/test/java/com/kingsrook/qbits/printing/PrintingMaintenanceTest.java @@ -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 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 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 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)); + } +} + diff --git a/src/test/java/com/kingsrook/qbits/printing/PrintingMigrationTest.java b/src/test/java/com/kingsrook/qbits/printing/PrintingMigrationTest.java index 8470478..febb21d 100644 --- a/src/test/java/com/kingsrook/qbits/printing/PrintingMigrationTest.java +++ b/src/test/java/com/kingsrook/qbits/printing/PrintingMigrationTest.java @@ -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. ***************************************************************************/ diff --git a/src/test/java/com/kingsrook/qbits/printing/PrintingPoolTest.java b/src/test/java/com/kingsrook/qbits/printing/PrintingPoolTest.java new file mode 100644 index 0000000..a9f0176 --- /dev/null +++ b/src/test/java/com/kingsrook/qbits/printing/PrintingPoolTest.java @@ -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 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); + } + } +} diff --git a/src/test/java/com/kingsrook/qbits/printing/PrintingProcessesTest.java b/src/test/java/com/kingsrook/qbits/printing/PrintingProcessesTest.java index 5fdbb6e..d51e349 100644 --- a/src/test/java/com/kingsrook/qbits/printing/PrintingProcessesTest.java +++ b/src/test/java/com/kingsrook/qbits/printing/PrintingProcessesTest.java @@ -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(); + 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) { } } diff --git a/src/test/java/com/kingsrook/qbits/printing/PrintingRealtimeProcessesTest.java b/src/test/java/com/kingsrook/qbits/printing/PrintingRealtimeProcessesTest.java new file mode 100644 index 0000000..1e5e33a --- /dev/null +++ b/src/test/java/com/kingsrook/qbits/printing/PrintingRealtimeProcessesTest.java @@ -0,0 +1,201 @@ +/* + * 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.math.BigDecimal; +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.layout.QAppMetaData; +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.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.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + + +/******************************************************************************* + ** Native settings forms preserve exact values and enforce current authority. + *******************************************************************************/ +class PrintingRealtimeProcessesTest +{ + /*************************************************************************** + ** Opening settings cannot save them until the operator passes native review. + ***************************************************************************/ + @Test + void nativeReviewIsReadOnly() throws Exception + { + PrintingService service = fixture(); + var preview = new RunProcessAction().execute(new RunProcessInput().withProcessName(PrintingRealtimeProcesses.SETTINGS)); + assertFalse(preview.getException().isPresent(), () -> preview.getException().toString()); + assertEquals("review", preview.getProcessState().getNextStepName().orElseThrow()); + assertEquals(0, service.getRealtimeSettings().getLong("revision")); + } + + + + /*************************************************************************** + ** Large PDFs and fractional human units round-trip without a fixed 20 MiB cap. + ***************************************************************************/ + @Test + void exactPolicyPersistsAndRejectsPartialOrInconsistentEdits() throws Exception + { + PrintingService service = fixture(); + RunBackendStepInput save = prepared(PrintingRealtimeProcesses.SETTINGS); + save.addValue("maxPdfMiB", new BigDecimal("250.5")); + save.addValue("maxConcurrentDownloads", 3); + new PrintingRealtimeProcesses().run(save, new RunBackendStepOutput()); + assertEquals(262668288L, service.getRealtimeSettings().getLong("maxPdfBytes")); + assertEquals(3, service.getRealtimeSettings().getInt("maxConcurrentDownloads")); + assertEquals(1, service.getRealtimeSettings().getLong("revision")); + RunBackendStepInput fractionalByte = prepared(PrintingRealtimeProcesses.SETTINGS).addValue("maxPdfMiB", new BigDecimal("0.1")); + assertThrows(QException.class, () -> new PrintingRealtimeProcesses().run(fractionalByte, new RunBackendStepOutput())); + RunBackendStepInput tooLittleDisk = prepared(PrintingRealtimeProcesses.SETTINGS).addValue("maxStagedMiB", 1); + assertThrows(QException.class, () -> new PrintingRealtimeProcesses().run(tooLittleDisk, new RunBackendStepOutput())); + assertThrows(QException.class, () -> new PrintingRealtimeProcesses().run(input(PrintingRealtimeProcesses.SETTINGS, "execute"), new RunBackendStepOutput())); + assertEquals(1, service.getRealtimeSettings().getLong("revision")); + } + + + + /*************************************************************************** + ** Backend invocation cannot bypass either tenant scope or administrator role. + ***************************************************************************/ + @Test + void currentUserAndTenantAreRequired() throws Exception + { + fixture(); + QInstance instance = QContext.getQInstance(); + RunBackendStepInput save = prepared(PrintingRealtimeProcesses.SETTINGS); + QContext.init(instance, session("foreign", true)); + assertThrows(QPermissionDeniedException.class, () -> new PrintingRealtimeProcesses().run(save, new RunBackendStepOutput())); + QContext.init(instance, session("tenant-a", false)); + assertThrows(QPermissionDeniedException.class, () -> new PrintingRealtimeProcesses().run(save, new RunBackendStepOutput())); + } + + + + /*************************************************************************** + ** Queue limits use the same typed native forms and survive new service objects. + ***************************************************************************/ + @Test + void admissionSettingsPersistAndRejectInvalidCapacity() throws Exception + { + PrintingService service = fixture(); + RunBackendStepInput save = prepared(PrintingRealtimeProcesses.ADMISSION).addValue("deviceJobsPerHour", 15000).addValue("deviceOutstandingMiB", new BigDecimal("10240.5")); + new PrintingRealtimeProcesses().run(save, new RunBackendStepOutput()); + assertEquals(15000, service.getAdmissionSettings().getInt("deviceJobsPerHour")); + assertEquals(10737942528L, service.getAdmissionSettings().getLong("deviceOutstandingBytes")); + RunBackendStepInput zero = prepared(PrintingRealtimeProcesses.ADMISSION).addValue("devicePrinters", 0); + assertThrows(QException.class, () -> new PrintingRealtimeProcesses().run(zero, new RunBackendStepOutput())); + assertTrue(service.getAdmissionSettings().getInt("devicePrinters") > 0); + } + + + + /*************************************************************************** + ** Prepared form values exercise the same complete fields used by the UI. + ***************************************************************************/ + private static RunBackendStepInput prepared(String process) throws Exception + { + RunBackendStepOutput output = new RunBackendStepOutput(); + new PrintingRealtimeProcesses().run(input(process, "prepare"), output); + RunBackendStepInput save = input(process, "execute"); + output.getValues().forEach(save::addValue); + return (save); + } + + + + /*************************************************************************** + ** Each test owns a database and normal authenticated tenant session. + ***************************************************************************/ + private static PrintingService fixture() throws Exception + { + DriverDataSource source = new DriverDataSource("jdbc:h2:mem:realtime-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))); + instance.addQBit(new QBitMetaData().withGroupId("com.kingsrook.qbits").withArtifactId("qbit-printing").withVersion("test").withNamespace("printing").withConfig(new PrintingQBitConfig().withService(service))); + QAppMetaData app = new QAppMetaData().withName("printing").withLabel("Printing"); + PrintingRealtimeProcesses.register(instance, app); + instance.addApp(app); + instance.withInstanceDefaultAuthentication(new QAuthenticationMetaData().withName("mock").withType(com.kingsrook.qqq.backend.core.model.metadata.QAuthenticationType.MOCK)); + QContext.init(instance, session("tenant-a", true)); + return (service); + } + + + + /*************************************************************************** + ** Negative authorization cases retain a real user to test role and tenant. + ***************************************************************************/ + private static QSession session(String tenant, boolean administrator) + { + QSession session = new QSession().withUser(new QUser().withIdReference("operator")).withSecurityKeyValue("printing_tenant", tenant); + if(administrator) + { + session.withPermissions("printing_admin"); + } + return (session); + } + + + + /*************************************************************************** + ** Backend entrypoints use explicit process and step names. + ***************************************************************************/ + private static RunBackendStepInput input(String process, String step) + { + RunBackendStepInput input = new RunBackendStepInput().withProcessName(process); + input.setStepName(step); + return (input); + } + + + + /*************************************************************************** + ** Never leak current tenant authority into another test. + ***************************************************************************/ + @AfterEach + void cleanup() + { + QContext.clear(); + } +} diff --git a/src/test/java/com/kingsrook/qbits/printing/PrintingRealtimeTest.java b/src/test/java/com/kingsrook/qbits/printing/PrintingRealtimeTest.java new file mode 100644 index 0000000..7821981 --- /dev/null +++ b/src/test/java/com/kingsrook/qbits/printing/PrintingRealtimeTest.java @@ -0,0 +1,330 @@ +/* + * 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.UUID; +import java.util.concurrent.TimeUnit; +import java.util.concurrent.atomic.AtomicReference; +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.assertNotEquals; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + + +/** Real native authentication and WebSocket lifecycle with durable synthetic jobs only. */ +public class PrintingRealtimeTest +{ + @TempDir + Path directory; + + + /** A transport ping while disconnected proves contact, never state application or normal heartbeat. */ + private static void disconnectedPingUpdatesContactOnly(PrintingService service, String device, PrintingSocketFixture socket) throws Exception + { + service.deviceAction(device, action("DISCONNECT"), "operator"); + JSONObject desired = socket.take("DESIRED_STATE").getJSONObject("payload"); + while(!"DISCONNECTED".equals(desired.getString("connectionState"))) + { + desired = socket.take("DESIRED_STATE").getJSONObject("payload"); + } + JSONObject before = deviceSnapshot(service, device); + long applied = before.getJSONObject("control").getLong("lastAppliedRevision"); + assertTrue(applied < desired.getLong("revision")); + Instant sent = Instant.now(); + socket.send("PING", "disconnected-contact", new JSONObject()); + socket.take("PONG"); + JSONObject after = deviceSnapshot(service, device); + assertFalse(Instant.parse(after.getJSONObject("control").getString("lastPollAt")).isBefore(sent)); + assertEquals(applied, after.getJSONObject("control").getLong("lastAppliedRevision")); + assertEquals(before.getString("lastSeenAt"), after.getString("lastSeenAt")); + assertEquals("DISCONNECTED", after.getJSONObject("control").getJSONObject("desiredState").getString("connectionState")); + } + + + /** Select the exact synthetic device when the shared-bus test has created others. */ + private static JSONObject deviceSnapshot(PrintingService service, String device) throws Exception + { + for(Object value : service.devices()) + { + JSONObject row = (JSONObject) value; + if(device.equals(row.getString("deviceId"))) + { + return (row); + } + } + throw new AssertionError("Synthetic device was not found"); + } + + + /** Commit wakeups, exact receipts, replacement and revocation all use actual QQQ sessions. */ + @Test + void authenticatedPushReconcilesDurableWorkWithoutHttpControlPolling() throws Exception + { + String jdbc = "jdbc:h2:file:" + directory.resolve("realtime").toString().replace('\\', '/'); + PrintingLocalHost host = new PrintingLocalHost(new PrintingLocalSettings(jdbc, "sa", "", "demo", 0, "synthetic-management-token-long-enough", "operator", "synthetic-realtime-password-1234")); + AtomicReference app = new AtomicReference<>(); + QApplicationLauncher launcher = QApplicationLauncher.run(host, new QApplicationLauncherConfig().withRegisterShutdownHook(false).withServerCustomizer(server -> + { + host.configure(server, false); + server.withJavalinConfigurationCustomizer(app::set); + })); + PrintingService service = launcher.getQInstance().getQBits().values().stream().map(value -> value.getConfig()).filter(PrintingQBitConfig.class::isInstance) + .map(PrintingQBitConfig.class::cast).findFirst().orElseThrow().getService(); + String base = "http://127.0.0.1:" + app.get().port(); + JSONObject enrolled = service.enrollForUser(service.createEnrollment("default", "Synthetic realtime").put("deviceName", "Synthetic realtime").put("agentVersion", "test"), "operator"); + 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("status", "READY").put("formats", new JSONArray().put("ZPL")))); + service.enablePrinter(device, "queue", true); + try(HttpClient http = HttpClient.newHttpClient()) + { + String cookie = login(http, base); + assertThrows(Exception.class, () -> PrintingSocketFixture.connect(http, base, "sessionUUID=invalid", device, proof)); + assertThrows(Exception.class, () -> PrintingSocketFixture.connect(http, base, cookie, device, "wrong-proof")); + try(PrintingSocketFixture first = PrintingSocketFixture.connect(http, base, cookie, device, proof)) + { + first.take("JOB_AVAILABLE"); + first.send("INVENTORY", "idle-inventory", new JSONObject().put("printers", new JSONArray().put(new JSONObject().put("printerId", "queue") + .put("name", "Synthetic queue").put("status", "READY").put("formats", new JSONArray().put("ZPL"))))); + assertEquals("idle-inventory", first.take("ACK").getJSONObject("payload").getString("acknowledgedMessageId")); + org.junit.jupiter.api.Assertions.assertNull(first.received.poll(300, TimeUnit.MILLISECONDS), "Idle inventory must not create a self-sustaining job wakeup"); + sharedBusRoundTrip(launcher, service, jdbc, http, cookie, device, first); + first.received.clear(); + String job = service.submit(request(device, "one")).getString("jobId"); + first.take("JOB_AVAILABLE"); + assertEquals(job, service.claim(device).getJSONObject("job").getString("jobId")); + JSONObject event = new JSONObject().put("eventId", "stable-event").put("status", "RECEIVED"); + first.send("JOB_EVENT", "event-stable-event", new JSONObject().put("jobId", job).put("event", event)); + assertEquals("event-stable-event", first.take("ACK").getJSONObject("payload").getString("acknowledgedMessageId")); + assertEquals("RECEIVED", service.getJob(job).getString("status")); + JSONObject policy = service.getRealtimeSettings(); + policy.remove("revision"); + service.saveRealtimeSettings(policy.put("maxCopies", 99)); + assertEquals(1, first.take("SETTINGS").getJSONObject("payload").getLong("revision")); + first.apply(0, 0); + assertEquals(409, assertThrows(PrintingException.class, () -> service.requireRealtimeReady(device)).getStatus()); + first.apply(0, 1); + service.requireRealtimeReady(device); + JSONObject pause = service.deviceAction(device, action("PAUSE_DISPATCH"), "operator"); + JSONObject desired = first.take("DESIRED_STATE").getJSONObject("payload"); + while(!desired.getBoolean("dispatchPaused")) + { + desired = first.take("DESIRED_STATE").getJSONObject("payload"); + } + first.apply(desired.getLong("revision"), 1); + assertTrue(service.claim(device).isNull("job")); + assertFalse(pause.isEmpty()); + JSONObject command = service.deviceAction(device, action("REFRESH_INVENTORY"), "operator"); + JSONObject pushed = first.take("COMMAND").getJSONObject("payload"); + assertEquals(command.getString("commandId"), pushed.getString("commandId")); + JSONObject receipt = new JSONObject().put("receiptId", "stable-receipt").put("outcome", "INVENTORY_REFRESHED").put("completedAt", Instant.now().toString()); + JSONObject delivery = new JSONObject().put("commandId", pushed.getString("commandId")).put("receipt", receipt); + first.send("COMMAND_RECEIPT", "receipt-stable-receipt", delivery); + first.take("ACK"); + first.send("COMMAND_RECEIPT", "receipt-pruned", new JSONObject().put("commandId", UUID.randomUUID().toString()).put("receipt", receipt)); + assertEquals("NOT_FOUND", first.take("ERROR").getJSONObject("payload").getString("code")); + first.send("PING", "after-pruned-receipt", new JSONObject()); + first.take("PONG"); + try(PrintingSocketFixture second = PrintingSocketFixture.connect(http, base, cookie, device, proof)) + { + assertEquals(1008, first.closed.get(10, TimeUnit.SECONDS)); + second.send("COMMAND_RECEIPT", "receipt-stable-receipt", delivery); + assertEquals("receipt-stable-receipt", second.take("ACK").getJSONObject("payload").getString("acknowledgedMessageId")); + second.send("JOB_EVENT", "event-stable-event", new JSONObject().put("jobId", job).put("event", event)); + second.take("ACK"); + assertEquals("RECEIVED", service.getJob(job).getString("status")); + disconnectedPingUpdatesContactOnly(service, device, second); + service.deviceAction(device, action("REVOKE"), "operator"); + assertEquals(1008, second.closed.get(10, TimeUnit.SECONDS)); + } + } + authenticationChangesAreImmediate(launcher, service, http, base, cookie); + } + finally + { + launcher.stop(); + } + } + + + /** Cookie variants, changed provider roles, channel policy and logout are checked after upgrade. */ + private static void authenticationChangesAreImmediate(QApplicationLauncher launcher, PrintingService service, HttpClient http, String base, String cookie) throws Exception + { + JSONObject enrolled = service.enrollForUser(service.createEnrollment("default", "Authentication fixture").put("deviceName", "Authentication fixture").put("agentVersion", "test"), "operator"); + String device = enrolled.getString("deviceId"); + String proof = enrolled.getString("deviceToken"); + var table = launcher.getQInstance().getTable(PrintingTables.DEVICE); + var originalRules = table.getPermissionRules(); + try(PrintingSocketFixture channel = PrintingSocketFixture.connect(http, base, cookie.replace("sessionUUID=", "sessionId="), device, proof)) + { + table.withPermissionRules(PrintingProcesses.permissionRules().withDeniedClients(java.util.Set.of("api"))); + channel.send("PING", "channel-denied", new JSONObject()); + assertEquals("AUTHORIZATION_REQUIRED", channel.take("ERROR").getJSONObject("payload").getString("code")); + assertEquals(1008, channel.closed.get(10, TimeUnit.SECONDS)); + } + finally + { + table.withPermissionRules(originalRules); + } + var auth = launcher.getQInstance().getAuthentication(); + var originalModule = auth.getModuleCodeReference(); + try(PrintingSocketFixture channel = PrintingSocketFixture.connect(http, base, cookie, device, proof)) + { + auth.withModuleCodeReference(new com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference(RemovedRoleAuthentication.class)); + service.getRealtimeBus().publish("demo", device); + assertEquals("AUTHORIZATION_REQUIRED", channel.take("ERROR").getJSONObject("payload").getString("code")); + assertEquals(1008, channel.closed.get(10, TimeUnit.SECONDS)); + } + finally + { + auth.withModuleCodeReference(originalModule); + } + try(PrintingSocketFixture channel = PrintingSocketFixture.connect(http, base, cookie, device, proof)) + { + HttpResponse logout = http.send(HttpRequest.newBuilder(URI.create(base + "/qqq/v1/logout")).header("Origin", base).header("Cookie", cookie) + .header("Content-Type", "application/json").POST(HttpRequest.BodyPublishers.ofString("{}")).build(), HttpResponse.BodyHandlers.ofString()); + assertEquals(200, logout.statusCode()); + channel.send("PING", "logged-out", new JSONObject()); + assertEquals("AUTHORIZATION_REQUIRED", channel.take("ERROR").getJSONObject("payload").getString("code")); + assertEquals(1008, channel.closed.get(10, TimeUnit.SECONDS)); + } + } + + + /** Native authentication still verifies the actual password/session; only current role membership changes. */ + public static class RemovedRoleAuthentication extends PrintingLocalAuthentication + { + @Override + public com.kingsrook.qqq.backend.core.model.session.QSession createSession(com.kingsrook.qqq.backend.core.model.metadata.QInstance instance, java.util.Map context) + throws com.kingsrook.qqq.backend.core.exceptions.QAuthenticationException + { + var session = super.createSession(instance, context); + session.setPermissions(java.util.Set.of()); + return (session); + } + } + + + /** Two independent route providers receive only their scoped commit wakeups through an explicitly shared bus. */ + private static void sharedBusRoundTrip(QApplicationLauncher launcher, PrintingService service, String jdbc, HttpClient http, String cookie, String firstDevice, PrintingSocketFixture first) throws Exception + { + PrintingService sibling = new PrintingService(new DriverDataSource(jdbc, "sa", ""), "demo").withRealtimeBus(service.getRealtimeBus()); + PrintingRealtimeRoutes routes = new PrintingRealtimeRoutes(sibling); + routes.setQInstance(launcher.getQInstance()); + Javalin other = Javalin.create(config -> + { + config.jetty.host = "127.0.0.1"; + routes.acceptJavalinConfig(config); + }).start(0); + JSONObject enrolled = service.enrollForUser(service.createEnrollment("default", "Second synthetic device").put("deviceName", "Second synthetic device").put("agentVersion", "test"), "operator"); + String secondDevice = enrolled.getString("deviceId"); + service.inventory(secondDevice, new JSONArray().put(new JSONObject().put("printerId", "queue").put("name", "Synthetic queue").put("formats", new JSONArray().put("ZPL")))); + service.enablePrinter(secondDevice, "queue", true); + try(PrintingSocketFixture second = PrintingSocketFixture.open(http, "http://127.0.0.1:" + other.port(), cookie, secondDevice, enrolled.getString("deviceToken"))) + { + String early = service.submit(request(secondDevice, "commit-between-upgrade-and-hello")).getString("jobId"); + second.initialize(); + second.take("JOB_AVAILABLE"); + assertEquals("QUEUED", sibling.getJob(early).getString("status")); + sibling.cancel(secondDevice, early); + first.received.clear(); + second.received.clear(); + String firstJob = sibling.submit(request(firstDevice, "other-service-to-first-hub")).getString("jobId"); + first.take("JOB_AVAILABLE"); + String secondJob = service.submit(request(secondDevice, "first-service-to-other-hub")).getString("jobId"); + second.take("JOB_AVAILABLE"); + assertEquals("QUEUED", sibling.getJob(firstJob).getString("status")); + assertEquals("QUEUED", service.getJob(secondJob).getString("status")); + service.cancel(firstDevice, firstJob); + sibling.cancel(secondDevice, secondJob); + } + finally + { + other.stop(); + } + } + + + /** A real browser login supplies only its own temporary test session. */ + private static String login(HttpClient client, String base) throws Exception + { + HttpRequest request = HttpRequest.newBuilder(URI.create(base + "/qqq/v1/manageSession")).header("Origin", base) + .header("Authorization", "Basic " + Base64.getEncoder().encodeToString("operator:synthetic-realtime-password-1234".getBytes(StandardCharsets.UTF_8))) + .header("Content-Type", "application/json").POST(HttpRequest.BodyPublishers.ofString("{}")).build(); + HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString()); + assertEquals(200, response.statusCode()); + return (response.headers().allValues("set-cookie").stream().filter(value -> value.startsWith("sessionUUID=")).findFirst().orElseThrow().split(";", 2)[0]); + } + + + /** Stable synthetic submission identity; no physical printer exists in this fixture. */ + private static JSONObject request(String device, String key) + { + return (new JSONObject().put("deviceId", device).put("printerId", "queue").put("title", "Synthetic realtime") + .put("format", "ZPL").put("contentBase64", Base64.getEncoder().encodeToString("^XA^XZ".getBytes(StandardCharsets.US_ASCII))).put("idempotencyKey", key)); + } + + + /** Native actions retain their existing temporal replay boundary. */ + private static JSONObject action(String name) + { + return (new JSONObject().put("action", name).put("requestId", UUID.randomUUID().toString()).put("issuedAt", Instant.now().toString())); + } + + + /** Policy updates preserve validation, tenant isolation and durable revisions. */ + @Test + void policyRejectsInconsistentLimitsAndPersistsRevisions() throws Exception + { + DriverDataSource source = new DriverDataSource("jdbc:h2:mem:policy-" + UUID.randomUUID() + ";DB_CLOSE_DELAY=-1", "sa", ""); + PrintingService first = new PrintingService(source, "one"); + first.initialize(); + PrintingService other = new PrintingService(source, "two"); + JSONObject values = first.getRealtimeSettings(); + assertEquals(104857600, values.getInt("maxPdfBytes")); + values.remove("revision"); + JSONObject invalid = new JSONObject(values.toString()).put("heartbeatTimeoutSeconds", 10); + assertThrows(PrintingException.class, () -> first.saveRealtimeSettings(invalid)); + assertThrows(PrintingException.class, () -> first.saveRealtimeSettings(new JSONObject(values.toString()).put("maxCopies", 1.5))); + values.put("maxPdfBytes", 30 * 1024 * 1024); + assertEquals(1, first.saveRealtimeSettings(values).getLong("revision")); + assertEquals(1, new PrintingService(source, "one").getRealtimeSettings().getLong("revision")); + assertNotEquals(first.getRealtimeSettings().getLong("maxPdfBytes"), other.getRealtimeSettings().getLong("maxPdfBytes")); + assertThrows(PrintingException.class, () -> PrintingRealtimePolicy.defaults().requireClientLimits(new JSONObject().put("maxPdfBytes", 1))); + } +} diff --git a/src/test/java/com/kingsrook/qbits/printing/PrintingRecordProcessesTest.java b/src/test/java/com/kingsrook/qbits/printing/PrintingRecordProcessesTest.java new file mode 100644 index 0000000..37fb1dc --- /dev/null +++ b/src/test/java/com/kingsrook/qbits/printing/PrintingRecordProcessesTest.java @@ -0,0 +1,242 @@ +/* + * 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.util.LinkedHashMap; +import java.util.List; +import java.util.Map; +import com.kingsrook.qqq.backend.core.actions.processes.QProcessCallback; +import com.kingsrook.qqq.backend.core.actions.processes.RunProcessAction; +import com.kingsrook.qqq.backend.core.actions.tables.InsertAction; +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.RunProcessInput; +import com.kingsrook.qqq.backend.core.model.actions.tables.insert.InsertInput; +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.QQueryFilter; +import com.kingsrook.qqq.backend.core.model.data.QRecord; +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.processes.QFrontendStepMetaData; +import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData; +import com.kingsrook.qqq.backend.core.modules.backend.implementations.memory.MemoryBackendModule; +import com.kingsrook.qqq.backend.core.modules.backend.implementations.memory.MemoryRecordStore; +import org.apache.pdfbox.pdmodel.PDDocument; +import org.apache.pdfbox.text.PDFTextStripper; +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.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; + + +/******************************************************************************* + ** Record printing: the per-table Print process and the record sheet document. + *******************************************************************************/ +class PrintingRecordProcessesTest +{ + /*************************************************************************** + ** Clear the shared memory store and context between tests. + ***************************************************************************/ + @AfterEach + void clear() + { + MemoryRecordStore.getInstance().reset(); + QContext.clear(); + } + + + + /*************************************************************************** + ** Printer form, review, then one queued PDF job per selected record. + ***************************************************************************/ + @Test + void printsEachSelectedRecordOnceAndReturnsTheJobIds() throws Exception + { + PrintingProcessesTest.Fixture fixture = fixtureWithPeople(); + String process = PrintingRecordProcesses.processName("person"); + assertEquals("printingPrintRecords_person", process); + QFrontendStepMetaData printerStep = (QFrontendStepMetaData) fixture.instance().getProcess(process).getStep("printer"); + assertEquals(PrintingTables.PRINTER, printerStep.getFormField(PrintingRecordProcesses.PRINTER_FIELD).getPossibleValueSourceName()); + + var form = new RunProcessAction().execute(new RunProcessInput().withProcessName(process).withValue("recordIds", "1,2")); + assertFalse(form.getException().isPresent(), () -> form.getException().toString()); + assertEquals("printer", form.getProcessState().getNextStepName().orElseThrow()); + var review = new RunProcessAction().execute(new RunProcessInput().withProcessName(process).withProcessUUID(form.getProcessUUID()) + .withStartAfterStep("printer").withValue(PrintingRecordProcesses.PRINTER_FIELD, fixture.printerId()).withValue(PrintingRecordProcesses.COPIES_FIELD, 2)); + assertFalse(review.getException().isPresent(), () -> review.getException().toString()); + assertEquals(0, fixture.service().jobs().length(), "review must not print"); + var done = new RunProcessAction().execute(new RunProcessInput().withProcessName(process).withProcessUUID(review.getProcessUUID()) + .withStartAfterStep(review.getProcessState().getNextStepName().orElseThrow()).withFrontendStepBehavior(RunProcessInput.FrontendStepBehavior.SKIP)); + assertFalse(done.getException().isPresent(), () -> done.getException().toString()); + + JSONArray jobs = fixture.service().jobs(); + assertEquals(2, jobs.length()); + String ids = String.valueOf(done.getValues().get(PrintingRecordProcesses.JOB_IDS)); + assertEquals(2, ids.split(",").length); + for(int i = 0; i < jobs.length(); i++) + { + JSONObject job = jobs.getJSONObject(i); + assertTrue(ids.contains(job.getString("jobId"))); + assertEquals("PDF", job.getString("format")); + assertTrue(job.getString("title").startsWith("Person: ")); + assertEquals(2, job.getJSONObject("options").getInt("copies")); + fixture.service().claimForJob(fixture.device(), job.getString("jobId")); + byte[] content = fixture.service().content(fixture.device(), job.getString("jobId")); + try(PDDocument document = PDDocument.load(content)) + { + String text = new PDFTextStripper().getText(document); + assertTrue(text.contains("Person:")); + assertTrue(text.contains("First name")); + assertTrue(text.contains("Ada") || text.contains("Grace")); + assertFalse(text.contains("Secret"), "hidden fields are not printed"); + } + } + } + + + + /*************************************************************************** + ** The UI API passes the selection only to init (as the callback filter); + ** the selection must survive the printer form that comes before review. + ***************************************************************************/ + @Test + void keepsTheInitSelectionAcrossThePrinterForm() throws Exception + { + PrintingProcessesTest.Fixture fixture = fixtureWithPeople(); + String process = PrintingRecordProcesses.processName("person"); + var form = new RunProcessAction().execute(new RunProcessInput().withProcessName(process).withCallback(new QProcessCallback() + { + @Override + public QQueryFilter getQueryFilter() + { + return (new QQueryFilter(new QFilterCriteria("id", QCriteriaOperator.IN, List.of(2)))); + } + + + + @Override + public Map getFieldValues(List fields) + { + return (Map.of()); + } + })); + var review = new RunProcessAction().execute(new RunProcessInput().withProcessName(process).withProcessUUID(form.getProcessUUID()) + .withStartAfterStep("printer").withValue(PrintingRecordProcesses.PRINTER_FIELD, fixture.printerId())); + new RunProcessAction().execute(new RunProcessInput().withProcessName(process).withProcessUUID(review.getProcessUUID()) + .withStartAfterStep(review.getProcessState().getNextStepName().orElseThrow()).withFrontendStepBehavior(RunProcessInput.FrontendStepBehavior.SKIP)); + JSONArray jobs = fixture.service().jobs(); + assertEquals(1, jobs.length()); + assertTrue(jobs.getJSONObject(0).getString("title").contains("Grace")); + } + + + + /*************************************************************************** + ** A printer that is not approved (or not exposed) is refused at review. + ***************************************************************************/ + @Test + void refusesAPrinterThatIsNotApproved() throws Exception + { + PrintingProcessesTest.Fixture fixture = fixtureWithPeople(); + String process = PrintingRecordProcesses.processName("person"); + var device = fixture.service(); + device.enablePrinter(fixture.device(), "laser", false); + var form = new RunProcessAction().execute(new RunProcessInput().withProcessName(process).withValue("recordIds", "1")); + QException refused = assertThrows(QException.class, () -> new RunProcessAction().execute(new RunProcessInput().withProcessName(process).withProcessUUID(form.getProcessUUID()) + .withStartAfterStep("printer").withValue(PrintingRecordProcesses.PRINTER_FIELD, fixture.printerId()))); + assertTrue(refused.getMessage().contains("approved"), refused::getMessage); + assertEquals(0, fixture.service().jobs().length()); + } + + + + /*************************************************************************** + ** Unknown tables are refused at registration. + ***************************************************************************/ + @Test + void registerRefusesAnUnknownTable() throws Exception + { + PrintingProcessesTest.Fixture fixture = PrintingProcessesTest.fixture(); + assertThrows(QException.class, () -> PrintingRecordProcesses.register(fixture.instance(), "nope")); + } + + + + /*************************************************************************** + ** Long values wrap, long documents continue on more pages, unencodable + ** characters are replaced rather than failing the render. + ***************************************************************************/ + @Test + void recordSheetWrapsAndContinuesAcrossPages() throws Exception + { + Map fields = new LinkedHashMap<>(); + fields.put("Notes", "word ".repeat(400)); + for(int i = 0; i < 80; i++) + { + fields.put("Field " + i, "value " + i + " 中文"); + } + fields.put("Empty", null); + byte[] bytes = PrintingRecordDocuments.pdf("Person: Ada Lovelace", "Person 1", fields); + try(PDDocument document = PDDocument.load(bytes)) + { + assertTrue(document.getNumberOfPages() > 1); + String text = new PDFTextStripper().getText(document); + assertTrue(text.contains("Field 79")); + assertTrue(text.contains("(continued)")); + assertTrue(text.contains("Page 2 of ")); + } + assertEquals(List.of("abc", "def"), PrintingRecordDocuments.wrap("abc def", 4)); + assertEquals(List.of("abcd", "ef"), PrintingRecordDocuments.wrap("abcdef", 4)); + assertEquals("ab~", PrintingRecordDocuments.truncate("abcdef", 3)); + } + + + + /*************************************************************************** + ** The process fixture plus a memory "person" table with two records. + ***************************************************************************/ + private static PrintingProcessesTest.Fixture fixtureWithPeople() throws Exception + { + PrintingProcessesTest.Fixture fixture = PrintingProcessesTest.fixture(); + QInstance instance = fixture.instance(); + instance.addBackend(new QBackendMetaData().withName("memory").withBackendType(MemoryBackendModule.class)); + instance.addTable(new QTableMetaData().withName("person").withLabel("Person").withBackendName("memory").withPrimaryKeyField("id") + .withRecordLabelFormat("%s %s").withRecordLabelFields(List.of("firstName", "lastName")) + .withField(new QFieldMetaData("id", QFieldType.INTEGER).withLabel("Id")) + .withField(new QFieldMetaData("firstName", QFieldType.STRING).withLabel("First name")) + .withField(new QFieldMetaData("lastName", QFieldType.STRING).withLabel("Last name")) + .withField(new QFieldMetaData("secret", QFieldType.STRING).withLabel("Secret").withIsHidden(true))); + PrintingRecordProcesses.register(instance, "person"); + new InsertAction().execute(new InsertInput("person").withRecords(List.of( + new QRecord().withValue("id", 1).withValue("firstName", "Ada").withValue("lastName", "Lovelace").withValue("secret", "x"), + new QRecord().withValue("id", 2).withValue("firstName", "Grace").withValue("lastName", "Hopper")))); + return (fixture); + } +} diff --git a/src/test/java/com/kingsrook/qbits/printing/PrintingRetentionProcessesTest.java b/src/test/java/com/kingsrook/qbits/printing/PrintingRetentionProcessesTest.java new file mode 100644 index 0000000..2ca990b --- /dev/null +++ b/src/test/java/com/kingsrook/qbits/printing/PrintingRetentionProcessesTest.java @@ -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).addValue("batchSize", 100); + 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(); + } +} diff --git a/src/test/java/com/kingsrook/qbits/printing/PrintingServiceTest.java b/src/test/java/com/kingsrook/qbits/printing/PrintingServiceTest.java index c3034a3..baca170 100644 --- a/src/test/java/com/kingsrook/qbits/printing/PrintingServiceTest.java +++ b/src/test/java/com/kingsrook/qbits/printing/PrintingServiceTest.java @@ -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")); diff --git a/src/test/java/com/kingsrook/qbits/printing/PrintingSocketFixture.java b/src/test/java/com/kingsrook/qbits/printing/PrintingSocketFixture.java new file mode 100644 index 0000000..f40c7f3 --- /dev/null +++ b/src/test/java/com/kingsrook/qbits/printing/PrintingSocketFixture.java @@ -0,0 +1,157 @@ +/* + * 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.WebSocket; +import java.util.concurrent.BlockingQueue; +import java.util.concurrent.CompletableFuture; +import java.util.concurrent.CompletionStage; +import java.util.concurrent.LinkedBlockingQueue; +import java.util.concurrent.TimeUnit; +import org.json.JSONArray; +import org.json.JSONObject; +import static org.junit.jupiter.api.Assertions.assertNotNull; + + +/** Real native WebSocket client shared by the HTTP and realtime integration fixtures. */ +final class PrintingSocketFixture implements WebSocket.Listener, AutoCloseable +{ + final BlockingQueue received = new LinkedBlockingQueue<>(); + final CompletableFuture closed = new CompletableFuture<>(); + private final StringBuilder text = new StringBuilder(); + private WebSocket socket; + + + /** Authenticate with the normal session cookie and secondary proof headers. */ + static PrintingSocketFixture connect(HttpClient client, String base, String cookie, String device, String proof) throws Exception + { + PrintingSocketFixture fixture = open(client, base, cookie, device, proof); + fixture.initialize(); + return (fixture); + } + + + /** Separate upgrade from HELLO so a commit in that interval can be tested deterministically. */ + static PrintingSocketFixture open(HttpClient client, String base, String cookie, String device, String proof) throws Exception + { + PrintingSocketFixture fixture = new PrintingSocketFixture(); + fixture.socket = client.newWebSocketBuilder().subprotocols(PrintingRealtimeRoutes.SUBPROTOCOL).header("Origin", base) + .header("X-QQQ-Client", "api/qqq-print-agent") + .header("Cookie", cookie).header(PrintingAgentAuthorization.DEVICE_HEADER, device).header(PrintingAgentAuthorization.TOKEN_HEADER, proof) + .buildAsync(URI.create(base.replace("http:", "ws:") + PrintingRealtimeRoutes.PATH), fixture).get(10, TimeUnit.SECONDS); + return (fixture); + } + + + /** Reconcile after the connection's subscription is already registered. */ + void initialize() throws Exception + { + send("HELLO", "hello", new JSONObject().put("agentVersion", "synthetic-test").put("capabilities", new JSONArray().put("realtime-v1").put("REFRESH_INVENTORY").put("CANCEL_SPOOL")) + .put("lastAppliedRevision", 0).put("lastSettingsRevision", 0).put("limits", PrintingRealtimePolicy.defaults().toJson(0))); + JSONObject welcome = take("WELCOME").getJSONObject("payload"); + apply(welcome.getJSONObject("desiredState").getLong("revision"), welcome.getJSONObject("settings").getLong("revision")); + } + + + /** Observe application ACK before allowing a dependent HTTP claim. */ + void apply(long state, long settings) throws Exception + { + send("STATE_APPLIED", "applied", new JSONObject().put("lastAppliedRevision", state).put("lastSettingsRevision", settings)); + take("ACK"); + } + + + /** Send one explicit protocol operation, never a timed query. */ + void send(String type, String id, JSONObject payload) + { + socket.sendText(new JSONObject().put("type", type).put("messageId", id).put("payload", payload).toString(), true).join(); + } + + + /** Bounded waiting diagnoses absent pushes without introducing a polling loop. */ + JSONObject take(String type) throws Exception + { + long end = System.nanoTime() + TimeUnit.SECONDS.toNanos(10); + while(System.nanoTime() < end) + { + JSONObject next = received.poll(Math.max(1, end - System.nanoTime()), TimeUnit.NANOSECONDS); + assertNotNull(next, "Expected realtime frame " + type); + if("ERROR".equals(next.getString("type")) && !"ERROR".equals(type)) + { + throw new AssertionError("Realtime rejected synthetic test message: " + next.getJSONObject("payload")); + } + if(type.equals(next.getString("type"))) + { + return (next); + } + } + throw new AssertionError("No frame " + type); + } + + + @Override + public void onOpen(WebSocket webSocket) + { + webSocket.request(1); + } + + + @Override + public CompletionStage onText(WebSocket webSocket, CharSequence data, boolean last) + { + text.append(data); + if(last) + { + received.add(new JSONObject(text.toString())); + text.setLength(0); + } + webSocket.request(1); + return (null); + } + + + @Override + public CompletionStage onClose(WebSocket webSocket, int statusCode, String reason) + { + closed.complete(statusCode); + return (null); + } + + + @Override + public void onError(WebSocket webSocket, Throwable error) + { + closed.completeExceptionally(error); + } + + + @Override + public void close() + { + if(socket != null) + { + socket.abort(); + } + } +} diff --git a/src/test/java/com/kingsrook/qbits/printing/PrintingStorageBindingTest.java b/src/test/java/com/kingsrook/qbits/printing/PrintingStorageBindingTest.java new file mode 100644 index 0000000..6c70741 --- /dev/null +++ b/src/test/java/com/kingsrook/qbits/printing/PrintingStorageBindingTest.java @@ -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 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 objects = new HashMap<>(); + private final List 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, int maximum) + { + 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); + } + } +} diff --git a/src/test/java/com/kingsrook/qbits/printing/PrintingTestDocumentsExport.java b/src/test/java/com/kingsrook/qbits/printing/PrintingTestDocumentsExport.java new file mode 100644 index 0000000..e943e93 --- /dev/null +++ b/src/test/java/com/kingsrook/qbits/printing/PrintingTestDocumentsExport.java @@ -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()); + } + } + } +} + diff --git a/src/test/java/com/kingsrook/qbits/printing/PrintingTestDocumentsTest.java b/src/test/java/com/kingsrook/qbits/printing/PrintingTestDocumentsTest.java new file mode 100644 index 0000000..59c1d23 --- /dev/null +++ b/src/test/java/com/kingsrook/qbits/printing/PrintingTestDocumentsTest.java @@ -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)); + } +} + diff --git a/src/test/java/com/kingsrook/qbits/printing/PrintingUiApiContractTest.java b/src/test/java/com/kingsrook/qbits/printing/PrintingUiApiContractTest.java new file mode 100644 index 0000000..c31bef0 --- /dev/null +++ b/src/test/java/com/kingsrook/qbits/printing/PrintingUiApiContractTest.java @@ -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), 2, + "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("2.1.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()); + } +} diff --git a/src/test/java/com/kingsrook/qbits/printing/PrintingUiApiTest.java b/src/test/java/com/kingsrook/qbits/printing/PrintingUiApiTest.java new file mode 100644 index 0000000..b09589b --- /dev/null +++ b/src/test/java/com/kingsrook/qbits/printing/PrintingUiApiTest.java @@ -0,0 +1,378 @@ +/* + * 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 = 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 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(409, send(client, base, prefix + "/device/jobs/claim", "POST", new JSONObject(), cookie, device, proof).statusCode()); + PrintingSocketFixture channel = PrintingSocketFixture.connect(client, base, cookie, device, proof); + assertEquals(job, json(send(client, base, prefix + "/device/jobs/claim", "POST", new JSONObject(), cookie, device, proof), 200).getJSONObject("job").getString("jobId")); + HttpResponse 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()); + channel.close(); + 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 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 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 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 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 response, int status) + { + assertEquals(status, response.statusCode()); + return (new JSONObject(new String(response.body(), StandardCharsets.UTF_8))); + } +} diff --git a/src/test/java/com/kingsrook/qbits/printing/PrintingWorkloadTest.java b/src/test/java/com/kingsrook/qbits/printing/PrintingWorkloadTest.java new file mode 100644 index 0000000..6af87df --- /dev/null +++ b/src/test/java/com/kingsrook/qbits/printing/PrintingWorkloadTest.java @@ -0,0 +1,255 @@ +/* + * 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.nio.file.Files; +import java.nio.file.Path; +import java.time.Instant; +import java.util.ArrayList; +import java.util.Base64; +import java.util.HashSet; +import java.util.List; +import java.util.Set; +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 org.h2.jdbcx.JdbcConnectionPool; +import org.json.JSONArray; +import org.json.JSONObject; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.Timeout; +import org.junit.jupiter.api.condition.EnabledIfSystemProperty; +import org.junit.jupiter.api.io.TempDir; +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.assertTrue; + + +/******************************************************************************* + ** Opt-in service workload: real file-backed SQL and receipts, never a printer. + *******************************************************************************/ +@EnabledIfSystemProperty(named = "printing.qualification.load", matches = "true") +class PrintingWorkloadTest +{ + private static final int LANES = 8; + private static final int JOBS_PER_LANE = 1250; + private static final byte[] CONTENT = ("^XA^FO20,20^FDSYNTHETIC - NOT SENT TO A PRINTER^FS" + " ".repeat(970) + "^XZ").getBytes(StandardCharsets.UTF_8); + + @TempDir + Path directory; + + + /*************************************************************************** + ** Run a day's sizing target through actual admission, claim and persistence. + ***************************************************************************/ + @Test + @Timeout(value = 10, unit = TimeUnit.MINUTES) + void completesTenThousandJobsWithReplayAndColdReopen() throws Exception + { + String jdbc = "jdbc:h2:file:" + directory.resolve("workload").toAbsolutePath().toString().replace('\\', '/'); + JdbcConnectionPool pool = JdbcConnectionPool.create(jdbc, "sa", ""); + pool.setMaxConnections(4); + pool.setLoginTimeout(15); + List> expected = List.of(ConcurrentHashMap.newKeySet(), ConcurrentHashMap.newKeySet()); + List> lanes = new ArrayList<>(); + CountDownLatch start = new CountDownLatch(1); + new PrintingService(pool, "tenant-0").initialize(); + for(int lane = 0; lane < LANES; lane++) + { + String tenant = "tenant-" + (lane % 2); + PrintingService service = new PrintingService(pool, tenant); + String device = enroll(service, lane); + int laneIndex = lane; + lanes.add(() -> + { + start.await(); + return runLane(pool, tenant, device, laneIndex, expected.get(laneIndex % 2)); + }); + } + long began = System.nanoTime(); + List durations = new ArrayList<>(); + try + { + try(var executor = Executors.newFixedThreadPool(LANES)) + { + var futures = lanes.stream().map(executor::submit).toList(); + start.countDown(); + for(var future : futures) + { + for(long duration : future.get(8, TimeUnit.MINUTES)) + { + durations.add(duration); + } + } + } + for(int tenant = 0; tenant < 2; tenant++) + { + verifyHistory(new PrintingService(pool, "tenant-" + tenant), expected.get(tenant)); + } + verifyAccounting(pool); + assertEquals(0, pool.getActiveConnections()); + } + finally + { + pool.dispose(); + } + // All pooled connections close before reopening. No application initialize repairs the database. + JdbcConnectionPool reopened = JdbcConnectionPool.create(jdbc, "sa", ""); + try + { + verifyAccounting(reopened); + for(int tenant = 0; tenant < 2; tenant++) + { + verifyHistory(new PrintingService(reopened, "tenant-" + tenant), expected.get(tenant)); + } + } + finally + { + reopened.dispose(); + } + double seconds = (System.nanoTime() - began) / 1_000_000_000.0; + long[] sorted = durations.stream().mapToLong(Long::longValue).sorted().toArray(); + JSONObject report = new JSONObject().put("completedAt", Instant.now().toString()).put("jobs", sorted.length) + .put("tenants", 2).put("devices", LANES).put("poolConnections", 4).put("bytesPerDocument", CONTENT.length) + .put("elapsedSeconds", seconds).put("jobsPerSecond", sorted.length / seconds) + .put("p50LifecycleMillis", sorted[sorted.length / 2] / 1_000_000.0) + .put("p95LifecycleMillis", sorted[(int) (sorted.length * 0.95)] / 1_000_000.0) + .put("p99LifecycleMillis", sorted[(int) (sorted.length * 0.99)] / 1_000_000.0) + .put("replayedSubmissions", LANES * (JOBS_PER_LANE / 25)).put("replayedReceipts", sorted.length) + .put("coldReopenVerified", true).put("physicalPrinting", false).put("httpOrS3Throughput", false) + .put("javaVersion", System.getProperty("java.version")).put("os", System.getProperty("os.name")); + Path reportPath = Path.of("target", "qualification", "service-workload.json"); + Files.createDirectories(reportPath.getParent()); + Files.writeString(reportPath, report.toString(2)); + } + + + /*************************************************************************** + ** Each lane represents one device with serial physical submission semantics. + ***************************************************************************/ + private static long[] runLane(JdbcConnectionPool pool, String tenant, String device, int lane, Set expected) throws Exception + { + PrintingService service = new PrintingService(pool, tenant); + long[] durations = new long[JOBS_PER_LANE]; + for(int index = 0; index < JOBS_PER_LANE; index++) + { + long began = System.nanoTime(); + JSONObject request = new JSONObject().put("deviceId", device).put("printerId", "synthetic") + .put("title", "Synthetic workload " + index).put("format", "ZPL").put("contentBase64", Base64.getEncoder().encodeToString(CONTENT)) + .put("idempotencyKey", "lane-" + lane + "-job-" + index); + String job = service.submit(request).getString("jobId"); + assertTrue(expected.add(job)); + if(index % 25 == 0) + { + assertEquals(job, service.submit(request).getString("jobId")); + } + assertEquals(job, service.claim(device).getJSONObject("job").getString("jobId")); + assertArrayEquals(CONTENT, service.content(device, job)); + for(String status : List.of("RECEIVED", "SUBMITTING", "SPOOLED")) + { + JSONObject event = new JSONObject().put("eventId", "lane-" + lane + "-job-" + index + "-" + status).put("status", status); + if("SPOOLED".equals(status)) + { + event.put("spoolerJobId", "synthetic-" + index); + } + service.event(device, job, event); + if("SPOOLED".equals(status)) + { + service.event(device, job, event); + } + } + durations[index] = System.nanoTime() - began; + } + assertTrue(service.claim(device).isNull("job")); + return (durations); + } + + + /*************************************************************************** + ** Service pagination must return every completed job once, without bytes. + ***************************************************************************/ + private static void verifyHistory(PrintingService service, Set expected) throws Exception + { + Set actual = new HashSet<>(); + String cursor = null; + do + { + JSONObject page = service.jobsPage(137, cursor); + JSONArray jobs = page.getJSONArray("jobs"); + assertTrue(jobs.length() <= 137); + for(int index = 0; index < jobs.length(); index++) + { + JSONObject job = jobs.getJSONObject(index); + assertTrue(actual.add(job.getString("jobId"))); + assertEquals("SPOOLED", job.getString("status")); + assertFalse(job.has("contentBase64")); + } + cursor = page.isNull("nextCursor") ? null : page.getString("nextCursor"); + } + while(cursor != null); + assertEquals(expected, actual); + assertEquals(LANES * JOBS_PER_LANE / 2, actual.size()); + } + + + /*************************************************************************** + ** Replays do not inflate stored receipts, retained bytes or queue size. + ***************************************************************************/ + private static void verifyAccounting(JdbcConnectionPool pool) throws Exception + { + try(var connection = pool.getConnection(); var statement = connection.createStatement()) + { + for(String sql : List.of("SELECT COUNT(*) FROM printing_job WHERE status='SPOOLED'", "SELECT COUNT(*) FROM printing_event", + "SELECT SUM(retained_bytes) / " + CONTENT.length + " FROM printing_resource_usage WHERE device_id=''")) + { + try(var rows = statement.executeQuery(sql)) + { + assertTrue(rows.next()); + assertEquals((long) LANES * JOBS_PER_LANE * (sql.contains("printing_event") ? 3 : 1), rows.getLong(1)); + } + } + try(var rows = statement.executeQuery("SELECT COUNT(*) FROM printing_document_orphan")) + { + assertTrue(rows.next()); + assertEquals(0, rows.getLong(1)); + } + } + } + + + /*************************************************************************** + ** Explicit synthetic enrollment and approval never target any Windows queue. + ***************************************************************************/ + private static String enroll(PrintingService service, int lane) throws Exception + { + String device = service.enroll(service.createEnrollment("fixture", "lane-" + lane) + .put("deviceName", "lane-" + lane).put("agentVersion", "qualification")).getString("deviceId"); + service.inventory(device, new JSONArray().put(new JSONObject().put("printerId", "synthetic").put("name", "Synthetic only") + .put("formats", new JSONArray(List.of("ZPL"))))); + service.enablePrinter(device, "synthetic", true); + return (device); + } +} \ No newline at end of file diff --git a/src/test/resources/log4j2-test.xml b/src/test/resources/log4j2-test.xml index 9ed980c..c9077d0 100644 --- a/src/test/resources/log4j2-test.xml +++ b/src/test/resources/log4j2-test.xml @@ -1 +1,6 @@ + + diff --git a/src/test/resources/openapi/printing-1.0.0.yaml b/src/test/resources/openapi/printing-1.0.0.yaml new file mode 100644 index 0000000..88032c2 --- /dev/null +++ b/src/test/resources/openapi/printing-1.0.0.yaml @@ -0,0 +1,2078 @@ +components: + schemas: + BasicErrorResponseV1: + description: "The error body of every UI API operation (core and extensions)." + properties: + error: + description: "The error message (the same as message; kept for clients of\ + \ UI API 1.0 to 1.5)." + type: "string" + code: + description: "A stable, machine-readable code. Well-known values: BAD_REQUEST\ + \ (400), UNAUTHENTICATED (401),\nPERMISSION_DENIED (403), NOT_FOUND (404),\ + \ CONFLICT (409), RATE_LIMITED (429), INTERNAL_ERROR (500),\nERROR (other).\ + \ Extensions may add codes; treat an unknown code by the HTTP status.\ + \ Since 1.6.0." + type: "string" + message: + description: "A message to show the user. Since 1.6.0." + type: "string" + fieldErrors: + description: "Errors about particular request fields, when known. Since\ + \ 1.6.0." + items: + properties: + field: + description: "The field (or parameter) name." + type: "string" + message: + description: "The error about that field." + type: "string" + code: + description: "An optional machine-readable code, e.g. REQUIRED, TOO_LONG,\ + \ PATTERN." + type: "string" + type: "object" + type: "array" + traceId: + description: "Identifies this request in the server logs (also the X-QQQ-Trace-Id\ + \ response header); quote it when reporting a problem. Since 1.6.0." + type: "string" + type: "object" + PrintingAcknowledgmentV1: + properties: + accepted: + type: "boolean" + required: + - "accepted" + type: "object" + PrintingActionRequestV1: + properties: + requestId: + maxLength: 128 + type: "string" + issuedAt: + description: "RFC3339 UTC ending in uppercase Z." + format: "date-time" + maxLength: 40 + type: "string" + action: + enum: + - "PAUSE_DISPATCH" + - "RESUME_DISPATCH" + - "DISCONNECT" + - "RECONNECT" + - "REVOKE" + - "REFRESH_INVENTORY" + - "CLEAR_QUEUE" + - "CANCEL_SPOOL" + type: "string" + jobId: + maxLength: 128 + type: "string" + required: + - "requestId" + - "issuedAt" + - "action" + type: "object" + PrintingActionV1: + properties: + commandId: + maxLength: 128 + type: "string" + requestId: + maxLength: 128 + type: "string" + issuedAt: + description: "RFC3339 UTC ending in uppercase Z." + format: "date-time" + maxLength: 40 + type: "string" + deviceId: + maxLength: 128 + type: "string" + action: + enum: + - "PAUSE_DISPATCH" + - "RESUME_DISPATCH" + - "DISCONNECT" + - "RECONNECT" + - "REVOKE" + - "REFRESH_INVENTORY" + - "CLEAR_QUEUE" + - "CANCEL_SPOOL" + type: "string" + status: + enum: + - "PENDING" + - "SUCCEEDED" + - "FAILED" + - "EXPIRED" + - "OUTCOME_UNKNOWN" + type: "string" + createdAt: + description: "RFC3339 UTC ending in uppercase Z." + format: "date-time" + maxLength: 40 + type: "string" + expiresAt: + description: "RFC3339 UTC ending in uppercase Z." + format: "date-time" + maxLength: 40 + type: "string" + jobId: + maxLength: 128 + type: "string" + resultCode: + maxLength: 80 + type: "string" + cancelledJobCount: + type: "integer" + receipt: + $ref: "#/components/schemas/PrintingReceiptRequestV1" + required: + - "commandId" + - "requestId" + - "issuedAt" + - "deviceId" + - "action" + - "status" + - "createdAt" + - "expiresAt" + type: "object" + PrintingActionsV1: + properties: + commands: + items: + $ref: "#/components/schemas/PrintingActionV1" + type: "array" + nextCursor: + maxLength: 128 + nullable: true + type: "string" + required: + - "commands" + - "nextCursor" + type: "object" + PrintingClaimV1: + properties: + job: + $ref: "#/components/schemas/PrintingJobV1" + nullable: true + required: + - "job" + type: "object" + PrintingCommandV1: + properties: + commandId: + maxLength: 128 + type: "string" + requestId: + maxLength: 128 + type: "string" + action: + enum: + - "REFRESH_INVENTORY" + - "CANCEL_SPOOL" + type: "string" + createdAt: + description: "RFC3339 UTC ending in uppercase Z." + format: "date-time" + maxLength: 40 + type: "string" + expiresAt: + description: "RFC3339 UTC ending in uppercase Z." + format: "date-time" + maxLength: 40 + type: "string" + jobId: + maxLength: 128 + type: "string" + required: + - "commandId" + - "requestId" + - "action" + - "createdAt" + - "expiresAt" + type: "object" + PrintingControlPollRequestV1: + properties: + controlVersion: + type: "integer" + agentVersion: + maxLength: 100 + type: "string" + capabilities: + items: + enum: + - "REFRESH_INVENTORY" + - "CANCEL_SPOOL" + type: "string" + type: "array" + lastAppliedRevision: + type: "integer" + required: + - "controlVersion" + - "agentVersion" + - "capabilities" + - "lastAppliedRevision" + type: "object" + PrintingControlPollV1: + properties: + controlVersion: + type: "integer" + serverTime: + description: "RFC3339 UTC ending in uppercase Z." + format: "date-time" + maxLength: 40 + type: "string" + pollIntervalSeconds: + type: "integer" + desiredState: + $ref: "#/components/schemas/PrintingDesiredStateV1" + commands: + items: + $ref: "#/components/schemas/PrintingCommandV1" + type: "array" + required: + - "controlVersion" + - "serverTime" + - "pollIntervalSeconds" + - "desiredState" + - "commands" + type: "object" + PrintingDesiredStateV1: + properties: + revision: + type: "integer" + dispatchPaused: + type: "boolean" + connectionState: + enum: + - "CONNECTED" + - "DISCONNECTED" + type: "string" + required: + - "revision" + - "dispatchPaused" + - "connectionState" + type: "object" + PrintingEmptyV1: + type: "object" + PrintingEnrollmentRequestV1: + properties: + enrollmentCode: + maxLength: 128 + type: "string" + deviceName: + maxLength: 1024 + type: "string" + agentVersion: + maxLength: 100 + type: "string" + required: + - "enrollmentCode" + - "deviceName" + - "agentVersion" + type: "object" + PrintingEnrollmentV1: + properties: + protocolVersion: + type: "integer" + deviceId: + maxLength: 128 + type: "string" + deviceToken: + description: "Private device proof, returned once; never log." + maxLength: 128 + type: "string" + pollIntervalSeconds: + type: "integer" + required: + - "protocolVersion" + - "deviceId" + - "deviceToken" + - "pollIntervalSeconds" + type: "object" + PrintingEventRequestV1: + properties: + eventId: + maxLength: 128 + type: "string" + status: + enum: + - "RECEIVED" + - "SUBMITTING" + - "SPOOLED" + - "SPOOLER_COMPLETED" + - "FAILED" + - "OUTCOME_UNKNOWN" + type: "string" + message: + maxLength: 2048 + type: "string" + spoolerJobId: + maxLength: 128 + type: "string" + required: + - "eventId" + - "status" + type: "object" + PrintingHeartbeatRequestV1: + properties: + agentVersion: + maxLength: 100 + type: "string" + profile: + $ref: "#/components/schemas/PrintingProfileV1" + required: + - "agentVersion" + type: "object" + PrintingHeartbeatV1: + properties: + serverTime: + description: "RFC3339 UTC ending in uppercase Z." + format: "date-time" + maxLength: 40 + type: "string" + required: + - "serverTime" + type: "object" + PrintingInventoryRequestV1: + properties: + printers: + items: + $ref: "#/components/schemas/PrintingPrinterV1" + type: "array" + required: + - "printers" + type: "object" + PrintingJobV1: + properties: + jobId: + maxLength: 128 + type: "string" + deviceId: + maxLength: 128 + type: "string" + printerId: + maxLength: 128 + type: "string" + title: + maxLength: 1024 + type: "string" + format: + enum: + - "PDF" + - "ZPL" + type: "string" + contentSha256: + maxLength: 64 + type: "string" + contentLength: + type: "integer" + options: + $ref: "#/components/schemas/PrintingOptionsV1" + createdAt: + description: "RFC3339 UTC ending in uppercase Z." + format: "date-time" + maxLength: 40 + type: "string" + status: + enum: + - "QUEUED" + - "CLAIMED" + - "RECEIVED" + - "SUBMITTING" + - "SPOOLED" + - "SPOOLER_COMPLETED" + - "FAILED" + - "OUTCOME_UNKNOWN" + type: "string" + message: + maxLength: 2048 + type: "string" + spoolerJobId: + maxLength: 128 + type: "string" + required: + - "jobId" + - "deviceId" + - "printerId" + - "title" + - "format" + - "contentSha256" + - "contentLength" + - "options" + - "createdAt" + - "status" + type: "object" + PrintingJobsV1: + properties: + jobs: + items: + $ref: "#/components/schemas/PrintingJobV1" + type: "array" + required: + - "jobs" + type: "object" + PrintingOptionsV1: + properties: + copies: + type: "integer" + scale: + enum: + - "ACTUAL_SIZE" + - "FIT" + type: "string" + paperWidthMm: + type: "number" + paperHeightMm: + type: "number" + type: "object" + PrintingPrinterV1: + properties: + printerId: + maxLength: 128 + type: "string" + name: + maxLength: 1024 + type: "string" + driverName: + maxLength: 1024 + type: "string" + portName: + maxLength: 1024 + type: "string" + status: + enum: + - "READY" + - "OFFLINE" + - "PAUSED" + - "ERROR" + - "UNKNOWN" + type: "string" + formats: + items: + enum: + - "PDF" + - "ZPL" + type: "string" + type: "array" + displayName: + maxLength: 512 + type: "string" + description: + maxLength: 4096 + type: "string" + location: + maxLength: 512 + type: "string" + required: + - "printerId" + - "name" + - "formats" + type: "object" + PrintingProfileV1: + properties: + name: + maxLength: 512 + nullable: true + type: "string" + description: + maxLength: 4096 + nullable: true + type: "string" + location: + maxLength: 512 + nullable: true + type: "string" + type: "object" + PrintingReceiptRequestV1: + properties: + receiptId: + maxLength: 128 + type: "string" + outcome: + enum: + - "INVENTORY_REFRESHED" + - "CANCEL_REQUESTED" + - "ALREADY_ABSENT" + - "OWNERSHIP_MISMATCH" + - "UNSUPPORTED" + - "FAILED" + - "EXPIRED" + - "OUTCOME_UNKNOWN" + type: "string" + completedAt: + description: "RFC3339 UTC ending in uppercase Z." + format: "date-time" + maxLength: 40 + type: "string" + message: + maxLength: 1024 + type: "string" + required: + - "receiptId" + - "outcome" + - "completedAt" + type: "object" + PrintingRetryRequestV1: + properties: + requestId: + maxLength: 128 + type: "string" + confirmDuplicateRisk: + type: "boolean" + required: + - "requestId" + type: "object" + PrintingSessionV1: + properties: + principalId: + maxLength: 200 + type: "string" + tenantId: + maxLength: 200 + type: "string" + deviceId: + maxLength: 128 + type: "string" + required: + - "principalId" + - "tenantId" + type: "object" + PrintingTestRequestV1: + properties: + requestId: + maxLength: 128 + type: "string" + printerId: + maxLength: 128 + type: "string" + format: + enum: + - "PDF" + - "ZPL" + type: "string" + testProfile: + maxLength: 40 + type: "string" + required: + - "requestId" + - "printerId" + - "format" + type: "object" + securitySchemes: + sessionUuidCookie: + description: "The session cookie set by POST /qqq/v1/manageSession (web clients)." + in: "cookie" + name: "sessionUUID" + type: "apiKey" + bearerAuth: + bearerFormat: "JWT or session UUID" + description: "`Authorization: Bearer `, where the token is either\n-\ + \ an OAuth2 access token (a signed JWT) issued by the app's identity provider\ + \ to the app's client,\n or to its native client (`values.nativeClientId`\ + \ in GET /qqq/v1/metaData/authentication), for\n example from the device-authorization\ + \ grant or auth-code + PKCE. It is verified against the\n provider's keys\ + \ (issuer, audience, expiry, signature) and gives the same user and permissions\n\ + \ as signing in on the web. When it expires (401), refresh it at the provider\ + \ and retry; or\n- a session UUID returned by POST /qqq/v1/manageSession,\ + \ which the server keeps refreshed." + scheme: "bearer" + type: "http" + oauth2: + description: "The app's OAuth2 / OpenID Connect provider. The real endpoints\ + \ come from the provider's discovery\ndocument: `{values.baseUrl}.well-known/openid-configuration`,\ + \ with values from\nGET /qqq/v1/metaData/authentication. Native clients use\ + \ `values.nativeClientId` (a public client)\nwith auth-code + PKCE (loopback\ + \ or custom-scheme redirect URI registered at the provider) or the\ndevice-authorization\ + \ grant (`device_authorization_endpoint`, RFC 8628), then send the access\ + \ token\nas `Authorization: Bearer`." + flows: + authorizationCode: + authorizationUrl: "/authorize" + scopes: + email: "Email address" + offline_access: "A refresh token, to renew the access token without signing\ + \ in again" + openid: "OpenID Connect sign-in" + profile: "Name, username and groups (permissions come from the groups)" + tokenUrl: "/token" + type: "oauth2" +info: + contact: + email: "contact@kingsrook.com" + description: "Native current-user printing with secondary device proof and device-control-v1." + title: "QQQ Middleware API extension: printing" + version: "1.0.0" +openapi: "3.0.3" +paths: + /qqq/v1/qbit/printing/session: + get: + description: "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." + operationId: "printingSession" + parameters: + - in: "header" + name: "X-QQQ-Device-Id" + required: false + schema: + maxLength: 36 + type: "string" + - description: "Private secondary device proof; never log." + in: "header" + name: "X-QQQ-Device-Token" + required: false + schema: + maxLength: 128 + type: "string" + responses: + 400: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Invalid request" + 401: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Native QQQ sign-in required" + 403: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Permission, device proof or user binding denied" + 404: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Record not found" + 200: + content: + application/json: + schema: + $ref: "#/components/schemas/PrintingSessionV1" + description: "Successful Response" + 409: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "State or request conflict" + 410: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Request or content expired" + 429: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Bounded capacity reached" + security: + - sessionUuidCookie: + - "N/A" + - bearerAuth: + - "N/A" + - oauth2: + - "openid" + - "profile" + - "email" + summary: "Printing Session" + tags: + - "printing" + /qqq/v1/qbit/printing/device/bind: + post: + description: "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." + operationId: "printingBind" + parameters: + - in: "header" + name: "X-QQQ-Device-Id" + required: true + schema: + maxLength: 36 + type: "string" + - description: "Private secondary device proof; never log." + in: "header" + name: "X-QQQ-Device-Token" + required: true + schema: + maxLength: 128 + type: "string" + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/PrintingEmptyV1" + required: true + responses: + 400: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Invalid request" + 401: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Native QQQ sign-in required" + 403: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Permission, device proof or user binding denied" + 404: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Record not found" + 200: + content: + application/json: + schema: + $ref: "#/components/schemas/PrintingAcknowledgmentV1" + description: "Successful Response" + 409: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "State or request conflict" + 410: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Request or content expired" + 429: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Bounded capacity reached" + security: + - sessionUuidCookie: + - "N/A" + - bearerAuth: + - "N/A" + - oauth2: + - "openid" + - "profile" + - "email" + summary: "Printing Bind" + tags: + - "printing" + /qqq/v1/qbit/printing/devices/enroll: + post: + description: "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." + operationId: "printingEnroll" + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/PrintingEnrollmentRequestV1" + required: true + responses: + 400: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Invalid request" + 401: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Native QQQ sign-in required" + 403: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Permission, device proof or user binding denied" + 404: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Record not found" + 200: + content: + application/json: + schema: + $ref: "#/components/schemas/PrintingEnrollmentV1" + description: "Successful Response" + 409: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "State or request conflict" + 410: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Request or content expired" + 429: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Bounded capacity reached" + security: + - sessionUuidCookie: + - "N/A" + - bearerAuth: + - "N/A" + - oauth2: + - "openid" + - "profile" + - "email" + summary: "Printing Enroll" + tags: + - "printing" + /qqq/v1/qbit/printing/device/heartbeat: + post: + description: "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." + operationId: "printingHeartbeat" + parameters: + - in: "header" + name: "X-QQQ-Device-Id" + required: true + schema: + maxLength: 36 + type: "string" + - description: "Private secondary device proof; never log." + in: "header" + name: "X-QQQ-Device-Token" + required: true + schema: + maxLength: 128 + type: "string" + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/PrintingHeartbeatRequestV1" + required: true + responses: + 400: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Invalid request" + 401: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Native QQQ sign-in required" + 403: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Permission, device proof or user binding denied" + 404: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Record not found" + 200: + content: + application/json: + schema: + $ref: "#/components/schemas/PrintingHeartbeatV1" + description: "Successful Response" + 409: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "State or request conflict" + 410: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Request or content expired" + 429: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Bounded capacity reached" + security: + - sessionUuidCookie: + - "N/A" + - bearerAuth: + - "N/A" + - oauth2: + - "openid" + - "profile" + - "email" + summary: "Printing Heartbeat" + tags: + - "printing" + /qqq/v1/qbit/printing/device/printers: + put: + description: "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." + operationId: "printingInventory" + parameters: + - in: "header" + name: "X-QQQ-Device-Id" + required: true + schema: + maxLength: 36 + type: "string" + - description: "Private secondary device proof; never log." + in: "header" + name: "X-QQQ-Device-Token" + required: true + schema: + maxLength: 128 + type: "string" + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/PrintingInventoryRequestV1" + required: true + responses: + 400: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Invalid request" + 401: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Native QQQ sign-in required" + 403: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Permission, device proof or user binding denied" + 404: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Record not found" + 200: + content: + application/json: + schema: + $ref: "#/components/schemas/PrintingAcknowledgmentV1" + description: "Successful Response" + 409: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "State or request conflict" + 410: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Request or content expired" + 429: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Bounded capacity reached" + security: + - sessionUuidCookie: + - "N/A" + - bearerAuth: + - "N/A" + - oauth2: + - "openid" + - "profile" + - "email" + summary: "Printing Inventory" + tags: + - "printing" + /qqq/v1/qbit/printing/device/jobs/claim: + post: + description: "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." + operationId: "printingClaim" + parameters: + - in: "header" + name: "X-QQQ-Device-Id" + required: true + schema: + maxLength: 36 + type: "string" + - description: "Private secondary device proof; never log." + in: "header" + name: "X-QQQ-Device-Token" + required: true + schema: + maxLength: 128 + type: "string" + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/PrintingEmptyV1" + required: true + responses: + 400: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Invalid request" + 401: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Native QQQ sign-in required" + 403: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Permission, device proof or user binding denied" + 404: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Record not found" + 200: + content: + application/json: + schema: + $ref: "#/components/schemas/PrintingClaimV1" + description: "Successful Response" + 409: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "State or request conflict" + 410: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Request or content expired" + 429: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Bounded capacity reached" + security: + - sessionUuidCookie: + - "N/A" + - bearerAuth: + - "N/A" + - oauth2: + - "openid" + - "profile" + - "email" + summary: "Printing Claim" + tags: + - "printing" + /qqq/v1/qbit/printing/device/jobs/queued: + get: + description: "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." + operationId: "printingQueued" + parameters: + - in: "header" + name: "X-QQQ-Device-Id" + required: true + schema: + maxLength: 36 + type: "string" + - description: "Private secondary device proof; never log." + in: "header" + name: "X-QQQ-Device-Token" + required: true + schema: + maxLength: 128 + type: "string" + responses: + 400: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Invalid request" + 401: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Native QQQ sign-in required" + 403: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Permission, device proof or user binding denied" + 404: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Record not found" + 200: + content: + application/json: + schema: + $ref: "#/components/schemas/PrintingJobsV1" + description: "Successful Response" + 409: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "State or request conflict" + 410: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Request or content expired" + 429: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Bounded capacity reached" + security: + - sessionUuidCookie: + - "N/A" + - bearerAuth: + - "N/A" + - oauth2: + - "openid" + - "profile" + - "email" + summary: "Printing Queued" + tags: + - "printing" + /qqq/v1/qbit/printing/device/jobs/{jobId}/content: + get: + description: "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." + operationId: "printingContent" + parameters: + - in: "header" + name: "X-QQQ-Device-Id" + required: true + schema: + maxLength: 36 + type: "string" + - description: "Private secondary device proof; never log." + in: "header" + name: "X-QQQ-Device-Token" + required: true + schema: + maxLength: 128 + type: "string" + - in: "path" + name: "jobId" + required: true + schema: + maxLength: 128 + type: "string" + responses: + 400: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Invalid request" + 401: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Native QQQ sign-in required" + 403: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Permission, device proof or user binding denied" + 404: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Record not found" + 200: + content: + application/octet-stream: + schema: + format: "binary" + type: "string" + description: "Verified retained document bytes" + 409: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "State or request conflict" + 410: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Request or content expired" + 429: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Bounded capacity reached" + security: + - sessionUuidCookie: + - "N/A" + - bearerAuth: + - "N/A" + - oauth2: + - "openid" + - "profile" + - "email" + summary: "Printing Content" + tags: + - "printing" + /qqq/v1/qbit/printing/device/jobs/{jobId}/events: + post: + description: "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." + operationId: "printingEvent" + parameters: + - in: "header" + name: "X-QQQ-Device-Id" + required: true + schema: + maxLength: 36 + type: "string" + - description: "Private secondary device proof; never log." + in: "header" + name: "X-QQQ-Device-Token" + required: true + schema: + maxLength: 128 + type: "string" + - in: "path" + name: "jobId" + required: true + schema: + maxLength: 128 + type: "string" + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/PrintingEventRequestV1" + required: true + responses: + 400: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Invalid request" + 401: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Native QQQ sign-in required" + 403: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Permission, device proof or user binding denied" + 404: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Record not found" + 200: + content: + application/json: + schema: + $ref: "#/components/schemas/PrintingAcknowledgmentV1" + description: "Successful Response" + 409: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "State or request conflict" + 410: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Request or content expired" + 429: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Bounded capacity reached" + security: + - sessionUuidCookie: + - "N/A" + - bearerAuth: + - "N/A" + - oauth2: + - "openid" + - "profile" + - "email" + summary: "Printing Event" + tags: + - "printing" + /qqq/v1/qbit/printing/device/test-print: + post: + description: "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." + operationId: "printingTest" + parameters: + - in: "header" + name: "X-QQQ-Device-Id" + required: true + schema: + maxLength: 36 + type: "string" + - description: "Private secondary device proof; never log." + in: "header" + name: "X-QQQ-Device-Token" + required: true + schema: + maxLength: 128 + type: "string" + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/PrintingTestRequestV1" + required: true + responses: + 400: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Invalid request" + 401: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Native QQQ sign-in required" + 403: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Permission, device proof or user binding denied" + 404: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Record not found" + 200: + content: + application/json: + schema: + $ref: "#/components/schemas/PrintingJobV1" + description: "Successful Response" + 409: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "State or request conflict" + 410: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Request or content expired" + 429: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Bounded capacity reached" + security: + - sessionUuidCookie: + - "N/A" + - bearerAuth: + - "N/A" + - oauth2: + - "openid" + - "profile" + - "email" + summary: "Printing Test" + tags: + - "printing" + /qqq/v1/qbit/printing/device/jobs/{jobId}/retry: + post: + description: "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." + operationId: "printingRetry" + parameters: + - in: "header" + name: "X-QQQ-Device-Id" + required: true + schema: + maxLength: 36 + type: "string" + - description: "Private secondary device proof; never log." + in: "header" + name: "X-QQQ-Device-Token" + required: true + schema: + maxLength: 128 + type: "string" + - in: "path" + name: "jobId" + required: true + schema: + maxLength: 128 + type: "string" + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/PrintingRetryRequestV1" + required: true + responses: + 400: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Invalid request" + 401: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Native QQQ sign-in required" + 403: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Permission, device proof or user binding denied" + 404: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Record not found" + 200: + content: + application/json: + schema: + $ref: "#/components/schemas/PrintingJobV1" + description: "Successful Response" + 409: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "State or request conflict" + 410: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Request or content expired" + 429: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Bounded capacity reached" + security: + - sessionUuidCookie: + - "N/A" + - bearerAuth: + - "N/A" + - oauth2: + - "openid" + - "profile" + - "email" + summary: "Printing Retry" + tags: + - "printing" + /qqq/v1/qbit/printing/device/jobs/{jobId}/cancel: + post: + description: "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." + operationId: "printingCancel" + parameters: + - in: "header" + name: "X-QQQ-Device-Id" + required: true + schema: + maxLength: 36 + type: "string" + - description: "Private secondary device proof; never log." + in: "header" + name: "X-QQQ-Device-Token" + required: true + schema: + maxLength: 128 + type: "string" + - in: "path" + name: "jobId" + required: true + schema: + maxLength: 128 + type: "string" + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/PrintingEmptyV1" + required: true + responses: + 400: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Invalid request" + 401: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Native QQQ sign-in required" + 403: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Permission, device proof or user binding denied" + 404: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Record not found" + 200: + content: + application/json: + schema: + $ref: "#/components/schemas/PrintingAcknowledgmentV1" + description: "Successful Response" + 409: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "State or request conflict" + 410: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Request or content expired" + 429: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Bounded capacity reached" + security: + - sessionUuidCookie: + - "N/A" + - bearerAuth: + - "N/A" + - oauth2: + - "openid" + - "profile" + - "email" + summary: "Printing Cancel" + tags: + - "printing" + /qqq/v1/qbit/printing/device/control/poll: + post: + description: "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." + operationId: "printingPoll" + parameters: + - in: "header" + name: "X-QQQ-Device-Id" + required: true + schema: + maxLength: 36 + type: "string" + - description: "Private secondary device proof; never log." + in: "header" + name: "X-QQQ-Device-Token" + required: true + schema: + maxLength: 128 + type: "string" + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/PrintingControlPollRequestV1" + required: true + responses: + 400: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Invalid request" + 401: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Native QQQ sign-in required" + 403: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Permission, device proof or user binding denied" + 404: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Record not found" + 200: + content: + application/json: + schema: + $ref: "#/components/schemas/PrintingControlPollV1" + description: "Successful Response" + 409: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "State or request conflict" + 410: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Request or content expired" + 429: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Bounded capacity reached" + security: + - sessionUuidCookie: + - "N/A" + - bearerAuth: + - "N/A" + - oauth2: + - "openid" + - "profile" + - "email" + summary: "Printing Poll" + tags: + - "printing" + /qqq/v1/qbit/printing/device/control/commands/{commandId}/receipt: + post: + description: "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." + operationId: "printingReceipt" + parameters: + - in: "header" + name: "X-QQQ-Device-Id" + required: true + schema: + maxLength: 36 + type: "string" + - description: "Private secondary device proof; never log." + in: "header" + name: "X-QQQ-Device-Token" + required: true + schema: + maxLength: 128 + type: "string" + - in: "path" + name: "commandId" + required: true + schema: + maxLength: 128 + type: "string" + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/PrintingReceiptRequestV1" + required: true + responses: + 400: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Invalid request" + 401: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Native QQQ sign-in required" + 403: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Permission, device proof or user binding denied" + 404: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Record not found" + 200: + content: + application/json: + schema: + $ref: "#/components/schemas/PrintingAcknowledgmentV1" + description: "Successful Response" + 409: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "State or request conflict" + 410: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Request or content expired" + 429: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Bounded capacity reached" + security: + - sessionUuidCookie: + - "N/A" + - bearerAuth: + - "N/A" + - oauth2: + - "openid" + - "profile" + - "email" + summary: "Printing Receipt" + tags: + - "printing" + /qqq/v1/qbit/printing/admin/devices/{deviceId}/actions: + post: + description: "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." + operationId: "printingAction" + parameters: + - in: "path" + name: "deviceId" + required: true + schema: + maxLength: 128 + type: "string" + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/PrintingActionRequestV1" + required: true + responses: + 400: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Invalid request" + 401: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Native QQQ sign-in required" + 403: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Permission, device proof or user binding denied" + 404: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Record not found" + 200: + content: + application/json: + schema: + $ref: "#/components/schemas/PrintingActionV1" + description: "Successful Response" + 409: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "State or request conflict" + 410: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Request or content expired" + 429: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Bounded capacity reached" + security: + - sessionUuidCookie: + - "N/A" + - bearerAuth: + - "N/A" + - oauth2: + - "openid" + - "profile" + - "email" + summary: "Printing Action" + tags: + - "printing" + /qqq/v1/qbit/printing/admin/devices/{deviceId}/commands: + get: + description: "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." + operationId: "printingCommands" + parameters: + - in: "path" + name: "deviceId" + required: true + schema: + maxLength: 128 + type: "string" + - description: "1 through 200; default 50." + in: "query" + name: "limit" + schema: + type: "integer" + - in: "query" + name: "before" + schema: + maxLength: 128 + type: "string" + responses: + 400: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Invalid request" + 401: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Native QQQ sign-in required" + 403: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Permission, device proof or user binding denied" + 404: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Record not found" + 200: + content: + application/json: + schema: + $ref: "#/components/schemas/PrintingActionsV1" + description: "Successful Response" + 409: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "State or request conflict" + 410: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Request or content expired" + 429: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Bounded capacity reached" + security: + - sessionUuidCookie: + - "N/A" + - bearerAuth: + - "N/A" + - oauth2: + - "openid" + - "profile" + - "email" + summary: "Printing Commands" + tags: + - "printing" + /qqq/v1/qbit/printing/admin/devices/{deviceId}/commands/{commandId}: + get: + description: "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." + operationId: "printingCommand" + parameters: + - in: "path" + name: "deviceId" + required: true + schema: + maxLength: 128 + type: "string" + - in: "path" + name: "commandId" + required: true + schema: + maxLength: 128 + type: "string" + responses: + 400: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Invalid request" + 401: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Native QQQ sign-in required" + 403: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Permission, device proof or user binding denied" + 404: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Record not found" + 200: + content: + application/json: + schema: + $ref: "#/components/schemas/PrintingActionV1" + description: "Successful Response" + 409: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "State or request conflict" + 410: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Request or content expired" + 429: + content: + application/json: + schema: + $ref: "#/components/schemas/BasicErrorResponseV1" + description: "Bounded capacity reached" + security: + - sessionUuidCookie: + - "N/A" + - bearerAuth: + - "N/A" + - oauth2: + - "openid" + - "profile" + - "email" + summary: "Printing Command" + tags: + - "printing" +servers: +- description: "The QQQ server that serves this document (paths include /qqq/v1)." + url: "/" +tags: +- description: "Operations of the printing extension." + name: "printing"