Error Handling Strategies
Relevant source files
The following files were used as context for generating this wiki page:
Error handling in the kilde project focuses on early environment validation, synchronized asynchronous task management, and graceful termination during media recording. The system prioritizes descriptive error messages and immediate process termination via a centralized failure utility to prevent inconsistent states.
Sources: Sources/Spike/Util.swift:9-16, Sources/Spike/Doctor.swift:7-12
Centralized Error Handling Utilities
The project defines a standard error structure and a global failure function to ensure consistent reporting across CLI commands.
SpikeError: A custom error struct that implementsCustomStringConvertibleto provide descriptive error messages.fail(_:): A utility function that writes a message to standard error and terminates the process with exit code 2.
struct SpikeError: Error, CustomStringConvertible {
let description: String
init(_ msg: String) { description = msg }
}
func fail(_ msg: String) -> Never {
FileHandle.standardError.write("ERROR: \(msg)\n".data(using: .utf8)!)
exit(2)
}
Sources: Sources/Spike/Util.swift:9-16
Environment and Permission Validation
Before execution, the Doctor module and specific commands validate system permissions and hardware availability. This prevents runtime crashes due to restricted access to ScreenCaptureKit or CoreAudio.
Validation Flow
The following diagram illustrates the sequence of permission checks performed during the doctor command:
The system checks CGPreflightScreenCaptureAccess() for screen recording and uses AVCaptureDevice.authorizationStatus(for: .audio) for microphone access. If permissions are missing, the application attempts to trigger system dialogs or instructs the user to update system settings.
Sources: Sources/Spike/Doctor.swift:7-40, Sources/Spike/MicCapture.swift:50-67
Synchronous Await for Asynchronous Tasks
Since many macOS APIs (like AVAssetWriter and SCStream) are asynchronous, the project utilizes a bridge function awaitSync to block the current thread until the task completes or fails. This ensures that command-line execution remains linear and predictable.
Sources: Sources/Spike/Util.swift:22-37
Media Recording and Finalization Errors
The recording session management in MovieWriter and runRecordingSession handles errors related to hardware disconnection, invalid sample timing, and file writing failures.
Error Scenarios in Media Processing
| Component | Error Condition | Handling Strategy |
|---|---|---|
| MovieWriter | Missing video size during init | Throws SpikeError immediately. |
| SCStream | Output registration failure | Calls fail() to terminate the process. |
| AVAssetWriter | Status != .completed at finish | Throws SpikeError with underlying OS error. |
| AggregateDevice | Creation failure | Throws SpikeError with OSStatus. |
Sources: Sources/Spike/MovieWriter.swift:34-36, Sources/Spike/MovieWriter.swift:115-118, Sources/Spike/SckCapture.swift:23-25, Sources/Spike/AggregateDevice.swift:26-28
Graceful Signal Interruption
The system installs signal handlers for SIGINT (Ctrl+C) and SIGTERM. When a signal is received, the recording session triggers a controlled shutdown instead of a hard crash. This allows the MovieWriter to finalize the file container, ensuring the output file is playable even if the user stops the recording prematurely.
Sources: Sources/Spike/Util.swift:60-72, Sources/Spike/RecSystemCmd.swift:45-52
Summary
Kilde's error handling strategy relies on proactive diagnostics (Doctor), aggressive termination for critical configuration failures (fail), and robust synchronization (awaitSync). By managing signals and validating permissions upfront, the system ensures that media resources are handled safely and errors are reported clearly to the CLI user.