provider

package
v0.2.1 Latest Latest
Warning

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

Go to latest
Published: Oct 28, 2026 License: AGPL-3.0 Imports: 12 Imported by: 0

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 interfaces and plain types, and WriteProblem, which the adapters' webhook handlers answer a refusal with. Adapters live in sub-packages (provider/github); provider/fake is the in-memory implementation for tests.

Index

Constants

View Source
const (
	KindIssue = "issue"
	KindPR    = "pr"
)

Object kinds, as in ObjectRef.Kind and Link.Kind.

View Source
const ProblemContentType = "application/problem+json"

ProblemContentType is the media type of the API's error bodies (RFC 9457), which a Conn's webhook Handler answers its refusals with too.

View Source
const Redacted = "[REDACTED]"

Redacted replaces a token wherever a Credential is printed, logged or JSON-encoded.

Variables

View Source
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

func EventID(deliveryID string, n int) string

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

func NotInstalledMessage(identity, app, repo string) string

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

func ReadOnlyPermissions() map[string]string

ReadOnlyPermissions are a read-only token's permissions: contents: read.

func WriteProblem added in v0.2.0

func WriteProblem(w http.ResponseWriter, status int, code, detail string)

WriteProblem answers a refused webhook delivery with an RFC 9457 problem, in the API server's error shape (api/openapi.yaml's Problem): the status, its text as the title, code (one of internal/server's codes), detail (left out of a 5xx, as the server leaves it out), and the request id the server set on the response (X-Request-Id) as the instance.

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

type Approval struct {
	Identity string `json:"identity"`
	Commit   string `json:"commit"`
}

Approval is an approving review: by which factory identity (or login), at which commit.

type Checks

type Checks struct {
	State   string `json:"state,omitzero"`
	Settled bool   `json:"settled,omitzero"`
}

Checks is the rollup of a PR head's checks.

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

type GroupLookup func(name string) (v1alpha1.GroupSpec, bool)

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

type IngressSink interface {
	Accept(ctx context.Context, ev RawEvent) error
}

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

type IngressSinkFunc func(ctx context.Context, ev RawEvent) error

IngressSinkFunc adapts a function to an IngressSink.

func (IngressSinkFunc) Accept

func (f IngressSinkFunc) Accept(ctx context.Context, ev RawEvent) error

Accept calls f.

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"`
}

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, for people to read. Nothing reads them back into the store.

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

func NewRegistry(adapters ...Adapter) (*Registry, error)

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.

func (*Registry) Lookup

func (r *Registry) Lookup(typ string) (Adapter, bool)

Lookup returns the adapter for typ.

func (*Registry) Register

func (r *Registry) Register(a Adapter) error

Register adds a, keyed by a.Type(). A second adapter for a type is ErrAlreadyRegistered.

func (*Registry) Types

func (r *Registry) Types() []string

Types returns the registered types, sorted.

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

type SecretResolverFunc func(ctx context.Context, ref v1alpha1.SecretRef) ([]byte, error)

SecretResolverFunc adapts a function to a SecretResolver.

func (SecretResolverFunc) Resolve

func (f SecretResolverFunc) Resolve(ctx context.Context, ref v1alpha1.SecretRef) ([]byte, error)

Resolve calls f.

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

Jump to

Keyboard shortcuts

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