protocol

package
v0.13.10 Latest Latest
Warning

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

Go to latest
Published: Jul 3, 2016 License: MPL-2.0, MIT Imports: 20 Imported by: 0

README

The BEPv1 Protocol

Latest Build API Documentation MIT License

This is the protocol implementation used by Syncthing.

License

MIT

Documentation

Overview

Package protocol implements the Block Exchange Protocol.

Index

Constants

View Source
const (
	// BlockSize is the standard ata block size (128 KiB)
	BlockSize = 128 << 10

	// MaxMessageLen is the largest message size allowed on the wire. (512 MiB)
	MaxMessageLen = 64 << 23
)
View Source
const (
	FlagDeleted              uint32 = 1 << 12 // bit 19 in MSB order with the first bit being #0
	FlagInvalid                     = 1 << 13 // bit 18
	FlagDirectory                   = 1 << 14 // bit 17
	FlagNoPermBits                  = 1 << 15 // bit 16
	FlagSymlink                     = 1 << 16 // bit 15
	FlagSymlinkMissingTarget        = 1 << 17 // bit 14

	FlagsAll = (1 << 18) - 1

	SymlinkTypeMask = FlagDirectory | FlagSymlinkMissingTarget
)

FileInfo flags

View Source
const (
	UpdateTypeAppend uint32 = iota
	UpdateTypeForget
)

FileDownloadProgressUpdate update types

View Source
const (
	FlagFolderReadOnly            uint32 = 1 << 0
	FlagFolderIgnorePerms                = 1 << 1
	FlagFolderIgnoreDelete               = 1 << 2
	FlagFolderDisabledTempIndexes        = 1 << 3
	FlagFolderAll                        = 1<<4 - 1
)

ClusterConfigMessage.Folders flags

View Source
const (
	FlagShareTrusted  uint32 = 1 << 0
	FlagShareReadOnly        = 1 << 1
	FlagIntroducer           = 1 << 2
	FlagShareBits            = 0x000000ff
)

ClusterConfigMessage.Folders.Devices flags

View Source
const (
	// PingSendInterval is how often we make sure to send a message, by
	// triggering pings if necessary.
	PingSendInterval = 90 * time.Second
	// ReceiveTimeout is the longest we'll wait for a message from the other
	// side before closing the connection.
	ReceiveTimeout = 300 * time.Second
)
View Source
const (
	FlagFromTemporary uint32 = 1 << iota
)

Request message flags

Variables

View Source
var (
	ErrNoError    error
	ErrGeneric    = errors.New("generic error")
	ErrNoSuchFile = errors.New("no such file")
	ErrInvalid    = errors.New("file is invalid")
)
View Source
var (
	// ErrTooOldVersion12 is returned by ExchangeHello when the other side
	// speaks the older, incompatible version 0.12 of the protocol.
	ErrTooOldVersion12 = errors.New("the remote device speaks an older version of the protocol (v0.12) not compatible with this version")
	// ErrUnknownMagic is returned by ExchangeHellow when the other side
	// speaks something entirely unknown.
	ErrUnknownMagic = errors.New("the remote device speaks an unknown (newer?) version of the protocol")
)
View Source
var (
	ErrClosed               = errors.New("connection closed")
	ErrTimeout              = errors.New("read timeout")
	ErrSwitchingConnections = errors.New("switching connections")
)
View Source
var LocalDeviceID = DeviceID{0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff}
View Source
var (
	Version13HelloMagic uint32 = 0x9F79BC40
)

Functions

func IsVersionMismatch added in v0.13.6

func IsVersionMismatch(err error) bool

IsVersionMismatch returns true if the error is a reliable indication of a version mismatch that we might want to alert the user about.

func TotalInOut

func TotalInOut() (int64, int64)

Types

type BlockInfo

type BlockInfo struct {
	Offset int64 // noencode (cache only)
	Size   int32
	Hash   []byte // max:64
}

func (BlockInfo) IsEmpty added in v0.12.4

func (b BlockInfo) IsEmpty() bool

IsEmpty returns true if the block is a full block of zeroes.

func (BlockInfo) MarshalXDR

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

func (BlockInfo) MarshalXDRInto added in v0.13.0

func (o BlockInfo) MarshalXDRInto(m *xdr.Marshaller) error

func (BlockInfo) MustMarshalXDR

func (o BlockInfo) MustMarshalXDR() []byte

func (BlockInfo) String

func (b BlockInfo) String() string

func (*BlockInfo) UnmarshalXDR

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

func (*BlockInfo) UnmarshalXDRFrom added in v0.13.0

