sonda/internal/federation/federation.go
tgiachi 7243fe7a04 feat: the seek bar shows the waveform of a friend's track
A friend's server works out the peaks of a track in a shared library and gives
them to a signed friend (GET /peer/tracks/{id}/peaks). This server asks for them
and passes them on to the listener after checking them: 1 to 1000 levels from 0
to 255, as many as the count says (GET /friends/{friend}/tracks/{id}/peaks). The
player uses it for a friend's track, so its bar is no longer flat.
2026-11-13 19:46:37 +01:00

128 lines
5.6 KiB
Go

// 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
}