ultralight-beam / ub.swift

Swift implementation of the ultralight beam protocol.

UB.swift

UB.swift is the swift implementation of the Ultralight Beam protocol, its primary focus is to provide an SDK for iOS and OSX devices.

Requirements

• iOS 9 or later
• OSX 10.13 or later
• Swift 5.0 or later

Installation

Swift Package Manager

dependencies: [
  .package(url: "https://github.com/ultralight-beam/UB.swift.git", from("0.1.0")),
],
targets: [
  .target(
    name: "Target",
    dependencies: ["UB"]
  ),
]

Cocoapods

pod 'UB'

Usage

Using the UB within your own project is kept simple. Initialize a Node, and assign delegate which will then be notified of received messages. Various transports can be added to a Node enabling sending and receiving messages through them.

import UB

let node = Node()
node.delegate = self

node.add(transport: CoreBluetoothTransport())

node.send(...)

License

UB.swift is licensed under the Apache License

ub.swift's Issues

CoreBluetooth Optimization

Problem

The current Bluetooth implementation created with #52 is not power efficient as it continuously scans for peripherals to connect with.

Currently all nodes are also peered with, this should also be thought about.

Acceptance Criteria

The bluetooth transport features two running modes, one lightweight and one less lightweight. The former will be more energy conservative to run efficiently on resource restricted devices. This means it does not perpetually scan for peripherals and disconnects after sending messages. Depending on how much a node talks to a given peer connections are kept open.

Notes

• http://www.splinter.com.au/2019/05/18/ios-swift-bluetooth-le/ (timeouts)

Setup Travis

Should run tests, lint.

Core Bluetooth transport implementation

Objective

Implement the Core Bluetooth library as a transport within the UB framework

Remove `Message` in favour of `Packet`

Problem

We currently have 2 methods of representing a message that gets sent around within UB. One is the Message type and the other is the Packet protocol buffer. The main differences are the fact that the Message type is "more" type safe and has the last sender of a message.

Acceptance Criteria

We remove message from our codebase and pass around (last_sender, packet) as a tuple where necessary. Functions that are responsible for sending a message take the input parameters as UB specific types and later cast them to those required for the protobuf internally.

Logging

Think about a logging framework to use within UB. Provide proper logging for various layers.

Current candidates

• https://github.com/SwiftyBeaver/SwiftyBeaver
• https://www.bignerdranch.com/blog/migrating-to-unified-logging-swift-edition/ & https://developer.apple.com/documentation/os/logging
• https://medium.com/back-market-engineering/discovering-using-oslog-output-console-with-swiftybeaver-on-ios-54d7bfbe3b97

Probably best to use either oslog or oslog through SwiftyBeaver

Better message routing

Problem

Right now message routing is pretty random, or better said non-existant at all. We need a method which allows users to more effectively route messages within the networks themselves.

Possible solution

After reading the scribe paper (notes), I believe I have found a possible solution.

Ideally we can build a pubsub network over our transports using multicast trees similarly to how scribe does.

This means that a peer knows what topic they want to subscribe to, they find their surrounding peer with the closest address using some distance metric. Let's say for example:

distance(topic, node) = topic XOR node

Now what we do is on the closest node we register that we want to subscribe to a given topic. If that node is also subscribe it adds us to its list, if not, it recursively registers on the next node. Until a root is hit.

To make the trees fault tolerant, if a disconnect is detected, the node registers at the next closest.

MultipeerConnectivity Transport Implementation

Objective

Implement the MultipeerConnectivity library as a transport within the UB framework

Note

The way MPC works, this transport will only work per app, and won't relay messages cross application by the looks of it.

Links

• https://developer.apple.com/documentation/multipeerconnectivity

[Meta] Peer Connectivity

Objective

Get two or more devices to peer with one another over bluetooth.

Related Issues

• Core Bluetooth transport implementation (#25)
• Message Passing
• Peer Discovery

Consider turning the listen callback into a delegate function

Problem

Currently there is a transport.listen function which takes in a callback, this does not seem like it fits into the rest of the design of Ultralight Beam which often uses delegates.

Acceptance Criteria

Look at trade offs of leaving it a callback vs a delegate function and consider changing it if need be.

Rename `proto` to `service`

Problem

We currently use proto in the code base to describe ultralight beam services, this clashes with swifts protocol type.

Solution

The proto field is renamed to service everywhere.

Node.send should not take `Message`

Problem

The node.send function currently takes an argument of the type Message this isn't optimal as we cannot expect endusers to know all those fields.

Acceptance Criteria

There are 3 functions, each for sending a message.

Sending to an address:

send(to: UBID, message: Data)

Sending to a service:

send(service: UBID, message: Data)

Sending to an address and service, this function is called by the above functions.

send(to: UBID, service: UBID, message: Data)

Gemfile

Create a gemfile to handle our ruby dependencies such as xcpretty and jazzy.

Create documentation github action

Create a github action that runs make docs whenever a pull request is merged.

Add another package manager

we will need another package manager for mobile etc, eg cocoapods.

Move Bluetooth to L2CAP

We currently use the more high level bluetooth API. We should change this to the more low level L2CAP api. This will require writing generic streams that can be used by other transports too.

Notes

• https://github.com/paulw11/L2CapDemo
• https://developer.apple.com/videos/play/wwdc2017/712/

Cleanup documentation comments

Problem

Sometimes certain terms are annotated like this or like this.

Acceptance Criteria

All terms are annotated in the same way.

Peer Discovery

Objective

Implement a peer discovery mechanism, similar to flood sub.

Add Podspec

https://guides.cocoapods.org/syntax/podspec.html

Github actions

Use github actions for both lint and test. Then we can remove travis and code climate.

Move Service handling from Relayer into UB

Problem

Services are a Relayer specific thing right now, this means that they can not be easily reused and added directly to a UB node.

Acceptance Criteria

There is message handling that is able to differentiate between a service specific and node specific messages, these messages are then handled accordingly. If they cannot be handled they are retransmitted.

Message passing

Objective

Allow message passing over bluetooth

Protocol Buffers

Problem

Currently there is no proper message serialization.

Acceptance Criteria

Use protocol buffers to have a common message serialization across implementations.