lib

package
v0.0.6 Latest Latest
Warning

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

 Go to latest Published: Oct 31, 2014 License: MIT Imports: 21 Imported by: 0

README

##package lib

Implements resources for creating and maintaining leaps documents, this includes the logic behind operational transforms and asynchronous document operations.

STATUS: INCOMPLETE

TODO:

  • Implementation of LeapLocator (curator) that maps a cluster of curators and acts as a network bridge.
  • More document storage solutions

Documentation

Index

Constants

View Source 
const (
	LeapError = 0
	LeapWarn  = 1
	LeapInfo  = 2
	LeapDebug = 3
)

Constants that define various log levels

Variables

This section is empty.

Functions

func GenerateID 

func GenerateID(content string) string

GenerateID - Create a unique ID for using a hash of a string, a timestamp and a pseudo random integer as a hex encoded string with the timestamp on the end.

func ParseDocumentContent 

func ParseDocumentContent(doctype string, content string) (interface{}, error)

ParseDocumentContent - Parse a string into a document content based on its type.

func SerializeDocumentContent 

func SerializeDocumentContent(doctype string, content interface{}) (string, error)

SerializeDocumentContent - Serialize the content of a document into a string, based on its type.

func ValidateDocument 

func ValidateDocument(doc *Document) error

ValidateDocument - validates that a given document has content that matches its type. If this isn't the case it will attempt to convert the content into the expected type, and failing that will return an error message.

Types

type Anarchy 

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

Anarchy - Most basic implementation of TokenAuthenticator, everyone has access to everything.

func (*Anarchy) AuthoriseCreate 

func (a *Anarchy) AuthoriseCreate(_, _ string) bool

AuthoriseCreate - Always returns true, because anarchy.

func (*Anarchy) AuthoriseJoin 

func (a *Anarchy) AuthoriseJoin(_, _ string) bool

AuthoriseJoin - Always returns true, because anarchy.

type Binder 

type Binder struct {
	ID            string
	SubscribeChan chan BinderSubscribeBundle
	// contains filtered or unexported fields
}

Binder - Contains a single document and acts as a broker between multiple readers, writers and the storage strategy.

func BindExisting 

func BindExisting(
	id string,
	block DocumentStore,
	config BinderConfig,
	errorChan chan<- BinderError,
	logger *LeapsLogger,
) (*Binder, error)

BindExisting - Creates a binder targeting a specific, existing document. Takes the id of the document along with the DocumentStore to acquire and store the document with.

func BindNew 

func BindNew(
	document *Document,
	block DocumentStore,
	config BinderConfig,
	errorChan chan<- BinderError,
	logger *LeapsLogger,
) (*Binder, error)

BindNew - Creates a binder around a new document. Requires a DocumentStore to store the document with. Returns the binder, the ID of the new document, and a potential error.

func (*Binder) Close 

func (b *Binder) Close()

Close - Close the binder, before closing the client channels the binder will flush changes and store the document.

func (*Binder) Subscribe 

func (b *Binder) Subscribe(token string) *BinderPortal

Subscribe - Returns a BinderPortal struct that allows a client to bootstrap and sync with the binder with the document content, current unapplied changes and channels for sending and receiving transforms. Accepts a string as a token for identifying the user, if left empty the token is generated.

Multiple clients can connect with the same token, however, these users will be treated as if the same client, therefore not receiving each others messages, cursor positions being overwritten and being kicked in unison.

type BinderClient 

type BinderClient struct {
	Token            string
	TransformSndChan chan<- interface{}
}

BinderClient - A struct representing a connected client held by a binder, contains a token for identification and a channel for broadcasting transforms and other data.

type BinderConfig 

type BinderConfig struct {
	FlushPeriod           int64       `json:"flush_period_ms"`
	RetentionPeriod       int64       `json:"retention_period_s"`
	ClientKickPeriod      int64       `json:"kick_period_ms"`
	CloseInactivityPeriod int64       `json:"close_inactivity_period_s"`
	ModelConfig           ModelConfig `json:"transform_model"`
}

BinderConfig - Holds configuration options for a binder.

