appsync

README

appsync-client-go

AWS AppSync Go client library

Features

• GraphQL Query(Queries, Mutations and Subscriptions).
• MQTT over Websocket for subscriptions.

Getting Started

Installation

$ go get github.com/sony/appsync-client-go

Example

See example.

License

This library is distributed under The MIT license. See LICENSE and NOTICE for more information.

Documentation

Index

• type AuthTokenGetter
• type Client
  • func NewClient(graphql GraphQLClient, opts ...ClientOption) *Client
  • func (c *Client) Post(request graphql.PostRequest) (*graphql.Response, error)
  • func (c *Client) PostAsync(request graphql.PostRequest, callback func(*graphql.Response, error)) (context.CancelFunc, error)
  • func (c *Client) UpdateAuth(auth AuthTokenGetter)
• type ClientOption
  • func WithIAMAuthorization(signer v4.Signer, region, host string) ClientOption
  • func WithSubscriberID(subscriberID string) ClientOption
  • func WithTokenAuthorization(auth AuthTokenGetter) ClientOption
• type Extensions
  • func NewExtensions(response *graphql.Response) (*Extensions, error)
• type GraphQLClient
  • func NewGraphQLClient(client *graphql.Client) GraphQLClient
• type Subscriber
  • func NewSubscriber(extensions Extensions, callback func(response *graphql.Response), ...) *Subscriber
  • func (s *Subscriber) Start() error
  • func (s *Subscriber) Stop()
• type Subscription

Examples

• Client.Post (Mutation)
• Client.Post (Query)
• Client.Post (Query_with_tokens)
• Client.Post (Subscription)

Types

type AuthTokenGetter

type AuthTokenGetter interface {
	GetAuthToken() (string, error)
}

AuthTokenGetter is an interface represeting something that keeps tokens up to date, e.g. github.com/mec07/awstokens.Auth.

type Client

type Client struct {
	sync.RWMutex
	// contains filtered or unexported fields
}

Client is the AppSync GraphQL API client

func NewClient

func NewClient(graphql GraphQLClient, opts ...ClientOption) *Client

NewClient returns a Client instance.

func (*Client) Post

func (c *Client) Post(request graphql.PostRequest) (*graphql.Response, error)

Post is a synchronous AppSync GraphQL POST request.

Example (Mutation)

package main

import (
	"encoding/json"
	"fmt"
	"log"

	"github.com/mec07/appsync-client-go/internal/appsynctest"

	appsync "github.com/mec07/appsync-client-go"
	"github.com/mec07/appsync-client-go/graphql"
)

func main() {
	server := appsynctest.NewAppSyncEchoServer()
	defer server.Close()

	client := appsync.NewClient(appsync.NewGraphQLClient(graphql.NewClient(server.URL)))
	mutation := `mutation Echo($message: String!) { echo(message: $message) }`
	variables := json.RawMessage(fmt.Sprintf(`{ "message": "%s"	}`, "Hi, AppSync!"))
	response, err := client.Post(graphql.PostRequest{
		Query:     mutation,
		Variables: &variables,
	})
	if err != nil {
		log.Fatal(err)
	}

	data := new(string)
	if err := response.DataAs(data); err != nil {
		log.Fatalln(err, response)
	}
	fmt.Println(*data)

}

Output:

Hi, AppSync!

Example (Query)

package main

import (
	"fmt"
	"log"

	"github.com/mec07/appsync-client-go/internal/appsynctest"

	appsync "github.com/mec07/appsync-client-go"
	"github.com/mec07/appsync-client-go/graphql"
)

func main() {
	server := appsynctest.NewAppSyncEchoServer()
	defer server.Close()

	query := `query Message() { message }`
	client := appsync.NewClient(appsync.NewGraphQLClient(graphql.NewClient(server.URL)))
	response, err := client.Post(graphql.PostRequest{
		Query: query,
	})
	if err != nil {
		log.Fatal(err)
	}

	data := new(string)
	if err := response.DataAs(data); err != nil {
		log.Fatalln(err, response)
	}
	fmt.Println(*data)

}

Output:

Hello, AppSync!

Example (Query_with_tokens)

server := appsynctest.NewAppSyncEchoServer()
defer server.Close()

query := `query Message() { message }`

validToken, err := jwt.NewWithClaims(jwt.SigningMethodHS256, jwt.StandardClaims{
	ExpiresAt: time.Now().Add(time.Hour).UTC().Unix(),
}).SignedString([]byte("secret signing key"))
if err != nil {
	log.Fatal(err)
}
config := awstokens.Config{
	AccessToken:  validToken,
	IDToken:      "id_token",
	RefreshToken: "refresh_token",
}
auth, err := awstokens.NewAuth(config)
if err != nil {
	log.Fatal(err)
}
client := appsync.NewClient(
	appsync.NewGraphQLClient(graphql.NewClient(server.URL)),
	appsync.WithTokenAuthorization(auth),
)
response, err := client.Post(graphql.PostRequest{
	Query: query,
})
if err != nil {
	log.Fatal(err)
}

