Skip to content

armgit / peel

Public Imported from GitHub
0

Uninstall Mac apps with every file they leave behind, and see why each belongs. Free up space, fine-tune macOS, and set up Terminal.

Put the helper's ledger and History on the drive before acting on them

Țugui Dragoș494d348cdf04
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index 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 leads
nowhere.
- 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 at
that moment, under a spawn constraint that names only the team and the helper's identifier, so the next request
runs the new helper, and a helper still running when an update replaced its program quits as soon as it is idle
diff --git a/Packages/PeelCore/Sources/PeelCore/Removal/RemovalLog.swift b/Packages/PeelCore/Sources/PeelCore/Removal/RemovalLog.swift
index 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: RemovalJournal
private let totals: URL
+ private let flush: @Sendable (String) -> Bool
public init(url: URL = RemovalHistory.defaultURL) {
+ self.init(url: url, flush: DriveFlush.file(at:))
+ }
+
+ init(url: URL, flush: @escaping @Sendable (String) -> Bool) {
self.url = url
journal = 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.swift
new file mode 100644
index 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.swift
index 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.swift
index 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: URL
private 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 = url
self.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.swift
new file mode 100644
index 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.swift
index 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 PeelPrivileged
import 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.swift
index 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.md
index 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 is
recognized by what it is (not by its name or place in the Trash), and it goes back only to the exact place
the 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 from
takes 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.