Don't Materialize the Cloud by Accident

"That 4 GB video in your iCloud folder might be zero bytes on this Mac. Touch it wrong and you just downloaded it — and maybe filled the disk."

The File That Isn't Really There

Modern macOS is full of placeholders — files that appear in a folder, show a name and a size, but whose actual bytes live on a server and haven't been downloaded to this machine. iCloud Drive's "Optimize Mac Storage," Dropbox's online-only files, any File Provider: they all present dataless stand-ins. The file is real as a name and metadata; the content is a promise the OS will fulfill if something asks for it.

The Accidental Download

Here's the trap. If Waygate reads a placeholder's contents during enumeration to make a thumbnail, or opens it during a batch copy, the OS dutifully downloads the whole file to satisfy the read. Do that across a folder of placeholders and you've silently pulled down gigabytes — filling the disk you were trying to manage, and possibly running up metered-connection charges. The user asked to look at a folder, not to download its entire cloud backlog.

Waygate's Rule: Consequence Must Be Visible

So Waygate does not materialize cloud placeholders by accident. Enumeration reads metadata without triggering downloads; previews of dataless files show a 'not downloaded' state rather than forcing materialization. When an operation genuinely needs the bytes — you really are copying that file somewhere — Waygate surfaces that it will download, so the consequence is chosen, not sprung. Visible-and-chosen beats silent-and-surprising, especially when the surprise is measured in gigabytes.

Cloud and file-provider placeholders are never silently materialized by preview or batch enumeration. A transfer that genuinely requires downloading shows that consequence up front. Waygate reads placeholder metadata without pulling bytes, and only materializes when an operation truly needs the content — visibly, never by accident.

Metadata is free; content is not. The key distinction is that a placeholder's name, size, dates, and type are available without downloading — that's what lets Waygate show the folder honestly. It's reading the CONTENT that triggers materialization. Design every 'quick look at the folder' path to touch only metadata, and reserve content reads for operations that have visibly committed to needing the bytes.

Code

See placeholders without downloading them·swift

func classifyForDisplay(_ url: URL) throws -> RowState {
    let vals = try url.resourceValues(forKeys: [
        .isUbiquitousItemKey,
        .ubiquitousItemDownloadingStatusKey,   // .notDownloaded / .downloaded / .current
        .fileSizeKey                            // METADATA -- safe, no download
    ])
    if vals.isUbiquitousItem == true,
       vals.ubiquitousItemDownloadingStatus == .notDownloaded {
        return .placeholder(size: vals.fileSize)   // show it as online-only
    }
    return .local(size: vals.fileSize)
}
// Reading .fileSize / dates / type does NOT materialize the file.
// Reading its CONTENTS would. Display paths must stay on the metadata side.

Exercise

You have an iCloud folder with 200 online-only 4K videos, 4 GB each. A file manager generates thumbnails by reading each file's content on scroll. Calculate what happens to your disk as you scroll the folder once. Then redesign the thumbnail path so browsing the folder downloads nothing, and downloading only happens when you explicitly act on a file.

Hint

Reading content to thumbnail 200 files at 4 GB each would try to download 800 GB just from scrolling — filling the disk and hammering the connection. The fix: detect the not-downloaded status from metadata and render a placeholder thumbnail (a cloud badge) instead of reading content. Materialization then only happens when the user explicitly opens or copies a specific file, having seen it will download.

Don't Materialize the Cloud by Accident

The File That Isn't Really There

The Accidental Download

Waygate's Rule: Consequence Must Be Visible

Code

External links

Exercise

Progress

Comments 0