Add PeerConnection

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

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,

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,
+    )
+}