hex/ios/HEXShared/SpeechModelInstall.swift
Dax c9fc9563ef
iOS: speech model preparation that never answers fails with Try again (#2372)
Apple's speech daemon can stop answering during preparation: the asset
reservation, the status checks before and after a download, the language lookup,
the network check and the release had no time limit. They are now watched at
60 s with StallWatch's suspension-aware deadline, a reservation or release that
never answers is forgotten so the next attempt asks again, and a call whose
success another caller already gave up on is retried rather than believed. A
keyboard check that only hangs counts no strike toward Hex's handoff.

A preparation a newer one replaces, or one the preparation watch ends, is
cancelled, and the keyboard's publish and handoff paths ignore a cancelled
check, so a late answer can't reopen the row. The keyboard's model check retries
after a real background trip. The multilingual download's restart cancels and
awaits the old transfer before resuming its .partial file, and a preparation
that ends in the background is retried on return.
2026-11-22 12:31:22 -05:00

380 lines
17 KiB
Swift

import Foundation
import Network
/// A language Hex can't get Apple's speech model for on this iPhone. Its message is written
/// for people, in Hex's interface language, so it names languages in that language.
nonisolated struct SpeechModelUnavailable: HexDescribedError, Equatable {
enum Reason: Equatable, Sendable {
/// Neither Apple Speech module installs it here, though the iPhone is online.
case notOnThisIPhone
/// The download failed or stalled while offline or on a bad connection.
case downloadFailed
}
/// BCP 47, such as `ru-RU`.
let language: String
let reason: Reason
/// What Automatic picks now that this language is set aside (BCP 47), when it's another one.
var fallback: String?
/// Whether dictation follows Automatic, which moves on to `fallback` by itself.
var automatic: Bool
init(language: String, reason: Reason, fallback: String? = nil, automatic: Bool = true) {
self.language = language
self.reason = reason
self.fallback = fallback
self.automatic = automatic
}
/// Automatic has already moved on to another language for the next dictations.
var switchedAutomatically: Bool {
reason == .notOnThisIPhone && automatic && fallback != nil
}
/// Short enough for the full keyboard's strip (about 60 characters).
var errorDescription: String? {
let name = Self.interfaceName(language)
switch reason {
case .downloadFailed:
return String(localized: "\(name) speech didn't download. Check your connection.")
case .notOnThisIPhone:
guard let fallback else {
return String(localized: "\(name) isn't available for dictation on this iPhone yet.")
}
let other = Self.interfaceName(fallback)
return automatic
? String(localized: "\(name) isn't available on this iPhone yet. Using \(other).")
: String(localized: "\(name) isn't available on this iPhone yet. Try \(other).")
}
}
/// "Russian", "Norwegian Bokmål": the language alone, in Hex's interface language.
static func interfaceName(_ identifier: String) -> String {
let code = Locale(identifier: identifier).language.languageCode?.identifier ?? identifier
let name = Locale.hexInterface.localizedString(forLanguageCode: code) ?? identifier
return name.prefix(1).uppercased() + name.dropFirst()
}
}
/// In-keyboard dictation couldn't get its language's speech model ready itself: an asset
/// released or removed since Hex downloaded it (each process holds its own reservation, and an
/// unreserved one reads as not installed), a download the keyboard couldn't finish, or Speech
/// listing nothing in the keyboard. Hex downloads it in the foreground, so the Hex key opens
/// Hex until a model installs (`LanguageSettings.keyboardNeedsHex`). Never "Apple doesn't
/// have your language": Speech listed the language, or listed nothing at all.
nonisolated struct SpeechModelNeedsHex: HexDescribedError, Equatable {
/// BCP 47, such as `en-US`.
let language: String
/// False for a first failure: the keyboard keeps dictating itself and asks for another try.
var handedOff = true
/// Short enough for the full keyboard's strip (about 60 characters).
var errorDescription: String? {
guard handedOff else { return UserFacingError.Context.transcription.fallback }
return String(localized: "Open Hex to download \(SpeechModelUnavailable.interfaceName(language)).")
}
/// Hands the keyboard's dictation to Hex for `language` and says so, the second time in a
/// row the keyboard couldn't get its model (`LanguageSettings.noteKeyboardModelFailure`).
/// One failure is no evidence: the keyboard tries again itself next time.
static func handOff(_ language: String, settings: LanguageSettings) -> SpeechModelNeedsHex {
guard settings.noteKeyboardModelFailure() else {
return SpeechModelNeedsHex(language: language, handedOff: false)
}
settings.markKeyboardNeedsHex()
return SpeechModelNeedsHex(language: language)
}
/// What the keyboard says when installing `language`'s model failed there. Automatic
/// moving to another language, or a choice that can't be had with one to try instead,
/// keeps `SpeechModelUnavailable`'s sentence: the next dictation works without Hex. A
/// daemon that never answered says so and counts no strike, like a cancelled try;
/// anything else is Hex's to download (`handOff`).
static func keyboardError(for error: Error, language: String, settings: LanguageSettings) -> Error {
if error is CancellationError || error is SpeechModelUnresponsive { return error }
if let unavailable = error as? SpeechModelUnavailable, unavailable.fallback != nil {
return unavailable
}
return handOff(language, settings: settings)
}
}
/// How Hex gets a language's speech model onto the iPhone, shared by the app and in-keyboard
/// dictation: the module the picker chose, then the same language on `DictationTranscriber`
/// when `SpeechTranscriber`'s won't install (Apple lists some languages whose
/// `SpeechTranscriber` asset never arrives: "transcription.ar asset not found after attempted
/// download"). A download whose progress stops moving is given up on rather than awaited, and
/// Apple's status and language lookups are watched the same way, so a speech daemon that stops
/// answering fails instead of holding the screen.
/// When nothing installs while the iPhone is online, the language is set aside for Automatic
/// (`LanguageSettings.noteUnavailable`) and the error says so plainly.
nonisolated enum SpeechModelInstall {
enum Availability: Equatable, Sendable {
case installed
case downloadable
case unsupported
}
/// The Apple Speech calls, swapped out in tests.
struct Steps: Sendable {
/// The same language on `DictationTranscriber`, or nil when it doesn't have it.
var dictationEquivalent: @Sendable (Locale) async -> Locale?
var status: @Sendable (SpeechLanguage) async -> Availability
/// Downloads and installs, reporting a fraction in 0...1.
var download: @Sendable (SpeechLanguage, @escaping @Sendable (Double) -> Void) async throws -> Void
var isOnline: @Sendable () async -> Bool
}
/// How long a download may sit at the same fraction before Hex stops waiting on it.
static let stallLimit: Duration = .seconds(45)
/// Installs `language`'s model, or the same language's on `DictationTranscriber`, and
/// returns the language it installed. Throws `SpeechModelUnavailable` when neither does.
/// A failure sets a module or language aside only the second time in a row
/// (`LanguageSettings.noteSpeechModuleFailure`, `noteUnavailable`), and only where
/// `setsAside`: in-keyboard dictation passes false, as its failures are often the
/// keyboard's own (its reservation released or over Apple's limit, "Too many asset
/// locales allocated") and must not take a language away from Hex too.
static func run(
_ language: SpeechLanguage,
steps: Steps,
settings: LanguageSettings,
setsAside: Bool = true,
stallLimit: Duration = Self.stallLimit,
log: @Sendable (String) -> Void = { _ in },
progress: @escaping @Sendable (Double) -> Void = { _ in }
) async throws -> SpeechLanguage {
var attempts = [language]
if language.module == .speech {
// Apple's modules answer from the speech daemon, which can stop answering: no step
// may hold the preparation forever.
let equivalent = try await SpeechModelDeadline.run(stallLimit) {
await steps.dictationEquivalent(language.locale)
}
if let equivalent {
attempts.append(SpeechLanguage(locale: equivalent, module: .dictation))
}
}
var downloadable = false
var stalled = false
// A model in place ends the keyboard's handoff to Hex, whichever process installed it.
func installed(_ attempt: SpeechLanguage) -> SpeechLanguage {
settings.clearKeyboardNeedsHex()
settings.clearFailureStrikes(attempt.identifier, speechModule: attempt.module == .speech)
return attempt
}
for attempt in attempts {
try Task.checkCancellation()
let status = try await SpeechModelDeadline.run(stallLimit) {
await steps.status(attempt)
}
switch status {
case .installed:
return installed(attempt)
case .unsupported:
log("speech \(attempt.identifier) \(attempt.module.rawValue): unsupported")
continue
case .downloadable:
downloadable = true
}
do {
let fraction = ProgressReading()
try await StallWatch.run(limit: stallLimit, progress: { fraction.value }) {
try await steps.download(attempt) { value in
fraction.value = value
progress(value)
}
}
// The check after a download is Apple's too, and just as silent.
let afterDownload = try await SpeechModelDeadline.run(stallLimit) {
await steps.status(attempt)
}
if afterDownload == .installed {
return installed(attempt)
}
log("speech \(attempt.identifier) \(attempt.module.rawValue): not installed after download")
} catch is CancellationError {
throw CancellationError()
} catch let error as SpeechModelUnresponsive {
// A daemon that stopped answering won't answer the next module either.
throw error
} catch {
if error is StallWatch.Stalled { stalled = true }
log("speech \(attempt.identifier) \(attempt.module.rawValue): \(Self.describe(error))")
}
if attempt.module == .speech, attempts.count > 1, setsAside {
// Try DictationTranscriber next, and go straight to it for a while once this
// has failed twice in a row.
settings.noteSpeechModuleFailure(attempt.identifier)
}
}
if downloadable {
// A path monitor that never answers is a daemon problem, not an offline iPhone: it
// is rethrown as `SpeechModelUnresponsive`, so the keyboard counts no strike for
// it. The one monitor wait it leaves behind is bounded to one per timeout.
let online = try await SpeechModelDeadline.run(stallLimit) {
await steps.isOnline()
}
if stalled || !online {
throw SpeechModelUnavailable(language: language.identifier, reason: .downloadFailed)
}
}
if setsAside {
settings.noteUnavailable(language.identifier)
}
throw SpeechModelUnavailable(language: language.identifier, reason: .notOnThisIPhone)
}
/// Whether the iPhone has a usable network path right now.
static func isOnline() async -> Bool {
let monitor = NWPathMonitor()
defer { monitor.cancel() }
let status = await withCheckedContinuation { (continuation: CheckedContinuation<NWPath.Status, Never>) in
let once = OnceFlag()
monitor.pathUpdateHandler = { path in
if once.claim() { continuation.resume(returning: path.status) }
}
monitor.start(queue: DispatchQueue(label: "anomaly.hex.speech.path"))
}
return status == .satisfied
}
private static func describe(_ error: Error) -> String {
let ns = error as NSError
return "\(ns.domain) \(ns.code) \(ns.localizedDescription)"
}
}
/// Ends an operation whose progress stopped moving instead of waiting on it forever: after
/// `limit` at the same value it cancels the operation and throws `Stalled` without waiting
/// for it to notice. A nil reading pauses the watch (a step that reports nothing, such as
/// compiling a model, which can't be cancelled anyway). Time while iOS had the app suspended
/// doesn't count: a poll that comes back far later than asked restarts the wait.
nonisolated enum StallWatch {
struct Stalled: HexDescribedError {
var errorDescription: String? { String(localized: "The download stopped. Check your connection and try again.") }
}
/// How much later than asked a poll may come back before the wait counts as suspended.
static let suspensionGap: Duration = .seconds(5)
static func run<T: Sendable>(
limit: Duration,
poll: Duration = .milliseconds(250),
progress: @escaping @Sendable () -> Double?,
operation: @escaping @Sendable () async throws -> T
) async throws -> T {
let outcome = StallOutcome<T>()
return try await withTaskCancellationHandler {
try await withCheckedThrowingContinuation { continuation in
outcome.attach(continuation)
let work = Task {
do {
outcome.finish(.success(try await operation()))
} catch {
outcome.finish(.failure(error))
}
}
outcome.attach(work)
Task {
let clock = ContinuousClock()
var last = progress()
var since = clock.now
var polled = since
while !outcome.isFinished {
try? await Task.sleep(for: poll)
let tick = clock.now
let resumed = tick - polled > poll + suspensionGap
polled = tick
let now = progress()
if now == nil || now != last || resumed {
last = now
since = tick
} else if tick - since >= limit {
work.cancel()
outcome.finish(.failure(Stalled()))
return
}
}
}
}
} onCancel: {
outcome.cancel()
}
}
}
/// The first result `StallWatch` gets wins; later ones are dropped.
private nonisolated final class StallOutcome<T: Sendable>: @unchecked Sendable {
private let lock = NSLock()
private var continuation: CheckedContinuation<T, Error>?
private var pending: Result<T, Error>?
private var done = false
private var work: Task<Void, Never>?
var isFinished: Bool { lock.withLock { done } }
func attach(_ continuation: CheckedContinuation<T, Error>) {
let ready: Result<T, Error>? = lock.withLock {
if let pending {
self.pending = nil
return pending
}
self.continuation = continuation
return nil
}
if let ready { continuation.resume(with: ready) }
}
func attach(_ work: Task<Void, Never>) {
let finished = lock.withLock {
self.work = work
return done
}
if finished { work.cancel() }
}
func finish(_ result: Result<T, Error>) {
let target: CheckedContinuation<T, Error>? = lock.withLock {
guard !done else { return nil }
done = true
guard let continuation else {
pending = result
return nil
}
self.continuation = nil
return continuation
}
target?.resume(with: result)
}
func cancel() {
let running = lock.withLock { work }
running?.cancel()
finish(.failure(CancellationError()))
}
}
/// A progress fraction written by one task and read by another.
nonisolated final class ProgressReading: @unchecked Sendable {
private let lock = NSLock()
private var current: Double = 0
var value: Double {
get { lock.withLock { current } }
set { lock.withLock { current = newValue } }
}
}
private nonisolated final class OnceFlag: @unchecked Sendable {
private let lock = NSLock()
private var claimed = false
func claim() -> Bool {
lock.withLock {
guard !claimed else { return false }
claimed = true
return true
}
}
}