dfuse

README

StreamingFast Golang Client Library

A GraphQL client library to consume dfuse API https://streamingfast.io (dfuse docs).

Installation

go get github.com/streamingfast/client-go

Features

What you get by using this library:

• StreamingFast API Token issuance & management (auto-refresh, expiration handling, storage, etc)
• StreamingFast GraphQL over gRPC API (planned)
• StreamingFast gRPC API helpers (planned)

Quick Start

Notice You should replace the sequence of characters Paste your API key here in the script above with your actual API key obtained from https://app.dfuse.io. You are connecting to a local unauthenticated dfuse instance or to a dfuse Community Edition (EOSIO only)? Replace apiKey: "<Paste your API key here>" pass option dfuse.WithoutAuthentication when creating your client.

Common

package main

import (

)

func main() {
    client, err := StreamingFast.NewClient("mainnet.eos.dfuse.io", "<Paste your API key here>")
    if err != nil { panic(err) }

    tokenInfo, err := client.GetAPITokenInfo(context.Background())
    if err != nil { panic(err) }

    // Use `tokenInfo.Token` and use it to connect to dfuse's API (`fmt.Sprintf("Bearer %s", tokenInfo.Token)`)
}

References

• streamingfast Docs

Contributing

Issues and PR in this repo related strictly to the Golang client library.

Report any protocol-specific issues in their respective repositories

Please first refer to the general StreamingFast contribution guide, if you wish to contribute to this code base.

This codebase uses unit tests extensively, please write and run tests.

License

Apache 2.0

Documentation

Index

• type APITokenInfo
  • func (t *APITokenInfo) IsAboutToExpire() bool
  • func (t *APITokenInfo) MarshalLogObject(encoder zapcore.ObjectEncoder) error
• type APITokenStore
• type Client
  • func NewClient(network string, apiKey string, opts ...ClientOption) (Client, error)
• type ClientOption
  • func WithAPITokenStore(store APITokenStore) ClientOption
  • func WithAuthURL(authURL string) ClientOption
  • func WithGRPCPort(port int) ClientOption
  • func WithInsecure() ClientOption
  • func WithLogger(logger *zap.Logger) ClientOption
  • func WithPlainText() ClientOption
  • func WithoutAuthentication() ClientOption
• type ExperimentalClient
• type FileAPITokenStore
  • func NewFileAPITokenStore(filePath string) *FileAPITokenStore
  • func (s *FileAPITokenStore) Get(ctx context.Context) (*APITokenInfo, error)
  • func (s *FileAPITokenStore) Set(ctx context.Context, token *APITokenInfo) error
  • func (s *FileAPITokenStore) String() string
• type GraphQLDocument
• type GraphQLFileDocument
  • func (d GraphQLFileDocument) Load(ctx context.Context) (string, error)
• type GraphQLOption
• type GraphQLStream
• type GraphQLStringDocument
  • func (d GraphQLStringDocument) Load(ctx context.Context) (string, error)
• type GraphQLVariables
• type InMemoryAPITokenStore
  • func NewInMemoryAPITokenStore() *InMemoryAPITokenStore
  • func (s *InMemoryAPITokenStore) Get(ctx context.Context) (*APITokenInfo, error)
  • func (s *InMemoryAPITokenStore) Set(ctx context.Context, token *APITokenInfo) error
  • func (s *InMemoryAPITokenStore) String() string
• type OnDiskAPITokenStore
  • func NewOnDiskAPITokenStore(apiKey string) *OnDiskAPITokenStore

Types

type APITokenInfo

type APITokenInfo struct {
	Token     string
	ExpiresAt time.Time
}

func (*APITokenInfo) IsAboutToExpire

func (t *APITokenInfo) IsAboutToExpire() bool

func (*APITokenInfo) MarshalLogObject

func (t *APITokenInfo) MarshalLogObject(encoder zapcore.ObjectEncoder) error

type APITokenStore

type APITokenStore interface {
	Get(ctx context.Context) (*APITokenInfo, error)
	Set(ctx context.Context, token *APITokenInfo) error

	fmt.Stringer
}

type Client

type Client interface {
	GetAPITokenInfo(ctx context.Context) (*APITokenInfo, error)

	GraphQLQuery(ctx context.Context, document string, opts ...GraphQLOption) (*pbgraphql.Response, error)
	GraphQLSubscription(ctx context.Context, document string, opts ...GraphQLOption) (GraphQLStream, error)
}

