use built-in LSP ResponseError with code RequestFailed for errors

Author: matthewbastien

Contributor Documentation/LSP Extensions.md

@@ -185,75 +185,25 @@ capabilities.
 
 ```ts
 export interface DoccDocumentationParams {
-    /**
-     * The document to render documentation for.
-     */
-    textDocument: TextDocumentIdentifier;
-
-    /**
-     * The document location at which to lookup symbol information.
-     * 
-     * This parameter is only used in Swift files to determine which symbol to render.
-     * The position is ignored for markdown and tutorial documents.
-     */
-    position: Position;
-}
-
-export type DoccDocumentationResponse = RenderNodeResponse | ErrorResponse;
-
-interface RenderNodeResponse {
-  /**
-   * The type of this response: either a RenderNode or error.
-   */
-  type: "renderNode";
-
-  /**
-   * The JSON encoded RenderNode that can be rendered by swift-docc-render.
-   */
-  renderNode: string;
-}
-
-interface ErrorResponse {
-  /**
-   * The type of this response: either a RenderNode or error.
-   */
-  type: "error";
-
   /**
-   * The error that occurred.
+   * The document to render documentation for.
    */
-  error: DoccDocumentationError;
-}
-
-export type DoccDocumentationError = ErrorWithNoParams | SymbolNotFoundError;
-
-interface ErrorWithNoParams {
-  /**
-   * The kind of error that occurred.
-   */
-  kind: "indexNotAvailable" | "noDocumentation";
+  textDocument: TextDocumentIdentifier;
 
   /**
-   * A human readable error message that can be shown to the user.
+   * The document location at which to lookup symbol information.
+   * 
+   * This parameter is only used in Swift files to determine which symbol to render.
+   * The position is ignored for markdown and tutorial documents.
    */
-  message: string;
+  position?: Position;
 }
 
-interface SymbolNotFoundError {
+export interface DoccDocumentationResponse {
   /**
-   * The kind of error that occurred.
-   */
-  kind: "symbolNotFound";
-
-  /**
-   * The name of the symbol that could not be found.
-   */
-  symbolName: string;
-
-  /**
-   * A human readable error message that can be shown to the user.
+   * The JSON encoded RenderNode that can be rendered by swift-docc-render.
    */
-  message: string;
+  renderNode: string;
 }
 ```
 

Sources/LanguageServerProtocol/Error.swift

@@ -124,6 +124,10 @@ extension ResponseError {
     return ResponseError(code: .unknownErrorCode, message: message)
   }
 
+  public static func requestFailed(_ message: String) -> ResponseError {
+    return ResponseError(code: .requestFailed, message: message)
+  }
+
   public static func internalError(_ message: String) -> ResponseError {
     return ResponseError(code: .internalError, message: message)
   }

Sources/LanguageServerProtocol/Requests/DoccDocumentationRequest.swift

@@ -44,105 +44,10 @@ public struct DoccDocumentationRequest: TextDocumentRequest, Hashable {
   }
 }
 
-public enum DoccDocumentationResponse: ResponseType {
-  case renderNode(String)
-  case error(DoccDocumentationError)
-}
-
-public enum DoccDocumentationError: ResponseType, Equatable {
-  case indexNotAvailable
-  case noDocumentation
-  case symbolNotFound(String)
-
-  var message: String {
-    switch self {
-    case .indexNotAvailable:
-      return "The index is not availble to complete the request"
-    case .noDocumentation:
-      return "No documentation could be rendered for the position in this document"
-    case .symbolNotFound(let symbolName):
-      return "Could not find symbol \(symbolName) in the project"
-    }
-  }
-}
-
-extension DoccDocumentationError: Codable {
-  enum CodingKeys: String, CodingKey {
-    case kind
-    case message
-    case symbolName
-  }
-
-  public init(from decoder: Decoder) throws {
-    let values = try decoder.container(keyedBy: CodingKeys.self)
-    let kind = try values.decode(String.self, forKey: .kind)
-    switch kind {
-    case "indexNotAvailable":
-      self = .indexNotAvailable
-    case "noDocumentation":
-      self = .noDocumentation
-    case "symbolNotFound":
-      let symbolName = try values.decode(String.self, forKey: .symbolName)
-      self = .symbolNotFound(symbolName)
-    default:
-      throw DecodingError.dataCorruptedError(
-        forKey: CodingKeys.kind,
-        in: values,
-        debugDescription: "Invalid error kind: \(kind)"
-      )
-    }
-  }
-
-  public func encode(to encoder: any Encoder) throws {
-    var container = encoder.container(keyedBy: CodingKeys.self)
-    switch self {
-    case .indexNotAvailable:
-      try container.encode("indexNotAvailable", forKey: .kind)
-    case .noDocumentation:
-      try container.encode("noDocumentation", forKey: .kind)
-    case .symbolNotFound(let symbolName):
-      try container.encode("symbolNotFound", forKey: .kind)
-      try container.encode(symbolName, forKey: .symbolName)
-    }
-    try container.encode(message, forKey: .message)
-  }
-}
-
-extension DoccDocumentationResponse: Codable {
-  enum CodingKeys: String, CodingKey {
-    case type
-    case renderNode
-    case error
-  }
-
-  public init(from decoder: Decoder) throws {
-    let values = try decoder.container(keyedBy: CodingKeys.self)
-    let type = try values.decode(String.self, forKey: .type)
-    switch type {
-    case "renderNode":
-      let renderNode = try values.decode(String.self, forKey: .renderNode)
-      self = .renderNode(renderNode)
-    case "error":
-      let error = try values.decode(DoccDocumentationError.self, forKey: .error)
-      self = .error(error)
-    default:
-      throw DecodingError.dataCorruptedError(
-        forKey: CodingKeys.type,
-        in: values,
-        debugDescription: "Invalid type: \(type)"
-      )
-    }
-  }
+public struct DoccDocumentationResponse: ResponseType {
+  public var renderNode: String
 
-  public func encode(to encoder: any Encoder) throws {
-    var container = encoder.container(keyedBy: CodingKeys.self)
-    switch self {
-    case .renderNode(let renderNode):
-      try container.encode("renderNode", forKey: .type)
-      try container.encode(renderNode, forKey: .renderNode)
-    case .error(let error):
-      try container.encode("error", forKey: .type)
-      try container.encode(error, forKey: .error)
-    }
+  public init(renderNode: String) {
+    self.renderNode = renderNode
   }
 }

Sources/SKTestSupport/TestSourceKitLSPClient.swift

@@ -237,17 +237,21 @@ package final class TestSourceKitLSPClient: MessageHandler, Sendable {
 
   // MARK: - Sending messages
 
-  /// Send the request to `server` and return the request result.
-  package func send<R: RequestType>(_ request: R) async throws -> R.Response {
-    return try await withCheckedThrowingContinuation { continuation in
+  package func sendWithRawResponse<R: RequestType>(_ request: R) async -> Result<R.Response, ResponseError> {
+    await withCheckedContinuation { continuation in
       self.send(request) { result in
-        continuation.resume(with: result)
+        continuation.resume(returning: result)
       }
     }
   }
 
+  /// Send the request to `server` and return the request result.
+  package func send<R: RequestType>(_ request: R) async throws(ResponseError) -> R.Response {
+    return try await sendWithRawResponse(request).get()
+  }
+
   /// Variant of `send` above that allows the response to be discarded if it is a `VoidResponse`.
-  package func send<R: RequestType>(_ request: R) async throws where R.Response == VoidResponse {
+  package func send<R: RequestType>(_ request: R) async throws(ResponseError) where R.Response == VoidResponse {
     let _: VoidResponse = try await self.send(request)
   }
 

Sources/SourceKitLSP/Documentation/DocumentationManager.swift

@@ -70,7 +70,7 @@ package final actor DocumentationManager {
           at: snapshot.absolutePosition(of: position)
         )
       else {
-        return .error(.noDocumentation)
+        throw ResponseError.requestFailed(.noDocumentation)
       }
       // Retrieve the symbol graph as well as information about the symbol
       let symbolPosition = await swiftLanguageService.adjustPositionToStartOfIdentifier(
@@ -96,7 +96,7 @@ package final actor DocumentationManager {
       symbolGraphs.append(rawSymbolGraph)
       overridingDocumentationComments[symbolUSR] = nearestDocumentableSymbol.documentationComments
     default:
-      return .error(.noDocumentation)
+      throw ResponseError.requestFailed(.noDocumentation)
     }
     // Send the convert request to SwiftDocC and wait for the response
     return try await withCheckedThrowingContinuation { continuation in
@@ -124,7 +124,7 @@ package final actor DocumentationManager {
             continuation.resume(throwing: ResponseError.internalError("Failed to encode render node from SwiftDocC"))
             return
           }
-          continuation.resume(returning: .renderNode(renderNode))
+          continuation.resume(returning: DoccDocumentationResponse(renderNode: renderNode))
         case .failure(let serverError):
           continuation.resume(throwing: serverError)
         }
@@ -133,6 +133,29 @@ package final actor DocumentationManager {
   }
 }
 
+package enum ConvertDocumentationError {
+  case indexNotAvailable
+  case noDocumentation
+  case symbolNotFound(String)
+
+  public var message: String {
+    switch self {
+    case .indexNotAvailable:
+      return "The index is not availble to complete the request"
+    case .noDocumentation:
+      return "No documentation could be rendered for the position in this document"
+    case .symbolNotFound(let symbolName):
+      return "Could not find symbol \(symbolName) in the project"
+    }
+  }
+}
+
+fileprivate extension ResponseError {
+  static func requestFailed(_ error: ConvertDocumentationError) -> ResponseError {
+    return ResponseError(code: .requestFailed, message: error.message)
+  }
+}
+
 fileprivate final class DocumentableSymbolFinder: SyntaxAnyVisitor {
   struct Symbol {
     let position: AbsolutePosition

Tests/SourceKitLSPTests/DoccDocumentationTests.swift

@@ -469,7 +469,7 @@ final class DoccDocumentationTests: XCTestCase {
 
 fileprivate enum PartialConvertResponse {
   case renderNode(kind: RenderNode.Kind, path: String? = nil, containing: String? = nil)
-  case error(DoccDocumentationError)
+  case error(ConvertDocumentationError)
 }
 
 fileprivate func renderDocumentation(
@@ -510,24 +510,15 @@ fileprivate func renderDocumentation(
   }
 
   for (index, marker) in positions.allMarkers.enumerated() {
-    let response: DoccDocumentationResponse
-    do {
-      response = try await testClient.send(
-        DoccDocumentationRequest(
-          textDocument: TextDocumentIdentifier(uri),
-          position: positions[marker]
-        )
-      )
-    } catch {
-      XCTFail(
-        "textDocument/doccDocumentation failed at position \(marker): \(error.localizedDescription)",
-        file: file,
-        line: line
+    let response = await testClient.sendWithRawResponse(
+      DoccDocumentationRequest(
+        textDocument: TextDocumentIdentifier(uri),
+        position: positions[marker]
       )
-      return
-    }
+    )
     switch response {
-    case .renderNode(let renderNodeString):
+    case .success(let response):
+      let renderNodeString = response.renderNode
       guard let renderNodeData = renderNodeString.data(using: .utf8),
         let renderNode = try? JSONDecoder().decode(RenderNode.self, from: renderNodeData)
       else {
@@ -562,36 +553,36 @@ fileprivate func renderDocumentation(
         }
       case .error(let error):
         XCTFail(
-          "expected error \(error.rawValue), but received a render node at position \(marker)",
+          "expected error \(error.message), but received a render node at position \(marker)",
           file: file,
           line: line
         )
       }
-    case .error(let error):
+    case .failure(let error):
       switch expectedResponses[index] {
       case .renderNode:
         XCTFail(
-          "expected a render node, but received an error \(error.rawValue) at position \(marker)",
+          "textDocument/doccDocumentation failed at position \(marker): \(error.localizedDescription)",
           file: file,
           line: line
         )
       case .error(let expectedError):
-        XCTAssertEqual(error, expectedError, file: file, line: line)
+        XCTAssertEqual(
+          error.code,
+          .requestFailed,
+          "expected a responseFailed error code at position \(marker)",
+          file: file,
+          line: line
+        )
+        XCTAssertEqual(
+          error.message,
+          expectedError.message,
+          "expected an error with message \(expectedError.message) at position \(marker)",
+          file: file,
+          line: line
+        )
       }
     }
   }
 }
-
-fileprivate extension DoccDocumentationError {
-  var rawValue: String {
-    switch self {
-    case .indexNotAvailable:
-      return "indexNotAvailable"
-    case .noDocumentation:
-      return "noDocumentation"
-    case .symbolNotFound:
-      return "symbolNotFound"
-    }
-  }
-}
 #endif