// Package federation lets two Sonda servers become friends: each one's listeners can play the libraries the // other's admin chose to share, read only. Nothing leaves a server unless its admin decides it, so federation is off // until an admin turns it on, and a friend is made only by an invite and two confirmations. // // This file holds the types and the contract of the store. The rules are in service.go, the call to the other // server in client.go. package federation import ( "context" "crypto/ed25519" "crypto/sha256" "encoding/hex" "errors" "time" ) // Errors returned by the service. Handlers map them to HTTP statuses. var ( ErrOff = errors.New("federation is off") ErrNoAddress = errors.New("this server has no public address yet") ErrInvalidInput = errors.New("invalid federation input") ErrInvalidInvite = errors.New("the invite is not valid") ErrAlreadyFriend = errors.New("this server is already a friend") ErrFriendMissing = errors.New("no such friend") ErrWrongState = errors.New("the friend is not waiting for approval") ErrTooMany = errors.New("too many pairing attempts: try again in a minute") ErrUnreachable = errors.New("the other server could not be reached") ErrRefused = errors.New("the other server refused the invite: it may be used, expired or federation off there") ErrKeyMismatch = errors.New("the other server's key is not the one in the invite") // ErrUnauthorized is every way a request from a friend can fail to be signed properly: no signature, a bad one, // an old date, a nonce seen before, an unknown key. It says no more, so a stranger learns nothing. ErrUnauthorized = errors.New("the request is not signed by a friend") // ErrNotApproved: the signature is good but the friendship is waiting for an admin's approval. ErrNotApproved = errors.New("the friendship is not approved yet") // ErrNotFriend: the other server does not take this server for a friend (it removed it, or federation is off there). ErrNotFriend = errors.New("the other server does not take this server for a friend") ErrTooManyStreams = errors.New("this friend already has as many streams open as allowed") // ErrNotFoundThere: the friend has no such artist, album or track among what it shares. ErrNotFoundThere = errors.New("the friend has no such item") // ErrWorking: the friend is working out the shape of the track; ask again in a moment. ErrWorking = errors.New("the friend is working out the waveform") // ErrNoWaveform: the friend cannot work out the shape of this track (a format it does not decode). ErrNoWaveform = errors.New("the friend has no waveform for this track") ) // Defaults of the limits a friend is held to, and what they may be set to. const ( DefaultMaxStreams = 3 DefaultMaxKiBPerSec = 4096 ) // State of a friend. type State string // The states a friend goes through. const ( // Incoming: they used an invite of mine and wait for my approval. Incoming State = "incoming" // Outgoing: I used an invite of theirs and wait for their approval. Outgoing State = "outgoing" // Active: both sides agreed. Active State = "active" ) // Settings of this server's federation. The private key never leaves the service: the API shows the key id only. type Settings struct { Enabled bool Name string // shown to friends; empty means the host name Address string // where friends reach this server, normalised PublicKey ed25519.PublicKey PrivateKey ed25519.PrivateKey UpdatedAt time.Time MaxStreams int // parallel streams one friend may have MaxKiBPerSec int // bytes a friend may take, in KiB a second, over all its streams; 0 means no limit } // FriendRequest is one request a friend made to this server, as it is logged. type FriendRequest struct { At time.Time FriendID int64 FriendName string // filled in when listed Route string // the route pattern, never the query Status int Bytes int64 } // Friend is another Sonda server. type Friend struct { ID int64 Name string Address string PublicKey ed25519.PublicKey State State CreatedAt time.Time ApprovedAt time.Time // zero until active } // KeyID is the short name of a key: the first 16 hex characters of its SHA-256. func KeyID(pub ed25519.PublicKey) string { sum := sha256.Sum256(pub) return hex.EncodeToString(sum[:])[:16] } // Store persists federation state. type Store interface { // Settings returns found=false until they were first saved. Settings(ctx context.Context) (s Settings, found bool, err error) SaveSettings(ctx context.Context, s Settings) error AddInvite(ctx context.Context, codeHash string, created, expires time.Time) error // UseInvite marks an unused, unexpired invite as used and says whether there was one. UseInvite(ctx context.Context, codeHash string, now time.Time) (bool, error) Friends(ctx context.Context) ([]Friend, error) Friend(ctx context.Context, id int64) (Friend, error) // ErrFriendMissing FriendByKey(ctx context.Context, key ed25519.PublicKey) (Friend, bool, error) AddFriend(ctx context.Context, f Friend) (Friend, error) // ErrAlreadyFriend when the key is known Approve(ctx context.Context, id int64, now time.Time) error // incoming to active; ErrFriendMissing, ErrWrongState Activate(ctx context.Context, id int64, now time.Time) error // outgoing to active; ErrFriendMissing, ErrWrongState DeleteFriend(ctx context.Context, id int64) error // ErrFriendMissing LogRequest(ctx context.Context, r FriendRequest) error Requests(ctx context.Context, limit int) ([]FriendRequest, error) // newest first, with the friend's name PruneRequests(ctx context.Context, before time.Time) error }