Make Packet Equatable, refactor, add test, expand documentation

Author: flowtoolz

README.md

@@ -4,17 +4,83 @@
 
 ## What?
 
-SwiftLSP employs a quite dynamic Swift representation of the [LSP (Language Server Protocol)](https://microsoft.github.io/language-server-protocol) and helps with:
+SwiftLSP offers a quite dynamic Swift representation of the [LSP (Language Server Protocol)](https://microsoft.github.io/language-server-protocol) and helps with many related use cases. It is foundational for [LSPService](https://github.com/codeface-io/LSPService) and [LSPServiceKit](https://github.com/codeface-io/LSPServiceKit).
+
+Since the LSP standard defines a complex amorphous multitude of valid JSON objects, it doesn't exactly lend itself to being represented as a strict type system that would mirror the standard down to every permutation and property. So SwiftLSP is strictly typed at the higher level of LSP messages but falls back onto a more dynamic and flexible JSON representation for the details. The strict typing can easily be expanded on client demand.
+
+## Code Examples
+
+Some of these examples build upon preceding ones, so it's best to read them from the beginning.
+
+### Create Messages
+
+```swift
+let myRequest = LSP.Request(method: "myMethod", params: nil)
+let myRequestMessage = LSP.Message.request(myRequest)
+
+let myNotification = LSP.Notification(method: "myMethod", params: nil)
+let myNotificationMessage = LSP.Message.notification(myNotification)
+```
+
+### Encode and Decode Messages
+
+SwiftLSP encodes LSP messages with the [LSP-conform JSON-RPC encoding](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#abstractMessage).
+
+```swift
+let myRequestMessageEncoded = try myRequestMessage.encode()  // Data
+let myRequestMessageDecoded = try LSP.Message(myRequestMessageEncoded)
+```
+
+### Wrap Messages in Packets
+
+To send LSP messages via data channels, the standard defines how to [wrap each message](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#baseProtocol) in what we call an `LSP.Packet`, which holds the `Data`  of its `header`- an `content` part.
+
+```swift
+let myRequestMessagePacket = try LSP.Packet(myRequestMessage)
+let packetHeader = myRequestMessagePacket.header     // Data
+let packetContent = myRequestMessagePacket.content   // Data
+let packetTotalData = myRequestMessagePacket.data    // Data
+```
+
+### Extract Messages From Packets
+
+```swift
+let myRequestMessageUnpacked = try myRequestMessagePacket.message()  // LSP.Message
+```
+
+### Extract LSP Packets From Data
+
+A client talking to an LSP server might need to extract `LSP.Packet`s from the server's output `Data` stream.
+
+SwiftLSP can detect an `LSP.Packet` at the beginning of any `Data` instance and also offers the `LSP.PacketDetector` for parsing a stream of `Data` incrementally.
+
+```swift
+let dataStartingWithPacket = packetTotalData + "Some other data".data(using: .utf8)!
+let parsedPacket = try LSP.Packet(parsingPrefixOf: dataStartingWithPacket)
+
+// now parsedPacket == myRequestMessagePacket
+
+var detectedPacket: LSP.Packet? = nil
+        
+let detector = LSP.PacketDetector { packet in
+    detectedPacket = packet
+}
+
+for byte in dataStartingWithPacket {
+    detector.read(Data([byte]))
+}
+
+// now detectedPacket == myRequestMessagePacket
+```
+
+## More Use Cases
+
+Beyond what the examples above have touched, SwiftLSP also helps with:
 
 * Launching an LSP server executable
-* Extracting LSP Packets from a data stream
-* Encoding and decoding LSP messages
-* Representing, creating and working with LSP messages
 * Matching response messages to request messages
-* Exchanging LSP Messages with an LSP Server
-* Exchanging LSP Messages with an LSP Server via WebSocket
-
-SwiftLSP is the basis for [LSPService](https://github.com/codeface-io/LSPService) and [LSPServiceKit](https://github.com/codeface-io/LSPServiceKit).
+* Making requests to an LSP Server through `async` **functions**
+* Using an LSP Server via WebSocket
 
 ## Architecture
 

Sources/Message/LSP.Message.swift

@@ -3,7 +3,10 @@ import SwiftyToolz
 
 extension LSP
 {
+    typealias Request = Message.Request
+    typealias Response = Message.Response
     typealias ErrorResult = Message.Response.ErrorResult
+    typealias Notification = Message.Notification
 
     /**
      https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#abstractMessage

Sources/Packet/LSP.Message+Packet.swift

@@ -0,0 +1,14 @@
+import Foundation
+
+public extension LSP.Packet
+{
+    init(_ message: LSP.Message) throws
+    {
+        try self.init(withContent: message.encode())
+    }
+    
+    func message() throws -> LSP.Message
+    {
+        try LSP.Message(content)
+    }
+}

Sources/Packet/LSP.Packet+Message.swift

@@ -3,7 +3,7 @@ import SwiftyToolz
 
 public extension LSP
 {
-    struct Packet
+    struct Packet: Equatable
     {
         public init(parsingPrefixOf data: Data) throws
         {

Sources/Packet/LSP.Packet.swift

@@ -8,7 +8,10 @@ extension LSP
     {
         // MARK: - Public API
 
-        public init() {}
+        public init(_ handleDetectedPacket: @escaping (Packet) -> Void)
+        {
+            didDetect = handleDetectedPacket
+        }
 
         public func read(_ data: Data)
         {
@@ -20,7 +23,7 @@ extension LSP
             }
         }
 
-        public var didDetect: (Packet) -> Void = { _ in }
+        public var didDetect: (Packet) -> Void
 
         // MARK: - Data Buffer
 

Sources/Packet/LSP.PacketDetector.swift

@@ -11,17 +11,14 @@ public extension LSP {
         public override init(config: Configuration) throws {
             try super.init(config: config)
 
-            setupPacketOutput()
+            didSendOutput = { [weak self] in self?.packetDetector.read($0) }
         }
 
         // MARK: - LSP Packet Output
 
-        private func setupPacketOutput() {
-            didSendOutput = { [weak self] in self?.packetDetector.read($0) }
-            packetDetector.didDetect = { [weak self] in self?.didSend($0) }
-        }
-        
-        private let packetDetector = LSP.PacketDetector()
+        private lazy var packetDetector: LSP.PacketDetector = {
+            .init { [weak self] in self?.didSend($0) }
+        }()
 
         public var didSend: (LSP.Packet) -> Void = { _ in
             log(warning: "LSP server did send lsp packet, but handler has not been set")

Sources/Server Communication/LSP.ServerExecutable.swift

@@ -59,7 +59,7 @@ public extension LSP
 
         public func sendToServer(_ message: LSP.Message) async throws
         {
-            try await webSocket.send(try message.packet().data)
+            try await webSocket.send(try LSP.Packet(message).data)
         }
 
         // MARK: - Manage Connection

Sources/Server Communication/LSP.WebSocketConnection.swift

@@ -2,6 +2,6 @@ public extension LSP.Message.Notification
 {
     static var initialized: Self
     {
-        .init(method: "initialized", params: .object([:]))
+        .init(method: "initialized", params: .emptyObject)
     }
 }

Sources/Use Cases/Server Life Cycle/LSP.Message.Notification+Initialized.swift

@@ -7,6 +7,42 @@ final class SwiftLSPTests: XCTestCase {
 
     // MARK: - Message
 
+    func testCodeExamplesFromREADME() throws {
+        let myRequest = LSP.Request(method: "myMethod", params: nil)
+        let myRequestMessage = LSP.Message.request(myRequest)
+        
+        let myNotification = LSP.Notification(method: "myMethod", params: nil)
+        _ = LSP.Message.notification(myNotification)
+        
+        let myRequestMessageEncoded = try myRequestMessage.encode()  // Data
+        let myRequestMessageDecoded = try LSP.Message(myRequestMessageEncoded)
+        XCTAssertEqual(myRequestMessageDecoded, myRequestMessage)
+        
+        let myRequestMessagePacket = try LSP.Packet(myRequestMessage)
+        _ = myRequestMessagePacket.header   // Data
+        _ = myRequestMessagePacket.content  // Data
+        let packetTotalData = myRequestMessagePacket.data     // Data
+        
+        let myRequestMessageUnpacked = try myRequestMessagePacket.message()  // LSP.Message
+        XCTAssertEqual(myRequestMessageUnpacked, myRequestMessage)
+        
+        let dataStartingWithPacket = packetTotalData + "Some other data".data(using: .utf8)!
+        let parsedPacket = try LSP.Packet(parsingPrefixOf: dataStartingWithPacket)
+        XCTAssertEqual(parsedPacket, myRequestMessagePacket)
+        
+        var detectedPacket: LSP.Packet? = nil
+        
+        let detector = LSP.PacketDetector { packet in
+            detectedPacket = packet
+        }
+        
+        for byte in dataStartingWithPacket {
+            detector.read(Data([byte]))
+        }
+        
+        XCTAssertEqual(detectedPacket, myRequestMessagePacket)
+    }
+    
     func testNewRequestMessageHasUUIDasID() throws {
 
         let message = LSP.Message.Request(method: "method", params: nil)
@@ -177,11 +213,11 @@ final class SwiftLSPTests: XCTestCase {
     func testPacket() throws {
         let messageJSONString = #"{"jsonrpc":"2.0", "method":"someMethod"}"#
         let packet1 = try LSP.Packet(withContent: messageJSONString.data!)
-        _ = try LSP.Message(packet1)
+        _ = try packet1.message()
 
         let packetBufferString = "Content-Length: 40\r\n\r\n" + messageJSONString + "Next packet or other data"
         let packet2 = try LSP.Packet(parsingPrefixOf: packetBufferString.data!)
-        _ = try LSP.Message(packet2)
+        _ = try packet2.message()
 
         XCTAssertThrowsError(try LSP.Packet(withContent: Data()))
         XCTAssertThrowsError(try LSP.Packet(withContent: (messageJSONString + "{}").data!))
@@ -192,9 +228,8 @@ final class SwiftLSPTests: XCTestCase {
     // MARK: - Packet Detector
 
     func testPacketDetector() {
-        let detector = LSP.PacketDetector()
         var detectedPackets = [LSP.Packet]()
-        detector.didDetect = { detectedPackets += $0 }
+        let detector = LSP.PacketDetector { detectedPackets += $0 }
 
         let header = "Content-Length: 40".data!
         let separator = "\r\n\r\n".data!