client

Documentation

Overview

Package client provides the client implementation of Yorkie. It is used to connect to the server and attach documents.

Index

• Variables
• type AttachOption
  • func WithPresence(presence innerpresence.Presence) AttachOption
• type AttachOptions
• type Attachment
• type AuthInterceptor
  • func NewAuthInterceptor(apiKey, token string) *AuthInterceptor
  • func (i *AuthInterceptor) Stream() grpc.StreamClientInterceptor
  • func (i *AuthInterceptor) Unary() grpc.UnaryClientInterceptor
• type Client
  • func Dial(rpcAddr string, opts ...Option) (*Client, error)
  • func New(opts ...Option) (*Client, error)
  • func (c *Client) Activate(ctx context.Context) error
  • func (c *Client) Attach(ctx context.Context, doc *document.Document, options ...AttachOption) error
  • func (c *Client) Close() error
  • func (c *Client) Deactivate(ctx context.Context) error
  • func (c *Client) Detach(ctx context.Context, doc *document.Document, options ...DetachOption) error
  • func (c *Client) Dial(rpcAddr string) error
  • func (c *Client) FindDocKey(docID string) (key.Key, error)
  • func (c *Client) ID() *time.ActorID
  • func (c *Client) IsActive() bool
  • func (c *Client) Key() string
  • func (c *Client) Remove(ctx context.Context, doc *document.Document) error
  • func (c *Client) Sync(ctx context.Context, options ...SyncOptions) error
  • func (c *Client) Watch(ctx context.Context, doc *document.Document) (<-chan WatchResponse, error)
• type DetachOption
  • func WithRemoveIfNotAttached() DetachOption
• type DetachOptions
• type Option
  • func WithAPIKey(apiKey string) Option
  • func WithCertFile(certFile string) Option
  • func WithKey(key string) Option
  • func WithLogger(logger *zap.Logger) Option
  • func WithMaxRecvMsgSize(maxRecvMsgSize int) Option
  • func WithServerNameOverride(serverNameOverride string) Option
  • func WithToken(token string) Option
• type Options
• type SyncOptions
  • func WithDocKey(k key.Key) SyncOptions
  • func (o SyncOptions) WithPushOnly() SyncOptions
• type WatchResponse
• type WatchResponseType

Variables

var (
	// ErrClientNotActivated occurs when an inactive client executes a function
	// that can only be executed when activated.
	ErrClientNotActivated = errors.New("client is not activated")

	// ErrDocumentNotAttached occurs when the given document is not attached to
	// this client.
	ErrDocumentNotAttached = errors.New("document is not attached")

	// ErrDocumentNotDetached occurs when the given document is not detached from
	// this client.
	ErrDocumentNotDetached = errors.New("document is not detached")

	// ErrUnsupportedWatchResponseType occurs when the given WatchResponseType
	// is not supported.
	ErrUnsupportedWatchResponseType = errors.New("unsupported watch response type")
)

Types

type AttachOption

type AttachOption func(*AttachOptions)

AttachOption configures AttachOptions.

func WithPresence

func WithPresence(presence innerpresence.Presence) AttachOption

WithPresence configures the presence of the client.

type AttachOptions

type AttachOptions struct {
	// Presence is the presence of the client.
	Presence innerpresence.Presence
}

AttachOptions configures how we set up the document.

type Attachment

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

Attachment represents the document attached.

type AuthInterceptor

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

AuthInterceptor is an interceptor for authentication.

func NewAuthInterceptor

func NewAuthInterceptor(apiKey, token string) *AuthInterceptor

NewAuthInterceptor creates a new instance of AuthInterceptor.

func (*AuthInterceptor) Stream

func (i *AuthInterceptor) Stream() grpc.StreamClientInterceptor

Stream creates a stream server interceptor for authorization.

func (*AuthInterceptor) Unary

func (i *AuthInterceptor) Unary() grpc.UnaryClientInterceptor

Unary creates a unary server interceptor for authorization.

type Client

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

Client is a normal client that can communicate with the server. It has documents and sends changes of the document in local to the server to synchronize with other replicas in remote.

func Dial

func Dial(rpcAddr string, opts ...Option) (*Client, error)

Dial creates an instance of Client and dials the given rpcAddr.

func New

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

New creates an instance of Client.

func (*Client) Activate

func (c *Client) Activate(ctx context.Context) error

Activate activates this client. That is, it registers itself to the server and receives a unique ID from the server. The given ID is used to distinguish different clients.

func (*Client) Attach

func (c *Client) Attach(ctx context.Context, doc *document.Document, options ...AttachOption) error

Attach attaches the given document to this client. It tells the server that this client will synchronize the given document.

