fix(api): make the spec say what the code does, and make the tests prove it

- fix(spec): album.artist and track.album are real nullable objects (OpenAPI
  3.0 only honours nullable next to a type); the stream documents 304 on HEAD,
  412, If-Unmodified-Since and multipart/byteranges answers
- fix(spec): passwords and idempotency keys are measured in bytes, an overlap
  between libraries is a 400, a library PATCH needs a name or a path, limit 0
  means the default, login has no format rules of its own, and the wording about
  signing out says that issued access tokens live until they expire
- fix(auth): the Bearer scheme is matched ignoring case (RFC 7235)
- fix(listening): a listen with the access token of a deleted account is a 401
  instead of a database error
- fix(docs): the docs pages answer HEAD and carry X-Frame-Options, a CSP
  frame-ancestors, nosniff and no-referrer, since people paste their token there
- test: error codes are asserted in every error case; every accepted request is
  validated against the spec too; HEAD and 3xx answers are checked by hand
  because the validator skips them; the stream Content-Type must be one the
  spec lists; a scan held mid-way proves the scan_running conflicts; null album
  and null album artist, a vanished file, multi-range, 412 and HEAD 304 are
  exercised. Verified by breaking the code and the spec on purpose
This commit is contained in:
tgiachi 2026-11-11 14:46:28 +01:00
commit 2ae4aedac0

View file

