Something went wrong. Try again.
a bluesky feed generator framework
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289package 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://<publisher>/app.bsky.feed.generator/<name>. 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.<name>.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}