github

README

github.com/carabiner-dev/github

A super simple client to talk to the GitHub API.

Description

This library implements a very very simple client to talk to the GitHub (and someday possibly other) APIs. The goals of this client are:

1. Lightweight: Low dependency count.
2. Easy to use in tests, easy to mock.
3. Pluggable credential (token) providers.

Non-goals include:

1. Response parsing
2. Anything else beyond handling https connections.

Usage

To use the client, simply export a token in GITHUB_TOKEN and run something like:

package main

import  "github.com/carabiner-dev/github"

func main() {
    // Creat the client
    client, err := github.NewClient()

    // Call an API endpoint:
    resp, err := client.Call(ctx, http.MethodGet, "users/carabiner-dev", nil)
    if err != nil {
        fmt.Fprintln(os.Stderr, err.Error())
    }

    // Output the response to stdout:
    io.Copy(os.Stdout, resp.Body)
    resp.Close()
}

Install

To pull the package simply use go get:

github.com/carabiner-dev/github

License

This package is released under the Apache 2.0 license by Carabiner Systems, Inc. Patches issues and contributions are welcome!

Documentation

Index

• Constants
• Variables
• func WithCaller(c Caller) fnOpt
• func WithEnsureToken(e bool) fnOpt
• func WithHost(h string) fnOpt
• func WithToken(t string) fnOpt
• func WithTokenReader(r TokenReader) fnOpt
• type Caller
• type Client
  • func NewClient(optFns ...fnOpt) (*Client, error)
  • func NewClientWithOptions(opts Options) (*Client, error)
  • func (c *Client) Call(ctx context.Context, method, path string, body io.Reader) (*http.Response, error)
• type EnvTokenReader
  • func (etr *EnvTokenReader) ReadToken() (string, error)
• type FileCaller
  • func (fc *FileCaller) RequestWithContext(_ context.Context, _, _ string, _ io.Reader) (*http.Response, error)
• type Options
  • func (o *Options) Validate() error
• type TokenReader

Constants

const DefaultAPIHostname = "api.github.com"

Variables

var DefaultEnvTokenReader = EnvTokenReader{
	VarName: "GITHUB_TOKEN",
}

DefaultEnvTokenReader is an env token reader configured to read the token from the GITHUB_TOKEN env variable.

Functions

func WithCaller

func WithCaller(c Caller) fnOpt

func WithEnsureToken

func WithEnsureToken(e bool) fnOpt

func WithHost

func WithHost(h string) fnOpt

func WithToken

func WithToken(t string) fnOpt

func WithTokenReader

func WithTokenReader(r TokenReader) fnOpt

Types

type Caller

type Caller interface {
	RequestWithContext(context.Context, string, string, io.Reader) (*http.Response, error)
}

Replaceable caller interface

type Client

type Client struct {
	Options Options
	// contains filtered or unexported fields
}

func NewClient

func NewClient(optFns ...fnOpt) (*Client, error)

NewClient creates a new client. It can take any number of optional functions

func NewClientWithOptions

func NewClientWithOptions(opts Options) (*Client, error)

NewClientWithOptions creates a new client, taking a full options set.

func (*Client) Call

func (c *Client) Call(ctx context.Context, method, path string, body io.Reader) (*http.Response, error)

type EnvTokenReader

type EnvTokenReader struct {
	VarName string
}

EnvTokenReader is a token reader that extracts an API token from an environment variable

func (*EnvTokenReader) ReadToken

func (etr *EnvTokenReader) ReadToken() (string, error)

ReadToken reads the token string from the convigured `VarName` environment variable.

type FileCaller

type FileCaller struct {
	SourcePath string
	Error      error
}

FileCaller implements the Caller but returns the data as read from a file specified in SourcePath. This is intended mostly for testing.

func (*FileCaller) RequestWithContext

func (fc *FileCaller) RequestWithContext(_ context.Context, _, _ string, _ io.Reader) (*http.Response, error)

RequestWithContext simulates the request to the API by returning a response from a file. If Error is set, it will return nil and the synthetic error.

type Options

type Options struct {
	Host        string
	Token       string
	EnsureToken bool
	TokenReader TokenReader
	Caller      Caller
}

func (*Options) Validate

func (o *Options) Validate() error

Validate ensures the client options are sane

type TokenReader

type TokenReader interface {
	ReadToken() (string, error)
}

TokenReader is an interface that abstracts a mechanism to read a token securely.