Skip to content

armgit / lyftr

Public Imported from GitHub
0

Self-hosted fitness tracker. Log workouts, track nutrition, and monitor progress. Docker deployment, mobile-friendly.

18.9 KB
Raw Blame
// Package oedb is Lyftr's client for open-exercise-db, the upstream community
// exercise catalog.
//
// Lyftr queries oedb rather than mirroring it. The local exercises table still
// exists, but as the rows a user has actually seen — see
// stores.ExerciseStore.Materialize — which a daily pass keeps current in every
// catalog language, and not as a copy of the catalog. Search, filtering and
// ordering are answered upstream, so the data Lyftr shows improves when oedb
// improves, without a redeploy.
//
// The cache here is what makes that affordable. oedb serves list and detail reads
// with `Cache-Control: public, max-age=300, stale-while-revalidate=86400` plus an
// ETag, so one popular query costs oedb roughly twelve requests an hour no matter
// how many Lyftr users run it. Caching in the backend rather than the browser is
// deliberate: it is one cache shared by every user of an instance, and it keeps
// Lyftr's own API contract unchanged.
package oedb

import (
	"context"
	"encoding/json"
	"errors"
	"fmt"
	"io"
	"net/http"
	"net/url"
	"strconv"
	"strings"
	"sync"
	"time"
)

// DefaultBaseURL is the hosted instance. Override with OEDB_BASE_URL to point a
// self-hosted Lyftr at a self-hosted catalog.
const DefaultBaseURL = "https://oedb-api-o4dqddih5q-uk.a.run.app"

// MaxPerPage is oedb's cap; asking for more is a 422, not a clamp.
const MaxPerPage = 100

// Client is a cache-aware reader for the oedb HTTP API. Safe for concurrent use.
type Client struct {
	baseURL   string
	userAgent string
	http      *http.Client

	// mu is a pointer so a Revalidating view shares the lock along with the map it guards.
	mu    *sync.Mutex
	cache map[string]*entry

	// alwaysRevalidate: never answer from cache; every read is a conditional GET.
	alwaysRevalidate bool
}

// entry is one cached response body plus the metadata needed to revalidate it.
type entry struct {
	body       []byte
	etag       string
	freshFor   time.Time // max-age boundary
	staleFor   time.Time // stale-while-revalidate boundary
	refreshing bool      // a background revalidation is already in flight
}

// New builds a client. An empty baseURL selects DefaultBaseURL.
//
// The User-Agent is not cosmetic: oedb tiers rate limits on caller identity, and
// a request with a generic or absent User-Agent is served 5 requests/minute
// instead of 60. Identifying properly is the difference between a working
// exercise picker and a 429.
func New(baseURL, version string) *Client {
	if baseURL == "" {
		baseURL = DefaultBaseURL
	}
	if version == "" {
		version = "dev"
	}
	return &Client{
		baseURL:   strings.TrimRight(baseURL, "/"),
		userAgent: fmt.Sprintf("lyftr/%s (+https://github.com/Cawlumm/lyftr)", version),
		// Generous, because this bounds the slowest legitimate call — the ~300 KB
		// bulk export, measured at ~14s against the hosted instance. Interactive
		// reads must not inherit that patience, so they carry their own deadline:
		// see the context each caller passes in.
		http:  &http.Client{Timeout: 90 * time.Second},
		cache: map[string]*entry{},
		mu:    &sync.Mutex{},
	}
}

// ListParams are the filters Lyftr forwards upstream. Zero values are omitted,
// so the zero ListParams asks for the unfiltered first page.
type ListParams struct {
	Query       string
	MuscleGroup string
	Category    string
	Equipment   string
	// Locale asks for translated text. It is part of the URL, never a header,
	// because the response cache is keyed by path.
	Locale  string
	IDs     []string
	Page    int
	PerPage int
}

