Skip to content

craft-print: a tracked PrintJob, an idempotency tag and a backend-neutral job listing - #121

Closed
b1tninja wants to merge 36 commits into
storytold:mainfrom
b1tninja:craft-print-job-tracking
Closed

b1tninja wants to merge 36 commits into
storytold:mainfrom
b1tninja:craft-print-job-tracking

Conversation

@b1tninja

@b1tninja b1tninja commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

craft-print: a tracked PrintJob, an idempotency tag and a backend-neutral job listing

Stacked on slice 1 (#116, the backend trait and registry) and slice 2 (#118,
the WS-Print backend, now at 384004b), and depends on craft-job (#120, now at aa6ea75).

Review only the commits above 7eaf366 other than the two craft-job merges and the slice-2 merge: dae53d9 (the design
note), 37544c9 (the implementation), 8129560 (tests and docs), bdc2d6a (merge of craft-job, no conflicts), bce801d
(craft-print builds on craft-job, plus PrintJob::view), 54dc532 (merge of slice 2 at 384004b: conflicts in
backend.rs, job.rs, lib.rs, registry.rs, wsd/backend.rs, resolved with the craft-job names for the shared
vocabulary and slice 2's Photo, formats, resolutions, converter and fakes kept), 3e21544 (merge of craft-job at 7d5aa42:
README fix and an optional serde feature, no API change, feature not enabled here) and 34257ef (job timeouts, see
below), ecee2ef (merge of craft-job at aa6ea75, which adds JobState::Abandoned; no conflicts) and 122f117 (an
abandoned print is JobState::Abandoned in view()). Branch craft-print-job-tracking, head 122f117.

Breaking, relative to the earlier heads of this PR (nothing outside this PR has shipped these names):
JobTag is Tag (and is Copy); ParseJobIdError / ParseJobIdErrorKind are ParseIdError /
ParseIdErrorKind; RetryAdvice::CheckPrinterFirst is CheckDeviceFirst; JobState::Stopped is
JobState::NeedsAttention; JobState::CompletedWithWarnings is removed (a completed job the printer qualified is
JobState::Completed plus JobStatus::warnings); TagPlacement::{JobName, Native} are
{JobNameSuffix, NativeAttribute}; TagSupport is the craft-job enum (None, Carried(p), Partial(p)) instead of
a struct with a matchable flag; Fingerprint is craft-job's (Fingerprint::new(title, submitted) with
with_user, with_tag, with_window, a Timestamp and a window instead of a since); RetryPolicy::next_delay is
replaced by craft_job::advise (craft-print: advise_error). craft_print::{JobId, NativeCode, RetrySafety, RetryPolicy, RetryAdvice, Jitter, JobState, Progress, ExpectedTotals, Tag, TagSupport, TagPlacement, Fingerprint} all
still resolve (re-exports of the craft-job types).

What

Merged in from slice 2 (384004b), now cooperating with PrintJob: Quality::Photo, the extra DocumentFormat
variants and negotiate, PrinterDetails::resolutions, the DocumentConverter path (Registry::set_converter,
submit_job_with_details, Submitted::conversion), the public pwg module and the fake additions. A tracked print goes
through the converter on every attempt (the document source is read and converted again after a safe failure), the tag is
applied once, RequestRecord::conversion and Snapshot::conversion say what the registry did, and view() shows the
document as it was sent (the converted format and size).

Timeouts (34257ef, PrintJobConfig::staleness, Staleness): an accepted print that is never heard from no longer
stays Accepted for ever. All times are on the job's clock, all fields are configurable, and Staleness::disabled()
restores the earlier behaviour. A timeout is never Failed and never resends: the device may still print.

