db

type AllocationInfo struct {
	ID     ids.AllocationID
	Limit  uint64
	Expiry time.Time
}

type BroadcastInfo struct {
	Broadcast *spb.Broadcast
	Sent      uint64
	Limit     uint64
}

type BroadcastStore interface {
	// CreateBroadcast stores a new broadcast message.
	CreateBroadcast(ctx context.Context, b *spb.Broadcast, limit uint64) error

	// SetBroadcastLimit adjusts the limit of an existing broadcast.
	SetBroadcastLimit(ctx context.Context, id ids.BroadcastID, limit uint64) error

	// SaveBroadcastMessage saves a new broadcast message.
	SaveBroadcastMessage(ctx context.Context, msg *fspb.Message, bid ids.BroadcastID, cid common.ClientID, aid ids.AllocationID) error

	// ListActiveBroadcasts lists broadcasts which could be sent to some
	// client.
	ListActiveBroadcasts(ctx context.Context) ([]*BroadcastInfo, error)

	// ListSentBroadcasts returns identifiers for those broadcasts which have already been sent to a client.
	ListSentBroadcasts(ctx context.Context, id common.ClientID) ([]ids.BroadcastID, error)

	// CreateAllocation creates an allocation for a given Broadcast,
	// reserving frac of the unallocated broadcast limit until
	// expiry. Return nil if there is no message allocation available.
	CreateAllocation(ctx context.Context, id ids.BroadcastID, frac float32, expiry time.Time) (*AllocationInfo, error)

	// CleanupAllocation deletes the identified allocation record and
	// updates the broadcast sent count according to the number that were
	// actually sent under the given allocation.
	CleanupAllocation(ctx context.Context, bid ids.BroadcastID, aid ids.AllocationID) error
}

type ClientData struct {
	Key    []byte        // The der encoded public key for the client.
	Labels []*fspb.Label // The client's labels.

	// Whether the client_id has been blacklisted. Once blacklisted any contact
	// from this client_id will result in an rekey request.
	Blacklisted bool
}

type ClientStore interface {
	// ListClients returns basic information about clients. If ids is empty, it
	// returns all clients.
	ListClients(ctx context.Context, ids []common.ClientID) ([]*spb.Client, error)

	// StreamClientIds streams the IDs of all available clients, optionally with last contact after a given timestamp.
	StreamClientIds(ctx context.Context, includeBlacklisted bool, lastContactAfter *time.Time, callback func(common.ClientID) error) error

	// GetClientData retrieves the current data about the client identified
	// by id.
	GetClientData(ctx context.Context, id common.ClientID) (*ClientData, error)

	// AddClient creates a new client.
	AddClient(ctx context.Context, id common.ClientID, data *ClientData) error

	// AddClientLabel records that a client now has a label.
	AddClientLabel(ctx context.Context, id common.ClientID, l *fspb.Label) error

	// RemoveLabel records that a client no longer has a label.
	RemoveClientLabel(ctx context.Context, id common.ClientID, l *fspb.Label) error

	// BlacklistClient records that a client_id is no longer trusted and should be
	// recreated.
	BlacklistClient(ctx context.Context, id common.ClientID) error

	// RecordClientContact records an authenticated contact with a
	// client. On success provides a contact id - an opaque string which can
	// be used to link messages to a contact.
	RecordClientContact(ctx context.Context, data ContactData) (ContactID, error)

	// ListClientContacts lists all of the contacts in the database for a given
	// client.
	//
	// NOTE: This method is explicitly permitted to return data up to 30 seconds
	// stale. Also, it is normal (and expected) for a datastore to delete contact
	// older than a few weeks.
	ListClientContacts(ctx context.Context, id common.ClientID) ([]*spb.ClientContact, error)

	// StreamClientContacts is a streaming version of ListClientContacts.
	StreamClientContacts(ctx context.Context, id common.ClientID, callback func(*spb.ClientContact) error) error

	// LinkMessagesToContact associates messages with a contact - it records
	// that they were sent or received during the given contact.
	LinkMessagesToContact(ctx context.Context, contact ContactID, msgs []common.MessageID) error

	// Writes resource-usage data received from a client to the data-store.
	RecordResourceUsageData(ctx context.Context, id common.ClientID, rud *mpb.ResourceUsageData) error

	// Fetches resource-usage records for a given client and time range from the data-store.
	FetchResourceUsageRecords(ctx context.Context, id common.ClientID, startTimestamp, endTimestamp *tspb.Timestamp) ([]*spb.ClientResourceUsageRecord, error)
}

type ContactData struct {
	ClientID                 common.ClientID // ID of the client.
	NonceSent, NonceReceived uint64          // Nonce sent to the client and received from the client.
	Addr                     string          // Observed client network address.
	ClientClock              *tspb.Timestamp // Client's report of its current clock setting.

	// If non-empty, indicates that the contact is or was a streaming contact to
	// the listed FS server. (As defined by notifications module being used.)
	StreamingTo string
}

type ContactID string

type FileStore interface {
	// StoreFile stores data into the Filestore, organized by service and name.
	StoreFile(ctx context.Context, service, name string, data io.Reader) error

	// StatFile returns the modification time of a file previously stored by
	// StoreFile. Returns ErrNotFound if not found.
	StatFile(ctx context.Context, servce, name string) (time.Time, error)

	// ReadFile returns the data and modification time of file previously
	// stored by StoreFile.  Caller is responsible for closing data.
	//
	// Note: Calls to data are permitted to fail if ctx is canceled or expired.
	ReadFile(ctx context.Context, service, name string) (data ReadSeekerCloser, modtime time.Time, err error)
}

type MessageProcessor interface {
	// ProcessMessage is called by the Datastore to indicate that the
	// provided message is overdue and that processing should be attempted
	// again.
	//
	// This call will be repeated until MarkMessage(Processed|Failed) is
	// successfully called on m.
	ProcessMessages(msgs []*fspb.Message)
}

type MessageStore interface {
	// StoreMessages records msgs. If contact is not the empty string, it attaches
	// them to the associated contact.
	//
	// It is not an error for a message to already exist. In this case a success result
	// will overwrite any result already present, and a failed result will overwrite
	// an empty result. Otherwise the operation is silently dropped.
	//
	// A message is eligible to be returned by ClientMessagesForProcessing or the
	// registered MessageProcessor iff it does not yet have a Result. Also,
	// setting a Result will delete the message's Data field payload.
	StoreMessages(ctx context.Context, msgs []*fspb.Message, contact ContactID) error

	// DeletePendingMessages removes all pending messages for given clients.
	DeletePendingMessages(ctx context.Context, ids []common.ClientID) error

	// GetPendingMessageCount returns the number of pending messages for the given clients.
	GetPendingMessageCount(ctx context.Context, ids []common.ClientID) (uint64, error)

	// GetPendingMessages returns pending messages for given clients.
	// If wantData is true, message data is retrieved as well.
	// offset and limit are optional, set them to 0 to retrieve all pending messages.
	GetPendingMessages(ctx context.Context, ids []common.ClientID, offset uint64, limit uint64, wantData bool) ([]*fspb.Message, error)

	// ClientMessagesForProcessing returns messages that are due to be
	// processed by a client. It also increments the time at which the
	// messages will again become overdue using rp.
	//
	// The lim parameter indicates the maximum number of messages to to
	// retrieve. If non-nil, serviceLimits further limits the number returned
	// for each service.
	//
	// Note that if an error occurs partway through the loading of messages,
	// the already loaded messages may be returned along with the error. In
	// particular, datastore implementations might do this if the ctx times
	// out before all messages are found and updated. Any such are message
	// is valid and ready for processing.
	ClientMessagesForProcessing(ctx context.Context, id common.ClientID, lim uint64, serviceLimits map[string]uint64) ([]*fspb.Message, error)

	// GetMessages retrieves specific messages.
	GetMessages(ctx context.Context, ids []common.MessageID, wantData bool) ([]*fspb.Message, error)

	// GetMessageResult retrieves the current status of a message.
	GetMessageResult(ctx context.Context, id common.MessageID) (*fspb.MessageResult, error)

	// SetMessageResult retrieves the current status of a message. The dest
	// parameter identifies the destination client, and must be the empty id for
	// messages addressed to the server.
	SetMessageResult(ctx context.Context, dest common.ClientID, id common.MessageID, res *fspb.MessageResult) error

	// RegisterMessageProcessor installs a MessageProcessor which will be
	// called when a message is overdue for processing.
	RegisterMessageProcessor(mp MessageProcessor)

	// StopMessageProcessor causes the datastore to stop making calls to the
	// registered MessageProcessor. It only returns once all existing calls
	// to MessageProcessor have completed.
	StopMessageProcessor()
}

type NOOPCloser struct {
	io.ReadSeeker
}

type ReadSeekerCloser interface {
	io.ReadSeeker
	io.Closer
}

type Store interface {
	MessageStore
	ClientStore
	BroadcastStore
	FileStore

	// IsNotFound returns whether an error returned by the Datastore indicates that
	// a record was not found.
	IsNotFound(error) bool

	// Close shuts down the Store, releasing any held resources.
	Close() error
}