ensign

package module
v0.7.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 31, 2023 License: BSD-3-Clause Imports: 23 Imported by: 22

README

Ensign Go SDK

Go Reference Go Report Card CI

Welcome to go-ensign!

This repository contains the Ensign driver, SDK, and helpers for Go. For the main ensign repo, go here. We also have SDKs for Javascript and Python.

The getting started guide and general documentation can be found at https://ensign.rotational.dev. You may also want to reference the GoDoc Package Documentation as well.

Quickstart

To add the Go SDK as a dependency, either go get it or import it and run go mod tidy:

$ go get github.com/rotationalio/go-ensign

The Go SDK provides a client that is able to connect to an Ensign system in order to manage topics, publish events, and subscribe to an event stream. At a minimum, you need API credentials, which can be obtained by creating an account at https://rotational.app. Once you've created an account and downloaded your credentials, you can instantiate a new Ensign client and check to make sure you're connected:

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/rotationalio/go-ensign"
)

func main() {
	client, err := ensign.New(ensign.WithCredentials("CLIENT ID", "CLIENT SECRET"))
	if err != nil {
		log.Fatal(err)
	}

	status, err := client.Status(context.Background())
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("%+v\n", status)
}

You can also set the $ENSIGN_CLIENT_ID and $ENSIGN_CLIENT_SECRET environment variables so that you can instantiate the Client without specifying credentials in code. Finally, if you downloaded the client.json file from the app; you can load it by specifying the path to the JSON file:

client, err := ensign.New(ensign.WithLoadCredentials("path/to/client.json"))

Documentation

Index

Constants

View Source 
const (
	EnvEndpoint     = "ENSIGN_ENDPOINT"
	EnvClientID     = "ENSIGN_CLIENT_ID"
	EnvClientSecret = "ENSIGN_CLIENT_SECRET"
	EnvInsecure     = "ENSIGN_INSECURE"
	EnvAuthURL      = "ENSIGN_AUTH_URL"
	EnvNoAuth       = "ENSIGN_NO_AUTHENTICATION"
)

Environment variables for configuring Ensign.

View Source 
const (
	EnsignEndpoint = "ensign.rotational.app:443"
	AuthEndpoint   = "https://auth.rotational.app"
)

Default connection endpoints to the production Ensign cluster.

View Source 
const (
	VersionMajor         = 0
	VersionMinor         = 7
	VersionPatch         = 0
	VersionReleaseLevel  = "beta"
	VersionReleaseNumber = 5
)

Version component constants for the current build.

View Source 
const DefaultPageSize uint32 = 100
View Source 
const (
	ReconnectTick = 750 * time.Millisecond
)

Variables

View Source 
var (
	ErrMissingEndpoint     = errors.New("invalid options: endpoint is required")
	ErrMissingClientID     = errors.New("invalid options: client ID is required")
	ErrMissingClientSecret = errors.New("invalid options: client secret is required")
	ErrMissingAuthURL      = errors.New("invalid options: auth url is required")
	ErrMissingMock         = errors.New("invalid options: in testing mode a mock grpc server is required")
	ErrTopicNameNotFound   = errors.New("topic name not found in project")
	ErrCannotAck           = errors.New("cannot ack or nack an event not received from subscribe")
	ErrOverwrite           = errors.New("this operation would overwrite existing event data")
)
View Source 
var GitVersion string

Set the GitVersion via -ldflags="-X 'github.com/rotationalio/go-ensign.GitVersion=$(git rev-parse --short HEAD)'"

Functions

func Version added in v0.7.0 

func Version() string

Version returns the semantic version for the current build.

Types

type Client 

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

Client manages the credentials and connection to the Ensign server.

func New 

func New(opts ...Option) (client *Client, err error)

func (*Client) ArchiveTopic added in v0.5.1 

func (c *Client) ArchiveTopic(ctx context.Context, topicID string) (err error)

Archive a topic marking it as read-only.

func (*Client) Close 

func (c *Client) Close() (err error)

func (*Client) ConnState added in v0.7.0 

func (c *Client) ConnState() connectivity.State

Conn state returns the connectivity state of the underlying gRPC connection.

Experimental: this method relies on an experimental gRPC API that could be changed.

func (*Client) CreateTopic added in v0.5.1 

func (c *Client) CreateTopic(ctx context.Context, topic string) (_ string, err error)

Create topic with the specified name and return the topic ID if there was no error.

func (*Client) DestroyTopic added in v0.5.1 

func (c *Client) DestroyTopic(ctx context.Context, topicID string) (err error)

Destroy a topic removing it and all of its data.

func (*Client) EnsignClient added in v0.5.1 

func (c *Client) EnsignClient() api.EnsignClient

func (*Client) Info added in v0.7.0 

func (c *Client) Info(ctx context.Context, topicIDs ...string) (info *api.ProjectInfo, err error)

Info returns summary statistics that describe the state of the project that you can connect to with your API key. Statistics include the number of topics, the number topics that are readonly (a subset of the number of topics) and the number of events. The project for the statistics is determined by the project your API key has access to (API keys are issued to projects). You can also specify a list of topicIDs to get the statistics for (e.g. filtering the statistics for one or more topics).

TODO: allow users to specify either topic names or topic IDs.

func (*Client) ListTopics added in v0.5.1 

func (c *Client) ListTopics(ctx context.Context) (topics []*api.Topic, err error)

func (*Client) Publish 

func (c *Client) Publish(topic string, events ...*Event) (err error)

func (*Client) PublishStream added in v0.7.0 

func (c *Client) PublishStream(ctx context.Context, opts ...grpc.CallOption) (api.Ensign_PublishClient, error)

func (*Client) QuarterdeckClient added in v0.5.1 

func (c *Client) QuarterdeckClient() *auth.Client

func (*Client) Status added in v0.7.0 

func (c *Client) Status(ctx context.Context) (state *api.ServiceState, err error)

func (*Client) Subscribe 

func (c *Client) Subscribe(topics ...string) (sub *Subscription, err error)

func (*Client) SubscribeStream added in v0.7.0 

func (c *Client) SubscribeStream(ctx context.Context, opts ...grpc.CallOption) (api.Ensign_SubscribeClient, error)

func (*Client) TopicExists added in v0.5.1 

func (c *Client) TopicExists(ctx context.Context, topicName string) (_ bool, err error)

Check if a topic with the specified name exists in the project or not.

func (*Client) TopicID added in v0.5.1 

func (c *Client) TopicID(ctx context.Context, topicName string) (_ string, err error)

Find a topic ID from a topic name. TODO: automate and cache this on the client for easier lookups.

func (*Client) WaitForConnStateChange added in v0.7.0 

func (c *Client) WaitForConnStateChange(ctx context.Context, sourceState connectivity.State) bool

Wait for the state of the underlying gRPC connection to change from the source state (not to the source state) or until the context times out. Returns true if the source state has changed to another state.

Experimental: this method relies on an experimental gRPC API that could be changed.

func (*Client) WaitForReconnect added in v0.7.0 

func (c *Client) WaitForReconnect(ctx context.Context) bool

WaitForReconnect checks if the connection has been reconnected periodically and retruns true when the connection is ready. If the context deadline timesout before a connection can be re-established, false is returned.

Experimental: this method relies on an experimental gRPC API that could be changed.

func (*Client) WithCallOptions added in v0.7.0 

func (c *Client) WithCallOptions(opts ...grpc.CallOption) *Client

WithCallOptions configures the next client Call to use the specified call options, after the call, the call options are removed. This method returns the Client pointer so that you can easily chain a call e.g. client.WithCallOptions(opts...).ListTopics() -- this ensures that we don't have to pass call options in to each individual call. Ensure that the clone of the client is discarded and garbage collected after use; the clone cannot be used to close the connection or fetch the options.

Experimental: call options and thread-safe cloning is an experimental feature and its signature may be subject to change in the future.

type Errorer 

type Errorer interface {
	Err() error
}

type Event added in v0.7.0 

type Event struct {
	// Metadata are user-defined key/value pairs that can be optionally added to an
	// event to store/lookup data without unmarshaling the entire payload.
	Metadata Metadata

	// Data is the datagram payload that defines the event.
	Data []byte

	// Mimetype describes how to parse the event datagram.
	Mimetype mimetype.MIME

	// Type defines the schema of the event datagram and is optional.
	Type *api.Type

	// Created is the timestamp that the event was created according to the client clock.
	Created time.Time
	// contains filtered or unexported fields
}

Events wrap user-defined datagrams that are totally ordered by the Ensign platform. Publishers create events with arbitrary data and send them to Ensign so that they can be sent to Subscribers awaiting the events or queried using EnSQL for later consumption. The datagram the event wraps is user-specific. It can be JSON, msgpack, text data, parquet, protocol buffers, etc. Applications should define event types using the Ensign schema registry and use those types to create events to publish and subscribe/query from.

func (*Event) Ack added in v0.7.0 

func (e *Event) Ack() (bool, error)

Ack allows a user to acknowledge back to the Ensign server that an event received by a subscription stream has been successfully consumed. For consumer groups that have exactly-once or at-least-once semantics, this signals the message has been delivered successfully so as to not trigger a redelivery of the message to another consumer. Ack does not block and returns true if already acked. If a nack was sent before ack, then this method returns false. If this event was not received on a subscribe stream then an error is returned.

func (*Event) Acked added in v0.7.0 

func (e *Event) Acked() (bool, error)

Acked allows a user to check if an event published to an event stream has been successfully received by the server.

func (*Event) Clone added in v0.7.0 

func (e *Event) Clone() *Event

Clone the event, resetting its state and removing acks, nacks, created timestamp and context. Useful for resending events or for duplicating an event to edit and publish.

func (*Event) Committed added in v0.7.0 

func (e *Event) Committed() time.Time

Returns the committed timestamp if available.

func (*Event) Context added in v0.7.0 

func (e *Event) Context() context.Context

Context returns the message context if set otherwise a background context.

func (*Event) Equals added in v0.7.0 

func (e *Event) Equals(o *Event) bool

Compare two events to determine if they are equivalent by data. See Same() to determine if they are the same event by offset/topic.

func (*Event) Err added in v0.7.0 

func (e *Event) Err() error

Err returns any error that occurred processing the event.

func (*Event) ID added in v0.7.0 

func (e *Event) ID() []byte

Returns the event ID if the event has been published; otherwise returns nil.

func (*Event) Info added in v0.7.0 

func (e *Event) Info() *api.EventWrapper

Returns the event wrapper which contains the API event info. Used for debugging.

func (*Event) Nack added in v0.7.0 

func (e *Event) Nack(code api.Nack_Code) (bool, error)

Nack allows a user to signal to the Ensign server that an event received by a subscription stream has not been successfully consumed. For consumer groups that have exactly-once or at-least-once semantics, this signals the message needs to be redelivered to another consumer.

Nack does not block and returns true if already nacked. If an ack was sent before the nack, then this method returns false. If this event was not received on a subscribe stream then an error is returned.

func (*Event) Nacked added in v0.7.0 

func (e *Event) Nacked() (bool, error)

Nacked allows a user to check if an event published to an event stream has errored or otherwise been rejected by the server.

func (*Event) Offset added in v0.7.0 

func (e *Event) Offset() (offset uint64, epoch uint64)

Returns the offset and epoch of the event if available, otherwise returns 0.

func (*Event) SetContext added in v0.7.0 

func (e *Event) SetContext(ctx context.Context)

SetContext provides an event context for use in the handling application.

func (*Event) TopicID added in v0.7.0 

func (e *Event) TopicID() []byte

Returns the topic ID that the event was published to if available; otherwise returns nil.

type Metadata added in v0.7.0 

type Metadata map[string]string

Metadata are user-defined key/value pairs that can be optionally added to an event to store/lookup data without unmarshaling the entire payload.

func (Metadata) Get added in v0.7.0 

func (m Metadata) Get(key string) string

Get returns the metadata value for the given key. If the key is not in the metadata an empty string is returned without an error.

func (Metadata) Set added in v0.7.0 

func (m Metadata) Set(key, value string)

Set a metadata value for the given key; overwrites existing keys.

type NackError added in v0.7.0 

type NackError struct {
	ID      []byte
	Code    api.Nack_Code
	Message string
}

func (*NackError) Error added in v0.7.0 

func (e *NackError) Error() string

type Option added in v0.7.0 

type Option func(o *Options) error

Option allows users to specify variadic options to create & connect the Ensign client.

func WithAuthenticator added in v0.7.0 