Rule Default Effect
poll gap 2 s, growing to a 15 s cap well under the 60 s minimum history retention
silence_after 3 min without one successful status read NeedsAttention, reason no-news-since:<unix secs of the last good read>; probes every 30 s, a good read returns the print to Watching
stall_after_processing 10 min with a completely unchanged reading (same_as) while Processing NeedsAttention, reason stalled, advice CheckDeviceFirst; any progress resets it
stall_after_pending 30 min unchanged while Pending the same
held, stopped never an explicit hold has no timeout; jams arrive through the printer's own reasons
ceiling 3 h from acceptance new Outcome::Abandoned (not a failure), JobState::Abandoned in view() (terminal, not a success, counted by needs_attention) plus the reason abandoned-no-outcome
dismiss() / dismiss_and_cancel(&Registry) by a person the same end, earlier; the second asks the device to cancel first
reconcile_after 65 s, or Backend::open_job_timeout() (WS-Print 65 s; the IPP-like fake 240 s) after a send of unknown outcome the resend advice waits for the device to end the half-made job itself (PrintJob::reconcile_wait()); a reconcile that finds it Aborted with a timeout reason advises RetryNow

A backend without status (watch_support() == None) is not polled and never times out: the print is Accepted, already
settled (SimpleState::Sent, JobState::Unknown), the same meaning as IPP queued-in-device. Sources: CUPS MaxJobTime
10800 s, RFC 8011 5.4.31 (multiple-operation-time-out 60 to 240 s), 5.3.7.2 (history of at least 60 s), the
submission-interrupted / aborted-by-system reasons, WS-Print DocumentTimeoutError after 60 s. The figures beyond
those protocol numbers (3 min, 30 s, 10 min, 30 min) are judgement.
The Windows spooler's timeouts are unverified.

