events

type Callbacks interface {

	// RegisterConnection can be fired as often as requied.
	// Dispatchers will be started against this connection for all persisted subscriptions that match via the supplied function.
	// It can be fired multiple times for the same connection ID, to update the subscription list
	// For a "connect-out" style plugin (MQTT/AMQP/JMS broker), you might fire it at startup (from Init) for each target queue, with a subscription match
	// For a "connect-in" style plugin (inbound WebSocket connections), you fire it every time the client application connects attaches to a subscription
	RegisterConnection(connID string, matcher SubscriptionMatcher) error

	// EphemeralSubscription creates an ephemeral (non-durable) subscription, and associates it with a connection
	EphemeralSubscription(connID, namespace string, filter *core.SubscriptionFilter, options *core.SubscriptionOptions) error

	// ConnectionClosed is a notification that a connection has closed, and all dispatchers should be re-allocated.
	// Note the plugin must not crash if it receives PublishEvent calls on the connID after the ConnectionClosed event is fired
	ConnectionClosed(connID string)

	// DeliveryResponse responds to a previous event delivery, to either:
	// - Acknowledge it: the offset for the associated subscription can move forwards
	//   * Note all gaps must fill before the offset can move forwards, so this message might still be redelivered if streaming ahead
	//   * If a message is included in the response, then that will be automatically sent with the correct CID
	// - Reject it: This resets the associated subscription back to the last committed offset
	//   * Note all message since the last committed offet will be redelivered, so additional messages to be redelivered if streaming ahead
	DeliveryResponse(connID string, inflight *core.EventDeliveryResponse)
}

type Capabilities struct{}

type Plugin interface {
	core.Named

	// InitConfig initializes the set of configuration options that are valid, with defaults. Called on all plugins.
	InitConfig(config config.Section)

	// Init initializes the plugin, with configuration
	// Returns the supported featureset of the interface
	Init(ctx context.Context, config config.Section, callbacks Callbacks) error

	// Capabilities returns capabilities - not called until after Init
	Capabilities() *Capabilities

	// ValidateOptions verifies a set of input options, prior to storage of a new subscription
	// The plugin can modify the core subscription options, such as overriding whether data is delivered.
	ValidateOptions(options *core.SubscriptionOptions) error

	// DeliveryRequest requests delivery of work on a connection, which must later be responded to
	// Data will only be supplied as non-nil if the subscription is set to include data
	DeliveryRequest(connID string, sub *core.Subscription, event *core.EventDelivery, data core.DataArray) error
}

type SubscriptionMatcher func(core.SubscriptionRef) bool