func NewClient

func NewClient(network string, apiKey string, opts ...ClientOption) (Client, error)

type ClientOption

type ClientOption interface {
	// contains filtered or unexported methods
}

func WithAPITokenStore

func WithAPITokenStore(store APITokenStore) ClientOption

func WithAuthURL

func WithAuthURL(authURL string) ClientOption

func WithGRPCPort

func WithGRPCPort(port int) ClientOption

WithGRPCPort is an option that can be used to overidde all heuristics performed by the client to infer the gRPC port to use based on the network.

func WithInsecure

func WithInsecure() ClientOption

WithInsecure is an option that can be used to notify the client that it should use an insecure TLS connection for gRPC calls. This option effectively skips all TLS certificate validation normally performed.

This option is mutually exclusive with `WithPlainText` and resets it's value to the default value which is `false`.

func WithLogger

func WithLogger(logger *zap.Logger) ClientOption

func WithPlainText

func WithPlainText() ClientOption

WithPlainText is an option that can be used to notify the client that it should use a plain text connection (so non-TLS) for gRPC calls.

This option is mutually exclusive with `WithInsecure` and resets it's value to the default value which is `false`.

func WithoutAuthentication

func WithoutAuthentication() ClientOption

WithoutAuthentication disables API token retrieval and management assuming the endpoint connecting to does not require authentication.

type ExperimentalClient

type ExperimentalClient interface {
	RawGraphQL(ctx context.Context, document string, opts ...GraphQLOption) (pbgraphql.GraphQL_ExecuteClient, error)
}

ExperimentalClient is an interface implemented by the client you received when doing `NewClient` but the method in there are **experimental**, the API could change or removed at any moment.

There is not backward compatibility policy for those methods.

type FileAPITokenStore

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

FileAPITokenStore saves the active token as a JSON string in plain text in the given file.

func NewFileAPITokenStore

func NewFileAPITokenStore(filePath string) *FileAPITokenStore

NewFileAPITokenStore creates a new FileAPITokenStore instance using the given `filePath`.

func (*FileAPITokenStore) Get

func (s *FileAPITokenStore) Get(ctx context.Context) (*APITokenInfo, error)

func (*FileAPITokenStore) Set

func (s *FileAPITokenStore) Set(ctx context.Context, token *APITokenInfo) error

func (*FileAPITokenStore) String

func (s *FileAPITokenStore) String() string

type GraphQLDocument

type GraphQLDocument interface {
	Load(ctx context.Context) (string, error)
}

type GraphQLFileDocument

type GraphQLFileDocument string

func (GraphQLFileDocument) Load

func (d GraphQLFileDocument) Load(ctx context.Context) (string, error)

type GraphQLOption

type GraphQLOption interface {
	// contains filtered or unexported methods
}

type GraphQLStream

type GraphQLStream interface {
	pbgraphql.GraphQL_ExecuteClient
}

type GraphQLStringDocument

type GraphQLStringDocument string

func (GraphQLStringDocument) Load

func (d GraphQLStringDocument) Load(ctx context.Context) (string, error)

type GraphQLVariables

type GraphQLVariables map[string]interface{}

GraphQLVariables option to pass

type InMemoryAPITokenStore

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

InMemoryAPITokenStore simply keeps the token in memory and serves it from there.

It is **never** persisted and will be reset upon restart of the process process, leading to a new token being issued.

You should try hard to use a persistent solution so that you re-use the same token as long as it's valid.

func NewInMemoryAPITokenStore

func NewInMemoryAPITokenStore() *InMemoryAPITokenStore

func (*InMemoryAPITokenStore) Get

func (s *InMemoryAPITokenStore) Get(ctx context.Context) (*APITokenInfo, error)

func (*InMemoryAPITokenStore) Set

func (s *InMemoryAPITokenStore) Set(ctx context.Context, token *APITokenInfo) error

func (*InMemoryAPITokenStore) String

func (s *InMemoryAPITokenStore) String() string

type OnDiskAPITokenStore

type OnDiskAPITokenStore struct {
	FileAPITokenStore
}

OnDiskAPITokenStore saves the active token as a JSON string in a file located at `~/.dfuse/<sha256-api-key>/token.json`.

The directory structure is created when it does not exists.

func NewOnDiskAPITokenStore

func NewOnDiskAPITokenStore(apiKey string) *OnDiskAPITokenStore