craft_print, one new dependency (craft-job, a leaf crate with no dependencies of its own) and no new feature:

  • Built on craft-job: the vocabulary shared with scanning (JobId, NativeCode, RetrySafety, RetryPolicy,
    RetryAdvice, Jitter, JobState, Progress, ExpectedTotals, Tag, TagSupport, TagPlacement, Fingerprint,
    namespaced_id, split_id) is craft-job's and is re-exported here. Stays in craft-print: PrintJob and its
    lifecycle, Attempt and the trail, the reconcile engine, RemoteJob / JobFilter / JobQueryCaps, ErrorKind /
    PrintError, Phase, Clock. What printing adds to the shared types is a set of extension traits (re-exported,
    imported where used): TagExt (Tag::random(), apply_to, strip, find_in), TagSupportExt (carries,
    matchable), FingerprintExt, ExpectedTotalsExt (for_job, apply) and JitterExt (from_clock).
  • PrintJob::view() / Snapshot::view(): the print as a craft_job::JobView (the record a scan job fills too):
    the printer's job id once accepted (a local:print-<n> id before), JobKind::Print, the title, a
    craft_job::JobState mapped from the lifecycle (NeedsAttention is NeedsAttention), reasons and warnings,
    progress with optional totals, wall-clock JobTimes, the document sent as a DocumentRef, the attempt count, the last
    error as an ErrorSummary with its retry advice and native code, the tag and the printer id. No I/O. The mapping is a
    table in docs/job-tracking.md.
  • PrintJob: the lifecycle record of one user-visible print, stable across retries. The caller drives it with
    advance(&Registry) (at most one bounded request per call, no thread, no timer, no async runtime, an injectable
    Clock); snapshot() is a cheap immutable view for a UI (no I/O; the attempt list and the status trail are shared
    Arcs, not copied). The lifecycle is its own state machine, separate from the printer's JobState: Preparing,
    Submitting, Accepted, Watching(JobState), RetryScheduled { attempt, next_at }, NeedsAttention (the outcome of
    a send is unknown) and Terminal(Completed | CompletedWithWarnings | Failed | Cancelled | Aborted | Abandoned), reduced for a UI
    to SimpleState. The lifecycle keeps Outcome::CompletedWithWarnings; the printer's JobState does not.
  • What it remembers: a stable local id; the attempts (start, end, phase reached, outcome Accepted(Option<JobId>)
    or a typed AttemptError { kind, safety, retry_after, native, phase, message }, and how the remote job ended); the
    request as sent (Job, JobOptions, the resolved printer, the tag, the document's length, format and a 64-bit FNV-1a
    fingerprint, the backend's own description of how it was sent) and never the document bytes (a DocumentSource
    supplies them again per attempt: BytesSource, FnSource); a reconcile Fingerprint (craft-job's); a bounded, de-duplicated
    status trail with timestamps; progress with optional totals (JobOptions::expected_pages still flows, a printer's own
    total still wins); warnings.
  • Retry rules: automatic retry only for RetrySafety::Safe errors that are also retryable, under a RetryPolicy
    that is on by default (3 attempts in a row, the device's retry_after honoured, with_retry(None) disables it,
    per job). An OutcomeUnknown failure is never retried automatically: the print goes to NeedsAttention;
    reconcile finds the already-created job, then accept(job) adopts it or retry() resends. A printer-side
    Aborted or Cancelled is a manual retry(): a new attempt, a new remote JobId, history kept.
    retry_advice() is RetryNow, RetryAfter(duration), CheckDeviceFirst or DoNotRetry (craft_job::RetryAdvice). cancel() works in every
    state (cancel_token() lets an app thread stop a submit in flight).
  • Idempotency tag: each PrintJob makes a short random tag (8 hex characters) once, the same for every attempt.
    SubmitRequest::with_tag; Backend::tag_support() -> TagSupport (None, Carried(TagPlacement::{JobNameSuffix, DocumentName, NativeAttribute}) when listings return the tag, Partial(..) when a device may rewrite it). The backend applies it
    exactly once (TagExt::apply_to keeps the suffix
    " [ref abc123de]" inside the backend's length limit); the registry drops it for a backend that cannot carry it;
    Submitted::tag says what was carried. TagPolicy::Auto (default) is on for BackendClass::Network, off for the
    local spooler
    ; Always and Never override it per job.
  • Common base for other job sources: RemoteJob, JobFilter, Reconciled, JobQueryCaps (and Fingerprint, from craft-job) and the
    optional Backend methods list_jobs (default Unsupported), find_job (default built on list_jobs),
    tag_support and job_query_caps, routed by printer id through Registry::list_jobs, find_job and backend_info
    (plus Registry::default_printer). Foreign jobs are listed too (ours == false); JobFilter::tag only marks, it
    never hides.
  • WS-Print: the tag is a suffix of the ticket's job name; list_jobs reads GetActiveJobs and GetJobHistory (and
    GetJobElements for up to a few summaries without a name); find_job matches by tag, else by title and the backend's
    user. Submitted::effective reports the ticket shape. The older WsdBackend::reconcile and wsd::Reconciled are
    unchanged.
  • Exported fakes (testing): FakeBackend::cups_like (local, no status, no tag support, no listing) and
    FakeBackend::ipp_like (network, pollable, a listing with creation time, user and history, the tag in a native
    attribute), with_submit_script([SubmitStep::LoseReply(..), ..]) (the job exists but the reply is lost), seed_job
    for foreign jobs, remote_jobs(), with_tag_support, with_query_caps. The WS-Print fake needed no change.
  • Docs: crates/print/docs/job-tracking.md (the design note, with a mapping table for CUPS, generic IPP, the
    Windows spooler and WS-Print: tag support, listing, creation time, state vocabulary, cancel, forgetting, and what the
    built-in adapters do today), a README section and a pointer from job-lifecycle.md.

Why

Slices 1 and 2 follow one remote job and say whether resending a failed request is safe. A person pressed Print once
and expects one sheet, however many connections, retries and printer-side restarts that takes. The recurring hard case
is a connection that closes after SendDocument was written: the job may exist, and guessing from the title can print
twice or not at all. The tag makes "did it?" answerable where the protocol can carry it, and the neutral listing makes
the same question askable of a spooler, an IPP printer or WS-Print. The apps (pdfcraft's CLI and GUI) need one object per
print to bind a UI row to, not a bag of ids that change per attempt.

How

  • PrintJob is built on the existing pieces: Registry::submit_job, JobWatch (for following), RetryPolicy
    (for the automatic retry) and ManualClock. Nothing in slices 1 and 2 changes behaviour; the additions are new pub
    items, the new SubmitRequest::tag and Submitted::{tag, effective} fields, and the new optional Backend methods
    (all with defaults, so an existing backend compiles unchanged).
  • The automatic retry of a send, the watch's retry of a status read and the retry helper decide with
    craft_job::advise over RetryFacts built from the error (is_retryable(), retry_safety(), retry_after()).
    Safe and Idempotent retry as before; an OutcomeUnknown error is CheckDeviceFirst also when the attempts are
    used up (next_delay answered None there), which changes nothing in the behaviour of the loops.
  • "Completed with warnings": the WS-Print backend reports JobState::Completed with a warning in
    JobStatus::warnings; PrintJob then ends as Outcome::CompletedWithWarnings and copies the warnings. A job the
    printer forgot still ends as CompletedWithWarnings.
  • Tag recovery from a title follows craft_job::Tag::parse_from_title (the last well-formed [ref xxxxxxxx] marker
    anywhere in the name), so a name a device appended to is still recognised; only a trailing suffix is stripped for the
    display title.
  • Preparing and Submitting are separate, so a worker can publish "sending" before the blocking send. The default
    printer is resolved once and pinned, so every retry goes to the same printer.
  • NeedsAttention is not a failure: nothing is resent until reconcile ran (one idempotent read) and a person or the
    app chose accept or retry. NotFound advises RetryNow only where the backend lists finished jobs
    (JobQueryCaps::history), otherwise CheckDeviceFirst.
  • Cancelling while the outcome is unknown cancels only jobs that carry this print's tag; a candidate found by title
    alone is reported and left alone, because it could be someone else's.
  • No persistence in this version. The types are plain data with no serde; nothing needs changing to add that behind a
    feature later.
  • The built-in adapters: CUPS and the Windows spooler return Unsupported for list_jobs and carry no tag. lp and
    lpstat show no titles and IPP listing needs a client this crate does not have; the Windows path does not keep the
    spooler job id. Neither can be exercised on the development machines or in CI, so they are not shipped untested; the
    design note says how each would map.

How verified

On Windows, at 122f117:

  • Default features: cargo test -p craft-print 362 passed, 0 failed, 2 ignored (also with --features testing);
    --no-default-features 223 passed, 0 failed, 2 ignored (the wsd tests are cfg-gated off). cargo test --workspace:
    616 passed, 0 failed, 4 ignored (including craft-job). The new files are print_job_conversion (4 tests: a tracked
    print converted for a raster-only printer with the tag applied once and the options forwarded, a retry after a Safe
    failure that reads the source and converts again, Photo quality on a raster-only WS-Print fake with the resolution
    chosen, and no common format failing before anything is created) and print_job_staleness (10 tests: silence and
    recovery, the never-read token, stall reset by progress, pending vs processing thresholds, held and stopped never
    timing out, the ceiling, dismiss and dismiss-and-cancel, no-status backends, Staleness::disabled, the
    reconcile_after window and the document-timeout advice).
  • print_job_staleness now asserts view().state == JobState::Abandoned (terminal, needs attention, not a success) for both the
    ceiling and dismiss(), where it asserted Unknown before; the reason is still checked.
  • The existing print_job tests now build their prints with Staleness::disabled() (their fakes answer Unknown for ever, which the
    new rules would end at the 3 h ceiling); print_job_conversion scripts a Completed status for the same reason.
  • Tests changed for the craft-job names and semantics: the lib tests of retry.rs (the next_delay tests now ask
    advise_error; an OutcomeUnknown error is CheckDeviceFirst, also with the attempts used up, and the two
    delay and jitter tests moved to craft-job, which has them), tag.rs (Tag and the extension trait; a marker in
    the middle of a name is now found, which the old trailing-only rule did not), job.rs (no CompletedWithWarnings
    state, warnings are part of a reading), remote.rs (Fingerprint has a submission time and a window), watch.rs;
    and the integration tests job_lifecycle, print_job, print_job_wsd and wsd_registry (renames, Completed plus
    warnings instead of CompletedWithWarnings, Fingerprint::new(title, timestamp)). No assertion about behaviour was
    loosened.
  • cargo fmt --check clean; clippy --workspace --all-targets -D warnings clean, and for -p craft-print with the
    default features, --no-default-features and --features testing; cargo check -p craft-print --target wasm32-unknown-unknown passes; cargo doc -p craft-print --no-deps with RUSTDOCFLAGS=-D warnings passes.
  • The new tests use an injected ManualClock and the public API only: the state machine and its trail; auto-retry of
    Safe errors up to the cap and then Failed, with the device's wait honoured and retry switched off; no automatic
    retry of an unknown outcome
    (however long the clock moves, one send); reconcile finds the already-created job by tag
    on the IPP-like fake and on the WS-Print fake (over a transport that loses the SendDocument reply), and reports
    Ambiguous and NotFound without tag support, with the right advice (the CUPS-like fake can only say
    CheckDeviceFirst); retry after a printer Aborted makes a new attempt with a new JobId and keeps the history;
    cancel in every state (including an unknown outcome); the tag is made once, is the same across attempts and appears
    exactly once in every attempt's job name, including a 400-character title cut to 255; foreign jobs are listed with
    ours == false; expected totals still flow; a snapshot makes no backend call and is not changed by later steps.
  • print_job_view checks view() for a new print, every printer state through the lifecycle (pending, held, processing,
    a stopped printer, completed), the id (local before, the printer's after, local again after a manual retry), the
    document, tag, times, progress totals (including expected totals), completed with warnings, a forgotten job, a
    printer abort, completed with errors, a refusal (error label, advice, native code), an unknown outcome
    (CheckDeviceFirst), a scheduled retry (RetryAfter), a cancel, a backend that cannot report, and that
    PrintJob::view() equals Snapshot::view().

Not verified:

  • Nothing was exercised against a real printer: only in-memory fakes and loopback transports. In particular how real
    devices list jobs (GetJobHistory windows, whether a job name is returned untouched) is untested.
  • The unix CUPS path (lp/lpstat) is only compile-checked on Windows and wasm, and the CUPS and Windows-spooler
    listing is not implemented (see How).

Boundaries

  • In memory only; no persistence, no serde.
  • No thread, timer or async runtime: the caller advances the job (the timeouts run inside advance).
  • No IPP client, no CUPS or Windows-spooler listing in this change.
  • No discovery and no change to consent: a network backend still needs a UserConfirmed, now also on PrintJob.
  • The document bytes are not kept by the job; the app supplies them per attempt.
  • The tag is a correlation id visible in queues, not a secret.

Candidate follow-ups (not in this PR, not approved)

  • Persisting a PrintJob (and serde for its plain types, now that craft-job has the optional feature).
  • A real-device check of the timeout figures; the defaults beyond the cited protocol numbers are judgement.

Consumers

pdfcraft's CLI print --wsd and its Print dialog (slice 3's craft-ui::printing::network) can replace their own retry and
reconcile logic with one PrintJob per print and a Snapshot per frame. Nothing in the apps changes in this PR.

Review order

Stacked on #116 and #118 and dependent on #120: review only the commits above 7eaf366 (the craft-job merge is #120's
content). Start with
crates/print/docs/job-tracking.md (section 3 has the view() mapping); the code is src/tracked.rs (PrintJob), src/tag.rs, src/remote.rs, the
Backend additions in src/backend.rs, src/registry.rs, the WS-Print changes in src/wsd/backend.rs, and the fakes in
src/testing.rs.

🤖 Generated with Claude Code

b1tninja and others added 30 commits October 14, 2026 06:36
Adds the Backend trait (blocking, Send + Sync, object safe), a Registry with
namespaced printer ids, partial-failure listing, neutral errors with native
codes, document formats, a UserConfirmed consent marker for network backends,
and the system spooler (cups or spooler) as a built-in adapter over the
existing functions. The existing public API is unchanged.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…cancel and retry vocabulary

Backend::submit now returns a Submitted as soon as the printer has accepted the document and never waits for the print. A job is followed with optional trait methods (watch_support, recommended_poll_interval, job_status, cancel_job) whose defaults say "accepted, outcome unknown". The registry routes job ids by prefix and offers submit_job, job_status, cancel_job and job_watch; Registry::submit still returns a Receipt.

JobWatch is a caller-driven state machine with an injectable clock, a backoff that slows while the status does not change, a max_wait, a cancel token and failure retries; wait_for_job is the blocking convenience built on it.

PrintError separates is_retryable (transient) from retry_safety (Safe, Idempotent, OutcomeUnknown), and adds phase and retry_after; RetryPolicy gives a bounded jittered backoff that never repeats an outcome-unknown error. The survey of how comparable stacks do this is in docs/job-lifecycle.md.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Adds craft_print::wsd, built on craft-wsd (named only in wsd/adapter.rs): typed
WS-Print operations, the print ticket with its TicketShape quirk modes, the job
flow with polling and tolerant cancel, pass-through and PWG raster encoders, and
WsdBackend, a Network-class registry backend named wsd. It lists only the
printers the app added, discovers nothing, maps printer elements to
PrinterDetails and errors to the neutral PrintError with wsd-fault native codes.
Tests run it through the registry against an in-memory fake printer and hostile
loopback servers; a loopback test against a real fakeprint server runs only when
FAKEPRINT_URL is set.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…build in CI

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…ob status, cancel and classified retries

WsdBackend::submit creates the job and sends the document and returns as soon as SendDocument is accepted; it no longer polls for up to five minutes. The job handle is wsd:<printer url>#<job id>. job_status is one GetJobElements mapped onto the neutral JobStatus (a forgotten job is NotFound with a message that says so), cancel_job is the tolerant CancelJob, watch_support is Poll and the recommended interval is configurable (with_poll_interval replaces with_poll).

Errors are classified by what failed and which operation was in flight: transient or not, safe to repeat or not, phase, and a suggested wait. HTTP 408, 425, 429 and 5xx except 501 and 505 are retryable; a refused redirect, a policy refusal, 501 and 505 are not. A connection closed or a timeout after a create or send may have been delivered, so it is outcome-unknown and the backend leaves any created job alone; the same failure on a query or cancel is idempotent. WsdBackend::reconcile looks for the job by title and user before anything is resent.

Tests: submit returns while the printer keeps the job, a watch on an injected clock, a forgotten job, a lost reply to SendDocument and CreatePrintJob with reconcile, no automatic retry of an outcome-unknown submit, and the retry table for every error kind and operation.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…kinds, stages and Retry-After

The WSD adapter now follows craft-wsd's typed errors: a transport failure carries its kind and the stage the exchange reached, an HTTP status error and a fault carry the printer's Retry-After, and the safety of repeating comes from craft-wsd's own retry_safety(idempotent) instead of reading the failure text. The closed-connection error kind is gone (it is a transport kind now), the retry table and its tests cover every typed kind against every operation, and the lock follows craft-wsd to its new commit.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
… other non-retryable HTTP errors

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
craft-wsd replaced TransportKind::Other with InvalidResponse (a peer that did not speak HTTP: Failed, not retryable) and Io (an I/O error that matched no other kind: Unavailable, retryable), both at the reply stage. A request the HTTP client could not build now arrives as Invalid, which stays a preparation failure and Safe. The retry table, the every-kind test and the lifecycle doc follow, and the lock resolves craft-wsd e06d454.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
SubmitRequest carries JobOptions (media, orientation, quality, resolution, an explicit colour choice and the expected page count) as hints a backend may ignore, with new JobHint entries for what it honours. JobRef is replaced by a typed JobId with Display, FromStr, backend(), native() and new(), a typed ParseJobIdError, and the registry, watch and free functions take it. Progress is now an event with an optional total, and the expected page count becomes the sheet total for progress events and status readings only where the backend reports none.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
… feature

The wsd backend maps JobOptions into each job's ticket (media size, orientation, quality, resolution, explicit colour) and keeps the ticket shape, strict mode and transfer as backend-wide configuration; a clone with different settings shares the printer list, which is how an app varies them per invocation. WsdBackend::job_id, parse_native and parse_job_id name and read wsd jobs without string handling, and a wsd backend refuses a job id of another backend. The new cargo feature testing exports craft_print::testing::FakeBackend and craft_print::wsd::testing (the in-memory WS-Print printer), and the crate's own tests use them in place of their private copies.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…nings

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
… the feature is off

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…and the common remote-job base

It describes one PrintJob per user-visible print that survives retries, the tag that lets a reconcile find an already-created job, and the backend-neutral job listing that CUPS, IPP, the Windows spooler and WS-Print can each fill in, with a per-source mapping table.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
A leaf crate: NativeCode, BackendName/JobId/DeviceId, RetrySafety/RetryPolicy
and advise() with seeded jitter, plus plain data records a UI can show for
print and scan alike (JobView, DeviceView, Tag, Fingerprint, Tri indicators).
No lifecycle, reconcile engine or I/O.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…tral job listing

PrintJob is the lifecycle record of one user-visible print: the caller advances it with one bounded request per step on an injectable clock, it retries only what is safe, parks an unknown outcome in NeedsAttention for a reconcile, and keeps the attempts, a de-duplicated status trail and progress. Each print makes a short random tag that a backend carries where its protocol allows (default on for network backends, off for the local spooler), so a reconcile can find a job whose reply was lost. RemoteJob, JobFilter, Fingerprint and Reconciled with the optional Backend methods list_jobs, find_job, tag_support and job_query_caps give CUPS, IPP, the Windows spooler and WS-Print one common base; the registry routes them by printer id. The WS-Print backend carries the tag in the ticket job name and lists active and finished jobs, and the exported fakes gain CUPS-like and IPP-like presets, scripted lost replies and a queue to inspect.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Thirty-five tests drive PrintJob through the exported fakes on a manual clock (state machine, automatic retry and its limits, the tag, reconcile, cancel in every state, foreign jobs, totals, snapshots) and five more run it over the WS-Print backend and its in-memory printer, including a lost SendDocument reply that is reconciled by tag. The README gets a section on tracked jobs and the new fakes, and the job lifecycle note points to the design note.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
The shared vocabulary now comes from the craft-job crate (storytold#120) and is re-exported at the old paths: JobId, NativeCode, RetrySafety, RetryPolicy, Jitter, RetryAdvice, JobState, Progress, ExpectedTotals, Tag, TagSupport, TagPlacement and Fingerprint. The duplicated definitions are removed from craft-print, and the printing-only helpers (a random tag, applying it to a name within a length limit, the reconcile listing a fingerprint asks for, expected totals from a request, jitter from a clock) are extension traits.

Renames that break callers: JobTag is Tag (now Copy), ParseJobIdError is ParseIdError, RetryAdvice::CheckPrinterFirst is CheckDeviceFirst, JobState::Stopped is NeedsAttention, TagPlacement::JobName and Native are JobNameSuffix and NativeAttribute, TagSupport is an enum instead of a struct with a matchable flag, and RetryPolicy::next_delay is replaced by craft_job::advise through advise_error. JobState::CompletedWithWarnings is gone: a completed job the printer qualified is Completed with JobStatus::warnings, and a PrintJob still ends as Outcome::CompletedWithWarnings.

PrintJob::view and Snapshot::view give the print as a craft_job::JobView (state, reasons and warnings, progress, wall-clock times, the document sent, attempts, the last error with its retry advice and native code, the tag and the printer). Snapshot gains a times field.

Docs and tests are updated; print_job_view.rs covers the view for every lifecycle state.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…format conversion

Quality gains Photo (a hint, like the others). DocumentFormat gains Jpeg, Png, Tiff, PlainText, Xps
and OpenXps with mime(), from_mime(), extension(), from_extension(), sniff(), detect() and a
configurable negotiate() against a printer's own list.

PrinterDetails lists the printer's resolutions. The app registers a DocumentConverter; when a
printer does not accept the document's format the registry picks the best target the converter
makes and the printer lists, chooses the resolution nearest a target dpi from the printer's list,
runs the converter and sends the result, or fails with a typed UnsupportedFormat naming both sides.
A neutral PWG raster encoder (craft_print::pwg) is available without the wsd feature. The built-in
spooler stays PDF-only.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…sion

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…ons and registry conversion

The WS-Print backend maps Quality::Photo into the ticket when the printer lists it (leaves it out
with a warning otherwise, refuses it in strict mode), names every listed MIME type that has a
DocumentFormat and passes a document in any of them through unchanged, and fills
PrinterDetails::resolutions from the GetPrinterElements it already reads. It reports
formats_per_printer, so a registry with a converter reads the printer's list before converting.
wsd::pwg now re-exports the neutral craft_print::pwg encoder. The fakes gain qualities and
resolutions (FakePrinter) and per-printer formats (FakeBackend).

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Off by default; with it, the ids, tags, timestamps, records, JobView and
DeviceView derive Serialize and Deserialize so an app can journal and print
jobs without hand-written JSON. Lowercase snake_case names, ids as strings
through Display/FromStr, durations as whole milliseconds, NativeCode and
IndicatorKey strings interned on the way in (bounded), unknown fields ignored,
optional fields defaulted, and a documented Unknown fallback where one exists.
Round-trip tests behind the feature (serde_json is a dev-dependency), CI runs
clippy, tests, docs and the wasm32 check with it, README documents the wire
format.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
b1tninja and others added 6 commits October 14, 2026 11:56
Brings in Quality::Photo, the extra document formats and negotiation, printer resolutions, the document converter path, the public pwg module and the fake additions. The craft-job names and types win for the shared vocabulary; the converter path, formats and resolutions are kept. PrintJob now records the conversion the registry made (RequestRecord and Snapshot), shows the document as it was sent in view(), and a new test file covers a tracked print with a converter, a retry that converts again, and Photo on a raster-only WS-Print fake.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Brings in the README fix and the optional serde feature of craft-job; the feature is not enabled here.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…wait out the device before advising a resend

PrintJobConfig gets a Staleness policy. Silence of three minutes or an unchanged reading for ten minutes while processing (thirty while pending) sends the print to NeedsAttention with the reasons no-news-since and stalled, probing every thirty seconds so a printer that comes back is noticed. Held and stopped jobs never time out. Three hours after acceptance the row ends as the new Outcome::Abandoned, which is not a failure and never causes a resend, and dismiss and dismiss_and_cancel end it earlier. Backends without status are not polled and never time out. After a send whose outcome is unknown the advice to resend waits for the device's own window (Backend::open_job_timeout, 65 seconds for WS-Print), and a reconcile that finds a document-timeout abort advises an immediate retry. Staleness::disabled keeps the earlier behaviour. The design note has a new section on the timeouts and their sources.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…eported

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…acking

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…, now that craft-job has the state

The reason abandoned-no-outcome is kept. Tests, the design note and the README no longer say craft-job lacks an abandoned state.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@b1tninja

Copy link
Copy Markdown
Contributor Author

Folded into #116, which now carries the whole print stack as one pull request, as six logical commits. The tracked-job commit here is the third of those, with the same content (the craft-job dependency is now stated in #116 instead of being merged into a separate branch). Closing so there is one print pull request to review and merge.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant