Uninstall Mac apps with every file they leave behind, and see why each belongs. Free up space, fine-tune macOS, and set up Terminal.
Swift cache-cleanercleanerclideveloper-toolsdisk-cleanupdisk-spaceduplicate-finderhomebrewliquid-glassmac-cleanermacosmacos-appmacos-golden-gatemacos-tahoemacos-tweaksswiftswiftuiterminal-themesuninstalluninstaller
Put the helper's ledger and History on the drive before acting on them
Țugui Dragoș494d348cdf04
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.mdindex 9905272a..296ff9d5 100644--- a/ARCHITECTURE.md+++ b/ARCHITECTURE.md@@ -183,8 +183,10 @@ macOS asks the user to approve it once. It talks to the app over XPC.- It opens folders by descriptor and works through them, so a path swapped for a link after the check leadsnowhere.- It keeps a ledger of what it moved, in a folder only root can write (`/private/var/db/com.tuguidragos.Peel.Helper`),- and puts back only what that ledger knows. While the ledger can't be read it moves nothing, and one it can't make- sense of is kept under another name (`DamagedFile`), never written over.+ and puts back only what that ledger knows. An item moves only once its record is on the drive (`DriveFlush`,+ `F_FULLFSYNC`), and History is on the drive before the journal lets a removal's items go. While the ledger can't be+ read it moves nothing, and one it can't make sense of is kept under another name (`DamagedFile`), never written+ over.- An update needs nothing from the person. launchd starts `Contents/MacOS/PeelHelper` from the app as it is atthat moment, under a spawn constraint that names only the team and the helper's identifier, so the next requestruns the new helper, and a helper still running when an update replaced its program quits as soon as it is idlediff --git a/Packages/PeelCore/Sources/PeelCore/Removal/RemovalLog.swift b/Packages/PeelCore/Sources/PeelCore/Removal/RemovalLog.swiftindex 0179d607..cf86492e 100644--- a/Packages/PeelCore/Sources/PeelCore/Removal/RemovalLog.swift+++ b/Packages/PeelCore/Sources/PeelCore/Removal/RemovalLog.swift@@ -38,11 +38,17 @@ public actor RemovalLog {/// What removals moved and have not recorded yet, item by item.private let journal: RemovalJournalprivate let totals: URL+ private let flush: @Sendable (String) -> Boolpublic init(url: URL = RemovalHistory.defaultURL) {+ self.init(url: url, flush: DriveFlush.file(at:))+ }++ init(url: URL, flush: @escaping @Sendable (String) -> Bool) {self.url = urljournal = RemovalJournal(beside: url)totals = RemovalTotals.url(beside: url)+ self.flush = flush}/// Reads the log. The read takes the lock too, because reading a damaged file sets it aside and writes back@@ -67,7 +73,11 @@ public actor RemovalLog {return RemovalLogOutcome(records: nil, problem: problem)}RemovalTotals.change(at: totals) { $0.add(records) }- journal.forget(records.map(\.trashedItem))+ // The journal is what records these items if History is lost, so it lets them go only once History is on+ // the drive.+ if flush(url.path(percentEncoded: false)) {+ journal.forget(records.map(\.trashedItem))+ }// A removal that is recorded clears an earlier `.couldNotRecord`.if problem == .couldNotRecord { problem = nil }return RemovalLogOutcome(records: updated, problem: problem)diff --git a/Packages/PeelCore/Sources/PeelPrivileged/DriveFlush.swift b/Packages/PeelCore/Sources/PeelPrivileged/DriveFlush.swiftnew file mode 100644index 00000000..18175241--- /dev/null+++ b/Packages/PeelCore/Sources/PeelPrivileged/DriveFlush.swift@@ -0,0 +1,13 @@+import Darwin++/// Waits until the drive holds what was written to a file. `fsync(2)` says a drive may write later data before+/// earlier data, so a record written before a move could be lost in a power cut while the move is kept; `F_FULLFSYNC`+/// (`fcntl(2)`) flushes the drive's queue. A file system that cannot flush it is synced as far as it can be.+public enum DriveFlush {+ public static func file(at path: String) -> Bool {+ let descriptor = open(path, O_RDONLY | O_CLOEXEC | O_NOFOLLOW)+ guard descriptor >= 0 else { return false }+ defer { close(descriptor) }+ return fcntl(descriptor, F_FULLFSYNC) == 0 || fsync(descriptor) == 0+ }+}diff --git a/Packages/PeelCore/Sources/PeelPrivileged/HelperInterface.swift b/Packages/PeelCore/Sources/PeelPrivileged/HelperInterface.swiftindex 568df368..54b9001c 100644--- a/Packages/PeelCore/Sources/PeelPrivileged/HelperInterface.swift+++ b/Packages/PeelCore/Sources/PeelPrivileged/HelperInterface.swift@@ -7,7 +7,7 @@ public enum HelperIdentity {public static let launchdPlistName = "com.tuguidragos.Peel.Helper.plist"/// Raise it whenever the helper changes, so Peel never works with a helper of another version. The helper/// refuses requests that carry any other version.- public static let protocolVersion = 14+ public static let protocolVersion = 15}/// The complete set of privileged operations. The helper validates every argument itself.diff --git a/Packages/PeelCore/Sources/PeelPrivileged/HelperLedger.swift b/Packages/PeelCore/Sources/PeelPrivileged/HelperLedger.swiftindex e77f3c28..4fb1a041 100644--- a/Packages/PeelCore/Sources/PeelPrivileged/HelperLedger.swift+++ b/Packages/PeelCore/Sources/PeelPrivileged/HelperLedger.swift@@ -27,13 +27,18 @@ public final class HelperLedger: Sendable {private let url: URLprivate let maximumEntries: Int+ private let flush: @Sendable (String) -> Bool/// One lock for every ledger in the process: the helper serves each connection on a queue of its own, and each/// request opens the ledger afresh, so a lock of each instance's own would let two requests overwrite each other.private static let lock = NSLock()/// Returns nil when the folder cannot be made private to the helper. Nothing should be moved then either,/// because an item moved without a record cannot be put back.- public init?(at url: URL = HelperLedger.defaultURL, maximumEntries: Int = 20_000) {+ public init?(+ at url: URL = HelperLedger.defaultURL,+ maximumEntries: Int = 20_000,+ flush: @escaping @Sendable (String) -> Bool = DriveFlush.file(at:)+ ) {let folder = url.deletingLastPathComponent().path(percentEncoded: false)mkdir(folder, 0o700)var info = stat()@@ -43,6 +48,7 @@ public final class HelperLedger: Sendable {else { return nil }self.url = urlself.maximumEntries = maximumEntries+ self.flush = flush}/// Records `items` in one write, before any of them moves. Returns false when the write fails, and then@@ -136,6 +142,7 @@ public final class HelperLedger: Sendable {guard let data = try? encoder.encode(Array(entries)), (try? data.write(to: url, options: .atomic)) != nil else {return false}- return chmod(url.path(percentEncoded: false), 0o600) == 0+ let path = url.path(percentEncoded: false)+ return chmod(path, 0o600) == 0 && flush(path)}}diff --git a/Packages/PeelCore/Tests/PeelCoreTests/DriveFlushTests.swift b/Packages/PeelCore/Tests/PeelCoreTests/DriveFlushTests.swiftnew file mode 100644index 00000000..b3b2c9bf--- /dev/null+++ b/Packages/PeelCore/Tests/PeelCoreTests/DriveFlushTests.swift@@ -0,0 +1,13 @@+import Foundation+@testable import PeelPrivileged+import Testing++struct DriveFlushTests {+ @Test func flushesAFileThisMacWrote() throws {+ let directory = try TemporaryDirectory()+ let file = try directory.file("written")++ #expect(DriveFlush.file(at: file.path(percentEncoded: false)))+ #expect(!DriveFlush.file(at: directory.url.appending(path: "missing").path(percentEncoded: false)))+ }+}diff --git a/Packages/PeelCore/Tests/PeelCoreTests/HelperLedgerTests.swift b/Packages/PeelCore/Tests/PeelCoreTests/HelperLedgerTests.swiftindex 71bcb5cb..85903326 100644--- a/Packages/PeelCore/Tests/PeelCoreTests/HelperLedgerTests.swift+++ b/Packages/PeelCore/Tests/PeelCoreTests/HelperLedgerTests.swift@@ -1,4 +1,5 @@import Foundation+import Synchronization@testable import PeelPrivilegedimport Testing@@ -41,6 +42,24 @@ struct HelperLedgerTests {return try TrashMover.move(item, into: try #require(policy.openTrash(ownedBy: getuid()))).get()}+ @Test func nothingMovesBeforeItsRecordIsOnTheDrive() throws {+ let directory = try TemporaryDirectory()+ let policy = try policy(in: directory)+ let url = directory.url.appending(path: "private/moved.plist")+ let flushed = Mutex<[String]>([])+ let ledger = try #require(HelperLedger(at: url) { path in+ flushed.withLock { $0.append(path) }+ return true+ })+ let unflushed = try #require(HelperLedger(at: url) { _ in false })+ try directory.file("root/Library/Caches/com.example.plist")+ let item = try policy.open(path("root/Library/Caches/com.example.plist", in: directory)).get()++ #expect(ledger.record([item], movedBy: getuid()))+ #expect(flushed.withLock { $0 } == [url.path(percentEncoded: false)])+ #expect(!unflushed.record([item], movedBy: getuid()), "an item could move with its record not on the drive")+ }+@Test func knowsWhereItTookAnItemFromWhateverItIsCalledNow() throws {let directory = try TemporaryDirectory()let policy = try policy(in: directory)diff --git a/Packages/PeelCore/Tests/PeelCoreTests/RemovalJournalTests.swift b/Packages/PeelCore/Tests/PeelCoreTests/RemovalJournalTests.swiftindex 2c840537..7a7a181b 100644--- a/Packages/PeelCore/Tests/PeelCoreTests/RemovalJournalTests.swift+++ b/Packages/PeelCore/Tests/PeelCoreTests/RemovalJournalTests.swift@@ -76,6 +76,26 @@ struct RemovalJournalTests {#expect(journal.entries().isEmpty, "History recorded the item and the journal kept it")}+ @Test func historyIsOnTheDriveBeforeTheJournalLetsGo() async throws {+ let directory = try TemporaryDirectory()+ let history = directory.url.appending(path: "Peel/removals.json")+ let journal = RemovalJournal(beside: history)+ let moved = item("com.example.app", in: directory)+ journal.note([moved], batch: UUID(), by: .current)+ let flushed = Mutex<[(path: String, waiting: Int)]>([])+ let log = RemovalLog(url: history) { path in+ flushed.withLock { $0.append((path, journal.entries().count)) }+ return true+ }++ let record = RemovalRecord(batch: UUID(), item: moved, size: 10, source: "Editor", tool: "applications")+ _ = await log.add([record])+ _ = await log.remove([record.id])++ #expect(flushed.withLock { $0.map(\.path) } == [history.path(percentEncoded: false)])+ #expect(flushed.withLock { $0.first?.waiting } == 1, "the journal let the item go before History was on the drive")+ }+/// An item History already has is never recorded twice, as when a process wrote History and stopped before it/// could let the journal go.@Test func anItemHistoryHasIsNotRecordedAgain() async throws {diff --git a/SAFETY.md b/SAFETY.mdindex c5d2b30e..7d886544 100644--- a/SAFETY.md+++ b/SAFETY.md@@ -470,8 +470,9 @@ and it fails closed.it. It keeps its own ledger, in a folder that is root's alone, of what it moved and from where: the item isrecognized by what it is (not by its name or place in the Trash), and it goes back only to the exact placethe helper took it from. Something dropped into your Trash by hand, or swapped in under a known name, stays- there. While the ledger can't be read, the helper moves nothing and puts nothing back; one it can't make sense- of is kept under another name, never written over, and a new one begins. A folder that code is loaded from+ there. An item moves only once its record is on the drive itself, so a power cut can't keep the move and lose+ the record. While the ledger can't be read, the helper moves nothing and puts nothing back; one it can't make+ sense of is kept under another name, never written over, and a new one begins. A folder that code is loaded fromtakes back only what is still owned by root and writable by nobody else.If you never install the helper, Peel still works; it just cannot touch what needs administrator rights.