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:
parent
346466c621
commit
89826fcd07
1 changed files with 3970 additions and 60 deletions
|
|
@ -3162,6 +3162,346 @@ paths:
|
|||
application/json:
|
||||
schema: {$ref: '#/components/schemas/Error'}
|
||||
|
||||
/federation/friends/{id}/check:
|
||||
parameters:
|
||||
- {name: id, in: path, required: true, schema: {type: integer}}
|
||||
post:
|
||||
tags: [Federation]
|
||||
operationId: checkFederationFriend
|
||||
summary: 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.
|
||||
security: [{bearerAuth: []}]
|
||||
responses:
|
||||
'200':
|
||||
description: The friend, active when it answered.
|
||||
content:
|
||||
application/json:
|
||||
schema: {$ref: '#/components/schemas/FederationFriend'}
|
||||
'400': {$ref: '#/components/responses/InvalidInput'}
|
||||
'401': {$ref: '#/components/responses/Unauthorized'}
|
||||
'403': {$ref: '#/components/responses/AdminRequired'}
|
||||
'404':
|
||||
description: No such friend (`friend_not_found`).
|
||||
content:
|
||||
application/json:
|
||||
schema: {$ref: '#/components/schemas/Error'}
|
||||
'409':
|
||||
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`).
|
||||
content:
|
||||
application/json:
|
||||
schema: {$ref: '#/components/schemas/Error'}
|
||||
'502':
|
||||
description: The other server could not be reached or did not answer as a Sonda server (`friend_unreachable`).
|
||||
content:
|
||||
application/json:
|
||||
schema: {$ref: '#/components/schemas/Error'}
|
||||
|
||||
/federation/requests:
|
||||
get:
|
||||
tags: [Federation]
|
||||
operationId: listFederationRequests
|
||||
summary: 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.
|
||||
security: [{bearerAuth: []}]
|
||||
responses:
|
||||
'200':
|
||||
description: The requests.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
additionalProperties: false
|
||||
required: [requests]
|
||||
properties:
|
||||
requests:
|
||||
type: array
|
||||
items: {$ref: '#/components/schemas/FederationRequest'}
|
||||
'401': {$ref: '#/components/responses/Unauthorized'}
|
||||
'403': {$ref: '#/components/responses/AdminRequired'}
|
||||
|
||||
/peer/info:
|
||||
get:
|
||||
tags: [Federation]
|
||||
operationId: peerInfo
|
||||
summary: 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.
|
||||
security: [{friendSignature: []}]
|
||||
responses:
|
||||
'200':
|
||||
description: The name and the number of shared libraries.
|
||||
content:
|
||||
application/json:
|
||||
schema: {$ref: '#/components/schemas/PeerInfo'}
|
||||
'401': {$ref: '#/components/responses/FriendUnauthorized'}
|
||||
'403': {$ref: '#/components/responses/FriendNotApproved'}
|
||||
'404': {$ref: '#/components/responses/FederationOff'}
|
||||
|
||||
/peer/artists:
|
||||
get:
|
||||
tags: [Federation]
|
||||
operationId: peerListArtists
|
||||
summary: 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.
|
||||
security: [{friendSignature: []}]
|
||||
parameters:
|
||||
- {$ref: '#/components/parameters/Q'}
|
||||
- {$ref: '#/components/parameters/Limit'}
|
||||
- {$ref: '#/components/parameters/Offset'}
|
||||
responses:
|
||||
'200':
|
||||
description: A page of artists.
|
||||
content:
|
||||
application/json:
|
||||
schema: {$ref: '#/components/schemas/ArtistPage'}
|
||||
'400': {$ref: '#/components/responses/InvalidInput'}
|
||||
'401': {$ref: '#/components/responses/FriendUnauthorized'}
|
||||
'403': {$ref: '#/components/responses/FriendNotApproved'}
|
||||
'404': {$ref: '#/components/responses/FederationOff'}
|
||||
|
||||
/peer/artists/{id}:
|
||||
parameters:
|
||||
- {$ref: '#/components/parameters/Id'}
|
||||
get:
|
||||
tags: [Federation]
|
||||
operationId: peerGetArtist
|
||||
summary: One artist of the shared libraries (called by a friend)
|
||||
security: [{friendSignature: []}]
|
||||
responses:
|
||||
'200':
|
||||
description: The artist.
|
||||
content:
|
||||
application/json:
|
||||
schema: {$ref: '#/components/schemas/Artist'}
|
||||
'400': {$ref: '#/components/responses/InvalidInput'}
|
||||
'401': {$ref: '#/components/responses/FriendUnauthorized'}
|
||||
'403': {$ref: '#/components/responses/FriendNotApproved'}
|
||||
'404':
|
||||
description: No such artist among the shared libraries (`artist_not_found`), or federation is off (`not_found`).
|
||||
content:
|
||||
application/json:
|
||||
schema: {$ref: '#/components/schemas/Error'}
|
||||
|
||||
/peer/albums:
|
||||
get:
|
||||
tags: [Federation]
|
||||
operationId: peerListAlbums
|
||||
summary: 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.
|
||||
security: [{friendSignature: []}]
|
||||
parameters:
|
||||
- {$ref: '#/components/parameters/Q'}
|
||||
- {$ref: '#/components/parameters/Limit'}
|
||||
- {$ref: '#/components/parameters/Offset'}
|
||||
- {$ref: '#/components/parameters/ArtistId'}
|
||||
responses:
|
||||
'200':
|
||||
description: A page of albums.
|
||||
content:
|
||||
application/json:
|
||||
schema: {$ref: '#/components/schemas/AlbumPage'}
|
||||
'400': {$ref: '#/components/responses/InvalidInput'}
|
||||
'401': {$ref: '#/components/responses/FriendUnauthorized'}
|
||||
'403': {$ref: '#/components/responses/FriendNotApproved'}
|
||||
'404': {$ref: '#/components/responses/FederationOff'}
|
||||
|
||||
/peer/albums/{id}:
|
||||
parameters:
|
||||
- {$ref: '#/components/parameters/Id'}
|
||||
get:
|
||||
tags: [Federation]
|
||||
operationId: peerGetAlbum
|
||||
summary: One album of the shared libraries (called by a friend)
|
||||
security: [{friendSignature: []}]
|
||||
responses:
|
||||
'200':
|
||||
description: The album.
|
||||
content:
|
||||
application/json:
|
||||
schema: {$ref: '#/components/schemas/Album'}
|
||||
'400': {$ref: '#/components/responses/InvalidInput'}
|
||||
'401': {$ref: '#/components/responses/FriendUnauthorized'}
|
||||
'403': {$ref: '#/components/responses/FriendNotApproved'}
|
||||
'404':
|
||||
description: No such album among the shared libraries (`album_not_found`), or federation is off (`not_found`).
|
||||
content:
|
||||
application/json:
|
||||
schema: {$ref: '#/components/schemas/Error'}
|
||||
|
||||
/peer/albums/{id}/cover:
|
||||
parameters:
|
||||
- {$ref: '#/components/parameters/Id'}
|
||||
get:
|
||||
tags: [Federation]
|
||||
operationId: peerGetAlbumCover
|
||||
summary: 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.
|
||||
security: [{friendSignature: []}]
|
||||
parameters:
|
||||
- name: size
|
||||
in: query
|
||||
description: "`small` or `large`. Large when absent."
|
||||
schema: {type: string, enum: [small, large], default: large}
|
||||
- name: If-None-Match
|
||||
in: header
|
||||
required: false
|
||||
schema: {type: string}
|
||||
responses:
|
||||
'200':
|
||||
description: The cover.
|
||||
headers:
|
||||
ETag: {$ref: '#/components/headers/ETag'}
|
||||
Cache-Control: {$ref: '#/components/headers/CacheControl'}
|
||||
Content-Length: {$ref: '#/components/headers/ContentLength'}
|
||||
content:
|
||||
image/jpeg:
|
||||
schema: {type: string, format: binary}
|
||||
'304': {description: Not modified since `If-None-Match`.}
|
||||
'400': {$ref: '#/components/responses/InvalidInput'}
|
||||
'401': {$ref: '#/components/responses/FriendUnauthorized'}
|
||||
'403': {$ref: '#/components/responses/FriendNotApproved'}
|
||||
'404':
|
||||
description: No such album among the shared libraries (`album_not_found`), no cover built (`cover_not_found`), or federation is off (`not_found`).
|
||||
content:
|
||||
application/json:
|
||||
schema: {$ref: '#/components/schemas/Error'}
|
||||
|
||||
/peer/tracks:
|
||||
get:
|
||||
tags: [Federation]
|
||||
operationId: peerListTracks
|
||||
summary: 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.
|
||||
security: [{friendSignature: []}]
|
||||
parameters:
|
||||
- {$ref: '#/components/parameters/Q'}
|
||||
- {$ref: '#/components/parameters/Limit'}
|
||||
- {$ref: '#/components/parameters/Offset'}
|
||||
- {$ref: '#/components/parameters/ArtistId'}
|
||||
- {$ref: '#/components/parameters/AlbumId'}
|
||||
responses:
|
||||
'200':
|
||||
description: A page of tracks.
|
||||
content:
|
||||
application/json:
|
||||
schema: {$ref: '#/components/schemas/TrackPage'}
|
||||
'400': {$ref: '#/components/responses/InvalidInput'}
|
||||
'401': {$ref: '#/components/responses/FriendUnauthorized'}
|
||||
'403': {$ref: '#/components/responses/FriendNotApproved'}
|
||||
'404': {$ref: '#/components/responses/FederationOff'}
|
||||
|
||||
/peer/tracks/{id}:
|
||||
parameters:
|
||||
- {$ref: '#/components/parameters/Id'}
|
||||
get:
|
||||
tags: [Federation]
|
||||
operationId: peerGetTrack
|
||||
summary: One track of the shared libraries (called by a friend)
|
||||
security: [{friendSignature: []}]
|
||||
responses:
|
||||
'200':
|
||||
description: The track.
|
||||
content:
|
||||
application/json:
|
||||
schema: {$ref: '#/components/schemas/Track'}
|
||||
'400': {$ref: '#/components/responses/InvalidInput'}
|
||||
'401': {$ref: '#/components/responses/FriendUnauthorized'}
|
||||
'403': {$ref: '#/components/responses/FriendNotApproved'}
|
||||
'404':
|
||||
description: No such track among the shared libraries (`track_not_found`), or federation is off (`not_found`).
|
||||
content:
|
||||
application/json:
|
||||
schema: {$ref: '#/components/schemas/Error'}
|
||||
|
||||
/peer/tracks/{id}/stream:
|
||||
parameters:
|
||||
- {$ref: '#/components/parameters/Id'}
|
||||
get:
|
||||
tags: [Federation]
|
||||
operationId: peerStreamTrack
|
||||
summary: 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`.
|
||||
security: [{friendSignature: []}]
|
||||
parameters:
|
||||
- name: Range
|
||||
in: header
|
||||
required: false
|
||||
description: A byte range, for example `bytes=0-99`.
|
||||
schema: {type: string}
|
||||
- name: If-Modified-Since
|
||||
in: header
|
||||
required: false
|
||||
schema: {type: string}
|
||||
responses:
|
||||
'200':
|
||||
description: The whole file.
|
||||
headers:
|
||||
Accept-Ranges: {$ref: '#/components/headers/AcceptRanges'}
|
||||
Content-Length: {$ref: '#/components/headers/ContentLength'}
|
||||
Last-Modified: {$ref: '#/components/headers/LastModified'}
|
||||
content:
|
||||
audio/mpeg:
|
||||
schema: {type: string, format: binary}
|
||||
audio/flac:
|
||||
schema: {type: string, format: binary}
|
||||
'206':
|
||||
description: The requested byte range.
|
||||
headers:
|
||||
Content-Range:
|
||||
description: The range sent and the size of the file, for example `bytes 0-99/40635`.
|
||||
schema: {type: string}
|
||||
content:
|
||||
audio/mpeg:
|
||||
schema: {type: string, format: binary}
|
||||
audio/flac:
|
||||
schema: {type: string, format: binary}
|
||||
multipart/byteranges:
|
||||
schema: {type: string, format: binary}
|
||||
'304': {description: Not modified since `If-Modified-Since`.}
|
||||
'400': {$ref: '#/components/responses/InvalidInput'}
|
||||
'401': {$ref: '#/components/responses/FriendUnauthorized'}
|
||||
'403': {$ref: '#/components/responses/FriendNotApproved'}
|
||||
'404':
|
||||
description: No such track among the shared libraries (`track_not_found`), its file is not available (`file_missing`), or federation is off (`not_found`).
|
||||
content:
|
||||
application/json:
|
||||
schema: {$ref: '#/components/schemas/Error'}
|
||||
'416':
|
||||
description: The range cannot be satisfied.
|
||||
headers:
|
||||
Content-Range:
|
||||
description: '`bytes */<size of the file>`.'
|
||||
schema: {type: string}
|
||||
'429':
|
||||
description: The friend already has as many streams open as allowed (`too_many_streams`).
|
||||
headers:
|
||||
Retry-After:
|
||||
description: Seconds to wait.
|
||||
schema: {type: integer}
|
||||
content:
|
||||
application/json:
|
||||
schema: {$ref: '#/components/schemas/Error'}
|
||||
|
||||
components:
|
||||
securitySchemes:
|
||||
bearerAuth:
|
||||
|
|
@ -3175,6 +3515,18 @@ components:
|
|||
name: access_token
|
||||
description: The same access token, for stream URLs used by an `<audio>` element. Accepted only on `/tracks/{id}/stream`, `/albums/{id}/cover` and `/artists/{id}/image`.
|
||||
|
||||
friendSignature:
|
||||
type: apiKey
|
||||
in: header
|
||||
name: Sonda-Signature
|
||||
description: |
|
||||
For the routes under `/peer`, which only another Sonda server calls. Each request carries four headers:
|
||||
`Sonda-Key-Id` (the first 16 hex characters of the SHA-256 of the sender's public key), `Sonda-Date` (unix
|
||||
seconds, at most two minutes from the receiver's clock), `Sonda-Nonce` (16 to 64 characters of `A-Za-z0-9_-`, never
|
||||
used twice) and `Sonda-Signature` (the Ed25519 signature, base64url without padding, of these five lines:
|
||||
the method, the path from `/api/v1/peer` on with the query as sent, the date, the nonce and the SHA-256 in hex of
|
||||
the body, which is empty). Anything that is not properly signed gets the same `401`.
|
||||
|
||||
parameters:
|
||||
Id:
|
||||
name: id
|
||||
|
|
@ -3244,6 +3596,21 @@ components:
|
|||
schema: {type: string}
|
||||
|
||||
responses:
|
||||
FriendUnauthorized:
|
||||
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`)."
|
||||
content:
|
||||
application/json:
|
||||
schema: {$ref: '#/components/schemas/Error'}
|
||||
FriendNotApproved:
|
||||
description: The signature is good but the admin of this server has not approved the friend yet (`not_approved`).
|
||||
content:
|
||||
application/json:
|
||||
schema: {$ref: '#/components/schemas/Error'}
|
||||
FederationOff:
|
||||
description: Federation is off on this server, so the route is as good as missing (`not_found`).
|
||||
content:
|
||||
application/json:
|
||||
schema: {$ref: '#/components/schemas/Error'}
|
||||
InvalidInput:
|
||||
description: The request is malformed or a value is out of range (`invalid_input`).
|
||||
content:
|
||||
|
|
@ -3390,11 +3757,12 @@ components:
|
|||
Library:
|
||||
type: object
|
||||
additionalProperties: false
|
||||
required: [id, name, path, created_at]
|
||||
required: [id, name, path, shared, created_at]
|
||||
properties:
|
||||
id: {type: integer, format: int64}
|
||||
name: {type: string}
|
||||
path: {type: string, description: Absolute directory on the server.}
|
||||
shared: {type: boolean, description: Whether friends (federation) may read this library. Off until an admin turns it on.}
|
||||
created_at: {type: string, format: date-time}
|
||||
|
||||
NewLibrary:
|
||||
|
|
@ -3409,9 +3777,11 @@ components:
|
|||
anyOf:
|
||||
- required: [name]
|
||||
- required: [path]
|
||||
- required: [shared]
|
||||
properties:
|
||||
name: {type: string, minLength: 1, maxLength: 100}
|
||||
path: {type: string}
|
||||
shared: {type: boolean, description: "Whether friends may read this library. Changing it never needs a scan and never waits for one."}
|
||||
|
||||
ScanSummary:
|
||||
type: object
|
||||
|
|
@ -4505,13 +4875,15 @@ components:
|
|||
Federation:
|
||||
type: object
|
||||
additionalProperties: false
|
||||
required: [enabled, name, address, key_id, sends, friends]
|
||||
required: [enabled, name, address, key_id, sends, max_streams, max_kib_per_sec, friends]
|
||||
properties:
|
||||
enabled: {type: boolean, description: Whether this server may pair with others. Off by default.}
|
||||
name: {type: string, description: How friends see this server.}
|
||||
address: {type: string, description: Where friends reach this server; empty until set.}
|
||||
key_id: {type: string, description: "Names this server's key; empty until federation was first turned on. Compare it with the one the other admin sees."}
|
||||
sends: {type: string, description: "What a friend's server is sent, and what it never learns."}
|
||||
max_streams: {type: integer, minimum: 1, maximum: 20, description: Streams one friend may have open at a time.}
|
||||
max_kib_per_sec: {type: integer, minimum: 0, maximum: 102400, description: "KiB a second one friend may take over all its streams; 0 means no limit. Otherwise at least 64."}
|
||||
friends:
|
||||
type: array
|
||||
items: {$ref: '#/components/schemas/FederationFriend'}
|
||||
|
|
@ -4522,10 +4894,32 @@ components:
|
|||
- required: [enabled]
|
||||
- required: [name]
|
||||
- required: [address]
|
||||
- required: [max_streams]
|
||||
- required: [max_kib_per_sec]
|
||||
properties:
|
||||
enabled: {type: boolean}
|
||||
max_streams: {type: integer}
|
||||
max_kib_per_sec: {type: integer}
|
||||
name: {type: string, maxLength: 240, description: "At most 60 characters, no control characters. Empty goes back to the host name."}
|
||||
address: {type: string, maxLength: 300}
|
||||
FederationRequest:
|
||||
type: object
|
||||
additionalProperties: false
|
||||
required: [at, friend_id, friend, route, status, bytes]
|
||||
properties:
|
||||
at: {type: string, format: date-time}
|
||||
friend_id: {type: integer}
|
||||
friend: {type: string, description: The name of the friend.}
|
||||
route: {type: string, description: "The route pattern, like `/api/v1/peer/tracks/:id/stream`. Never the query."}
|
||||
status: {type: integer}
|
||||
bytes: {type: integer, format: int64, description: Bytes of the answer.}
|
||||
PeerInfo:
|
||||
type: object
|
||||
additionalProperties: false
|
||||
required: [name, shared_libraries]
|
||||
properties:
|
||||
name: {type: string}
|
||||
shared_libraries: {type: integer, description: How many libraries are shared with friends.}
|
||||
FederationInvite:
|
||||
type: object
|
||||
additionalProperties: false
|
||||
|
|
|
|||
Loading…
Reference in a new issue