Documentation
¶
Overview ¶
Package domain holds the feed contracts: pull-request and subscription models, ports and use-case interfaces.
Index ¶
- Constants
- Variables
- func LoadDay(moment time.Time) string
- type Claim
- type CleanupReason
- type Clock
- type ConfiguredRepositories
- type DeliveryStore
- type ErrorCode
- type FetchStore
- type NewSubscriptions
- type NotSubscribedError
- type PartyClaim
- type PartyClaimResult
- type PartyDecision
- type PartyMember
- type PartyResolution
- type PartyRound
- type PartySettings
- type PartySettingsResolver
- type PartyState
- type PullRequest
- type PullRequestCleaner
- type PullRequestKey
- type PullRequestStore
- type PullRequests
- type PullRequestsParams
- type Recorder
- type RecorderParams
- type RemovedSubscriptions
- type RepositoryCatalog
- type SinceQuery
- type Subscriber
- type Subscription
- type SubscriptionCleaner
- type SubscriptionRequest
- type SubscriptionStore
- type SubscriptionType
- type Subscriptions
- type SubscriptionsParams
- type TurnPolicy
- type TypeChange
- type UnknownRepositoriesError
- type WaitingPullRequest
Constants ¶
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.
const AwayAfter = 24 * time.Hour
AwayAfter is how long a party member stays a candidate after its last fetch.
const DayLayout = "2006-01-02"
DayLayout formats the day of the party loads.
const FetchResolution = time.Minute
FetchResolution is how old a stored fetch time must be before a fetch writes a new one.
const PartyFilesReadTimeout = 2 * time.Second
PartyFilesReadTimeout caps how long the party settings wait for the changed files of a pull request.
const RecordTimeout = 3 * time.Second
RecordTimeout caps how long a webhook waits for the feed record.
Variables ¶
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 ¶
Types ¶
type Claim ¶
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 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 ( 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
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
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
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
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 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
SinceQuery asks for the pull requests of the repositories that changed, or reached the token, at or after Since.
type Subscriber ¶
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.