1. 1
2. 2
3. 3
4. 4
5. 5
6. 6
7. 7
8. 8
9. 9
10. 10
11. 11
12. 12
13. 13
14. 14
15. 15
16. 16
17. 17
18. 18
19. 19
20. 20
21. 21
22. 22
23. 23
24. 24
25. 25
26. 26
27. 27
28. 28
29. 29
30. 30
31. 31
32. 32
33. 33
34. 34
35. 35
36. 36
37. 37
38. 38
39. 39
40. 40
41. 41
42. 42
43. 43
44. 44
45. 45
46. 46
47. 47
48. 48
49. 49
50. 50
51. 51
52. 52
53. 53
54. 54
55. 55
56. 56
57. 57
58. 58
59. 59
60. 60

// Copyright 2025 Shota FUJI
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//
// SPDX-License-Identifier: Apache-2.0

public enum MessageReadError: Error {
	case connectionClosed
	case timeout
}

public enum MessageWriteError: Error {
	case connectionNotReady
}

public protocol Communicatable: Actor {
	/// A stream of incoming messages. Roon API uses WebSocket for most of the operation,
	/// even including request-response methods. Due to this nature, caller must check
	/// "Request-Id" header field to determine if a message is a response for the request.
	///
	/// The stream will end when the underlying connection was closed.
	///
	/// This is low-level API. Only use for continuous reading, such as change subscription.
	var messages: AsyncStream<Moo> { get }

	/// Send a MOO message to connected Roon server and returns a response for the message.
	///
	/// This function sets "Request-Id" header if the message does not have one.
	/// Unless you have a specific reason, let this function set it so the ID will be unique among other requests.
	///
	/// Throws when send failed or connection closed during the read.
	func request(_ msg: consuming Moo) async throws -> Moo

	/// Send a MOO message to connected Roon server and returns a response for the message.
	///
	/// This function sets "Request-Id" header if the message does not have one.
	/// Unless you have a specific reason, let this function set it so the ID will be unique among other requests.
	///
	/// Throws when send failed or connection closed during the read.
	///
	/// If no response was made when the `timeout` elapsed, `MessageReadError.timeout` error will be thrown.
	func request(_ msg: consuming Moo, timeout: ContinuousClock.Instant.Duration)
		async throws -> Moo

	/// Sends a MOO message to the connected Roon server, then returns.
	/// This function does not waits for a response message.
	///
	/// Throws when a network error occured during send operation.
	func send(_ msg: consuming Moo) async throws
}