From bfb7bb38589d958ca8d4d58e3e4df5a46977b32e Mon Sep 17 00:00:00 2001 From: Skyler Jokiel Date: Tue, 21 Feb 2023 15:35:20 -0800 Subject: [PATCH] Add basic experimental bus doc (#466) --- docs/common/sidebar.js | 8 +++ docs/ios/experimental/_category_.json | 4 ++ docs/ios/experimental/ditto-bus.mdx | 94 +++++++++++++++++++++++++++ snippets.json | 11 +++- 4 files changed, 116 insertions(+), 1 deletion(-) create mode 100644 docs/ios/experimental/_category_.json create mode 100644 docs/ios/experimental/ditto-bus.mdx diff --git a/docs/common/sidebar.js b/docs/common/sidebar.js index 237b275e30..a5daf10417 100644 --- a/docs/common/sidebar.js +++ b/docs/common/sidebar.js @@ -73,6 +73,14 @@ module.exports = function (opts) { dirName: 'common/how-it-works' }] }, + { + type: "category", + label: "Experimental", + items: [{ + type: 'autogenerated', + dirName: 'experimental' + }] + }, opts.api, "common/v3", "common/troubleshooting" diff --git a/docs/ios/experimental/_category_.json b/docs/ios/experimental/_category_.json new file mode 100644 index 0000000000..fb1f571897 --- /dev/null +++ b/docs/ios/experimental/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Experimental", + "position": 1 +} diff --git a/docs/ios/experimental/ditto-bus.mdx b/docs/ios/experimental/ditto-bus.mdx new file mode 100644 index 0000000000..42a8cb03a9 --- /dev/null +++ b/docs/ios/experimental/ditto-bus.mdx @@ -0,0 +1,94 @@ +--- +title: 'Ditto Bus' +--- + +import SnippetGroup from '@site/src/components/SnippetGroup'; + +:::danger +*The Ditto Bus API is currently **Experimental** and should not be used in production scenarios* +::: + +The Ditto Bus is designed to enable developers to leverage the underlying mesh network to transmit data peer-to-peer without using the Ditto Store. It can be used to send one-off messages or create continuous channels with other peers in the mesh. The Ditto bus does not persist data. + +Messages are treated as opaque binary by Ditto and must be created and interpreted by your application. + +## Example Use Cases + +- Voice and video streaming +- Remote control systems +- Tunneling other protocols +- Gaming + +## Version Support & Imports + +### Version Support + +The Ditto bus is included as experimental in SDK version `3.0.0` and later. + +### Import + +It can be imported in a file through the standard `DittoSwift` import. + +```swift +import DittoSwift +``` + +## Getting PeerAddress + +To be able to send a message or establish a connection you need to know the peer you want to connect to. + +[ObservingPeers Docs](../common/mesh-network/manual#observing-peers) + + + +## Sending Messages + +Messages can be sent as single one-off messages or through establishing a bidirectional stream with another peer. All transports are peer-to-peer and require having the address of the peer you are connecting to. + +### Reliable Single Message +User1 sends a single reliable message to User2 + + + + +### Unreliable Single Message +User1 sends a single unreliable message to User2 + + + + +### Reliable Bidirectional Stream +User1 establishes a reliable bidirectional stream with User2. Both users can enqueue messages on the stream. Messages are ordered and guarantee. + + + + + +### Unreliable Bidirectional Stream +User1 establishes an unreliable bidirectional stream with User2. Both users can enqueue messages on the stream. Messages are not ordered or guarantee. + + + + \ No newline at end of file diff --git a/snippets.json b/snippets.json index b87ba98d81..9c763cf3ce 100644 --- a/snippets.json +++ b/snippets.json @@ -108,7 +108,16 @@ "evict": "collection.find(\"owner == 'Bob'\").evict()\n\n", "remove-query": "collection.find(\"owner == 'Bob'\").remove()\n\n", "remove-id": "collection.findByID(docID).remove()\n\n", - "sync-basic": "try! ditto.startSync()\n\n" + "sync-basic": "try! ditto.startSync()\n\n", + "bus-peers-first-user": "// Get the DittoAddress from the first user in the peer object\nditto.presence.observe { presence in\n if !presence.remotePeers.isEmpty {\n let user2PeerAddress = presence.remotePeers[0].address\n }", + "bus-single-message-receive": "// User2 sets up a delegate to handle inbound requests\nditto.bus.delegate = SingleMessageReceivedDelegate()\n\nclass SingleMessageReceivedDelegate: DittoBusDelegate {\n var receivedMessage: Data?\n \n func dittoBus(_ bus: DittoBus, didReceiveSingleMessage message: DittoBusMessage) {\n self.receivedMessage = message.data\n }\n \n func dittoBus(_ bus: DittoBus, didReceiveIncomingStream busStream: DittoBusStream,\nfromPeer peer: DittoAddress) {\n // not implemented\n }\n}", + "bus-reliable-single-message-send": "// User1 sends data to User2. Success provides guarantee of data delivery.\nlet data = Data([1, 2, 3, 4, 5])\nditto.bus.sendSingleReliableMessage(data, to: user2PeerAddress, completion: { e in\n if let error = e {\n // success\n }\n})", + "bus-unreliable-single-message-send": "// User1 sends data to User2. Success provides guarantee of data sent.\nlet data = Data([1, 2, 3, 4, 5])\nditto.bus.sendSingleUnreliableMessage(data, to: user2PeerAddress, completion: { e in\n if let error = e {\n // success\n }\n})", + "bus-bidirectional-stream-handler": "// User2 - Create a delegate to handle inbound stream requests\nlet incomingDelegate = IncomingStreamRecievedDelegate()\n// Attach a StreamDelegate to handle messages once a connection is established\nincomingDelegate.streamDelegate = StreamDelegate()\nditto.bus.delegate = incomingDelegate\n\n// Send a message\nlet data = Data([1, 2, 3, 4, 5])\nincomingDelegate.connectedStream?.enqueueMessage(data: data)\n\n// An ID unique to the local device that can be used to track this individual stream.\nuser1Stream?.id\n\n// Close the stream\nincomingDelegate.connectedStream?.close()", + "bus-reliable-bidirectional-stream-sender":"// User1 - Reliable Bidirectional Stream\n\nditto.bus.delegate = IncomingStreamRecievedDelegate()\n\nlet streamDelegate = StreamDelegate()\nvar user1Stream: DittoBusStream?\nself.ditto1.bus.openStream(toAddress: user2PeerAddress, reliability: .reliable) { stream, err in\n user1Stream = stream\n stream?.delegate = streamDelegate\n}\n\n// Send Message\nlet data = Data([1, 2, 3, 4, 5])\nuser1Stream?.enqueueMessage(data: data)\n\n// An ID unique to the local device that can be used to track this individual stream.\nuser1Stream?.id\n\n// close\nuser1Stream?.close()", + "bus-unreliable-bidirectional-stream-sender":"// User1 - Unreliable Bidirectional Stream\n\nditto.bus.delegate = IncomingStreamRecievedDelegate()\n\nlet streamDelegate = StreamDelegate()\nvar user1Stream: DittoBusStream?\nself.ditto1.bus.openStream(toAddress: user2PeerAddress, reliability: .unreliable) { stream, err in\n user1Stream = stream\n stream?.delegate = streamDelegate\n}\n\n// Send Message\nlet data = Data([1, 2, 3, 4, 5])\nuser1Stream?.enqueueMessage(data: data)\n\n// An ID unique to the local device that can be used to track this individual stream.\nuser1Stream?.id\n\n// close\nuser1Stream?.close()", + "bus-bidirectional-stream-common":"// Common Classes\n\n// Handles new stream requests\nclass IncomingStreamRecievedDelegate: DittoBusDelegate {\n var connectedStream: DittoBusStream?\n var streamDelegate: DittoBusStreamDelegate?\n \n func dittoBus(_ bus: DittoBus, didReceiveSingleMessage message: DittoBusMessage) {}\n \n func dittoBus(_ bus: DittoBus, didReceiveIncomingStream busStream: DittoBusStream, fromPeer peer: DittoAddress) {\n self.incomingStream = busStream\n busStream.delegate = self.streamDelegate\n }\n}\n\n/// Handles opeartions/messages on a connected stream\nclass StreamDelegate: DittoBusStreamDelegate {\n \n /// A new message has been received from the specified stream.\n func dittoBusStream(_ busStream: DittoBusStream, didReceiveMessage message: Data) {\n // handle message recieved\n }\n \n /// The stream has closed. This can be triggered by calling close() or by the remote peer doing the same.\n func dittoBusStream(_ busStream: DittoBusStream, didClose error: DittoSwiftError) {\n // handle connection closed\n }\n \n // The operation to enqueue outgoing data on a stream has completed. More data may now be enqueued.\n // The message sequence number may be used to track when the remote side has fully acknowledged receipt.\n // `error` will be non-nil if the operation failed.\n func dittoBusStream(_ busStream: DittoBusStream, didEnqueueDataWithMessageSequence messageSequence: UInt64, error: DittoSwiftError?) {\n // handle did enqueue data\n }\n \n // The remote peer has acknowledged receipt of all messages up to the given sequence number.\n func dittoBusStream(_ busStream: DittoBusStream, didAcknowledgeReceipt messageSequence: UInt64) {}\n // handle did data was received \n}" + }, "cpp": { "sync-observe-local": "// --- Register live query to update UI\nstd::shared_ptr query =\n collection.find(\"color == 'red'\")\n .observe_local([&](std::vector docs, LiveQueryEvent event) {\n\n });\n\n",