docs: specify bounded printer history and capacity responses
Co-authored-by: Codex (GPT-6) <noreply@openai.com> Signed-off-by: James Maes <james@kof22.com>
This commit is contained in:
8 files changed
+53
-6
No files matched your search
+2
-1
@@ -4,7 +4,8 @@
|
||||
|
||||
- Gate publication on security checks, promote the tested archive and verify packaged checksums.
|
||||
- Add GitHub build provenance attestations and disable npm caching in the release-producing job.
|
||||
- Preserve the v1 wire contract and compatibility fixtures unchanged.
|
||||
- Add optional management printer pagination with bounded pages and compatible cursor-free responses; retain wire v1.
|
||||
- Document capacity rejection and document-expiration responses without changing existing device requests.
|
||||
|
||||
## 0.1.3-rc.1 — 2026-10-30
|
||||
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
Shared contract for the [QQQ 4.1+ printing QBit](https://github.com/QRun-IO/qbit-printing) and [Windows AppKit connector](https://github.com/QRun-IO/qqq-print-agent). The first implementation uses outbound HTTPS polling. WebSockets are unnecessary for this happy path. This contract is authoritative for wire names; language types may use their idiomatic naming.
|
||||
|
||||
Distribution version: **0.1.3-rc.1**, a prerelease with additive test-document profiles. Wire protocol: **v1**. This repository supplies specification, JSON Schema and synthetic compatibility fixtures; install the Windows connector and integrate the QBit from their own repositories to print documents.
|
||||
Source distribution version: **0.1.4-rc.1** (unreleased audit update). Wire protocol: **v1**. This repository supplies specification, JSON Schema and synthetic compatibility fixtures; install the Windows connector and integrate the QBit from their own repositories to print documents.
|
||||
|
||||
Use Node.js 24+ to run the development checks:
|
||||
|
||||
@@ -41,7 +41,7 @@ The host application authenticates management requests and determines authorized
|
||||
| GET `/device/jobs/{jobId}/content` | none | 200 binary content |
|
||||
| POST `/device/jobs/{jobId}/events` | `JobEvent` | 200 `Acknowledgment` |
|
||||
| GET `/admin/devices` | none | 200 `{ "devices": [Device] }` |
|
||||
| GET `/admin/devices/{deviceId}/printers` | none | 200 `{ "printers": [ManagedPrinter] }` |
|
||||
| GET `/admin/devices/{deviceId}/printers` | optional `limit`, `before` query parameters | 200 `PrinterList` |
|
||||
| PUT `/admin/devices/{deviceId}/printers/{printerId}` | `{ "enabled": true }` | 200 `Acknowledgment` |
|
||||
| POST `/admin/jobs` | `SubmitJobRequest` | 200 `PrintJob`, including identical idempotent replay |
|
||||
| GET `/admin/jobs` | none | 200 `{ "jobs": [PrintJob] }` |
|
||||
@@ -119,6 +119,8 @@ Management device responses additionally include `computerName` and `profile`. M
|
||||
|
||||
Device queued inspection remains the oldest 50 QUEUED jobs. Claim returns a single eligible job; content is downloaded separately after claim. A local list is a bounded operational window, not a statement that older history or a larger backlog does not exist.
|
||||
|
||||
`GET /printing/v1/admin/devices/{deviceId}/printers?limit=200&before=<nextCursor>` returns `{ printers: [ManagedPrinter, ...], nextCursor: string|null }`. Limit defaults to 200 and must be between 1 and 200. Pages follow ascending display name and stable row identity; pass the opaque cursor unchanged. The host rechecks device and tenant scope on every page. Existing clients can continue reading the bounded `printers` array. Discovery snapshots still contain at most 200 queues; configurable cumulative history limits prevent repeated fresh IDs from growing inventory indefinitely, while preserving approved and job-referenced records.
|
||||
|
||||
## Errors
|
||||
|
||||
Error body: `{ "code": "ERROR_CODE", "message": "Human-readable explanation" }`.
|
||||
@@ -128,7 +130,9 @@ Error body: `{ "code": "ERROR_CODE", "message": "Human-readable explanation" }`.
|
||||
* 403: authenticated identity lacks permission.
|
||||
* 404: unknown object or object outside the device's scope (avoid cross-device disclosure).
|
||||
* 409: idempotency conflict, enrollment already used, invalid lifecycle transition.
|
||||
* 410: the delivery document expired under the host retention policy. Submit a new document explicitly; an existing idempotent receipt remains valid.
|
||||
* 413: document or request exceeds configured limit.
|
||||
* 429: host queue, retained-document, inventory or request-rate capacity is exhausted. Respect the host's capacity policy; retry the same request identity with bounded backoff after capacity becomes available. Do not create fresh identities to evade limits.
|
||||
* 503: transient server failure; retry transport operations with bounded backoff. A timeout does not prove a physical print failed.
|
||||
|
||||
## Verification
|
||||
|
||||
+10
-2
@@ -1,6 +1,14 @@
|
||||
# Session state
|
||||
# Session state — 2026-10-30
|
||||
|
||||
2026-10-30 audit: pending 0.1.4-rc.1 changes release engineering only, preserving wire v1 compatibility. Release publication now requires reusable security checks, promotes the verified archive, verifies checksums and requests GitHub build provenance. Disable npm cache in the release-producing workflow to avoid cache poisoning. Published baseline remains 0.1.3-rc.1; hosted validation/provenance and independent security scan remain pending. User-confirmed laser PDF and Zebra ZPL/PDF evidence is recorded in the implementation repositories.
|
||||
## Audit candidate 0.1.4-rc.1
|
||||
|
||||
Wire v1 remains compatible. Optional management printer pagination adds bounded pages and an opaque nextCursor; existing cursor-free responses remain valid. Capacity and document-expiration errors are documented. `npm run check` passes **29 definitions and 23 fixtures**, including cursor type/length and page-overflow regressions.
|
||||
|
||||
Draft PR #2 contains release integrity and fail-closed CodeQL evidence guards that passed hosted checks at 6aefdaf; final contract/documentation edits still require fresh checks. Publication promotes verified archives and includes provenance. No audit release has been published. Windows/server security remediation and installed/deployment qualification remain coordinated release gates. The independent baseline scan completed without a distinct protocol finding.
|
||||
|
||||
Master communications are in `R:\agent-comms\qqq-cloud-printing.md`; both other masters acknowledged ownership and retention boundaries.
|
||||
|
||||
## Historical checkpoints
|
||||
|
||||
2026-10-30 source 0.1.2-rc.1: additive v1 DeviceProfile in heartbeat, optional printer displayName/description/location, explicit null-preserve/empty-clear behavior, 512/4096/1024 character bounds and admin keyset job history cursor documented. Added two shared profile fixtures and boundary invalid-input checks. `npm run check` passed: 28 schema definitions,21 fixtures plus integrity/invalid-input checks. Both implementations pin fixtures to a0de93b. Exact-source GitHub CI41126317410 passed; release publication is coordinated by root. Existing wire IDs and physical printer name semantics remain unchanged.
|
||||
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
# TODO
|
||||
|
||||
- [ ] Verify security-gated artifact promotion and public build provenance for 0.1.4-rc.1.
|
||||
- [x] Audit PR #2 at 2e871e6 passes all hosted checks; verify downloaded CI archive checksum. Tagged release and published attestation remain pending.
|
||||
- [x] Shared contract v1 remains unchanged during the retention/storage and Windows audit fixes.
|
||||
- [x] User confirmed laser PDF and Zebra ZPL/PDF output with the previous implementation releases; barcode scanning remains unverified.
|
||||
|
||||
@@ -18,3 +19,5 @@
|
||||
- [ ] Verify GitHub CI after maintainer publication.
|
||||
|
||||
WebSocket notifications, automatic reconciliation, cancellation, destination CRUD and fleet-scale behavior are outside this initial wire contract.
|
||||
|
||||
- [ ] Complete independent review and deployment qualification after the five baseline security findings are remediated; current details are in SESSION-STATE.md.
|
||||
@@ -0,0 +1,15 @@
|
||||
{
|
||||
"printers": [
|
||||
{
|
||||
"printerId": "printer-zebra",
|
||||
"name": "Packing Zebra",
|
||||
"driverName": "Synthetic ZPL driver",
|
||||
"portName": "SYNTHETIC",
|
||||
"status": "READY",
|
||||
"formats": ["ZPL"],
|
||||
"enabled": true,
|
||||
"available": true
|
||||
}
|
||||
],
|
||||
"nextCursor": null
|
||||
}
|
||||
@@ -650,7 +650,14 @@
|
||||
"type": "array",
|
||||
"items": {
|
||||
"$ref": "#/$defs/ManagedPrinter"
|
||||
}
|
||||
},
|
||||
"maxItems": 200
|
||||
},
|
||||
"nextCursor": {
|
||||
"anyOf": [
|
||||
{ "type": "string", "maxLength": 12000 },
|
||||
{ "type": "null" }
|
||||
]
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
|
||||
@@ -12,6 +12,7 @@ export const fixtureTypes = {
|
||||
'heartbeat.request.json': 'HeartbeatRequest',
|
||||
'heartbeat.response.json': 'HeartbeatResponse',
|
||||
'printers.request.json': 'PrinterInventory',
|
||||
'printers-page.response.json': 'PrinterList',
|
||||
'approval.request.json': 'PrinterApproval',
|
||||
'claim-empty.response.json': 'ClaimResponse',
|
||||
'claim.response.json': 'ClaimResponse',
|
||||
|
||||
@@ -28,4 +28,12 @@ assert(validateTest({ ...testRequest, testProfile: 'LABEL_4X6_300' }));
|
||||
assert(!validateTest({ ...testRequest, testProfile: 'LETTER' }));
|
||||
assert(!validateTest({ ...testRequest, testProfile: null }));
|
||||
assert(!validateTest({ format: 'PDF' }));
|
||||
const validatePrinters = ajv.compile({ $ref: `${schema.$id}#/$defs/PrinterList` });
|
||||
const printerPage = JSON.parse(readFileSync(new URL('../fixtures/printers-page.response.json', import.meta.url), 'utf8'));
|
||||
assert(validatePrinters(printerPage));
|
||||
assert(validatePrinters({ printers: printerPage.printers }), 'Older responses without a cursor remain valid.');
|
||||
assert(validatePrinters({ ...printerPage, nextCursor: 'opaque-server-cursor' }));
|
||||
assert(!validatePrinters({ ...printerPage, nextCursor: 17 }));
|
||||
assert(!validatePrinters({ ...printerPage, nextCursor: 'x'.repeat(12001) }));
|
||||
assert(!validatePrinters({ printers: Array(201).fill(printerPage.printers[0]) }));
|
||||
console.log(`Compiled ${Object.keys(schema.$defs).length} JSON Schema 2020-12 definitions; ${Object.keys(fixtureTypes).length} fixtures passed full schema validation.`);
|
||||
Reference in new issue
Block a user