starling

README

Starling Protocol

The Starling protocol is an open standard suitable for anonymous ad-hoc routing in an unstructured peer-to-peer network. It is optimized for use in low-bandwidth environments, and it has been specifically designed for use with smartphones using Bluetooth Low Energy for the link layer.

This repository contains an implementation of the Starling protocol in Go. It has been implemented as a generic library that can be integrated with any environment. This allows for the protocol to be run on actual devices, by integrating the protocol with an environment that interacts over Bluetooth with other devices. An example of this can be seen in https://github.com/starling-protocol/starling-messenger. It also enables us to run the exact same code in a simulated environment using a simulator such as https://github.com/starling-protocol/simulator.

Documentation

Overview

An implementation of the Starling protocol

Index

• type Protocol
  • func NewProtocol(dev device.Device, options *device.ProtocolOptions) *Protocol
  • func (proto *Protocol) BroadcastRouteRequest()
  • func (proto *Protocol) DeleteContact(contact device.ContactID)
  • func (proto *Protocol) JoinGroup(groupSecret device.SharedSecret) (device.ContactID, error)
  • func (proto *Protocol) LinkingCreate(linkSession *contacts.LinkingSession, remoteKey []byte) (device.ContactID, error)
  • func (proto *Protocol) LinkingStart() (*contacts.LinkingSession, error)
  • func (proto *Protocol) LoadPersistedState()
  • func (proto *Protocol) NewGroup() (device.ContactID, error)
  • func (proto *Protocol) OnConnection(address device.DeviceAddress)
  • func (proto *Protocol) OnDisconnection(address device.DeviceAddress)
  • func (proto *Protocol) ReceivePacket(address device.DeviceAddress, packet []byte)
  • func (proto *Protocol) SendMessage(session device.SessionID, message []byte) (device.MessageID, error)
  • func (proto *Protocol) SyncAddMessage(contact device.ContactID, message []byte, attachedContact *device.ContactID) error
  • func (proto *Protocol) SyncLoadState(contact device.ContactID, state []byte) error

Types

type Protocol

type Protocol struct {
	// contains filtered or unexported fields
}

The main protocol object which keeps the state of the entire protocol stack

func NewProtocol

func NewProtocol(dev device.Device, options *device.ProtocolOptions) *Protocol

NewProtocol constructs a new Protocol given device and options.

func (*Protocol) BroadcastRouteRequest

func (proto *Protocol) BroadcastRouteRequest()

BroadcastRouteRequest is called to send a route request to all connected peers.

func (*Protocol) DeleteContact

func (proto *Protocol) DeleteContact(contact device.ContactID)

DeleteContact deletes the given contact such that future requests from this contact will be ignored.

func (*Protocol) JoinGroup

func (proto *Protocol) JoinGroup(groupSecret device.SharedSecret) (device.ContactID, error)

func (*Protocol) LinkingCreate

func (proto *Protocol) LinkingCreate(linkSession *contacts.LinkingSession, remoteKey []byte) (device.ContactID, error)

LinkingStart is used to finish a linking session and create a common contact.

func (*Protocol) LinkingStart

func (proto *Protocol) LinkingStart() (*contacts.LinkingSession, error)

LinkingStart is used to initiate a linking session.

func (*Protocol) LoadPersistedState

func (proto *Protocol) LoadPersistedState()

func (*Protocol) NewGroup

func (proto *Protocol) NewGroup() (device.ContactID, error)

NewGroup creates a new contact which is shared with no one else yet.

func (*Protocol) OnConnection

func (proto *Protocol) OnConnection(address device.DeviceAddress)

OnConnection should be called when a new link layer connection has been established and is ready to receive messages.

func (*Protocol) OnDisconnection

func (proto *Protocol) OnDisconnection(address device.DeviceAddress)

OnDisconnection should be called when a link layer connection has been broken and can no longer receive messages.

func (*Protocol) ReceivePacket

func (proto *Protocol) ReceivePacket(address device.DeviceAddress, packet []byte)

ReceivePacket should be called when a new packet is received on the link layer.

func (*Protocol) SendMessage

func (proto *Protocol) SendMessage(session device.SessionID, message []byte) (device.MessageID, error)

SendMessage is called to send a message on a session. The SessionID is obtained from the OnSessionEstablished function of the Device.

func (*Protocol) SyncAddMessage

func (proto *Protocol) SyncAddMessage(contact device.ContactID, message []byte, attachedContact *device.ContactID) error

SyncAddMessage will add a message to a synchronized group. If attachedContact is not nil, the shared secret for the given contact will be attached to the message and shared in the group, in order for other group members to join the the attached group.

The synchronization protocol option must be enabled in order to use this method.

func (*Protocol) SyncLoadState

func (proto *Protocol) SyncLoadState(contact device.ContactID, state []byte) error