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 from the environment that GitHub refuses (401) is one the user may not know is there, often stale: the request is asked again without it, and the token isn't sent again while magpie runs (till on Discord). The token set in Settings is the user's own choice, so a refusal of it is said (Refused).

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 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 from the environment, 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. A refused token from Settings is answered as GitHub answered, for the caller to say Refused().

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 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. An environment variable's token GitHub refused isn't one: the next variable's is, or none.

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