crusch

README

Crusch is a lightweight libary which provides tools for Github Apps to communicate with Githubs V3 API, without too much unnecessary hassle.

This libary provides a simple client structure to make requests to Githubs API. Clients aid with adding and creating the required authorization headers, keeping track of when they might need to be renewed and other small helper methods.

If you are looking for something more complete then go-github is probably for you. go-github is a more complete libary with types, seperate methods and bindings for every request github offers, which for what I was working on, was too complicated and quite annoying to work with when all I wanted was something simple, hence crusch.

Usage

import "github.com/aixr/crusch"

basic example

client := crusch.NewDefault()
client.NewInstallationAuthFile(<ApplicationID>, <InstallationID>, <PEM keyfile location>)

v := make(map[string]interface{})
respose, err := client.GetJson(
    fmt.Sprintf("/repos/%s/%s/issues", <user>, <repo>), 
    "assignee=aixr&state=open", &v)

Clients created through crusch.New(<name>, <baseURL>) or crusch.NewDefault() are added to a client pool, accessed via crusch.Pool variable, allowing you to get premade clients by name or authentication details.

client1 := crusch.New("client_1", "api.github.com")
client1.NewInstallationAuth(<ApplicationID>, <InstallationID>, <private key>)

...

client = crusch.Pool.Get("client_1")

issue := []byte(`
    "title": "Issue title",
    "body": "Issue body"
`)
buffer := bytes.NewBuffer(issue)
client.Post(fmt.Sprintf("/repos/%s/%s/issues", <owner>, <repo>), buffer)

If more control over the request is required, there is also a Do(*http.Request) method which will take a *http.Request, apply the authentication headers and send the request.

req := http.Request{}
req.Header = http.Header{}

req.Method = http.MethodPost
req.Header.Add("Accept", "application/vnd.github.squirrel-girl-preview+json")
req.URL = &url.URL{
    Scheme: "https", 
    Host: "api.github.com", 
    Path: "/repos/<owner>/<repo>/comments/<comment_id>/reactions",
}

client = crusch.NewDefault()
client.NewOAuth("11a6c2809da4bc163487481cf02fb210", "bearer")
res, err := client.Do(req)

Notes

Im extemely new to golang (this is the second project, which was done alongside the 'first') so there are certainly things that can be done better, I will happily take feedback/contributions.

Todo

1. use contexts
2. finish tests
3. docs
4. optional types/structs? maybe - go-github's types work well alongside this already

Documentation

Index

• func JsonBody(body interface{}) (*bytes.Buffer, error)
• func ParseQuery(opt interface{}) (string, error)
• func RSAPrivateKeyFromPEMFile(keyfile string) (*rsa.PrivateKey, error)
• type AuthType
• type Authorization
• type Client
  • func New(name string, baseURL string) *Client
  • func NewDefault() *Client
  • func (s *Client) Authorization() (string, error)
  • func (s *Client) Delete(uri string) (*http.Response, error)
  • func (s *Client) DeleteJson(uri string, v interface{}) (*http.Response, error)
  • func (s *Client) Dispose() *Client
  • func (s *Client) Do(req *http.Request) (*http.Response, error)
  • func (s *Client) Get(uri string, params interface{}) (*http.Response, error)
  • func (s *Client) GetJson(uri string, params interface{}, v interface{}) (*http.Response, error)
  • func (s *Client) GetURL() string
  • func (s *Client) NewApplicationAuth(applicationID int64, key *rsa.PrivateKey)
  • func (s *Client) NewApplicationAuthBytes(applicationID int64, key []byte)
  • func (s *Client) NewApplicationAuthFile(applicationID int64, keyfile string)
  • func (s *Client) NewInstallationAuth(applicationID int64, installationID int64, key *rsa.PrivateKey)
  • func (s *Client) NewInstallationAuthBytes(applicationID int64, installationID int64, key []byte)
  • func (s *Client) NewInstallationAuthFile(applicationID int64, installationID int64, keyfile string)
  • func (s *Client) NewOAuth(token string, oauthType string)
  • func (s *Client) Patch(uri string, body *bytes.Buffer) (*http.Response, error)
  • func (s *Client) PatchJson(uri string, body interface{}, v interface{}) (*http.Response, error)
  • func (s *Client) Post(uri string, body *bytes.Buffer) (*http.Response, error)
  • func (s *Client) PostJson(uri string, body interface{}, v interface{}) (*http.Response, error)
  • func (s *Client) Put(uri string, body *bytes.Buffer) (*http.Response, error)
  • func (s *Client) PutJson(uri string, body interface{}, v interface{}) (*http.Response, error)
