Documentation
¶
Overview ¶
Package domain holds the routing domain's contracts: the ports, DTOs, enums, constants, and pure validation for resolving a repository (and a PR's changed files) to the Slack channel(s) and behavioural config that apply, across the global/org/repo tiers and monorepo path rules.
It depends only on the standard library, the shared kernel, and the YAML codec used to decode the mappings section of config.yaml onto these types (transition debt: the wire-decoding lives on the domain types until a later phase splits wire types from domain types). It never imports application, infrastructure, or a platform client (store/slack/github).
Index ¶
- Constants
- Variables
- func IsChannelID(value string) bool
- func ParsePartyDeadline(value string) (time.Duration, error)
- func ParsePartyReviewers(value string) (int, error)
- func ValidatePartyReviewers(value int) error
- type ChangedFilesReader
- type ChannelSpec
- type Defaults
- type DigestConfig
- type Entry
- type EntryLister
- type File
- type NotificationStrategy
- type NotificationsConfig
- type Org
- type PartyOverride
- type PartyRules
- type PartySettings
- type PathRule
- type Reactions
- type ReactionsOverride
- type RepoConfig
- type RepoMapping
- type Resolved
- type RoutingProvider
- type ScheduleMode
- type Target
- type TargetResolver
- type TimeOfDay
Constants ¶
const ( DefaultPartyReviewers = 1 MinPartyReviewers = 1 DefaultPartyDeadline = time.Hour MinPartyDeadline = 15 * time.Minute MaxPartyDeadline = 24 * time.Hour // PartyDeadlineRangeText spells the bounds in the format the parser accepts. PartyDeadlineRangeText = "15m to 24h" // PartyDeadlinePattern allows hours and minutes only, like 15m, 2h or 1h30m. PartyDeadlinePattern = "^(?:[0-9]+h)?(?:[0-9]+m)?$" )
Party defaults, the smallest cap and the allowed range of the party deadline.
const AtTimeLayout = "15:04"
AtTimeLayout is the `at:` time format: 24-hour HH:MM.
const ChannelMention = "<!channel>"
ChannelMention is the Slack wire token used when an entry omits the `mentions:` key — operators see `@channel` in Slack.
const DefaultDigestSchedule = "0 9 * * *"
DefaultDigestSchedule is the cron spec used when the digest section is absent or omits `schedule`: 9am every morning, in the configured digest timezone (default UTC; see DigestConfig.Timezone).
const HourlyCronSpec = "0 * * * *"
HourlyCronSpec is the cron spec of the hourly schedule mode.
const WildcardKey = "*"
WildcardKey is the org-level tier key (the literal "*"): it both supplies defaults that explicit repo tiers inherit and matches any repo not named explicitly.
Variables ¶
var ErrNotFound = errors.New("store: not found")
ErrNotFound is returned when a repository resolves to no mapping. It is the routing provider's port-contract sentinel. The message string is retained verbatim ("store: not found") so store.ErrNotFound can alias this value during the migration without changing any error text or errors.Is behaviour.
Functions ¶
func IsChannelID ¶ added in v0.25.0
IsChannelID reports whether value is a well-formed Slack channel id.
func ParsePartyDeadline ¶ added in v0.32.0
ParsePartyDeadline parses a party deadline written in hours and minutes.
func ParsePartyReviewers ¶ added in v0.32.0
ParsePartyReviewers parses a party cap written as a whole number.
func ValidatePartyReviewers ¶ added in v0.32.0
ValidatePartyReviewers checks that a party needs at least MinPartyReviewers reviewers.
Types ¶
type ChangedFilesReader ¶
type ChangedFilesReader interface {
ListPullRequestFiles(ctx context.Context, owner, repo string, number int) ([]string, error)
}
ChangedFilesReader fetches the repo-relative paths a PR touches. The GitHub client satisfies it.
type ChannelSpec ¶ added in v0.24.0
ChannelSpec is one entry in a tier's or path rule's `channels:` list: a Slack channel and the mentions to ping there. Mentions carry the same tri-state as a single tier (MentionsPresent distinguishes an absent key — which defaults to ChannelMention — from an explicit empty list that pings nobody).
type Defaults ¶
type Defaults struct {
Reactions Reactions
IgnoreAIReviews bool
DependabotFormat bool
DeleteOnClose bool
Party PartySettings
// GitProvider is the deployment's single git_provider; the Provider stamps it
// on every entry so it hashes into the lock (see Entry.Provider).
GitProvider kernel.Provider
}
Defaults is the global tier: the config.yaml top-level behavioral settings that per-repo tiers override.
type DigestConfig ¶
DigestConfig is the `digest:` section: a scheduled reminder that lists open PRs nobody has touched since the previous day. The global section is optional and the feature is opt-in, so an absent section (or one without `enabled: true`) behaves like `{enabled: false}` with the default schedule. Per-repo tiers reuse this type to override Enabled/Schedule.
Timezone and Country are global-only — the server runs a single cron clock and serves a single team calendar, so both belong on the global section and are rejected on a per-repo tier. An empty Timezone means the default (UTC); config.Load resolves it to a *time.Location and fails fast on an invalid zone. An empty Country means no holiday table: weekends are still skipped, but public holidays are not.
type Entry ¶
type Entry struct {
Org string
Repo string // empty when Wildcard is true
Wildcard bool
Channel string
Mentions []string
// ExtraChannels are the distinct channels a repo can post to beyond its
// primary Channel — extra base-list channels plus per-path channels (sorted,
// deduped). They feed both validation (bot membership) and the entry hash, so
// adding or repointing one re-triggers validation. Always empty for a wildcard
// entry unless the org/* tier itself uses a channels: list.
ExtraChannels []string
// Provider is the deployment's git_provider (e.g. "github"). It hashes into
// every entry so flipping the provider — under which the same org/repo names
// point at different remote objects — revalidates the whole lock.
Provider kernel.Provider
// DeleteOnClose is the entry's resolved cleanup.delete_on_close. It hashes
// into the entry because it adds required Slack scopes; omitted when false so
// existing lock hashes stay valid.
DeleteOnClose bool
}
Entry is one validation unit: an explicit (org, repo) pair or an (org, "*") wildcard. Each entry has its own hash in mappings.lock.
func (Entry) Hash ¶
Hash is the cache key for an entry: sha256 over canonical JSON of the validation-relevant fields. Mentions are deliberately excluded — they only affect message formatting at Slack-send time, not anything the validator checks (channel membership, bot scopes, webhook events). A mention edit shouldn't invalidate the entry's cache.
type EntryLister ¶ added in v0.29.0
type EntryLister interface {
Entries() []Entry
}
EntryLister lists the validation entries of the configured mappings.
type File ¶
type File struct {
Digest *DigestConfig `yaml:"digest"`
Mappings map[string]Org `yaml:"mappings"`
}
File is the parsed mappings.yaml document.
type NotificationStrategy ¶ added in v0.27.0
type NotificationStrategy string
NotificationStrategy decides when a PR event reaches Slack.
const ( // StrategyPerEvent posts or updates one Slack message per PR as each event // arrives. It is the default when no tier sets a strategy. StrategyPerEvent NotificationStrategy = "per-event" // StrategyScheduled queues new PRs and posts one list message per channel // on the tier's schedule. StrategyScheduled NotificationStrategy = "scheduled" )
type NotificationsConfig ¶ added in v0.27.0
type NotificationsConfig struct {
Strategy NotificationStrategy
Mode ScheduleMode
At []TimeOfDay
Cron []string
}
NotificationsConfig is a tier's `notifications:` block. The per-event strategy (also the zero value) posts as each event arrives; the scheduled strategy queues new PRs and sends one list per channel at the times its Mode describes. Send times run in the digest timezone.
func (NotificationsConfig) Scheduled ¶ added in v0.27.0
func (c NotificationsConfig) Scheduled() bool
Scheduled reports whether PR events are queued for a scheduled send.
func (NotificationsConfig) Specs ¶ added in v0.27.0
func (c NotificationsConfig) Specs() []string
Specs returns the cron specs the scheduled strategy sends on, or nil for the per-event strategy.
type Org ¶
type Org map[string]RepoConfig
Org maps each repo name (or the literal "*") to its tier config. The "*" key is the org-level tier: it both supplies defaults that explicit repo tiers inherit and matches any repo not named explicitly.
type PartyOverride ¶ added in v0.32.0
type PartyOverride struct {
Reviewers *int
Deadline *time.Duration
// Declared is true when the entry names a party key, even with an empty value.
Declared bool
}
PartyOverride is the optional party cap and timer a tier or path sets; a nil field inherits from a less specific level.
func (PartyOverride) IsSet ¶ added in v0.32.0
func (override PartyOverride) IsSet() bool
IsSet reports whether the override sets a cap or a timer.
type PartyRules ¶ added in v0.32.0
type PartyRules interface {
// HasPartyPathRules reports whether a path rule of the repository sets party_reviewers or party_deadline.
HasPartyPathRules(repository string) bool
// PartySettings returns the highest cap and the shortest timer over the files.
// No files give the repository's values.
PartySettings(repository string, files []string) PartySettings
}
PartyRules answers the party cap and timer of a repository from the mappings. Repository names match in any case.
type PartySettings ¶ added in v0.32.0
PartySettings is the resolved party cap and timer of a repository.
type PathRule ¶
type PathRule struct {
Dir string
Channel string
Mentions []string
MentionsPresent bool
// Channels is the path rule's `channels:` fan-out list. Mutually exclusive
// with Channel/Mentions (enforced at decode); nil means the single Channel
// form. List entries default absent mentions to ChannelMention.
Channels []ChannelSpec
// Party is the path rule's review-party override.
Party PartyOverride
}
PathRule is one entry in a repo tier's `paths:` block: a normalized directory and the routing applied to files under it. Channel/Mentions carry the same tri-state inheritance as a repo tier (empty Channel inherits; MentionsPresent distinguishes absent from an explicit empty list).
type Reactions ¶
type Reactions struct {
Enabled bool
NewPR string
MergedPR string
ClosedPR string
Approved string
Commented string
RequestChange string
BotReview string
}
Reactions is the resolved per-repo reaction-emoji set (Slack emoji names without colons). Enabled gates whether close/review reactions are added at all. Empty BotReview disables the bot-reviewer marker.
type ReactionsOverride ¶
type ReactionsOverride struct {
Enabled *bool
NewPR *string
MergedPR *string
ClosedPR *string
Approved *string
Commented *string
RequestChange *string
BotReview *string
}
ReactionsOverride is a tier's optional reaction overrides; each nil field inherits from a less-specific tier (org/* then the global config.yaml set).
type RepoConfig ¶
type RepoConfig struct {
Channel string
Mentions []string
MentionsPresent bool
Reactions *ReactionsOverride
IgnoreAIReviews *bool
DependabotFormat *bool
DeleteOnClose *bool
Digest *DigestConfig
// Notifications is the tier's `notifications:` block. It is atomic: the
// most specific tier that sets it wins whole, so a half-set schedule
// cannot be inherited. Nil inherits.
Notifications *NotificationsConfig
// Paths is the optional per-directory routing for a monorepo, in
// declaration order (order is significant for tie-breaking). Only valid on
// a named repo tier — ValidateMappings rejects it on the "*" tier.
Paths []PathRule
// Channels is the tier's `channels:` fan-out list (unconditional multi-channel
// base). Mutually exclusive with Channel/Mentions — exactly one form is
// populated per tier, enforced at decode. Nil means the single Channel form.
Channels []ChannelSpec
// Party is the tier's review-party override; the Slack routing ignores it.
Party PartyOverride
}
RepoConfig is one tier (org/repo or org/*). Phase A carries routing only. An empty Channel means this tier does not set a channel (it inherits). MentionsPresent distinguishes an absent mentions key (inherit) from an explicit empty list (ping nobody).
func (RepoConfig) PartyOnly ¶ added in v0.32.0
func (tier RepoConfig) PartyOnly() bool
PartyOnly reports whether the tier and all its path rules set party keys and no Slack routing, so the tier routes nothing to Slack.
type RepoMapping ¶
type RepoMapping struct {
Repository string
SlackChannel string
Mentions []string
// Resolved per-repo behavioral config (global config.yaml defaults merged
// with org/* and org/repo overrides). Formatting-only — not part of
// validation or the lock.
Reactions Reactions
IgnoreAIReviews bool
DependabotFormat bool
// DeleteOnClose removes the Slack message when the PR is merged or declined
// instead of updating it with the [Merged]/[Closed] decoration.
DeleteOnClose bool
// Notifications is the resolved strategy: per-event, or scheduled with its
// send times.
Notifications NotificationsConfig
}
RepoMapping is the value object handlers and validators consume — a GitHub repository routed to a Slack channel with an optional mentions list, and resolved behavioral config (global defaults merged with org/* and org/repo overrides). The source of truth for routing lives in config.yaml's mappings: section (loaded by internal/config / internal/mappings); the type stays here so consumers don't have to know who produced it.
type Resolved ¶
Resolved is the effective routing config for one repository after merging the org/repo tier over the org/* tier.
type RoutingProvider ¶
type RoutingProvider interface {
// Get returns the resolved mapping for "org/repo", or ErrNotFound when no
// tier matches.
Get(ctx context.Context, repository string) (RepoMapping, error)
// RepoHasPathRules reports whether the repository configures a `paths:` block.
RepoHasPathRules(repository string) bool
// TargetsForFiles returns the fan-out destinations for a PR touching files.
TargetsForFiles(repository string, files []string) []Target
// BaseTargets returns the repository's unconditional base fan-out targets,
// used when the repo has no path rules or no changed-files reader.
BaseTargets(repository string) []Target
}
RoutingProvider resolves a repository to its behavioural mapping and, for a monorepo with path rules, the per-channel fan-out targets for a set of changed files. The application-layer provider satisfies it; the per-PR router depends on it.
type ScheduleMode ¶ added in v0.27.0
type ScheduleMode string
ScheduleMode is how a scheduled strategy writes its send times.
const ( // ScheduleModeHourly sends at the top of every hour. ScheduleModeHourly ScheduleMode = "hourly" // ScheduleModeAt sends once a day at each listed time. ScheduleModeAt ScheduleMode = "at" // ScheduleModeCron sends on each listed cron spec. ScheduleModeCron ScheduleMode = "cron" )
type Target ¶
Target is one fan-out destination resolved for a PR: a channel and the mentions to ping there. Produced by the mappings resolver, consumed by the open handler.
type TargetResolver ¶
type TargetResolver interface {
ResolveTargets(ctx context.Context, repository string, prNumber int) (RepoMapping, []Target, error)
}
TargetResolver resolves the per-PR fan-out: the repository's behaviour plus the per-channel targets, layering path rules over the base tier when a changed-files reader is available.