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 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 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 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
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 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.