Documentation
¶
Overview ¶
Package provider is the contract between the dispatcher and a provider adapter (GitHub, and later Slack): ingress, observation, projection, effects and git credentials for agents (design/workstreams/foundation/LLD/contracts.md §Provider interface).
The package holds only interfaces and plain types. Adapters live in sub-packages (provider/github); provider/fake is the in-memory implementation for tests.
Index ¶
- Constants
- Variables
- func EventID(deliveryID string, n int) string
- func NotInstalledMessage(identity, app, repo string) string
- func ReadOnlyPermissions() map[string]string
- type Adapter
- type Approval
- type Checks
- type Conn
- type Credential
- type DeployObservation
- type EffectRequest
- type EffectResult
- type GitCredentialRequest
- type GroupLookup
- type HealthState
- type HealthStatus
- type IngressSink
- type IngressSinkFunc
- type InstallationChecker
- type IssueObservation
- type NotInstalledError
- type ObjectState
- type Observation
- type PRObservation
- type Projection
- type RawEvent
- type Registry
- type RetryableError
- type SecretResolver
- type SecretResolverFunc
Constants ¶
const ( KindIssue = "issue" KindPR = "pr" )
Object kinds, as in ObjectRef.Kind and Link.Kind.
const Redacted = "[REDACTED]"
Redacted replaces a token wherever a Credential is printed, logged or JSON-encoded.
Variables ¶
var ( // ErrDuplicateDelivery is returned by an IngressSink for a delivery it already stored. ErrDuplicateDelivery = errors.New("provider: duplicate delivery") // ErrNotFound is an object, team or group that doesn't exist on the provider. ErrNotFound = errors.New("provider: not found") // ErrForbidden is a request the provider refuses for lack of access (the integration may // not read or do this). It lasts until the installation or its permissions change; a // rate limit is ErrRetryable instead. ErrForbidden = errors.New("provider: forbidden") // ErrInvalid is a request the adapter rejects: a missing idempotency key, an unscoped // credential request, a malformed delivery, … ErrInvalid = errors.New("provider: invalid request") // ErrUnsupported is an op or call this provider type can't do (a git-side effect op, a // PR op on Slack, …). ErrUnsupported = errors.New("provider: unsupported") // ErrRetryable is a transient failure (rate limit, 5xx): the Effector API answers 429 with // Retry-After. // Adapters return it as a *RetryableError. ErrRetryable = errors.New("provider: retryable") // ErrUnknownType is a Provider type no registered adapter connects. ErrUnknownType = errors.New("provider: unknown provider type") // ErrAlreadyRegistered is a second adapter for the same type. ErrAlreadyRegistered = errors.New("provider: adapter type already registered") )
Errors returned by adapters and sinks; match them with errors.Is.
Functions ¶
func EventID ¶
EventID is the ID of the n-th Event normalised from delivery deliveryID: "<deliveryID>/<n>". Adapters number a delivery's Events in a stable order (sorted by object ref), so the store's dedupe keeps each of them once.
func NotInstalledMessage ¶
NotInstalledMessage is the human sentence for an App that isn't installed on a repo: "the reviewer App (ccf-factory-reviewer) isn't installed on owner/name".
func ReadOnlyPermissions ¶
ReadOnlyPermissions are a read-only token's permissions: contents: read.
Types ¶
type Adapter ¶
type Adapter interface {
// Type is the Provider spec.type this adapter connects ("github").
Type() string
// Connect returns a connection for one Provider instance. Adapter-wide dependencies (HTTP
// client, clock, logger, the catalog's Groups) are given to the adapter's constructor, not
// here. The provider controller connects again when the Provider object changes.
Connect(ctx context.Context, p v1alpha1.Provider, secrets SecretResolver) (Conn, error)
}
Adapter connects Provider objects of one type.
type Approval ¶
Approval is an approving review: by which factory identity (or login), at which commit.
type Conn ¶
type Conn interface {
// Handler is mounted at the Provider's webhook path. It verifies the request, then calls
// sink.Accept, and acknowledges only once Accept has returned: 202 when it succeeded, 200
// when it returned ErrDuplicateDelivery, 503 for any other error (so the provider retries).
Handler(sink IngressSink) http.Handler
// Recover re-ingests, through sink.Accept, the deliveries the provider made since since
// (startup, after the restart gap). Deliveries the sink already has come back as
// ErrDuplicateDelivery and are skipped.
Recover(ctx context.Context, since time.Time, sink IngressSink) error
// Normalise maps one delivery to neutral Events, with IDs EventID(ev.ID, n), Source and
// Data.Provider set to the Provider's name and the actor's tier resolved. A delivery that
// maps to no event type returns no Events and no error.
Normalise(ctx context.Context, ev RawEvent) ([]v1alpha1.Event, error)
// Observe reads the current state of one object; ErrNotFound when it doesn't exist.
Observe(ctx context.Context, ref v1alpha1.ObjectRef) (Observation, error)
// List returns the objects in scope that the work-item rebuild must see: the open ones,
// and those carrying a projection marker.
List(ctx context.Context, scope v1alpha1.Scope) ([]v1alpha1.ObjectRef, error)
// ResolveGroup returns the provider-native user IDs (GitHub logins, not Actor IDs) in one
// Group member source, sorted and without duplicates.
ResolveGroup(ctx context.Context, g v1alpha1.GroupSource) ([]string, error)
// Project writes a work item's projection onto one object. It is idempotent: projecting
// the same Projection again changes nothing.
Project(ctx context.Context, ref v1alpha1.ObjectRef, p Projection) error
// Apply executes one API-side effect. Replaying an IdempotencyKey that was already
// applied creates nothing and returns the first result, with Replayed set.
Apply(ctx context.Context, e EffectRequest) (EffectResult, error)
// MintGitCredential mints a git token scoped to the requested repos and permissions. It
// refuses a request that fails GitCredentialRequest.Validate with ErrInvalid.
MintGitCredential(ctx context.Context, req GitCredentialRequest) (Credential, error)
// Health is the connection's last known health. It doesn't block.
Health() HealthStatus
}
Conn is a connection to one provider instance. It is safe for concurrent use.
type Credential ¶
type Credential struct {
Provider string
// Host is the git host ("github.com"); Username goes with the token ("x-access-token").
Host string
Username string
Token string
ExpiresAt time.Time
Repo string
ReadRepos []string
Permissions map[string]string
}
Credential is a minted git token, the API's GitCredential: the task token (the lease's gitCredential) or a read-only token for one private read repo (one of its readCredentials). It is sent to the agent in the lease and heartbeat responses and never stored.
Printing (fmt, any verb), logging (slog) and JSON-encoding it all redact Token, so it can't leak through a log line or a store record. The lease response copies the fields into the generated API type explicitly.
func (Credential) Format ¶
func (c Credential) Format(f fmt.State, _ rune)
Format prints String() for every verb, %#v and %d included, so no verb reaches the token.
func (Credential) LogValue ¶
func (c Credential) LogValue() slog.Value
LogValue logs the credential's fields with the token redacted.
func (Credential) MarshalJSON ¶
func (c Credential) MarshalJSON() ([]byte, error)
MarshalJSON encodes the credential with the token redacted.
func (Credential) String ¶
func (c Credential) String() string
String describes the credential with the token redacted.
type DeployObservation ¶
type DeployObservation struct {
State string `json:"state,omitzero"`
SHA string `json:"sha,omitzero"`
URL string `json:"url,omitzero"`
ContainsMerge bool `json:"containsMerge,omitzero"`
}
DeployObservation is the latest deployment of the default branch (the rules' item.deploy).
type EffectRequest ¶
type EffectRequest struct {
Op v1alpha1.EffectOp `json:"op"`
// Target is the object acted on; for create-issue and pr.open, Ref is the repo
// ("owner/name").
Target v1alpha1.ObjectRef `json:"target"`
// Args are the op-specific fields (labels, body, title, base, …).
Args map[string]any `json:"args,omitzero"`
// Identity is the factory identity that acts ("author", "reviewer").
Identity string `json:"identity,omitzero"`
// IdempotencyKey is required: the Effector's hash(task, key), or the rule controller's
// evt/<event>/<rule>/<i>.
IdempotencyKey string `json:"idempotencyKey"`
}
EffectRequest is one API-side effect, as the Effector API and the rule controller send it (an Effect record's spec, without the task).
type EffectResult ¶
type EffectResult struct {
URL string `json:"url,omitzero"`
// Object is the object created (create-issue, pr.open) or acted on.
Object *v1alpha1.ObjectRef `json:"object,omitzero"`
// Outcome qualifies an op that did something other than asked, e.g. pr.merge's
// "labelled-for-merge"; empty when the op was applied as asked.
Outcome string `json:"outcome,omitzero"`
// Replayed is true when the idempotency key had already been applied and nothing new was
// created.
Replayed bool `json:"replayed,omitzero"`
}
EffectResult is the outcome of an applied effect.
type GitCredentialRequest ¶
type GitCredentialRequest struct {
Identity string
// Repo is the repo ("owner/name") the token is for; required, so a token is never unscoped.
Repo string
// ReadRepos are further repos for a read-only token (every permission "read"). A token that
// can write covers its Repo only, so write access is on at most one repo by construction.
ReadRepos []string
Permissions map[string]string
TTL time.Duration
}
GitCredentialRequest asks for one of an agent's git tokens, with the TTL the scheduler computed at lease time. The scheduler sends two shapes:
- the task token: the Task's spec.credentials.git repo with the TaskSpec permissions, and no ReadRepos;
- a read-only token per private read repo: ReadOnlyRequest, that repo with ReadOnlyPermissions (contents: read).
Validate says which requests an adapter must refuse.
func ReadOnlyRequest ¶
func ReadOnlyRequest(identity, repo string, ttl time.Duration) GitCredentialRequest
ReadOnlyRequest asks for a read-only token (ReadOnlyPermissions) on one repo.
func (GitCredentialRequest) ReadOnly ¶
func (r GitCredentialRequest) ReadOnly() bool
ReadOnly reports whether the request asks for read access only: it names permissions and every one is "read".
func (GitCredentialRequest) Validate ¶
func (r GitCredentialRequest) Validate() error
Validate returns an ErrInvalid error for a request no adapter may mint: no identity, no repo (an unscoped token), a TTL that isn't positive, or ReadRepos on a token that can write.
type GroupLookup ¶
GroupLookup returns the catalog Group named name, for trust rules that name a Group. An adapter takes one in its constructor; `factory serve` passes one that reads the live catalog, so a Conn sees Group changes without reconnecting.
func StaticGroups ¶
func StaticGroups(groups map[string]v1alpha1.GroupSpec) GroupLookup
StaticGroups is a GroupLookup over a fixed map, for tests.
type HealthState ¶
type HealthState string
HealthState is a connection's health, as GET /providers reports it.
const ( HealthOK HealthState = "ok" HealthDegraded HealthState = "degraded" HealthDown HealthState = "down" HealthUnknown HealthState = "unknown" )
Health states.
type HealthStatus ¶
type HealthStatus struct {
Status HealthState `json:"status"`
Message string `json:"message,omitzero"`
CheckedAt time.Time `json:"checkedAt,omitzero"`
}
HealthStatus is Conn.Health(): the API's ProviderHealth.
type IngressSink ¶
IngressSink accepts raw deliveries. The provider controller's sink stores a Delivery record; it returns ErrDuplicateDelivery (wrapped or not) when the record already exists, and any other error makes the handler answer 503.
type IngressSinkFunc ¶
IngressSinkFunc adapts a function to an IngressSink.
type InstallationChecker ¶
type InstallationChecker interface {
// MissingInstallations returns which of repos ("owner/name") the identity's App isn't
// installed on, and the App's slug ("" when it can't be learnt).
MissingInstallations(ctx context.Context, identity string, repos []string) (app string, missing []string, err error)
}
InstallationChecker is a Conn that can say which repos an identity's App is installed on (the GitHub Conn). `factory serve` checks the repos the catalog can touch with it.
type IssueObservation ¶
type IssueObservation struct {
SubIssues []v1alpha1.ObjectRef `json:"subIssues,omitzero"`
LinkedPRs []v1alpha1.ObjectRef `json:"linkedPRs,omitzero"`
Comments int `json:"comments,omitzero"`
}
IssueObservation is what Observe reads of an issue.
type NotInstalledError ¶
type NotInstalledError struct {
// Identity is the factory identity (author, reviewer); App is its App's slug, when known.
Identity, App string
// Repo is "owner/name".
Repo string
Err error
}
NotInstalledError is a credential an identity's App can't mint because the App isn't installed on the repo. errors.Is(err, ErrNotFound) is true.
func (*NotInstalledError) Error ¶
func (e *NotInstalledError) Error() string
func (*NotInstalledError) Is ¶
func (e *NotInstalledError) Is(target error) bool
Is makes errors.Is(err, ErrNotFound) true.
func (*NotInstalledError) Unwrap ¶
func (e *NotInstalledError) Unwrap() error
Unwrap returns the underlying error.
type ObjectState ¶
type ObjectState string
ObjectState is the lifecycle state of an observed object.
const ( StateOpen ObjectState = "open" StateClosed ObjectState = "closed" // StateMerged is a merged PR (a PR closed without merging is StateClosed). StateMerged ObjectState = "merged" )
Object states.
type Observation ¶
type Observation struct {
Ref v1alpha1.ObjectRef `json:"ref"`
State ObjectState `json:"state"`
Labels []string `json:"labels,omitzero"`
// Author is who opened the object; IsFactory and Identity say whether a factory App did.
// Tier is not resolved.
Author *v1alpha1.Actor `json:"author,omitzero"`
UpdatedAt time.Time `json:"updatedAt,omitzero"`
Issue *IssueObservation `json:"issue,omitzero"`
PR *PRObservation `json:"pr,omitzero"`
Deploy *DeployObservation `json:"deploy,omitzero"`
// Projections are the projections found on the object (the GitHub markers), one per work
// item, sorted by WorkItemID.
Projections []Projection `json:"projections,omitzero"`
}
Observation is the current state of one provider object, as Observe reads it. Exactly one of Issue and PR is set, following Ref.Kind. Untrusted text (titles, bodies, comments) is never part of it.
type PRObservation ¶
type PRObservation struct {
Draft bool `json:"draft"`
// Head is the head commit SHA; Base the base branch.
Head string `json:"head,omitzero"`
Base string `json:"base,omitzero"`
Checks Checks `json:"checks"`
ApprovedBy []Approval `json:"approvedBy,omitzero"`
UnresolvedThreads int `json:"unresolvedThreads,omitzero"`
MergedAt time.Time `json:"mergedAt,omitzero"`
MergeCommit string `json:"mergeCommit,omitzero"`
}
PRObservation is what Observe reads of a PR (the rules' item.pr).
type Projection ¶
type Projection struct {
WorkItemID string `json:"workItemID"`
State map[string]any `json:"state,omitzero"`
Counters map[string]int `json:"counters,omitzero"`
Links []v1alpha1.Link `json:"links,omitzero"`
// Labels are the factory-owned labels to ensure; other labels are left untouched.
Labels []string `json:"labels,omitzero"`
}
Projection is what a work item writes onto each linked object: the GitHub marker comment and the factory-owned labels. Observe reads the markers back (Observation.Projections), which is how the work-item rebuild recreates work items after a restart.
type RawEvent ¶
type RawEvent struct {
// ID identifies the delivery across every provider: the adapter prefixes the provider's
// own delivery ID ("gh-<X-GitHub-Delivery>"). Events normalised from it are EventID(ID, n).
ID string `json:"id"`
// Provider is the Provider instance's name ("github-public").
Provider string `json:"provider"`
// Type is the provider-native event name ("issues", X-GitHub-Event), if the provider has one.
Type string `json:"type,omitzero"`
// Headers are the request headers as received.
Headers http.Header `json:"headers,omitzero"`
// Body is the request body as received (untrusted).
Body []byte `json:"body"`
ReceivedAt time.Time `json:"receivedAt"`
}
RawEvent is one provider delivery as received, before normalisation. The provider controller stores it as a Delivery record named ID.
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry maps Provider types to adapters. `factory serve` registers the GitHub adapter; tests register provider/fake under the type they stand in for. The zero value is ready to use and it is safe for concurrent use.
func NewRegistry ¶
NewRegistry returns a registry holding adapters.
func (*Registry) Connect ¶
func (r *Registry) Connect(ctx context.Context, p v1alpha1.Provider, secrets SecretResolver) (Conn, error)
Connect connects p with the adapter for p.Spec.Type; ErrUnknownType when there is none.
type RetryableError ¶
type RetryableError struct {
// RetryAfter is the provider's hint (Retry-After), or zero.
RetryAfter time.Duration
Err error
}
RetryableError is a transient failure; errors.Is(err, ErrRetryable) is true.
func (*RetryableError) Error ¶
func (e *RetryableError) Error() string
func (*RetryableError) Is ¶
func (e *RetryableError) Is(target error) bool
Is makes errors.Is(err, ErrRetryable) true.
func (*RetryableError) Unwrap ¶
func (e *RetryableError) Unwrap() error
Unwrap returns the underlying error.
type SecretResolver ¶
type SecretResolver interface {
Resolve(ctx context.Context, ref v1alpha1.SecretRef) ([]byte, error)
}
SecretResolver resolves a catalog secretRef (`factory serve` reads FACTORY_SECRET_<NAME>_<KEY>). Values are never logged.
type SecretResolverFunc ¶
SecretResolverFunc adapts a function to a SecretResolver.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package fake is an in-memory provider for tests: it keeps objects in memory, records every Project and Apply for assertions, emits scripted deliveries into an IngressSink and normalises them into Events, resolves Groups from configured membership, mints fake git tokens and reports a settable health.
|
Package fake is an in-memory provider for tests: it keeps objects in memory, records every Project and Apply for assertions, emits scripted deliveries into an IngressSink and normalises them into Events, resolves Groups from configured membership, mints fake git tokens and reports a settable health. |
|
Package github is the provider adapter for GitHub and GHE (design/workstreams/provider-github/LLD/github-provider.md): App auth and scoped git credentials (GH-S1-T01), webhook ingress and normalisation (GH-S1-T02), observe, list and projection (GH-S1-T03) and effects (GH-S1-T04).
|
Package github is the provider adapter for GitHub and GHE (design/workstreams/provider-github/LLD/github-provider.md): App auth and scoped git credentials (GH-S1-T01), webhook ingress and normalisation (GH-S1-T02), observe, list and projection (GH-S1-T03) and effects (GH-S1-T04). |
|
githubtest
Package githubtest is an httptest GitHub for the GitHub adapter's tests.
|
Package githubtest is an httptest GitHub for the GitHub adapter's tests. |
|
Package tokens mints GitHub App installation tokens for the factory's App identities (design/workstreams/provider-github/LLD/github-provider.md §Auth and tokens).
|
Package tokens mints GitHub App installation tokens for the factory's App identities (design/workstreams/provider-github/LLD/github-provider.md §Auth and tokens). |