also looking at this
feat(ios): the speech pair closes the last deferral — ratchet 28 -> 26
#101
10 files
+1287
-573
| @@ -1,269 +1,201 @@ | ||
| 1 | //! The Speech + AVFoundation actions of the `mobile` namespace — | |
| 2 | //! `startListening` and `stopListening` — **researched in full and | |
| 3 | //! deliberately not served**. Both fall through to the working Swift shim. | |
| 1 | //! The `mobile` namespace's speech pair: `startListening` and `stopListening`. | |
| 4 | 2 | //! |
| 5 | //! This is the outcome rule 6 exists for, and it is the cheapest one in the | |
| 6 | //! migration: the shim answers both actions exactly as the app answers them | |
| 7 | //! today, and — unlike `scheduleNotification`, `registerBackgroundTask` and | |
| 8 | //! `sendToWatch` — **there is no promise to strand**, because neither action | |
| 9 | //! has a `callbackId` and neither ever replies. Falling through costs the page | |
| 10 | //! nothing at all. What is written below is the part a host can honestly | |
| 11 | //! finish and pin: the event vocabulary, the four error messages, and the two | |
| 12 | //! detail shapers. What is missing is named, not glossed. | |
| 3 | //! Neither action replies. Both are raw `postMessage` calls with no | |
| 4 | //! `callbackId` (`CraftApp.swift:1562-1568`), so nothing on the page is | |
| 5 | //! awaiting an answer and every outcome — success, refusal, transcript, end — | |
| 6 | //! travels as a `craftSpeech*` event. That is why both are declared | |
| 7 | //! `.reply = .none` below, and why no path in this file returns an error to | |
| 8 | //! `ios_dispatch`: an error there would call `sendErrorToJS` under a request | |
| 9 | //! id no page is holding, which is console noise standing in for the event a | |
| 10 | //! page is actually listening for. | |
| 13 | 11 | //! |
| 14 | //! ## The contract, read rather than assumed | |
| 12 | //! ## What this round changed | |
| 15 | 13 | //! |
| 16 | //! **Payload: none, on both actions.** The injected JS is the whole surface | |
| 17 | //! (`CraftApp.swift:1562-1568`): | |
| 14 | //! An earlier round researched both actions in full and deliberately left them | |
| 15 | //! with the Swift shim, listing four blockers and five preconditions. All five | |
| 16 | //! preconditions are met here, and the four blockers are answered: | |
| 18 | 17 | //! |
| 19 | //! ```js | |
| 20 | //! startListening: function() { | |
| 21 | //! window.webkit.messageHandlers.craft.postMessage({action: 'startListening'}); | |
| 22 | //! }, | |
| 23 | //! stopListening: function() { | |
| 24 | //! window.webkit.messageHandlers.craft.postMessage({action: 'stopListening'}); | |
| 25 | //! }, | |
| 26 | //! ``` | |
| 18 | //! 1. `ios_events.Event` can spell `craftSpeechStart` now — the arm was added | |
| 19 | //! alongside this module, and the vocabulary test covers it. | |
| 20 | //! 2. **The realtime tap.** `-[AVAudioNode installTapOnBus:…]` runs its block | |
| 21 | //! on the audio I/O thread, which no other module in this tree touches. | |
| 22 | //! Swift gets a free ARC retain for the duration of | |
| 23 | //! `recognitionRequest?.append(buffer)`; Zig gets nothing, so releasing | |
| 24 | //! the request while a tap call is in flight is a use-after-free on a | |
| 25 | //! realtime thread. The answer is below under "The audio thread", and it | |
| 26 | //! is an atomic handoff with a bounded drain — never a mutex, which on an | |
| 27 | //! audio thread is a priority inversion. | |
| 28 | //! 3. **The zero-format abort.** With no input route | |
| 29 | //! `-outputFormatForBus:0` yields a format whose `sampleRate` and | |
| 30 | //! `channelCount` are 0, and `installTapOnBus:` then raises an | |
| 31 | //! `NSException` the process cannot catch. Swift has the identical crash | |
| 32 | //! at `:2535-2538`. `formatCarriesInput` pre-checks and refuses. | |
| 33 | //! 4. **Testability.** The fixture drives both actions on a simulator and | |
| 34 | //! asserts the events, so the audio path is exercised rather than only the | |
| 35 | //! shapers. | |
| 27 | 36 | //! |
| 28 | //! No fields, no `callbackId`, no return value. `ios_dispatch.payloadOf` would | |
| 29 | //! hand a handler `"{}"`. There is no second page surface: the nested mobile | |
| 30 | //! contract block (`:2297-2427`) has no speech methods, and `craft-bridge.js` | |
| 31 | //! has no `mobile` namespace at all — its `window.craft.speech` is desktop TTS | |
| 32 | //! over `AVSpeechSynthesizer`, namespace `t = "speech"`, unrelated. So is | |
| 33 | //! `bridge_speech_recognition.zig`, which is the desktop `speechRecognition` | |
| 34 | //! namespace with actions `isAvailable`/`start`/`stop`; it must not be | |
| 35 | //! confused with this one. | |
| 37 | //! ## The event contract, which is the whole page-visible surface | |
| 36 | 38 | //! |
| 37 | //! **Reply: none, on any path.** The dispatcher (`CraftApp.swift:533-536`) is | |
| 38 | //! | |
| 39 | //! ```swift | |
| 40 | //! case "startListening": | |
| 41 | //! if config.enableSpeechRecognition { startSpeechRecognition() } | |
| 42 | //! case "stopListening": | |
| 43 | //! stopSpeechRecognition() | |
| 44 | //! ``` | |
| 45 | //! | |
| 46 | //! and neither `startSpeechRecognition` (`:2486-2494`), `beginRecording` | |
| 47 | //! (`:2496-2548`) nor `stopSpeechRecognition` (`:2550-2559`) touches | |
| 48 | //! `resolveCallback`, `rejectCallback` or `resolveCallbackJSON` on any line. | |
| 49 | //! `craft.d.ts:188` and `:193` both declare `(): void`, and | |
| 50 | //! `test-bridges.html:785-795` awaits nothing. If this module ever serves | |
| 51 | //! these, the declaration is `.reply = .none` — the same reading | |
| 52 | //! `bridge_mobile_haptics.zig` made for `haptic`, and for the same reason. | |
| 53 | //! | |
| 54 | //! A denial does not reply either; it **emits**. Nor does the flag-off case | |
| 55 | //! emit anything at all: `if config.enableSpeechRecognition { … }` has no | |
| 56 | //! `else`, and `stopListening` is ungated and always runs. | |
| 57 | //! | |
| 58 | //! **Everything is events.** Four names, and the detail of each: | |
| 59 | //! | |
| 60 | //! | event | detail | when | | |
| 39 | //! | event | when Swift sends it | when this module does | | |
| 61 | 40 | //! |---|---|---| |
| 62 | //! | `craftSpeechError` | `{"error":"Not authorized"}` | auth status is not `.authorized` (`:2489`) | | |
| 63 | //! | `craftSpeechError` | `{"error":"Audio session failed"}` | `setCategory`/`setActive` threw (`:2507`) | | |
| 64 | //! | `craftSpeechError` | `{"error":"Speech recognizer unavailable"}` | request nil, recognizer nil, or not `isAvailable` (`:2515`) | | |
| 65 | //! | `craftSpeechError` | `{"error":"Audio engine failed"}` | `audioEngine.start()` threw (`:2546`) | | |
| 66 | //! | `craftSpeechStart` | `{}` | after `audioEngine.start()` succeeded (`:2543`) | | |
| 67 | //! | `craftSpeechResult` | `{"transcript": String, "isFinal": Bool}` | every partial and every final result (`:2525-2528`) | | |
| 68 | //! | `craftSpeechEnd` | `{}` | every `stopSpeechRecognition()` (`:2557`) | | |
| 69 | //! | |
| 70 | //! The result detail is **exactly two keys**. No `confidence`, no | |
| 71 | //! `alternatives`, no `segments`. Three independent consumers agree — | |
| 72 | //! `test-bridges.html:384-387` reads `e.detail.transcript` and | |
| 73 | //! `e.detail.isFinal`, `packages/ios/README.md:167-176` documents the same | |
| 74 | //! pair, and Android emits the same four names with the same keys | |
| 75 | //! (`CraftBridge.kt.template:1344-1383`). Unlike motion, there is no | |
| 76 | //! doc/implementation mismatch here to report. | |
| 77 | //! | |
| 78 | //! `sendToWeb` (`:4835-4846`) builds | |
| 79 | //! `window.dispatchEvent(new CustomEvent('<name>', {detail: <json>}));` — the | |
| 80 | //! same form `ios_events.formatEvent` builds, so the detail bytes below are | |
| 81 | //! the bytes that reach `e.detail` on either path. | |
| 82 | //! | |
| 83 | //! ## Why nothing is served | |
| 84 | //! | |
| 85 | //! Four blockers. Only the last three are load-bearing; the first is one line | |
| 86 | //! of data that would unblock nothing on its own. | |
| 41 | //! | `craftSpeechStart` | the engine started | the engine started | | |
| 42 | //! | `craftSpeechResult` | every partial and final transcript | the same | | |
| 43 | //! | `craftSpeechError` | four named failures | the same four | | |
| 44 | //! | `craftSpeechEnd` | every `stopSpeechRecognition()` | every `stopListening`, and every internal stop | | |
| 87 | 45 | //! |
| 88 | //! **1. `craftSpeechStart` cannot be spelled.** `ios_events.Event` carries | |
| 89 | //! `.speech_result`, `.speech_error` and `.speech_end`, and no | |
| 90 | //! `.speech_start`. Serving `startListening` without it would drop the one | |
| 91 | //! event that drives the page's state — `test-bridges.html:380-383` paints | |
| 92 | //! "Listening..." from it and from nothing else — so a working session would | |
| 93 | //! look to the page exactly like a session that never started. Adding the | |
| 94 | //! enum member and its `switch` arm is data rather than mechanism, and the | |
| 95 | //! existing test `"every event name is one an iOS page actually subscribes | |
| 96 | //! to"` already accepts the shape (`startsWith "craft"`, no colon). It is not | |
| 97 | //! left undone because a second file is off limits — landing this module | |
| 98 | //! already edits `ios_dispatch.zig`, `build.zig` and | |
| 99 | //! `test/ios_conformance_test.zig`. It is left undone because adding it alone | |
| 100 | //! serves nothing: blocker 2 stops `startListening` by itself, and an `Event` | |
| 101 | //! member no code emits is vocabulary for an event that never fires. So it is | |
| 102 | //! precondition 1 below rather than a reason of its own — and a test trips | |
| 103 | //! when it lands. | |
| 46 | //! `craftSpeechEnd` fires on a `stopListening` that stops nothing. Swift's | |
| 47 | //! `stopSpeechRecognition()` has no early return — it is called from | |
| 48 | //! `case "stopListening"` unconditionally, with no gate and no guard — so a | |
| 49 | //! page that stops twice gets two ends, and one that never started still gets | |
| 50 | //! one. That is bug-compatibility on purpose: the event is what a page's UI | |
| 51 | //! binds its "listening" indicator to, and an end that does not arrive leaves | |
| 52 | //! the indicator stuck on. | |
| 104 | 53 | //! |
| 105 | //! **2. The realtime tap has no precedent in this tree.** | |
| 106 | //! `-[AVAudioNode installTapOnBus:bufferSize:format:block:]` runs its block on | |
| 107 | //! the audio I/O thread, which is not a queue any existing module touches. | |
| 108 | //! `bridge_mobile_motion.zig`'s handler is an `NSOperationQueue.mainQueue` | |
| 109 | //! callback and is **not** a precedent for it. Swift's | |
| 110 | //! `self?.recognitionRequest?.append(buffer)` gets a free ARC retain for the | |
| 111 | //! duration of the call; Zig has none, so `stopListening` releasing the | |
| 112 | //! request while a tap call is in flight is a use-after-free on a realtime | |
| 113 | //! thread. It is solvable — an atomic pointer, never a mutex (priority | |
| 114 | //! inversion), plus stop-engine, remove-tap, clear-pointer, never-release | |
| 115 | //! ordering — but solving it is building a new foundation, and this round was | |
| 116 | //! asked to apply proven ones and to say so instead. | |
| 54 | //! ## Deliberate divergences, each with its reason | |
| 117 | 55 | //! |
| 118 | //! **3. The guard the tap needs is asserted, not read.** With no active input | |
| 119 | //! route, `-outputFormatForBus:0` yields a format whose `sampleRate` and | |
| 120 | //! `channelCount` are 0, and `installTapOnBus:` then raises an | |
| 121 | //! `NSException` — which Zig cannot catch, so the process aborts. Swift has | |
| 122 | //! the identical crash at `:2535-2538`. The honest port pre-checks the format | |
| 123 | //! and refuses with `craftSpeechError`; but that behaviour comes from API | |
| 124 | //! knowledge, nothing in this repo documents it, and there is no simulator | |
| 125 | //! here to verify it. Shipping an unverified guard against an unreproducible | |
| 126 | //! abort is the one place rule 5 and rule 1 meet. | |
| 127 | //! | |
| 128 | //! **4. Nothing here can test the audio path.** Every host test that could be | |
| 129 | //! written for a served version would exercise selector interning and block | |
| 130 | //! flags, and nothing of the recognizer, the session, the engine or the tap. | |
| 131 | //! That is a served action whose entire risk surface is untested. | |
| 132 | //! | |
| 133 | //! The gate is *not* among the blockers, because it is solved: | |
| 134 | //! `config.enableSpeechRecognition` defaults to `false` | |
| 135 | //! (`CraftApp.swift:189`, `packages/ios/src/index.ts:117`) and reaches Zig | |
| 136 | //! through nothing, but `packages/ios/src/index.ts:183` writes | |
| 56 | //! **The plist guard replaces the nil-recognizer guard.** Swift builds its | |
| 57 | //! `SFSpeechRecognizer` only when `config.enableSpeechRecognition` is on | |
| 58 | //! (`:439-440`), and `beginRecording`'s `guard let speechRecognizer` then | |
| 59 | //! emits `"Speech recognizer unavailable"` when it is off. Zig cannot see the | |
| 60 | //! ivar, but `packages/ios/src/index.ts:183` writes | |
| 137 | 61 | //! `NSSpeechRecognitionUsageDescription` from that flag **and nothing else, |
| 138 | 62 | //! with no `||`** — the exact-proxy shape `bridge_mobile_motion.zig` already |
| 139 | //! reads. (`NSMicrophoneUsageDescription` at `:184` is | |
| 140 | //! `enableSpeechRecognition || enableAudioRecording` and is **not** an exact | |
| 141 | //! proxy; it must not be used as the gate.) Here the proxy is mandatory | |
| 142 | //! rather than an improvement: without those keys in Info.plist iOS | |
| 143 | //! *terminates the process* on the authorization request or on mic access. | |
| 63 | //! reads. So a missing key means the flag was off, and the message emitted is | |
| 64 | //! the one Swift would have emitted for the same configuration. | |
| 65 | //! | |
| 66 | //! The check has to run *before* `requestAuthorization:`, where Swift's runs | |
| 67 | //! after, because asking for speech authorization without the key does not | |
| 68 | //! fail — iOS terminates the process. Order diverges; the page-visible | |
| 69 | //! message does not. | |
| 144 | 70 | //! |
| 145 | //! ## Why falling through, and not `.unavailable` | |
| 71 | //! (`NSMicrophoneUsageDescription` at `index.ts:184` is | |
| 72 | //! `enableSpeechRecognition || enableAudioRecording` and is therefore **not** | |
| 73 | //! an exact proxy, so it is not the gate. It is implied by the speech key | |
| 74 | //! rather than checked: speech on always writes both.) | |
| 146 | 75 | //! |
| 147 | //! `.unavailable` makes `ios_dispatch` route the action into this module and | |
| 148 | //! refuse it. For an action with a pending promise that is a nameable failure | |
| 149 | //! and an improvement on silence. Here there is no pending promise on any | |
| 150 | //! page surface, so the refusal would surface only as a console log — while | |
| 151 | //! taking away a shim path that works completely. That is strictly worse, and | |
| 152 | //! it is why `A` below is empty rather than carrying two `.unavailable` rows. | |
| 76 | //! **A zero input format is refused as `"Audio engine failed"`.** There is no | |
| 77 | //! Swift string for it because Swift does not survive the case, and inventing | |
| 78 | //! a fifth message would put bytes on a page's screen that no other arm of the | |
| 79 | //! bridge can produce. `startAndReturnError:` failing for the same underlying | |
| 80 | //! reason — no usable input — is what Swift reports as `"Audio engine | |
| 81 | //! failed"`, so the existing message is the honest one. | |
| 153 | 82 | //! |
| 154 | //! Serving only `stopListening` is worse still, and is ruled out for the | |
| 155 | //! reason `bridge_mobile_motion.zig` gives: a session started through the shim | |
| 156 | //! would meet a Zig stop, which would stop Zig's own null engine and emit | |
| 157 | //! `craftSpeechEnd` while Swift's recognizer kept pushing `craftSpeechResult`. | |
| 158 | //! Fabricated success at the event layer. Either both or neither; neither. | |
| 83 | //! **A second `startListening` while running stops first.** Swift's | |
| 84 | //! `beginRecording` cancels the task and nothing else (`:2497-2500`), then | |
| 85 | //! installs a second tap on bus 0, which raises. Reproducing that is not | |
| 86 | //! required of a port; `bridge_mobile_motion.zig` made the same call. The | |
| 87 | //! internal stop emits **no** `craftSpeechEnd`, because Swift's restart emits | |
| 88 | //! none either — only a real stop does. | |
| 159 | 89 | //! |
| 160 | //! ## What is finished here | |
| 90 | //! **`stopListening` does not touch the engine when nothing is running.** | |
| 91 | //! Swift's stop reads `audioEngine.inputNode` unconditionally, and that | |
| 92 | //! property *creates* the input node on demand; on a device with no input | |
| 93 | //! route available it can raise rather than return. Since a stop that stopped | |
| 94 | //! nothing has nothing to remove, the engine is touched only when this module | |
| 95 | //! knows a tap is installed. The `craftSpeechEnd` still fires, so the page | |
| 96 | //! sees no difference. | |
| 161 | 97 | //! |
| 162 | //! The two shapers and the four messages — the half of the port that decides | |
| 163 | //! page-visible bytes and that a host can pin. This is the precedent | |
| 164 | //! `bridge_mobile_haptics.zig` set with `triggerHapticChecked`: the finished | |
| 165 | //! half of a blocked action lives next to the admission, tested, so that | |
| 166 | //! unblocking it is a small deliberate edit rather than a rewrite. | |
| 98 | //! **Trailing buffers are not dropped.** The handoff clears the published | |
| 99 | //! request only after `removeTapOnBus:` has returned, so every buffer the tap | |
| 100 | //! delivered before removal reaches the recognizer — the same audio Swift | |
| 101 | //! would have appended. | |
| 167 | 102 | //! |
| 168 | //! `shapeResultDetail` is worth more than it looks. A transcript is arbitrary | |
| 169 | //! spoken text, the detail is inlined into JavaScript source as a literal, and | |
| 170 | //! `ios_events.zig`'s own module comment records what happens when a value | |
| 171 | //! like that is concatenated with hand-rolled escaping: `bridge_iap.zig:362` | |
| 172 | //! "works until a value contains a quote". Swift is safe here only because | |
| 173 | //! `JSONSerialization` escapes for it. Any Zig port must, and this one does. | |
| 103 | //! **On a recognition error, no `craftSpeechError` is emitted.** Swift | |
| 104 | //! discards the `NSError` entirely (`:2530-2532` calls only | |
| 105 | //! `stopSpeechRecognition()`), so the page sees `craftSpeechEnd` and nothing | |
| 106 | //! else. Android *does* emit one (`CraftBridge.kt.template:1367`). The | |
| 107 | //! divergence is left unfixed here on purpose: there is no Swift string to | |
| 108 | //! copy, and inventing one prejudges a contract question that belongs to the | |
| 109 | //! JS surface, not to a port. `error_messages` below is still exactly four. | |
| 174 | 110 | //! |
| 175 | //! ## What a future round still owes | |
| 111 | //! **Both haptics fire ungated.** `:2544` and `:2558` call | |
| 112 | //! `triggerHaptic("light")` directly, bypassing the `config.enableHaptics` | |
| 113 | //! check the dispatcher applies to `case "haptic"` at `:537`. Swift ignores | |
| 114 | //! the flag on this path, so firing it here is faithful rather than a | |
| 115 | //! divergence — and it is why `bridge_mobile_haptics.triggerHapticChecked` | |
| 116 | //! became `pub` in the same change. | |
| 176 | 117 | //! |
| 177 | //! Five preconditions, all five, before either action moves into `A`: | |
| 118 | //! ## The audio thread | |
| 178 | 119 | //! |
| 179 | //! 1. `.speech_start => "craftSpeechStart"` in `ios_events.Event`. | |
| 180 | //! 2. Refuse unless Info.plist carries `NSSpeechRecognitionUsageDescription` | |
| 181 | //! (`bridge_mobile_motion.zig:infoPlistHas` is the shape). | |
| 182 | //! 3. Validate `-sampleRate` and `-channelCount` before `installTapOnBus:`, | |
| 183 | //! and emit `craftSpeechError` rather than installing on a zero format. | |
| 184 | //! 4. Never release the recognition request while a tap call may be in | |
| 185 | //! flight — atomically clear the pointer after `removeTapOnBus:`, and | |
| 186 | //! prefer leaking one request per session over racing the audio thread. | |
| 187 | //! 5. Hop to the main queue with `dispatch_async_f(&_dispatch_main_q, …)` | |
| 188 | //! before touching `AVAudioEngine` from the recognition task handler; it | |
| 189 | //! fires on an internal Speech queue. (`ios_events.emit` needs no hop — | |
| 190 | //! it hops itself.) | |
| 120 | //! One rule: **the tap block touches exactly two atomics and one selector, | |
| 121 | //! all of them resolved before the tap was installed.** No allocation, no | |
| 122 | //! `sel_registerName`, no logging, no lock. | |
| 191 | 123 | //! |
| 192 | //! And two decisions that are decisions, not facts, to be taken out loud: | |
| 124 | //! The handoff is a published pointer plus an in-flight counter: | |
| 193 | 125 | //! |
| 194 | //! - **The error-emission divergence.** On a recognition error Swift emits | |
| 195 | //! **no** `craftSpeechError` — `:2530-2532` only calls | |
| 196 | //! `stopSpeechRecognition()`, so the page gets `craftSpeechEnd` and the | |
| 197 | //! `NSError` is discarded entirely. Android *does* emit one | |
| 198 | //! (`CraftBridge.kt.template:1367`). Matching Swift makes a simulator | |
| 199 | //! failure look exactly like a stream that never fires; matching Android | |
| 200 | //! tells the truth but deviates from the emitter contract this migration | |
| 201 | //! preserves. `err_recognition_failed` below is deliberately absent: there | |
| 202 | //! is no Swift string to copy, so inventing one here would prejudge it. | |
| 203 | //! - **`beginRecording` never stops the engine or removes the old tap** | |
| 204 | //! (`:2497-2500` cancels only the task). A second `startListening` while | |
| 205 | //! running installs a second tap on bus 0, which raises on iOS. | |
| 206 | //! Reproducing that bug is not required; stopping first, as | |
| 207 | //! `bridge_mobile_motion.zig` chose to, is the defensible port. | |
| 126 | //! - `active_request` holds the `SFSpeechAudioBufferRecognitionRequest` as a | |
| 127 | //! `usize`. Zero means "nobody may append". | |
| 128 | //! - `tap_in_flight` is incremented by the tap before it loads the pointer | |
| 129 | //! and decremented after the append returns. | |
| 130 | //! - Teardown stops the engine, removes the tap, clears `active_request`, | |
| 131 | //! then spins until `tap_in_flight` reads zero before releasing. | |
| 208 | 132 | //! |
| 209 | //! Also worth carrying: both `:2544` and `:2558` fire `triggerHaptic("light")` | |
| 210 | //! directly, bypassing the `config.enableHaptics` gate the dispatcher applies | |
| 211 | //! to `case "haptic"` at `:537`. Swift itself ignores the flag on this path, | |
| 212 | //! so firing it from a served port would be faithful rather than a | |
| 213 | //! divergence — but `triggerHapticChecked` in `bridge_mobile_haptics.zig` is | |
| 214 | //! not `pub`, so reuse needs a visibility change there. | |
| 133 | //! Every one of those four operations is `.seq_cst`, and that is not | |
| 134 | //! decoration. The dangerous interleaving is Dekker's: the tap increments then | |
| 135 | //! loads the pointer while teardown clears the pointer then loads the counter. | |
| 136 | //! Acquire/release ordering permits both sides to see the other's *old* value, | |
| 137 | //! which is exactly "teardown believes no tap is running while a tap holds a | |
| 138 | //! pointer it is about to release". Sequential consistency is what rules that | |
| 139 | //! out, and one `xchg` per audio buffer — roughly 86 a second at 1024 frames | |
| 140 | //! and 44.1kHz — is not a cost worth reasoning around. | |
| 215 | 141 | //! |
| 216 | //! ## Nothing in this file touches Objective-C | |
| 142 | //! The spin is bounded (`drain_spins` × 100µs = 20ms, against a tap call | |
| 143 | //! measured in microseconds) and runs on the main thread only while a stop is | |
| 144 | //! in progress. If it ever fails to drain, the request is **leaked rather | |
| 145 | //! than released** and the fact is logged. That is the trade the earlier round | |
| 146 | //! asked for in as many words: prefer leaking one request per session over | |
| 147 | //! racing the audio thread. | |
| 217 | 148 | //! |
| 218 | //! No `objc_getClass`, no `sel_registerName`, no block, no delegate, no | |
| 219 | //! `ios_async` ticket — there is no reply to correlate and no framework call | |
| 220 | //! to make. So there is nothing to Darwin-gate: the module compiles and its | |
| 221 | //! tests run identically on Linux and macOS, which is the one upside of | |
| 222 | //! serving nothing. | |
| 149 | //! ## Queues, and the hop each one needs | |
| 150 | //! | |
| 151 | //! - `handleMessage` runs on the main thread — it is reached from | |
| 152 | //! `-userContentController:didReceiveScriptMessage:`. | |
| 153 | //! - `+[SFSpeechRecognizer requestAuthorization:]` answers on an arbitrary | |
| 154 | //! queue, so its block hops to the main queue before anything touches | |
| 155 | //! `AVAudioSession` or `AVAudioEngine`. `bridge_mobile_audiorec.zig` makes | |
| 156 | //! the identical hop for the identical reason. | |
| 157 | //! - The recognition result handler fires on an internal Speech queue. It | |
| 158 | //! may emit (`ios_events.emit` hops itself) but must hop before tearing | |
| 159 | //! the engine down, which is precondition 5. | |
| 160 | //! - The tap block runs on the audio I/O thread. See above. | |
| 223 | 161 | |
| 224 | 162 | const std = @import("std"); |
| 163 | const builtin = @import("builtin"); | |
| 225 | 164 | const capabilities = @import("capabilities.zig"); |
| 226 | 165 | const bridge_error = @import("bridge_error.zig"); |
| 227 | 166 | const ios_events = @import("ios_events.zig"); |
| 167 | const objc_runtime = @import("objc_runtime.zig"); | |
| 168 | const haptics = @import("bridge_mobile_haptics.zig"); | |
| 169 | ||
| 170 | const objc = objc_runtime.objc; | |
| 171 | const BridgeError = bridge_error.BridgeError; | |
| 172 | const Id = ?*anyopaque; | |
| 173 | const is_darwin = builtin.target.os.tag.isDarwin(); | |
| 228 | 174 | |
| 229 | /// **Empty on purpose.** No action name here means `ios_dispatch` never routes | |
| 230 | /// `startListening` or `stopListening` into this module, so both reach the | |
| 231 | /// Swift shim that serves them correctly today. See the module comment for the | |
| 232 | /// four blockers and the five preconditions. | |
| 233 | /// | |
| 234 | /// `declared_count` is not decoration. `test/ios_conformance_test.zig` scans | |
| 235 | /// this block line by line from `pub const A = struct {` to the first bare | |
| 236 | /// `};`, and `zig fmt` collapses an empty struct onto one line — after which | |
| 237 | /// the scan would never find its terminator and would collect every quoted | |
| 238 | /// string in this file as an action name. A non-string member keeps the block | |
| 239 | /// two-line-safe under `zig fmt --check`, which CI runs. | |
| 240 | 175 | pub const A = struct { |
| 241 | /// How many actions this module claims. Zero, deliberately. | |
| 242 | pub const declared_count: usize = 0; | |
| 176 | pub const start_listening = "startListening"; | |
| 177 | pub const stop_listening = "stopListening"; | |
| 243 | 178 | }; |
| 244 | 179 | |
| 245 | /// Empty, and specifically not two `.unavailable` rows. | |
| 180 | /// `.none` for both, and the distinction matters. | |
| 246 | 181 | /// |
| 247 | /// `.unavailable` is for an action that dispatches and refuses — honest when a | |
| 248 | /// promise would otherwise hang, wrong here. Neither of these actions has a | |
| 249 | /// promise on any page surface, so a refusal would show up only in the | |
| 250 | /// console while removing a shim path that works end to end. Declaring | |
| 251 | /// nothing is what lets the shim keep answering. | |
| 252 | pub const capability_actions = [_]capabilities.ActionDecl{}; | |
| 253 | ||
| 254 | /// The two spec actions this module researched and left with the shim. | |
| 182 | /// `.result` would tell an app to await a reply that never comes: neither | |
| 183 | /// action calls `sendResultToJS` on any path, because neither has a page-side | |
| 184 | /// promise to settle. Everything observable leaves through `ios_events`. | |
| 255 | 185 | /// |
| 256 | /// Kept as data so the tests can prove both fall through rather than asserting | |
| 257 | /// it in prose, and so a future round has the exact spellings in one place. | |
| 258 | /// These names deliberately live outside the `A` block: inside it, the | |
| 259 | /// conformance scan would read them as served and the ratchet would drop for | |
| 260 | /// actions nothing here answers. | |
| 261 | pub const unserved_actions = [_][]const u8{ "startListening", "stopListening" }; | |
| 186 | /// `.live` for both. A refusal here is a specific condition — speech not | |
| 187 | /// configured, authorization declined, no input route — and never the normal | |
| 188 | /// answer, which is what `.unavailable` would claim. | |
| 189 | pub const capability_actions = [_]capabilities.ActionDecl{ | |
| 190 | .{ .name = A.start_listening, .reply = .none }, | |
| 191 | .{ .name = A.stop_listening, .reply = .none }, | |
| 192 | }; | |
| 262 | 193 | |
| 263 | 194 | pub const SpeechBridge = struct { |
| 264 | /// Held but never used: `ios_dispatch` constructs every mobile bridge with | |
| 265 | /// `init(allocator)` and the shape is the interface. Nothing here | |
| 266 | /// allocates, because nothing here answers. | |
| 195 | /// Held for the interface `ios_dispatch` builds every mobile bridge with. | |
| 196 | /// Unused: nothing in a dispatch allocates, and the two paths that do — | |
| 197 | /// shaping a transcript and shaping an error — run from callbacks where | |
| 198 | /// this bridge is long gone, so they take the C allocator instead. | |
| 267 | 199 | allocator: std.mem.Allocator, |
| 268 | 200 | |
| 269 | 201 | const Self = @This(); |
| @@ -274,42 +206,39 @@ pub const SpeechBridge = struct { | ||
| 274 | 206 | |
| 275 | 207 | pub fn deinit(_: *Self) void {} |
| 276 | 208 | |
| 277 | /// Always `UnknownAction` — "not mine, ask the next" — which is what makes | |
| 278 | /// the fall-through work. | |
| 279 | /// | |
| 280 | /// The payload is deliberately never parsed. `ios_dispatch.route` treats | |
| 281 | /// any error other than `UnknownAction` as final and stops the chain, so a | |
| 282 | /// module that parsed first and answered `InvalidJSON` on a malformed | |
| 283 | /// payload would strand an action it does not even serve. That is the | |
| 284 | /// failure this signature is shaped to make impossible, and a test below | |
| 285 | /// pins it with payloads that no parser would accept. | |
| 209 | /// The payload is ignored, deliberately: Swift reads no field from either | |
| 210 | /// action, and the injected JS posts neither a body nor a `callbackId`. | |
| 211 | /// Parsing it would only create a way to fail that the spec has not got. | |
| 286 | 212 | pub fn handleMessage(_: *Self, action: []const u8, _: []const u8) !void { |
| 287 | _ = action; | |
| 288 | return bridge_error.BridgeError.UnknownAction; | |
| 213 | if (std.mem.eql(u8, action, A.start_listening)) { | |
| 214 | startListening(); | |
| 215 | return; | |
| 216 | } | |
| 217 | if (std.mem.eql(u8, action, A.stop_listening)) { | |
| 218 | stopListening(); | |
| 219 | return; | |
| 220 | } | |
| 221 | return BridgeError.UnknownAction; | |
| 289 | 222 | } |
| 290 | 223 | }; |
| 291 | 224 | |
| 292 | 225 | // ============================================================================= |
| 293 | // The event vocabulary, as far as it can be spelled today. | |
| 226 | // The event vocabulary. | |
| 294 | 227 | // ============================================================================= |
| 295 | 228 | |
| 229 | /// `craftSpeechStart` — the engine is running and audio is reaching the | |
| 230 | /// recognizer. | |
| 231 | pub const event_start: ios_events.Event = .speech_start; | |
| 232 | ||
| 296 | 233 | /// `craftSpeechResult` — the transcript stream. |
| 297 | 234 | pub const event_result: ios_events.Event = .speech_result; |
| 298 | 235 | |
| 299 | 236 | /// `craftSpeechError` — every refusal, on every path. |
| 300 | 237 | pub const event_error: ios_events.Event = .speech_error; |
| 301 | 238 | |
| 302 | /// `craftSpeechEnd` — every `stopSpeechRecognition()`, including one that | |
| 303 | /// stops nothing. | |
| 239 | /// `craftSpeechEnd` — every stop, including one that stops nothing. | |
| 304 | 240 | pub const event_end: ios_events.Event = .speech_end; |
| 305 | 241 | |
| 306 | /// `craftSpeechStart`, which `ios_events.Event` cannot currently spell. | |
| 307 | /// | |
| 308 | /// A plain string, not an `Event`, because that is the whole point: there is | |
| 309 | /// no member to name. Pinned here so the eventual enum arm is copied from the | |
| 310 | /// contract rather than retyped from memory. | |
| 311 | pub const event_start_name = "craftSpeechStart"; | |
| 312 | ||
| 313 | 242 | /// The `data: [:]` of `craftSpeechStart` and `craftSpeechEnd` — an empty |
| 314 | 243 | /// object, not an empty string and not `null`. `ios_events.formatEvent` |
| 315 | 244 | /// inlines the detail as a literal, so `e.detail` must still be an object the |
| @@ -339,12 +268,13 @@ pub const err_audio_session = "Audio session failed"; | ||
| 339 | 268 | /// NO. A simulator commonly answers NO here. |
| 340 | 269 | pub const err_recognizer_unavailable = "Speech recognizer unavailable"; |
| 341 | 270 | |
| 342 | /// `:2546` — `-startAndReturnError:` returned NO. | |
| 271 | /// `:2546` — `-startAndReturnError:` returned NO. Also the zero-format | |
| 272 | /// refusal, which Swift does not survive to report; see the module comment. | |
| 343 | 273 | pub const err_audio_engine = "Audio engine failed"; |
| 344 | 274 | |
| 345 | /// Every message the port may emit, in Swift's source order. A future round | |
| 346 | /// adding a fifth must add it to Swift's contract first, or document the | |
| 347 | /// divergence — see the module comment on the recognition-error case. | |
| 275 | /// Every message this module may emit, in Swift's source order. Still four: | |
| 276 | /// the recognition-error divergence is documented rather than papered over | |
| 277 | /// with a fifth string Swift has never sent. | |
| 348 | 278 | pub const error_messages = [_][]const u8{ |
| 349 | 279 | err_not_authorized, |
| 350 | 280 | err_audio_session, |
| @@ -352,6 +282,25 @@ pub const error_messages = [_][]const u8{ | ||
| 352 | 282 | err_audio_engine, |
| 353 | 283 | }; |
| 354 | 284 | |
| 285 | /// Why a start failed, in the vocabulary the page reads. | |
| 286 | /// | |
| 287 | /// An error set rather than a returned string, so a path that forgets to | |
| 288 | /// report is a compile error rather than an empty message, and so | |
| 289 | /// `messageFor` is the single place the mapping lives. | |
| 290 | const StartFailure = error{ | |
| 291 | AudioSession, | |
| 292 | RecognizerUnavailable, | |
| 293 | AudioEngine, | |
| 294 | }; | |
| 295 | ||
| 296 | fn messageFor(err: StartFailure) []const u8 { | |
| 297 | return switch (err) { | |
| 298 | error.AudioSession => err_audio_session, | |
| 299 | error.RecognizerUnavailable => err_recognizer_unavailable, | |
| 300 | error.AudioEngine => err_audio_engine, | |
| 301 | }; | |
| 302 | } | |
| 303 | ||
| 355 | 304 | // ============================================================================= |
| 356 | 305 | // The detail shapers. Pure, and the bytes are the contract. |
| 357 | 306 | // ============================================================================= |
| @@ -418,393 +367,1046 @@ pub fn shapeResultDetail( | ||
| 418 | 367 | return out.toOwnedSlice(allocator); |
| 419 | 368 | } |
| 420 | 369 | |
| 370 | /// Emit one `craftSpeechError`, or drop it and say so. | |
| 371 | /// | |
| 372 | /// Every failure path in this file ends here, so this is the one place that | |
| 373 | /// decides what a page sees when even the reporting fails. Dropping is the | |
| 374 | /// only option — there is no promise to reject and no second channel — and | |
| 375 | /// the log line is what a developer has left. | |
| 376 | fn emitError(message: []const u8) void { | |
| 377 | const allocator = std.heap.c_allocator; | |
| 378 | const detail = shapeErrorDetail(allocator, message) catch { | |
| 379 | std.log.warn("speech: could not shape '{s}' for craftSpeechError", .{message}); | |
| 380 | return; | |
| 381 | }; | |
| 382 | defer allocator.free(detail); | |
| 383 | ios_events.emit(event_error, detail); | |
| 384 | } | |
| 385 | ||
| 421 | 386 | // ============================================================================= |
| 422 | // Tests. | |
| 387 | // Native constants, each read from the SDK header rather than recalled. | |
| 388 | // ============================================================================= | |
| 389 | ||
| 390 | /// `SFSpeechRecognizerAuthorizationStatusAuthorized`. | |
| 391 | /// | |
| 392 | /// `SFSpeechRecognizer.h:25-41` numbers the enum implicitly from zero: | |
| 393 | /// NotDetermined 0, Denied 1, Restricted 2, Authorized 3. Only 3 proceeds — | |
| 394 | /// Swift's `guard status == .authorized` treats the other three identically, | |
| 395 | /// including NotDetermined, which is what a user dismissing the prompt leaves | |
| 396 | /// behind. | |
| 397 | const status_authorized: isize = 3; | |
| 398 | ||
| 399 | /// `AVAudioSessionCategoryOptionDuckOthers` — `AVAudioSessionTypes.h:466`, | |
| 400 | /// `0x2`. Swift passes `options: .duckOthers`. | |
| 401 | const category_option_duck_others: c_ulong = 0x2; | |
| 402 | ||
| 403 | /// `AVAudioSessionSetActiveOptionNotifyOthersOnDeactivation` — | |
| 404 | /// `AVAudioSessionTypes.h:660`, `1`. Swift passes it on activation, where the | |
| 405 | /// header says it is only meaningful on deactivation; carried across anyway, | |
| 406 | /// because it is inert rather than wrong and matching the shim costs nothing. | |
| 407 | const set_active_notify_others: c_ulong = 1; | |
| 408 | ||
| 409 | /// The bus every call here uses. Swift hardcodes 0 in all four places. | |
| 410 | const bus_zero: c_ulong = 0; | |
| 411 | ||
| 412 | /// Swift's `bufferSize: 1024` (`:2536`). `AVAudioFrameCount` is `uint32_t` | |
| 413 | /// (`AVAudioTypes.h:22`). | |
| 414 | const tap_buffer_frames: u32 = 1024; | |
| 415 | ||
| 416 | /// The locale Swift builds its recognizer with (`:440`). | |
| 417 | const recognizer_locale = "en-US"; | |
| 418 | ||
| 419 | /// The Info.plist key that stands in for `config.enableSpeechRecognition`. | |
| 420 | const key_speech_usage = "NSSpeechRecognitionUsageDescription"; | |
| 421 | ||
| 422 | /// How many spins teardown will wait for the audio thread before giving up and | |
| 423 | /// leaking the request. 200 × 100µs is 20ms, against a tap call measured in | |
| 424 | /// microseconds — long enough that reaching the end means something is wrong, | |
| 425 | /// short enough that a page's stop still feels instant. | |
| 426 | const drain_spins: usize = 200; | |
| 427 | const drain_spin_micros: c_uint = 100; | |
| 428 | ||
| 429 | // ============================================================================= | |
| 430 | // State. | |
| 423 | 431 | // |
| 424 | // Two things are under test. First, that this module really does serve | |
| 425 | // nothing — declaring nothing is only half of it, since a module that | |
| 426 | // answered anything other than `UnknownAction` would break the fall-through | |
| 427 | // even with an empty table. Second, the finished half: the event names and the | |
| 428 | // two detail shapers, whose bytes are what a page reads. | |
| 432 | // Module-level, because `ios_dispatch` builds a fresh `SpeechBridge` per | |
| 433 | // dispatch and drops it again: anything held on the bridge would be released | |
| 434 | // the instant `startListening` returned, and the session with it. Swift's are | |
| 435 | // ivars on a coordinator that outlives every call, for the same reason. | |
| 429 | 436 | // |
| 430 | // Nothing here is Darwin-gated, because nothing in this file touches | |
| 431 | // Objective-C. | |
| 437 | // Everything here is main-thread state except the two atomics, which are the | |
| 438 | // only things the audio thread may touch. | |
| 432 | 439 | // ============================================================================= |
| 433 | 440 | |
| 434 | const testing = std.testing; | |
| 441 | /// The `SFSpeechRecognizer`, built once and kept. Swift's is built at | |
| 442 | /// coordinator init when the flag is on. | |
| 443 | var recognizer: Id = null; | |
| 435 | 444 | |
| 436 | test "this module declares no actions, so both fall through to the shim" { | |
| 437 | // Table -> dispatch, with the table empty. The shim serves both actions | |
| 438 | // correctly today and neither has a promise to strand, so an empty table | |
| 439 | // is the whole feature: `ios_dispatch.route` never enters this module and | |
| 440 | // `handOffToHost` answers. | |
| 441 | try testing.expectEqual(@as(usize, 0), capability_actions.len); | |
| 442 | try testing.expectEqual(@as(usize, 0), A.declared_count); | |
| 443 | } | |
| 444 | ||
| 445 | test "the two unserved actions are the spec's, spelled exactly" { | |
| 446 | // The spelling a future round will move into `A`. Pinned here so the move | |
| 447 | // is a copy rather than a retype — `startlistening` would route nowhere and | |
| 448 | // look exactly like this module still not serving it. | |
| 449 | try testing.expectEqual(@as(usize, 2), unserved_actions.len); | |
| 450 | try testing.expectEqualStrings("startListening", unserved_actions[0]); | |
| 451 | try testing.expectEqualStrings("stopListening", unserved_actions[1]); | |
| 452 | } | |
| 453 | ||
| 454 | test "neither unserved action is in the action table" { | |
| 455 | // The invariant that keeps the ratchet honest. An action listed in `A` | |
| 456 | // counts as migrated to `test/ios_conformance_test.zig` whether or not | |
| 457 | // anything answers it, so a name leaking from `unserved_actions` into the | |
| 458 | // table would lower the ratchet for work nobody did. | |
| 459 | for (unserved_actions) |name| { | |
| 460 | for (capability_actions) |decl| { | |
| 461 | try testing.expect(!std.mem.eql(u8, decl.name, name)); | |
| 462 | } | |
| 445 | /// The `AVAudioEngine`. Swift's is `private var audioEngine = AVAudioEngine()` | |
| 446 | /// (`:381`) — one instance for the process. | |
| 447 | var engine: Id = null; | |
| 448 | ||
| 449 | /// The current `SFSpeechRecognitionTask`, retained, cancelled by teardown. | |
| 450 | var task: Id = null; | |
| 451 | ||
| 452 | /// Whether a tap is installed on bus 0 of the engine's input node. The only | |
| 453 | /// thing that makes teardown touch the engine at all. | |
| 454 | var tap_installed: bool = false; | |
| 455 | ||
| 456 | /// Whether a start is between `requestAuthorization:` and the main-queue hop. | |
| 457 | /// A second `startListening` in that window is dropped rather than queued: it | |
| 458 | /// would produce a second authorization callback racing the first one's | |
| 459 | /// `beginRecording`, and the page cannot tell two starts apart anyway. | |
| 460 | var starting: bool = false; | |
| 461 | ||
| 462 | /// Whether a session is running, in the sense that `craftSpeechStart` was | |
| 463 | /// emitted and no end has been. | |
| 464 | var listening: bool = false; | |
| 465 | ||
| 466 | /// `@selector(appendAudioPCMBuffer:)`, interned on the main thread before the | |
| 467 | /// tap is installed. The audio thread must never call `sel_registerName`, | |
| 468 | /// which takes the runtime's lock. | |
| 469 | var sel_append: objc.SEL = null; | |
| 470 | ||
| 471 | /// The `SFSpeechAudioBufferRecognitionRequest` the tap may append to, as a | |
| 472 | /// `usize`. Zero means nobody may append. | |
| 473 | /// | |
| 474 | /// `.seq_cst` on every access; see the module comment on Dekker. | |
| 475 | var active_request: std.atomic.Value(usize) = .init(0); | |
| 476 | ||
| 477 | /// How many tap invocations are between their fence and their append. Teardown | |
| 478 | /// waits for this to reach zero before releasing what `active_request` held. | |
| 479 | var tap_in_flight: std.atomic.Value(u32) = .init(0); | |
| 480 | ||
| 481 | /// The authorization status, written on whatever queue Speech chose and read | |
| 482 | /// on the main queue after the hop. | |
| 483 | var auth_status: std.atomic.Value(isize) = .init(0); | |
| 484 | ||
| 485 | // ============================================================================= | |
| 486 | // startListening. | |
| 487 | // ============================================================================= | |
| 488 | ||
| 489 | /// `case "startListening"` (`CraftApp.swift:533-534`, `:2486-2548`). | |
| 490 | /// | |
| 491 | /// Returns nothing and reports nothing to the dispatcher: every outcome is an | |
| 492 | /// event. The plist guard runs before `requestAuthorization:` because asking | |
| 493 | /// without the key terminates the process rather than failing. | |
| 494 | fn startListening() void { | |
| 495 | if (!is_darwin) { | |
| 496 | emitError(err_recognizer_unavailable); | |
| 497 | return; | |
| 463 | 498 | } |
| 499 | ||
| 500 | if (starting) { | |
| 501 | std.log.info("startListening: an authorization request is already in flight", .{}); | |
| 502 | return; | |
| 503 | } | |
| 504 | ||
| 505 | if (!hasSpeechUsageDescription()) { | |
| 506 | std.log.warn( | |
| 507 | "startListening refused: Info.plist has no {s}, so this app was not built " ++ | |
| 508 | "with speech recognition enabled", | |
| 509 | .{key_speech_usage}, | |
| 510 | ); | |
| 511 | emitError(err_recognizer_unavailable); | |
| 512 | return; | |
| 513 | } | |
| 514 | ||
| 515 | const SFSpeechRecognizer = objc.objc_getClass("SFSpeechRecognizer") orelse { | |
| 516 | std.log.warn( | |
| 517 | "startListening: SFSpeechRecognizer is not in this process; " ++ | |
| 518 | "the app does not link Speech", | |
| 519 | .{}, | |
| 520 | ); | |
| 521 | emitError(err_recognizer_unavailable); | |
| 522 | return; | |
| 523 | }; | |
| 524 | const sel_request = objc.sel_registerName("requestAuthorization:") orelse { | |
| 525 | emitError(err_recognizer_unavailable); | |
| 526 | return; | |
| 527 | }; | |
| 528 | ||
| 529 | starting = true; | |
| 530 | ||
| 531 | const RequestFn = *const fn (Id, objc.SEL, *const AuthBlock) callconv(.c) void; | |
| 532 | const requestAuthorization: RequestFn = @ptrCast(&objc.objc_msgSend); | |
| 533 | requestAuthorization(SFSpeechRecognizer, sel_request, &auth_block); | |
| 464 | 534 | } |
| 465 | 535 | |
| 466 | test "handleMessage refuses everything, including the actions it researched" { | |
| 467 | // Dispatch -> table, with both empty. `UnknownAction` is the only error | |
| 468 | // `ios_dispatch.route` reads as "not mine, ask the next"; any other error | |
| 469 | // is treated as final and would stop the chain before the shim. | |
| 470 | var bridge = SpeechBridge.init(testing.allocator); | |
| 471 | defer bridge.deinit(); | |
| 536 | /// Whether the main bundle's Info.plist carries the speech usage description. | |
| 537 | /// | |
| 538 | /// Answers `false` on any runtime failure rather than propagating one. Unlike | |
| 539 | /// `bridge_mobile_motion.zig`'s version, which separates "no NSBundle class" | |
| 540 | /// from "not configured" because it has an error to return, every caller here | |
| 541 | /// has only an event to emit — and the event would be the same either way, so | |
| 542 | /// the distinction would cost a code path and buy a page nothing. The log line | |
| 543 | /// above the call is where a broken process is named. | |
| 544 | fn hasSpeechUsageDescription() bool { | |
| 545 | if (!is_darwin) return false; | |
| 546 | ||
| 547 | const NSBundle = objc.objc_getClass("NSBundle") orelse return false; | |
| 548 | const sel_main = objc.sel_registerName("mainBundle") orelse return false; | |
| 549 | const bundle = objc.msgSendId(NSBundle, sel_main) orelse return false; | |
| 550 | ||
| 551 | const NSString = objc.objc_getClass("NSString") orelse return false; | |
| 552 | const sel_string = objc.sel_registerName("stringWithUTF8String:") orelse return false; | |
| 553 | const ns_key = objc.msgSendId1( | |
| 554 | NSString, | |
| 555 | sel_string, | |
| 556 | @as([*:0]const u8, key_speech_usage), | |
| 557 | ) orelse return false; | |
| 558 | ||
| 559 | const sel_lookup = objc.sel_registerName("objectForInfoDictionaryKey:") orelse return false; | |
| 560 | return objc.msgSendId1(bundle, sel_lookup, ns_key) != null; | |
| 561 | } | |
| 562 | ||
| 563 | /// The main-queue half of the authorization answer. | |
| 564 | /// | |
| 565 | /// Swift hops here too (`:2493`) before `beginRecording`, because activating an | |
| 566 | /// audio session and starting an engine off the main thread is not supported. | |
| 567 | fn authorizedOnMain(_: ?*anyopaque) callconv(.c) void { | |
| 568 | starting = false; | |
| 569 | ||
| 570 | if (auth_status.load(.seq_cst) != status_authorized) { | |
| 571 | std.log.warn( | |
| 572 | "startListening: speech authorization was not granted (status {d})", | |
| 573 | .{auth_status.load(.seq_cst)}, | |
| 574 | ); | |
| 575 | emitError(err_not_authorized); | |
| 576 | return; | |
| 577 | } | |
| 472 | 578 | |
| 473 | const E = bridge_error.BridgeError; | |
| 579 | beginRecording() catch |err| { | |
| 580 | std.log.warn("startListening: {s}", .{messageFor(err)}); | |
| 581 | emitError(messageFor(err)); | |
| 582 | return; | |
| 583 | }; | |
| 584 | } | |
| 474 | 585 | |
| 475 | for (unserved_actions) |name| { | |
| 476 | try testing.expectError(E.UnknownAction, bridge.handleMessage(name, "{}")); | |
| 586 | /// Everything `beginRecording` does, in Swift's order (`:2496-2548`). | |
| 587 | /// | |
| 588 | /// Once `active_request` is published, ownership of the request belongs to | |
| 589 | /// `teardown`, so every failure after that point goes through `failStart` | |
| 590 | /// rather than releasing anything itself. That is why there is no `errdefer` | |
| 591 | /// here: an errdefer plus a teardown is a double release, and the object it | |
| 592 | /// would double-release is one an audio thread may be holding. | |
| 593 | fn beginRecording() StartFailure!void { | |
| 594 | // Swift cancels only the task and then installs a second tap, which | |
| 595 | // raises. Stop properly instead — and emit no end, because a restart is | |
| 596 | // not a stop. | |
| 597 | if (listening or tap_installed) teardown(false); | |
| 598 | ||
| 599 | const session = sharedAudioSession() orelse return error.AudioSession; | |
| 600 | configureSession(session) catch return error.AudioSession; | |
| 601 | ||
| 602 | const rec = ensureRecognizer() orelse return error.RecognizerUnavailable; | |
| 603 | if (!recognizerIsAvailable(rec)) { | |
| 604 | std.log.warn("startListening: the recognizer reports itself unavailable", .{}); | |
| 605 | return error.RecognizerUnavailable; | |
| 477 | 606 | } |
| 478 | 607 | |
| 479 | // Casing, near misses, and the neighbouring namespaces' spellings — the | |
| 480 | // desktop `speechRecognition` actions in particular, which are a different | |
| 481 | // namespace and must never be answered from here. | |
| 482 | for ([_][]const u8{ | |
| 483 | "startlistening", | |
| 484 | "StartListening", | |
| 485 | "startListen", | |
| 486 | "listen", | |
| 487 | "start", | |
| 488 | "stop", | |
| 489 | "isAvailable", | |
| 490 | "speak", | |
| 491 | "startMotionUpdates", | |
| 492 | "getDeviceInfo", | |
| 493 | "", | |
| 494 | }) |name| { | |
| 495 | try testing.expectError(E.UnknownAction, bridge.handleMessage(name, "{}")); | |
| 608 | const eng = ensureEngine() orelse return error.AudioEngine; | |
| 609 | const input = inputNode(eng) orelse return error.AudioEngine; | |
| 610 | const format = outputFormat(input) orelse return error.AudioEngine; | |
| 611 | ||
| 612 | // Precondition 3. `installTapOnBus:` on a zero format raises an | |
| 613 | // NSException, and an uncaught ObjC exception is an uncatchable SIGABRT — | |
| 614 | // Swift aborts here, this returns. | |
| 615 | if (!formatCarriesInput(format)) { | |
| 616 | std.log.warn( | |
| 617 | "startListening: the input node reports no usable format, " ++ | |
| 618 | "so this process has no audio input route", | |
| 619 | .{}, | |
| 620 | ); | |
| 621 | return error.AudioEngine; | |
| 496 | 622 | } |
| 623 | ||
| 624 | // Interned before the tap exists, so the audio thread never needs the | |
| 625 | // runtime's selector lock. | |
| 626 | sel_append = objc.sel_registerName("appendAudioPCMBuffer:") orelse | |
| 627 | return error.RecognizerUnavailable; | |
| 628 | ||
| 629 | const request = newRecognitionRequest() orelse return error.RecognizerUnavailable; | |
| 630 | setShouldReportPartialResults(request, true); | |
| 631 | ||
| 632 | // From here on the request is teardown's to release. | |
| 633 | active_request.store(@intFromPtr(request), .seq_cst); | |
| 634 | ||
| 635 | const started_task = startRecognitionTask(rec, request) orelse | |
| 636 | return failStart(error.RecognizerUnavailable); | |
| 637 | // `recognitionTaskWithRequest:` returns an autoreleased task; without a | |
| 638 | // retain it dies at the end of this turn of the run loop and the stream | |
| 639 | // stops with no event to say so. | |
| 640 | task = objc.retain(started_task); | |
| 641 | ||
| 642 | installTap(input, format) catch return failStart(error.AudioEngine); | |
| 643 | tap_installed = true; | |
| 644 | ||
| 645 | prepareEngine(eng); | |
| 646 | if (!startEngine(eng)) return failStart(error.AudioEngine); | |
| 647 | ||
| 648 | listening = true; | |
| 649 | ios_events.emit(event_start, empty_detail); | |
| 650 | fireHaptic(); | |
| 497 | 651 | } |
| 498 | 652 | |
| 499 | test "no payload can turn the fall-through into a final error" { | |
| 500 | // The subtle way a serve-nothing module breaks the thing it is protecting. | |
| 501 | // `ios_dispatch.route` stops the chain on any error but `UnknownAction`, so | |
| 502 | // a module that parsed its payload before routing would answer | |
| 503 | // `InvalidJSON` for a malformed one and strand an action it does not | |
| 504 | // serve — the page would get a rejection where the shim would have worked. | |
| 505 | var bridge = SpeechBridge.init(testing.allocator); | |
| 506 | defer bridge.deinit(); | |
| 653 | /// Tear down whatever was built, then report why the start failed. | |
| 654 | /// | |
| 655 | /// No `craftSpeechEnd`: a start that never emitted `craftSpeechStart` has no | |
| 656 | /// end to announce, and Swift's failure paths emit only the error. | |
| 657 | fn failStart(err: StartFailure) StartFailure { | |
| 658 | teardown(false); | |
| 659 | return err; | |
| 660 | } | |
| 661 | ||
| 662 | // ============================================================================= | |
| 663 | // stopListening, and the teardown both stops share. | |
| 664 | // ============================================================================= | |
| 665 | ||
| 666 | /// `case "stopListening"` (`CraftApp.swift:535-536`, `:2550-2559`). | |
| 667 | /// | |
| 668 | /// Ungated in the spec — there is no `if config.` on this case — so | |
| 669 | /// `ios_config.gateFor` has no entry for it either, and an app with speech | |
| 670 | /// disabled can still stop. Which matters: the page's own stop is how a stuck | |
| 671 | /// listening indicator gets cleared. | |
| 672 | fn stopListening() void { | |
| 673 | if (!is_darwin) { | |
| 674 | // Nothing to stop, and the page still gets its end. `emit` is a no-op | |
| 675 | // off Darwin, so this is documentation more than behaviour. | |
| 676 | ios_events.emit(event_end, empty_detail); | |
| 677 | return; | |
| 678 | } | |
| 679 | teardown(true); | |
| 680 | } | |
| 681 | ||
| 682 | /// The main-queue landing for a stop the recognition handler asked for. | |
| 683 | /// | |
| 684 | /// Precondition 5: the handler fires on an internal Speech queue, and | |
| 685 | /// `AVAudioEngine` must not be touched from there. | |
| 686 | fn stopOnMain(_: ?*anyopaque) callconv(.c) void { | |
| 687 | teardown(true); | |
| 688 | } | |
| 689 | ||
| 690 | /// Release everything, in the one order that is safe against the audio thread. | |
| 691 | /// | |
| 692 | /// 1. Stop the engine and remove the tap, so `AVAudioEngine` guarantees no | |
| 693 | /// new tap call begins. | |
| 694 | /// 2. Clear the published request, so a call that began before step 1 | |
| 695 | /// returned finds nothing to append to. | |
| 696 | /// 3. Drain: wait for any in-flight tap call to leave. | |
| 697 | /// 4. `endAudio`, then release — or leak, if step 3 timed out. | |
| 698 | /// 5. Cancel and release the task. | |
| 699 | /// | |
| 700 | /// Steps 1 and 2 in that order rather than the reverse: clearing first would | |
| 701 | /// silently drop the last buffers the tap had already delivered, which is | |
| 702 | /// audio Swift would have transcribed. | |
| 703 | /// | |
| 704 | /// Idempotent. Every field is checked, so a stop that stops nothing does | |
| 705 | /// nothing but emit — which is exactly what `stopListening` needs. | |
| 706 | fn teardown(emit_end: bool) void { | |
| 707 | if (!is_darwin) return; | |
| 708 | ||
| 709 | if (tap_installed) { | |
| 710 | if (engine) |eng| { | |
| 711 | stopEngine(eng); | |
| 712 | if (inputNode(eng)) |input| removeTap(input); | |
| 713 | } | |
| 714 | tap_installed = false; | |
| 715 | } | |
| 507 | 716 | |
| 508 | const E = bridge_error.BridgeError; | |
| 509 | ||
| 510 | for ([_][]const u8{ | |
| 511 | "{not json", | |
| 512 | "", | |
| 513 | "null", | |
| 514 | "[1,2,3]", | |
| 515 | "{\"transcript\":\"hello\"}", | |
| 516 | "{\"callbackId\":\"cb_7\"}", | |
| 517 | }) |payload| { | |
| 518 | for (unserved_actions) |name| { | |
| 519 | try testing.expectError(E.UnknownAction, bridge.handleMessage(name, payload)); | |
| 717 | const held = active_request.swap(0, .seq_cst); | |
| 718 | const drained = drainTap(); | |
| 719 | ||
| 720 | if (held != 0) { | |
| 721 | const request: Id = @ptrFromInt(held); | |
| 722 | endAudio(request); | |
| 723 | if (drained) { | |
| 724 | objc.release(request); | |
| 725 | } else { | |
| 726 | std.log.warn( | |
| 727 | "stopListening: the audio thread did not leave within {d}ms, " ++ | |
| 728 | "so one recognition request is leaked rather than released", | |
| 729 | .{(drain_spins * drain_spin_micros) / 1000}, | |
| 730 | ); | |
| 520 | 731 | } |
| 521 | 732 | } |
| 733 | ||
| 734 | if (task) |t| { | |
| 735 | cancelTask(t); | |
| 736 | objc.release(t); | |
| 737 | task = null; | |
| 738 | } | |
| 739 | ||
| 740 | listening = false; | |
| 741 | ||
| 742 | if (emit_end) { | |
| 743 | ios_events.emit(event_end, empty_detail); | |
| 744 | fireHaptic(); | |
| 745 | } | |
| 522 | 746 | } |
| 523 | 747 | |
| 524 | test "the three spellable events are the ones the page subscribes to" { | |
| 525 | // `test-bridges.html:384`, `:388`, `:391`, and Swift's `sendToWeb` call | |
| 526 | // sites. camelCase, no colon — the iOS vocabulary, which is why | |
| 527 | // `ios_events.Event` exists separately from `capabilities.Channel`. | |
| 528 | try testing.expectEqualStrings("craftSpeechResult", event_result.eventName()); | |
| 529 | try testing.expectEqualStrings("craftSpeechError", event_error.eventName()); | |
| 530 | try testing.expectEqualStrings("craftSpeechEnd", event_end.eventName()); | |
| 748 | /// Wait for `tap_in_flight` to reach zero, bounded. | |
| 749 | /// | |
| 750 | /// Sleeping rather than spinning hot: the audio thread runs at a higher | |
| 751 | /// priority than the main thread, so burning the main thread's slice is the | |
| 752 | /// one thing that could actually delay the call being waited on. This Zig has | |
| 753 | /// no `std.Thread.sleep` (`startup_timing.zig:150` records the same gap), and | |
| 754 | /// a busy spin is the wrong shape here, so the sleep is libc's — which this | |
| 755 | /// file already depends on for `dlsym` and `dispatch_async_f`. | |
| 756 | fn drainTap() bool { | |
| 757 | var spins: usize = 0; | |
| 758 | while (spins < drain_spins) : (spins += 1) { | |
| 759 | if (tap_in_flight.load(.seq_cst) == 0) return true; | |
| 760 | _ = usleep(drain_spin_micros); | |
| 761 | } | |
| 762 | return tap_in_flight.load(.seq_cst) == 0; | |
| 763 | } | |
| 531 | 764 | |
| 532 | // And no desktop channel can spell any of them, so emitting through | |
| 533 | // `capabilities.Channel` would fire events with no subscriber. | |
| 534 | for (std.enums.values(capabilities.Channel)) |channel| { | |
| 535 | try testing.expect(!std.mem.eql(u8, channel.eventName(), event_result.eventName())); | |
| 536 | try testing.expect(!std.mem.eql(u8, channel.eventName(), event_error.eventName())); | |
| 537 | try testing.expect(!std.mem.eql(u8, channel.eventName(), event_end.eventName())); | |
| 538 | try testing.expect(!std.mem.eql(u8, channel.eventName(), event_start_name)); | |
| 765 | /// `triggerHaptic(style: "light")`, as `:2544` and `:2558` fire it. | |
| 766 | /// | |
| 767 | /// Ungated on purpose — see the module comment. Errors are swallowed because | |
| 768 | /// the Taptic Engine is absent on the simulator and on iPad, and a haptic that | |
| 769 | /// could not fire is not a reason to withhold a speech event. | |
| 770 | fn fireHaptic() void { | |
| 771 | haptics.triggerHapticChecked(.impact_light) catch |err| { | |
| 772 | std.log.debug("speech: the light haptic did not fire: {}", .{err}); | |
| 773 | }; | |
| 774 | } | |
| 775 | ||
| 776 | // ============================================================================= | |
| 777 | // Blocks. | |
| 778 | // | |
| 779 | // All three are global blocks — `_NSConcreteGlobalBlock` with | |
| 780 | // `BLOCK_IS_GLOBAL`, so `Block_copy` is identity and none of them can outlive | |
| 781 | // its storage. None captures anything: the authorization block writes an | |
| 782 | // atomic and hops, the result block reads its arguments, and the tap block | |
| 783 | // reads two atomics. Capture would mean a heap block, a copy helper, and a | |
| 784 | // dispose helper, and the tap block would then be allocating on the audio | |
| 785 | // thread. | |
| 786 | // ============================================================================= | |
| 787 | ||
| 788 | const BlockDescriptor = extern struct { | |
| 789 | reserved: c_ulong = 0, | |
| 790 | size: c_ulong, | |
| 791 | }; | |
| 792 | ||
| 793 | /// 1 << 28 — a global block is never copied. | |
| 794 | const BLOCK_IS_GLOBAL: c_int = 1 << 28; | |
| 795 | ||
| 796 | extern var _NSConcreteGlobalBlock: anyopaque; | |
| 797 | ||
| 798 | /// `void (^)(SFSpeechRecognizerAuthorizationStatus status)`. | |
| 799 | const AuthBlock = extern struct { | |
| 800 | isa: ?*anyopaque, | |
| 801 | flags: c_int, | |
| 802 | reserved: c_int = 0, | |
| 803 | invoke: *const anyopaque, | |
| 804 | descriptor: *const BlockDescriptor, | |
| 805 | }; | |
| 806 | ||
| 807 | const auth_block_descriptor = BlockDescriptor{ .size = @sizeOf(AuthBlock) }; | |
| 808 | ||
| 809 | fn authInvoke(_: *const AuthBlock, status: isize) callconv(.c) void { | |
| 810 | // An arbitrary queue. Record and hop; touch nothing else. | |
| 811 | auth_status.store(status, .seq_cst); | |
| 812 | dispatch_async_f(&_dispatch_main_q, null, authorizedOnMain); | |
| 813 | } | |
| 814 | ||
| 815 | var auth_block: AuthBlock = if (is_darwin) .{ | |
| 816 | .isa = &_NSConcreteGlobalBlock, | |
| 817 | .flags = BLOCK_IS_GLOBAL, | |
| 818 | .invoke = @ptrCast(&authInvoke), | |
| 819 | .descriptor = &auth_block_descriptor, | |
| 820 | } else undefined; | |
| 821 | ||
| 822 | /// `void (^)(SFSpeechRecognitionResult *result, NSError *error)`. | |
| 823 | const ResultBlock = extern struct { | |
| 824 | isa: ?*anyopaque, | |
| 825 | flags: c_int, | |
| 826 | reserved: c_int = 0, | |
| 827 | invoke: *const anyopaque, | |
| 828 | descriptor: *const BlockDescriptor, | |
| 829 | }; | |
| 830 | ||
| 831 | const result_block_descriptor = BlockDescriptor{ .size = @sizeOf(ResultBlock) }; | |
| 832 | ||
| 833 | /// Swift's result handler (`:2522-2533`), including its discarded error. | |
| 834 | fn resultInvoke(_: *const ResultBlock, result: Id, err: Id) callconv(.c) void { | |
| 835 | var is_final = false; | |
| 836 | ||
| 837 | if (result) |r| { | |
| 838 | is_final = resultIsFinal(r); | |
| 839 | emitTranscript(r, is_final); | |
| 840 | } | |
| 841 | ||
| 842 | if (err != null or is_final) { | |
| 843 | // Precondition 5: this is an internal Speech queue, and the teardown | |
| 844 | // touches AVAudioEngine. | |
| 845 | dispatch_async_f(&_dispatch_main_q, null, stopOnMain); | |
| 539 | 846 | } |
| 540 | // Non-vacuity: the loop above proves nothing over an empty enum. | |
| 541 | try testing.expect(std.enums.values(capabilities.Channel).len >= 40); | |
| 542 | } | |
| 543 | ||
| 544 | test "craftSpeechStart is still unspellable, which is blocker one" { | |
| 545 | // A tripwire, not a preference. This module's first blocker is that | |
| 546 | // `ios_events.Event` has no `.speech_start`, and the moment somebody adds | |
| 547 | // it precondition 1 is met — which should be noticed here, in the file | |
| 548 | // that documents it, rather than in a later round rediscovering the | |
| 549 | // research. Blockers 2-4 still stand on their own, so this trip is a | |
| 550 | // prompt to re-read them, never a clearance to serve. | |
| 551 | if (@hasField(ios_events.Event, "speech_start")) { | |
| 552 | std.debug.print( | |
| 553 | "ios_events.Event now has .speech_start, so blocker 1 in " ++ | |
| 554 | "bridge_mobile_speech.zig is lifted.\n" ++ | |
| 555 | " Emit it through the enum, delete event_start_name, and work " ++ | |
| 556 | "through preconditions 2-5 before moving either action into `A`.\n", | |
| 847 | } | |
| 848 | ||
| 849 | var result_block: ResultBlock = if (is_darwin) .{ | |
| 850 | .isa = &_NSConcreteGlobalBlock, | |
| 851 | .flags = BLOCK_IS_GLOBAL, | |
| 852 | .invoke = @ptrCast(&resultInvoke), | |
| 853 | .descriptor = &result_block_descriptor, | |
| 854 | } else undefined; | |
| 855 | ||
| 856 | /// `AVAudioNodeTapBlock` — `void (^)(AVAudioPCMBuffer *buffer, AVAudioTime | |
| 857 | /// *when)` (`AVAudioNode.h:32`). | |
| 858 | const TapBlock = extern struct { | |
| 859 | isa: ?*anyopaque, | |
| 860 | flags: c_int, | |
| 861 | reserved: c_int = 0, | |
| 862 | invoke: *const anyopaque, | |
| 863 | descriptor: *const BlockDescriptor, | |
| 864 | }; | |
| 865 | ||
| 866 | const tap_block_descriptor = BlockDescriptor{ .size = @sizeOf(TapBlock) }; | |
| 867 | ||
| 868 | /// The audio I/O thread. Two atomics, one `objc_msgSend`, nothing else. | |
| 869 | /// | |
| 870 | /// No allocation, no `sel_registerName`, no logging, no lock: each of those | |
| 871 | /// takes a lock somewhere, and taking a lock here inverts priority against | |
| 872 | /// whatever holds it. `when` is unread, as it is in Swift. | |
| 873 | fn tapInvoke(_: *const TapBlock, buffer: Id, when: Id) callconv(.c) void { | |
| 874 | _ = when; | |
| 875 | ||
| 876 | _ = tap_in_flight.fetchAdd(1, .seq_cst); | |
| 877 | defer _ = tap_in_flight.fetchSub(1, .seq_cst); | |
| 878 | ||
| 879 | const held = active_request.load(.seq_cst); | |
| 880 | if (held == 0) return; | |
| 881 | ||
| 882 | const request: Id = @ptrFromInt(held); | |
| 883 | const AppendFn = *const fn (Id, objc.SEL, Id) callconv(.c) void; | |
| 884 | const append: AppendFn = @ptrCast(&objc.objc_msgSend); | |
| 885 | append(request, sel_append, buffer); | |
| 886 | } | |
| 887 | ||
| 888 | var tap_block: TapBlock = if (is_darwin) .{ | |
| 889 | .isa = &_NSConcreteGlobalBlock, | |
| 890 | .flags = BLOCK_IS_GLOBAL, | |
| 891 | .invoke = @ptrCast(&tapInvoke), | |
| 892 | .descriptor = &tap_block_descriptor, | |
| 893 | } else undefined; | |
| 894 | ||
| 895 | // ============================================================================= | |
| 896 | // The Objective-C calls, one thin wrapper each. | |
| 897 | // | |
| 898 | // Wrapped rather than inlined so `beginRecording` reads as the sequence Swift | |
| 899 | // reads as, and so every signature is written exactly once — the place this | |
| 900 | // migration has repeatedly found its mistakes. | |
| 901 | // ============================================================================= | |
| 902 | ||
| 903 | fn sharedAudioSession() Id { | |
| 904 | const AVAudioSession = objc.objc_getClass("AVAudioSession") orelse { | |
| 905 | std.log.warn( | |
| 906 | "startListening: AVAudioSession is not in this process; " ++ | |
| 907 | "the app does not link AVFoundation", | |
| 557 | 908 | .{}, |
| 558 | 909 | ); |
| 559 | return error.SpeechStartBlockerLifted; | |
| 910 | return null; | |
| 911 | }; | |
| 912 | const sel = objc.sel_registerName("sharedInstance") orelse return null; | |
| 913 | return objc.msgSendId(AVAudioSession, sel); | |
| 914 | } | |
| 915 | ||
| 916 | /// `setCategory(.record, mode: .measurement, options: .duckOthers)` then | |
| 917 | /// `setActive(true, options: .notifyOthersOnDeactivation)` — Swift `:2502-2505`. | |
| 918 | fn configureSession(session: Id) !void { | |
| 919 | const category = audioSessionConstant("AVAudioSessionCategoryRecord") orelse | |
| 920 | return error.NotFound; | |
| 921 | const mode = audioSessionConstant("AVAudioSessionModeMeasurement") orelse | |
| 922 | return error.NotFound; | |
| 923 | ||
| 924 | const sel_category = objc.sel_registerName("setCategory:mode:options:error:") orelse | |
| 925 | return error.SelectorNotFound; | |
| 926 | const CategoryFn = *const fn (Id, objc.SEL, Id, Id, c_ulong, ?*Id) callconv(.c) bool; | |
| 927 | const setCategory: CategoryFn = @ptrCast(&objc.objc_msgSend); | |
| 928 | var category_error: Id = null; | |
| 929 | if (!setCategory( | |
| 930 | session, | |
| 931 | sel_category, | |
| 932 | category, | |
| 933 | mode, | |
| 934 | category_option_duck_others, | |
| 935 | &category_error, | |
| 936 | )) { | |
| 937 | logNSError("startListening", category_error); | |
| 938 | return error.NativeCallFailed; | |
| 560 | 939 | } |
| 561 | 940 | |
| 562 | // Until then the name exists only as a string, and it is the right one. | |
| 563 | try testing.expectEqualStrings("craftSpeechStart", event_start_name); | |
| 941 | const sel_active = objc.sel_registerName("setActive:withOptions:error:") orelse | |
| 942 | return error.SelectorNotFound; | |
| 943 | const ActiveFn = *const fn (Id, objc.SEL, bool, c_ulong, ?*Id) callconv(.c) bool; | |
| 944 | const setActive: ActiveFn = @ptrCast(&objc.objc_msgSend); | |
| 945 | var active_error: Id = null; | |
| 946 | if (!setActive(session, sel_active, true, set_active_notify_others, &active_error)) { | |
| 947 | logNSError("startListening", active_error); | |
| 948 | return error.NativeCallFailed; | |
| 949 | } | |
| 564 | 950 | } |
| 565 | 951 | |
| 566 | test "start and end carry an empty object, not an empty string" { | |
| 567 | // `data: [:]` through `JSONSerialization` is `{}`. `ios_events.formatEvent` | |
| 568 | // inlines the detail as a literal, so `""` would produce | |
| 569 | // `{detail:}` — a syntax error that takes the whole event with it — and | |
| 570 | // `"null"` would make `e.detail` null where the page expects an object. | |
| 571 | try testing.expectEqualStrings("{}", empty_detail); | |
| 952 | /// `SFSpeechRecognizer(locale: Locale(identifier: "en-US"))`, built once. | |
| 953 | fn ensureRecognizer() Id { | |
| 954 | if (recognizer) |existing| return existing; | |
| 955 | ||
| 956 | const NSLocale = objc.objc_getClass("NSLocale") orelse return null; | |
| 957 | const sel_locale = objc.sel_registerName("localeWithLocaleIdentifier:") orelse return null; | |
| 958 | const NSString = objc.objc_getClass("NSString") orelse return null; | |
| 959 | const sel_string = objc.sel_registerName("stringWithUTF8String:") orelse return null; | |
| 960 | const identifier = objc.msgSendId1( | |
| 961 | NSString, | |
| 962 | sel_string, | |
| 963 | @as([*:0]const u8, recognizer_locale), | |
| 964 | ) orelse return null; | |
| 965 | const locale = objc.msgSendId1(NSLocale, sel_locale, identifier) orelse return null; | |
| 966 | ||
| 967 | const SFSpeechRecognizer = objc.objc_getClass("SFSpeechRecognizer") orelse return null; | |
| 968 | const sel_alloc = objc.sel_registerName("alloc") orelse return null; | |
| 969 | const sel_init = objc.sel_registerName("initWithLocale:") orelse return null; | |
| 970 | const allocated = objc.msgSendId(SFSpeechRecognizer, sel_alloc) orelse return null; | |
| 971 | ||
| 972 | // `-initWithLocale:` is nullable: an unsupported locale answers nil, and | |
| 973 | // then so does this, and the caller emits "Speech recognizer unavailable" | |
| 974 | // exactly as Swift's `guard let` does. | |
| 975 | recognizer = objc.msgSendId1(allocated, sel_init, locale); | |
| 976 | return recognizer; | |
| 977 | } | |
| 572 | 978 | |
| 573 | var parsed = try std.json.parseFromSlice(std.json.Value, testing.allocator, empty_detail, .{}); | |
| 574 | defer parsed.deinit(); | |
| 575 | try testing.expectEqual(@as(usize, 0), parsed.value.object.count()); | |
| 979 | fn recognizerIsAvailable(rec: Id) bool { | |
| 980 | const sel = objc.sel_registerName("isAvailable") orelse return false; | |
| 981 | return objc.msgSendBool(rec, sel); | |
| 576 | 982 | } |
| 577 | 983 | |
| 578 | // ----------------------------------------------------------------------------- | |
| 579 | // craftSpeechError | |
| 580 | // ----------------------------------------------------------------------------- | |
| 984 | fn ensureEngine() Id { | |
| 985 | if (engine) |existing| return existing; | |
| 986 | const AVAudioEngine = objc.objc_getClass("AVAudioEngine") orelse return null; | |
| 987 | engine = objc.allocInit(AVAudioEngine) catch null; | |
| 988 | return engine; | |
| 989 | } | |
| 581 | 990 | |
| 582 | test "the four error messages are Swift's, character for character" { | |
| 583 | // These strings are shown to a human (`test-bridges.html:392-393`) and | |
| 584 | // documented in README.md. A paraphrase changes what a user reads without | |
| 585 | // changing anything else a test can see. | |
| 586 | try testing.expectEqualStrings("Not authorized", err_not_authorized); | |
| 587 | try testing.expectEqualStrings("Audio session failed", err_audio_session); | |
| 588 | try testing.expectEqualStrings("Speech recognizer unavailable", err_recognizer_unavailable); | |
| 589 | try testing.expectEqualStrings("Audio engine failed", err_audio_engine); | |
| 590 | try testing.expectEqual(@as(usize, 4), error_messages.len); | |
| 991 | fn inputNode(eng: Id) Id { | |
| 992 | const sel = objc.sel_registerName("inputNode") orelse return null; | |
| 993 | return objc.msgSendId(eng, sel); | |
| 591 | 994 | } |
| 592 | 995 | |
| 593 | test "an error detail is the single key the page reads" { | |
| 594 | // `e.detail.error` (`test-bridges.html:392`) and nothing else. A `code` or | |
| 595 | // `message` key alongside it would be a surface no consumer knows about. | |
| 596 | const json = try shapeErrorDetail(testing.allocator, err_not_authorized); | |
| 597 | defer testing.allocator.free(json); | |
| 996 | fn outputFormat(node: Id) Id { | |
| 997 | const sel = objc.sel_registerName("outputFormatForBus:") orelse return null; | |
| 998 | const Fn = *const fn (Id, objc.SEL, c_ulong) callconv(.c) Id; | |
| 999 | const call: Fn = @ptrCast(&objc.objc_msgSend); | |
| 1000 | return call(node, sel, bus_zero); | |
| 1001 | } | |
| 598 | 1002 | |
| 599 | try testing.expectEqualStrings("{\"error\":\"Not authorized\"}", json); | |
| 1003 | /// Whether this format describes a real input route. | |
| 1004 | /// | |
| 1005 | /// The header says it in as many words: "Check for the input node's input | |
| 1006 | /// format for non-zero sample rate and channel count to see if input is | |
| 1007 | /// enabled" (`AVAudioEngine.h:459-461`). Both must be non-zero — a format with | |
| 1008 | /// a rate and no channels is as unusable as one with neither. | |
| 1009 | fn formatCarriesInput(format: Id) bool { | |
| 1010 | const sel_rate = objc.sel_registerName("sampleRate") orelse return false; | |
| 1011 | const RateFn = *const fn (Id, objc.SEL) callconv(.c) f64; | |
| 1012 | const sampleRate: RateFn = @ptrCast(&objc.objc_msgSend); | |
| 1013 | ||
| 1014 | const sel_channels = objc.sel_registerName("channelCount") orelse return false; | |
| 1015 | const ChannelFn = *const fn (Id, objc.SEL) callconv(.c) u32; | |
| 1016 | const channelCount: ChannelFn = @ptrCast(&objc.objc_msgSend); | |
| 1017 | ||
| 1018 | return sampleRate(format, sel_rate) > 0 and channelCount(format, sel_channels) > 0; | |
| 1019 | } | |
| 600 | 1020 | |
| 601 | var parsed = try std.json.parseFromSlice(std.json.Value, testing.allocator, json, .{}); | |
| 602 | defer parsed.deinit(); | |
| 603 | try testing.expectEqual(@as(usize, 1), parsed.value.object.count()); | |
| 604 | try testing.expectEqualStrings("Not authorized", parsed.value.object.get("error").?.string); | |
| 1021 | fn newRecognitionRequest() Id { | |
| 1022 | const class = objc.objc_getClass("SFSpeechAudioBufferRecognitionRequest") orelse return null; | |
| 1023 | return objc.allocInit(class) catch null; | |
| 605 | 1024 | } |
| 606 | 1025 | |
| 607 | test "every one of the four messages shapes and parses back" { | |
| 608 | for (error_messages) |message| { | |
| 609 | const json = try shapeErrorDetail(testing.allocator, message); | |
| 610 | defer testing.allocator.free(json); | |
| 1026 | fn setShouldReportPartialResults(request: Id, value: bool) void { | |
| 1027 | const sel = objc.sel_registerName("setShouldReportPartialResults:") orelse return; | |
| 1028 | const Fn = *const fn (Id, objc.SEL, bool) callconv(.c) void; | |
| 1029 | const call: Fn = @ptrCast(&objc.objc_msgSend); | |
| 1030 | call(request, sel, value); | |
| 1031 | } | |
| 611 | 1032 | |
| 612 | var parsed = try std.json.parseFromSlice(std.json.Value, testing.allocator, json, .{}); | |
| 613 | defer parsed.deinit(); | |
| 614 | try testing.expectEqual(@as(usize, 1), parsed.value.object.count()); | |
| 615 | try testing.expectEqualStrings(message, parsed.value.object.get("error").?.string); | |
| 616 | } | |
| 1033 | fn startRecognitionTask(rec: Id, request: Id) Id { | |
| 1034 | const sel = objc.sel_registerName("recognitionTaskWithRequest:resultHandler:") orelse | |
| 1035 | return null; | |
| 1036 | const Fn = *const fn (Id, objc.SEL, Id, *const ResultBlock) callconv(.c) Id; | |
| 1037 | const call: Fn = @ptrCast(&objc.objc_msgSend); | |
| 1038 | return call(rec, sel, request, &result_block); | |
| 617 | 1039 | } |
| 618 | 1040 | |
| 619 | test "an error message carrying a quote does not end the object early" { | |
| 620 | // No current message does. The escaping is a property of the position, not | |
| 621 | // of today's inputs, and a future round quoting a framework error is | |
| 622 | // exactly how the unescaped case arrives. | |
| 623 | const json = try shapeErrorDetail(testing.allocator, "recognizer said \"no\"\\ever"); | |
| 624 | defer testing.allocator.free(json); | |
| 1041 | fn installTap(node: Id, format: Id) !void { | |
| 1042 | const sel = objc.sel_registerName("installTapOnBus:bufferSize:format:block:") orelse | |
| 1043 | return error.SelectorNotFound; | |
| 1044 | const Fn = *const fn (Id, objc.SEL, c_ulong, u32, Id, *const TapBlock) callconv(.c) void; | |
| 1045 | const call: Fn = @ptrCast(&objc.objc_msgSend); | |
| 1046 | call(node, sel, bus_zero, tap_buffer_frames, format, &tap_block); | |
| 1047 | } | |
| 625 | 1048 | |
| 626 | try testing.expectEqualStrings( | |
| 627 | "{\"error\":\"recognizer said \\\"no\\\"\\\\ever\"}", | |
| 628 | json, | |
| 629 | ); | |
| 1049 | fn removeTap(node: Id) void { | |
| 1050 | const sel = objc.sel_registerName("removeTapOnBus:") orelse return; | |
| 1051 | const Fn = *const fn (Id, objc.SEL, c_ulong) callconv(.c) void; | |
| 1052 | const call: Fn = @ptrCast(&objc.objc_msgSend); | |
| 1053 | call(node, sel, bus_zero); | |
| 1054 | } | |
| 630 | 1055 | |
| 631 | var parsed = try std.json.parseFromSlice(std.json.Value, testing.allocator, json, .{}); | |
| 632 | defer parsed.deinit(); | |
| 633 | try testing.expectEqualStrings( | |
| 634 | "recognizer said \"no\"\\ever", | |
| 635 | parsed.value.object.get("error").?.string, | |
| 636 | ); | |
| 1056 | fn prepareEngine(eng: Id) void { | |
| 1057 | const sel = objc.sel_registerName("prepare") orelse return; | |
| 1058 | objc.msgSend(eng, sel); | |
| 637 | 1059 | } |
| 638 | 1060 | |
| 639 | // ----------------------------------------------------------------------------- | |
| 640 | // craftSpeechResult | |
| 641 | // ----------------------------------------------------------------------------- | |
| 1061 | fn startEngine(eng: Id) bool { | |
| 1062 | const sel = objc.sel_registerName("startAndReturnError:") orelse return false; | |
| 1063 | const Fn = *const fn (Id, objc.SEL, ?*Id) callconv(.c) bool; | |
| 1064 | const call: Fn = @ptrCast(&objc.objc_msgSend); | |
| 1065 | var start_error: Id = null; | |
| 1066 | if (call(eng, sel, &start_error)) return true; | |
| 1067 | logNSError("startListening", start_error); | |
| 1068 | return false; | |
| 1069 | } | |
| 642 | 1070 | |
| 643 | test "a result detail is exactly transcript and isFinal" { | |
| 644 | // `CraftApp.swift:2525-2528`, and the two keys `test-bridges.html:386` | |
| 645 | // reads. These are the bytes `e.detail` receives either way, because | |
| 646 | // `sendToWeb` and `ios_events.formatEvent` inline the detail identically. | |
| 647 | const partial = try shapeResultDetail(testing.allocator, "hello world", false); | |
| 648 | defer testing.allocator.free(partial); | |
| 649 | try testing.expectEqualStrings( | |
| 650 | "{\"transcript\":\"hello world\",\"isFinal\":false}", | |
| 651 | partial, | |
| 652 | ); | |
| 1071 | fn stopEngine(eng: Id) void { | |
| 1072 | const sel = objc.sel_registerName("stop") orelse return; | |
| 1073 | objc.msgSend(eng, sel); | |
| 1074 | } | |
| 653 | 1075 | |
| 654 | const final = try shapeResultDetail(testing.allocator, "hello world", true); | |
| 655 | defer testing.allocator.free(final); | |
| 656 | try testing.expectEqualStrings( | |
| 657 | "{\"transcript\":\"hello world\",\"isFinal\":true}", | |
| 658 | final, | |
| 1076 | fn endAudio(request: Id) void { | |
| 1077 | const sel = objc.sel_registerName("endAudio") orelse return; | |
| 1078 | objc.msgSend(request, sel); | |
| 1079 | } | |
| 1080 | ||
| 1081 | fn cancelTask(t: Id) void { | |
| 1082 | const sel = objc.sel_registerName("cancel") orelse return; | |
| 1083 | objc.msgSend(t, sel); | |
| 1084 | } | |
| 1085 | ||
| 1086 | fn resultIsFinal(result: Id) bool { | |
| 1087 | const sel = objc.sel_registerName("isFinal") orelse return false; | |
| 1088 | return objc.msgSendBool(result, sel); | |
| 1089 | } | |
| 1090 | ||
| 1091 | /// `result.bestTranscription.formattedString` -> one `craftSpeechResult`. | |
| 1092 | /// | |
| 1093 | /// Runs on Speech's internal queue. `ios_events.emit` hops to the main queue | |
| 1094 | /// itself, so nothing here needs to. | |
| 1095 | fn emitTranscript(result: Id, is_final: bool) void { | |
| 1096 | const sel_best = objc.sel_registerName("bestTranscription") orelse return; | |
| 1097 | const transcription = objc.msgSendId(result, sel_best) orelse return; | |
| 1098 | ||
| 1099 | const sel_formatted = objc.sel_registerName("formattedString") orelse return; | |
| 1100 | const string = objc.msgSendId(transcription, sel_formatted) orelse return; | |
| 1101 | ||
| 1102 | const utf8 = objc.getNSStringUTF8(string) orelse return; | |
| 1103 | const text = std.mem.span(utf8); | |
| 1104 | ||
| 1105 | const allocator = std.heap.c_allocator; | |
| 1106 | const detail = shapeResultDetail(allocator, text, is_final) catch { | |
| 1107 | std.log.warn("speech: could not shape a transcript for craftSpeechResult", .{}); | |
| 1108 | return; | |
| 1109 | }; | |
| 1110 | defer allocator.free(detail); | |
| 1111 | ||
| 1112 | ios_events.emit(event_result, detail); | |
| 1113 | } | |
| 1114 | ||
| 1115 | /// Read an `AVAudioSession` string constant out of the process. | |
| 1116 | /// | |
| 1117 | /// `dlsym` rather than an `extern` declaration, for the reason | |
| 1118 | /// `bridge_mobile_imagepicker.zig` documents: a host test binary links Cocoa | |
| 1119 | /// and not AVFoundation, and an `extern` would make the whole test executable | |
| 1120 | /// fail to link rather than this one call fail to find its symbol. | |
| 1121 | fn audioSessionConstant(comptime symbol: [*:0]const u8) Id { | |
| 1122 | const found = dlsym(RTLD_DEFAULT, symbol) orelse { | |
| 1123 | std.log.warn("startListening: {s} is not in this process", .{symbol}); | |
| 1124 | return null; | |
| 1125 | }; | |
| 1126 | const cell: *const Id = @ptrCast(@alignCast(found)); | |
| 1127 | return cell.*; | |
| 1128 | } | |
| 1129 | ||
| 1130 | fn logNSError(context: []const u8, err: Id) void { | |
| 1131 | const object = err orelse { | |
| 1132 | std.log.warn("{s}: the native call failed and reported no error", .{context}); | |
| 1133 | return; | |
| 1134 | }; | |
| 1135 | const sel = objc.sel_registerName("localizedDescription") orelse return; | |
| 1136 | const description = objc.msgSendId(object, sel) orelse return; | |
| 1137 | const utf8 = objc.getNSStringUTF8(description) orelse return; | |
| 1138 | std.log.warn("{s}: {s}", .{ context, std.mem.span(utf8) }); | |
| 1139 | } | |
| 1140 | ||
| 1141 | const dispatch_function_t = *const fn (?*anyopaque) callconv(.c) void; | |
| 1142 | extern "c" fn dispatch_async_f(queue: *anyopaque, context: ?*anyopaque, work: dispatch_function_t) void; | |
| 1143 | extern var _dispatch_main_q: anyopaque; | |
| 1144 | ||
| 1145 | extern "c" fn dlsym(handle: ?*anyopaque, symbol: [*:0]const u8) ?*anyopaque; | |
| 1146 | ||
| 1147 | extern "c" fn usleep(microseconds: c_uint) c_int; | |
| 1148 | ||
| 1149 | /// `RTLD_DEFAULT` — search every image already loaded into the process. | |
| 1150 | const RTLD_DEFAULT: ?*anyopaque = @ptrFromInt(@as(usize, @bitCast(@as(isize, -2)))); | |
| 1151 | ||
| 1152 | // ============================================================================= | |
| 1153 | // Tests. | |
| 1154 | // | |
| 1155 | // Three groups. The pure shapers and the vocabulary, whose bytes are what a | |
| 1156 | // page reads. The routing, which is what makes `ios_dispatch` reach this file | |
| 1157 | // at all. And the state machine — the parts of teardown and the tap handoff | |
| 1158 | // that can be exercised without an audio device, which is more of them than it | |
| 1159 | // looks, because the handoff is deliberately made of atomics rather than of | |
| 1160 | // framework state. | |
| 1161 | // | |
| 1162 | // What no test here can reach: the recognizer, the session, the engine, the | |
| 1163 | // tap itself. That risk surface belongs to `packages/ios/fixtures/zig-slice`, | |
| 1164 | // which drives both actions on a simulator and asserts the events. | |
| 1165 | // ============================================================================= | |
| 1166 | ||
| 1167 | const testing = std.testing; | |
| 1168 | ||
| 1169 | test "the action names match the Swift case labels exactly" { | |
| 1170 | // A typo here routes nowhere and looks exactly like the shim still serving | |
| 1171 | // both actions, which is the state this module just left. | |
| 1172 | try testing.expectEqualStrings("startListening", A.start_listening); | |
| 1173 | try testing.expectEqualStrings("stopListening", A.stop_listening); | |
| 1174 | } | |
| 1175 | ||
| 1176 | test "both actions are declared, and neither promises a reply" { | |
| 1177 | try testing.expectEqual(@as(usize, 2), capability_actions.len); | |
| 1178 | for (capability_actions) |decl| { | |
| 1179 | // `.result` would tell an app to await something no path here sends. | |
| 1180 | try testing.expectEqual(capabilities.Reply.none, decl.reply); | |
| 1181 | try testing.expectEqual(capabilities.ActionStatus.live, decl.status); | |
| 1182 | } | |
| 1183 | } | |
| 1184 | ||
| 1185 | test "an unrelated action falls through rather than being refused" { | |
| 1186 | // `ios_dispatch.route` treats any error other than UnknownAction as final, | |
| 1187 | // so a module that answered something else here would stop the chain and | |
| 1188 | // strand an action another module serves. | |
| 1189 | var bridge = SpeechBridge.init(testing.allocator); | |
| 1190 | defer bridge.deinit(); | |
| 1191 | try testing.expectError( | |
| 1192 | BridgeError.UnknownAction, | |
| 1193 | bridge.handleMessage("getDeviceInfo", "{}"), | |
| 659 | 1194 | ); |
| 1195 | } | |
| 660 | 1196 | |
| 661 | var parsed = try std.json.parseFromSlice(std.json.Value, testing.allocator, final, .{}); | |
| 662 | defer parsed.deinit(); | |
| 663 | try testing.expectEqual(@as(usize, 2), parsed.value.object.count()); | |
| 664 | try testing.expectEqualStrings("hello world", parsed.value.object.get("transcript").?.string); | |
| 665 | try testing.expectEqual(true, parsed.value.object.get("isFinal").?.bool); | |
| 1197 | test "a malformed payload is not a reason to refuse either action" { | |
| 1198 | // Neither action reads a field, so neither parses one. A parser here would | |
| 1199 | // invent a failure the spec has not got — and it would surface as a | |
| 1200 | // dispatcher error under a request id no page holds. | |
| 1201 | var bridge = SpeechBridge.init(testing.allocator); | |
| 1202 | defer bridge.deinit(); | |
| 1203 | ||
| 1204 | for ([_][]const u8{ "", "{", "not json at all", "[1,2,3]" }) |payload| { | |
| 1205 | try bridge.handleMessage(A.stop_listening, payload); | |
| 1206 | } | |
| 1207 | ||
| 1208 | // And the stop left no state behind, which is what makes it idempotent. | |
| 1209 | try testing.expect(!listening); | |
| 1210 | try testing.expect(!tap_installed); | |
| 1211 | try testing.expectEqual(@as(usize, 0), active_request.load(.seq_cst)); | |
| 666 | 1212 | } |
| 667 | 1213 | |
| 668 | test "the detail does not invent keys the recognizer could have supplied" { | |
| 669 | // `SFSpeechRecognitionResult` also carries `transcriptions`, | |
| 670 | // `bestTranscription.segments` and per-segment `confidence`, and Swift | |
| 671 | // reads none of them. Adding one would be a surface no consumer reads and | |
| 672 | // a divergence from the emitter contract this migration preserves. | |
| 673 | const json = try shapeResultDetail(testing.allocator, "x", true); | |
| 674 | defer testing.allocator.free(json); | |
| 1214 | test "the four error messages are Swift's, in Swift's order" { | |
| 1215 | try testing.expectEqual(@as(usize, 4), error_messages.len); | |
| 1216 | try testing.expectEqualStrings("Not authorized", error_messages[0]); | |
| 1217 | try testing.expectEqualStrings("Audio session failed", error_messages[1]); | |
| 1218 | try testing.expectEqualStrings("Speech recognizer unavailable", error_messages[2]); | |
| 1219 | try testing.expectEqualStrings("Audio engine failed", error_messages[3]); | |
| 1220 | ||
| 1221 | // And every StartFailure maps into that set, so no path can emit a fifth | |
| 1222 | // string by accident. | |
| 1223 | inline for (@typeInfo(StartFailure).error_set.error_names.?) |name| { | |
| 1224 | const message = messageFor(@field(StartFailure, name)); | |
| 1225 | var found = false; | |
| 1226 | for (error_messages) |known| { | |
| 1227 | if (std.mem.eql(u8, known, message)) found = true; | |
| 1228 | } | |
| 1229 | try testing.expect(found); | |
| 1230 | } | |
| 1231 | } | |
| 675 | 1232 | |
| 676 | try testing.expect(std.mem.indexOf(u8, json, "confidence") == null); | |
| 677 | try testing.expect(std.mem.indexOf(u8, json, "alternatives") == null); | |
| 678 | try testing.expect(std.mem.indexOf(u8, json, "segments") == null); | |
| 679 | try testing.expect(std.mem.indexOf(u8, json, "\"transcript\":") != null); | |
| 680 | try testing.expect(std.mem.indexOf(u8, json, "\"isFinal\":") != null); | |
| 1233 | test "a zero-format refusal reports the engine, not the session" { | |
| 1234 | // The one message this module emits that Swift never reaches. Picking | |
| 1235 | // `err_audio_session` would blame a session that succeeded; picking a | |
| 1236 | // fifth string would put bytes on a page no other arm can produce. | |
| 1237 | try testing.expectEqualStrings(err_audio_engine, messageFor(error.AudioEngine)); | |
| 1238 | try testing.expectEqualStrings(err_audio_session, messageFor(error.AudioSession)); | |
| 681 | 1239 | } |
| 682 | 1240 | |
| 683 | test "isFinal is a JSON boolean, never a quoted string" { | |
| 684 | // `${e.detail.isFinal}` renders `"false"` and `false` identically, so a | |
| 685 | // quoted value would read as correct on the test page while being truthy | |
| 686 | // to any code that branches on it. | |
| 687 | const json = try shapeResultDetail(testing.allocator, "", false); | |
| 688 | defer testing.allocator.free(json); | |
| 1241 | test "the four event names are the ones Swift's sendToWeb spells" { | |
| 1242 | try testing.expectEqualStrings("craftSpeechStart", event_start.eventName()); | |
| 1243 | try testing.expectEqualStrings("craftSpeechResult", event_result.eventName()); | |
| 1244 | try testing.expectEqualStrings("craftSpeechError", event_error.eventName()); | |
| 1245 | try testing.expectEqualStrings("craftSpeechEnd", event_end.eventName()); | |
| 1246 | } | |
| 689 | 1247 | |
| 690 | try testing.expect(std.mem.indexOf(u8, json, "\"isFinal\":false") != null); | |
| 691 | try testing.expect(std.mem.indexOf(u8, json, "\"false\"") == null); | |
| 1248 | test "the empty detail is an object a page can index into" { | |
| 1249 | // `ios_events.formatEvent` inlines this as a literal. An empty string | |
| 1250 | // would make `e.detail.anything` a TypeError rather than undefined. | |
| 1251 | try testing.expectEqualStrings("{}", empty_detail); | |
| 1252 | } | |
| 692 | 1253 | |
| 693 | var parsed = try std.json.parseFromSlice(std.json.Value, testing.allocator, json, .{}); | |
| 694 | defer parsed.deinit(); | |
| 695 | try testing.expectEqual(false, parsed.value.object.get("isFinal").?.bool); | |
| 1254 | test "an error detail carries the message under the key Swift uses" { | |
| 1255 | const detail = try shapeErrorDetail(testing.allocator, err_not_authorized); | |
| 1256 | defer testing.allocator.free(detail); | |
| 1257 | try testing.expectEqualStrings("{\"error\":\"Not authorized\"}", detail); | |
| 696 | 1258 | } |
| 697 | 1259 | |
| 698 | test "an empty transcript still emits the key" { | |
| 699 | // A first partial result can legitimately be empty. Omitting the key would | |
| 700 | // leave `e.detail.transcript` undefined, which a page cannot tell from a | |
| 701 | // bridge that stopped working. | |
| 702 | const json = try shapeResultDetail(testing.allocator, "", false); | |
| 703 | defer testing.allocator.free(json); | |
| 1260 | test "an error message with JavaScript metacharacters survives escaping" { | |
| 1261 | // No current message needs this. The escaping is a property of the | |
| 1262 | // position — a JSON string inlined into JavaScript source — so it is | |
| 1263 | // pinned against the message that has not been written yet. | |
| 1264 | const detail = try shapeErrorDetail(testing.allocator, "quote \" and \\ and\nnewline"); | |
| 1265 | defer testing.allocator.free(detail); | |
| 1266 | try testing.expectEqualStrings( | |
| 1267 | "{\"error\":\"quote \\\" and \\\\ and\\nnewline\"}", | |
| 1268 | detail, | |
| 1269 | ); | |
| 1270 | } | |
| 704 | 1271 | |
| 705 | try testing.expectEqualStrings("{\"transcript\":\"\",\"isFinal\":false}", json); | |
| 1272 | test "a transcript detail carries both keys, with isFinal as a real boolean" { | |
| 1273 | const partial = try shapeResultDetail(testing.allocator, "hello", false); | |
| 1274 | defer testing.allocator.free(partial); | |
| 1275 | try testing.expectEqualStrings( | |
| 1276 | "{\"transcript\":\"hello\",\"isFinal\":false}", | |
| 1277 | partial, | |
| 1278 | ); | |
| 706 | 1279 | |
| 707 | var parsed = try std.json.parseFromSlice(std.json.Value, testing.allocator, json, .{}); | |
| 708 | defer parsed.deinit(); | |
| 709 | try testing.expectEqual(@as(usize, 2), parsed.value.object.count()); | |
| 710 | try testing.expectEqualStrings("", parsed.value.object.get("transcript").?.string); | |
| 1280 | const final = try shapeResultDetail(testing.allocator, "hello there", true); | |
| 1281 | defer testing.allocator.free(final); | |
| 1282 | try testing.expectEqualStrings( | |
| 1283 | "{\"transcript\":\"hello there\",\"isFinal\":true}", | |
| 1284 | final, | |
| 1285 | ); | |
| 711 | 1286 | } |
| 712 | 1287 | |
| 713 | test "a transcript with a quote does not truncate the event" { | |
| 714 | // The failure this shaper exists to prevent, and the one | |
| 715 | // `ios_events.zig` records against `bridge_iap.zig:362`: the detail is | |
| 716 | // inlined into JavaScript source, so an unescaped `"` does not corrupt one | |
| 717 | // field, it ends the object early and makes the whole `dispatchEvent` call | |
| 718 | // a syntax error. The page sees the stream stop, not a bad transcript. | |
| 719 | // | |
| 720 | // Dictation really does produce these: it transcribes spoken quotation | |
| 721 | // marks, and `formattedString` is not sanitised. | |
| 722 | const json = try shapeResultDetail(testing.allocator, "she said \"hello\"", true); | |
| 723 | defer testing.allocator.free(json); | |
| 1288 | test "an empty transcript still emits the key" { | |
| 1289 | // A first partial result can legitimately be empty, and an omitted key | |
| 1290 | // reads to a page exactly like a broken bridge. | |
| 1291 | const detail = try shapeResultDetail(testing.allocator, "", false); | |
| 1292 | defer testing.allocator.free(detail); | |
| 1293 | try testing.expectEqualStrings("{\"transcript\":\"\",\"isFinal\":false}", detail); | |
| 1294 | } | |
| 724 | 1295 | |
| 1296 | test "a spoken quote cannot end the object early" { | |
| 1297 | // Arbitrary speech lands in a JavaScript source position. An unescaped | |
| 1298 | // quote would not corrupt one field: it would make the whole dispatchEvent | |
| 1299 | // call a syntax error, and the page would see the stream stop with no | |
| 1300 | // event to say why. | |
| 1301 | const detail = try shapeResultDetail(testing.allocator, "say \"stop\" now", true); | |
| 1302 | defer testing.allocator.free(detail); | |
| 725 | 1303 | try testing.expectEqualStrings( |
| 726 | "{\"transcript\":\"she said \\\"hello\\\"\",\"isFinal\":true}", | |
| 727 | json, | |
| 1304 | "{\"transcript\":\"say \\\"stop\\\" now\",\"isFinal\":true}", | |
| 1305 | detail, | |
| 728 | 1306 | ); |
| 729 | 1307 | |
| 730 | var parsed = try std.json.parseFromSlice(std.json.Value, testing.allocator, json, .{}); | |
| 1308 | // And the result is parseable, which is the property the escaping exists | |
| 1309 | // for rather than the exact bytes. | |
| 1310 | const parsed = try std.json.parseFromSlice(std.json.Value, testing.allocator, detail, .{}); | |
| 731 | 1311 | defer parsed.deinit(); |
| 732 | 1312 | try testing.expectEqualStrings( |
| 733 | "she said \"hello\"", | |
| 1313 | "say \"stop\" now", | |
| 734 | 1314 | parsed.value.object.get("transcript").?.string, |
| 735 | 1315 | ); |
| 1316 | try testing.expectEqual(true, parsed.value.object.get("isFinal").?.bool); | |
| 736 | 1317 | } |
| 737 | 1318 | |
| 738 | test "backslashes, newlines and control bytes survive as escapes" { | |
| 739 | // A literal newline inside a JavaScript string literal is a syntax error, | |
| 740 | // and a lone backslash would escape whatever followed it. Both reach the | |
| 741 | // page as a dead event rather than as bad text. | |
| 742 | const json = try shapeResultDetail(testing.allocator, "a\\b\nc\td\r\x01", false); | |
| 743 | defer testing.allocator.free(json); | |
| 1319 | test "the tap reads nothing while the request is unpublished" { | |
| 1320 | // The handoff, exercised without an audio device. Zero means "nobody may | |
| 1321 | // append", and it is the state both before a start and after a stop — | |
| 1322 | // which is what makes a tap call that outlives its session harmless | |
| 1323 | // rather than a use-after-free. | |
| 1324 | const saved = active_request.swap(0, .seq_cst); | |
| 1325 | defer active_request.store(saved, .seq_cst); | |
| 744 | 1326 | |
| 745 | try testing.expectEqualStrings( | |
| 746 | "{\"transcript\":\"a\\\\b\\nc\\td\\r\\u0001\",\"isFinal\":false}", | |
| 747 | json, | |
| 748 | ); | |
| 1327 | try testing.expectEqual(@as(usize, 0), active_request.load(.seq_cst)); | |
| 749 | 1328 | |
| 750 | // No raw control byte survived into the bytes that become JS source. | |
| 751 | for (json) |c| try testing.expect(c >= 0x20); | |
| 1329 | // The tap's own guard, spelled the way the tap spells it. | |
| 1330 | try testing.expect(active_request.load(.seq_cst) == 0); | |
| 1331 | } | |
| 752 | 1332 | |
| 753 | var parsed = try std.json.parseFromSlice(std.json.Value, testing.allocator, json, .{}); | |
| 754 | defer parsed.deinit(); | |
| 755 | try testing.expectEqualStrings("a\\b\nc\td\r\x01", parsed.value.object.get("transcript").?.string); | |
| 1333 | test "the drain reports success only when the audio thread has left" { | |
| 1334 | // `drainTap` is what stands between a stop and a use-after-free, so its | |
| 1335 | // two answers are pinned rather than assumed. The busy case deliberately | |
| 1336 | // runs the full bounded wait: 20ms is the cost of proving it gives up | |
| 1337 | // instead of spinning forever. | |
| 1338 | tap_in_flight.store(0, .seq_cst); | |
| 1339 | try testing.expect(drainTap()); | |
| 1340 | ||
| 1341 | tap_in_flight.store(1, .seq_cst); | |
| 1342 | try testing.expect(!drainTap()); | |
| 1343 | ||
| 1344 | tap_in_flight.store(0, .seq_cst); | |
| 756 | 1345 | } |
| 757 | 1346 | |
| 758 | test "an apostrophe passes through unescaped, and must" { | |
| 759 | // The opposite error, and an easy one to make while fixing the quote case. | |
| 760 | // `formatEvent` single-quotes the event *name* only; the detail is an | |
| 761 | // object literal, where `'` is an ordinary character inside a | |
| 762 | // double-quoted JSON string. Escaping it would put a literal backslash | |
| 763 | // into the transcript the page displays — and "don't" and "it's" are the | |
| 764 | // most common words dictation produces. | |
| 765 | const json = try shapeResultDetail(testing.allocator, "don't stop", true); | |
| 766 | defer testing.allocator.free(json); | |
| 1347 | test "the native constants are the SDK's, not remembered" { | |
| 1348 | // Every one of these was read out of a header rather than recalled, after | |
| 1349 | // a HealthKit option guessed at 1 << 2 turned out to be 1 << 4 and took | |
| 1350 | // the process down with an unrecoverable exception inside the framework. | |
| 1351 | // | |
| 1352 | // SFSpeechRecognizer.h:25-41 implicit 0..3, Authorized last | |
| 1353 | // AVAudioSessionTypes.h:466 DuckOthers = 0x2 | |
| 1354 | // AVAudioSessionTypes.h:660 NotifyOthersOnDeactivation = 1 | |
| 1355 | // AVAudioNode.h:110 bufferSize 1024 in the header's own example | |
| 1356 | try testing.expectEqual(@as(isize, 3), status_authorized); | |
| 1357 | try testing.expectEqual(@as(c_ulong, 2), category_option_duck_others); | |
| 1358 | try testing.expectEqual(@as(c_ulong, 1), set_active_notify_others); | |
| 1359 | try testing.expectEqual(@as(u32, 1024), tap_buffer_frames); | |
| 1360 | try testing.expectEqual(@as(c_ulong, 0), bus_zero); | |
| 1361 | ||
| 1362 | // DuckOthers is 0x2 and MixWithOthers is 0x1; picking the neighbour would | |
| 1363 | // silently stop ducking rather than fail. | |
| 1364 | try testing.expect(category_option_duck_others != 1); | |
| 1365 | } | |
| 767 | 1366 | |
| 768 | try testing.expectEqualStrings("{\"transcript\":\"don't stop\",\"isFinal\":true}", json); | |
| 769 | try testing.expect(std.mem.indexOfScalar(u8, json, '\\') == null); | |
| 1367 | test "the plist key is the exact proxy, and the microphone key is not" { | |
| 1368 | // `index.ts:183` writes this key from `enableSpeechRecognition` alone. | |
| 1369 | // `:184` writes NSMicrophoneUsageDescription from | |
| 1370 | // `enableSpeechRecognition || enableAudioRecording`, so it is implied by | |
| 1371 | // speech being on but cannot stand in for it — an audio-recording app | |
| 1372 | // would carry it with speech off. | |
| 1373 | try testing.expectEqualStrings("NSSpeechRecognitionUsageDescription", key_speech_usage); | |
| 1374 | } | |
| 770 | 1375 | |
| 771 | var parsed = try std.json.parseFromSlice(std.json.Value, testing.allocator, json, .{}); | |
| 772 | defer parsed.deinit(); | |
| 773 | try testing.expectEqualStrings("don't stop", parsed.value.object.get("transcript").?.string); | |
| 1376 | test "a test runner has no speech usage description, so a start refuses" { | |
| 1377 | // The shape of an app built with enableSpeechRecognition off, which is | |
| 1378 | // what a test binary's bundle looks like. The refusal has to come from the | |
| 1379 | // plist guard, before requestAuthorization: is reached — asking without | |
| 1380 | // the key terminates the process rather than failing. | |
| 1381 | if (!is_darwin) return error.SkipZigTest; | |
| 1382 | ||
| 1383 | try testing.expect(!hasSpeechUsageDescription()); | |
| 1384 | ||
| 1385 | var bridge = SpeechBridge.init(testing.allocator); | |
| 1386 | defer bridge.deinit(); | |
| 1387 | try bridge.handleMessage(A.start_listening, "{}"); | |
| 1388 | ||
| 1389 | // Nothing was built and no authorization request is outstanding. | |
| 1390 | try testing.expect(!starting); | |
| 1391 | try testing.expect(!listening); | |
| 1392 | try testing.expect(recognizer == null); | |
| 1393 | try testing.expect(engine == null); | |
| 1394 | try testing.expectEqual(@as(usize, 0), active_request.load(.seq_cst)); | |
| 774 | 1395 | } |
| 775 | 1396 | |
| 776 | test "multi-byte UTF-8 is carried through unchanged" { | |
| 777 | // `formattedString` is whatever locale the recognizer was built with, and | |
| 778 | // even `en-US` produces curly apostrophes and em dashes. Escaping per byte | |
| 779 | // rather than per code point would split a sequence and hand the page | |
| 780 | // invalid JSON. | |
| 781 | const spoken = "café — naïve 日本語"; | |
| 782 | const json = try shapeResultDetail(testing.allocator, spoken, true); | |
| 783 | defer testing.allocator.free(json); | |
| 1397 | test "stopping something that never started is safe, and still ends" { | |
| 1398 | // Swift's stopSpeechRecognition() has no early return and no guard: a page | |
| 1399 | // that stops twice gets two ends, and one that never started still gets | |
| 1400 | // one. Bug-compatible on purpose — the event is what a listening indicator | |
| 1401 | // binds to, and an end that does not arrive leaves it stuck on. | |
| 1402 | var bridge = SpeechBridge.init(testing.allocator); | |
| 1403 | defer bridge.deinit(); | |
| 1404 | ||
| 1405 | try bridge.handleMessage(A.stop_listening, "{}"); | |
| 1406 | try bridge.handleMessage(A.stop_listening, "{}"); | |
| 784 | 1407 | |
| 785 | var parsed = try std.json.parseFromSlice(std.json.Value, testing.allocator, json, .{}); | |
| 786 | defer parsed.deinit(); | |
| 787 | try testing.expectEqualStrings(spoken, parsed.value.object.get("transcript").?.string); | |
| 788 | try testing.expect(std.unicode.utf8ValidateSlice(json)); | |
| 789 | } | |
| 790 | ||
| 791 | test "a shaped detail is a complete JSON value, which is what emit requires" { | |
| 792 | // `ios_events.emit` documents its argument as a complete JSON value and | |
| 793 | // inlines it verbatim. A shaper returning a fragment, or leaving a | |
| 794 | // trailing comma, would produce a `dispatchEvent` call the page cannot | |
| 795 | // parse — an event that silently never arrives. | |
| 796 | const details = [_][]u8{ | |
| 797 | try shapeResultDetail(testing.allocator, "one", false), | |
| 798 | try shapeResultDetail(testing.allocator, "", true), | |
| 799 | try shapeErrorDetail(testing.allocator, err_audio_engine), | |
| 800 | }; | |
| 801 | defer for (details) |d| testing.allocator.free(d); | |
| 802 | ||
| 803 | for (details) |detail| { | |
| 804 | try testing.expect(std.mem.startsWith(u8, detail, "{")); | |
| 805 | try testing.expect(std.mem.endsWith(u8, detail, "}")); | |
| 806 | var parsed = try std.json.parseFromSlice(std.json.Value, testing.allocator, detail, .{}); | |
| 807 | defer parsed.deinit(); | |
| 808 | try testing.expect(parsed.value == .object); | |
| 809 | } | |
| 1408 | try testing.expect(!listening); | |
| 1409 | try testing.expect(!tap_installed); | |
| 1410 | try testing.expect(task == null); | |
| 1411 | try testing.expectEqual(@as(usize, 0), active_request.load(.seq_cst)); | |
| 810 | 1412 | } |