domain

package
v0.32.0 Latest Latest
Warning

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

Go to latest
Published: Nov 4, 2026 License: MIT Imports: 6 Imported by: 0

Documentation

Overview

Package domain holds the feed contracts: pull-request and subscription models, ports and use-case interfaces.

Index

Constants

View Source
const (
	AllRepositories          = "*"
	MaxSubscriptionsPerToken = 200
	MaxRequestBodyBytes      = 16 << 10
	RepositoryNamePattern    = `^[a-z0-9._-]+/[a-z0-9._-]+$`

	ListSubscriptionsPattern   = "GET /api/v1/subs"
	AddSubscriptionsPattern    = "POST /api/v1/subs"
	ChangeSubscriptionsPattern = "PATCH /api/v1/subs"
	RemoveSubscriptionPattern  = "DELETE /api/v1/subs/{id}"
	PullRequestsPattern        = "GET /api/v1/subs/prs"
	RepositoriesPattern        = "GET /api/v1/repos"
	SubscriptionIDPathValue    = "id"
	SinceQueryParameter        = "since"
)

Feed limits, the repository name rule, routes and parameter names.

View Source
const AwayAfter = 24 * time.Hour

AwayAfter is how long a party member stays a candidate after its last fetch.

View Source
const DayLayout = "2006-01-02"

DayLayout formats the day of the party loads.

View Source
const FetchResolution = time.Minute

FetchResolution is how old a stored fetch time must be before a fetch writes a new one.

View Source
const PartyFilesReadTimeout = 2 * time.Second

PartyFilesReadTimeout caps how long the party settings wait for the changed files of a pull request.

View Source
const RecordTimeout = 3 * time.Second

RecordTimeout caps how long a webhook waits for the feed record.

Variables

View Source
var (
	ErrSubscriptionNotFound = errors.New("feed: subscription not found")
	ErrTooManySubscriptions = errors.New("feed: too many subscriptions")
	ErrNoRepositories       = errors.New("feed: no repositories")
	ErrInvalidType          = errors.New("feed: invalid subscription type")
	ErrMalformedRepository  = errors.New("feed: repository is not owner/name")
)

Feed sentinel errors.

Functions

func LoadDay added in v0.32.0

func LoadDay(moment time.Time) string

LoadDay returns the UTC date of the moment, so the party loads start again at 00:00 UTC.

Types

type Claim

type Claim struct {
	TokenID      string
	Repositories []string
	DeliveredAt  time.Time
}

Claim asks the store to mark pull requests delivered to a token and return the newly claimed ones.

type CleanupReason

type CleanupReason string

CleanupReason says why stored pull requests or subscriptions were removed at startup.

const (
	CleanupReasonAgentAPIOff CleanupReason = "agent_api_off"
	CleanupReasonUnmapped    CleanupReason = "unmapped"
)

Startup cleanup reasons.

type Clock

type Clock interface {
	Now() time.Time
}

Clock provides the current time.

type ConfiguredRepositories added in v0.31.0

type ConfiguredRepositories struct {
	// Repositories are the explicitly configured repositories, sorted.
	Repositories []string
	// Organizations have an org tier, so each of their repositories is configured too; sorted.
	Organizations []string
}

ConfiguredRepositories is what a token can subscribe to.

type DeliveryStore

type DeliveryStore interface {
	// Claim returns only pull requests not yet delivered to the token, marking them delivered at most once.
	Claim(ctx context.Context, claim Claim) ([]PullRequest, error)
	// ClaimParty delivers the pull requests the turn rule lets the token take, at most once each, in one atomic step.
	ClaimParty(ctx context.Context, claim PartyClaim) (PartyClaimResult, error)
}

DeliveryStore records which pull requests were delivered to which token.

type ErrorCode

type ErrorCode string

ErrorCode is the machine-readable code in an HTTP error body.