func (o *BlockInfo) UnmarshalXDRFrom(u *xdr.Unmarshaller) error

func (BlockInfo) XDRSize added in v0.13.0

func (o BlockInfo) XDRSize() int

type CloseMessage

type CloseMessage struct {
	Reason string // max:1024
	Code   int32
}

func (CloseMessage) MarshalXDR

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

func (CloseMessage) MarshalXDRInto added in v0.13.0

func (o CloseMessage) MarshalXDRInto(m *xdr.Marshaller) error

func (CloseMessage) MustMarshalXDR

func (o CloseMessage) MustMarshalXDR() []byte

func (*CloseMessage) UnmarshalXDR

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

func (*CloseMessage) UnmarshalXDRFrom added in v0.13.0

func (o *CloseMessage) UnmarshalXDRFrom(u *xdr.Unmarshaller) error

func (CloseMessage) XDRSize added in v0.13.0

func (o CloseMessage) XDRSize() int

type ClusterConfigMessage

type ClusterConfigMessage struct {
	Folders []Folder // max:1000000
	Options []Option // max:64
}

func (*ClusterConfigMessage) GetOption

func (o *ClusterConfigMessage) GetOption(key string) string

func (ClusterConfigMessage) MarshalXDR

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

func (ClusterConfigMessage) MarshalXDRInto added in v0.13.0

func (o ClusterConfigMessage) MarshalXDRInto(m *xdr.Marshaller) error

func (ClusterConfigMessage) MustMarshalXDR

func (o ClusterConfigMessage) MustMarshalXDR() []byte

func (*ClusterConfigMessage) UnmarshalXDR

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

func (*ClusterConfigMessage) UnmarshalXDRFrom added in v0.13.0

func (o *ClusterConfigMessage) UnmarshalXDRFrom(u *xdr.Unmarshaller) error

func (ClusterConfigMessage) XDRSize added in v0.13.0

func (o ClusterConfigMessage) XDRSize() int

type Compression

type Compression int
const (
	CompressMetadata Compression = iota // zero value is the default, default should be "metadata"
	CompressNever
	CompressAlways
)

func (Compression) GoString

func (c Compression) GoString() string

func (Compression) MarshalText

func (c Compression) MarshalText() ([]byte, error)

func (Compression) String

func (c Compression) String() string

func (*Compression) UnmarshalText

func (c *Compression) UnmarshalText(bs []byte) error

type Connection

type Connection interface {
	Start()
	ID() DeviceID
	Name() string
	Index(folder string, files []FileInfo, flags uint32, options []Option) error
	IndexUpdate(folder string, files []FileInfo, flags uint32, options []Option) error
	Request(folder string, name string, offset int64, size int, hash []byte, fromTemporary bool) ([]byte, error)
	ClusterConfig(config ClusterConfigMessage)
	DownloadProgress(folder string, updates []FileDownloadProgressUpdate, flags uint32, options []Option)
	Statistics() Statistics
	Closed() bool
}

func NewConnection

func NewConnection(deviceID DeviceID, reader io.Reader, writer io.Writer, receiver Model, name string, compress Compression) Connection

type Counter

type Counter struct {
	ID    ShortID
	Value uint64
}

Counter represents a single counter in the version vector.

type Device

type Device struct {
	ID              []byte   // max:32
	Name            string   // max:64
	Addresses       []string // max:64,2083
	Compression     uint32
	CertName        string // max:64
	MaxLocalVersion int64
	Flags           uint32
	Options         []Option // max:64
}

func (Device) MarshalXDR

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

func (Device) MarshalXDRInto added in v0.13.0

func (o Device) MarshalXDRInto(m *xdr.Marshaller) error

func (Device) MustMarshalXDR

func (o Device) MustMarshalXDR() []byte

func (*Device) UnmarshalXDR

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

func (*Device) UnmarshalXDRFrom added in v0.13.0

func (o *Device) UnmarshalXDRFrom(u *xdr.Unmarshaller) error

func (Device) XDRSize added in v0.13.0

func (o Device) XDRSize() int

type DeviceID

type DeviceID [32]byte

func DeviceIDFromBytes

func DeviceIDFromBytes(bs []byte) DeviceID

func DeviceIDFromString

func DeviceIDFromString(s string) (DeviceID, error)

func NewDeviceID

func NewDeviceID(rawCert []byte) DeviceID

NewDeviceID generates a new device ID from the raw bytes of a certificate

func (DeviceID) Compare

func (n DeviceID) Compare(other DeviceID) int

func (DeviceID) Equals

func (n DeviceID) Equals(other DeviceID) bool

func (DeviceID) GoString

func (n DeviceID) GoString() string

