jsonball

README

JSONball

JSONball is here to trigger actions based on changes of given JSON documents. It follows an even driven approach, where one change triggers an action that might trigger another change ... like a growing snowball rolling down a hill. In the end you have a possible large accumulated change across many different documents.

Why the name

The name is based of the snowball effect. A tiny snowball (or here change) can cause a chain reaction of changes. The little initial snowball/change can grow to a large one.

I struggled whether I name the project "JSONball" or "JSNOball". I quite like "JSNOball", because JSON has a quite silent "O" and snowball as quite silent "w" (non native speaker, sorry if I'm wrong here). You could read "JSNOball" as "J snoball" or "JSN snoball" -> JSON snowball. But because JSONball and JSNOball are basically typo variants of each other ... I went for JSONball. By the way, try to type "JSNOball" - you will (like I did) most of the time write JSONball. Well, we are devs, we write JSON multiple times a day :) And if we are honest, JSONball sounds nice, as well.

Documentation

Index

• Variables
• type Change
• type DocOps
• type DocumentList
• type Registry

Variables

var ErrDocumentNotExist = errors.New("document does not exist")

ErrDocumentNotExist indicates that an operation failed because a given document does not exist.

Types

type Change

type Change struct {
	Document string
}

Change represents a given change

type DocOps

type DocOps interface {
	// IsNew tells wether this doc was created because it got
	// opened now.
	IsNew() bool

	// Document returns the current json document.
	Document() string

	// Change updates the document and implicitely closes the document.
	Change(change Change) error

	// Refresh marks the document as recently re-checked for changes,
	// but no changes where found. Implicitely closes the document.
	Refresh() error

	// Close closes the document.
	Close() error
}

DocOps handles the operations possible on an opened document

type DocumentList

type DocumentList struct {
	Documents []string
	NextToken string
}

DocumentList is the result of a ListDocuments operation

type Registry

type Registry interface {
	// OpenDocument opens a new or existing document to update it.
	// To simply read a document use GetDocument instead.
	OpenDocument(ctx context.Context, docType, name string) (DocOps, error)

	// GetDocument returns the current latest version
	// Note: Currently running "PutDocument" operation
	// will not affect this method. This method is NOT blocked
	// by a running "PutDocument" method. But it is not guaranteed, that
	// this document is the actual latest Version! It is possible that
	// the upstream system change the doc, but that change was not yet
	// published to and processed by the registry.
	GetDocument(ctx context.Context, docType, name string) (string, error)

	// GetNewDocHanders returns all handlers that should be triggered for a given
	// document type. This function is used to determin which listerns should be automatically
	// generated if a new document was created.
	GetNewDocHanders(ctx context.Context, docType string) ([]string, error)

	// GetHandlerQueueURL returns the SQS queue URL. This func is called
	// if a change for a given handler was found.
	GetHandlerQueueURL(ctx context.Context, handler string) (string, error)

	// Registers a document type in the registry
	RegisterDocumentType(ctx context.Context, docType string) error

	// RegisterHandler registers a new handler
	RegisterHandler(ctx context.Context, handler *event.RegisterHandler) error

	// ListDocuments lists documents of a given type. With the parameter startToken pagination is
	// possible. Either startToken is empty or the value of "NextToken" of a previous list operation.
	// Note: There is no guarantee that documents are listed which were created after the NextToken
	// was build. They might be listed or might not be.
	ListDocuments(ctx context.Context, docType, startToken string, maxDocs uint16) (*DocumentList, error)

	// HandlerNewDoc registers or de-registers that a handler should
	// trigger for a new document of given type.
	HandlerNewDoc(ctx context.Context, handler, docType string, register bool) error
}

Registry provides backend features to store documents and handles.