const (
	ErrorCodeUnauthorized         ErrorCode = "unauthorized"
	ErrorCodeInvalidBody          ErrorCode = "invalid_body"
	ErrorCodeUnknownRepository    ErrorCode = "unknown_repository"
	ErrorCodeTooManySubscriptions ErrorCode = "too_many_subscriptions"
	ErrorCodeInvalidType          ErrorCode = "invalid_type"
	ErrorCodeNotSubscribed        ErrorCode = "not_subscribed"
	ErrorCodeInvalidSince         ErrorCode = "invalid_since"
	ErrorCodeNotFound             ErrorCode = "not_found"
	ErrorCodeInternal             ErrorCode = "internal_error"
	ErrorCodeMethodNotAllowed     ErrorCode = "method_not_allowed"
)

HTTP error codes.

type FetchStore added in v0.32.0

type FetchStore interface {
	// Record stores the fetch time of the token. It keeps a stored time that is less than FetchResolution older.
	Record(ctx context.Context, tokenID string, fetchedAt time.Time) error
}

FetchStore records when tokens fetch their pull requests.

type NewSubscriptions

type NewSubscriptions struct {
	TokenID      string
	Repositories []string
	Type         SubscriptionType
	CreatedAt    time.Time
}

NewSubscriptions asks the store to subscribe a token to repositories.

type NotSubscribedError added in v0.32.0

type NotSubscribedError struct {
	Repositories []string
}

NotSubscribedError lists named repositories the token does not follow.

func (*NotSubscribedError) Error added in v0.32.0

func (notSubscribed *NotSubscribedError) Error() string

type PartyClaim added in v0.32.0

type PartyClaim struct {
	TokenID      string
	Repositories []string
	DeliveredAt  time.Time
	Day          string
	ActiveSince  time.Time
}

PartyClaim asks the store to deliver party pull requests to a token.

type PartyClaimResult added in v0.32.0

type PartyClaimResult struct {
	Delivered []PullRequest
	Taken     int
	Waiting   int
}

PartyClaimResult is what a party claim delivered and how the turn rule judged the rest.

type PartyDecision added in v0.32.0

type PartyDecision struct {
	Take    []PullRequestKey
	Taken   int
	Waiting int
}

PartyDecision is the outcome of one party claim.

type PartyMember added in v0.32.0

type PartyMember struct {
	TokenID    string
	Repository string
}

PartyMember is one token inside one repository.

type PartyResolution added in v0.32.0

type PartyResolution struct {
	Settings PartySettings
	// Fallback is true when the changed files could not be read and Settings holds the repository's values.
	Fallback bool
}

PartyResolution is the outcome of resolving the party settings of one pull request.

type PartyRound added in v0.32.0

type PartyRound struct {
	TokenID      string
	Now          time.Time
	PullRequests []WaitingPullRequest
	Loads        map[PartyMember]int
}

PartyRound is the input of one party claim.

type PartySettings added in v0.32.0

type PartySettings struct {
	Reviewers int
	Deadline  time.Duration
}

PartySettings are the global review party settings.

type PartySettingsResolver added in v0.32.0

type PartySettingsResolver interface {
	Resolve(ctx context.Context, key PullRequestKey) PartyResolution
}

PartySettingsResolver gives the party settings that apply to a pull request. It never fails. If it cannot read the changed files, it returns the repository's values and sets Fallback.

type PartyState added in v0.32.0

type PartyState struct {
	Reviewers  int
	RecordedAt time.Time
	DeadlineAt time.Time
}

PartyState is the party record of a pull request. A zero DeadlineAt means the timer ran out.

type PullRequest

type PullRequest struct {
	Repository   string
	Number       int
	Title        string
	Description  string
	URL          string
	AuthorID     string
	SourceBranch string
	TargetBranch string
	HeadSHA      string
	CreatedAt    time.Time
	UpdatedAt    time.Time
	Party        PartyState
	// KeepStoredParty tells the store not to overwrite the party columns of a row that has a record time.
	KeepStoredParty bool
}

PullRequest is the feed's view of an open pull request; it carries no author name.

type PullRequestCleaner

type PullRequestCleaner interface {
	// RemoveAll removes every stored pull request and returns how many it removed.
	RemoveAll(ctx context.Context) (int, error)
	// RemoveUnconfigured removes the pull requests of repositories the catalog no longer configures and returns how many it removed.
	RemoveUnconfigured(ctx context.Context) (int, error)
}

PullRequestCleaner removes stored pull requests the feed can no longer keep in sync; subscriptions and tokens stay.

type PullRequestKey added in v0.32.0

