forge

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

type AppNotInstalledError struct {
	App        string // the app id
	Slug       string // owner/repo
	InstallURL string // where the app is installed
}

type CLI interface {
	// Token is this source's credential. A source with nothing to give
	// may answer either way — an error, or the empty string — and a
	// caller standing for SEVERAL sources owes the difference: it must
	// return an error when none of them answered, never a silent empty
	// string, because the server decides "have we got a credential at
	// all" on that error alone.
	Token(ctx context.Context) (string, error)
	// Login is who the forge says this source's token belongs to, which
	// need not be whoever ran a tool on the machine: a stored bot token
	// belongs to the bot. It must describe the token Token would hand
	// back right now, or the push is made with one account's credential
	// and the work signed with another's name.
	Login(ctx context.Context) (string, error)
}

type Credential interface {
	CLI
	TokenAndLogin(ctx context.Context) (token, login string, err error)
}

type Forge interface {
	// Kind names the forge; Label is its display name for UI copy.
	Kind() Kind
	Label() string
	// Host is the instance this forge is: github.com, or the host of a
	// GitLab's base URL. It is what a credential belongs to, so a caller
	// keeping one token per forge keys it by this rather than parsing a
	// repository URL of its own.
	Host() string

	// AuthorizeURL and TokenURL are the OAuth endpoints the sign-in flow
	// uses; DefaultScopes the scope string a board needs when the operator
	// sets none.
	AuthorizeURL() string
	TokenURL() string
	DefaultScopes() string
	// ExchangeForm and RefreshForm are the token endpoint's request bodies
	// in the forge's dialect (GitLab names the grant type and wants the
	// redirect URI on a refresh too).
	ExchangeForm(clientID, secret, code, redirectURI string) url.Values
	RefreshForm(clientID, secret, refresh, redirectURI string) url.Values

	// User is who a token belongs to. A rejected token is ErrBadToken.
	User(ctx context.Context, client *http.Client, token string) (User, error)

	// RepoRef is a repository URL as the forge's API names the repository —
	// and the check that the URL names one at all.
	RepoRef(repoURL string) (string, error)
	// Access asks, as the visitor, what they may do with the repository:
	// read it, write it. A repository they cannot see is (false, false, nil);
	// a rejected token is ErrBadToken.
	Access(ctx context.Context, client *http.Client, token, repoURL string) (read, write bool, err error)
	// Readers is the subset of logins that may read the repository, asked
	// with the server's credential, keyed by login — with whatever the forge
	// said about each on the way (a member list carries names and avatars).
	Readers(ctx context.Context, client *http.Client, serverToken, repoURL string, logins []string) (map[string]Person, error)
	// Lookup finds a person by login. It may or may not call the forge.
	Lookup(ctx context.Context, client *http.Client, token, login string) (Person, error)

	// GitAuth is the HTTPS credential git operations use with a token.
	GitAuth(token string) *githttp.BasicAuth
}

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

type Kind string

type Person struct {
	Login     string
	Name      string
	AvatarURL string
}

type User struct {
	Login     string
	Name      string
	AvatarURL string
}