func DefaultBinderConfig 

func DefaultBinderConfig() BinderConfig

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

type BinderError 

type BinderError struct {
	ID  string
	Err error
}

BinderError - 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. BinderError is a structure used to carry our error message and our ID over an error channel. A BinderError with the Err set to nil can be used as a graceful shutdown request.

type BinderPortal 

type BinderPortal struct {
	Token            string
	Document         *Document
	Version          int
	Error            error
	TransformRcvChan <-chan interface{}
	RequestSndChan   chan<- BinderRequest
}

BinderPortal - A container that holds all data necessary to begin an open portal with the binder, allowing fresh transforms to be submitted and returned as they come. Also carries the token of the client.

func (*BinderPortal) SendTransform 

func (p *BinderPortal) SendTransform(ot interface{}, timeout time.Duration) (int, error)

SendTransform - A helper function for submitting a transform to the binder. The binder responds with either an error or a corrected version number for the document at the time of your submission.

func (*BinderPortal) SendUpdate 

func (p *BinderPortal) SendUpdate(update interface{}, timeout time.Duration) error

SendUpdate - A helper function for submitting an update to the binder. The binder will return an error in the event of one.

type BinderRequest 

type BinderRequest struct {
	Token       string
	Transform   interface{}
	VersionChan chan<- int
	ErrorChan   chan<- error
}

BinderRequest - A container used to communicate with a binder, it holds a transform to be submitted to the document model. Two channels are used for return values from the request. VersionChan is used to send back the actual version of the transform submitted. ErrorChan is used to send errors that occur. Both channels must be non-blocking, so a buffer of 1 is recommended.

type BinderSubscribeBundle 

type BinderSubscribeBundle struct {
	Token         string
	PortalRcvChan chan<- *BinderPortal
}

BinderSubscribeBundle - A container that holds all data necessary to provide a binder that you wish to subscribe to. Contains a user token for identifying the client and a channel for receiving the resultant BinderPortal.

type Curator 

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

Curator - A structure designed to keep track of a live collection of Binders. Assists prospective clients in locating their target Binders, and when necessary creates new Binders.

func CreateNewCurator 

func CreateNewCurator(config CuratorConfig) (*Curator, error)

CreateNewCurator - Creates and returns a fresh curator, and launches its internal loop for monitoring Binder errors.

func (*Curator) Close 

func (c *Curator) Close()

Close - Shut the curator down, you must ensure that this library cannot be accessed after closing.

func (*Curator) FindDocument 

func (c *Curator) FindDocument(token string, id string) (*BinderPortal, error)

FindDocument - Locates an existing, or creates a fresh Binder for an existing document and returns that Binder for subscribing to. Returns an error if there was a problem locating the document.

func (*Curator) GetLogger 

func (c *Curator) GetLogger() *LeapsLogger

GetLogger - The curator generates a LeapsLogger that all other leaps components should write to. GetLogger returns a reference to the logger for components not generated by the curator itself.

func (*Curator) NewDocument 

func (c *Curator) NewDocument(token string, userID string, doc *Document) (*BinderPortal, error)

NewDocument - Creates a fresh Binder for a new document, which is subsequently stored, returns an error if either the document ID is already currently in use, or if there is a problem storing the new document. May require authentication, if so a userID is supplied.

type CuratorConfig 

type CuratorConfig struct {
	StoreConfig         DocumentStoreConfig      `json:"storage"`
	BinderConfig        BinderConfig             `json:"binder"`
	LoggerConfig        LoggerConfig             `json:"logger"`
	AuthenticatorConfig TokenAuthenticatorConfig `json:"authenticator"`
}

CuratorConfig - Holds configuration options for a curator.

func DefaultCuratorConfig 

func DefaultCuratorConfig() CuratorConfig

DefaultCuratorConfig - Returns a fully defined curator configuration with the default values for each field.

type Document 

type Document struct {
	ID          string      `json:"id"`
	Title       string      `json:"title"`
	Description string      `json:"description"`
	Type        string      `json:"type"`
	Content     interface{} `json:"content"`
}

Document - A representation of a leap document.

