leaplib

package
v0.0.1 Latest Latest
Warning

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

Go to latest
Published: Jun 30, 2014 License: MIT Imports: 15 Imported by: 0

README

##package leaplib

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
  • More options for interacting with documents (delete, update, archive?)

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(title, description string) string

GenerateID - Create a unique ID for a document using a hash of the title, description, 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 {
}

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 (chan<- *BinderPortal)
	// 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() *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.

type BinderConfig

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

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 {
	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.

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.

type BinderRequest

type BinderRequest struct {
	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 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, 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.

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 {
	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'.

type DocumentStoreConfig

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

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) 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) 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{}, retention time.Duration) (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(id string) Model

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

type OModel

type OModel struct {
	DocID     string        `json:"docid"`
	Version   int           `json:"version"`
	Applied   []*OTransform `json:"applied"`
	Unapplied []*OTransform `json:"unapplied"`
}

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{}, retention time.Duration) (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 long 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 TokenAuthenticator

type TokenAuthenticator interface {
	AuthoriseCreate(token 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

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

func TokenAuthenticatorFactory

func TokenAuthenticatorFactory(config TokenAuthenticatorConfig) (TokenAuthenticator, error)

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

type TokenAuthenticatorConfig

type TokenAuthenticatorConfig struct {
	Type string `json:"type"`
}

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

func DefaultTokenAuthenticatorConfig

func DefaultTokenAuthenticatorConfig() TokenAuthenticatorConfig

DefaultTokenAuthenticatorConfig - Returns a default generic configuration.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL