fleet

package module
v0.12.24 Latest Latest
Warning

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

 Go to latest Published: Oct 21, 2024 License: MIT Imports: 56 Imported by: 1

README

Fleet system

Allows peers to connect to each other when run within a fleet system.

Documentation

See: https://godoc.org/github.com/KarpelesLab/fleet

Documentation

Index

Constants

View Source 
const (
	PacketMaxLen     = 32 * 1024 * 1024 // 32MB
	PacketHeaderSize = 6                // 2 bytes packet code, 4 bytes packet length
	PacketMaxBody    = PacketMaxLen - PacketHeaderSize

	PacketLegacy      = 0xffff // legacy gob-encoded packet
	PacketPing        = 0x1001
	PacketPong        = 0x3001
	PacketLockReq     = 0x1002 // request for lock
	PacketLockRes     = 0x3002 // response (aye or nay)
	PacketLockConfirm = 0x1003 // lock is confirmed (or re-confirmed) → status = 1
	PacketLockRelease = 0x1004 // lock is released
	PacketSeed        = 0x1005 // seed data
	PacketRpcBinReq   = 0x1006
	PacketRpcBinRes   = 0x3006
	PacketClose       = 0x1fff

	PacketCustom    = 0xa000 // 0xa000 ~ 0xafff are custom channels
	PacketCustomMax = 0xafff

	Aye = 1
	Nay = 0
)
View Source 
const UUID_SEEDID_SPACE = "da736663-83ec-46ef-9c29-3f9102c5c519"

Variables

View Source 
var (
	ErrWriteQueueFull   = errors.New("peer write queue is full")
	ErrPeerNoRoute      = errors.New("no route to peer")
	ErrConnectionClosed = errors.New("connection has been closed")
	ErrInvalidLegacy    = errors.New("invalid operation on legacy peer")
	ErrInvalidLockName  = errors.New("invalid lock name")
	ErrCancelledLock    = errors.New("lock request has been cancelled")
	ErrEndpointNameLen  = errors.New("RPC endpoint name length too long")
)

Functions

func CallRpcEndpoint added in v0.3.23 

func CallRpcEndpoint(e string, p any) (res any, err error)

CallRpcEndpoint will call the named RPC endpoint on the local machine

func Custom added in v0.5.12 

func Custom(v uint16) uint16

Custom returns a packet id for a given custom packet Typically you will define your custom packet as follow: 

var MyCustomPacket = fleet.Custom(0)

func EnsureDir 

func EnsureDir(c string) error

func GetSelfsignedCertificate added in v0.8.3 

func GetSelfsignedCertificate(n string) (*tls.Certificate, error)

GetSelfsignedCertificate is a utility function that returns a self-signed certificate for any given host name

All generated certificates are cached, and calling this method multiple times with the same name will return the same certificate for a few days, and will then generate a new certificate.

func IsReady added in v0.11.8 

func IsReady() bool

IsReady returns true if the fleet is initiated and configured properly

func SetCustomHandler added in v0.5.12 

func SetCustomHandler(pc uint16, h CustomHandler)

func SetRpcEndpoint 

func SetRpcEndpoint(e string, f RpcEndpoint)

func UniqueTimestamp added in v0.6.15 

func UniqueTimestamp() uint64

UniqueTimestamp returns a uint64 timestamp in microsecond that is unique, so that even if called multiple times in the same millisecond each call will return a different value.

This can be safely called from multiple threads, it does not lock.

Types

type Agent 

type Agent struct {
	IP string // ip as seen from outside

	Events *emitter.Hub

	// getfile callback
	GetFile GetFileFunc
	// contains filtered or unexported fields
}

func New added in v0.5.0 

func New(opts ...AgentOption) *Agent

New will just initialize a basic agent without any settings

func Self added in v0.5.0 

func Self() *Agent

Self returns the Agent instance returned by New() (or similar), and will wait if instance has not been instanciated yet. As such, Self() should not be used in func init(), but only in separate goroutines or after instance has been created.

