discover

package
v0.12.12 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 10, 2016 License: MPL-2.0 Imports: 23 Imported by: 9

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).

Index

Constants

View Source 
const (
	BroadcastInterval = 30 * time.Second
	CacheLifeTime     = 3 * BroadcastInterval
)
View Source 
const (
	AnnouncementMagic = 0x9D79BC40
)

Variables

View Source 
var (
	ErrIncorrectMagic = errors.New("incorrect magic number")
)

Functions

This section is empty.

Types

type Address 

type Address struct {
	URL string // max:2083
}

func (Address) AppendXDR 

func (o Address) AppendXDR(bs []byte) ([]byte, error)

func (*Address) DecodeXDR 

func (o *Address) DecodeXDR(r io.Reader) error

func (*Address) DecodeXDRFrom 

func (o *Address) DecodeXDRFrom(xr *xdr.Reader) error

func (Address) EncodeXDR 

func (o Address) EncodeXDR(w io.Writer) (int, error)

func (Address) EncodeXDRInto 

func (o Address) EncodeXDRInto(xw *xdr.Writer) (int, error)

func (Address) MarshalXDR 

func (o Address) MarshalXDR() ([]byte, error)

func (Address) MustMarshalXDR 

func (o Address) MustMarshalXDR() []byte

func (*Address) UnmarshalXDR 

func (o *Address) UnmarshalXDR(bs []byte) error

type AddressLister added in v0.12.0 

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

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

type Announce 

type Announce struct {
	Magic uint32
	This  Device
	Extra []Device // max:16
}

func (Announce) AppendXDR 

func (o Announce) AppendXDR(bs []byte) ([]byte, error)

func (*Announce) DecodeXDR 

func (o *Announce) DecodeXDR(r io.Reader) error

func (*Announce) DecodeXDRFrom 

func (o *Announce) DecodeXDRFrom(xr *xdr.Reader) error

func (Announce) EncodeXDR 

func (o Announce) EncodeXDR(w io.Writer) (int, error)

func (Announce) EncodeXDRInto 

func (o Announce) EncodeXDRInto(xw *xdr.Writer) (int, error)

func (Announce) MarshalXDR 

func (o Announce) MarshalXDR() ([]byte, error)

func (Announce) MustMarshalXDR 

func (o Announce) MustMarshalXDR() []byte

func (*Announce) UnmarshalXDR 

func (o *Announce) UnmarshalXDR(bs []byte) error

type CacheEntry 

type CacheEntry struct {
	Direct []string `json:"direct"`
	Relays []Relay  `json:"relays"`
	// contains filtered or unexported fields
}

type CachingMux added in v0.12.0 

type CachingMux struct {
	*suture.Supervisor
	// contains filtered or unexported fields
}

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 successfull 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 added in v0.12.0 

func NewCachingMux() *CachingMux

func (*CachingMux) Add added in v0.12.0 

func (m *CachingMux) Add(finder Finder, cacheTime, negCacheTime time.Duration, priority int)

Add registers a new Finder, with associated cache timeouts.

func (*CachingMux) Cache added in v0.12.0 

func (m *CachingMux) Cache() map[protocol.DeviceID]CacheEntry

func (*CachingMux) ChildErrors added in v0.12.0 

func (m *CachingMux) ChildErrors() map[string]error

func (*CachingMux) Error added in v0.12.0 

func (m *CachingMux) Error() error

func (*CachingMux) Lookup added in v0.12.0 

func (m *CachingMux) Lookup(deviceID protocol.DeviceID) (direct []string, relays []Relay, err error)

Lookup attempts to resolve the device ID using any of the added Finders, while obeying the cache settings.

func (*CachingMux) String added in v0.12.0 

func (m *CachingMux) String() string

type Device 

type Device struct {
	ID        []byte    // max:32
	Addresses []Address // max:16
	Relays    []Relay   // max:16
}

func (Device) AppendXDR 

func (o Device) AppendXDR(bs []byte) ([]byte, error)

func (*Device) DecodeXDR 

func (o *Device) DecodeXDR(r io.Reader) error

func (*Device) DecodeXDRFrom 

func (o *Device) DecodeXDRFrom(xr *xdr.Reader) error

func (Device) EncodeXDR 

func (o Device) EncodeXDR(w io.Writer) (int, error)

func (Device) EncodeXDRInto 

func (o Device) EncodeXDRInto(xw *xdr.Writer) (int, error)

func (Device) MarshalXDR 

func (o Device) MarshalXDR() ([]byte, error)

func (Device) MustMarshalXDR 

func (o Device) MustMarshalXDR() []byte

func (*Device) UnmarshalXDR 

func (o *Device) UnmarshalXDR(bs []byte) error

type Finder added in v0.12.0 

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

A Finder provides lookup services of some kind.

type FinderMux added in v0.12.0 

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

type FinderService added in v0.12.0 

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 added in v0.12.0 

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

func NewLocal added in v0.12.0 

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

type Relay added in v0.12.0 

type Relay struct {
	URL     string `json:"url"` // max:2083
	Latency int32  `json:"latency"`
}

func (Relay) AppendXDR added in v0.12.0 

func (o Relay) AppendXDR(bs []byte) ([]byte, error)

func (*Relay) DecodeXDR added in v0.12.0 

func (o *Relay) DecodeXDR(r io.Reader) error

func (*Relay) DecodeXDRFrom added in v0.12.0 

func (o *Relay) DecodeXDRFrom(xr *xdr.Reader) error

func (Relay) EncodeXDR added in v0.12.0 

func (o Relay) EncodeXDR(w io.Writer) (int, error)

func (Relay) EncodeXDRInto added in v0.12.0 

func (o Relay) EncodeXDRInto(xw *xdr.Writer) (int, error)

func (Relay) MarshalXDR added in v0.12.0 

func (o Relay) MarshalXDR() ([]byte, error)

func (Relay) MustMarshalXDR added in v0.12.0 

func (o Relay) MustMarshalXDR() []byte

func (*Relay) UnmarshalXDR added in v0.12.0 

func (o *Relay) UnmarshalXDR(bs []byte) error

type RelayStatusProvider added in v0.12.0 

type RelayStatusProvider interface {
	Relays() []string
	RelayStatus(uri string) (time.Duration, bool)
}

The RelayStatusProvider answers questions about current relay status.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.