Documentation
¶
Overview ¶
Package domain defines the digest domain's ports, DTOs, and constants — the scheduled stuck-PR reminder contracts. It imports only the standard library, the shared kernel, and the routing domain.
Index ¶
- Constants
- type AnnouncedPR
- type Block
- type CalendarParams
- type CountryCode
- type DigestCalendar
- type DigestComposer
- type DigestPoster
- type DigestReporter
- type DigestResolver
- type DigestScheduler
- type DigestTargets
- type HolidayRule
- type Message
- type ObservanceKind
- type PullRequest
- type ReporterParams
- type RuleKind
- type ScheduleJob
- type ScheduledAnnouncements
- type SchedulerParams
- type StuckFinder
- type StuckPR
- type TextObject
Constants ¶
const ( SkipReasonWeekend = "weekend" SkipReasonHoliday = "holiday" )
Skip reasons for the "skipped digest" log line. They mirror the `ignored webhook event` reason contract: a small closed set of values an operator can grep for.
const BlockTypeSection = "section"
BlockTypeSection is the block type the digest emits (a Block Kit "section").
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AnnouncedPR ¶ added in v0.27.0
AnnouncedPR is one PR the scheduled notification strategy announces (or already announced) in a channel.
type Block ¶
type Block struct {
Type string
Text *TextObject
}
Block is one rendered block of a Message. The digest emits only section blocks (Type == BlockTypeSection, Text set).
type CalendarParams ¶ added in v0.23.0
CalendarParams bundles the calendar's inputs. Country is an ISO 3166-1 alpha-2 code, case-insensitive; empty means no holiday table (weekends only, plus a warning at construction).
type CountryCode ¶ added in v0.23.0
type CountryCode string
CountryCode is an ISO 3166-1 alpha-2 country code selecting a holiday table. The empty code means no country is configured: weekends are still skipped, but no holiday is.
const ( CountryAustria CountryCode = "AT" CountryBelgium CountryCode = "BE" CountryDenmark CountryCode = "DK" CountryFinland CountryCode = "FI" CountryFrance CountryCode = "FR" CountryGermany CountryCode = "DE" CountryIreland CountryCode = "IE" CountryItaly CountryCode = "IT" CountryLuxembourg CountryCode = "LU" CountryNetherlands CountryCode = "NL" CountryNorway CountryCode = "NO" CountryPoland CountryCode = "PL" CountryPortugal CountryCode = "PT" CountrySpain CountryCode = "ES" CountrySweden CountryCode = "SE" CountrySwitzerland CountryCode = "CH" CountryUkraine CountryCode = "UA" CountryUnitedKingdom CountryCode = "GB" CountryUnitedStates CountryCode = "US" )
The supported country codes. Each one has a table in holidays.go; a code absent from that map is rejected at startup.
func SupportedCountries ¶ added in v0.23.0
func SupportedCountries() []CountryCode
SupportedCountries returns every supported country code, sorted, for error messages and documentation.
type DigestCalendar ¶ added in v0.23.0
type DigestCalendar interface {
SkipReason(now time.Time) (reason string, skip bool)
HolidayName(now time.Time) (string, bool)
// Country is the resolved ISO 3166-1 alpha-2 code, empty when none is
// configured. It is logged alongside a holiday skip.
Country() string
}
DigestCalendar decides whether a digest tick on a given day should be suppressed. The scheduler consults it before running the job, so a skipped day makes no Slack call at all. The returned reason is the value of the `reason` field on the "skipped digest" log line — SkipReasonWeekend or SkipReasonHoliday.
Weekends are always skipped, whatever the configured schedule. Holidays are skipped only when a country is configured; with no country the calendar warns once at construction and reports weekends only.
type DigestComposer ¶
type DigestComposer interface {
StuckDigestParent(mentions []string, count int) Message
StuckDigestList(prs []StuckPR) Message
}
DigestComposer renders the two messages of a channel's stuck-PR digest: a parent headline carrying the mentions and PR count, and a threaded list of one line per stuck PR. Implementations produce a presentation-neutral Message the poster delivers.
type DigestPoster ¶
type DigestPoster interface {
PostMessage(ctx context.Context, channel string, msg Message) (string, error)
PostReply(ctx context.Context, channel, threadTS string, msg Message) (string, error)
}
DigestPoster posts a composed message to a channel, either as a top-level post (PostMessage, returning its id) or threaded under one (PostReply).
type DigestReporter ¶
type DigestReporter interface {
Report(ctx context.Context) error
ReportSchedule(ctx context.Context, spec string) error
}
DigestReporter runs one stuck-PR digest pass: find open PRs idle since the start of today, group them by channel, and post one reminder per channel. Report includes every enabled repo; ReportSchedule includes only repos whose effective digest is enabled and scheduled at spec.
type DigestResolver ¶
type DigestResolver interface {
DigestFor(repository string) routingdomain.DigestConfig
}
DigestResolver looks up the effective digest configuration for a repository.
type DigestScheduler ¶
DigestScheduler runs one cron per distinct schedule spec, calling its job for each tick, and blocks until its context is cancelled.
type DigestTargets ¶ added in v0.25.0
type DigestTargets interface {
BaseTargets(repository string) []routingdomain.Target
}
DigestTargets returns the channels a repository's digest is delivered to, with the mentions to ping in each. The routing provider's base fan-out satisfies it: the digest is a repo-level reminder, so it goes to the repository's configured base channels, never to a `paths:` channel — which path rule applied to a given PR is not knowable without re-reading the PR's changed files.
type HolidayRule ¶ added in v0.23.0
type HolidayRule struct {
Name string
Kind RuleKind
// Month applies to RuleFixed, RuleNthWeekday, and RuleWeekdayOnOrAfter.
Month time.Month
// Day applies to RuleFixed and, as the anchor, to RuleWeekdayOnOrAfter.
Day int
// EasterDays applies to RuleEasterOffset.
EasterDays int
// Weekday applies to RuleNthWeekday and RuleWeekdayOnOrAfter.
Weekday time.Weekday
// Nth applies to RuleNthWeekday: 1..5, or -1 for the last in the month.
Nth int
Observance ObservanceKind
}
HolidayRule is one entry of a country's holiday table: how the date is derived (Kind) and what happens when it lands on a weekend (Observance). Only the fields relevant to Kind are set; the rest stay zero.
func HolidayTable ¶ added in v0.23.0
func HolidayTable(code CountryCode) ([]HolidayRule, bool)
HolidayTable returns the rule table for a country code, and whether the code is supported.
type Message ¶
Message is a presentation-neutral rendered message that crosses the composer and poster ports. The application treats it as opaque — it only carries a composer's output to the poster; the Slack adapter maps it to and from the platform message type at the boundary.
type ObservanceKind ¶ added in v0.23.0
type ObservanceKind uint8
ObservanceKind selects what happens when a rule's natural date lands on a weekend. It is only ever consulted for RuleFixed: every Easter-derived holiday falls on a fixed weekday, and an Nth-weekday rule names its weekday outright, so neither can collide with a weekend.
const ( // ObserveNone loses the holiday when it falls on a weekend. This is the // real rule in Germany, France, and most of continental Europe. ObserveNone ObservanceKind = iota // ObserveUSShift moves a Saturday date to the preceding Friday and a Sunday // date to the following Monday — the US federal rule. ObserveUSShift // ObserveUKSubstitute moves the date forward to the first weekday not // already claimed by another holiday, so consecutive weekend holidays // produce consecutive substitute days. ObserveUKSubstitute )
type PullRequest ¶
PullRequest is the digest's view of one tracked PR: the fields the reporter reads to build a reminder. It is mapped from the store's persistence model at the repository boundary, so no gorm-tagged type crosses a port.
type ReporterParams ¶
type ReporterParams struct {
Finder StuckFinder
Targets DigestTargets
Poster DigestPoster
Composer DigestComposer
Digests DigestResolver
Announcements ScheduledAnnouncements
Logger *slog.Logger
TZ *time.Location
Now func() time.Time
// Provider is the deployment's git host; it selects the web-URL form each
// stuck PR's link is reconstructed in. The zero value builds github.com URLs.
Provider kernel.Provider
}
ReporterParams bundles everything the stuck-PR reporter needs. Now supplies the clock (time.Now in production, a fixed clock in tests); TZ is the timezone the "start of day" cutoff is computed in (nil defaults to UTC) and must match the scheduler's timezone so a digest fires and cuts off in the same zone.
type RuleKind ¶ added in v0.23.0
type RuleKind uint8
RuleKind selects how a HolidayRule resolves to a date in a given year.
const ( // RuleFixed is a fixed calendar date: Month + Day. RuleFixed RuleKind = iota // RuleEasterOffset is a whole number of days from Easter Sunday // (negative before, positive after). RuleEasterOffset // RuleNthWeekday is the Nth Weekday of Month, where Nth == -1 means the // last one in the month. RuleNthWeekday // RuleWeekdayOnOrAfter is the first Weekday falling on or after Month/Day. // It exists for the Nordic Midsummer Eve ("the Friday on or after 19 June"), // which neither a fixed date nor an Nth-weekday rule can express. RuleWeekdayOnOrAfter )
type ScheduleJob ¶
ScheduleJob is the unit the scheduler fires on each cron tick; the reporter satisfies it. spec is the cron expression that fired, so the job can include only the repos scheduled at that spec.
type ScheduledAnnouncements ¶ added in v0.27.0
type ScheduledAnnouncements interface {
AnnouncedSince(ctx context.Context, cutoff time.Time) ([]AnnouncedPR, error)
}
ScheduledAnnouncements lists the (PR, channel) pairs the scheduled notification strategy has queued but not sent yet, or sent at or after cutoff. The reporter leaves those pairs out, so one PR never shows in a channel's scheduled list and its stuck digest on the same day.
type SchedulerParams ¶
type SchedulerParams struct {
Specs []string
Job ScheduleJob
Logger *slog.Logger
TZ *time.Location
// Calendar suppresses ticks on weekends and holidays. A nil Calendar runs
// every tick, which is what the tests that predate the calendar expect.
Calendar DigestCalendar
// Now supplies the tick's wall clock (time.Now in production, a fixed clock
// in tests). It is evaluated in TZ before reaching the calendar.
Now func() time.Time
}
SchedulerParams bundles everything the digest scheduler needs. Specs is a list of standard 5-field cron expressions; TZ is the timezone every spec is interpreted in (nil defaults to UTC).
type StuckFinder ¶
type StuckFinder interface {
FindStuck(ctx context.Context, cutoff time.Time) ([]PullRequest, error)
}
StuckFinder returns open PRs (with their messages) idle since before cutoff.
type StuckPR ¶
StuckPR is one line of a channel's digest list: the PR, its web URL, and how many whole days it has sat idle.
type TextObject ¶
TextObject is a block's text payload.