Skip to content

Run Windows games on Apple Silicon — free, open source, with an open compatibility database that tells you what actually works.

Failures show a sentence, a meaning and one button; raw output moves behind Details

Gauthier Piarretteb2132dbf9547
diff --git a/Sources/HighballApp/AppState.swift b/Sources/HighballApp/AppState.swift
index 8003d27..e36be44 100644
--- a/Sources/HighballApp/AppState.swift
+++ b/Sources/HighballApp/AppState.swift
@@ -61,6 +61,26 @@ final class AppState {
}
var errorMessage: String?
+ /// The recovery the error alert shows (headline, meaning, one button) and what its button
+ /// runs. Set together with errorMessage, which keeps the raw text for the details view.
+ var errorRecovery: Recovery?
+ var errorRetry: (() -> Void)?
+ var errorBottle: Bottle?
+ var showErrorDetails = false
+
+ /// The one place failures are put in front of the user: the recovery sentences on the alert,
+ /// the raw description behind Details, and the retry the button runs when the recovery
+ /// says so. `bottle` lets a Repair recovery know what to repair.
+ func fail(_ error: Error, retry: (() -> Void)? = nil, bottle: Bottle? = nil) {
+ errorIsPartialSuccess = false
+ errorRecovery = Recovery.describe(error)
+ errorRetry = retry
+ errorBottle = bottle
+ errorMessage = Self.message(for: error)
+ errorDetailsText = errorMessage ?? ""
+ }
+ /// The raw description of the last failure, for the Details sheet.
+ var errorDetailsText = ""
/// True when errorMessage describes an operation that SUCCEEDED with something left over,
/// so the alert can say so instead of calling it a failure.
var errorIsPartialSuccess = false
@@ -191,7 +211,7 @@ final class AppState {
panel.message = String(format: L("Choose a cover image for %@"), item.title)
guard panel.runModal() == .OK, let url = panel.url else { return }
do { try coverStore.setCover(for: item.id, from: url); coverVersion += 1 }
- catch { errorIsPartialSuccess = false; errorMessage = Self.message(for: error) }
+ catch { fail(error) }
}
func resetCover(for item: LibraryItem) {
@@ -413,7 +433,12 @@ final class AppState {
do {
try await work()
doneState = done ?? DoneState(title: L("Done"), ctaTitle: nil, cta: nil)
- } catch { showLog = false; errorIsPartialSuccess = false; errorMessage = Self.message(for: error) }
+ } catch {
+ showLog = false
+ // A retry is the same operation with the same closure; the sheet's own state
+ // resets when runBusy starts again.
+ fail(error, retry: { [weak self] in self?.runBusy(title, expected: expected, showLogSheet: showLogSheet, done: done, cleanup: cleanup, work) })
+ }
cleanup?()
busy = false
refresh()
@@ -450,7 +475,7 @@ final class AppState {
func acceptGPTK(engine: InstalledEngine) {
do { _ = try engineStore.accept(license: "apple-gptk-license-2023-08-17", engine: engine); refresh() }
- catch { errorIsPartialSuccess = false; errorMessage = Self.message(for: error) }
+ catch { fail(error) }
}
func createBottle(name: String, recipeID: String?) {
@@ -549,7 +574,7 @@ final class AppState {
}
func update(_ bottle: Bottle) {
- do { try bottleStore.update(bottle); refresh() } catch { errorIsPartialSuccess = false; errorMessage = Self.message(for: error) }
+ do { try bottleStore.update(bottle); refresh() } catch { fail(error, bottle: bottle) }
}
func deleteBottle(_ name: String) {
diff --git a/Sources/HighballApp/HighballApp.swift b/Sources/HighballApp/HighballApp.swift
index 8364671..1956132 100644
--- a/Sources/HighballApp/HighballApp.swift
+++ b/Sources/HighballApp/HighballApp.swift
@@ -292,18 +292,37 @@ struct ContentView: View {
// A partial delete succeeded — the bottle is gone and the name is free — so framing it as
// a failure, with an invitation to file a bug, misreads what happened. Same alert, honest
// title, and no Report button for something that is not a problem to report.
- .alert(state.errorIsPartialSuccess ? L("Some files couldn't be removed") : L("Something went wrong"),
+ .alert(state.errorIsPartialSuccess ? L("Some files couldn't be removed") : (state.errorRecovery.map { L($0.headline) } ?? L("Something went wrong")),
isPresented: .init(
get: { state.errorMessage != nil },
set: { if !$0 { state.errorMessage = nil } })) {
- Button("OK") { state.errorMessage = nil }
+ // One button that does the next thing, when the failure has one (UX plan §3.6).
+ if let r = state.errorRecovery, let title = r.actionTitle, !state.errorIsPartialSuccess {
+ Button(L(title)) {
+ let retry = state.errorRetry, bottle = state.errorBottle
+ state.errorMessage = nil
+ switch r.action {
+ case .retry: retry?()
+ case .repairBottle: if let bottle { state.repairBottle(bottle) } else { retry?() }
+ case .none: break
+ }
+ }
+ }
+ Button(L("Details…")) { state.showErrorDetails = true; state.errorMessage = nil }
if !state.errorIsPartialSuccess {
Button(L("Report this problem…")) {
state.errorMessage = nil
NSWorkspace.shared.open(BugReport.url(version: Bundle.main.infoDictionary?["CFBundleShortVersionString"] as? String ?? "dev"))
}
}
- } message: { Text(state.errorMessage ?? "") }
+ Button("OK", role: .cancel) { state.errorMessage = nil }
+ } message: {
+ // The meaning, in words; exit codes, paths and raw output live behind Details.
+ Text(state.errorIsPartialSuccess ? (state.errorMessage ?? "") : (state.errorRecovery?.meaning ?? ""))
+ }
+ .sheet(isPresented: Binding(get: { state.showErrorDetails }, set: { state.showErrorDetails = $0 })) {
+ ErrorDetailsSheet(text: state.errorDetailsText)
+ }
.alert(crashTitle, isPresented: Binding(get: { state.crashSuggestion != nil }, set: { if !$0 { state.crashSuggestion = nil } }),
presenting: state.crashSuggestion) { s in
Button("Use \(s.renderer.rawValue.uppercased())") {
@@ -435,3 +454,25 @@ struct LogSheet: View {
.padding(16)
}
}
+
+/// The raw description of a failure: what a report needs, kept off the primary surface.
+struct ErrorDetailsSheet: View {
+ @Environment(\.dismiss) private var dismiss
+ let text: String
+ var body: some View {
+ VStack(alignment: .leading, spacing: 12) {
+ Text(L("Details")).font(.title3.bold())
+ ScrollView {
+ Text(verbatim: text).font(.body.monospaced()).textSelection(.enabled)
+ .frame(maxWidth: .infinity, alignment: .leading)
+ }
+ HStack {
+ Button(L("Copy")) { NSPasteboard.general.clearContents(); NSPasteboard.general.setString(text, forType: .string) }
+ Spacer()
+ Button(L("Done")) { dismiss() }.keyboardShortcut(.defaultAction)
+ }
+ }
+ .padding(16)
+ .frame(minWidth: 520, minHeight: 320)
+ }
+}
diff --git a/Sources/HighballApp/L10n.swift b/Sources/HighballApp/L10n.swift
index d5810fe..3b793c1 100644
--- a/Sources/HighballApp/L10n.swift
+++ b/Sources/HighballApp/L10n.swift
@@ -178,6 +178,22 @@ enum L10n {
"Details": "Détails",
"Run and add to Programs": "Lancer et ajouter aux programmes",
"Keep current": "Garder l’actuel",
+ "Try again": "Réessayer",
+ "Download again": "Retélécharger",
+ "Repair": "Réparer",
+ "Details…": "Détails…",
+ "Copy": "Copier",
+ "The download could not reach the server.": "Le téléchargement n'a pas pu joindre le serveur.",
+ "The download stopped waiting for data.": "Le téléchargement a cessé de recevoir des données.",
+ "The download stopped.": "Le téléchargement s'est arrêté.",
+ "Highball keeps what it already received and continues from there.": "Highball garde ce qui est déjà reçu et reprend à partir de là.",
+ "The download didn't arrive intact.": "Le téléchargement n'est pas arrivé intact.",
+ "This is usually a network problem. Highball discards the damaged file and downloads it again.": "C'est en général un problème réseau. Highball supprime le fichier abîmé et le retélécharge.",
+ "The Windows environment didn't finish setting up.": "L'environnement Windows n'a pas fini de s'installer.",
+ "Highball can run the setup again.": "Highball peut relancer l'installation.",
+ "Highball can try again with a fresh copy.": "Highball peut réessayer avec une copie neuve.",
+ "Its 32-bit half is missing, which most installers need. Highball can repair it.": "Sa moitié 32 bits manque, dont la plupart des installeurs ont besoin. Highball peut la réparer.",
+ "Something Highball needs is missing.": "Il manque quelque chose dont Highball a besoin.",
"download": "téléchargement",
"Try engine %@": "Essayer le moteur %@",
"Moving '%@' to %@": "Déplacement de '%@' vers %@",
diff --git a/Sources/HighballKit/Recovery.swift b/Sources/HighballKit/Recovery.swift
new file mode 100644
index 0000000..195ffbe
--- /dev/null
+++ b/Sources/HighballKit/Recovery.swift
@@ -0,0 +1,71 @@
+import Foundation
+
+/// What a failure looks like on the primary surface: one sentence about what happened, one
+/// about what it means, and at most one button that does the next thing (UX plan §3.6). Raw
+/// output and exit codes never appear here; they stay behind a details view. A cause is named
+/// only when the app actually detected it: a 60-second timeout is not "your connection dropped".
+public struct Recovery: Equatable, Sendable {
+ public enum Action: Equatable, Sendable {
+ /// Run the same operation again (installs, downloads, recipe steps).
+ case retry
+ /// Re-run the bottle's Windows setup.
+ case repairBottle
+ /// Nothing automatic; the details and a report are the next step.
+ case none
+ }
+ public var headline: String
+ public var meaning: String
+ public var actionTitle: String?
+ public var action: Action
+
+ public init(headline: String, meaning: String, actionTitle: String? = nil, action: Action = .none) {
+ self.headline = headline; self.meaning = meaning; self.actionTitle = actionTitle; self.action = action
+ }
+
+ /// The mapping from what actually failed to what the user sees. Unknown failures keep their
+ /// own message as the headline so nothing is hidden, and get no button.
+ public static func describe(_ error: Error) -> Recovery {
+ if let url = error as? URLError {
+ switch url.code {
+ case .notConnectedToInternet, .networkConnectionLost, .cannotFindHost, .cannotConnectToHost, .dnsLookupFailed:
+ return Recovery(headline: "The download could not reach the server.",
+ meaning: "Highball keeps what it already received and continues from there.",
+ actionTitle: "Try again", action: .retry)
+ case .timedOut:
+ return Recovery(headline: "The download stopped waiting for data.",
+ meaning: "Highball keeps what it already received and continues from there.",
+ actionTitle: "Try again", action: .retry)
+ default:
+ return Recovery(headline: "The download stopped.",
+ meaning: "Highball keeps what it already received and continues from there.",
+ actionTitle: "Try again", action: .retry)
+ }
+ }
+ guard let known = error as? HighballError else {
+ return Recovery(headline: (error as NSError).localizedDescription, meaning: "")
+ }
+ switch known {
+ case .checksumMismatch:
+ return Recovery(headline: "The download didn't arrive intact.",
+ meaning: "This is usually a network problem. Highball discards the damaged file and downloads it again.",
+ actionTitle: "Download again", action: .retry)
+ case let .processFailed(command, _, _) where command.hasPrefix("wineboot"):
+ return Recovery(headline: "The Windows environment didn't finish setting up.",
+ meaning: "Highball can run the setup again.",
+ actionTitle: "Repair", action: .repairBottle)
+ case let .processFailed(command, _, _):
+ let name = command.split(separator: " ").first.map(String.init) ?? "The installer"
+ return Recovery(headline: "\(name) didn't finish.",
+ meaning: "Highball can try again with a fresh copy.",
+ actionTitle: "Try again", action: .retry)
+ case let .invalid(what) where what.contains("32-bit"):
+ return Recovery(headline: "The Windows environment didn't finish setting up.",
+ meaning: "Its 32-bit half is missing, which most installers need. Highball can repair it.",
+ actionTitle: "Repair", action: .repairBottle)
+ case let .missing(what):
+ return Recovery(headline: "Something Highball needs is missing.", meaning: what)
+ case let .invalid(what), let .failed(what):
+ return Recovery(headline: what, meaning: "")
+ }
+ }
+}
diff --git a/Tests/HighballKitTests/RegressionTests.swift b/Tests/HighballKitTests/RegressionTests.swift
index a210498..e65fd34 100644
--- a/Tests/HighballKitTests/RegressionTests.swift
+++ b/Tests/HighballKitTests/RegressionTests.swift
@@ -1010,6 +1010,24 @@ extension RegressionTests {
try? FileManager.default.removeItem(at: dir)
}
+ // Failures reach the user as a sentence, a meaning and at most one button (plan §3.6).
+ func testRecoveryMapping() {
+ let mismatch = Recovery.describe(HighballError.checksumMismatch(file: "engine.tar.gz", expected: "a", actual: "b"))
+ XCTAssertEqual(mismatch.action, .retry); XCTAssertEqual(mismatch.actionTitle, "Download again")
+ XCTAssertFalse(mismatch.headline.contains("engine.tar.gz"), "no file names on the primary surface")
+ let boot = Recovery.describe(HighballError.processFailed(command: "wineboot -u", status: 1, output: "see /tmp/x.log"))
+ XCTAssertEqual(boot.action, .repairBottle)
+ XCTAssertFalse(boot.headline.contains("1") || boot.meaning.contains("/tmp"), "no exit codes or paths")
+ let installer = Recovery.describe(HighballError.processFailed(command: "VC_redist.x64.exe /install", status: 3010, output: ""))
+ XCTAssertEqual(installer.action, .retry); XCTAssertTrue(installer.headline.hasPrefix("VC_redist.x64.exe"))
+ let wow = Recovery.describe(HighballError.invalid("Windows 32-bit support couldn't be set up in this bottle"))
+ XCTAssertEqual(wow.action, .repairBottle)
+ let net = Recovery.describe(URLError(.timedOut))
+ XCTAssertEqual(net.action, .retry); XCTAssertFalse(net.headline.lowercased().contains("connection dropped"), "a timeout is not a diagnosed cause")
+ let plain = Recovery.describe(HighballError.failed("Steam is already running."))
+ XCTAssertEqual(plain.headline, "Steam is already running."); XCTAssertNil(plain.actionTitle)
+ }
+
func testDefaultEnginePrefersBundledManifestID() throws {
func engine(_ id: String) throws -> InstalledEngine {
let json = #"{"id":"\#(id)","displayName":"e","arch":"x86_64","minMacOS":"14.0","components":{}}"#