binder

Documentation

Overview

Package binder - Defines the binder type, used for managing multiple clients of a single document, ensuring that operational transforms received are ordered and dispatched across all other clients. Also manages message broadcasting and session management for all client connections, as well as periodic flushing of changes to a document storage solution.

Index

• Variables
• type ClientMetadata
• type Config
  • func NewConfig() Config
• type Error
• type Portal
• type TransformSink
• type Type
  • func New(id string, block store.Type, config Config, errorChan chan<- Error, ...) (Type, error)

Variables

var (
	ErrReadOnlyPortal = errors.New("attempting to send transforms through a READ ONLY portal")
)

Errors for the binder portal type.

var (
	ErrTimeout = errors.New("timed out")
)

Errors used throughout the package.

Types

type ClientMetadata

type ClientMetadata struct {
	Client   interface{} `json:"client"`
	Metadata interface{} `json:"metadata"`
}

ClientMetadata - Clients can send metadata through a binder to be broadcast to all other clients. This metadata comes with the user metadata already associated with the sending client.

type Config

type Config struct {
	FlushPeriodMS           int64               `json:"flush_period_ms" yaml:"flush_period_ms"`
	RetentionPeriodS        int64               `json:"retention_period_s" yaml:"retention_period_s"`
	ClientKickPeriodMS      int64               `json:"kick_period_ms" yaml:"kick_period_ms"`
	CloseInactivityPeriodMS int64               `json:"close_inactivity_period_ms" yaml:"close_inactivity_period_ms"`
	OTBufferConfig          text.OTBufferConfig `json:"transform_buffer" yaml:"transform_buffer"`
}

Config - Holds configuration options for a binder.

func NewConfig

func NewConfig() Config

NewConfig - Returns a fully defined Binder configuration with the default values for each field.

type Error

type Error struct {
	ID  string
	Err error
}

Error - A binder has encountered a problem and needs to close. In order for this to happen it needs to inform its owner that it should be shut down. Error is a structure used to carry our error message and our ID over an error channel. An Error with the Err set to nil can be used as a graceful shutdown request.

type Portal

type Portal interface {
	// ClientMetadata - Returns the user identifying metadata associated with
	// this binder session.
	ClientMetadata() interface{}

	// BaseVersion - Returns the version of the binder as it was when this
	// session opened.
	BaseVersion() int

	// Document - Returns the document contents as it was when this session
	// opened.
	Document() store.Document

	// ReleaseDocument - Releases the cached document.
	ReleaseDocument()

	// TransformReadChan - Get the channel for reading transforms from other
	// binder clients.
	TransformReadChan() <-chan text.OTransform

	// MetadataReadChan - Get the channel for reading meta updates from other
	// binder clients.
	MetadataReadChan() <-chan ClientMetadata

	// SendTransform - Submits an operational transform to the document, this
	// call adds the transform to the stack of pending changes and broadcasts it
	// to all other connected clients. The transform must be submitted with the
	// target version (the version that the client believed it was, at the time
	// it was made), and the actual version is returned.
	SendTransform(ot text.OTransform, timeout time.Duration) (int, error)

	// SendMetadata - Broadcasts metadata out to all other connected clients.
	SendMetadata(metadata interface{})

	// Exit - Inform the binder that this client is shutting down, this call
	// will block until acknowledged by the binder. Therefore, you may specify a
	// timeout.
	Exit(timeout time.Duration)
}

Portal - An interface used by clients to contact a connected binder type.

type TransformSink

type TransformSink interface {
	// PushTransform - Process a newly received transform and return the
	// corrected version.
	PushTransform(ot text.OTransform) (text.OTransform, int, error)

	// IsDirty - Check whether the sink has uncommitted changes.
	IsDirty() bool

	// GetVersion - Returns the current version of the underlying transform
	// model
	GetVersion() int

	// FlushTransforms - apply all unapplied transforms to content and perform
	// any subsequent cleaning up of the transforms stack, transforms within
	// the secondsRetention period will be preserved for corrections. Returns a
	// bool indicating whether any changes were applied.
	FlushTransforms(content *string, secondsRetention int64) (bool, error)
}

TransformSink - A type that consumes transforms,

type Type

type Type interface {
	// ID - Returns the ID of this binder.
	ID() string

	// Subscribe - Register a new client as an editor of this binder document.
	// Metadata can be provided in order to identify submissions from the
	// client.
	Subscribe(metadata interface{}, timeout time.Duration) (Portal, error)

	// SubscribeReadOnly - Register a new client as a read only viewer of this
	// binder document.
	SubscribeReadOnly(metadata interface{}, timeout time.Duration) (Portal, error)

	// Close - Close the binder and shut down all clients, also flushes and
	// cleans up the document.
	Close()
}

Type - Provides thread safe implementations of binder and session creation.

func New

func New(
	id string,
	block store.Type,
	config Config,
	errorChan chan<- Error,
	log log.Modular,
	stats metrics.Type,
	auditor audit.Auditor,
) (Type, error)

New - Creates a binder targeting an existing document determined via an ID.