func WithGetFile added in v0.5.0 

func WithGetFile(f GetFileFunc, opts ...AgentOption) *Agent

return a new agent using the provided GetFile method

func WithIssuer added in v0.5.0 

func WithIssuer(url string, opts ...AgentOption) *Agent

func (*Agent) AddService added in v0.5.0 

func (a *Agent) AddService(service string) (net.Listener, error)

func (*Agent) AllRPC added in v0.5.7 

func (a *Agent) AllRPC(ctx context.Context, endpoint string, data any) ([]any, error)

func (*Agent) AllRpcRequest added in v0.9.5 

func (a *Agent) AllRpcRequest(ctx context.Context, endpoint string, data []byte) ([]any, error)

func (*Agent) AltNames added in v0.11.19 

func (a *Agent) AltNames() []string

AltNames will attempt to return alternative names from the certificate issued to this node

func (*Agent) AnyRpc added in v0.5.0 

func (a *Agent) AnyRpc(ctx context.Context, division string, endpoint string, data any) error

func (*Agent) BroadcastPacket added in v0.5.12 

func (a *Agent) BroadcastPacket(ctx context.Context, pc uint16, data []byte) error

func (*Agent) BroadcastRpc added in v0.5.0 

func (a *Agent) BroadcastRpc(ctx context.Context, endpoint string, data any) error

BroadcastRpc broadcasts the given data to the specified endpoint

func (*Agent) BroadcastRpcBin added in v0.9.5 

func (a *Agent) BroadcastRpcBin(ctx context.Context, endpoint string, pkt []byte) (n int, err error)

func (*Agent) CacheDir added in v0.6.9 

func (a *Agent) CacheDir() string

func (*Agent) Close added in v0.5.0 

func (a *Agent) Close()

func (*Agent) ConfigureTlsServer added in v0.5.0 

func (a *Agent) ConfigureTlsServer(cfg *tls.Config)

func (*Agent) Connect added in v0.5.0 

func (a *Agent) Connect(id string, service string) (net.Conn, error)

connect to given peer under specified protocol (if supported)

func (*Agent) CountPeers added in v0.6.8 

func (a *Agent) CountPeers() int

func (*Agent) DbDelete added in v0.8.2 

func (a *Agent) DbDelete(key string) error

DbDelete will remove a value from the shared fleet database

func (*Agent) DbGet added in v0.5.0 

func (a *Agent) DbGet(key string) ([]byte, error)

DbGet will get a value from the shared fleet database

func (*Agent) DbKeys added in v0.12.20 

func (a *Agent) DbKeys(bucket, prefix []byte) func(yield func(k, v []byte) bool)

func (*Agent) DbSet added in v0.5.0 

func (a *Agent) DbSet(key string, value []byte) error

DbSet will set a value into the shared fleet database

func (*Agent) DbWatch added in v0.5.0 

func (a *Agent) DbWatch(key string, cb func(string, []byte))

DbWatch will trigger the cb function upon updates of the given key Special key "*" covers all keys (can only be one callback for a key) If the value is nil, it means it is being deleted

func (*Agent) DebugLocks added in v0.6.21 

func (a *Agent) DebugLocks(w io.Writer)

func (*Agent) Dial added in v0.5.0 

func (a *Agent) Dial(network, addr string) (net.Conn, error)

func (*Agent) DialContext added in v0.5.0 

func (a *Agent) DialContext(c context.Context, network, addr string) (net.Conn, error)

func (*Agent) Division added in v0.11.22 

func (a *Agent) Division() string

Division returns the division (locality) of the local node

func (*Agent) DivisionPrefixRpc added in v0.5.0 

func (a *Agent) DivisionPrefixRpc(ctx context.Context, divMatch string, endpoint string, data any) error

func (*Agent) DivisionRpc added in v0.5.0 

func (a *Agent) DivisionRpc(ctx context.Context, division int, endpoint string, data any) error

func (*Agent) DumpInfo added in v0.5.0 

func (a *Agent) DumpInfo(w io.Writer)

func (*Agent) ExternalKey added in v0.11.12 

func (a *Agent) ExternalKey() (crypto.PrivateKey, error)

ExternalKey returns the key associated with the cluster, if any. If this host hasn't joined a cluster or the cluster has no shared key, this will return fs.ErrNotExist

func (*Agent) GenInternalCert added in v0.5.0 

func (a *Agent) GenInternalCert() (tls.Certificate, error)

func (*Agent) GetCA added in v0.5.0 

func (a *Agent) GetCA() (*x509.CertPool, error)

func (*Agent) GetClientTlsConfig added in v0.5.0 

func (a *Agent) GetClientTlsConfig() (*tls.Config, error)

func (*Agent) GetInternalCertificate added in v0.7.0 

func (a *Agent) GetInternalCertificate(h *tls.ClientHelloInfo) (*tls.Certificate, error)

return internal certificate (cached)

func (*Agent) GetInternalTlsConfig added in v0.5.11 

func (a *Agent) GetInternalTlsConfig() (*tls.Config, error)

func (*Agent) GetPeer added in v0.5.0 

func (a *Agent) GetPeer(id string) *Peer

func (*Agent) GetPeerByName added in v0.5.0 

func (a *Agent) GetPeerByName(name string) *Peer

func (*Agent) GetPeers added in v0.5.0 

func (a *Agent) GetPeers() []*Peer

func (*Agent) GetPeersCount added in v0.6.12 

func (a *Agent) GetPeersCount() uint32

GetPeersCount return the number of existing peers, connected or not. The value may be more than the number of entries GetPeers will return as some peers may be down or unavailable.

func (*Agent) GetPublicCertificate added in v0.7.0 

func (a *Agent) GetPublicCertificate(h *tls.ClientHelloInfo) (*tls.Certificate, error)

func (*Agent) GetStatus added in v0.10.0 

func (a *Agent) GetStatus() int

func (*Agent) GetStringSetting added in v0.10.7 

func (a *Agent) GetStringSetting(v string) string

func (*Agent) GetTlsConfig added in v0.5.0 

func (a *Agent) GetTlsConfig() (*tls.Config, error)

GetTlsConfig returns TLS config suitable for making public facing ssl servers.

func (*Agent) Id added in v0.5.0 

func (a *Agent) Id() string

Id returns the id of the local node

func (*Agent) InternalKey added in v0.11.12 

func (a *Agent) InternalKey() (crypto.Signer, error)

InternalKey returns the key associated with the local host, possibly a TPM key if the host has a functioning tpm.

func (*Agent) IsConnected added in v0.5.0 

func (a *Agent) IsConnected(id string) bool

func (*Agent) KeyShake128 deprecated added in v0.5.4 

func (a *Agent) KeyShake128(N []byte) (sha3.ShakeHash, error)

KeyShake128 uses PKCS8 private key blob as hash key

Deprecated: won't work with TPM machines

func (*Agent) KeyShake256 deprecated added in v0.5.4 

func (a *Agent) KeyShake256(N []byte) (sha3.ShakeHash, error)

KeySha256 uses PKCS8 private key blob as hash key

Deprecated: won't work with TPM machines

func (*Agent) Lock added in v0.6.12 

func (a *Agent) Lock(ctx context.Context, name string) (*LocalLock, error)

func (*Agent) MetaSet added in v0.6.10 

func (a *Agent) MetaSet(key string, value any)

func (*Agent) Name added in v0.5.0 

func (a *Agent) Name() (string, string)

Name returns the name and hostname of the local node

func (*Agent) NewRpcInstance added in v0.9.4 

func (a *Agent) NewRpcInstance(name string) (RPC, error)

func (*Agent) RPC added in v0.5.0 

func (a *Agent) RPC(ctx context.Context, id string, endpoint string, data any) (any, error)

func (*Agent) RoundTripper added in v0.5.0 

func (a *Agent) RoundTripper() http.RoundTripper

func (*Agent) RpcRequest added in v0.9.5 

