gregor

README

Gregor

Gregor is a simple system for consuming, persisting, and broadcasting notifications to a collection of clients for a user.

Documents

• Design
• Architecture
• Code Organization

Repository Layout

• . — the top level interface to all major Gregor objects. Right now, it just contains an interface.
• storage/ — storage engines for persisting Gregor objects. Right now, only SQL is implemented.
• test/ — Test code that is used throughout
• protocol — AVDL files and output for generating protocol-friendly data types
  • protocol/avdl — AVDL inputs
  • protocol/go — Go outputs
• rpc/ — Code for managing and routing RPCs.

Documentation

Index

• type Body
• type Category
• type DeviceID
• type Dismissal
• type InBandMessage
• type InBandMsgType
• type Item
• type MainLoopServer
• type Message
• type MessageConsumer
• type MessageWithMetadata
• type Metadata
• type MsgID
• type MsgRange
• type NetworkInterface
• type NetworkInterfaceIncoming
• type NetworkInterfaceOutgoing
• type ObjFactory
• type OutOfBandMessage
• type State
• type StateMachine
• type StateSyncMessage
• type StateUpdateMessage
• type System
• type TimeOrOffset
• type UID
  • func UIDFromMessage(m Message) UID

Types

type Body

type Body interface {
	Bytes() []byte
}

type Category

type Category interface {
	String() string
}

type DeviceID

type DeviceID interface {
	Bytes() []byte
}

type Dismissal

type Dismissal interface {
	MsgIDsToDismiss() []MsgID
	RangesToDismiss() []MsgRange
}

type InBandMessage

type InBandMessage interface {
	MessageWithMetadata
	ToStateUpdateMessage() StateUpdateMessage
	ToStateSyncMessage() StateSyncMessage
	Merge(m1 InBandMessage) error
}

type InBandMsgType

type InBandMsgType int

const (
	InBandMsgTypeNone   InBandMsgType = 0
	InBandMsgTypeUpdate InBandMsgType = 1
	InBandMsgTypeSync   InBandMsgType = 2
)

type Item

type Item interface {
	MessageWithMetadata
	DTime() TimeOrOffset
	NotifyTimes() []TimeOrOffset
	Body() Body
	Category() Category
}

type MainLoopServer

type MainLoopServer interface {
	Serve(n net.Listener) error
}

type Message

type Message interface {
	ToInBandMessage() InBandMessage
	ToOutOfBandMessage() OutOfBandMessage
}

type MessageConsumer

type MessageConsumer interface {
	// ConsumeMessage is called on a new incoming message to mutate the state
	// of the state machine. Of course messages can be "inband" which actually
	// perform state mutations, or might be "out-of-band" that just use the
	// Gregor broadcast mechanism to make sure that all clients get the
	// notification.
	ConsumeMessage(m Message) error
}

MessageConsumer consumes state update messages. It's half of the state machine protocol

type MessageWithMetadata

type MessageWithMetadata interface {
	Metadata() Metadata
}

type Metadata

type Metadata interface {
	UID() UID
	MsgID() MsgID
	CTime() time.Time
	SetCTime(time.Time)
	DeviceID() DeviceID
	InBandMsgType() InBandMsgType
}

type MsgID

type MsgID interface {
	Bytes() []byte
}

type MsgRange

type MsgRange interface {
	EndTime() TimeOrOffset
	Category() Category
}

type NetworkInterface

type NetworkInterface interface {
	NetworkInterfaceOutgoing
	Serve(i NetworkInterfaceIncoming) error
}

type NetworkInterfaceIncoming

type NetworkInterfaceIncoming interface {
	ConsumeMessage(c context.Context, m Message) error
}

type NetworkInterfaceOutgoing

type NetworkInterfaceOutgoing interface {
	BroadcastMessage(c context.Context, m Message) error
}

type ObjFactory

type ObjFactory interface {
	MakeUID(b []byte) (UID, error)
	MakeMsgID(b []byte) (MsgID, error)
	MakeDeviceID(b []byte) (DeviceID, error)
	MakeBody(b []byte) (Body, error)
	MakeCategory(s string) (Category, error)
	MakeItem(u UID, msgid MsgID, deviceid DeviceID, ctime time.Time, c Category, dtime *time.Time, body Body) (Item, error)
	MakeDismissalByRange(uid UID, msgid MsgID, devid DeviceID, ctime time.Time, c Category, d time.Time) (InBandMessage, error)
	MakeDismissalByID(uid UID, msgid MsgID, devid DeviceID, ctime time.Time, d MsgID) (InBandMessage, error)
	MakeStateSyncMessage(uid UID, msgid MsgID, devid DeviceID, ctime time.Time) (InBandMessage, error)
	MakeState(i []Item) (State, error)
	MakeMetadata(uid UID, msgid MsgID, devid DeviceID, ctime time.Time, i InBandMsgType) (Metadata, error)
	MakeInBandMessageFromItem(i Item) (InBandMessage, error)
}

type OutOfBandMessage

type OutOfBandMessage interface {
	System() System
	UID() UID
	Body() Body
}

type State

type State interface {
	Items() ([]Item, error)
	ItemsInCategory(c Category) ([]Item, error)
}

type StateMachine

type StateMachine interface {
	MessageConsumer

	// State returns the state for the user u on device d at time t.
	// d can be nil, in which case the global state (across all devices)
	// is returned. If t is nil, then use Now, otherwise, return the state
	// at the given time.
	State(u UID, d DeviceID, t TimeOrOffset) (State, error)

	// InBandMessagesSince returns all messages since the given time
	// for the user u on device d.  If d is nil, then we'll return
	// all messages across all devices.  If d is a device, then we'll
	// return global messages and per-device messages for that device.
	InBandMessagesSince(u UID, d DeviceID, t TimeOrOffset) ([]InBandMessage, error)
}

StateMachine is the central interface of the Gregor system. Various parts of the server and client infrastructure will implement various parts of this interface, to ensure that the state machine can be replicated, and that it can be queried.

type StateSyncMessage

type StateSyncMessage interface {
	MessageWithMetadata
}

type StateUpdateMessage

type StateUpdateMessage interface {
	MessageWithMetadata
	Creation() Item
	Dismissal() Dismissal
}

type System

type System interface {
	String() string
}

type TimeOrOffset

type TimeOrOffset interface {
	Time() *time.Time
	Offset() *time.Duration
}

type UID

type UID interface {
	Bytes() []byte
}

func UIDFromMessage

func UIDFromMessage(m Message) UID