func (*DeviceID) MarshalText

func (n *DeviceID) MarshalText() ([]byte, error)

func (DeviceID) Short

func (n DeviceID) Short() ShortID

Short returns an integer representing bits 0-63 of the device ID.

func (DeviceID) String

func (n DeviceID) String() string

String returns the canonical string representation of the device ID

func (*DeviceID) UnmarshalText

func (n *DeviceID) UnmarshalText(bs []byte) error

type DownloadProgressMessage added in v0.13.0

type DownloadProgressMessage struct {
	Folder  string                       // max:64
	Updates []FileDownloadProgressUpdate // max:1000000
	Flags   uint32
	Options []Option // max:64
}

func (DownloadProgressMessage) MarshalXDR added in v0.13.0

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

func (DownloadProgressMessage) MarshalXDRInto added in v0.13.0

func (o DownloadProgressMessage) MarshalXDRInto(m *xdr.Marshaller) error

func (DownloadProgressMessage) MustMarshalXDR added in v0.13.0

func (o DownloadProgressMessage) MustMarshalXDR() []byte

func (*DownloadProgressMessage) UnmarshalXDR added in v0.13.0

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

func (*DownloadProgressMessage) UnmarshalXDRFrom added in v0.13.0

func (o *DownloadProgressMessage) UnmarshalXDRFrom(u *xdr.Unmarshaller) error

func (DownloadProgressMessage) XDRSize added in v0.13.0

func (o DownloadProgressMessage) XDRSize() int

type EmptyMessage

type EmptyMessage struct{}

func (EmptyMessage) MarshalXDR

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

func (EmptyMessage) MarshalXDRInto added in v0.13.0

func (o EmptyMessage) MarshalXDRInto(m *xdr.Marshaller) error

func (EmptyMessage) MustMarshalXDR

func (o EmptyMessage) MustMarshalXDR() []byte

func (*EmptyMessage) UnmarshalXDR

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

func (*EmptyMessage) UnmarshalXDRFrom added in v0.13.0

func (o *EmptyMessage) UnmarshalXDRFrom(u *xdr.Unmarshaller) error

func (EmptyMessage) XDRSize added in v0.13.0

func (o EmptyMessage) XDRSize() int

type FileDownloadProgressUpdate added in v0.13.0

type FileDownloadProgressUpdate struct {
	UpdateType   uint32
	Name         string // max:8192
	Version      Vector
	BlockIndexes []int32 // max:1000000
}

func (FileDownloadProgressUpdate) MarshalXDR added in v0.13.0

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

func (FileDownloadProgressUpdate) MarshalXDRInto added in v0.13.0

func (o FileDownloadProgressUpdate) MarshalXDRInto(m *xdr.Marshaller) error

func (FileDownloadProgressUpdate) MustMarshalXDR added in v0.13.0

func (o FileDownloadProgressUpdate) MustMarshalXDR() []byte

func (*FileDownloadProgressUpdate) UnmarshalXDR added in v0.13.0

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

func (*FileDownloadProgressUpdate) UnmarshalXDRFrom added in v0.13.0

func (o *FileDownloadProgressUpdate) UnmarshalXDRFrom(u *xdr.Unmarshaller) error

func (FileDownloadProgressUpdate) XDRSize added in v0.13.0

func (o FileDownloadProgressUpdate) XDRSize() int

type FileInfo

type FileInfo struct {
	Name         string // max:8192
	Flags        uint32
	Modified     int64
	Version      Vector
	LocalVersion int64
	CachedSize   int64       // noencode (cache only)
	Blocks       []BlockInfo // max:10000000
}

func (FileInfo) HasPermissionBits

func (f FileInfo) HasPermissionBits() bool

func (FileInfo) IsDeleted

func (f FileInfo) IsDeleted() bool

func (FileInfo) IsDirectory

func (f FileInfo) IsDirectory() bool

func (FileInfo) IsInvalid

func (f FileInfo) IsInvalid() bool
func (f FileInfo) IsSymlink() bool

func (FileInfo) MarshalXDR

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

func (FileInfo) MarshalXDRInto added in v0.13.0

func (o FileInfo) MarshalXDRInto(m *xdr.Marshaller) error

func (FileInfo) MustMarshalXDR

func (o FileInfo) MustMarshalXDR() []byte

func (FileInfo) Size

func (f FileInfo) Size() (bytes int64)

func (FileInfo) String

func (f FileInfo) String() string

func (*FileInfo) UnmarshalXDR

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

func (*FileInfo) UnmarshalXDRFrom added in v0.13.0

func (o *FileInfo) UnmarshalXDRFrom(u *xdr.Unmarshaller) error