func (a *Agent) RpcRequest(ctx context.Context, id string, endpoint string, data []byte) ([]byte, error)

func (*Agent) RpcSend added in v0.9.5 

func (a *Agent) RpcSend(ctx context.Context, id string, endpoint string, data []byte) error

RpcSend sends a request but expects no response, failure will only reported if the request failed to be sent, and failure on the other side will not be reported

func (*Agent) SeedCrypt added in v0.5.0 

func (a *Agent) SeedCrypt(in []byte) ([]byte, error)

func (*Agent) SeedDecrypt added in v0.5.0 

func (a *Agent) SeedDecrypt(in []byte) ([]byte, error)

func (*Agent) SeedId added in v0.5.0 

func (a *Agent) SeedId() uuid.UUID

func (*Agent) SeedShake128 added in v0.5.4 

func (a *Agent) SeedShake128(N []byte) sha3.ShakeHash

func (*Agent) SeedShake256 added in v0.5.4 

func (a *Agent) SeedShake256(N []byte) sha3.ShakeHash

func (*Agent) SeedSign added in v0.5.0 

func (a *Agent) SeedSign(in []byte) []byte

func (*Agent) SeedTlsConfig added in v0.5.0 

func (a *Agent) SeedTlsConfig(c *tls.Config)

func (*Agent) SendPacketTo added in v0.5.12 

func (a *Agent) SendPacketTo(ctx context.Context, target string, pc uint16, data []byte) error

func (*Agent) SendTo added in v0.5.0 

func (a *Agent) SendTo(ctx context.Context, target string, pkt any) error

func (*Agent) Settings added in v0.10.0 

func (a *Agent) Settings() (map[string]any, error)

Settings fetches the current settings from the global system and returns these if the system is initializing, this will block until initialization is done

func (*Agent) Spot added in v0.12.18 

func (a *Agent) Spot() *spotlib.Client

func (*Agent) SwitchChannel added in v0.8.7 

func (a *Agent) SwitchChannel(channel string) error

SwitchChannel will signal the whole fleet to switch to the given channel for the currently running software. This can be used to switch between stable and beta versions and the like. Attempting to switch to a non-existing channel will trigger errors across the fleet.

func (*Agent) WaitReady added in v0.10.0 

func (a *Agent) WaitReady()

WaitReady will lock until the agent is ready for operation (connected to other peers)

type AgentOption added in v0.6.12 

type AgentOption interface {
	// contains filtered or unexported methods
}

type CustomHandler added in v0.5.12 

type CustomHandler func(p *Peer, data []byte) error

type DbStamp 

type DbStamp time.Time

a timestamp for db

func DbNow 

func DbNow() DbStamp

func DbZero 

func DbZero() DbStamp

func (DbStamp) After 

func (t DbStamp) After(t2 DbStamp) bool

func (DbStamp) Bytes added in v0.5.7 

func (t DbStamp) Bytes() []byte

func (*DbStamp) GobDecode 

func (t *DbStamp) GobDecode(data []byte) error

func (DbStamp) GobEncode 

func (t DbStamp) GobEncode() ([]byte, error)

func (DbStamp) MarshalBinary 

func (t DbStamp) MarshalBinary() ([]byte, error)

func (DbStamp) String 

func (t DbStamp) String() string

func (DbStamp) Unix 

func (t DbStamp) Unix() int64

func (DbStamp) UnixNano 

func (t DbStamp) UnixNano() int64

func (*DbStamp) UnmarshalBinary 

func (t *DbStamp) UnmarshalBinary(data []byte) error

type DbWatchCallback added in v0.3.16 

type DbWatchCallback func(string, []byte)

type GetFileFunc added in v0.5.0 

type GetFileFunc func(*Agent, string) ([]byte, error)

type LocalLock added in v0.6.12 

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

func (*LocalLock) Release added in v0.6.12 

func (lk *LocalLock) Release()

type Packet 

type Packet any

type PacketAnnounce 