func (p ListParams) query() url.Values {
	v := url.Values{}
	set := func(k, s string) {
		if s = strings.TrimSpace(s); s != "" {
			v.Set(k, s)
		}
	}
	set("q", p.Query)
	set("muscle_group", p.MuscleGroup)
	set("category", p.Category)
	set("equipment", p.Equipment)
	set("locale", p.Locale)
	if len(p.IDs) > 0 {
		v.Set("ids", strings.Join(p.IDs, ","))
	}
	if p.Page > 1 {
		v.Set("page", strconv.Itoa(p.Page))
	}
	per := p.PerPage
	if per <= 0 {
		per = MaxPerPage
	}
	if per > MaxPerPage {
		per = MaxPerPage
	}
	v.Set("per_page", strconv.Itoa(per))
	return v
}

// Image is one rendition of an exercise image. Lyftr uses the first image's URL
// and ignores variants for now.
type Image struct {
	ID          string `json:"id"`
	URL         string `json:"url"`
	Width       int    `json:"width"`
	Height      int    `json:"height"`
	ContentType string `json:"content_type"`
	License     string `json:"license"`
}

// Translation is the locale-resolved text for an exercise. oedb keeps name and
// instructions here rather than on the exercise because they vary by locale
// while the taxonomy does not.
//
// Each field reports the locale it was actually served in, because a locale that
// was asked for may be answered per field in English.
type Translation struct {
	Name                      string   `json:"name"`
	Aliases                   []string `json:"aliases"`
	Instructions              []string `json:"instructions"`
	NameLocale                string   `json:"name_locale"`
	NameMachineOrigin         bool     `json:"name_machine_origin"`
	InstructionsLocale        string   `json:"instructions_locale"`
	InstructionsMachineOrigin bool     `json:"instructions_machine_origin"`
}

// Exercise is one oedb catalog row, trimmed to the fields Lyftr reads.
type Exercise struct {
	ID               string      `json:"id"`
	Slug             string      `json:"slug"`
	SourceID         string      `json:"source_id"`
	MuscleGroup      string      `json:"muscle_group"`
	SecondaryMuscles []string    `json:"secondary_muscles"`
	Category         string      `json:"category"`
	Equipment        string      `json:"equipment"`
	Mechanic         string      `json:"mechanic"`
	Force            string      `json:"force"`
	Level            string      `json:"level"`
	Images           []Image     `json:"images"`
	Translation      Translation `json:"translation"`
}

// Name is the display name, which lives on the translation.
func (e Exercise) Name() string { return e.Translation.Name }

// Description renders the instruction steps as the single numbered block
// Lyftr's description column holds.
//
// The numbering is not decoration: every exercise seeded before oedb was stored
// in exactly this shape by seed.buildInstructions, and the UI renders the column
// as preformatted text. Joining with blank lines instead would make the same
// exercise look different depending on whether its row predates the migration.
func (e Exercise) Description() string {
	var b strings.Builder
	for i, step := range e.Translation.Instructions {
		if i > 0 {
			b.WriteByte('\n')
		}
		fmt.Fprintf(&b, "%d. %s", i+1, step)
	}
	return b.String()
}

// ImageURL returns an absolute URL for the first image, or "" when there is
// none. oedb serves image URLs relative to its own origin, so they are unusable
// verbatim by a client that is not oedb.
func (e Exercise) ImageURL(baseURL string) string {
	if len(e.Images) == 0 {
		return ""
	}
	u := e.Images[0].URL
	if u == "" || strings.HasPrefix(u, "http://") || strings.HasPrefix(u, "https://") {
		return u
	}
	return strings.TrimRight(baseURL, "/") + "/" + strings.TrimLeft(u, "/")
}

// BaseURL exposes the configured origin so callers can absolutize image URLs.
func (c *Client) BaseURL() string { return c.baseURL }

// ListResult is one page of catalog results.
type ListResult struct {
	Exercises []Exercise `json:"exercises"`
	Total     int        `json:"total"`
	Page      int        `json:"page"`
	PerPage   int        `json:"per_page"`
}

// List queries the catalog.
func (c *Client) List(ctx context.Context, p ListParams) (ListResult, error) {
	var out ListResult
	err := c.getJSON(ctx, "/api/v1/exercises?"+p.query().Encode(), &out)
	return out, err
}

