domain

package
v0.31.0 Latest Latest
Warning

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

Go to latest
Published: Oct 28, 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"
	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 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")
)

Feed sentinel errors.

Functions

This section is empty.

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

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"
	ErrorCodeInvalidSince         ErrorCode = "invalid_since"
	ErrorCodeNotFound             ErrorCode = "not_found"
	ErrorCodeInternal             ErrorCode = "internal_error"
	ErrorCodeMethodNotAllowed     ErrorCode = "method_not_allowed"
)

HTTP error codes.

type NewSubscriptions

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

NewSubscriptions asks the store to subscribe a token to repositories.

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
}

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 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(ctx context.Context, repositories []string, since time.Time) ([]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.
	Next(ctx context.Context, subscriber Subscriber) ([]PullRequest, error)
	// Since returns pull requests changed after the given time without marking anything delivered.
	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
	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 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 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
	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 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)
}

SubscriptionStore persists token subscriptions.

type Subscriptions

type Subscriptions interface {
	List(ctx context.Context, subscriber Subscriber) ([]Subscription, error)
	// Add subscribes to the repositories and returns the full list; it adds nothing when any request is rejected.
	Add(ctx context.Context, subscriber Subscriber, repositories []string) ([]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 UnknownRepositoriesError

type UnknownRepositoriesError struct {
	Repositories []string
}

UnknownRepositoriesError lists requested repositories that are not configured.

func (*UnknownRepositoriesError) Error

func (unknown *UnknownRepositoriesError) Error() string

Jump to

Keyboard shortcuts

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