Event Listener Extension APIs

The following can be found in package github.com/kwilteam/kwil-db/listeners.

ListenFunc

import (
    "context"
    "github.com/kwilteam/kwil-db/common"
)

// ListenFunc is a function that allows custom event listeners to be built
// with Kwil. The function is called when a node has come online,
// synced with the network, and is currently a validator. The
// function is expected to run for as long as the implementer wants
// the listener to continue running. The passed context will be
// canceled when the node is shutting down, or when it is no longer
// a validator. It is expected that any resources associated with
// the listener are cleaned up when the context is canceled. The
// function can be called many times if a node's validator status
// changes (e.g. becomes a validator, is removed as a validator, then
// becomes a validator again). The function can block indefinitely,
// but all resources should be cleaned up when the context is
// canceled to prevent memory leaks.
type ListenFunc func(ctx context.Context, service *common.Service, eventstore EventStore) error

EventStore

import (
    "context"
)

// EventStore is an interface that allows listeners to persist events,
// and track arbitrary metadata about its external source. It should
// be used to signal to the local Kwil node that the validator has
// seen an event, and that the event should be broadcast to the
// network. Events should be broadcast to the network using the
// Broadcast method. The KV store data is never forwarded to the
// network, and is simply for the convenience of the listener
// implementer to persist metadata about the data source.
type EventStore interface {
    // Broadcast broadcasts an event seen by the local node to the
    // network. The eventType is a string that identifies the network
    // should interpret the data. The eventType should directly
    // correspond to a "resolution" type, implemented in the
    // resolutions package. The data argument will be passed to the
    // resolution's ResolveFunc if enough nodes vote on the resolution.
    Broadcast(ctx context.Context, eventType string, data []byte) error

    // Set sets a key-value pair in the KV store. The data is scoped
    // to the local node, and is not broadcast to the network.
    Set(ctx context.Context, key []byte, value []byte) error
    // Get gets a value from the local node's KV store.
    Get(ctx context.Context, key []byte) ([]byte, error)
    // Delete deletes a value from the local node's KV store. The
    // data is scoped to the local node, and is not broadcast to the
    // network.
    Delete(ctx context.Context, key []byte) error
}