// ErrNotFound is returned for a 404 so callers can tell "no such exercise" from
// "the catalog is unreachable" — the first is a client error, the second is a
// reason to fall back to the local snapshot.
var ErrNotFound = errors.New("oedb: exercise not found")

// Get fetches one exercise by its oedb UUID.
func (c *Client) Get(ctx context.Context, id string) (Exercise, error) {
	var out Exercise
	err := c.getJSON(ctx, "/api/v1/exercises/"+url.PathEscape(id), &out)
	return out, err
}

// getJSON performs a cache-aware GET and decodes the body.
func (c *Client) getJSON(ctx context.Context, path string, dst any) error {
	body, err := c.get(ctx, path)
	if err != nil {
		return err
	}
	if err := json.Unmarshal(body, dst); err != nil {
		return fmt.Errorf("oedb: decode %s: %w", path, err)
	}
	return nil
}

// get returns a response body, from cache when it is still fresh.
//
// The three states mirror what oedb's Cache-Control describes:
//
//   - fresh (within max-age): serve from memory, no request at all.
//   - stale but within stale-while-revalidate: serve the stale body immediately
//     and revalidate in the background. This is the state a moderately-used query
//     spends most of its life in, and serving through it is what keeps a user's
//     search off the critical path of an upstream round trip.
//   - beyond both: fetch synchronously.
//
// A Revalidating view skips the first two states and always takes the third,
// conditionally.
func (c *Client) get(ctx context.Context, path string) ([]byte, error) {
	now := time.Now()

	c.mu.Lock()
	e, ok := c.cache[path]
	cached := ok && !c.alwaysRevalidate
	if cached && now.Before(e.freshFor) {
		body := e.body
		c.mu.Unlock()
		return body, nil
	}
	if cached && now.Before(e.staleFor) && len(e.body) > 0 {
		body := e.body
		if !e.refreshing {
			e.refreshing = true
			go c.revalidate(path)
		}
		c.mu.Unlock()
		return body, nil
	}
	etag := ""
	if ok {
		etag = e.etag
	}
	c.mu.Unlock()

	return c.fetch(ctx, path, etag)
}

// Revalidating returns a view of c that never answers from cache: every read is a
// conditional GET with the stored ETag, and a 304 reuses the cached body. It shares
// c's cache, so what it learns also refreshes what interactive reads are served.
// The catalog sync reads through it; served from cache, each pass would apply what
// the previous pass fetched, a whole interval late.
func (c *Client) Revalidating() *Client {
	v := *c
	v.alwaysRevalidate = true
	return &v
}

// DropCache forgets every cached response, in the map the Revalidating views share. A
// caller that has just learned upstream changed uses it so the next read asks again
// instead of being answered from before.
func (c *Client) DropCache() {
	c.mu.Lock()
	defer c.mu.Unlock()
	for k := range c.cache {
		delete(c.cache, k)
	}
}

// revalidate refreshes a stale entry off the request path. It deliberately uses
// its own timeout-bounded context rather than the caller's: the caller has
// already been served, and cancelling the refresh when that request finishes
// would mean the entry never refreshes under steady traffic.
func (c *Client) revalidate(path string) {
	ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
	defer cancel()

	c.mu.Lock()
	etag := ""
	if e, ok := c.cache[path]; ok {
		etag = e.etag
	}
	c.mu.Unlock()

	_, _ = c.fetch(ctx, path, etag)

	c.mu.Lock()
	if e, ok := c.cache[path]; ok {
		e.refreshing = false
	}
	c.mu.Unlock()
}

// maxRateLimitRetries bounds the 429 backoff. Two retries covers a burst
// overrun, which refills in seconds; more than that means the per-minute budget
// is genuinely gone and waiting would just move the failure later.
const maxRateLimitRetries = 2

func (c *Client) fetch(ctx context.Context, path, etag string) ([]byte, error) {
	return c.fetchAttempt(ctx, path, etag, 0)
}

