golongpoll

type AddOn interface {
	// OnLongpollStart is called from StartLongpoll() before LongpollManager's
	// run goroutine starts. This should return a channel of events to
	// pre-populate within the manager. If Options.EventTimeToLiveSeconds
	// is set, then events that already too old will be skipped.
	// AddOn implementers can provide their own pre-filtering of events
	// based on the TTL for efficiency to avoid sending expired events on
	// this channel in the first place.
	//
	// The AddOn must close the returned channel when it is done sending
	// initial events to it as the LongpollManager will read from the
	// channel until it is closed. The LongpollManager's main goroutine
	// will not launch until after all data is read from this channel.
	// NOTE: if an AddOn does not wish to pre-populate any events, then
	// simply return an empty channel that is already closed.
	//
	// IMPORTANT: the events sent to the returned channel must be in
	// chronological order! The longpoll manager will panic if events are sent
	// out of order. The reason for this is that the longpoll manager
	// does not have to sort published events internally since publishing
	// happens in real time. The fact that events from Publish naturally
	// have chronological timestamps allows for many efficiencies and
	// simplifications.
	OnLongpollStart() <-chan *Event

	// OnPublish will be called with any event published by the LongpollManager.
	// Note that the manager blocks on this function completing, so if
	// an AddOn is going to perform any slow operations like a file write,
	// database insert, or a network call, then it should do so it a separate
	// goroutine to avoid blocking the manager. See FilePersistorAddOn for an
	// example of how OnPublish can do its work in its own goroutine.
	OnPublish(*Event)

	// OnShutdown will be called on LongpollManager.Shutdown().
	// AddOns can perform any cleanup or flushing before exit.
	// The LongpollManager will block on this function during shutdown.
	// Example use: FilePersistorAddOn will flush any buffered file write data
	// to disk on shutdown.
	OnShutdown()
}

type Event struct {
	// Timestamp is milliseconds since epoch to match javascrits Date.getTime().
	// This is the timestamp when the event was published.
	Timestamp int64 `json:"timestamp"`
	// Category this event belongs to. Clients subscribe to a given category.
	Category string `json:"category"`
	// Event data payload.
	// NOTE: Data can be anything that is able to passed to json.Marshal()
	Data interface{} `json:"data"`
	// Event ID, used in conjunction with Timestamp to get a complete timeline
	// of event data as there could be more than one event with the same timestamp.
	ID uuid.UUID `json:"id"`
}

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

type LongpollManager struct {

	// SubscriptionHandler is an Http handler function that can be served
	// directly or wrapped within another handler function that adds additional
	// behavior like authentication or business logic.
	SubscriptionHandler func(w http.ResponseWriter, r *http.Request)
	// PublishHandler is an Http handler function that can be served directly
	// or wrapped within another handler function that adds additional
	// behavior like authentication or business logic. If one does not want
	// to expose the PublishHandler, and instead only publish via
	// LongpollManager.Publish(), then simply don't serve this handler.
	// NOTE: this default publish handler does not enforce anything like what
	// category or data is allowed. It is entirely permissive by default.
	// For more production-type uses, wrap this with a http handler that
	// limits what can be published.
	PublishHandler func(w http.ResponseWriter, r *http.Request)
	// contains filtered or unexported fields
}

type Options struct {
	// Whether or not to print non-error logs about longpolling.
	// Useful mainly for debugging, defaults to false.
	// NOTE: this will log every event's contents which can be spammy!
	LoggingEnabled bool

	// Max client timeout seconds to be accepted by the SubscriptionHandler
	// (The 'timeout' HTTP query param).  Defaults to 110.
	// NOTE: if serving behind a proxy/webserver, make sure the max allowed
	// timeout here is less than that server's configured HTTP timeout!
	// Typically, servers will have a 60 or 120 second timeout by default.
	MaxLongpollTimeoutSeconds int

	// How many events to buffer per subscriptoin category before discarding
	// oldest events due to buffer being exhausted.  Larger buffer sizes are
	// useful for high volumes of events in the same categories.  But for
	// low-volumes, smaller buffer sizes are more efficient.  Defaults to 250.
	MaxEventBufferSize int

	// How long (seconds) events remain in their respective category's
	// eventBuffer before being deleted. Deletes old events even if buffer has
	// the room.  Useful to save space if you don't need old events.
	// You can use a large MaxEventBufferSize to handle spikes in event volumes
	// in a single category but have a relatively short EventTimeToLiveSeconds
	// value to save space in the more common low-volume case.
	// Defaults to infinite/forever TTL.
	EventTimeToLiveSeconds int

	// Whether or not to delete an event as soon as it is retrieved via an
	// HTTP longpoll.  Saves on space if clients only interested in seeing an
	// event once and never again.  Meant mostly for scenarios where events
	// act as a sort of notification and each subscription category is assigned
	// to a single client.  As soon as any client(s) pull down this event, it's
	// gone forever.  Notice how multiple clients can get the event if there
	// are multiple clients actively in the middle of a longpoll when a new
	// event occurs.  This event gets sent to all listening clients and then
	// the event skips being placed in a buffer and is gone forever.
	DeleteEventAfterFirstRetrieval bool

	// Optional add-on to add behavior like event persistence to longpolling.
	AddOn AddOn
}

type PublishData struct {
	Category string      `json:"category"`
	Data     interface{} `json:"data"`
}

type TrivialAddOn struct{}