A friend's server can now read what an admin chose to share.
- A library has a shared flag, off by default (migration 0024), set with
PATCH /libraries/{id}. Changing it never waits for a scan.
- Requests between friends are signed with each server's Ed25519 key: the
method, the path and query from /api/v1/peer on, a date, a nonce and the
hash of the empty body. A date more than two minutes off, a nonce used
before, an unknown or removed key and a bad signature all get the same
401. A friend still waiting for approval gets 403, and while federation is
off the routes are missing.
- Routes under /api/v1/peer: info, artists, albums, tracks, covers and
streaming with Range. The catalogue, the counts and the format come from
the shared libraries only, and the file served is the one in a shared
library. No path, library id, listen, taste, user or provider data is part
of an answer.
- A friend never makes this server build a cover, read an audio file or ask
a provider: only covers already built from the audio files are served.
- Per-friend limits, set by the admin: parallel streams (default 3) and KiB
a second (default 4096, 0 for none), shared by all the streams of a friend.
- A log of the last requests friends made (route, status, bytes; never the
query), kept for 7 days, in GET /federation/requests.
- POST /federation/friends/{id}/check lets the side that pasted an invite
find out that the other admin approved; a signed call from a friend this
server is waiting for makes it active too.
- Admin: a Shared with friends switch on each library, which asks first, and
limits, recent requests and a Check button in the Federation section, in
English and Italian.
- OpenAPI paths and schemas, contract test, two real servers checked end to
end with tagged audio files.
122 lines
5.1 KiB
Go
122 lines
5.1 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")
|
|
)
|
|
|
|
// 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
|
|
}
|