// retryAfter parses the delay-seconds form of Retry-After, which is what oedb
// sends. The HTTP-date form is rejected rather than guessed at: a misparsed date
// becomes an unbounded sleep, and reporting the 429 is the safer failure.
func retryAfter(h string) (time.Duration, bool) {
	secs, err := strconv.Atoi(strings.TrimSpace(h))
	if err != nil || secs < 0 || secs > 60 {
		return 0, false
	}
	// A zero-second Retry-After still needs a beat, or the retry races the refill.
	return time.Duration(secs)*time.Second + 250*time.Millisecond, true
}

func (c *Client) fetchAttempt(ctx context.Context, path, etag string, attempt int) ([]byte, error) {
	req, err := http.NewRequestWithContext(ctx, http.MethodGet, c.baseURL+path, nil)
	if err != nil {
		return nil, fmt.Errorf("oedb: build request: %w", err)
	}
	req.Header.Set("User-Agent", c.userAgent)
	req.Header.Set("Accept", "application/json")
	// Deliberately NOT setting Accept-Encoding. net/http adds it and transparently
	// decompresses the response only when it owns the header; setting it by hand
	// opts out of that and hands back raw gzip bytes, which fail to decode with
	// "invalid character '\x1f'". Compression still happens — Go just does it.
	if etag != "" {
		req.Header.Set("If-None-Match", etag)
	}

	resp, err := c.http.Do(req)
	if err != nil {
		return nil, fmt.Errorf("oedb: %s: %w", path, err)
	}
	defer resp.Body.Close()

	// oedb rate-limits per tier and says when to come back. Honour that rather
	// than treating 429 as a failure: its search tier allows 60 requests a minute
	// but a far smaller instantaneous burst, so a client issuing a short run of
	// legitimate queries trips it while nowhere near the per-minute budget. A
	// caller that retries on the server's own schedule gets its data; one that
	// gives up degrades for no reason, and one that retries immediately makes it
	// worse for everyone.
	if resp.StatusCode == http.StatusTooManyRequests {
		wait, ok := retryAfter(resp.Header.Get("Retry-After"))
		if !ok || attempt >= maxRateLimitRetries {
			snippet, _ := io.ReadAll(io.LimitReader(resp.Body, 512))
			return nil, fmt.Errorf("oedb: %s: http 429: %s", path, strings.TrimSpace(string(snippet)))
		}
		select {
		case <-ctx.Done():
			return nil, fmt.Errorf("oedb: %s: %w", path, ctx.Err())
		case <-time.After(wait):
		}
		return c.fetchAttempt(ctx, path, etag, attempt+1)
	}

	// 304 means the cached body is still correct: keep it and only push the
	// freshness window forward. This is the cheap path, and the reason ETags are
	// worth sending at all — a revalidation that changes nothing costs headers.
	if resp.StatusCode == http.StatusNotModified {
		c.mu.Lock()
		e, ok := c.cache[path]
		if ok {
			fresh, stale := cacheWindow(resp.Header.Get("Cache-Control"))
			now := time.Now()
			e.freshFor = now.Add(fresh)
			e.staleFor = now.Add(fresh + stale)
		}
		c.mu.Unlock()
		if ok {
			return e.body, nil
		}
		// Evicted while the request was out. Ask again without the ETag for the body.
		if etag != "" {
			return c.fetchAttempt(ctx, path, "", attempt)
		}
		return nil, fmt.Errorf("oedb: %s: 304 with no cached body", path)
	}

	if resp.StatusCode == http.StatusNotFound {
		return nil, ErrNotFound
	}
	if resp.StatusCode != http.StatusOK {
		// Cap the body read: an error page is not a reason to buffer whatever the
		// far side chose to send.
		snippet, _ := io.ReadAll(io.LimitReader(resp.Body, 512))
		return nil, fmt.Errorf("oedb: %s: http %d: %s", path, resp.StatusCode, strings.TrimSpace(string(snippet)))
	}

	body, err := io.ReadAll(resp.Body)
	if err != nil {
		return nil, fmt.Errorf("oedb: %s: read body: %w", path, err)
	}

	fresh, stale := cacheWindow(resp.Header.Get("Cache-Control"))
	now := time.Now()
	c.mu.Lock()
	c.store(path, &entry{
		body:     body,
		etag:     resp.Header.Get("ETag"),
		freshFor: now.Add(fresh),
		staleFor: now.Add(fresh + stale),
	}, now)
	c.mu.Unlock()

	return body, nil
}