func (FileInfo) WinsConflict

func (f FileInfo) WinsConflict(other FileInfo) bool

WinsConflict returns true if "f" is the one to choose when it is in conflict with "other".

func (FileInfo) XDRSize added in v0.13.0

func (o FileInfo) XDRSize() int

type Folder

type Folder struct {
	ID      string   // max:256
	Label   string   // max:256
	Devices []Device // max:1000000
	Flags   uint32
	Options []Option // max:64
}

func (Folder) MarshalXDR

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

func (Folder) MarshalXDRInto added in v0.13.0

func (o Folder) MarshalXDRInto(m *xdr.Marshaller) error

func (Folder) MustMarshalXDR

func (o Folder) MustMarshalXDR() []byte

func (*Folder) UnmarshalXDR

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

func (*Folder) UnmarshalXDRFrom added in v0.13.0

func (o *Folder) UnmarshalXDRFrom(u *xdr.Unmarshaller) error

func (Folder) XDRSize added in v0.13.0

func (o Folder) XDRSize() int

type HelloMessage added in v0.13.0

type HelloMessage interface {
	Magic() uint32
	Marshal() ([]byte, error)
}

The HelloMessage interface is implemented by the version specific hello message. It knows its magic number and how to serialize itself to a byte buffer.

type HelloResult added in v0.13.6

type HelloResult struct {
	DeviceName    string
	ClientName    string
	ClientVersion string
}

The HelloResult is the non version specific interpretation of the other side's Hello message.

func ExchangeHello added in v0.13.6

func ExchangeHello(c io.ReadWriter, h HelloMessage) (HelloResult, error)

type IndexMessage

type IndexMessage struct {
	Folder  string     // max:256
	Files   []FileInfo // max:1000000
	Flags   uint32
	Options []Option // max:64
}

func (IndexMessage) MarshalXDR

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

func (IndexMessage) MarshalXDRInto added in v0.13.0

func (o IndexMessage) MarshalXDRInto(m *xdr.Marshaller) error

func (IndexMessage) MustMarshalXDR

func (o IndexMessage) MustMarshalXDR() []byte

func (*IndexMessage) UnmarshalXDR

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

func (*IndexMessage) UnmarshalXDRFrom added in v0.13.0

func (o *IndexMessage) UnmarshalXDRFrom(u *xdr.Unmarshaller) error

func (IndexMessage) XDRSize added in v0.13.0

func (o IndexMessage) XDRSize() int

type Model

type Model interface {
	// An index was received from the peer device
	Index(deviceID DeviceID, folder string, files []FileInfo, flags uint32, options []Option)
	// An index update was received from the peer device
	IndexUpdate(deviceID DeviceID, folder string, files []FileInfo, flags uint32, options []Option)
	// A request was made by the peer device
	Request(deviceID DeviceID, folder string, name string, offset int64, hash []byte, flags uint32, options []Option, buf []byte) error
	// A cluster configuration message was received
	ClusterConfig(deviceID DeviceID, config ClusterConfigMessage)
	// The peer device closed the connection
	Close(deviceID DeviceID, err error)
	// The peer device sent progress updates for the files it is currently downloading
	DownloadProgress(deviceID DeviceID, folder string, updates []FileDownloadProgressUpdate, flags uint32, options []Option)
}

type Option

type Option struct {
	Key   string // max:64
	Value string // max:1024
}

func (Option) MarshalXDR

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

func (Option) MarshalXDRInto added in v0.13.0

func (o Option) MarshalXDRInto(m *xdr.Marshaller) error

func (Option) MustMarshalXDR

func (o Option) MustMarshalXDR() []byte

func (*Option) UnmarshalXDR

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

func (*Option) UnmarshalXDRFrom added in v0.13.0

func (o *Option) UnmarshalXDRFrom(u *xdr.Unmarshaller) error

func (Option) XDRSize added in v0.13.0

func (o Option) XDRSize() int

type Ordering

type Ordering int

Ordering represents the relationship between two Vectors.

const (
	Equal Ordering = iota
	Greater
	Lesser
	ConcurrentLesser
	ConcurrentGreater
)

type RequestMessage

type RequestMessage struct {
	Folder  string // max:256
	Name    string // max:8192
	Offset  int64
	Size    int32
	Hash    []byte // max:64
	Flags   uint32
	Options []Option // max:64
}

func (RequestMessage) MarshalXDR

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

func (RequestMessage) MarshalXDRInto added in v0.13.0

func (o RequestMessage) MarshalXDRInto(m *xdr.Marshaller) error

func (RequestMessage) MustMarshalXDR