• type ClientPool
  • func (cp *ClientPool) Get(name string) *Client
  • func (cp *ClientPool) GetByApplicationAuth(applicationID int64) *Client
  • func (cp *ClientPool) GetByInstallationAuth(applicationID int64, installationID int64) *Client
  • func (cp *ClientPool) GetByOauthToken(token string) *Client
• type LastUsed

Functions

func JsonBody

func JsonBody(body interface{}) (*bytes.Buffer, error)

JsonBody takes a model/struct and attempts to make it into a *bytes.Buffer

func ParseQuery

func ParseQuery(opt interface{}) (string, error)

ParseQuery turns a struct into a url encoded query string

func RSAPrivateKeyFromPEMFile

func RSAPrivateKeyFromPEMFile(keyfile string) (*rsa.PrivateKey, error)

RSAPrivateKeyFromPEMFile returns the *rsa.PrivateKey decoded from given PEM file, can be used elsewhere when generating Clients without having to read the file over and over

Types

type AuthType

type AuthType int

AuthType allows us to identify the authorization type to use when generating authorization headers

const (
	// Application authentication type
	// This type works using the ApplicationID and
	// private kd by Github
	Application AuthType = 0
	// Installation authentication type
	// Similar to application but authorizes as a specific
	// application installion using the ApplicationID, InstallationID
	// and privatovided by Github
	Installation AuthType = 1
	// OAuth authentication type
	// Just uses an OAuth token to authorize application as a specific user
	OAuth AuthType = 2
)

type Authorization

type Authorization struct {
	AuthType         AuthType
	ApplicationID    int64
	InstallationID   int64
	OAuthAccessToken string
	OAuthType        string
	Key              *rsa.PrivateKey
	LastUsed         *LastUsed
}

Authorization for github requests

type Client

type Client struct {
	Name     string
	BaseURL  string
	Protocol string
	Auth     *Authorization
}

Client for making http requests to Githubs v3 json api

func New

func New(name string, baseURL string) *Client

New creates a new Client struct using given arguments

func NewDefault

func NewDefault() *Client

NewDefault creates a new Client with default values and no auth

func (*Client) Authorization

func (s *Client) Authorization() (string, error)

Authorization creates and returns the Clients authorization header

func (*Client) Delete

func (s *Client) Delete(uri string) (*http.Response, error)

Delete executes a Delete http request to given uri

func (*Client) DeleteJson

func (s *Client) DeleteJson(uri string, v interface{}) (*http.Response, error)

DeleteJson executes a Delete http request to given uri and binds the response to v

func (*Client) Dispose

func (s *Client) Dispose() *Client

Dispose of client and references to it

func (*Client) Do

func (s *Client) Do(req *http.Request) (*http.Response, error)

Do takes a *http.Request adds authorization headers and performs the request useful for requests that don't follow Githubs usual headers and body etc i.e. reactions

func (*Client) Get

func (s *Client) Get(uri string, params interface{}) (*http.Response, error)

Get executes a GET http request to given uri and params params must be a Struct, string or nil

func (*Client) GetJson

func (s *Client) GetJson(uri string, params interface{}, v interface{}) (*http.Response, error)

GetJson executes a GET http request to given uri and params and binds the response to v params must be a Struct, string or nil

func (*Client) GetURL

