From 5c7d3d8a7a3513ede88320a895ef8d89cf6dc440 Mon Sep 17 00:00:00 2001
From: Alexander Nozik <altavir@gmail.com>
Date: Fri, 7 Jun 2024 10:52:28 +0300
Subject: [PATCH] Add PeerConnection

---
 CHANGELOG.md                                  |  1 +
 .../kscience/controls/api/DeviceMessage.kt    | 10 ++++-
 .../kscience/controls/peer/PeerConnection.kt  | 42 +++++++++++++++++++
 3 files changed, 51 insertions(+), 2 deletions(-)
 create mode 100644 controls-core/src/commonMain/kotlin/space/kscience/controls/peer/PeerConnection.kt

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 92b2765..ae8c47f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,7 @@
 - PLC4X bindings
 - Shortcuts to access all Controls devices in a magix network.
 - `DeviceClient` properly evaluates lifecycle and logs
+- `PeerConnection` API for direct device-device binary sharing
 
 ### Changed
 - Constructor properties return `DeviceState` in order to be able to subscribe to them
diff --git a/controls-core/src/commonMain/kotlin/space/kscience/controls/api/DeviceMessage.kt b/controls-core/src/commonMain/kotlin/space/kscience/controls/api/DeviceMessage.kt
index dda89de..f91beb5 100644
--- a/controls-core/src/commonMain/kotlin/space/kscience/controls/api/DeviceMessage.kt
+++ b/controls-core/src/commonMain/kotlin/space/kscience/controls/api/DeviceMessage.kt
@@ -166,12 +166,18 @@ public data class ActionResultMessage(
 }
 
 /**
- * Notifies listeners that a new binary with given [binaryID] is available. The binary itself could not be provided via [DeviceMessage] API.
+ * Notifies listeners that a new binary with given [contentId] and [contentMeta] is available.
+ *
+ * [contentMeta] includes public information that could be shared with loop subscribers. It should not contain sensitive data.
+ *
+ * The binary itself could not be provided via [DeviceMessage] API.
+ * [space.kscience.controls.peer.PeerConnection] must be used instead
  */
 @Serializable
 @SerialName("binary.notification")
 public data class BinaryNotificationMessage(
-    val binaryID: String,
+    val contentId: String,
+    val contentMeta: Meta,
     override val sourceDevice: Name,
     override val targetDevice: Name? = null,
     override val comment: String? = null,
diff --git a/controls-core/src/commonMain/kotlin/space/kscience/controls/peer/PeerConnection.kt b/controls-core/src/commonMain/kotlin/space/kscience/controls/peer/PeerConnection.kt
new file mode 100644
index 0000000..14b49ef
--- /dev/null
+++ b/controls-core/src/commonMain/kotlin/space/kscience/controls/peer/PeerConnection.kt
@@ -0,0 +1,42 @@
+package space.kscience.controls.peer
+
+import space.kscience.dataforge.io.Envelope
+import space.kscience.dataforge.meta.Meta
+import space.kscience.dataforge.names.Name
+
+/**
+ * A manager that allows direct synchronous sending and receiving binary data
+ */
+public interface PeerConnection {
+    /**
+     * Receive an [Envelope] from a device with name [deviceName] on a given [address] with given [contentId].
+     *
+     * The address depends on the specifics of given [PeerConnection]. For example, it could be a TCP/IP port or
+     * magix endpoint name.
+     *
+     * Depending on [PeerConnection] implementation, the resulting [Envelope] could be lazy loaded
+     *
+     * Additional metadata in [requestMeta] could be required for authentication.
+     */
+    public suspend fun receive(
+        address: String,
+        deviceName: Name,
+        contentId: String,
+        requestMeta: Meta = Meta.EMPTY,
+    ): Envelope
+
+    /**
+     * Send an [envelope] to a device with name [deviceName] on a given [address]
+     *
+     * The address depends on the specifics of given [PeerConnection]. For example, it could be a TCP/IP port or
+     * magix endpoint name.
+     *
+     * Additional metadata in [requestMeta] could be required for authentication.
+     */
+    public suspend fun send(
+        address: String,
+        deviceName: Name,
+        envelope: Envelope,
+        requestMeta: Meta = Meta.EMPTY,
+    )
+}
\ No newline at end of file