func WithAuthenticator(url string, noauth bool) Option

WithAuthenticator specifies a different Quarterdeck URL or you can supply an empty string and noauth set to true to have no authentication occur with the Ensign client.

func WithCredentials added in v0.7.0 

func WithCredentials(clientID, clientSecret string) Option

WithCredentials allows you to instantiate an Ensign client with API Key information.

func WithEnsignEndpoint added in v0.7.0 

func WithEnsignEndpoint(endpoint string, insecure bool, opts ...grpc.DialOption) Option

WithEnsignEndpoint allows you to specify an endpoint that is not the production Ensign cloud. This is useful if you're running an Ensign node in CI or connecting to a mock in local tests. Ensign developers may also use this to connect to staging. If any gRPC dial options are specified, they override the default Ensign dial options including the interceptors that perform authentication -- use only if you know what you're doing and why!

func WithLoadCredentials added in v0.7.0 

func WithLoadCredentials(path string) Option

WithLoadCredentials loads the Ensign API Key information from the JSON file that was download from the Rotational web application. Pass in the path to the credentials on disk to load them with this option!

func WithMock added in v0.7.0 

func WithMock(mock *mock.Ensign, opts ...grpc.DialOption) Option

WithMock connects ensign to the specified mock ensign server for local testing.

func WithOptions added in v0.7.0 

func WithOptions(opts Options) Option

WithOptions sets the options to the passed in options value. Note that this will override everything in the processing chain including zero-valued items; so use this as the first variadic option in NewOptions to guarantee correct processing.

type Options 

type Options struct {
	// The API Key credentials include the client ID and secret, both of which are
	// required to authenticate with Ensign via the authentication service so that an
	// access token can be retrieved and placed in all Ensign requests. The only time
	// these settings are not required is if NoAuthentication is true.
	ClientID     string
	ClientSecret string

	// The gRPC endpoint of the Ensign service; by default the EnsignEndpoint.
	Endpoint string

	// Dial options allows the user to specify gRPC connection options if necessary.
	// NOTE: use with care, this overrides the default dialing options including the
	// interceptors for authentication!
	Dialing []grpc.DialOption

	// The URL of the Quarterdeck system for authentication; by default AuthEndpoint.
	AuthURL string

	// If true, the client will not use TLS to connect to Ensign (default false).
	Insecure bool

	// If true, the client will not login with the api credentials and will omit access
	// tokens from Ensign RPCs. This is primarily used for testing against mocks.
	NoAuthentication bool

	// Mocking allows the client to be used in test code. Set testing mode to true and
	// create a *mock.Ensign to add to the dialer. Any other dialer options can also be
	// added to the mock for connection purposes.
	Testing bool
	Mock    *mock.Ensign
}

Options specifies the client configuration for authenticating and connecting to the Ensign service. The goal of the options struct is to be as minimal as possible. If users set their credentials via the environment, they should not have to specify any options at all to connect. The options does give the client flexibility to connect to Ensign nodes in other environments and is primarily for advanced usage.

func NewOptions added in v0.4.2 

func NewOptions(opts ...Option) (options Options, err error)

NewOptions instantiates an options object for configuring Ensign, sets defaults and loads missing options from the environment, then validates the options; returning an error if the options are incorrectly configured.

func (*Options) Validate 

func (o *Options) Validate() (err error)

Validate the options to make sure required configuration is set. This method also ensures that default values are set if a configuration is missing. For example, if the Endpoint is not set, this method first tries to set it from the environment, and then uses the default value as a last step.

type Subscription added in v0.7.0 

type Subscription struct {
	C <-chan *Event
	// contains filtered or unexported fields
}

func (*Subscription) Close added in v0.7.0 

func (c *Subscription) Close() error

Source Files

View all Source files

Directories

Path Synopsis
api
Package auth enables an Ensign client to authenticate with Ensign's Authn and Authz service called Quarterdeck.
 Package auth enables an Ensign client to authenticate with Ensign's Authn and Authz service called Quarterdeck.
mimetype
Package mock implements an in-memory gRPC mock Ensign server that can be connected to using a bufconn.
 Package mock implements an in-memory gRPC mock Ensign server that can be connected to using a bufconn.
region
Package stream provides
 Package stream provides

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.