data := new(string)
if err := response.DataAs(data); err != nil {
	log.Fatalln(err, response)
}
fmt.Println(*data)

Output:

Hello, AppSync!

Example (Subscription)

package main

import (
	"encoding/json"
	"fmt"
	"log"

	"github.com/mec07/appsync-client-go/internal/appsynctest"

	appsync "github.com/mec07/appsync-client-go"
	"github.com/mec07/appsync-client-go/graphql"
)

func main() {
	server := appsynctest.NewAppSyncEchoServer()
	defer server.Close()

	client := appsync.NewClient(appsync.NewGraphQLClient(graphql.NewClient(server.URL)))
	subscription := `subscription SubscribeToEcho() { subscribeToEcho }`
	response, err := client.Post(graphql.PostRequest{
		Query: subscription,
	})
	if err != nil {
		log.Fatal(err)
	}

	ext, err := appsync.NewExtensions(response)
	if err != nil {
		log.Fatalln(err)
	}

	ch := make(chan *graphql.Response)
	subscriber := appsync.NewSubscriber(*ext,
		func(r *graphql.Response) { ch <- r },
		func(err error) { log.Println(err) },
	)

	if err := subscriber.Start(); err != nil {
		log.Fatalln(err)
	}
	defer subscriber.Stop()

	mutation := `mutation Echo($message: String!) { echo(message: $message) }`
	variables := json.RawMessage(fmt.Sprintf(`{ "message": "%s" }`, "Hi, AppSync!"))
	_, err = client.Post(graphql.PostRequest{
		Query:     mutation,
		Variables: &variables,
	})
	if err != nil {
		log.Fatal(err)
	}

	response = <-ch
	data := new(string)
	if err := response.DataAs(data); err != nil {
		log.Fatalln(err, response)
	}
	fmt.Println(*data)

}

Output:

Hi, AppSync!

func (*Client) PostAsync

func (c *Client) PostAsync(request graphql.PostRequest, callback func(*graphql.Response, error)) (context.CancelFunc, error)

PostAsync is an asynchronous AppSync GraphQL POST request.

func (*Client) UpdateAuth

func (c *Client) UpdateAuth(auth AuthTokenGetter)

UpdateAuth lets the user update the tokens. This is necessary because the refresh token will eventually expire.

type ClientOption

type ClientOption func(*Client)

ClientOption represents options for an AppSync client.

func WithIAMAuthorization

func WithIAMAuthorization(signer v4.Signer, region, host string) ClientOption

WithIAMAuthorization returns a ClientOption configured with the given signature version 4 signer.

func WithSubscriberID

func WithSubscriberID(subscriberID string) ClientOption

WithSubscriberID returns a ClientOption configured with the given AppSync subscriber ID

func WithTokenAuthorization

func WithTokenAuthorization(auth AuthTokenGetter) ClientOption

WithTokenAuthorization uses tokens to authorize the request. We recommend using github.com/mec07/awstokens.Auth to satisfy this interface.

type Extensions

type Extensions struct {
	Subscription struct {
		Version         string `json:"version"`
		MqttConnections []struct {
			URL    string   `json:"url"`
			Topics []string `json:"topics"`
			Client string   `json:"client"`
		} `json:"mqttConnections"`
		NewSubscriptions map[string]Subscription `json:"newSubscriptions"`
	} `json:"subscription"`
}

Extensions represents AWS AppSync subscription response extensions

func NewExtensions

func NewExtensions(response *graphql.Response) (*Extensions, error)

NewExtensions returns Extensions instance

type GraphQLClient

type GraphQLClient interface {
	Post(header http.Header, request graphql.PostRequest) (*graphql.Response, error)
	PostAsync(header http.Header, request graphql.PostRequest, callback func(*graphql.Response, error)) (context.CancelFunc, error)
}

GraphQLClient is the interface to access GraphQL server.

func NewGraphQLClient

func NewGraphQLClient(client *graphql.Client) GraphQLClient

NewGraphQLClient returns a GraphQLClient interface

type Subscriber

type Subscriber struct {
	// contains filtered or unexported fields
}

Subscriber has MQTT connections and subscription information.

func NewSubscriber

func NewSubscriber(extensions Extensions, callback func(response *graphql.Response), onConnectionLost func(err error)) *Subscriber

NewSubscriber returns a new Subscriber instance.

func (*Subscriber) Start

func (s *Subscriber) Start() error

Start starts a new subscription.

func (*Subscriber) Stop

func (s *Subscriber) Stop()

Stop ends the subscription.

type Subscription

type Subscription struct {
	Topic      string      `json:"topic"`
	ExpireTime interface{} `json:"expireTime"`
}

Subscription represents AWS AppSync subscription mqtt topic