feat(federation): shared libraries and the signed read API for friends

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.
This commit is contained in:
tgiachi 2026-11-13 15:04:07 +01:00
commit 89826fcd07
3 changed files with 3970 additions and 60 deletions

View file

@ -5,12 +5,17 @@ import type { components } from './schema'
export type Federation = components['schemas']['Federation']
export type FederationFriend = components['schemas']['FederationFriend']
export type FederationInvite = components['schemas']['FederationInvite']
export type FederationRequest = components['schemas']['FederationRequest']
/** What `PUT /federation` takes: any of these, and what is left out is kept. */
export interface FederationChanges {
enabled?: boolean
name?: string
address?: string
/** Streams one friend may have open at a time, 1 to 20. */
max_streams?: number
/** KiB a second one friend may take; 0 means no limit, otherwise 64 or more. */
max_kib_per_sec?: number
}
const FEDERATION = ['federation']
@ -60,3 +65,21 @@ export function useRemoveFriend() {
onSuccess: () => client.invalidateQueries({ queryKey: FEDERATION }),
})
}
/** Asks a friend that is waiting, signed, whether it approved: an answer makes it a friend. */
export function useCheckFriend() {
const client = useQueryClient()
return useMutation({
mutationFn: (id: number) => api.post<FederationFriend>(`/federation/friends/${id}/check`),
onSuccess: () => client.invalidateQueries({ queryKey: FEDERATION }),
})
}
/** The last requests friends made to this server, newest first. */
export function useFederationRequests() {
return useQuery({
queryKey: [...FEDERATION, 'requests'],
queryFn: () => api.get<{ requests: FederationRequest[] }>('/federation/requests'),
select: (data) => data.requests,
})
}

View file

@ -26,11 +26,11 @@ export function useAddLibrary() {
})
}
/** Rename, move, or both: only the fields given are sent. */
/** Rename, move, share with friends, or any of them: only the fields given are sent. */
export function useUpdateLibrary() {
const client = useQueryClient()
return useMutation({
mutationFn: ({ id, ...changes }: { id: number; name?: string; path?: string }) => api.patch<Library>(`/libraries/${id}`, changes),
mutationFn: ({ id, ...changes }: { id: number; name?: string; path?: string; shared?: boolean }) => api.patch<Library>(`/libraries/${id}`, changes),
onSuccess: () => client.invalidateQueries({ queryKey: LIBRARIES }),
})
}

View file

