QwkSync

QWKSync.NET Error Model

Goals

• Fail safely.
• Be deterministic.
• Make failures understandable and actionable.
• Never leak credentials in diagnostics or errors. 

---

Public reporting surface

The primary output of a sync is a QwkSyncResult which includes:

• Outcome (overall result classification)
• Issues (a list of QwkSyncIssue entries) 

Progress and logging are informational only and do not affect behaviour. 

This model allows callers to:

• treat completion vs failure deterministically,
• inspect a stable set of issues,
• avoid relying on transport-specific exception types.

---

Exceptions vs result issues

QWKSync.NET uses both. It uses exceptions for unrecoverable failures and cancellation, and it uses issues for structured reporting when a coherent result can be returned.

• Exceptions: for unrecoverable errors that prevent producing a meaningful session result, or when cancellation is requested and must interrupt promptly.

• Result issues: for structured reporting about what happened during the session, including failures encountered and policy decisions taken, as long as a coherent session result can still be returned.

Where a transport extension throws, QWKSync.NET should capture and translate into issues only when doing so does not hide cancellation, concurrency conflicts, or unrecoverable I/O errors that prevent a coherent result.

Cancellation

• All operations accept a CancellationToken.
• Cancellation interrupts I/O promptly.
• Cancellation triggers cleanup of temporary files created by the session. 

Timeouts

TransferPolicy.Timeout exists and should be enforced deterministically per transport call, aligned to TransferPolicy.Timeout semantics in the public API doc. It should not introduce heuristic behaviour. 

Retry failures

Retry behaviour is core-orchestrated, bounded, deterministic, and configured via policy:

• Default: MaxRetries = 0 (no retries). 
• No adaptive or heuristic retries. 

When retries are enabled:

• Each failed attempt should be recorded as an issue (or aggregated into a single issue that includes attempt count), without changing ordering or introducing parallelism.
• Use a single issue per operation with fields for attempt count and last error summary, unless the public issue model explicitly supports per-attempt entries.

Resume behaviour

Resume is transport-owned and disabled by default. QWKSync.NET never assumes resume exists. If a transport extension cannot resume, it must fall back to a full transfer or fail clearly. 

QWKSync.NET error handling does not depend on resume being available.

Atomicity and partial transfers

Atomicity is mandatory:

• Downloads go to a temporary file.
• Successful downloads finalise via atomic move into place.
• Partial downloads are detected and removed.
• Temp files are cleaned up on failure or cancellation. 

Any failure during download finalisation:

• leave the destination unchanged,
• remove the temp file where possible,
• report a clear failure reason via issues or exception (depending on whether a result can be produced).

Concurrency violations

QWKSync.NET enforces the single-flight guarantee:

• Only one active sync may operate against the same local inbox, outbox, or profile at a time.
• Concurrent attempts fail fast with a clear error. 

This failure should be easy for the caller to detect and handle. It does not look like a transient transport error.

Credential and diagnostics safety

• Never include credential material in exception messages, result issues, or log sink output.
• Do not persist credentials.
• Keep diagnostics structured and safe.
• No logging framework dependencies in QWKSync.NET. 

This site is open source. Improve this page.