domain

package
v0.23.1 Latest Latest
Warning

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

Go to latest
Published: Aug 24, 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 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 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 MappingLookup

type MappingLookup interface {
	Get(ctx context.Context, repository string) (routingdomain.RepoMapping, error)
}

MappingLookup resolves a repository to its Slack channel and mentions.

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 MessageRef

type MessageRef struct {
	Channel   string
	MessageID string
}

MessageRef is one posted message for a PR: the channel it lives in and the messenger's id for the post.

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
	Messages   []MessageRef
}

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
	Mappings MappingLookup
	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

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