type PullRequestKey struct {
	Repository string
	Number     int
}

PullRequestKey names one pull request.

type PullRequestStore

type PullRequestStore interface {
	Upsert(ctx context.Context, pullRequest PullRequest) error
	Delete(ctx context.Context, repository string, number int) error
	// DeleteAll removes every pull request with its deliveries and returns how many pull requests it removed.
	DeleteAll(ctx context.Context) (int, error)
	// DeleteRepositories removes the pull requests of the repositories with their deliveries and returns how many pull requests it removed.
	DeleteRepositories(ctx context.Context, repositories []string) (int, error)
	// Repositories returns every repository that has a stored pull request.
	Repositories(ctx context.Context) ([]string, error)
	// ChangedSince returns pull requests that changed at or after Since, and those delivered to the token at or after Since.
	ChangedSince(ctx context.Context, query SinceQuery) ([]PullRequest, error)
	// Find returns false when the pull request is not stored.
	Find(ctx context.Context, key PullRequestKey) (PullRequest, bool, error)
	// ReceivedSince returns pull requests the token received, solo or party, that changed or reached it at or after Since.
	ReceivedSince(ctx context.Context, query SinceQuery) ([]PullRequest, error)
}

PullRequestStore persists open pull requests for the feed.

type PullRequests

type PullRequests interface {
	// Next returns pull requests not yet delivered to the subscriber and marks them delivered. It delivers party
	// repositories by the turn rule within the cap, and records the fetch.
	Next(ctx context.Context, subscriber Subscriber) ([]PullRequest, error)
	// Since returns pull requests changed after the given time without marking anything delivered.
	// On party repositories it returns only pull requests the token received.
	Since(ctx context.Context, subscriber Subscriber, since time.Time) ([]PullRequest, error)
}

PullRequests serves a token's feed of open pull requests.

type PullRequestsParams

type PullRequestsParams struct {
	Subscriptions SubscriptionStore
	PullRequests  PullRequestStore
	Deliveries    DeliveryStore
	Fetches       FetchStore
	Catalog       RepositoryCatalog
	Clock         Clock
	Logger        *slog.Logger
}

PullRequestsParams are the dependencies of the pull-requests use case.

type Recorder

type Recorder interface {
	Record(ctx context.Context, event kernel.Event) error
}

Recorder keeps the feed's pull-request store in sync with provider events.

type RecorderParams added in v0.32.0

type RecorderParams struct {
	PullRequests  PullRequestStore
	Catalog       RepositoryCatalog
	Clock         Clock
	PartySettings PartySettingsResolver
}

RecorderParams are the dependencies of the recorder.

type RemovedSubscriptions

type RemovedSubscriptions struct {
	// Count is the number of removed subscription rows, across all tokens.
	Count int
	// Repositories are the repositories whose subscriptions were removed, sorted.
	Repositories []string
}

RemovedSubscriptions reports what a subscription cleanup removed.

type RepositoryCatalog

type RepositoryCatalog interface {
	IsConfigured(repository string) bool
	// HasRepositories reports whether any repository, explicit or through an org tier, is configured.
	HasRepositories() bool
	// Configured returns the subset of repositories that is configured.
	Configured(repositories []string) []string
	// List returns the explicitly configured repositories and the organizations configured through an org tier.
	List() ConfiguredRepositories
}

RepositoryCatalog answers which repositories the operator configured.

type SinceQuery added in v0.32.0

type SinceQuery struct {
	TokenID      string
	Repositories []string
	Since        time.Time
}

SinceQuery asks for the pull requests of the repositories that changed, or reached the token, at or after Since.

type Subscriber

type Subscriber struct {
	TokenID string
	User    string
}

Subscriber identifies the agent token making a request.

type Subscription

type Subscription struct {
	ID         int64
	TokenID    string
	Repository string
	Type       SubscriptionType
	CreatedAt  time.Time
}

Subscription is one repository a token follows.

type SubscriptionCleaner

type SubscriptionCleaner interface {
	// RemoveUnconfigured removes every token's subscriptions to repositories the catalog no longer configures and keeps the all-repositories subscription.
	// It removes nothing when the catalog configures no repository at all.
	RemoveUnconfigured(ctx context.Context) (RemovedSubscriptions, error)
}

