appsync

README

appsync-client-go

AWS AppSync Go client library

Features

• GraphQL Query(Queries, Mutations and Subscriptions).
• MQTT over Websocket for subscriptions.
• Pure Websockets 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 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)
• type ClientOption
  • func WithIAMAuthorization(signer v4.Signer, region, host string) ClientOption
  • func WithSubscriberID(subscriberID string) ClientOption
• type Extensions
  • func NewExtensions(response *graphql.Response) (*Extensions, error)
• type GraphQLClient
  • func NewGraphQLClient(client *graphql.Client) GraphQLClient
• type PureWebSocketSubscriber
  • func NewPureWebSocketSubscriber(realtimeEndpoint string, request graphql.PostRequest, ...) *PureWebSocketSubscriber
  • func (p *PureWebSocketSubscriber) Start() error
  • func (p *PureWebSocketSubscriber) Stop()
• type PureWebSocketSubscriberOption
  • func WithAPIKey(host, apiKey string) PureWebSocketSubscriberOption
  • func WithIAM(signer *v4.Signer, region, host string) PureWebSocketSubscriberOption
  • func WithOIDC(host, jwt string) PureWebSocketSubscriberOption
• 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 (Graphqlws_subscription)
• Client (Mqtt_subscription)
• Client.Post (Mutation)
• Client.Post (Query)

Types

type Client

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

Client is the AppSync GraphQL API client

Example (Graphqlws_subscription)

package main

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

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

	appsync "github.com/sony/appsync-client-go"
	"github.com/sony/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 }`

	ch := make(chan *graphql.Response)
	subscriber := appsync.NewPureWebSocketSubscriber(
		strings.Replace(server.URL, "http", "ws", 1),
		graphql.PostRequest{
			Query: subscription,
		},
		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!

Example (Mqtt_subscription)

package main

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

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

	appsync "github.com/sony/appsync-client-go"
	"github.com/sony/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 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/sony/appsync-client-go/internal/appsynctest"

	appsync "github.com/sony/appsync-client-go"
	"github.com/sony/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/sony/appsync-client-go/internal/appsynctest"

	appsync "github.com/sony/appsync-client-go"
	"github.com/sony/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!

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.

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

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 PureWebSocketSubscriber

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

PureWebSocketSubscriber has pure WebSocket connections and subscription information.

func NewPureWebSocketSubscriber

func NewPureWebSocketSubscriber(realtimeEndpoint string, request graphql.PostRequest,
	onReceive func(response *graphql.Response),
	onConnectionLost func(err error),
	opts ...PureWebSocketSubscriberOption) *PureWebSocketSubscriber

NewPureWebSocketSubscriber returns a PureWebSocketSubscriber instance.

func (*PureWebSocketSubscriber) Start

func (p *PureWebSocketSubscriber) Start() error

Start starts a new subscription.

func (*PureWebSocketSubscriber) Stop

func (p *PureWebSocketSubscriber) Stop()

Stop ends the subscription.

type PureWebSocketSubscriberOption

type PureWebSocketSubscriberOption func(*PureWebSocketSubscriber)

PureWebSocketSubscriberOption represents options for an PureWebSocketSubscriber.

func WithAPIKey

func WithAPIKey(host, apiKey string) PureWebSocketSubscriberOption

WithAPIKey returns a PureWebSocketSubscriberOption configured with the host for the AWS AppSync GraphQL endpoint and API key

func WithIAM

func WithIAM(signer *v4.Signer, region, host string) PureWebSocketSubscriberOption

WithIAM returns a PureWebSocketSubscriberOption configured with the signature version 4 signer, the region and the host for the AWS AppSync GraphQL endpoint.

func WithOIDC

func WithOIDC(host, jwt string) PureWebSocketSubscriberOption

WithOIDC returns a PureWebSocketSubscriberOption configured with the host for the AWS AppSync GraphQL endpoint and JWT Access Token.

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