Add a logging option to record all notifications received by SoruceKit-LSP

This allows us to record the communication between SourceKit-LSP and the editor on a very low level to inspect any transfer issues. It also allows us to record an entire SourceKit-LSP session and replay it using

```
cat /path/to/mirror.log - | path/to/sourcekit-lsp
```

Author: ahoppen

Documentation/Configuration File.md

@@ -42,6 +42,7 @@ The structure of the file is currently not guaranteed to be stable. Options may
 - `logging`: Dictionary with the following keys, changing SourceKit-LSP’s logging behavior on non-Apple platforms. On Apple platforms, logging is done through the [system log](Diagnose%20Bundle.md#Enable%20Extended%20Logging). These options can only be set globally and not per workspace.
   - `logLevel: "debug"|"info"|"default"|"error"|"fault"`: The level from which one onwards log messages should be written.
   - `privacyLevel: "public"|"private"|"sensitive"`: Whether potentially sensitive information should be redacted. Default is `public`, which redacts potentially sensitive information.
+  - `inputMirrorDirectory: string`: Write all input received by SourceKit-LSP on stdin to a file in this directory. Useful to record and replay an entire SourceKit-LSP session.
 - `defaultWorkspaceType: "buildserver"|"compdb"|"swiftpm"`: Overrides workspace type selection logic.
 - `generatedFilesPath: string`: Directory in which generated interfaces and macro expansions should be stored.
 - `backgroundIndexing: bool`: Explicitly enable or disable background indexing.

Package.swift

@@ -281,6 +281,7 @@ var targets: [Target] = [
   .testTarget(
     name: "SKSupportTests",
     dependencies: [
+      "SKLogging",
       "SKSupport",
       "SKTestSupport",
       "SwiftExtensions",

Sources/LanguageServerProtocolJSONRPC/JSONRPCConnection.swift

@@ -265,9 +265,15 @@ public final class JSONRPCConnection: Connection {
   /// Start processing `inFD` and send messages to `receiveHandler`.
   ///
   /// - parameter receiveHandler: The message handler to invoke for requests received on the `inFD`.
+  /// - parameter mirrorFile: If non-nil, all input received by this `JSONRPCConnection` will be written to the file
+  ///   handle
   ///
   /// - Important: `start` must be called before sending any data over the `JSONRPCConnection`.
-  public func start(receiveHandler: MessageHandler, closeHandler: @escaping @Sendable () async -> Void = {}) {
+  public func start(
+    receiveHandler: MessageHandler,
+    mirrorFile: FileHandle? = nil,
+    closeHandler: @escaping @Sendable () async -> Void = {}
+  ) {
     queue.sync {
       precondition(state == .created)
       state = .running
@@ -294,6 +300,10 @@ public final class JSONRPCConnection: Connection {
           return
         }
 
+        orLog("Writing data mirror file") {
+          try mirrorFile?.write(contentsOf: data)
+        }
+
         // Parse and handle any messages in `buffer + data`, leaving any remaining unparsed bytes in `buffer`.
         if self.requestBuffer.isEmpty {
           data.withUnsafeBytes { (pointer: UnsafePointer<UInt8>) in

Sources/SKOptions/SourceKitLSPOptions.swift

@@ -200,21 +200,30 @@ public struct SourceKitLSPOptions: Sendable, Codable, Equatable {
   public struct LoggingOptions: Sendable, Codable, Equatable {
     /// The level from which one onwards log messages should be written.
     public var level: String?
+
     /// Whether potentially sensitive information should be redacted.
     public var privacyLevel: String?
 
+    /// Write all input received by SourceKit-LSP on stdin to a file in this directory.
+    ///
+    /// Useful to record and replay an entire SourceKit-LSP session.
+    public var inputMirrorDirectory: String?
+
     public init(
       level: String? = nil,
-      privacyLevel: String? = nil
+      privacyLevel: String? = nil,
+      inputMirrorDirectory: String? = nil
     ) {
       self.level = level
       self.privacyLevel = privacyLevel
+      self.inputMirrorDirectory = inputMirrorDirectory
     }
 
     static func merging(base: LoggingOptions, override: LoggingOptions?) -> LoggingOptions {
       return LoggingOptions(
         level: override?.level ?? base.level,
-        privacyLevel: override?.privacyLevel ?? base.privacyLevel
+        privacyLevel: override?.privacyLevel ?? base.privacyLevel,
+        inputMirrorDirectory: override?.inputMirrorDirectory ?? base.inputMirrorDirectory
       )
     }
   }

Sources/sourcekit-lsp/SourceKitLSP.swift

@@ -331,6 +331,24 @@ struct SourceKitLSP: AsyncParsableCommand {
 
     let installPath = try AbsolutePath(validating: Bundle.main.bundlePath)
 
+    var inputMirror: FileHandle? = nil
+    if let inputMirrorDirectory = globalConfigurationOptions.loggingOrDefault.inputMirrorDirectory {
+      orLog("Setting up input mirror") {
+        let dateFormatter = ISO8601DateFormatter()
+        dateFormatter.timeZone = NSTimeZone.local
+        let date = dateFormatter.string(from: Date()).replacingOccurrences(of: ":", with: "-")
+
+        let inputMirrorDirectory = URL(fileURLWithPath: inputMirrorDirectory)
+        let inputMirrorURL = inputMirrorDirectory.appendingPathComponent("\(date).log")
+
+        logger.log("Mirroring input to \(inputMirrorURL)")
+        try FileManager.default.createDirectory(at: inputMirrorDirectory, withIntermediateDirectories: true)
+        FileManager.default.createFile(atPath: try inputMirrorURL.filePath, contents: nil)
+
+        inputMirror = try FileHandle(forWritingTo: inputMirrorURL)
+      }
+    }
+
     let server = SourceKitLSPServer(
       client: clientConnection,
       toolchainRegistry: ToolchainRegistry(installPath: installPath, localFileSystem),
@@ -342,6 +360,7 @@ struct SourceKitLSP: AsyncParsableCommand {
     )
     clientConnection.start(
       receiveHandler: server,
+      mirrorFile: inputMirror,
       closeHandler: {
         await server.prepareForExit()
         // Use _Exit to avoid running static destructors due to https://github.com/swiftlang/swift/issues/55112.