github

type AppFactory struct {
	// contains filtered or unexported fields
}

type AppInfo struct {
	ID    int64
	Slug  string
	Name  string
	Owner string
	// Permissions is what the App was granted, so setup can tell the operator
	// exactly which permission is missing rather than "403".
	Permissions map[string]string
	Events      []string
	// RepositorySelection is GitHub's own word for how much of the target this
	// installation covers: "all" or "selected". It is the difference between a
	// pool that will see every repository somebody pushes to and one that
	// silently sees none of them -- the second commonest setup mistake after a
	// missing permission, and the one nothing in Zoomies could previously say
	// anything about.
	RepositorySelection string
}

type Client interface {
	// Target returns the org or repo this client acts on.
	Target() (name string, kind store.TargetType)
	// Probe verifies the credentials and permissions, returning an error whose
	// message names the missing permission where GitHub tells us.
	Probe(ctx context.Context) (*AppInfo, error)
	// CreateJITConfig mints an ephemeral runner registration.
	CreateJITConfig(ctx context.Context, req JITRequest) (*JITConfig, error)
	// CreateRegistrationToken mints a one-hour token for config.sh.
	CreateRegistrationToken(ctx context.Context) (*RegistrationToken, error)
	// CreateRemoveToken mints a token for deregistering a runner from the host.
	CreateRemoveToken(ctx context.Context) (*RegistrationToken, error)
	// ListRunners returns every self-hosted runner registered on the target.
	ListRunners(ctx context.Context) ([]Runner, error)
	// DeleteRunner removes a registration. Deleting one that is already gone
	// returns nil, because the desired end state has been reached.
	DeleteRunner(ctx context.Context, id int64) error
	// ListRunnerGroups returns the target's runner groups.
	ListRunnerGroups(ctx context.Context) ([]RunnerGroup, error)
	// CreateRunnerGroup creates an organisation runner group. Repository
	// targets reject it because GitHub only supports groups at organisation
	// scope.
	CreateRunnerGroup(ctx context.Context, req RunnerGroupCreate) (*RunnerGroup, error)
	// ListQueuedJobs is the webhook fallback: it walks recent workflow runs and
	// returns the jobs still waiting for a runner.
	ListQueuedJobs(ctx context.Context) ([]QueuedJob, error)
	// GetWorkflowJob reconciles a known job even after its run has completed.
	GetWorkflowJob(ctx context.Context, repo string, id int64) (*WorkflowJobEvent, error)
	// CancelWorkflowRun asks GitHub to cancel the entire run containing a job.
	// Force bypasses conditions that may otherwise keep a run cancelling.
	CancelWorkflowRun(ctx context.Context, repo string, runID int64, force bool) error
	// RateLimit reports remaining quota.
	RateLimit(ctx context.Context) (*RateLimit, error)
	// WebURL returns the browser URL for the target.
	WebURL() string

	// ListRepositories returns the repositories this installation can see.
	ListRepositories(ctx context.Context, limit int) ([]Repository, error)
	// ListWorkflows returns the workflow files at the top of a repository's
	// .github/workflows, with their contents.
	ListWorkflows(ctx context.Context, repo string) ([]WorkflowFile, error)
	// ReadReadme returns the README GitHub renders on the repository's front
	// page, or ErrNoReadme when there is none. It is where the badge goes.
	ReadReadme(ctx context.Context, repo string) (*Readme, error)
	// OpenPullRequest commits a set of files to a new branch and opens a pull
	// request for it.
	OpenPullRequest(ctx context.Context, req PullRequestRequest) (*PullRequest, error)
}

type Factory interface {
	For(ctx context.Context, inst *store.Installation, privateKeyPEM []byte) (Client, error)
}

type FakeGitHub struct {
	// contains filtered or unexported fields
}

type FileChange struct {
	Path    string
	Content string
	// SHA is the blob SHA the change was computed against.
	SHA string
}

type JITConfig struct {
	// Encoded is the base64 configuration.
	Encoded string
	// RunnerID is the ID GitHub assigned, so Zoomies can delete the
	// registration later if the runner never comes up.
	RunnerID int64
	// Name echoes the requested name.
	Name string
}

type JITRequest struct {
	// Name must be unique within the target. GitHub rejects reuse.
	Name string
	// Labels are the custom labels this runner advertises, without the
	// implicit self-hosted/os/arch set.
	Labels []string
	// RunnerGroupID is 1 (Default) unless the pool names a group.
	RunnerGroupID int64
	// WorkFolder defaults to "_work".
	WorkFolder string
}

type ManifestCredentials struct {
	AppID int64
	Slug  string
	Name  string
	// PEM is the App's private key. It is shown once and must be sealed
	// immediately.
	PEM string
	// WebhookSecret is the secret GitHub generated for the App's webhook. It
	// is the only copy: the manifest cannot ask for a particular one, and
	// GitHub does not show it again.
	WebhookSecret string
	ClientID      string
	ClientSecret  string
	HTMLURL       string
}

