go-graphql-client

go-graphql-client is a GraphQL client implementation for Go. It is a fork of shurcooL/graphql that includes extended features such as a subscription client and named operations.

The subscription client follows the Apollo client specification using the WebSocket protocol via the coder/websocket library.

The client uses reflection to generate queries. To control this behavior, use specific struct tags:

• Custom Scalars: If a field is a custom scalar (like a JSON object) and you want to prevent the generator from expanding its internal fields, add the scalar:"true" tag. If the type implements the JSON decoder interface, it will be automatically decoded.
• Skip Fields: To prevent a field from being included in the generated GraphQL query, use the graphql:"-" tag.

struct {
	Viewer struct {
		ID         interface{} `graphql:"-"` // Field skipped in query
		Data       interface{} `scalar:"true"` // Field treated as scalar, not expanded
		Login      string
	}
}

By default, the client infers the GraphQL type name from the Go type name. If you need a different name (e.g., for lowercase GraphQL types or private Go types), you can:

1. Use a type alias.
2. Implement the GetGraphQLType() string method on your type.

type UserReviewInput struct {
	Review string
	UserID string
}

// Implement GetGraphQLType to override inference
func (u UserReviewInput) GetGraphQLType() string {
    return "user_review_input"
}

Install the client using the standard Go get command. Note that version v0.16 and later requires Go version 1.23 or later.

go get -u github.com/hasura/go-graphql-client

The repository provides two different client implementations for testing subscriptions with different protocols. You can run them using the following commands:

• subscriptions-transport-ws protocol: go run ./client/subscriptions-transport-ws
• graphql-ws protocol: go run ./client/graphql-ws

# Subscription with subscriptions-transport-ws protocol
go run ./client/subscriptions-transport-ws

# Subscription with graphql-ws protocol
go run ./client/graphql-ws

This example demonstrates a subscription client interacting with a Node.js server that implements graphql-ws with subscriptions-transport-ws backwards compatibility. It also demonstrates custom authentication handling via HTTP headers.

### 1. Start the Server
Requires Node.js and npm.

```bash
cd server
npm install
npm start

The server will be hosted on localhost:4000.

2. Run the Client

go run ./client

The graphql package does not handle authentication directly. Instead, you should provide an http.Client that performs authentication when creating a new client.

For simple header injection, use the WithRequestModifier method. For standard OAuth2 flows, it is recommended to use the golang.org/x/oauth2 package to create an http.Client and pass it to graphql.NewClient.

// Using WithRequestModifier for custom headers
client := graphql.NewClient(endpoint, http.DefaultClient).
  WithRequestModifier(func(r *http.Request) {
	  r.Header.Set("Authorization", "random-token")
})

// Using OAuth2
import "golang.org/x/oauth2"

func main() {
	src := oauth2.StaticTokenSource(
		&oauth2.Token{AccessToken: os.Getenv("GRAPHQL_TOKEN")},
	)
	httpClient := oauth2.NewClient(context.Background(), src)

	client := graphql.NewClient("https://example.com/graphql", httpClient)
}

This demo demonstrates the GraphQL client using Tibber's API. To run it, you must first obtain a demo token from the Tibber Developer Explorer, then set it as an environment variable before executing the program.

export TIBBER_DEMO_TOKEN=<token>
go run .

Since queries are generated at runtime via reflection, you can use Construct* functions to inspect the generated string before execution. Additionally, enabling debug mode with WithDebug will include the request and response details in the extensions[].internal property of any returned errors.

// Inspect the generated query string
queryStr, err := graphql.ConstructQuery(myStruct, variables)

// Enable debug mode in client
client := graphql.NewClient(endpoint, nil).WithDebug()

To handle GraphQL inline fragments (e.g., ... on Type), use the graphql struct tag on the field representing the fragment. You can either define the fragment fields directly in the parent struct or use an embedded struct type.

// Option 1: Direct fields
var q struct {
	Hero struct {
		Name  string
		Droid struct {
			PrimaryFunction string
		} `graphql:"... on Droid"`
	} `graphql:"hero(episode: \"JEDI\")"`
}

// Option 2: Embedded types
type DroidFragment struct {
	PrimaryFunction string
}

var q2 struct {
	Hero struct {
		Name          string
		DroidFragment `graphql:"... on Droid"` 
	} `graphql:"hero(episode: \"JEDI\")"`
}