README
¶
background
Keeps local GitHub metadata fresh while the daemon runs: discovery polls of
every picked repository, then reads of the saved reviews' evidence. It never
queues or starts generation. The daemon hands each successful snapshot to its
automatic scheduler through Discovered.
A pass
Run makes a pass at least every 30 seconds, or sooner when a repository is
due sooner, as one settling after a new head is. A pass (Sync):
- Probes (
discovery.Probe), at most once per interval (a minute). A repository whose open pull requests changed since its last poll polls now (PollNow), past discovery's backoff. A pull request opened or pushed from anywhere therefore shows within about a minute. A probe that succeeds after one that failed makes every repository whose poll failed meanwhile poll at once. - Polls every due repository,
pollConcurrency(3) at a time. Each poll stops once GitHub has not answered it forpollTimeout(45 s), so a busy repository's sweep may take minutes. Discovery keeps what it read when time runs out. The polls share the credential's GitHub budget, which discovery checks before every request. Their results are handled one at a time:Discovered, the repository's state, and the reads each poll makes due. - Reads the due saved pull requests within
refreshBudget: those GitHub reported changed first, then the oldest. A rate-limited read pauses reads on that host (Paused,Limited), which the PR page's facts share. A read that finds nothing new leaves the saved document unwritten, itsevidence_refreshed_atincluded (store.Store.RefreshCurrent), and still counts as the pull request's last read, in memory: an open one is read again after 15 minutes, a closed one after an hour. - Reconciles retained review refs (
Retain) once a day per common git directory.
A repository's state (GET /api/background) records its last success, its
next refresh and the error of the last pass: discovery_unavailable,
discovery_timeout (the poll ran out of time), rate_limited,
metadata_unavailable, store_unreadable or cache_unavailable. A failed
poll backs off exponentially, for at most 15 minutes. A settling poll is due
when discovery says.
Tests
just oss-go test -race ./internal/background
Documentation
¶
Overview ¶
Package background keeps local GitHub metadata fresh without a generation queue, model backend, checkout export or hosted baum service. It hands discovery snapshots to Service.Discovered and nothing else: automatic generation is the daemon's separate scheduler.
Index ¶
- func Saved(ctx context.Context, clone repos.Clone) ([]int, error)
- type Discovery
- type Local
- type Problem
- type Registry
- type Retention
- type Service
- func (s *Service) Handler() http.Handler
- func (s *Service) Limited(host string, until time.Time)
- func (s *Service) Paused(host string) time.Time
- func (s *Service) RefreshInterval() time.Duration
- func (s *Service) RefreshNow(ctx context.Context, clone repos.Clone, numbers []int) ([]discovery.Observation, error)
- func (s *Service) ResetIdentity()
- func (s *Service) Run(ctx context.Context)
- func (s *Service) Sync(ctx context.Context)
- type State
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Discovery ¶
type Discovery interface {
Poll(context.Context, github.Repository) (discovery.Snapshot, error)
PollNow(context.Context, github.Repository) (discovery.Snapshot, error)
Probe(context.Context, []github.Repository) (map[string]bool, error)
Observe(context.Context, github.Repository, discovery.Observation) error
}
type Registry ¶
type Registry interface {
Repositories(context.Context) ([]repos.Repository, error)
}
type Retention ¶
Retention reconciles the refs that keep saved review versions' commits in a clone (reviewrefs.Reconcile, within reviewrefs.DefaultLimits). A clone that cannot be opened or reconciled is skipped with a log line.
type Service ¶
type Service struct {
Registry Registry
Discovery Discovery
// Refresh must only read GitHub/local evidence and CAS-publish the latest
// saved review. It must never enqueue or invoke generation.
Refresh func(context.Context, repos.Clone, int) (discovery.Observation, error)
Saved func(context.Context, repos.Clone) ([]int, error)
// Discovered receives every snapshot a discovery poll returned without
// error. The daemon passes them to its automatic generation scheduler
// (internal/automatic), which alone decides whether to queue a job; this
// service never enqueues or invokes generation itself.
Discovered func(context.Context, discovery.Snapshot)
// Retain reconciles a clone's retained review refs with its stores and
// reports whether a bound left work for another pass (Retention.Retain);
// nil skips it. Sync calls it per common git directory, see retainDue.
Retain func(context.Context, repos.Clone) (bool, error)
Changed func()
Now func() time.Time
Interval time.Duration
// contains filtered or unexported fields
}
func (*Service) Limited ¶
Limited records a rate limit another reader of the account's GitHub budget hit, so refreshes wait it out too.
func (*Service) Paused ¶
Paused is when the host's rate limit lets refreshes resume, for another reader of the same account's GitHub budget, such as the PR page's facts (internal/facts), to wait it out too.
func (*Service) RefreshInterval ¶
RefreshInterval is how often the background refresh polls.
func (*Service) RefreshNow ¶
func (s *Service) RefreshNow(ctx context.Context, clone repos.Clone, numbers []int) ([]discovery.Observation, error)
RefreshNow refreshes some pull requests of one clone at once, as Sync refreshes each of them, outside Sync's schedule: a hook event said they changed. It honors the host's rate pause, which a rate-limited refresh here extends for Sync too, and returns the observations it made. It never enqueues or invokes generation.
func (*Service) ResetIdentity ¶
func (s *Service) ResetIdentity()
ResetIdentity drops credential-dependent backoff without waiting for an old network pass. Its late state/rate writes are fenced by the captured epoch.
func (*Service) Run ¶
Run starts immediately in its caller's goroutine. The host runs it separately from HTTP startup; a slow/offline GitHub never holds the cached inbox hostage. One pass runs at a time: its polls run pollConcurrency at once, its reads one at a time.
func (*Service) Sync ¶
Sync is a single serialized scheduling pass, exposed for deterministic tests. Discovery itself owns conditional requests and credential-wide rate budgets. It polls every due repository first, pollConcurrency at a time, so no repository's pull requests wait behind another's reads, then reads the saved pull requests that are due, those GitHub reported changed first, within refreshBudget.
Source Files