QwkSync 1.0.0

QwkSync.NET Library

QwkSync.NET is a small, dependency-free .NET library that safely and predictably moves QWK and REP files between a local application and a remote endpoint.

Overview

QwkSync.NET operates strictly at the transport and orchestration level. It does not parse, validate, or interpret packet contents. It only moves files.

What This Library Does

• Discovers QWK and REP files
• Orders them deterministically
• Transfers them atomically
• Reports what happened

What This Library Does Not Do

• Parse QWK or REP packets
• Validate packet contents
• Understand packet semantics
• Maintain sync history or state

For packet parsing and validation, use QWK.NET or your own parsing logic.

Quick Start

using QwkSync;

// Create a profile pointing to a remote endpoint
QwkSyncProfile profile = new QwkSyncProfile
{
  Endpoint = new Uri("file:///path/to/remote/folder"),
  TransportId = "local-folder"
};

// Create a plan specifying local directories
QwkSyncPlan plan = new QwkSyncPlan
{
  LocalInboxDirectory = "/path/to/local/inbox",
  LocalOutboxDirectory = "/path/to/local/outbox"
};

// Create a client and run the sync
QwkSyncClient client = new QwkSyncClient();

using CancellationTokenSource cts = new CancellationTokenSource();
QwkSyncResult result = await client.SyncAsync(profile, plan, cts.Token);

// Check the result
Console.WriteLine($"Outcome: {result.Outcome}");
Console.WriteLine($"Issues: {result.Issues.Count}");

Transports

Built-in Transport

• LocalFolderTransport - Production-ready transport for local file system operations

Extension Transports

• QwkSync.Http - HTTP transport (extension library)

See creating-transport-extensions.md for information about creating custom transport implementations.

Security Considerations

QwkSync.NET is designed for file transport and orchestration only; it does not parse or validate packet contents. When processing untrusted remote sources:

Path Safety

File names from remote endpoints are used directly. If you cannot trust the remote source, sanitise file names before passing them to QwkSyncClient. Consider validating file names for path separators, reserved characters, and length limits.

Resource Limits

The library does not enforce file size or count limits by default. For untrusted sources, configure TransferPolicy with appropriate timeouts and consider validating file sizes before processing. Monitor disk space when processing many or large files.

Directory Isolation

When using LocalFolderTransport, ensure the root directory is isolated and does not contain sensitive files. The transport prevents path traversal within its root, but should not be used with highly privileged directories.

Logging

If you enable logging via ISyncLogSink, be aware that file names and paths may be logged. Consider sanitising logged information if logs may be exposed or shared.

Concurrency

QwkSync.NET enforces single-flight guarantees for local directories, preventing race conditions. However, ensure your application does not create conflicting sync operations programmatically.

Temporary Files

Downloads use temporary files in the system temp directory (via Path.GetTempPath()). Ensure this directory has appropriate permissions and is not accessible to untrusted processes.

Transport Extensions

When implementing custom transports, ensure they validate and sanitise all path inputs, handle errors safely, and do not expose sensitive information in exceptions or logs.

Requirements

• .NET 10.0 or later
• Cross-platform: Windows 11, macOS 26 (Tahoe)

Installation

dotnet add package QwkSync

Or add to your .csproj:

<ItemGroup>
  <PackageReference Include="QwkSync" Version="1.0.0" />
</ItemGroup>

License

MIT License. See LICENSE file for details.