// maxCacheEntries bounds the response cache. Keys are request paths, and the search
// box makes those user-controlled, so without a cap every distinct query stays in
// memory until restart.
const maxCacheEntries = 256

// store adds e under path, first making room: entries past their stale window go
// first, then whichever expires soonest. Callers hold c.mu.
func (c *Client) store(path string, e *entry, now time.Time) {
	if _, ok := c.cache[path]; !ok && len(c.cache) >= maxCacheEntries {
		var oldest string
		for k, v := range c.cache {
			if !now.Before(v.staleFor) {
				delete(c.cache, k)
			} else if oldest == "" || v.staleFor.Before(c.cache[oldest].staleFor) {
				oldest = k
			}
		}
		if len(c.cache) >= maxCacheEntries {
			delete(c.cache, oldest)
		}
	}
	c.cache[path] = e
}

// cacheWindow reads max-age and stale-while-revalidate out of a Cache-Control
// header, falling back to a conservative 60s/0 when the header is absent or
// unparseable. The fallback is short rather than long: guessing a long freshness
// for a response that never claimed one would serve stale data on a header
// change we did not notice.
func cacheWindow(header string) (fresh, stale time.Duration) {
	fresh, stale = 60*time.Second, 0

	for _, part := range strings.Split(header, ",") {
		part = strings.TrimSpace(part)
		k, v, ok := strings.Cut(part, "=")
		if !ok {
			continue
		}
		secs, err := strconv.Atoi(strings.TrimSpace(v))
		if err != nil || secs < 0 {
			continue
		}
		switch strings.ToLower(strings.TrimSpace(k)) {
		case "max-age":
			fresh = time.Duration(secs) * time.Second
		case "stale-while-revalidate":
			stale = time.Duration(secs) * time.Second
		}
	}
	return fresh, stale
}

// maxLocalePages bounds locale discovery. oedb's locale list is a curated taxonomy
// that fits on one page; a list still going after this many is a broken or hostile
// upstream, and every listed locale costs the sync a pass of its own.
const maxLocalePages = 5

// Locales lists every locale the catalog holds translated content in; oedb always
// includes en. The list is bounded, and a list that exceeds it is an error rather
// than a partial answer.
func (c *Client) Locales(ctx context.Context) ([]string, error) {
	var codes []string
	for page := 1; page <= maxLocalePages; page++ {
		var out struct {
			Locales []struct {
				Code string `json:"code"`
			} `json:"locales"`
			Total int `json:"total"`
		}
		path := "/api/v1/meta/locales?page=" + strconv.Itoa(page) + "&per_page=" + strconv.Itoa(MaxPerPage)
		if err := c.getJSON(ctx, path, &out); err != nil {
			return nil, err
		}
		for _, l := range out.Locales {
			codes = append(codes, l.Code)
		}
		if out.Total > maxLocalePages*MaxPerPage || len(codes) > maxLocalePages*MaxPerPage {
			return nil, fmt.Errorf("oedb: locale list exceeds %d entries", maxLocalePages*MaxPerPage)
		}
		if len(out.Locales) == 0 || len(codes) >= out.Total {
			return codes, nil
		}
	}
	return nil, fmt.Errorf("oedb: locale list did not end within %d pages", maxLocalePages)
}

// Export fetches the entire published catalog in one request.
//
// oedb caps per_page at 100, so assembling all ~873 exercises through List would
// take nine round trips. The export endpoint returns them in a single ~300 KB
// response carrying the same row shape, and is cached upstream for 900s rather
// than 300s. It is the right call for "give me everything" — which is exactly
// what Lyftr's exercise picker asks for — and the wrong one for anything
// filtered, where List returns far less data.
func (c *Client) Export(ctx context.Context) ([]Exercise, error) {
	var out struct {
		Exercises []Exercise `json:"exercises"`
		Total     int        `json:"total"`
	}
	if err := c.getJSON(ctx, "/api/v1/exercises/export", &out); err != nil {
		return nil, err
	}
	return out.Exercises, nil
}