ghtoken

Documentation

Overview

Package ghtoken has magpie's requests to GitHub's REST API carry the user's GitHub token, and says plainly when GitHub turns them away.

GitHub's API answers an address 60 requests an hour without a token, which a check of a few repositories, or a network shared with others, uses up; with a token it answers 5,000 an hour. The token is the one set in Settings (GitHubToken), else GITHUB_TOKEN or GH_TOKEN from the environment. It goes to GitHub's API's host alone, never to codeload, raw files or a mirror (source.Do sends no request with Authorization to one), and is never written to a log or an error. The library's skills and the Plugins page's git plugins both ask GitHub through here (#1942).

A token GitHub refuses (401) is one that no longer reads: the request is asked again without it, and the token isn't sent again while magpie runs (till on Discord). For a token from the environment that is the whole of it. The token set in Settings is the user's own choice, so its refusal is also said (SettingsRefused): the checks go on without a token, not with the environment's, rather than failing whole, and Settings › Network and sharing says that token was refused and needs replacing (#3926).

Index

• Variables
• func Authorize(req *http.Request, api string) bool
• func Do(req *http.Request, api string, ...) (*http.Response, bool, error)
• func Refused() error
• func SettingsRefused() (time.Time, bool)
• func Token() (token, from string)
• type Limited
  • func LimitedBy(resp *http.Response, body []byte, token bool) (Limited, bool)
  • func (e Limited) Error() string

Variables

var Env = []string{"GITHUB_TOKEN", "GH_TOKEN"}

Env names the environment variables a token is taken from when Settings has none, in the order they are looked at.

Functions

func Authorize

func Authorize(req *http.Request, api string) bool

Authorize has req carry the token, if there is one and req goes to the host of api (GitHub's API's base URL, which tests move); it says whether it did.

Do is Authorize with an environment token GitHub refuses dropped for an anonymous request; a caller sends through it rather than this.

func Do

func Do(req *http.Request, api string, send func(*http.Request) (*http.Response, error)) (*http.Response, bool, error)

Do sends req with send, carrying the token as Authorize does, and says whether the answer given back is to a request that carried it. When GitHub refuses (401) a token, that token is dropped for the rest of the run and req is sent again without it: the anonymous answer is the one given back, so a check goes on with the 60 an hour rather than failing whole. A refusal of the token set in Settings is kept too (SettingsRefused), for the page to say which token to replace.

func Refused

func Refused() error

Refused is the error for a 401 from GitHub to a request that carried the token: which token it was, never the token itself.

func SettingsRefused

func SettingsRefused() (time.Time, bool)

SettingsRefused is when GitHub refused the token set in Settings, and whether it did. From then on the checks ask GitHub without a token until that field is changed or magpie restarts, so a stale token costs the user the 5,000 an hour it was for and not every check (#3926).

func Token

func Token() (token, from string)

Token is the token requests to GitHub's API carry, and where it came from: "settings", the environment variable's name, or "" for none. A token GitHub refused isn't one, wherever it came from. After an environment variable's, the next variable's is, or none; after the one set in Settings, none: the user chose that one over the environment's, and the page says requests go without a token till it is replaced.

Types

type Limited

type Limited struct {
	Until time.Time
	Token bool
}

Limited is GitHub turning requests away for a while: until when (zero when GitHub didn't say), and whether the requests carried a token.

func LimitedBy

func LimitedBy(resp *http.Response, body []byte, token bool) (Limited, bool)

LimitedBy is the Limited a refusal of GitHub's says, or false when it isn't one: 429, or 403 with the limit spent or a secondary limit's Retry-After or message. A 403 for anything else (a token without access) isn't one.

func (Limited) Error

func (e Limited) Error() string