SubscriptionCleaner removes subscriptions the feed can no longer serve; tokens and stored pull requests stay.

type SubscriptionRequest added in v0.32.0

type SubscriptionRequest struct {
	Repositories []string
	Type         SubscriptionType
}

SubscriptionRequest asks to subscribe to repositories; an empty Type means solo.

type SubscriptionStore

type SubscriptionStore interface {
	List(ctx context.Context, tokenID string) ([]Subscription, error)
	// Add returns how many rows were newly inserted; already-subscribed repositories are skipped.
	Add(ctx context.Context, subscriptions NewSubscriptions) (int, error)
	// Delete returns ErrSubscriptionNotFound when the id is not the token's.
	Delete(ctx context.Context, tokenID string, id int64) (Subscription, error)
	// DeleteRepositories removes the repositories' subscriptions of every token and returns how many it removed.
	DeleteRepositories(ctx context.Context, repositories []string) (int, error)
	// Repositories returns every repository that has a subscription.
	Repositories(ctx context.Context) ([]string, error)
	// SetType returns how many subscriptions changed type; subscriptions that already have the type do not count.
	SetType(ctx context.Context, tokenID string, change TypeChange) (int, error)
}

SubscriptionStore persists token subscriptions.

type SubscriptionType added in v0.32.0

type SubscriptionType string

SubscriptionType says whether a subscription receives every pull request or shares review turns with a party.

const (
	SubscriptionTypeSolo  SubscriptionType = "solo"
	SubscriptionTypeParty SubscriptionType = "party"
)

Subscription types.

func (SubscriptionType) Valid added in v0.32.0

func (subscriptionType SubscriptionType) Valid() bool

Valid reports whether the type is one of the known subscription types.

type Subscriptions

type Subscriptions interface {
	List(ctx context.Context, subscriber Subscriber) ([]Subscription, error)
	// Add subscribes to the repositories with the requested type and returns the full list; it adds nothing when any request is rejected.
	Add(ctx context.Context, subscriber Subscriber, request SubscriptionRequest) ([]Subscription, error)
	// ChangeType sets the type of the subscriber's subscriptions (nil Repositories: every one) and returns the full list.
	// It returns ErrInvalidType for an unknown type, ErrNoRepositories for a non-nil empty list and NotSubscribedError when a named repository is not subscribed; nothing changes then.
	ChangeType(ctx context.Context, subscriber Subscriber, change TypeChange) ([]Subscription, error)
	// Remove returns ErrSubscriptionNotFound when the id is not the subscriber's.
	Remove(ctx context.Context, subscriber Subscriber, id int64) error
	// Available returns the repositories and organizations a subscriber can subscribe to.
	Available() ConfiguredRepositories
}

Subscriptions manages a token's repository subscriptions.

type SubscriptionsParams

type SubscriptionsParams struct {
	Subscriptions SubscriptionStore
	Catalog       RepositoryCatalog
	Clock         Clock
	Logger        *slog.Logger
}

SubscriptionsParams are the dependencies of the subscriptions use case.

type TurnPolicy added in v0.32.0

type TurnPolicy interface {
	// Choose keeps the input order in Take. Taken counts pull requests at their cap; Waiting counts those
	// where another member has the turn. The caller's Loads map is not changed.
	Choose(round PartyRound) PartyDecision
}

TurnPolicy decides which waiting pull requests the fetcher may take in a party round.

type TypeChange added in v0.32.0

type TypeChange struct {
	Repositories []string
	Type         SubscriptionType
}

TypeChange sets the type of a token's subscriptions; nil Repositories means every subscription.

type UnknownRepositoriesError

type UnknownRepositoriesError struct {
	Repositories []string
}

UnknownRepositoriesError lists requested repositories that are not configured.

func (*UnknownRepositoriesError) Error

func (unknown *UnknownRepositoriesError) Error() string

type WaitingPullRequest added in v0.32.0

type WaitingPullRequest struct {
	Key             PullRequestKey
	Party           PartyState
	PartyDeliveries int
	// Candidates are the other members of the repository, not away, without a delivery of this pull request.
	Candidates []string
}

WaitingPullRequest is a pull request a party fetcher could take.

Jump to

Keyboard shortcuts

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