type ManifestOptions struct {
	// Name is the App's display name, unique across all of GitHub.
	Name string
	// URL is the App's homepage, shown on its GitHub page.
	URL string
	// WebhookURL is where GitHub delivers workflow_job events.
	WebhookURL string
	// Organization is the org the App is created under. Empty creates it on
	// the operator's own account, which is the right choice for repo targets.
	Organization string
	// SetupURL is permanent App configuration: GitHub sends the operator here
	// after every future install or reconfiguration of the App -- adding a
	// repository to the installation, most commonly, years later. It has to be
	// an address that still answers then.
	SetupURL string
	// RedirectURL is where GitHub returns during *this* handshake, carrying
	// ?code=. Empty means "the same as SetupURL", which is right when the
	// handshake is driven from the controller's own web UI.
	//
	// They are separate because the installer is not: it catches the callback
	// on a temporary loopback listener that is gone minutes later, and writing
	// that ephemeral port into setup_url left every App `zoomies init` ever
	// created sending its operator to a refused connection.
	RedirectURL string
	// Public allows the App to be installed on accounts other than the one
	// that created it. Zoomies defaults it off: a fleet controller's App has
	// no business being installable by strangers.
	Public bool
	// AllowWorkflowCancellation raises Actions from read to write so Zoomies
	// can cancel workflow runs. It is opt-in because write is not needed to run
	// the fleet.
	AllowWorkflowCancellation bool
}

type PullRequest struct {
	Number  int    `json:"number"`
	HTMLURL string `json:"html_url"`
	Branch  string `json:"branch"`
}

type PullRequestRequest struct {
	// Repo is "owner/name".
	Repo string
	// Base is the branch to open against. Empty means the default branch.
	Base string
	// Head is the branch to create. It must not already exist.
	Head          string
	Title         string
	Body          string
	CommitMessage string
	Files         []FileChange
}

type QueuedJob struct {
	ID           int64
	RunID        int64
	Repo         string
	WorkflowName string
	JobName      string
	Labels       []string
	QueuedAt     time.Time
	HTMLURL      string
	// RunnerName is set once GitHub has assigned the job.
	RunnerName  string
	Status      string
	Conclusion  string
	StartedAt   *time.Time
	CompletedAt *time.Time
}

type RateLimit struct {
	Limit     int
	Remaining int
	ResetAt   time.Time
}

type RateLimitedError struct {
	// ResetAt is when the quota refills, zero when GitHub did not say.
	ResetAt time.Time
	// RetryAfter is the secondary limit's answer, which is a duration rather
	// than an instant. Zero when unset.
	RetryAfter time.Duration
	Detail     string
}

type Readme struct {
	// Path is repository-relative -- "README.md", but also "readme.markdown"
	// or "README.rst", which is why the caller checks it before writing
	// Markdown into it.
	Path string
	// SHA is the blob SHA, for the same reason a workflow file carries one.
	SHA string
	// Content is the decoded file.
	Content string
}

type RegistrationToken struct {
	Token     string
	ExpiresAt time.Time
}

type Repository struct {
	FullName      string `json:"full_name"`
	DefaultBranch string `json:"default_branch"`
	Private       bool   `json:"private"`
	Archived      bool   `json:"archived"`
	HTMLURL       string `json:"html_url"`
}

type Runner struct {
	ID     int64
	Name   string
	OS     string
	Status string // online | offline
	Busy   bool
	Labels []string
	// Ephemeral is reported by GitHub for JIT-configured runners.
	Ephemeral bool
}

type RunnerGroup struct {
	ID         int64
	Name       string
	Default    bool
	Visibility string
	// PublicRepositoryAccessKnown distinguishes an older GitHub Enterprise
	// response that omitted the setting from a group that explicitly disables
	// it. Treating both as false would raise a warning nobody could act on.
	PublicRepositoryAccessKnown bool
	AllowsPublicRepositories    bool
	RestrictedToWorkflows       bool
}

type RunnerGroupCreate struct {
	Name                     string
	Visibility               string
	AllowsPublicRepositories bool
}

type WorkflowFile struct {
	// Path is repository-relative.
	Path string
	// SHA is the blob SHA. GitHub requires it to update the file, and it is
	// what makes an update fail rather than clobber somebody's change.
	SHA string
	// Content is the decoded file.
	Content string
}

type WorkflowJobEvent struct {
	// Action is "queued", "in_progress", "completed" or "waiting".
	Action string
	// InstallationID routes the delivery to one of Zoomies' installations.
	InstallationID int64

	JobID        int64
	RunID        int64
	Repo         string // "acme/widgets"
	WorkflowName string
	JobName      string
	// Labels are the workflow's runs-on values, including implicit ones.
	Labels     []string
	RunnerID   int64
	RunnerName string
	Status     string
	Conclusion string

	// QueuedAt is the job's created_at, i.e. when GitHub started looking for a
	// runner.
	QueuedAt    time.Time
	StartedAt   time.Time
	CompletedAt time.Time
	HTMLURL     string

	// HeadBranch, HeadSHA and RunAttempt say what the job ran for.
	HeadBranch string
	HeadSHA    string
	RunAttempt int
	// Steps are the job's steps as this delivery reports them. On a completed
	// delivery every step carries its conclusion, which is what lets a failed
	// job say where it failed.
	Steps []store.JobStep
}