update README

Author: wangzhizhou

README.md

@@ -51,27 +51,78 @@ import OpenAPIURLSession
 @main
 struct HttpUsageDemo {
     static func main() async throws {
-
-        let yourAccountToken = ProcessInfo.processInfo.environment["TOKEN"] ?? ""
+        let token = ProcessInfo.processInfo.environment["TOKEN"] ?? ""
+        let serverId = ProcessInfo.processInfo.environment["SERVER"] ?? ""
+        guard !token.isEmpty else {
+            print("Missing env TOKEN. Example: TOKEN=... swift run HTTPUsageDemo")
+            return
+        }
 
         let client = Client(
-            serverURL: try! Servers.server1(),
+            serverURL: try! Servers.Server1.url(),
             transport: URLSessionTransport(),
-            middlewares: [AuthenticationMiddleware(token: yourAccountToken)]
+            middlewares: [AuthenticationMiddleware(token: token)]
         )
-        let response = try await client.getAccount()
+        let accountResponse = try await client.getAccount()
+
+        switch accountResponse {
+        case .ok(let ok):
+            let account = try ok.body.json.data
+            print("Account: \(account?.name ?? "-")")
+        case .forbidden(let forbidden):
+            let json = try forbidden.body.json
+            print("Forbidden: \(json.error ?? "-")")
+        case .undocumented(let statusCode, let unknownPayload):
+            print("Unexpected status: \(statusCode), payload: \(unknownPayload)")
+        }
 
-        switch response {
+        let serversResponse = try await client.getServers()
+        switch serversResponse {
         case .ok(let ok):
-            if let data = try ok.body.json.data,
-               let name = data.name {
-                print("account: \(name)")
+            let servers = try ok.body.json.data ?? []
+            print("Servers: \(servers.count)")
+            if let first = servers.first {
+                print("First server: \(first.id ?? "-") \(first.name ?? "-") status=\(first.status?.rawValue ?? -1)")
             }
+        case .badRequest(let badRequest):
+            let json = try badRequest.body.json
+            print("Bad request: \(json.error ?? "-")")
         case .forbidden(let forbidden):
             let json = try forbidden.body.json
-            print(json.error ?? "")
+            print("Forbidden: \(json.error ?? "-")")
+        case .notFound(let notFound):
+            let json = try notFound.body.json
+            print("Not found: \(json.error ?? "-")")
+        case .internalServerError(let internalServerError):
+            let json = try internalServerError.body.json
+            print("Internal error: \(json.error ?? "-")")
         case .undocumented(let statusCode, let unknownPayload):
-            print("statusCode:\(statusCode), payload: \(unknownPayload)")
+            print("Unexpected status: \(statusCode), payload: \(unknownPayload)")
+        }
+
+        if !serverId.isEmpty {
+            let serverResponse = try await client.getServer(path: .init(serverId: serverId))
+            switch serverResponse {
+            case .ok(let ok):
+                let server = try ok.body.json.data
+                print("Server: \(server?.id ?? "-") \(server?.name ?? "-")")
+            case .badRequest(let badRequest):
+                let json = try badRequest.body.json
+                print("Bad request: \(json.error ?? "-")")
+            case .notFound(let notFound):
+                let json = try notFound.body.json
+                print("Not found: \(json.error ?? "-")")
+            case .forbidden(let forbidden):
+                let json = try forbidden.body.json
+                print("Forbidden: \(json.error ?? "-")")
+            case .internalServerError(let internalServerError):
+                let json = try internalServerError.body.json
+                print("Internal error: \(json.error ?? "-")")
+            case .undocumented(let statusCode, let unknownPayload):
+                print("Unexpected status: \(statusCode), payload: \(unknownPayload)")
+            }
+        } else {
+            print("Tip: set env SERVER=... to query a specific server.")
         }
     }
 }
@@ -108,6 +159,9 @@ let package = Package(
 
 ```
 
+Note:
+- `ExarotonWebSocketAPI.delegate` is `weak`. Keep a strong reference to your handler (e.g. store it as a property), otherwise callbacks may stop unexpectedly.
+
 Use ExarotonWebSocket:
 
 ```swift
@@ -119,38 +173,98 @@ import Starscream
 struct WebSocketUsageDemo {
 
     static func main() async throws {
-        
-        let socket = ExarotonWebSocketAPI(
-            token: ProcessInfo.processInfo.environment["TOKEN"] ?? "your_account_token",
-            serverId: ProcessInfo.processInfo.environment["SERVER"] ?? "your_server_id",
-            delegate: ServerEventHandler()
-        )
-        
-        socket.client.connect()
-        try await wait(for: socket.timeout)
-
-        let consoleStreamMessage = ExarotonMessage(
-            stream: .console,
-            type: StreamType.start,
-            data: ["tail": 2]
-        )
-        socket.client.write(stringData: try consoleStreamMessage.toData) {
-            print("console stream start completed!")
+        let token = ProcessInfo.processInfo.environment["TOKEN"] ?? ""
+        let serverId = ProcessInfo.processInfo.environment["SERVER"] ?? ""
+        guard !token.isEmpty, !serverId.isEmpty else {
+            print("Missing env TOKEN or SERVER. Example: TOKEN=... SERVER=... swift run WebSocketUsageDemo")
+            return
+        }
+
+        let ready = ReadySignal()
+        let handler = ServerEventHandler(ready: ready)
+        let socket = ExarotonWebSocketAPI(token: token, serverId: serverId, delegate: handler)
+
+        socket.connect()
+
+        let didBecomeReady = await ready.wait(seconds: socket.timeout)
+        guard didBecomeReady else {
+            print("Timed out waiting for ready")
+            socket.disconnect()
+            return
+        }
+
+        try socket.startStream(.console, tail: 10) {
+            print("console stream start sent")
         }
 
-        try await wait(for: socket.timeout)
-        socket.client.disconnect()
+        try socket.sendConsoleCommand("say Hello from WebSocketUsageDemo") {
+            print("console command sent")
+        }
+
+        try await sleep(seconds: 3)
+        try socket.stopStream(.console) {
+            print("console stream stop sent")
+        }
+
+        try await sleep(seconds: 1)
+        socket.disconnect()
+    }
+
+    static func sleep(seconds: Double) async throws {
+        let ns = UInt64(max(0, seconds) * 1_000_000_000)
+        try await Task.sleep(nanoseconds: ns)
+    }
+}
+
+actor ReadySignal {
+    private var continuation: CheckedContinuation<Void, Never>?
+    private var isSignaled = false
+
+    func signal() {
+        isSignaled = true
+        continuation?.resume()
+        continuation = nil
     }
 
-    static func wait(for minutes: Double) async throws {
-        try await Task.sleep(nanoseconds: UInt64(1_000_000_000 * minutes))
+    func wait(seconds: Double) async -> Bool {
+        if isSignaled { return true }
+        return await withTaskGroup(of: Bool.self) { group in
+            group.addTask {
+                await withCheckedContinuation { continuation in
+                    Task { await self._install(continuation) }
+                }
+                return true
+            }
+            group.addTask {
+                let ns = UInt64(max(0, seconds) * 1_000_000_000)
+                try? await Task.sleep(nanoseconds: ns)
+                return false
+            }
+            let result = await group.next() ?? false
+            group.cancelAll()
+            return result
+        }
+    }
+
+    private func _install(_ continuation: CheckedContinuation<Void, Never>) {
+        if isSignaled {
+            continuation.resume()
+            return
+        }
+        self.continuation = continuation
     }
 }
 
 final class ServerEventHandler: ExarotonServerEventHandlerProtocol {
+    let ready: ReadySignal
+
+    init(ready: ReadySignal) {
+        self.ready = ready
+    }
 
     func onReady(serverID: String?) {
         print("server ready: \(serverID ?? "")")
+        Task { await ready.signal() }
     }
 
     func onConnected() {
@@ -207,19 +321,21 @@ final class ServerEventHandler: ExarotonServerEventHandlerProtocol {
         }
     }
 
-    // MARK: WebSocketDelegate
+    func onError(_ error: Error) {
+        print("error: \(error.localizedDescription)")
+    }
+
     func didReceive(event: Starscream.WebSocketEvent, client: any Starscream.WebSocketClient) {
-        // all events, if you need process them your self
     }
 }
 ```
 For More Use Cases:
 - 👉🏻 [Send Message][websocket send message cases]
 - 👉🏻 [Receive Message][websocket message receive handler]
 
-## Developemnt 👨🏻‍💻
+## Development 👨🏻‍💻
 
-If you want to contribute to this project, you can use your Mac device and install the Xcode`(>= 15.3)` to get start
+If you want to contribute to this project, you can use your Mac device and install the Xcode`(>= 15.4)` to get start
 
 Run shell command as follow to get the project and open it with xcode editor:
 
@@ -261,6 +377,6 @@ If things goes well, you will see the unittests run and success or fail as follo
 [Exaroton OpenAPI Doc]: <https://developers.exaroton.com/openapi.yaml>
 [Swagger Editor]: <https://editor-next.swagger.io/>
 [Swift OpenAPI Generator]: <https://swiftpackageindex.com/apple/swift-openapi-generator>
-[openapi http client cases]: <https://github.com/wangzhizhou/ExarotonAPI/blob/main/Tests/ExarotonHTTPTests/ExarotonHTTPTests.swift>
-[websocket send message cases]: <https://github.com/wangzhizhou/ExarotonAPI/blob/main/Tests/ExarotonWebSocketTests/ExarotonWebSocketTests.swift>
+[openapi http client cases]: <https://github.com/wangzhizhou/ExarotonAPI/blob/main/Tests/ExarotonHTTPTests/ExarotonHTTPUnitTests.swift>
+[websocket send message cases]: <https://github.com/wangzhizhou/ExarotonAPI/blob/main/Sources/ExarotonWebSocket/ExarotonWebSocketAPI.swift>
 [websocket message receive handler]: <https://github.com/wangzhizhou/ExarotonAPI/blob/main/Tests/ExarotonWebSocketTests/ExarotonWebSocketEventDelegateHandler.swift>