func CreateNewDocument 

func CreateNewDocument(title, description, doctype string, content interface{}) (*Document, error)

CreateNewDocument - Create a fresh leap document with a title, description, type and the initial content. We also validate here that the content type provided matches the type.

type DocumentStore 

type DocumentStore interface {
	Create(string, *Document) error
	Store(string, *Document) error
	Fetch(string) (*Document, error)
}

DocumentStore - Implemented by types able to acquire and store documents. This is abstracted in order to accommodate for multiple storage strategies. These methods should be asynchronous if possible.

func DocumentStoreFactory 

func DocumentStoreFactory(config DocumentStoreConfig) (DocumentStore, error)

DocumentStoreFactory - Returns a document store object based on a configuration object.

func GetFileStore 

func GetFileStore(config DocumentStoreConfig) (DocumentStore, error)

GetFileStore - Just a func that returns a FileStore

func GetMemoryStore 

func GetMemoryStore(config DocumentStoreConfig) (DocumentStore, error)

GetMemoryStore - Just a func that returns a MemoryStore

func GetMockStore 

func GetMockStore(config DocumentStoreConfig) (DocumentStore, error)

GetMockStore - returns a MemoryStore with a document already created for testing purposes. The document has the ID of the config value 'Name'.

func GetSQLStore 

func GetSQLStore(config DocumentStoreConfig) (DocumentStore, error)

GetSQLStore - Just a func that returns an SQLStore

type DocumentStoreConfig 

type DocumentStoreConfig struct {
	Type           string    `json:"type"`
	Name           string    `json:"name"`
	StoreDirectory string    `json:"store_directory"`
	SQLConfig      SQLConfig `json:"sql"`
}

DocumentStoreConfig - Holds generic configuration options for a document storage solution.

func DefaultDocumentStoreConfig 

func DefaultDocumentStoreConfig() DocumentStoreConfig

DefaultDocumentStoreConfig - Returns a default generic configuration.

type FileStore 

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

FileStore - Most basic persistent implementation of DocumentStore. Simple stores each document into a file within a configured directory.

func (*FileStore) Create 

func (s *FileStore) Create(id string, doc *Document) error

Create - Store document in a file location

func (*FileStore) Fetch 

func (s *FileStore) Fetch(id string) (*Document, error)

Fetch - Fetch document from its file location.

func (*FileStore) Store 

func (s *FileStore) Store(id string, doc *Document) error

Store - Store document in its file location.

type LeapsLogger 

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

LeapsLogger - A logger object configured along with leaps, which all leaps components log to.

func CreateLogger 

func CreateLogger(config LoggerConfig) *LeapsLogger

CreateLogger - Create a new logger.

func (*LeapsLogger) Close 

func (l *LeapsLogger) Close()

Close - Close the logger, a closed logger will no longer respond to requests for stats or log events and probably isn't even worth doing. I don't know why I wrote this. Help me.

func (*LeapsLogger) DecrementStat 

func (l *LeapsLogger) DecrementStat(path string)

DecrementStat - Decrement the integer value of a particular stat. If the stat doesn't yet exist it is created. Stats that are decremented are integer only, and this is enforced.

func (*LeapsLogger) GetStats 

func (l *LeapsLogger) GetStats(timeout time.Duration) (*string, error)

GetStats - Returns a string containing the JSON serialized structure of logger stats at the time of the request.

func (*LeapsLogger) IncrementStat 

func (l *LeapsLogger) IncrementStat(path string)

IncrementStat - Increment the integer value of a particular stat. If the stat doesn't yet exist it is created. Stats that are incremented are integer only, and this is enforced.

func (*LeapsLogger) Log 

func (l *LeapsLogger) Log(level int, prefix, message string)

Log - Log an event.

func (*LeapsLogger) SetStat 

func (l *LeapsLogger) SetStat(path string, value interface{})

SetStat - Sets a stat to whatever value you give it, it's currently up to the caller to ensure the value will be JSON serializable. Calls are made asynchronously and do not return errors or indications of success.

type LoggerConfig 

type LoggerConfig struct {
	LogLevel   int    `json:"level"`
	TargetPath string `json:"output_path"`
}

