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:
parent
9d28a8a99c
commit
2ae4aedac0
1 changed files with 405 additions and 114 deletions
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in a new issue