schema

Documentation

Overview

Package schema contains HTTP request and response schemas used throughout the Karman API. These differ from models mainly through the presence of JSON tags. Some schemas however hide model fields or present them in a different way.

A schema must implement render.Renderer if they can be used as a response schema. A schema must implement render.Binder if they can be used as a request schema.

Index

• type AudioFile
• type ImageFile
• type List
  • func (l *List[T]) PrepareResponse(w http.ResponseWriter, _ *http.Request) any
  • func (l *List[T]) Render(http.ResponseWriter, *http.Request) error
• type MedleyMode
• type Song
  • func FromSong(m model.Song) Song
• type SongRW
  • func (s *SongRW) Apply(m *model.Song)
  • func (s *SongRW) Bind(*http.Request) error
  • func (s *SongRW) Render(http.ResponseWriter, *http.Request) error
• type Upload
  • func FromUpload(m model.Upload) Upload
  • func (u *Upload) MarshalJSON() ([]byte, error)
• type UploadDirEntry
  • func (e UploadDirEntry) MarshalJSON() ([]byte, error)
• type UploadFileStat
  • func FromUploadFileStat(stat fs.FileInfo, children []fs.FileInfo, nextMarker string) UploadFileStat
  • func (s UploadFileStat) MarshalJSON() ([]byte, error)
• type UploadProcessingError
  • func FromUploadProcessingError(err model.UploadProcessingError) UploadProcessingError
• type VideoFile

Types

type AudioFile

type AudioFile struct {
	Type     mediatype.MediaType `json:"type"` // RFC 6838 media type
	Duration time.Duration       `json:"duration"`
}

AudioFile contains data about an audio file.

type ImageFile

type ImageFile struct {
	Type   mediatype.MediaType `json:"type"`   // RFC 6838 media type
	Width  int                 `json:"width"`  // in pixels
	Height int                 `json:"height"` // in pixels
}

ImageFile contains data about an image file.

type List

type List[T render.Renderer] struct {
	// The number of elements in this list response.
	// Equal to len(l.Items), less than or equal to Total.
	Count int

	// The Offset of this list within the underlying collection.
	Offset int64

	// The Limit from the request. Greater or equal to Count.
	Limit int

	// The Total number of elements in the underlying collection.
	Total int64

	// A slice of items in this list.
	Items []T
}

List is a generic schema type for list responses. Apart from the actual slice of items a List contains information about the size of the underlying query result.

func (*List[T]) PrepareResponse

func (l *List[T]) PrepareResponse(w http.ResponseWriter, _ *http.Request) any

PrepareResponse generates the actual response list from l. This method also sets pagination headers.

func (*List[T]) Render

func (l *List[T]) Render(http.ResponseWriter, *http.Request) error

Render makes sure that l.Count is correctly set. Render implements the render.Renderer interface.

type MedleyMode

type MedleyMode string

MedleyMode indicates how a song's medley is to be calculated.

const (
	// MedleyModeOff disables medley calculation.
	// The song will not have a medley.
	MedleyModeOff MedleyMode = "off"

	// MedleyModeAuto enables automatic medley detection by UltraStar.
	// This is the default.
	MedleyModeAuto MedleyMode = "auto"

	// MedleyModeManual disables automatic medley calculation but provides manual medley start and end times.
	MedleyModeManual MedleyMode = "manual"
)

type Song

type Song struct {
	SongRW
	UUID uuid.UUID `json:"uuid"`

	Duet       bool       `json:"duet"`
	Audio      *AudioFile `json:"audio"`
	Video      *VideoFile `json:"video"`
	Cover      *ImageFile `json:"cover"`
	Background *ImageFile `json:"background"`
}

Song extends SongRW with additional read-only fields used in API responses. The Song schema should not be used as request schema.

func FromSong

func FromSong(m model.Song) Song

FromSong converts m into a schema instance representing the current state of m.

type SongRW

type SongRW struct {
	Title    string   `json:"title"`
	Artists  []string `json:"artists,omitempty"`
	Genre    string   `json:"genre,omitempty"`
	Edition  string   `json:"edition,omitempty"`
	Creator  string   `json:"creator,omitempty"`
	Language string   `json:"language,omitempty"`
	Year     int      `json:"year,omitempty"`
	Comment  string   `json:"comment,omitempty"`

	DuetSinger1 string            `json:"duetSinger1,omitempty"`
	DuetSinger2 string            `json:"duetSinger2,omitempty"`
	Extra       map[string]string `json:"extra,omitempty"`

	BPM          ultrastar.BPM  `json:"bpm"`
	Gap          time.Duration  `json:"gap,omitempty"`
	VideoGap     time.Duration  `json:"videoGap,omitempty"`
	NotesGap     ultrastar.Beat `json:"notesGap,omitempty"`
	Start        time.Duration  `json:"start,omitempty"`
	End          time.Duration  `json:"end,omitempty"`
	PreviewStart time.Duration  `json:"previewStart,omitempty"`

	Medley struct {
		Mode            MedleyMode     `json:"mode"`
		MedleyStartBeat ultrastar.Beat `json:"medleyStartBeat,omitempty"`
		MedleyEndBeat   ultrastar.Beat `json:"medleyEndBeat,omitempty"`
	} `json:"medley"`
}

SongRW is the main schema for working with songs. All fields in SongRW are readable and writeable fields. The Song schema extends this with some read-only fields.

func (*SongRW) Apply

func (s *SongRW) Apply(m *model.Song)

Apply stores the fields of s into the respective fields of m.

func (*SongRW) Bind

func (s *SongRW) Bind(*http.Request) error

Bind implements the render.Bind interface. Bind makes sure that the medley information is valid.

func (*SongRW) Render

func (s *SongRW) Render(http.ResponseWriter, *http.Request) error

Render implements the render.Renderer interface. Render makes sure that medley information is generated consistently.

type Upload

type Upload struct {
	render.NopRenderer
	UUID   uuid.UUID         `json:"uuid"`
	Status model.UploadState `json:"status"`

	SongsTotal     int `json:"songsTotal"`
	SongsProcessed int `json:"songsProcessed"`
	Errors         int `json:"errors"`
}

Upload is the response schema for model.Upload. The struct contains JSON tags for completeness. These however, are not used during marshalling.

func FromUpload

func FromUpload(m model.Upload) Upload

FromUpload generates a response schema, describing m.

func (*Upload) MarshalJSON

func (u *Upload) MarshalJSON() ([]byte, error)

MarshalJSON marshals u into a JSON string. The fields included depend on the upload status.

type UploadDirEntry

type UploadDirEntry struct {
	Name string `json:"name"`
	Dir  bool   `json:"dir"`
	Size int64  `json:"size"`
}

UploadDirEntry describes the subschema for files in a directory in an upload. This schema should be used only with UploadFileStat.

It differs from UploadFileStat mostly in the fact, that folders do not list their children recursively.

func (UploadDirEntry) MarshalJSON

func (e UploadDirEntry) MarshalJSON() ([]byte, error)

MarshalJSON marshals e into a JSON string. The file size is only included for files.

type UploadFileStat

type UploadFileStat struct {
	render.NopRenderer
	Name       string           `json:"name"`
	Size       int64            `json:"size"`
	Dir        bool             `json:"dir"`
	Children   []UploadDirEntry `json:"children,omitempty"`
	NextMarker string           `json:"nextMarker,omitempty"`
}

UploadFileStat describes the response schema for a file listing in an upload.

func FromUploadFileStat

func FromUploadFileStat(stat fs.FileInfo, children []fs.FileInfo, nextMarker string) UploadFileStat

FromUploadFileStat creates an UploadFileStat from the specified file infos. If nextMarker is not empty, it will also be included.

func (UploadFileStat) MarshalJSON

func (s UploadFileStat) MarshalJSON() ([]byte, error)

MarshalJSON marshals s into JSON data. The included fields mainly depend on whether s is a directory or a file.

type UploadProcessingError

type UploadProcessingError struct {
	render.NopRenderer
	File    string `json:"file"`
	Message string `json:"message"`
}

UploadProcessingError describes an item in an error listing for uploads.

func FromUploadProcessingError

func FromUploadProcessingError(err model.UploadProcessingError) UploadProcessingError

FromUploadProcessingError creates an UploadProcessingError describing err.

type VideoFile

type VideoFile struct {
	Type     mediatype.MediaType `json:"type"` // RFC 6838 media type
	Duration time.Duration       `json:"duration"`
	Width    int                 `json:"width"`  // in pixels
	Height   int                 `json:"height"` // in pixels
}

VideoFile contains data about a video file.