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
- 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 (m *Announce) MarshalToSizedBuffer(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
- func (m *Announce) XXX_DiscardUnknown()
- func (m *Announce) XXX_Marshal(b []byte, deterministic bool) ([]byte, error)
- func (m *Announce) XXX_Merge(src proto.Message)
- func (m *Announce) XXX_Size() int
- func (m *Announce) XXX_Unmarshal(b []byte) error
- type CacheEntry
- type Finder
- type FinderService
- type Manager
Constants ¶
const ( BroadcastInterval = 30 * time.Second CacheLifeTime = 3 * BroadcastInterval Magic = uint32(0x2EA7D90B) // same as in BEP )
Variables ¶
Functions ¶
This section is empty.
Types ¶
type AddressLister ¶ added in v0.12.0
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" xml:"id"`
Addresses []string `protobuf:"bytes,2,rep,name=addresses,proto3" json:"addresses" xml:"address"`
InstanceID int64 `protobuf:"varint,3,opt,name=instance_id,json=instanceId,proto3" json:"instanceId" xml:"instanceId"`
}
func (*Announce) Descriptor ¶ added in v0.14.0
func (*Announce) MarshalToSizedBuffer ¶ added in v1.3.0
func (*Announce) ProtoMessage ¶ added in v0.14.0
func (*Announce) ProtoMessage()
func (*Announce) XXX_DiscardUnknown ¶ added in v1.0.1
func (m *Announce) XXX_DiscardUnknown()
func (*Announce) XXX_Marshal ¶ added in v1.0.1
func (*Announce) XXX_Unmarshal ¶ added in v1.0.1
type CacheEntry ¶
type CacheEntry struct {
Addresses []string `json:"addresses"`
// contains filtered or unexported fields
}
type Finder ¶ added in v0.12.0
type Finder interface {
Lookup(ctx context.Context, 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 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, evLogger events.Logger, registry *registry.Registry) (FinderService, error)
func NewLocal ¶ added in v0.12.0
func NewLocal(id protocol.DeviceID, addr string, addrList AddressLister, evLogger events.Logger) (FinderService, error)
type Manager ¶ added in v1.9.0
type Manager interface {
FinderService
ChildErrors() map[string]error
}
The Manager 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).
Source Files
Directories