[RFC] Native macOS PBS client: filesystem metadata and tested prototype

[RFC] Native macOS PBS client: filesystem metadata and tested prototype

[Adam Okoń]

Hello,

I would appreciate architectural feedback on a native macOS port of
proxmox-backup-client, based on PBS v4.2.8. The prototype runs without
Docker or a Linux guest and keeps the usual backup/restore CLI, PBS
chunking, deduplication and client-side encryption.

Source and review workspace:
https://github.com/adamokon/proxmox-backup-macos/pull/1

The main design question is preservation of Darwin filesystem
metadata. The prototype uses a bounded, versioned envelope in standard
PXAR xattr records to describe ordered UUID ACLs, birthtime, BSD flags
and native attribute content references. Attribute bytes, including
large resource forks, are content-addressed regular files in an
additional standard PXAR archive in the same snapshot. A
manifest-listed map associates it with the primary archives. The
server protocol and PXAR record format are unchanged. Temporary
spooling is authenticated-encrypted with an ephemeral local key, then
the ordinary PBS encryption and deduplication pipeline processes the
upload stream.

Native archive/restore tests cover Unicode filenames, symlinks,
hardlinks, binary xattrs, FinderInfo, a resource fork larger than 1
MiB, nanosecond times and destination name alias rejection before
truncation. A fresh Homebrew source installation on Apple Silicon also
passed backup and restore against a dedicated PBS test namespace, both
unencrypted and client-side encrypted. Repeated backups reused 100% of
primary and auxiliary archive data. Linux client compilation and
format regression checks accompany the port.

The work also separates client formats from Linux server dependencies
and fixes native fd/xattr/time/UUID APIs and mmap alignment on 16 KiB
pages. The inherited endian_trait ownership issue (RUSTSEC-2021-0039)
is addressed by a documented local MIT-licensed compatibility fork
using panic-safe array mapping and Copy-bound slices; it is not
presented as a published upstream fix.

Current scope and limits: Apple Silicon is tested; Intel is not yet
tested. FUSE mount/map remain Linux-only. There is no automatic iCloud
placeholder download or atomic APFS snapshot. Protected system-managed
xattrs can produce explicit restore warnings. This is an experimental
prototype, not a claim of official support or a merge-ready packaging
series.

The implementation was developed with extensive AI assistance. Its
provenance, source patches and actual test results are available for
review. Proxmox confirmed on 26 October 2026 that my Individual CLA is
on record for future contributions. No independent human code review
is claimed at this stage.

Before preparing a cleaned-up cross-repository patch series, would
this native client scope and metadata representation fit the upstream
architecture? I would welcome guidance on a preferred representation,
required review and how to split the
proxmox-backup/proxmox/pxar/pathpatterns changes.

Best regards,
Adam Okoń