@ -104,7 +104,7 @@ paths:
required: true
content:
application/json:
schema: {$ref: '#/components/schemas/Credentials'}
schema: {$ref: '#/components/schemas/LoginRequest'}
responses:
'200':
description: A new session.
@ -127,7 +127,8 @@ paths:
Exchanges a refresh token for a new access token and a new refresh token. The old refresh
token stops working. Presenting a spent one again, more than ten seconds after it was used,
ends every session of that user; inside those ten seconds it only fails, so two tabs
refreshing together do not log each other out.
refreshing together do not log each other out. This holds for any spent token, including
one revoked by logout or by a password change.
requestBody:
required: true
content:
@ -180,7 +181,9 @@ paths:
tags: [Auth]
operationId: changePassword
summary: Change your password
description: "Signs you out everywhere: every refresh token of the account is revoked."
description: |
Revokes every refresh token of the account, so no session can be renewed. An access token
that was already issued keeps working until it expires (15 minutes by default).
security: [{bearerAuth: []}]
requestBody:
required: true
@ -286,7 +289,10 @@ paths:
tags: [Users]
operationId: deleteUser
summary: Delete a user
description: Admin only. Removes the account and its sessions. The last admin cannot be deleted.
description: |
Admin only. Removes the account and its refresh tokens. Access tokens already issued stop
working at once on admin routes, `/auth/me`, `/auth/password` and `/listens`; other routes
accept them until they expire (15 minutes by default). The last admin cannot be deleted.
security: [{bearerAuth: []}]
responses:
'204': {description: Deleted.}
@ -311,7 +317,9 @@ paths:
tags: [Users]
operationId: resetUserPassword
summary: Reset a user's password
description: Admin only. Signs that user out everywhere.
description: |
Admin only. Revokes every refresh token of that user, so no session can be renewed. Access
tokens already issued keep working until they expire (15 minutes by default).
security: [{bearerAuth: []}]
requestBody:
required: true
@ -321,7 +329,10 @@ paths:
type: object
required: [password]
properties:
password: {type: string, format: password, minLength: 8, maxLength: 256}
password:
type: string
format: password
description: 8 to 256 bytes (UTF-8).
responses:
'204': {description: Password reset.}
'400': {$ref: '#/components/responses/InvalidInput'}
@ -361,7 +372,9 @@ paths:
summary: Add a library
description: |
Admin only. The path must be an absolute, existing directory, never the filesystem root,
and never inside or around another library. Names are unique ignoring case.
and never inside or around another library (a bad path or an overlap is `400 invalid_input`).
A name or path that another library already uses is `409 library_exists`. Names are unique
ignoring case.
security: [{bearerAuth: []}]
requestBody:
required: true
@ -652,6 +665,10 @@ paths:
in: header
required: false
schema: {type: string}
- name: If-Unmodified-Since
in: header
required: false
schema: {type: string}
responses:
'200':
description: The whole file.
@ -665,17 +682,22 @@ paths:
audio/flac:
schema: {type: string, format: binary}
'206':
description: The requested byte range.
description: |
The requested byte range. Several ranges in one request are answered as
`multipart/byteranges`.
headers:
Content-Range:
description: The range sent and the size of the file, for example `bytes 0-99/40635`.
description: The range sent and the size of the file, for example `bytes 0-99/40635`. Absent for a multipart answer.
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`.}
'412': {description: '`If-Unmodified-Since` names a date before the last change of the file.'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'404':
@ -702,6 +724,14 @@ paths:
in: header
required: false
schema: {type: string}
- name: If-Modified-Since
in: header
required: false
schema: {type: string}
- name: If-Unmodified-Since
in: header
required: false
schema: {type: string}
responses:
'200':
description: Headers of the whole file.
@ -714,9 +744,11 @@ paths:
headers:
Content-Range:
schema: {type: string}
'304': {description: Not modified since `If-Modified-Since`.}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'404': {description: No such track or file.}
'412': {description: '`If-Unmodified-Since` names a date before the last change of the file.'}
'416': {description: The range cannot be satisfied.}
/listens:
@ -781,8 +813,8 @@ components:
Limit:
name: limit
in: query
description: Page size. Default 50; values above 200 are lowered to 200.
schema: {type: integer, minimum: 0}
description: Page size. 50 when absent or 0; values above 200 are lowered to 200.
schema: {type: integer, minimum: 0, default: 50}
Offset:
name: offset
in: query
@ -869,7 +901,17 @@ components:
minLength: 3
maxLength: 64
pattern: '^[A-Za-z0-9._-]+$'
password: {type: string, format: password, minLength: 8, maxLength: 256}
password:
type: string
format: password
description: 8 to 256 bytes (UTF-8).
LoginRequest:
type: object
required: [username, password]
properties:
username: {type: string}
password: {type: string, format: password}
CreateUser:
allOf:
@ -909,7 +951,10 @@ components:
required: [current_password, new_password]
properties:
current_password: {type: string, format: password}
new_password: {type: string, format: password, minLength: 8, maxLength: 256}
new_password:
type: string
format: password
description: 8 to 256 bytes (UTF-8).
Library:
type: object
@ -930,7 +975,9 @@ components:
LibraryUpdate:
type: object
minProperties: 1
anyOf:
- required: [name]
- required: [path]
properties:
name: {type: string, minLength: 1, maxLength: 100}
path: {type: string}
@ -997,10 +1044,14 @@ components:
id: {type: integer, format: int64}
title: {type: string}
artist:
type: object
nullable: true
description: The album artist, if the album has one.
allOf:
- $ref: '#/components/schemas/ArtistRef'
description: The album artist; null when the album has none.
additionalProperties: false
required: [id, name]
properties:
id: {type: integer, format: int64}
name: {type: string}
track_count: {type: integer}
duration_ms: {type: integer, format: int64}
@ -1015,9 +1066,14 @@ components:
track_no: {type: integer, description: 0 when unknown.}
disc_no: {type: integer, description: 0 when unknown.}
album:
type: object
nullable: true
allOf:
- $ref: '#/components/schemas/AlbumRef'
description: The album; null for a track that belongs to none.
additionalProperties: false
required: [id, title]
properties:
id: {type: integer, format: int64}
title: {type: string}
artists:
type: array
items: {$ref: '#/components/schemas/ArtistRef'}
@ -1067,7 +1123,7 @@ components:
event_type: {type: string, enum: [play, complete, skip]}
occurred_at: {type: string, format: date-time, description: Defaults to now.}
duration_played_ms: {type: integer, format: int64, minimum: 0}
idempotency_key: {type: string, minLength: 1, maxLength: 128}
idempotency_key: {type: string, description: 1 to 128 bytes (UTF-8).}
ListenResult:
type: object