type PacketAnnounce struct {
	Id   string
	Now  time.Time
	Idx  uint64
	NumG uint32 // number of goroutines
	AZ   string
	Meta map[string]any
}

type PacketDbRecord 

type PacketDbRecord struct {
	TargetId string
	SourceId string
	Stamp    DbStamp
	Bucket   []byte // typically "app"
	Key, Val []byte
}

type PacketDbRequest added in v0.3.14 

type PacketDbRequest struct {
	TargetId string
	SourceId string
	Bucket   []byte // typically "app"
	Key      []byte
}

PacketDbRequest requests a specific record, response will be a PacketDbRecord

type PacketDbVersions added in v0.3.14 

type PacketDbVersions struct {
	Info []*PacketDbVersionsEntry
}

PacketDbVersions signals what records are available in a peer, typically sent on connection established

type PacketDbVersionsEntry added in v0.3.14 

type PacketDbVersionsEntry struct {
	Stamp  DbStamp
	Bucket []byte // typically "app"
	Key    []byte
}

type PacketHandshake 

type PacketHandshake struct {
	Id       string
	Name     string
	Division string
	Now      time.Time

	Git     string
	Build   string
	Channel string
}

type PacketRpc 

type PacketRpc struct {
	TargetId string
	SourceId string
	Endpoint string
	R        rchan.Id
	Data     any
}

type PacketRpcResponse 

type PacketRpcResponse struct {
	TargetId string
	SourceId string
	R        rchan.Id
	Data     any
	Error    string
	HasError bool
}

type Peer 

type Peer struct {
	Ping time.Duration
	// contains filtered or unexported fields
}

func (*Peer) Addr added in v0.11.20 

func (p *Peer) Addr() net.Addr

func (*Peer) Agent added in v0.5.12 

func (p *Peer) Agent() *Agent

Agent returns the Agent object associated with this peer

func (*Peer) Close added in v0.3.19 

func (p *Peer) Close(reason string) error

func (*Peer) Division added in v0.5.12 

func (p *Peer) Division() string

Division returns this peer's division string

func (*Peer) Id added in v0.5.12 

func (p *Peer) Id() string

Id returns the peer's internal ID, which is unique and can be used to send packets to this peer specifically in the future.

func (*Peer) IsAlive added in v0.12.3 

func (p *Peer) IsAlive() bool

func (*Peer) Meta added in v0.6.10 

func (p *Peer) Meta() map[string]any

func (*Peer) Name added in v0.5.12 

func (p *Peer) Name() string

Name returns this peer's name

func (*Peer) RemoteAddr added in v0.8.11 

func (p *Peer) RemoteAddr() net.Addr

func (*Peer) Send 

func (p *Peer) Send(ctx context.Context, pkt Packet) error

func (*Peer) String added in v0.6.29 

func (p *Peer) String() string

func (*Peer) WritePacket added in v0.5.7 

func (p *Peer) WritePacket(ctx context.Context, pc uint16, data []byte) error

type RPC added in v0.9.4 

type RPC interface {
	// All will send a given data object to all other RPC instances on the fleet
	// and will collect responses
	All(ctx context.Context, data []byte) ([]any, error)

	// Broadcast will do the same as All but will not wait for responses
	Broadcast(ctx context.Context, data []byte) error

	// Request will send a given object to a specific peer and return the response
	Request(ctx context.Context, id string, data []byte) ([]byte, error)

	// Send will send a given object to a specific peer but ignore the response
	Send(ctx context.Context, id string, data []byte) error

	// Self will return the id of the local peer, can be used for other instances
	// to contact here with Send().
	Self() string

	// ListOnlinePeers returns a list of connected peers
	ListOnlinePeers() []string

	// CountAllPeers return the number of known connected or offline peers
	CountAllPeers() int

	// Connect connects this RPC instance incoming events to a given function
	// that will be called each time an event is received.
	Connect(cb func(context.Context, []byte) ([]byte, error))
}

type RpcEndpoint 

type RpcEndpoint func(any) (any, error)

RpcEndpoint represents a callback function for the legacy RPC system

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.