sonda/internal/federation/federation.go
tgiachi 29bd46c3ba feat(federation): browse and search a friend's catalogue
A listener can now browse the music that a friend's server shares.

- GET /friends lists the friends both admins agreed to, by id and name; an
  address or a key is for the admin only. It is empty while federation is off.
- GET /friends/{friend}/artists, albums and tracks (q, limit, offset,
  artist_id, album_id) and the one-item routes: this server asks the friend
  with a request signed by its own key and passes the page on. The answer is
  read into this API's own types first, so what a friend adds is dropped and
  the shape is the one in the spec. Nothing is kept, and the ids are the
  friend's own.
- Only the three kinds of thing can be asked, and only the parameters their
  routes take: a listener cannot make this server ask a friend for anything
  else. The friend's address and what the connection said never reach a
  listener.
- A friend that cannot be reached, no longer takes this server for a friend,
  is busy or is not there is told in words, never as an error page.
- The client of friends gets a generic signed GET with a size limit.
- The web app has a Friends entry in the menu, shown only when there is a
  friend to browse, a list of friends and a page for each with artists,
  albums and songs, a search and links from an artist to its albums and from
  an album to its songs, in English and Italian.
- OpenAPI paths and schemas, contract test with a friend that is a whole
  server, and two real servers checked end to end.
2026-11-13 15:59:26 +01:00

124 lines
5.3 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")
)
// 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
}