0.2.81

server/internal/api/genre_affinity.go

@@ -0,0 +1,155 @@
+package api
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"time"
+
+	"github.com/ponzischeme89/memby/server/internal/cache"
+	"github.com/ponzischeme89/memby/server/internal/store"
+)
+
+// The Genres browser's rail is a fixed catalogue in product order on the television, and
+// that order is deliberately not server data — it must not jump around while home rows are
+// arriving. What *is* server data is the evidence: Tracearr already knows who watched what,
+// and the imported catalogue already knows each title's genres, so the gateway can say
+// which labels a viewer actually watches and let the set decide what to do about it.
+//
+// The split is the point. The gateway sends Emby's own genre spellings with a weight each;
+// the television folds them into its sixteen categories through the alias table it already
+// owns and re-orders its own rail. A gateway that sorted the categories itself would need a
+// second copy of that catalogue, and the two would disagree the first time a category
+// gained an alias — which is the failure the aliases exist to fix in the first place.
+
+const (
+	// genreAffinityTTL is how long one viewer's reading is kept. Long, because this is
+	// exactly the sort of answer that must never be on the path of opening a page and
+	// because taste does not move in an evening — but not indefinite, so a household whose
+	// viewing changes sees the rail follow it within a day.
+	genreAffinityTTL = 6 * time.Hour
+
+	// genreAffinityEmptyTTL remembers "nothing to say about this viewer" for a shorter
+	// span. A new account genuinely acquires a history, and a six-hour no would leave their
+	// first evening of watching invisible until the following morning.
+	genreAffinityEmptyTTL = time.Hour
+)
+
+// genreAffinityEntry is one label on the wire.
+type genreAffinityEntry struct {
+	Genre  string  `json:"genre"`
+	Weight float64 `json:"weight"`
+}
+
+// genreAffinityResponse is what a television is told.
+//
+// Sessions rides along because the ordering rule on the set refuses to personalise below a
+// floor, and a share of nothing is not evidence: a viewer three sessions old would
+// otherwise have one of those three deciding what leads their rail. It is the count of
+// qualifying sessions the weights were built from, not the household's total.
+type genreAffinityResponse struct {
+	Sessions int                  `json:"sessions"`
+	Genres   []genreAffinityEntry `json:"genres"`
+}
+
+// normaliseGenreAffinity scales the weights so the most-watched genre is 1.
+//
+// Pure, and the reason it exists is that the television's rule is written in shares rather
+// than in counts: a household that watches every night and one that watches on Sundays must
+// personalise the same way, and a floor expressed in raw sessions would mean something
+// different for each of them. Anything not positive is dropped rather than sent as a zero —
+// a genre with no weight is one the ordering has nothing to say about, and saying so with a
+// row invites the set to treat it as a considered nil.
+func normaliseGenreAffinity(affinity store.GenreAffinity) genreAffinityResponse {
+	out := genreAffinityResponse{Sessions: affinity.Sessions, Genres: []genreAffinityEntry{}}
+	top := 0.0
+	for _, entry := range affinity.Genres {
+		if entry.Score > top {
+			top = entry.Score
+		}
+	}
+	if top <= 0 {
+		return out
+	}
+	for _, entry := range affinity.Genres {
+		if entry.Genre == "" || entry.Score <= 0 {
+			continue
+		}
+		out.Genres = append(out.Genres, genreAffinityEntry{
+			Genre:  entry.Genre,
+			Weight: entry.Score / top,
+		})
+	}
+	return out
+}
+
+// handleGenreAffinity answers which genres this viewer watches.
+//
+// It is its own route rather than a field on /v1/home for the reason the update verdict is:
+// home is cached per user and is the response every television in the house is waiting on,
+// while this is asked for at most once per session by the one set whose viewer has opened
+// the Genres browser. Nothing on the launcher wants it.
+//
+// Every way this can fail is the same answer — an empty reading, which the television reads
+// as "use the default order". A rail that refused to draw because Tracearr was unreachable
+// would be a personalisation feature costing somebody their genre list.
+func (s *Server) handleGenreAffinity(w http.ResponseWriter, r *http.Request, sess store.Session) {
+	ctx := r.Context()
+	key := cache.UserKey(sess.EmbyUserID, "genre-affinity:v1")
+	if raw, err := s.cache.Get(ctx, key); err == nil {
+		w.Header().Set("X-Memby-Cache", "hit")
+		writeRaw(w, http.StatusOK, raw)
+		return
+	}
+
+	response := s.genreAffinityFor(ctx, sess)
+	body, err := json.Marshal(response)
+	if err != nil {
+		writeJSON(w, http.StatusOK, genreAffinityResponse{Genres: []genreAffinityEntry{}})
+		return
+	}
+	ttl := genreAffinityTTL
+	if len(response.Genres) == 0 {
+		ttl = genreAffinityEmptyTTL
+	}
+	if err := s.cache.Set(ctx, key, body, ttl); err != nil {
+		s.loggerFor(ctx).Warn("genre affinity cache write failed", "error", err)
+	}
+	w.Header().Set("X-Memby-Cache", "miss")
+	writeRaw(w, http.StatusOK, body)
+}
+
+// genreAffinityFor is the reading itself, separated from the caching so the failure stance
+// is stated once: nothing below returns an error, because there is no trouble here a viewer
+// could act on and the rail has a perfectly good answer without it.
+func (s *Server) genreAffinityFor(ctx context.Context, sess store.Session) genreAffinityResponse {
+	empty := genreAffinityResponse{Genres: []genreAffinityEntry{}}
+	if s.store == nil {
+		return empty
+	}
+	// The operator's switch is honoured even though the rows are already in Postgres.
+	// Tracearr switched off means the household has said Memby may not read their viewing,
+	// and old rows are still their viewing.
+	if !s.integrationEnabled(ctx, integrationTracearr) {
+		return empty
+	}
+	identity, err := s.store.TracearrIdentity(ctx, sess.EmbyUserID)
+	if err != nil {
+		s.loggerFor(ctx).Debug("genre affinity identity failed", "error", err)
+	}
+	// The session's own username is the fallback join, and it is the only one a viewer the
+	// recommendation builder has never profiled has.
+	username := identity.Username
+	if username == "" {
+		username = sess.Username
+	}
+	affinity, err := s.store.TracearrGenreAffinity(ctx, identity.TracearrUserID, username, time.Now())
+	if err != nil {
+		s.loggerFor(ctx).Warn("genre affinity failed", "error", err)
+		return empty
+	}
+	response := normaliseGenreAffinity(affinity)
+	s.loggerFor(ctx).Debug("genre affinity read",
+		"sessions", response.Sessions, "genres", len(response.Genres))
+	return response
+}