func (s *Client) GetURL() string

GetURL looks at values in client and formats the full url this method isn't exactly fool-proof but it should kind of work...

func (*Client) NewApplicationAuth

func (s *Client) NewApplicationAuth(applicationID int64, key *rsa.PrivateKey)

NewApplicationAuth creates new application authentication Client

func (*Client) NewApplicationAuthBytes

func (s *Client) NewApplicationAuthBytes(applicationID int64, key []byte)

NewApplicationAuthBytes creates new application authentication Client from byte array

func (*Client) NewApplicationAuthFile

func (s *Client) NewApplicationAuthFile(applicationID int64, keyfile string)

NewApplicationAuthFile creates new application authentication Client from keyfile

func (*Client) NewInstallationAuth

func (s *Client) NewInstallationAuth(applicationID int64, installationID int64, key *rsa.PrivateKey)

NewInstallationAuth creates new installation authentication Client

func (*Client) NewInstallationAuthBytes

func (s *Client) NewInstallationAuthBytes(applicationID int64, installationID int64, key []byte)

NewInstallationAuthBytes creates new installation authentication Client from byte array

func (*Client) NewInstallationAuthFile

func (s *Client) NewInstallationAuthFile(applicationID int64, installationID int64, keyfile string)

NewInstallationAuthFile creates new installation authentication Client from keyfile

func (*Client) NewOAuth

func (s *Client) NewOAuth(token string, oauthType string)

NewOAuth creates a new OAuth authentication client

func (*Client) Patch

func (s *Client) Patch(uri string, body *bytes.Buffer) (*http.Response, error)

Patch executes a PATCH http request to given uri and binds the response to v body will be encoded to json, use nil for no body

func (*Client) PatchJson

func (s *Client) PatchJson(uri string, body interface{}, v interface{}) (*http.Response, error)

PatchJson executes a PATCH http request to given uri and binds the response to v body will be encoded to json, use nil for no body

func (*Client) Post

func (s *Client) Post(uri string, body *bytes.Buffer) (*http.Response, error)

Post executes a POST http request to given uri and binds the response to v body will be encoded to json, use nil for no body

func (*Client) PostJson

func (s *Client) PostJson(uri string, body interface{}, v interface{}) (*http.Response, error)

PostJson executes a POST http request to given uri and binds the response to v body will be encoded to json, use nil for no body

func (*Client) Put

func (s *Client) Put(uri string, body *bytes.Buffer) (*http.Response, error)

Put executes a PUT http request to given uri and binds the response to v body will be encoded to json, use nil for no body

func (*Client) PutJson

func (s *Client) PutJson(uri string, body interface{}, v interface{}) (*http.Response, error)

PutJson executes a PUT http request to given uri and binds the response to v body will be encoded to json, use nil for no body

type ClientPool

type ClientPool struct {
	Pool []*Client
}

ClientPool stores a slice of Clients created in this session Clients are automatically added when created using New or NewDefault

var (
	// Pool is an array of Clients used within this session
	Pool ClientPool = ClientPool{}
)

func (*ClientPool) Get

func (cp *ClientPool) Get(name string) *Client

Get will find a client by the given name, if multiple are in the array, only the first will be returned

func (*ClientPool) GetByApplicationAuth

func (cp *ClientPool) GetByApplicationAuth(applicationID int64) *Client

GetByApplicationAuth tries to find an existing application client that matches the auth details

func (*ClientPool) GetByInstallationAuth

func (cp *ClientPool) GetByInstallationAuth(applicationID int64, installationID int64) *Client

GetByInstallationAuth tries to find an existing installation client that matches the auth details

func (*ClientPool) GetByOauthToken

func (cp *ClientPool) GetByOauthToken(token string) *Client

GetByOauthToken tries to find an existing application client that matches the auth details

type LastUsed

type LastUsed struct {
	AuthHeader string
	ValidUntil int64
	Time       int64
}

LastUsed authentication header & valid until date for this Client