discover

Documentation

Overview

Package discover implements the local and global device discovery protocols.

Global Discovery ================

Announcements -------------

A device should announce itself at startup. It does this by an HTTPS POST to the announce server URL (with the path usually being "/", but this is of course up to the discovery server). The POST has a JSON payload listing direct connection addresses (if any) and relay addresses (if any).

{
	direct: ["tcp://192.0.2.45:22000", "tcp://:22202"],
	relays: [{"url": "relay://192.0.2.99:22028", "latency": 142}]
}

It's OK for either of the "direct" or "relays" fields to be either the empty list ([]), null, or missing entirely. An announcement with both fields missing or empty is however not useful...

Any empty or unspecified IP addresses (i.e. addresses like tcp://:22000, tcp://0.0.0.0:22000, tcp://[::]:22000) are interpreted as referring to the source IP address of the announcement.

The device ID of the announcing device is not part of the announcement. Instead, the server requires that the client perform certificate authentication. The device ID is deduced from the presented certificate.

The server response is empty, with code 200 (OK) on success. If no certificate was presented, status 403 (Forbidden) is returned. If the posted data doesn't conform to the expected format, 400 (Bad Request) is returned.

In successful responses, the server may return a "Reannounce-After" header containing the number of seconds after which the client should perform a new announcement.

In error responses, the server may return a "Retry-After" header containing the number of seconds after which the client should retry.

Performing announcements significantly more often than indicated by the Reannounce-After or Retry-After headers may result in the client being throttled. In such cases the server may respond with status code 429 (Too Many Requests).

Queries =======

Queries are performed as HTTPS GET requests to the announce server URL. The requested device ID is passed as the query parameter "device", in canonical string form, i.e. https://announce.syncthing.net/?device=ABC12345-....

Successful responses will have status code 200 (OK) and carry a JSON payload of the same format as the announcement above. The response will not contain empty or unspecified addresses.

If the "device" query parameter is missing or malformed, the status code 400 (Bad Request) is returned.

If the device ID is of a valid format but not found in the registry, 404 (Not Found) is returned.

If the client has exceeded a rate limit, the server may respond with 429 (Too Many Requests).

Package discover is a generated protocol buffer package.

It is generated from these files:
	local.proto

It has these top-level messages:
	Announce

Index

• Constants
• Variables
• type AddressLister
• type Announce
  • func (*Announce) Descriptor() ([]byte, []int)
  • func (m *Announce) Marshal() (dAtA []byte, err error)
  • func (m *Announce) MarshalTo(dAtA []byte) (int, error)
  • func (*Announce) ProtoMessage()
  • func (m *Announce) ProtoSize() (n int)
  • func (m *Announce) Reset()
  • func (m *Announce) String() string
  • func (m *Announce) Unmarshal(dAtA []byte) error
• type CacheEntry
• type CachingMux
  • func NewCachingMux() CachingMux
• type Finder
• type FinderMux
• type FinderService
  • func NewGlobal(server string, cert tls.Certificate, addrList AddressLister) (FinderService, error)
  • func NewLocal(id protocol.DeviceID, addr string, addrList AddressLister) (FinderService, error)

Constants

const (
	BroadcastInterval = 30 * time.Second
	CacheLifeTime     = 3 * BroadcastInterval
	Magic             = uint32(0x2EA7D90B) // same as in BEP

)

Variables

var (
	ErrInvalidLengthLocal = fmt.Errorf("proto: negative length found during unmarshaling")
	ErrIntOverflowLocal   = fmt.Errorf("proto: integer overflow")
)

Types

type AddressLister

type AddressLister interface {
	ExternalAddresses() []string
	AllAddresses() []string
}

The AddressLister answers questions about what addresses we are listening on.

type Announce

type Announce struct {
	ID         github_com_syncthing_syncthing_lib_protocol.DeviceID `protobuf:"bytes,1,opt,name=id,proto3,customtype=github.com/syncthing/syncthing/lib/protocol.DeviceID" json:"id"`
	Addresses  []string                                             `protobuf:"bytes,2,rep,name=addresses" json:"addresses,omitempty"`
	InstanceID int64                                                `protobuf:"varint,3,opt,name=instance_id,json=instanceId,proto3" json:"instance_id,omitempty"`
}

func (*Announce) Descriptor

func (*Announce) Descriptor() ([]byte, []int)

func (*Announce) Marshal

func (m *Announce) Marshal() (dAtA []byte, err error)

func (*Announce) MarshalTo

func (m *Announce) MarshalTo(dAtA []byte) (int, error)

func (*Announce) ProtoMessage

func (*Announce) ProtoMessage()

func (*Announce) ProtoSize

func (m *Announce) ProtoSize() (n int)

func (*Announce) Reset

func (m *Announce) Reset()

func (*Announce) String

func (m *Announce) String() string

func (*Announce) Unmarshal

func (m *Announce) Unmarshal(dAtA []byte) error

type CacheEntry

type CacheEntry struct {
	Addresses []string `json:"addresses"`
	// contains filtered or unexported fields
}

type CachingMux

type CachingMux interface {
	FinderService
	Add(finder Finder, cacheTime, negCacheTime time.Duration, priority int)
	ChildErrors() map[string]error
}

The CachingMux aggregates results from multiple Finders. Each Finder has an associated cache time and negative cache time. The cache time sets how long we cache and return successful lookup results, the negative cache time sets how long we refrain from asking about the same device ID after receiving a negative answer. The value of zero disables caching (positive or negative).

func NewCachingMux

func NewCachingMux() CachingMux

type Finder

type Finder interface {
	Lookup(deviceID protocol.DeviceID) (address []string, err error)
	Error() error
	String() string
	Cache() map[protocol.DeviceID]CacheEntry
}

A Finder provides lookup services of some kind.

type FinderMux

type FinderMux interface {
	Finder
	ChildStatus() map[string]error
}

type FinderService

type FinderService interface {
	Finder
	suture.Service
}

A FinderService is a Finder that has background activity and must be run as a suture.Service.

func NewGlobal

func NewGlobal(server string, cert tls.Certificate, addrList AddressLister) (FinderService, error)

func NewLocal

func NewLocal(id protocol.DeviceID, addr string, addrList AddressLister) (FinderService, error)