LoggerConfig - Holds configuration options for the global leaps logger.

func DefaultLoggerConfig 

func DefaultLoggerConfig() LoggerConfig

DefaultLoggerConfig - Returns a fully defined logger configuration with the default values for each field.

type MemoryStore 

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

MemoryStore - Most basic implementation of DocumentStore, simply keeps the document in memory. Has zero persistence across sessions.

func (*MemoryStore) Create 

func (s *MemoryStore) Create(id string, doc *Document) error

Create - Store document in memory.

func (*MemoryStore) Fetch 

func (s *MemoryStore) Fetch(id string) (*Document, error)

Fetch - Fetch document from memory.

func (*MemoryStore) Store 

func (s *MemoryStore) Store(id string, doc *Document) error

Store - Store document in memory.

type Model 

type Model interface {
	/* PushTransform - Push a single transform to our model, and if successful, return the updated
	 * transform along with the new version of the document.
	 */
	PushTransform(ot interface{}) (interface{}, int, error)

	/* FlushTransforms - apply all unapplied transforms to content, and delete old applied
	 * in accordance with our retention period. Returns a bool indicating whether any changes
	 * were applied, and an error in case a fatal problem was encountered.
	 */
	FlushTransforms(content *interface{}, secondsRetention int64) (bool, error)

	/* GetVersion - returns the current version of the document.
	 */
	GetVersion() int
}

Model - an interface that represents an internal operation transform model of a particular type. Initially text is the only supported transform model, however, the plan will eventually be to have different models for various types of document that should all be supported by our binder.

func CreateTextModel 

func CreateTextModel(config ModelConfig) Model

CreateTextModel - Returns a fresh transform model, with the version set to 1.

type ModelConfig 

type ModelConfig struct {
	MaxDocumentSize    uint64 `json:"max_document_size"`
	MaxTransformLength uint64 `json:"max_transform_length"`
}

ModelConfig - Holds configuration options for a transform model.

func DefaultModelConfig 

func DefaultModelConfig() ModelConfig

DefaultModelConfig - Returns a default ModelConfig.

type OModel 

type OModel struct {
	Version   int          `json:"version"`
	Applied   []OTransform `json:"applied"`
	Unapplied []OTransform `json:"unapplied"`
	// contains filtered or unexported fields
}

OModel - A representation of the transform model surrounding a document session. This keeps track of changes submitted and recently applied in order to distribute those changes to clients.

func (*OModel) FlushTransforms 

func (m *OModel) FlushTransforms(contentBoxed *interface{}, secondsRetention int64) (bool, error)

FlushTransforms - apply all unapplied transforms and append them to the applied stack, then remove old entries from the applied stack. Accepts retention as an indicator for how many seconds applied transforms should be retained. Returns a bool indicating whether any changes were applied.

func (*OModel) GetVersion 

func (m *OModel) GetVersion() int

GetVersion - returns the current version of the document.

func (*OModel) PushTransform 

func (m *OModel) PushTransform(otBoxed interface{}) (interface{}, int, error)

PushTransform - Inserts a transform onto the unapplied stack and increments the version number of the document. Whilst doing so it fixes the transform in relation to earlier transforms it was unaware of, this fixed version gets sent back for distributing across other clients.

type OTransform 

type OTransform struct {
	Position  int    `json:"position"`
	Delete    int    `json:"num_delete"`
	Insert    string `json:"insert"`
	Version   int    `json:"version"`
	TReceived int64  `json:"received,omitempty"`
}

OTransform - A representation of a transformation relating to a leap document. This can either be a text addition, a text deletion, or both.

type RedisAuthenticator 

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

RedisAuthenticator - A wrapper around the Redis client that acts as an authenticator.

func CreateRedisAuthenticator 

func CreateRedisAuthenticator(config TokenAuthenticatorConfig, logger *LeapsLogger) *RedisAuthenticator

CreateRedisAuthenticator - Creates a RedisAuthenticator using the provided configuration.

func (*RedisAuthenticator) AuthoriseCreate 

