domain

package
v0.30.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 28, 2026 License: MIT Imports: 6 Imported by: 0

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

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

View Source
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

type AnnouncedPR struct {
	Repository string
	PRNumber   int
	Channel    string
}

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

type CalendarParams struct {
	Country string
	Logger  *slog.Logger
}

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

type DigestScheduler interface {
	Run(ctx context.Context) error
}

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

type Message struct {
	Blocks   []Block
	Fallback string
}

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

type PullRequest struct {
	Repository string
	PRNumber   int
	UpdatedAt  time.Time
}

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

type ScheduleJob interface {
	ReportSchedule(ctx context.Context, spec string) error
}

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

type StuckPR struct {
	Repository string
	Number     int
	URL        string
	IdleDays   int
}

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

type TextObject struct {
	Type string
	Text string
}

TextObject is a block's text payload.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL