graphql

README

graphql

Low-level GraphQL client for Go.

• Simple, familiar API
• Respects context.Context timeouts and cancellation
• Build and execute any kind of GraphQL request
• Use strong Go types for response data
• Use variables and upload files
• Simple error handling

Installation

Make sure you have a working Go environment. To install graphql, simply run:

$ go get github.com/machinebox/graphql

Usage

import "context"

// create a client (safe to share across requests)
client := graphql.NewClient("https://machinebox.io/graphql")

// make a request
req := graphql.NewRequest(`
    query ($key: String!) {
        items (id:$key) {
            field1
            field2
            field3
        }
    }
`)

// set any variables
req.Var("key", "value")

// set header fields
req.Header.Set("Cache-Control", "no-cache")

// define a Context for the request
ctx := context.Background()

// run it and capture the response
var respData ResponseStruct
if err := client.Run(ctx, req, &respData); err != nil {
    log.Fatal(err)
}

File support via multipart form data

By default, the package will send a JSON body. To enable the sending of files, you can opt to use multipart form data instead using the UseMultipartForm option when you create your Client:

client := graphql.NewClient("https://machinebox.io/graphql", graphql.UseMultipartForm())

For more information, read the godoc package documentation or the blog post.

Thanks

Thanks to Chris Broadfoot for design help.

Documentation

Overview

Package graphql provides a low level GraphQL client.

// create a client (safe to share across requests)
client := graphql.NewClient("https://machinebox.io/graphql")

// make a request
req := graphql.NewRequest(`
    query ($key: String!) {
        items (id:$key) {
            field1
            field2
            field3
        }
    }
`)

// set any variables
req.Var("key", "value")

// run it and capture the response
var respData ResponseStruct
if err := client.Run(ctx, req, &respData); err != nil {
    log.Fatal(err)
}

Specify client

To specify your own http.Client, use the WithHTTPClient option:

httpclient := &http.Client{}
client := graphql.NewClient("https://machinebox.io/graphql", graphql.WithHTTPClient(httpclient))

Index

• type Client
  • func NewClient(endpoint string, opts ...ClientOption) Client
• type ClientOption
  • func ImmediatelyCloseReqBody() ClientOption
  • func UseMultipartForm() ClientOption
  • func WithBeforeRetryHandler(beforeRetryHandler func(*http.Request, *http.Response, error, int)) ClientOption
  • func WithDefaultExponentialRetryConfig() ClientOption
  • func WithDefaultHeaders(defaultHeaders map[string]string) ClientOption
  • func WithDefaultLinearRetryConfig() ClientOption
  • func WithHTTPClient(httpclient *http.Client) ClientOption
  • func WithRetryConfig(config RetryConfig) ClientOption
• type File
• type PolicyType
• type Request
  • func NewRequest(q string) *Request
  • func (req *Request) File(fieldname, filename string, r io.Reader)
  • func (req *Request) Files() []File
  • func (req *Request) Query() string
  • func (req *Request) Var(key string, value interface{})
  • func (req *Request) Vars() map[string]interface{}
• type RetryConfig

Types

type Client

type Client interface {
	Run(ctx context.Context, req *Request, resp interface{}) error
	SetLogger(func(string))
}

func NewClient

func NewClient(endpoint string, opts ...ClientOption) Client

NewClient makes a new Client capable of making GraphQL requests.

type ClientOption

type ClientOption func(*clientImp)

ClientOption are functions that are passed into NewClient to modify the behaviour of the Client.

func ImmediatelyCloseReqBody

func ImmediatelyCloseReqBody() ClientOption

ImmediatelyCloseReqBody will close the req body immediately after each request body is ready

func UseMultipartForm

func UseMultipartForm() ClientOption

UseMultipartForm uses multipart/form-data and activates support for files.

func WithBeforeRetryHandler

func WithBeforeRetryHandler(beforeRetryHandler func(*http.Request, *http.Response, error, int)) ClientOption

WithBeforeRetryHandler provides a handler for beforeRetry

func WithDefaultExponentialRetryConfig

func WithDefaultExponentialRetryConfig() ClientOption

WithDefaultExponentialRetryConfig provides a default set of value for exponential backoff policy

func WithDefaultHeaders

func WithDefaultHeaders(defaultHeaders map[string]string) ClientOption

WithDefaultHeaders provides a default set of header values

func WithDefaultLinearRetryConfig

func WithDefaultLinearRetryConfig() ClientOption

WithDefaultLinearRetryConfig provides a default set of value for linear policy

func WithHTTPClient

func WithHTTPClient(httpclient *http.Client) ClientOption

WithHTTPClient specifies the underlying http.Client to use when making requests.

NewClient(endpoint, WithHTTPClient(specificHTTPClient))

func WithRetryConfig

func WithRetryConfig(config RetryConfig) ClientOption

WithRetryConfig allows consumer to assign their retryConfig to the client's private retryConfig

type File

type File struct {
	Field string
	Name  string
	R     io.Reader
}

File represents a file to upload.

type PolicyType

type PolicyType string

PolicyType defines a type of different possible Policies to be applied towards retrying

const (
	// ExponentialBackoff - the interval is doubled after every try until hitting MaxInterval or MaxTries
	ExponentialBackoff PolicyType = "exponential_backoff"
	// Linear - the interval stays the same every try until hitting MaxTries
	Linear PolicyType = "linear"
)

type Request

type Request struct {

	// Header represent any request headers that will be set
	// when the request is made.
	Header http.Header
	// contains filtered or unexported fields
}

Request is a GraphQL request.

func NewRequest

func NewRequest(q string) *Request

NewRequest makes a new Request with the specified string.

func (*Request) File

func (req *Request) File(fieldname, filename string, r io.Reader)

File sets a file to upload. Files are only supported with a Client that was created with the UseMultipartForm option.

func (*Request) Files

func (req *Request) Files() []File

Files gets the files in this request.

func (*Request) Query

func (req *Request) Query() string

Query gets the query string of this request.

func (*Request) Var

func (req *Request) Var(key string, value interface{})

Var sets a variable.

func (*Request) Vars

func (req *Request) Vars() map[string]interface{}

Vars gets the variables for this Request.

type RetryConfig

type RetryConfig struct {
	// Optional - Max number of times client should retry
	MaxTries int `json:"maxTries"`
	// Required - Time interval to wait before trying attempt sending a request again
	Interval float64 `json:"interval"`
	// Required - Defines a policy to be used for retry
	Policy PolicyType `json:"policy"`
	// Optional - The max interval of time to wait before retrying
	MaxInterval float64 `json:"maxInterval"`
	// Optional - A mapping of statuses that client should retry.
	// If not specifed, we will use default retry behavior on certain statuses
	RetryStatus map[int]bool `json:"statusToRetry"`
	// Client can use this function to supply some logic to further debug GraphQL request & response
	BeforeRetry func(req *http.Request, resp *http.Response, err error, attemptNum int)
}

RetryConfig defines possible fields that client can supply for their retry strategies