package config import ( "encoding/json" "errors" "fmt" "os" "path/filepath" "regexp" "slices" "strings" "time" "github.com/BurntSushi/toml" ) // Algorithm selects how a feed's posts are ordered. type Algorithm string const ( // AlgorithmChronological orders posts newest first. AlgorithmChronological Algorithm = "chronological" // AlgorithmHot orders posts by like-driven heat that cools over time. AlgorithmHot Algorithm = "hot" ) // MaxPageSize is the largest page getFeedSkeleton may return, per the protocol. const MaxPageSize = 100 // Feed is a fully resolved feed definition: [default] values with the feed's overrides applied. type Feed struct { // Name is the feed's record key in at:///app.bsky.feed.generator/. Name string // Rules decide which posts the feed adds. An event that satisfies any rule // adds that rule's target. Rules []Rule // PageSize is the number of posts returned when a request does not specify a limit. PageSize int // MaxAge is how long matched posts are kept before being purged. MaxAge time.Duration // Algorithm is how the feed's posts are ordered. Algorithm Algorithm // Gravity is the hourly cooling rate used by AlgorithmHot. Gravity float64 // TrackLikes enables counting likes on the feed's posts. TrackLikes bool } // Rule is a set of patterns that must all match an event for the feed to add the rule's target. type Rule struct { // Patterns are the Quamina patterns that must all match. Patterns []Pattern // Target is the dot path, from the event root, to a strongRef ({uri, cid}) // naming the post to add. An empty Target adds the matched post itself. Target string } // Pattern is a Quamina pattern loaded from a file. type Pattern struct { // Path is the resolved path of the pattern file. Path string // JSON is the Quamina pattern read from Path. JSON string } // feedSettings is one TOML table of feed settings. Pointer fields distinguish // "not set" from a zero value so a feed can override a default with zero/false. type feedSettings struct { // Pattern is shorthand for a single rule holding one pattern and no target. Pattern *string `toml:"pattern"` Rules []ruleSettings `toml:"rules"` PageSize *int `toml:"page_size"` MaxAge *string `toml:"max_age"` Algorithm *string `toml:"algorithm"` Gravity *float64 `toml:"gravity"` TrackLikes *bool `toml:"track_likes"` } // ruleSettings is one [[feeds..rules]] table. type ruleSettings struct { Patterns []string `toml:"patterns"` Target string `toml:"target"` } type feedsFile struct { Default feedSettings `toml:"default"` Feeds map[string]feedSettings `toml:"feeds"` } // builtinDefaults apply to any setting that neither [default] nor the feed sets. var builtinDefaults = feedSettings{ PageSize: ptr(30), MaxAge: ptr("48h"), Algorithm: ptr(string(AlgorithmChronological)), Gravity: ptr(0.1), TrackLikes: ptr(false), } // recordKeyPattern is the allowed character set for an atproto record key. var recordKeyPattern = regexp.MustCompile(`^[A-Za-z0-9._:~-]{1,512}$`) // LoadFeeds reads the feeds file at path and returns its feeds sorted by name. // Pattern paths are resolved relative to the feeds file's directory. func LoadFeeds(path string) ([]Feed, error) { var file feedsFile meta, err := toml.DecodeFile(path, &file) if err != nil { return nil, fmt.Errorf("parsing %s: %w", path, err) } if undecoded := meta.Undecoded(); len(undecoded) > 0 { keys := make([]string, len(undecoded)) for i, key := range undecoded { keys[i] = key.String() } return nil, fmt.Errorf("parsing %s: unknown keys: %s", path, strings.Join(keys, ", ")) } if len(file.Feeds) == 0 { return nil, fmt.Errorf("%s defines no feeds", path) } baseDir := filepath.Dir(path) defaults := file.Default.withFallback(builtinDefaults) var feeds []Feed var errs []error for name, settings := range file.Feeds { feed, err := resolveFeed(name, settings.withFallback(defaults), baseDir) if err != nil { errs = append(errs, fmt.Errorf("feed %q: %w", name, err)) continue } feeds = append(feeds, feed) } if err := errors.Join(errs...); err != nil { return nil, err } slices.SortFunc(feeds, func(a, b Feed) int { return strings.Compare(a.Name, b.Name) }) return feeds, nil } // withFallback returns s with every unset field taken from fallback. func (s feedSettings) withFallback(fallback feedSettings) feedSettings { // pattern and rules are alternatives, so a feed that sets either one // inherits neither. if s.Pattern == nil && s.Rules == nil { s.Pattern = fallback.Pattern s.Rules = fallback.Rules } if s.PageSize == nil { s.PageSize = fallback.PageSize } if s.MaxAge == nil { s.MaxAge = fallback.MaxAge } if s.Algorithm == nil { s.Algorithm = fallback.Algorithm } if s.Gravity == nil { s.Gravity = fallback.Gravity } if s.TrackLikes == nil { s.TrackLikes = fallback.TrackLikes } return s } // resolveFeed validates fully merged settings and loads the feed's pattern file. func resolveFeed(name string, settings feedSettings, baseDir string) (Feed, error) { if !recordKeyPattern.MatchString(name) || name == "." || name == ".." { return Feed{}, errors.New("name is not a valid record key") } feed := Feed{ Name: name, PageSize: *settings.PageSize, Algorithm: Algorithm(*settings.Algorithm), Gravity: *settings.Gravity, TrackLikes: *settings.TrackLikes, } var errs []error if feed.PageSize < 1 || feed.PageSize > MaxPageSize { errs = append(errs, fmt.Errorf("page_size must be between 1 and %d", MaxPageSize)) } maxAge, err := time.ParseDuration(*settings.MaxAge) switch { case err != nil: errs = append(errs, fmt.Errorf("max_age: %w", err)) case maxAge <= 0: errs = append(errs, errors.New("max_age must be positive")) } feed.MaxAge = maxAge switch feed.Algorithm { case AlgorithmChronological: case AlgorithmHot: if !feed.TrackLikes { errs = append(errs, errors.New(`algorithm "hot" requires track_likes = true`)) } if feed.Gravity <= 0 { errs = append(errs, errors.New(`algorithm "hot" requires gravity > 0`)) } default: errs = append(errs, fmt.Errorf("algorithm must be %q or %q", AlgorithmChronological, AlgorithmHot)) } rules, err := resolveRules(settings, baseDir) if err != nil { errs = append(errs, err) } feed.Rules = rules return feed, errors.Join(errs...) } // resolveRules validates the feed's rules and loads their pattern files. // A pattern setting becomes a single rule holding that pattern and no target. func resolveRules(settings feedSettings, baseDir string) ([]Rule, error) { if settings.Pattern != nil && settings.Rules != nil { return nil, errors.New("set pattern or rules, not both") } if settings.Pattern != nil { pattern, err := loadPattern(*settings.Pattern, baseDir) if err != nil { return nil, err } return []Rule{{Patterns: []Pattern{pattern}}}, nil } if len(settings.Rules) == 0 { return nil, errors.New("pattern or rules is required") } rules := make([]Rule, len(settings.Rules)) var errs []error for i, ruleSettings := range settings.Rules { rule, err := resolveRule(ruleSettings, baseDir) if err != nil { errs = append(errs, fmt.Errorf("rules[%d]: %w", i, err)) } rules[i] = rule } return rules, errors.Join(errs...) } // resolveRule validates one rule and loads its pattern files. func resolveRule(settings ruleSettings, baseDir string) (Rule, error) { rule := Rule{Target: settings.Target} var errs []error if len(settings.Patterns) == 0 { errs = append(errs, errors.New("patterns is required")) } if rule.Target != "" && slices.Contains(strings.Split(rule.Target, "."), "") { errs = append(errs, fmt.Errorf("target %q is not a valid dot path", rule.Target)) } for _, path := range settings.Patterns { pattern, err := loadPattern(path, baseDir) if err != nil { errs = append(errs, err) continue } rule.Patterns = append(rule.Patterns, pattern) } return rule, errors.Join(errs...) } // loadPattern reads the Quamina pattern file at path, resolved relative to baseDir. func loadPattern(path, baseDir string) (Pattern, error) { if path == "" { return Pattern{}, errors.New("pattern path must not be empty") } if !filepath.IsAbs(path) { path = filepath.Join(baseDir, path) } data, err := os.ReadFile(path) switch { case err != nil: return Pattern{}, fmt.Errorf("reading pattern: %w", err) case !json.Valid(data): return Pattern{}, fmt.Errorf("pattern %s is not valid JSON", path) } return Pattern{Path: path, JSON: string(data)}, nil } func ptr[T any](value T) *T { return &value }