@ -2163,6 +2163,241 @@ export interface paths {
patch?: never;
trace?: never;
};
"/federation/friends/{id}/check": {
parameters: {
query?: never;
header?: never;
path: {
id: number;
};
cookie?: never;
};
get?: never;
put?: never;
/**
* Ask a friend whether it approved
* @description Admin only. Sends the friend one signed request (`GET /peer/info`). An answer means it approved, and a friend that
* was `outgoing` becomes `active`. The friend is returned. A friend in state `incoming` is a `409` (`not_waiting`):
* it waits for this server's admin, not the other way round.
*/
post: operations["checkFederationFriend"];
delete?: never;
options?: never;
head?: never;
patch?: never;
trace?: never;
};
"/federation/requests": {
parameters: {
query?: never;
header?: never;
path?: never;
cookie?: never;
};
/**
* The last requests friends made
* @description Admin only. The last 50 requests that friends made to this server, newest first, kept for 7 days: when, which
* friend, which route (the pattern, never the query, so what was searched for is not kept), the status and how many
* bytes were sent.
*/
get: operations["listFederationRequests"];
put?: never;
post?: never;
delete?: never;
options?: never;
head?: never;
patch?: never;
trace?: never;
};
"/peer/info": {
parameters: {
query?: never;
header?: never;
path?: never;
cookie?: never;
};
/**
* Who this server is (called by a friend)
* @description Not for people: a friend's server calls this, signed (see the `friendSignature` scheme), and also to find out whether
* this server's admin approved it. Says the name of this server and how many libraries are shared.
*/
get: operations["peerInfo"];
put?: never;
post?: never;
delete?: never;
options?: never;
head?: never;
patch?: never;
trace?: never;
};
"/peer/artists": {
parameters: {
query?: never;
header?: never;
path?: never;
cookie?: never;
};
/**
* The artists of the shared libraries (called by a friend)
* @description Like `GET /artists`, over the libraries that are shared and nothing else: an artist is listed only when it has a
* playable track in one of them, and the counts are of those tracks. Paths, library ids and everything that providers
* said are never part of it. Signed like every `/peer` route.
*/
get: operations["peerListArtists"];
put?: never;
post?: never;
delete?: never;
options?: never;
head?: never;
patch?: never;
trace?: never;
};
"/peer/artists/{id}": {
parameters: {
query?: never;
header?: never;
path: {
id: components["parameters"]["Id"];
};
cookie?: never;
};
/** One artist of the shared libraries (called by a friend) */
get: operations["peerGetArtist"];
put?: never;
post?: never;
delete?: never;
options?: never;
head?: never;
patch?: never;
trace?: never;
};
"/peer/albums": {
parameters: {
query?: never;
header?: never;
path?: never;
cookie?: never;
};
/**
* The albums of the shared libraries (called by a friend)
* @description Like `GET /albums`, over the libraries that are shared. Signed like every `/peer` route.
*/
get: operations["peerListAlbums"];
put?: never;
post?: never;
delete?: never;
options?: never;
head?: never;
patch?: never;
trace?: never;
};
"/peer/albums/{id}": {
parameters: {
query?: never;
header?: never;
path: {
id: components["parameters"]["Id"];
};
cookie?: never;
};
/** One album of the shared libraries (called by a friend) */
get: operations["peerGetAlbum"];
put?: never;
post?: never;
delete?: never;
options?: never;
head?: never;
patch?: never;
trace?: never;
};
"/peer/albums/{id}/cover": {
parameters: {
query?: never;
header?: never;
path: {
id: components["parameters"]["Id"];
};
cookie?: never;
};
/**
* The cover of an album of the shared libraries (called by a friend)
* @description Only a cover that this server already built from the audio files of the album: a friend never makes this server
* build one, read an audio file or ask a provider. A cover that came from the Cover Art Archive is not given. Any other
* album answers `cover_not_found`. The bytes go out within the friend's allowance.
*/
get: operations["peerGetAlbumCover"];
put?: never;
post?: never;
delete?: never;
options?: never;
head?: never;
patch?: never;
trace?: never;
};
"/peer/tracks": {
parameters: {
query?: never;
header?: never;
path?: never;
cookie?: never;
};
/**
* The tracks of the shared libraries (called by a friend)
* @description Like `GET /tracks`, over the libraries that are shared. Signed like every `/peer` route.
*/
get: operations["peerListTracks"];
put?: never;
post?: never;
delete?: never;
options?: never;
head?: never;
patch?: never;
trace?: never;
};
"/peer/tracks/{id}": {
parameters: {
query?: never;
header?: never;
path: {
id: components["parameters"]["Id"];
};
cookie?: never;
};
/** One track of the shared libraries (called by a friend) */
get: operations["peerGetTrack"];
put?: never;
post?: never;
delete?: never;
options?: never;
head?: never;
patch?: never;
trace?: never;
};
"/peer/tracks/{id}/stream": {
parameters: {
query?: never;
header?: never;
path: {
id: components["parameters"]["Id"];
};
cookie?: never;
};
/**
* Stream a track of the shared libraries (called by a friend)
* @description The file of the track that lives in a shared library, with `Range` support, as a listener would get it. A track that is
* only in libraries that are not shared is `track_not_found`. A friend has a few streams open at a time and a number
* of bytes a second to share among them, both set by the admin (`max_streams`, `max_kib_per_sec`): one stream too many
* is a `429` (`too_many_streams`) with `Retry-After`.
*/
get: operations["peerStreamTrack"];
put?: never;
post?: never;
delete?: never;
options?: never;
head?: never;
patch?: never;
trace?: never;
};
}
export type webhooks = Record<string, never>;
export interface components {
@ -2236,6 +2471,8 @@ export interface components {
name: string;
/** @description Absolute directory on the server. */
path: string;
/** @description Whether friends (federation) may read this library. Off until an admin turns it on. */
shared: boolean;
/** Format: date-time */
created_at: string;
};
@ -2247,7 +2484,9 @@ export interface components {
LibraryUpdate: {
name?: string;
path?: string;
} | unknown | unknown;
/** @description Whether friends may read this library. Changing it never needs a scan and never waits for one. */
shared?: boolean;
} | unknown | unknown | unknown;
ScanSummary: {
/** @description Libraries covered by the scan. */
libraries: number;
@ -3207,14 +3446,40 @@ export interface components {
key_id: string;
/** @description What a friend's server is sent, and what it never learns. */
sends: string;
/** @description Streams one friend may have open at a time. */
max_streams: number;
/** @description KiB a second one friend may take over all its streams; 0 means no limit. Otherwise at least 64. */
max_kib_per_sec: number;
friends: components["schemas"]["FederationFriend"][];
};
FederationUpdate: {
enabled?: boolean;
max_streams?: number;
max_kib_per_sec?: number;
/** @description At most 60 characters, no control characters. Empty goes back to the host name. */
name?: string;
address?: string;
} | unknown | unknown | unknown;
} | unknown | unknown | unknown | unknown | unknown;
FederationRequest: {
/** Format: date-time */
at: string;
friend_id: number;
/** @description The name of the friend. */
friend: string;
/** @description The route pattern, like `/api/v1/peer/tracks/:id/stream`. Never the query. */
route: string;
status: number;
/**
* Format: int64
* @description Bytes of the answer.
*/
bytes: number;
};
PeerInfo: {
name: string;
/** @description How many libraries are shared with friends. */
shared_libraries: number;
};
FederationInvite: {
/** @description One piece of text to give to the other admin. Starts with `sonda1.`. */
invite: string;
@ -3256,6 +3521,33 @@ export interface components {
};
};
responses: {
/** @description The request is not signed by a friend: no signature, a bad one, an old date, a nonce used before or an unknown key, all the same answer (`unauthorized`). */
FriendUnauthorized: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
/** @description The signature is good but the admin of this server has not approved the friend yet (`not_approved`). */
FriendNotApproved: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
/** @description Federation is off on this server, so the route is as good as missing (`not_found`). */
FederationOff: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
/** @description The request is malformed or a value is out of range (`invalid_input`). */
InvalidInput: {
headers: {
@ -7040,4 +7332,442 @@ export interface operations {
};
};
};
checkFederationFriend: {
parameters: {
query?: never;
header?: never;
path: {
id: number;
};
cookie?: never;
};
requestBody?: never;
responses: {
/** @description The friend, active when it answered. */
200: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["FederationFriend"];
};
};
400: components["responses"]["InvalidInput"];
401: components["responses"]["Unauthorized"];
403: components["responses"]["AdminRequired"];
/** @description No such friend (`friend_not_found`). */
404: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
/**
* @description Federation is off (`federation_off`), the friend is not waiting for the other admin (`not_waiting`), the other
* admin has not approved yet (`not_approved`), or the other server does not take this one for a friend any more
* (`friend_gone`).
*/
409: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
/** @description The other server could not be reached or did not answer as a Sonda server (`friend_unreachable`). */
502: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
};
};
listFederationRequests: {
parameters: {
query?: never;
header?: never;
path?: never;
cookie?: never;
};
requestBody?: never;
responses: {
/** @description The requests. */
200: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": {
requests: components["schemas"]["FederationRequest"][];
};
};
};
401: components["responses"]["Unauthorized"];
403: components["responses"]["AdminRequired"];
};
};
peerInfo: {
parameters: {
query?: never;
header?: never;
path?: never;
cookie?: never;
};
requestBody?: never;
responses: {
/** @description The name and the number of shared libraries. */
200: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["PeerInfo"];
};
};
401: components["responses"]["FriendUnauthorized"];
403: components["responses"]["FriendNotApproved"];
404: components["responses"]["FederationOff"];
};
};
peerListArtists: {
parameters: {
query?: {
/**
* @description Case- and accent-insensitive substring of the name or title: `bjork`, `BJORK` and `BJÖRK` all
* find `Björk`, and `strasse` finds `Straße`. At most 200 characters.
*/
q?: components["parameters"]["Q"];
/** @description Page size. 50 when absent or 0; values above 200 are lowered to 200. */
limit?: components["parameters"]["Limit"];
offset?: components["parameters"]["Offset"];
};
header?: never;
path?: never;
cookie?: never;
};
requestBody?: never;
responses: {
/** @description A page of artists. */
200: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["ArtistPage"];
};
};
400: components["responses"]["InvalidInput"];
401: components["responses"]["FriendUnauthorized"];
403: components["responses"]["FriendNotApproved"];
404: components["responses"]["FederationOff"];
};
};
peerGetArtist: {
parameters: {
query?: never;
header?: never;
path: {
id: components["parameters"]["Id"];
};
cookie?: never;
};
requestBody?: never;
responses: {
/** @description The artist. */
200: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Artist"];
};
};
400: components["responses"]["InvalidInput"];
401: components["responses"]["FriendUnauthorized"];
403: components["responses"]["FriendNotApproved"];
/** @description No such artist among the shared libraries (`artist_not_found`), or federation is off (`not_found`). */
404: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
};
};
peerListAlbums: {
parameters: {
query?: {
/**
* @description Case- and accent-insensitive substring of the name or title: `bjork`, `BJORK` and `BJÖRK` all
* find `Björk`, and `strasse` finds `Straße`. At most 200 characters.
*/
q?: components["parameters"]["Q"];
/** @description Page size. 50 when absent or 0; values above 200 are lowered to 200. */
limit?: components["parameters"]["Limit"];
offset?: components["parameters"]["Offset"];
artist_id?: components["parameters"]["ArtistId"];
};
header?: never;
path?: never;
cookie?: never;
};
requestBody?: never;
responses: {
/** @description A page of albums. */
200: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["AlbumPage"];
};
};
400: components["responses"]["InvalidInput"];
401: components["responses"]["FriendUnauthorized"];
403: components["responses"]["FriendNotApproved"];
404: components["responses"]["FederationOff"];
};
};
peerGetAlbum: {
parameters: {
query?: never;
header?: never;
path: {
id: components["parameters"]["Id"];
};
cookie?: never;
};
requestBody?: never;
responses: {
/** @description The album. */
200: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Album"];
};
};
400: components["responses"]["InvalidInput"];
401: components["responses"]["FriendUnauthorized"];
403: components["responses"]["FriendNotApproved"];
/** @description No such album among the shared libraries (`album_not_found`), or federation is off (`not_found`). */
404: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
};
};
peerGetAlbumCover: {
parameters: {
query?: {
/** @description `small` or `large`. Large when absent. */
size?: "small" | "large";
};
header?: {
"If-None-Match"?: string;
};
path: {
id: components["parameters"]["Id"];
};
cookie?: never;
};
requestBody?: never;
responses: {
/** @description The cover. */
200: {
headers: {
ETag: components["headers"]["ETag"];
"Cache-Control": components["headers"]["CacheControl"];
"Content-Length": components["headers"]["ContentLength"];
[name: string]: unknown;
};
content: {
"image/jpeg": string;
};
};
/** @description Not modified since `If-None-Match`. */
304: {
headers: {
[name: string]: unknown;
};
content?: never;
};
400: components["responses"]["InvalidInput"];
401: components["responses"]["FriendUnauthorized"];
403: components["responses"]["FriendNotApproved"];
/** @description No such album among the shared libraries (`album_not_found`), no cover built (`cover_not_found`), or federation is off (`not_found`). */
404: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
};
};
peerListTracks: {
parameters: {
query?: {
/**
* @description Case- and accent-insensitive substring of the name or title: `bjork`, `BJORK` and `BJÖRK` all
* find `Björk`, and `strasse` finds `Straße`. At most 200 characters.
*/
q?: components["parameters"]["Q"];
/** @description Page size. 50 when absent or 0; values above 200 are lowered to 200. */
limit?: components["parameters"]["Limit"];
offset?: components["parameters"]["Offset"];
artist_id?: components["parameters"]["ArtistId"];
album_id?: components["parameters"]["AlbumId"];
};
header?: never;
path?: never;
cookie?: never;
};
requestBody?: never;
responses: {
/** @description A page of tracks. */
200: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["TrackPage"];
};
};
400: components["responses"]["InvalidInput"];
401: components["responses"]["FriendUnauthorized"];
403: components["responses"]["FriendNotApproved"];
404: components["responses"]["FederationOff"];
};
};
peerGetTrack: {
parameters: {
query?: never;
header?: never;
path: {
id: components["parameters"]["Id"];
};
cookie?: never;
};
requestBody?: never;
responses: {
/** @description The track. */
200: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Track"];
};
};
400: components["responses"]["InvalidInput"];
401: components["responses"]["FriendUnauthorized"];
403: components["responses"]["FriendNotApproved"];
/** @description No such track among the shared libraries (`track_not_found`), or federation is off (`not_found`). */
404: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
};
};
peerStreamTrack: {
parameters: {
query?: never;
header?: {
/** @description A byte range, for example `bytes=0-99`. */
Range?: string;
"If-Modified-Since"?: string;
};
path: {
id: components["parameters"]["Id"];
};
cookie?: never;
};
requestBody?: never;
responses: {
/** @description The whole file. */
200: {
headers: {
"Accept-Ranges": components["headers"]["AcceptRanges"];
"Content-Length": components["headers"]["ContentLength"];
"Last-Modified": components["headers"]["LastModified"];
[name: string]: unknown;
};
content: {
"audio/mpeg": string;
"audio/flac": string;
};
};
/** @description The requested byte range. */
206: {
headers: {
/** @description The range sent and the size of the file, for example `bytes 0-99/40635`. */
"Content-Range"?: string;
[name: string]: unknown;
};
content: {
"audio/mpeg": string;
"audio/flac": string;
"multipart/byteranges": string;
};
};
/** @description Not modified since `If-Modified-Since`. */
304: {
headers: {
[name: string]: unknown;
};
content?: never;
};
400: components["responses"]["InvalidInput"];
401: components["responses"]["FriendUnauthorized"];
403: components["responses"]["FriendNotApproved"];
/** @description No such track among the shared libraries (`track_not_found`), its file is not available (`file_missing`), or federation is off (`not_found`). */
404: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
/** @description The range cannot be satisfied. */
416: {
headers: {
/** @description `bytes *\/<size of the file>`. */
"Content-Range"?: string;
[name: string]: unknown;
};
content?: never;
};
/** @description The friend already has as many streams open as allowed (`too_many_streams`). */
429: {
headers: {
/** @description Seconds to wait. */
"Retry-After"?: number;
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
};
};
}