func (s *RedisAuthenticator) AuthoriseCreate(token, userID string) bool

AuthoriseCreate - Checks whether a specific key exists in Redis and that the value matches our user ID.

func (*RedisAuthenticator) AuthoriseJoin 

func (s *RedisAuthenticator) AuthoriseJoin(token, documentID string) bool

AuthoriseJoin - Checks whether a specific key exists in Redis and that the value matches a document ID.

func (*RedisAuthenticator) DeleteKey 

func (s *RedisAuthenticator) DeleteKey(key string) error

DeleteKey - Deletes an existing key.

func (*RedisAuthenticator) ReadKey 

func (s *RedisAuthenticator) ReadKey(key string) (string, error)

ReadKey - Simply return the value of a particular key, or an error.

type RedisAuthenticatorConfig 

type RedisAuthenticatorConfig struct {
	URL string `json:"url"`
}

RedisAuthenticatorConfig - A config object for the redis authentication object.

func DefaultRedisAuthenticatorConfig 

func DefaultRedisAuthenticatorConfig() RedisAuthenticatorConfig

DefaultRedisAuthenticatorConfig - Returns a default config object for a RedisAuthenticator.

type SQLConfig 

type SQLConfig struct {
	DSN         string      `json:"dsn"`
	TableConfig TableConfig `json:"db_table"`
}

SQLConfig - The configuration fields for an SQL document store solution.

func DefaultSQLConfig 

func DefaultSQLConfig() SQLConfig

DefaultSQLConfig - A default SQL configuration.

type SQLStore 

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

SQLStore - A document store implementation for an SQL database.

func (*SQLStore) Create 

func (m *SQLStore) Create(id string, doc *Document) error

Create - Create a new document in a database table.

func (*SQLStore) Fetch 

func (m *SQLStore) Fetch(id string) (*Document, error)

Fetch - Fetch document from a database table.

func (*SQLStore) Store 

func (m *SQLStore) Store(id string, doc *Document) error

Store - Store document in a database table.

type TableConfig 

type TableConfig struct {
	Name           string `json:"table"`
	IDCol          string `json:"id_column"`
	TitleCol       string `json:"title_column"`
	DescriptionCol string `json:"description_column"`
	TypeCol        string `json:"type_column"`
	ContentCol     string `json:"content_column"`
}

TableConfig - The configuration fields for specifying the table labels of the SQL database target.

func DefaultTableConfig 

func DefaultTableConfig() TableConfig

DefaultTableConfig - Default table configuration.

type TokenAuthenticator 

type TokenAuthenticator interface {
	AuthoriseCreate(token, userID string) bool
	AuthoriseJoin(token, documentID string) bool
}

TokenAuthenticator - Implemented by types able to validate tokens for editing or creating documents. This is abstracted in order to accommodate for multiple authentication strategies.

func GetAnarchy 

func GetAnarchy(config TokenAuthenticatorConfig) TokenAuthenticator

GetAnarchy - Get yourself a little taste of sweet, juicy anarchy.

func TokenAuthenticatorFactory 

func TokenAuthenticatorFactory(config TokenAuthenticatorConfig, logger *LeapsLogger) (TokenAuthenticator, error)

TokenAuthenticatorFactory - Returns a document store object based on a configuration object.

type TokenAuthenticatorConfig 

type TokenAuthenticatorConfig struct {
	Type        string                   `json:"type"`
	AllowCreate bool                     `json:"allow_creation"`
	RedisConfig RedisAuthenticatorConfig `json:"redis_config"`
}

TokenAuthenticatorConfig - Holds generic configuration options for a token based authentication solution.

func DefaultTokenAuthenticatorConfig 

func DefaultTokenAuthenticatorConfig() TokenAuthenticatorConfig

DefaultTokenAuthenticatorConfig - Returns a default generic configuration.

type UserUpdate 

type UserUpdate struct {
	Message  string `json:"message,omitempty"`
	Position *int64 `json:"position,omitempty"`
	Active   bool   `json:"active"`
	Token    string `json:"user_id"`
}

UserUpdate - A struct containing an update for a clients' status.

Source Files

View all Source files

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.