func (o RequestMessage) MustMarshalXDR() []byte

func (*RequestMessage) UnmarshalXDR

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

func (*RequestMessage) UnmarshalXDRFrom added in v0.13.0

func (o *RequestMessage) UnmarshalXDRFrom(u *xdr.Unmarshaller) error

func (RequestMessage) XDRSize added in v0.13.0

func (o RequestMessage) XDRSize() int

type ResponseMessage

type ResponseMessage struct {
	Data []byte
	Code int32
}

func (ResponseMessage) MarshalXDR

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

func (ResponseMessage) MarshalXDRInto added in v0.13.0

func (o ResponseMessage) MarshalXDRInto(m *xdr.Marshaller) error

func (ResponseMessage) MustMarshalXDR

func (o ResponseMessage) MustMarshalXDR() []byte

func (*ResponseMessage) UnmarshalXDR

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

func (*ResponseMessage) UnmarshalXDRFrom added in v0.13.0

func (o *ResponseMessage) UnmarshalXDRFrom(u *xdr.Unmarshaller) error

func (ResponseMessage) XDRSize added in v0.13.0

func (o ResponseMessage) XDRSize() int

type ShortID added in v0.12.16

type ShortID uint64

func (ShortID) String added in v0.12.16

func (s ShortID) String() string

type Statistics

type Statistics struct {
	At            time.Time
	InBytesTotal  int64
	OutBytesTotal int64
}

type Vector

type Vector []Counter

The Vector type represents a version vector. The zero value is a usable version vector. The vector has slice semantics and some operations on it are "append-like" in that they may return the same vector modified, or v new allocated Vector with the modified contents.

func (Vector) Compare

func (a Vector) Compare(b Vector) Ordering

Compare returns the Ordering that describes a's relation to b.

func (Vector) Concurrent

func (v Vector) Concurrent(b Vector) bool

Concurrent returns true when the two vectors are concurrent.

func (Vector) Copy

func (v Vector) Copy() Vector

Copy returns an identical vector that is not shared with v.

func (Vector) Counter

func (v Vector) Counter(id ShortID) uint64

Counter returns the current value of the given counter ID.

func (Vector) Equal

func (v Vector) Equal(b Vector) bool

Equal returns true when the two vectors are equivalent.

func (Vector) GreaterEqual

func (v Vector) GreaterEqual(b Vector) bool

GreaterEqual returns true when the two vectors are equivalent or v is Greater than b.

func (Vector) LesserEqual

func (v Vector) LesserEqual(b Vector) bool

LesserEqual returns true when the two vectors are equivalent or v is Lesser than b.

func (Vector) MarshalXDRInto added in v0.13.0

func (v Vector) MarshalXDRInto(m *xdr.Marshaller) error

func (Vector) Merge

func (v Vector) Merge(b Vector) Vector

Merge returns the vector containing the maximum indexes from v and b. If it is possible, the vector v is updated and returned. If it is not, a copy will be created, updated and returned.

func (*Vector) UnmarshalXDRFrom added in v0.13.0

func (v *Vector) UnmarshalXDRFrom(u *xdr.Unmarshaller) error

func (Vector) Update

func (v Vector) Update(id ShortID) Vector

Update returns a Vector with the index for the specific ID incremented by one. If it is possible, the vector v is updated and returned. If it is not, a copy will be created, updated and returned.

func (Vector) XDRSize added in v0.13.0

func (v Vector) XDRSize() int

type Version13HelloMessage added in v0.13.6

type Version13HelloMessage struct {
	DeviceName    string // max:64
	ClientName    string // max:64
	ClientVersion string // max:64
}

func (Version13HelloMessage) Magic added in v0.13.6

func (m Version13HelloMessage) Magic() uint32

func (Version13HelloMessage) Marshal added in v0.13.6

func (m Version13HelloMessage) Marshal() ([]byte, error)

func (Version13HelloMessage) MarshalXDR added in v0.13.6

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

func (Version13HelloMessage) MarshalXDRInto added in v0.13.6

func (o Version13HelloMessage) MarshalXDRInto(m *xdr.Marshaller) error

func (Version13HelloMessage) MustMarshalXDR added in v0.13.6

func (o Version13HelloMessage) MustMarshalXDR() []byte

func (*Version13HelloMessage) UnmarshalXDR added in v0.13.6

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

func (*Version13HelloMessage) UnmarshalXDRFrom added in v0.13.6

func (o *Version13HelloMessage) UnmarshalXDRFrom(u *xdr.Unmarshaller) error

func (Version13HelloMessage) XDRSize added in v0.13.6

func (o Version13HelloMessage) XDRSize() int

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL