// Zaparoo Core // Copyright (c) 2026 The Zaparoo Project Contributors. // SPDX-License-Identifier: GPL-3.0-or-later // // This file is part of Zaparoo Core. // // Zaparoo Core is free software: you can redistribute it and/or modify // it under the terms of the GNU General Public License as published by // the Free Software Foundation, either version 3 of the License, or // (at your option) any later version. // // Zaparoo Core is distributed in the hope that it will be useful, // but WITHOUT ANY WARRANTY; without even the implied warranty of // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the // GNU General Public License for more details. // // You should have received a copy of the GNU General Public License // along with Zaparoo Core. If not, see . package methods import ( "bytes" "encoding/json" "errors" "fmt" "os" "path/filepath" "slices" "sort" "strings" "time" "unicode" "unicode/utf8" "github.com/ZaparooProject/zaparoo-core/v2/pkg/api/models" "github.com/ZaparooProject/zaparoo-core/v2/pkg/api/models/requests" "github.com/ZaparooProject/zaparoo-core/v2/pkg/database" "github.com/ZaparooProject/zaparoo-core/v2/pkg/database/tags" "github.com/ZaparooProject/zaparoo-core/v2/pkg/helpers" "github.com/ZaparooProject/zaparoo-core/v2/pkg/helpers/imagefiles" "github.com/ZaparooProject/zaparoo-core/v2/pkg/platforms" "github.com/ZaparooProject/zaparoo-core/v2/pkg/service/uploads" "github.com/google/uuid" "github.com/rs/zerolog/log" "github.com/spf13/afero" ) const ( mediaUserNameMaxLength = 255 mediaUserDescriptionMaxLength = 10000 mediaUserTagsMaxValues = 32 // mediaUserImagePrefix names every stored user image; the rest of a // file's name is its content hash, so two games given the same image // share one file. mediaUserImagePrefix = "img" // UploadPurposeMediaImage is the upload purpose of an image for // media.meta.update. UploadPurposeMediaImage = "media-image" ) // mediaUserTagTypes are the title tag types a user may edit. var mediaUserTagTypes = []tags.TagType{ tags.TagTypeDeveloper, tags.TagTypePublisher, tags.TagTypeYear, tags.TagTypeGenre, tags.TagTypePlayers, } // mediaUserImageKinds are the image kinds a user may set, each the // "image-" property of a file. var mediaUserImageKinds = []string{ "image", "boxart", "boxart3d", "boxartside", "boxartback", "screenshot", "thumbnail", "marquee", "wheel", "fanart", "titleshot", "map", } // mediaFieldEdit is one user-edited field a media.meta.update sets or resets. type mediaFieldEdit struct { // value is the field's new stored value; nil resets the field. value *string // image is the source of an image field being set. image *models.MediaImageInput field string } // UserImagesDir is the folder that holds the images users set on games. It is // user data, kept out of backups: UserDB records which image a game uses. func UserImagesDir(pl platforms.Platform) string { return filepath.Join(helpers.DataDir(pl), "media", "images-user") } // NewUserImages returns the store of the images users set on games. func NewUserImages(pl platforms.Platform) *imagefiles.Store { return &imagefiles.Store{FS: afero.NewOsFs(), Dir: UserImagesDir(pl)} } func userImages(env *requests.RequestEnv) (*imagefiles.Store, error) { if env.Platform == nil { return nil, errors.New("platform is not available") } return NewUserImages(env.Platform), nil } // parseMediaUserName accepts a display name or null. func parseMediaUserName(raw json.RawMessage) (mediaFieldEdit, error) { edit := mediaFieldEdit{field: database.MediaUserFieldName} if isJSONNull(raw) { return edit, nil } var name string if err := json.Unmarshal(raw, &name); err != nil { return edit, fmt.Errorf("media.name must be a string or null: %w", err) } name = strings.TrimSpace(name) switch { case name == "": return edit, errors.New("media.name cannot be empty; use null to reset") case utf8.RuneCountInString(name) > mediaUserNameMaxLength: return edit, fmt.Errorf("media.name is longer than %d characters", mediaUserNameMaxLength) case strings.ContainsFunc(name, unicode.IsControl): return edit, errors.New("media.name cannot contain control characters") } edit.value = &name return edit, nil } // parseMediaUserDescription accepts a description or null. func parseMediaUserDescription(raw json.RawMessage) (mediaFieldEdit, error) { edit := mediaFieldEdit{field: database.MediaUserFieldDescription} if isJSONNull(raw) { return edit, nil } var description string if err := json.Unmarshal(raw, &description); err != nil { return edit, fmt.Errorf("media.description must be a string or null: %w", err) } description = strings.TrimSpace(description) if utf8.RuneCountInString(description) > mediaUserDescriptionMaxLength { return edit, fmt.Errorf("media.description is longer than %d characters", mediaUserDescriptionMaxLength) } if strings.ContainsFunc(description, func(r rune) bool { return unicode.IsControl(r) && r != '\n' && r != '\r' && r != '\t' }) { return edit, errors.New("media.description cannot contain control characters") } edit.value = &description return edit, nil } // parseMediaUserTags accepts an object of tag type to a list of values or // null. A list is the full set the title carries for that type; an empty // list is a title with none. func parseMediaUserTags(raw json.RawMessage) ([]mediaFieldEdit, error) { var byType map[string]json.RawMessage if err := json.Unmarshal(raw, &byType); err != nil || byType == nil { return nil, errors.New("media.tags must be an object of tag type to a list of values or null") } tagTypes := make([]string, 0, len(byType)) for tagType := range byType { tagTypes = append(tagTypes, tagType) } sort.Strings(tagTypes) edits := make([]mediaFieldEdit, 0, len(tagTypes)) for _, tagType := range tagTypes { if !slices.Contains(mediaUserTagTypes, tags.TagType(tagType)) { return nil, fmt.Errorf("media.tags.%s cannot be edited", tagType) } edit := mediaFieldEdit{field: database.MediaUserFieldTagPrefix + tagType} if isJSONNull(byType[tagType]) { edits = append(edits, edit) continue } var rawValues []string if err := json.Unmarshal(byType[tagType], &rawValues); err != nil { return nil, fmt.Errorf("media.tags.%s must be a list of strings or null: %w", tagType, err) } values, err := normalizeMediaUserTags(tags.TagType(tagType), rawValues) if err != nil { return nil, err } encoded := database.EncodeMediaUserTags(values) edit.value = &encoded edits = append(edits, edit) } return edits, nil } // normalizeMediaUserTags turns what a user typed into canonical tag values, // the way the scrapers do: a company keeps its name as the tag's label. func normalizeMediaUserTags(tagType tags.TagType, rawValues []string) ([]database.MediaUserTagValue, error) { if len(rawValues) > mediaUserTagsMaxValues { return nil, fmt.Errorf("media.tags.%s has more than %d values", tagType, mediaUserTagsMaxValues) } if tags.IsExclusiveType(tagType) && len(rawValues) > 1 { return nil, fmt.Errorf("media.tags.%s takes one value", tagType) } values := make([]database.MediaUserTagValue, 0, len(rawValues)) for _, rawValue := range rawValues { rawValue = strings.TrimSpace(rawValue) value := tags.NormalizeTagValue(string(tagType), rawValue) if err := tags.ValidateTagValue(tagType, value); err != nil { return nil, fmt.Errorf("media.tags.%s: %q is not a valid value", tagType, rawValue) } if slices.ContainsFunc(values, func(v database.MediaUserTagValue) bool { return v.Tag == value }) { continue } tagValue := database.MediaUserTagValue{Tag: value} if (tagType == tags.TagTypeDeveloper || tagType == tags.TagTypePublisher) && rawValue != value { tagValue.Label = rawValue } values = append(values, tagValue) } return values, nil } // parseMediaUserImages accepts an object of image kind to an image source or // null. func parseMediaUserImages(raw json.RawMessage) ([]mediaFieldEdit, error) { var byKind map[string]json.RawMessage if err := json.Unmarshal(raw, &byKind); err != nil || byKind == nil { return nil, errors.New("media.images must be an object of image kind to an image source or null") } kinds := make([]string, 0, len(byKind)) for kind := range byKind { kinds = append(kinds, kind) } sort.Strings(kinds) edits := make([]mediaFieldEdit, 0, len(kinds)) for _, kind := range kinds { if !slices.Contains(mediaUserImageKinds, kind) { return nil, fmt.Errorf("media.images.%s is not an image kind", kind) } edit := mediaFieldEdit{field: database.MediaUserFieldImagePrefix + kind} if isJSONNull(byKind[kind]) { edits = append(edits, edit) continue } var input models.MediaImageInput decoder := json.NewDecoder(bytes.NewReader(byKind[kind])) decoder.DisallowUnknownFields() if err := decoder.Decode(&input); err != nil { return nil, fmt.Errorf("media.images.%s must be an image source or null: %w", kind, err) } switch input.Kind { case models.MediaImageKindFile: if input.UploadID != "" || input.Root != "" || !filepath.IsAbs(input.Path) { return nil, fmt.Errorf("media.images.%s: a file image needs an absolute path and nothing else", kind) } case models.MediaImageKindUpload: if input.Path != "" || input.Root != "" || input.UploadID == "" { return nil, fmt.Errorf("media.images.%s: an upload image needs an uploadId and nothing else", kind) } case models.MediaImageKindBrowse: if input.UploadID != "" || input.Root == "" || input.Path == "" { return nil, fmt.Errorf("media.images.%s: a browse image needs a root and a path", kind) } default: return nil, fmt.Errorf("media.images.%s: unknown image kind %q", kind, input.Kind) } edit.image = &input edits = append(edits, edit) } return edits, nil } func isJSONNull(raw json.RawMessage) bool { return bytes.Equal(bytes.TrimSpace(raw), []byte("null")) } // storeMediaUserImage reads the image an edit names, stores it in the user // images folder and returns the file name UserDB keeps. func storeMediaUserImage(env *requests.RequestEnv, input *models.MediaImageInput) (string, error) { store, err := userImages(env) if err != nil { return "", err } if input.Kind == models.MediaImageKindUpload { var name string takeErr := uploadManager(env).Take(input.UploadID, env.ClientID, UploadPurposeMediaImage, func(path string) error { data, readErr := readMediaBinaryFile(afero.NewOsFs(), path, imagefiles.MaxBytes) if readErr != nil { return fmt.Errorf("read uploaded image: %w", readErr) } name, readErr = store.Save(mediaUserImagePrefix, data) if readErr != nil { return fmt.Errorf("store uploaded image: %w", readErr) } return nil }) if takeErr != nil { return "", uploadClientError(takeErr) } return name, nil } sourcePath := input.Path if input.Kind == models.MediaImageKindBrowse { // A browse image is one files.browse listed: inside a browse root. browser, browseErr := hostBrowser(env) if browseErr != nil { return "", browseErr } sourcePath, err = browser.ResolveImage(input.Root, input.Path) if err != nil { return "", hostFilesClientError(err) } } else if !isLocalOrAdmin(env) { // A file image reads any image on the Core host. return "", models.ClientErrf("%w", ErrForbidden) } info, err := os.Stat(sourcePath) if err != nil || !info.Mode().IsRegular() { return "", models.ClientErrf("image file not found: %s", input.Path) } if info.Size() > imagefiles.MaxBytes { return "", models.ClientErr(imagefiles.ErrTooLarge) } data, err := readMediaBinaryFile(afero.NewOsFs(), sourcePath, imagefiles.MaxBytes) if err != nil { return "", models.ClientErrf("image file cannot be read: %w", err) } name, err := store.Save(mediaUserImagePrefix, data) if err != nil { if errors.Is(err, imagefiles.ErrNotImage) || errors.Is(err, imagefiles.ErrTooLarge) { return "", models.ClientErr(err) } return "", fmt.Errorf("failed to store image: %w", err) } return name, nil } // applyMediaFieldEdits writes each edit to UserDB and the media database, // then brings the caches that read them up to date. func applyMediaFieldEdits(env *requests.RequestEnv, row *database.MediaFullRow, edits []mediaFieldEdit) error { if len(edits) == 0 { return nil } db := env.Database var tagsChanged, imagesChanged, cleared bool for i := range edits { edit := &edits[i] value := edit.value if edit.image != nil { name, err := storeMediaUserImage(env, edit.image) if err != nil { return err } value = &name } result, err := database.ApplyMediaUserField(env.Context, db, row, edit.field, value) if err != nil { return mediaWriteClientError( fmt.Errorf("failed to apply media %s: %w", edit.field, err), database.MediaWriteOperationNone, ) } tagsChanged = tagsChanged || result.TagsChanged imagesChanged = imagesChanged || result.ImagesChanged cleared = cleared || len(result.ClearedMediaDBIDs) > 0 } if tagsChanged { refreshScrapedTags(env.Context, db.MediaDB) } if imagesChanged { mediaImageNoImages.clear() invalidateChangedScrapeThumbnails(db.MediaDB) pruneMediaUserImages(env) } if cleared { refillMediaAfterReset(env, row) } return nil } // pruneMediaUserImages removes stored user images no game uses any more. func pruneMediaUserImages(env *requests.RequestEnv) { store, err := userImages(env) if err != nil { return } fields, err := env.Database.UserDB.ListMediaUserFields() if err != nil { log.Warn().Err(err).Msg("failed to list media user fields; user images not pruned") return } keep := make(map[string]struct{}) for i := range fields { if strings.HasPrefix(fields[i].Field, database.MediaUserFieldImagePrefix) { keep[fields[i].Value] = struct{}{} } } store.Prune(keep, time.Now()) } // refillMediaAfterReset asks the scrapers to fill what a reset field left // empty on one file, and on its title. It runs each scraper that fills // missing fields, scoped to that file; when another media job is running the // jobs wait in the queue instead. func refillMediaAfterReset(env *requests.RequestEnv, row *database.MediaFullRow) { if env.Platform == nil || env.State == nil { return } path, err := database.CanonicalScrapePath(row.Path, false) if err != nil { return } scope := &database.ScrapeScope{SystemID: row.System.SystemID, Path: path, MediaID: row.DBID} if scope.Validate() != nil { return } scrapers := env.Platform.Scrapers(env.Config) var jobs []database.ScrapeJob for id, s := range scrapers { if !s.SupportsFillMissing || s.Scrape == nil { continue } if len(s.SupportedSystemIDs) > 0 && !slices.Contains(s.SupportedSystemIDs, row.System.SystemID) { continue } jobs = append(jobs, database.ScrapeJob{ ScraperID: id, Systems: []string{row.System.SystemID}, FillMissing: true, Scope: scope, RunID: uuid.NewString(), }) } if len(jobs) == 0 { return } sortScrapeQueue(jobs, scrapers) first := jobs[0] operation := &database.ScrapingOperation{ Version: 1, ScraperID: first.ScraperID, Systems: first.Systems, RunID: first.RunID, FillMissing: true, Scope: scope, Pending: jobs[1:], } if _, startErr := startMediaScrapeOperation(env, operation, nil, false); startErr != nil { for i := range jobs { jobs[i].RunID = "" } if queueErr := enqueueScrapeJobs(env.Database.MediaDB, jobs, scrapers); queueErr != nil { log.Warn().Err(errors.Join(startErr, queueErr)).Str("path", row.Path). Msg("failed to scrape a file again after a metadata reset") } } } // takeUserEditedFields removes the internal user-fields marker from a // response's properties and returns the fields it lists, in the names // media.meta.update takes. func takeUserEditedFields(props map[string]models.MediaMetaPropertyItem) []string { typeTag := tags.PropertyTypeTag(tags.TagPropertyUserFields) item, ok := props[typeTag] if !ok { return nil } delete(props, typeTag) marker := database.DecodeMediaUserFieldsMarker(item.Text) edited := make([]string, 0, len(marker.Fields)) for _, field := range marker.Fields { switch { case strings.HasPrefix(field, database.MediaUserFieldTagPrefix): edited = append(edited, "tags."+strings.TrimPrefix(field, database.MediaUserFieldTagPrefix)) case strings.HasPrefix(field, database.MediaUserFieldImagePrefix): edited = append(edited, "images."+strings.TrimPrefix(field, database.MediaUserFieldImagePrefix)) default: edited = append(edited, field) } } sort.Strings(edited) return edited } // uploadClientError turns an upload service error a client caused into a // client error. func uploadClientError(err error) error { for _, clientErr := range []error{ uploads.ErrUnknownPurpose, uploads.ErrTooLarge, uploads.ErrInvalidSize, uploads.ErrInvalidHash, uploads.ErrTooManySessions, uploads.ErrNotFound, uploads.ErrWrongOffset, uploads.ErrChunkTooLarge, uploads.ErrEmptyChunk, uploads.ErrOverrun, uploads.ErrIncomplete, uploads.ErrHashMismatch, uploads.ErrFinished, uploads.ErrNotFinished, uploads.ErrWrongPurpose, imagefiles.ErrNotImage, imagefiles.ErrTooLarge, } { if errors.Is(err, clientErr) { return models.ClientErr(err) } } return err }