func (*Client) Close

func (c *Client) Close() error

Close closes all resources of this client.

func (*Client) Deactivate

func (c *Client) Deactivate(ctx context.Context) error

Deactivate deactivates this client.

func (*Client) Detach

func (c *Client) Detach(ctx context.Context, doc *document.Document, options ...DetachOption) error

Detach detaches the given document from this client. It tells the server that this client will no longer synchronize the given document.

To collect garbage things like CRDT tombstones left on the document, all the changes should be applied to other replicas before GC time. For this, if the document is no longer used by this client, it should be detached.

func (*Client) Dial

func (c *Client) Dial(rpcAddr string) error

Dial dials the given rpcAddr.

func (*Client) FindDocKey

func (c *Client) FindDocKey(docID string) (key.Key, error)

FindDocKey returns the document key of the given document id.

func (*Client) ID

func (c *Client) ID() *time.ActorID

ID returns the ID of this client.

func (*Client) IsActive

func (c *Client) IsActive() bool

IsActive returns whether this client is active or not.

func (*Client) Key

func (c *Client) Key() string

Key returns the key of this client.

func (*Client) Remove

func (c *Client) Remove(ctx context.Context, doc *document.Document) error

Remove removes the given document.

func (*Client) Sync

func (c *Client) Sync(ctx context.Context, options ...SyncOptions) error

Sync pushes local changes of the attached documents to the server and receives changes of the remote replica from the server then apply them to local documents.

func (*Client) Watch

func (c *Client) Watch(
	ctx context.Context,
	doc *document.Document,
) (<-chan WatchResponse, error)

Watch subscribes to events on a given documentIDs. If an error occurs before stream initialization, the second response, error, is returned. If the context "ctx" is canceled or timed out, returned channel is closed, and "WatchResponse" from this closed channel has zero events and nil "Err()".

type DetachOption

type DetachOption func(*DetachOptions)

DetachOption configures DetachOptions.

func WithRemoveIfNotAttached

func WithRemoveIfNotAttached() DetachOption

WithRemoveIfNotAttached configures the removeIfNotAttached of the document.

type DetachOptions

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

DetachOptions configures how we set up the document.

type Option

type Option func(*Options)

Option configures Options.

func WithAPIKey

func WithAPIKey(apiKey string) Option

WithAPIKey configures the API key of the client.

func WithCertFile

func WithCertFile(certFile string) Option

WithCertFile configures the certificate file of the client.

func WithKey

func WithKey(key string) Option

WithKey configures the key of the client.

func WithLogger

func WithLogger(logger *zap.Logger) Option

WithLogger configures the Logger of the client.

func WithMaxRecvMsgSize

func WithMaxRecvMsgSize(maxRecvMsgSize int) Option

WithMaxRecvMsgSize configures the maximum message size in bytes the client can receive.

func WithServerNameOverride

func WithServerNameOverride(serverNameOverride string) Option

WithServerNameOverride configures the server name override of the client.

func WithToken

func WithToken(token string) Option

WithToken configures the token of the client.

type Options

type Options struct {
	// Key is the key of the client. It is used to identify the client.
	Key string

	// APIKey is the API key of the client.
	APIKey string

	// Token is the token of the client. Each request will be authenticated with this token.
	Token string

	// CertFile is the path to the certificate file.
	CertFile string

	// ServerNameOverride is the server name override.
	ServerNameOverride string

	// Logger is the Logger of the client.
	Logger *zap.Logger

	// MaxCallRecvMsgSize is the maximum message size in bytes the client can receive.
	MaxCallRecvMsgSize int
}

Options configures how we set up the client.

type SyncOptions

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

SyncOptions is an option for sync. It contains the key of the document to sync and the sync mode.

func WithDocKey

func WithDocKey(k key.Key) SyncOptions

WithDocKey creates a SyncOptions with the given document key.

func (SyncOptions) WithPushOnly

func (o SyncOptions) WithPushOnly() SyncOptions

WithPushOnly returns a SyncOptions with the sync mode set to PushOnly.

type WatchResponse

type WatchResponse struct {
	Type      WatchResponseType
	Presences map[string]innerpresence.Presence
	Err       error
}

WatchResponse is a structure representing response of Watch.

type WatchResponseType

type WatchResponseType string

WatchResponseType is type of watch response.

const (
	DocumentChanged   WatchResponseType = "document-changed"
	DocumentWatched   WatchResponseType = "document-watched"
	DocumentUnwatched WatchResponseType = "document-unwatched"
	PresenceChanged   WatchResponseType = "presence-changed"
	DocumentBroadcast WatchResponseType = "document-broadcast"
)

The values below are types of WatchResponseType.