Documentation
¶
Overview ¶
Package domain holds the maintenance domain's contracts: the ports, DTOs, enums, and constants for stale-message cleanup and PR reconcile. It depends only on the standard library and the shared kernel.
Index ¶
- Constants
- Variables
- type ChannelConfig
- type CleanerParams
- type Closer
- type Deleter
- type MessageCourier
- type MessageRows
- type OpenLister
- type PRChecker
- type PRRow
- type ReactionPolicy
- type Reconciler
- type ReconcilerParams
- type RelocateSummary
- type Relocator
- type RelocatorParams
- type StaleMessage
- type StaleMessageCleaner
- type StaleMessageDeleter
- type Summary
- type TrackedLister
- type TrackedMessage
- type TrackedPR
Constants ¶
const Interval = 24 * time.Hour
Interval is the fixed cadence between stale-message cleanup passes. 24h is conservative enough that a transient DB error has nearly a full day to clear before the next attempt.
Variables ¶
var ErrMessageGone = errors.New("relocate: message no longer exists")
ErrMessageGone marks an original message the messenger no longer has: it was deleted by hand, or the bot lost sight of the channel. There is nothing to carry over, so the relocator drops the row instead of failing the run.
var ErrPRDraft = errors.New("reconcile: pull request is a draft")
ErrPRDraft marks a draft PR. A draft must never stay in the database (regardless of open/closed state), so the reconciler deletes its row the same way the live converted_to_draft webhook does — the difference being this catches drafts in the pre-tracking backlog.
var ErrPRNotFound = errors.New("reconcile: pull request not found")
ErrPRNotFound marks a PR that GitHub reports as 404 — deleted, or in a repo that was renamed or is no longer accessible. The reconciler treats it distinctly from other API errors: rather than leave the row untouched, it removes the PR from the digest (a 404 will never resolve on its own).
Functions ¶
This section is empty.
Types ¶
type ChannelConfig ¶ added in v0.25.0
ChannelConfig reports every channel a repository is currently configured to post to — its base fan-out plus any `paths:` channels. A stored message in a channel absent from this set is stale routing.
type CleanerParams ¶
type CleanerParams struct {
Deleter StaleMessageDeleter
TTL time.Duration
Interval time.Duration
Logger *slog.Logger
Now func() time.Time
}
CleanerParams bundles everything the stale-message cleaner needs. TTL is the maximum age a row may reach before it becomes eligible for deletion; Interval is the cadence between passes (use the Interval constant in production); Now supplies the clock (time.Now in production, a fixed clock in tests).
type Deleter ¶
Deleter removes a PR's row entirely. Used for drafts, which must not stay in the database at all (a draft is not review-ready; the row is recreated by the open webhook if it is later marked ready_for_review).
type MessageCourier ¶ added in v0.25.0
type MessageCourier interface {
Repost(ctx context.Context, from TrackedMessage, toChannel string) (string, error)
CopyReactions(ctx context.Context, from, to TrackedMessage, allowed []string) error
MarkMoved(ctx context.Context, from TrackedMessage, toChannel string) error
}
MessageCourier carries a posted message between channels. Repost reads the original, rewrites it as a mention-free "moved" message and posts it to toChannel, returning the new message id; it reports ErrMessageGone when the original is no longer there. CopyReactions re-adds the source message's reactions, restricted to allowed, so a relocated message keeps its review state without inheriting ad-hoc human reactions the bot cannot attribute. MarkMoved edits the original in place into a pointer at toChannel: the message is never deleted, so the thread hanging off it survives the move.
type MessageRows ¶ added in v0.25.0
type MessageRows interface {
MoveMessage(ctx context.Context, repository string, prNumber int, fromChannel, toChannel, messageID string) error
RemoveMessage(ctx context.Context, repository string, prNumber int, channel string) error
}
MessageRows retargets or drops a PR's stored message row. It never touches the messenger — only the database row that records where a message lives.
type OpenLister ¶
OpenLister lists the tracked PR rows not yet marked closed.
type PRChecker ¶
type PRChecker interface {
IsOpen(ctx context.Context, repository string, prNumber int) (bool, error)
}
PRChecker reports whether a PR is still open on GitHub.
type PRRow ¶
PRRow is the maintenance view of one tracked PR: the fields the reconciler reads to check and resolve it. It is mapped from the store's persistence model at the repository boundary, so no gorm-tagged type crosses a port.
type ReactionPolicy ¶ added in v0.25.0
type ReactionPolicy interface {
AllowedReactions(ctx context.Context, repository string) ([]string, error)
}
ReactionPolicy lists the reaction emoji a repository's notifications use, so a relocated message carries those and nothing else.
type Reconciler ¶
Reconciler resolves every not-yet-closed tracked PR against GitHub: a merged/closed PR is marked closed, a 404 is removed from the digest, and a draft is deleted outright (a draft must never stay in the database). Per-PR errors are logged and counted, never fatal — an unconfirmable row is left untouched so a token-scope miss never wrongly hides an open PR, and re-running is safe. Run reports the tallies in a Summary.
type ReconcilerParams ¶
type ReconcilerParams struct {
Lister OpenLister
Checker PRChecker
Closer Closer
Deleter Deleter
Logger *slog.Logger
DryRun bool
// Provider is the deployment's git host; it selects the web-URL form the
// per-PR log lines are reconstructed in. The zero value builds github.com URLs.
Provider kernel.Provider
}
ReconcilerParams bundles everything the reconciler needs. DryRun reports what would change without writing.
type RelocateSummary ¶ added in v0.25.0
type RelocateSummary struct {
Scanned int // open PRs holding a message in the source channel
Moved int // reposted in the destination and retargeted (would be, in dry-run)
Merged int // destination already had a message; the original became a pointer
Forgotten int // the row was dropped; the Slack message itself was left alone
Errors int
}
RelocateSummary tallies one relocate run.
type Relocator ¶ added in v0.25.0
type Relocator interface {
Run(ctx context.Context) (RelocateSummary, error)
Audit(ctx context.Context) ([]StaleMessage, error)
}
Relocator moves stored messages from one channel to another after an operator repoints a repository. Per PR it either moves the message (repost in the new channel, retarget the row, carry the reactions over, leave the original behind as a pointer), merges (the PR already has a message in the destination, so the original becomes a pointer and its row goes), or forgets it (no destination given: the row goes, the message is left alone). A per-PR failure is logged and counted, never fatal, and the run is idempotent: the row is retargeted immediately after the repost, so a re-run skips what already moved. Audit reports rows sitting in channels the config no longer mentions.
type RelocatorParams ¶ added in v0.25.0
type RelocatorParams struct {
Lister TrackedLister
Rows MessageRows
Courier MessageCourier
Reactions ReactionPolicy
Channels ChannelConfig
Logger *slog.Logger
From string
To string
Repository string
DryRun bool
}
RelocatorParams bundles everything the relocate use case needs. From is the channel to move messages out of; To is the destination, and an empty To means stop tracking the messages instead of moving them. Repository, when set, narrows the run to one "org/repo". DryRun reports what would change without writing.
type StaleMessage ¶ added in v0.25.0
StaleMessage is one audit finding: a stored message sitting in a channel the repository is no longer configured to post to.
type StaleMessageCleaner ¶
StaleMessageCleaner prunes stale slack_messages rows on a fixed cadence: one pass immediately on start, then one every Interval, until its context is cancelled. It deletes only database rows — never the Slack messages themselves. A pass's error is logged and swallowed so the next tick retries; Run always returns nil (so callers can compose it with other long-running goroutines without special-casing).
type StaleMessageDeleter ¶
type StaleMessageDeleter interface {
DeleteStaleBefore(ctx context.Context, cutoff time.Time) (int64, error)
}
StaleMessageDeleter deletes tracked-PR rows whose message predates a cutoff. It is the persistence port the cleanup use case drives; the maintenance infrastructure layer satisfies it over the store.
type Summary ¶
type Summary struct {
Checked int
Closed int // marked closed (in dry-run: would be marked)
Removed int // PR 404s or is a draft; dropped from the digest (would be, in dry-run)
StillOpen int
Errors int
}
Summary tallies one reconcile run.
type TrackedLister ¶ added in v0.25.0
TrackedLister lists open PRs together with the channels their messages currently live in. It is the relocate use case's read port.
type TrackedMessage ¶ added in v0.25.0
TrackedMessage is one posted message: the channel it lives in and the messenger's id for the post.
type TrackedPR ¶ added in v0.25.0
type TrackedPR struct {
Repository string
PRNumber int
Messages []TrackedMessage
}
TrackedPR is one open PR with every message posted for it. Mapped from the store's persistence model at the repository boundary.