dinkur

Documentation

Overview

Package dinkur contains abstractions and models used by multiple Dinkur client implementations.

Index

• Variables
• type Client
• type CommonFields
• type EditEntry
• type EditStatus
• type Entries
• type Entry
  • func (t Entry) Elapsed() time.Duration
• type EventType
  • func (ev EventType) String() string
• type NewEntry
• type NilClient
  • func (*NilClient) Close() error
  • func (*NilClient) Connect(context.Context) error
  • func (*NilClient) CreateEntry(context.Context, NewEntry) (StartedEntry, error)
  • func (*NilClient) DeleteEntry(context.Context, uint) (Entry, error)
  • func (*NilClient) GetActiveEntry(context.Context) (*Entry, error)
  • func (*NilClient) GetEntry(context.Context, uint) (Entry, error)
  • func (*NilClient) GetEntryList(context.Context, SearchEntry) ([]Entry, error)
  • func (*NilClient) GetStatus(context.Context) (Status, error)
  • func (*NilClient) Ping(context.Context) error
  • func (*NilClient) SetStatus(context.Context, EditStatus) error
  • func (*NilClient) StopActiveEntry(context.Context, time.Time) (*Entry, error)
  • func (*NilClient) StreamEntry(context.Context) (<-chan StreamedEntry, error)
  • func (*NilClient) StreamStatus(context.Context) (<-chan StreamedStatus, error)
  • func (*NilClient) UpdateEntry(context.Context, EditEntry) (UpdatedEntry, error)
• type SearchEntry
• type StartedEntry
• type Status
• type Statuses
• type StreamedEntry
• type StreamedStatus
• type TimeFields
• type UpdatedEntry

Variables

var (
	ErrAlreadyConnected    = errors.New("client is already connected to database")
	ErrNotConnected        = errors.New("client is not connected to database")
	ErrEntryNameEmpty      = errors.New("entry name cannot be empty")
	ErrEntryEndBeforeStart = errors.New("entry end time cannot be before start time")
	ErrNotFound            = gorm.ErrRecordNotFound
	ErrLimitTooLarge       = errors.New("search limit is too large, maximum: " + strconv.Itoa(math.MaxInt))
	ErrClientIsNil         = errors.New("client is nil")
)

Common errors used by multiple Dinkur client and daemon implementations.

Types

type Client

type Client interface {
	Connect(ctx context.Context) error
	Close() error
	Ping(ctx context.Context) error

	Entries
	Statuses
}

Client is a Dinkur client interface. This is the core interface to act upon the Dinkur data store. Depending on the implementation, it may either talk directly to an Sqlite3 database file, or talk to a Dinkur daemon via gRPC over TCP/IP that in turn talks to a database.

type CommonFields

type CommonFields struct {
	// ID is a unique identifier for this entry. The same ID will never be used
	// twice for a given database.
	ID uint `json:"id" yaml:"id" xml:"Id"`
	TimeFields
}

CommonFields contains fields used by multiple other models.

type EditEntry

type EditEntry struct {
	// IDOrZero of the entry to edit. If set to nil, then Dinkur will attempt to make
	// an educated guess on what entry to edit by editing the active entry or a
	// recent entry.
	IDOrZero uint
	// Name is the new entry name. If AppendName is enabled, then this value will
	// append to the existing name, delimited with a space.
	//
	// No change to the entry name is applied if this is set to nil.
	Name *string
	// Start is the new entry start timestamp.
	//
	// No change to the entry start timestamp is applied if this is set to nil.
	Start *time.Time
	// StartFuzzy is the new entry start timestamp, but will be parsed fuzzy.
	// This is ignored if empty string or if Start is supplied.
	//
	// No change to the entry start timestamp is applied if this is set to empty.
	StartFuzzy string
	// End is the new entry end timestamp.
	//
	// No change to the entry end timestamp is applied if this is set to nil.
	End *time.Time
	// EndFuzzy is the new entry end timestamp, but will be parsed fuzzy.
	// This is ignored if empty string or if End is supplied.
	//
	// No change to the entry end timestamp is applied if this is set to empty.
	EndFuzzy string
	// AppendName changes the name field to append the name to the entry's
	// existing name (delimited with a space) instead of replacing it.
	AppendName         bool
	StartAfterIDOrZero uint
	EndBeforeIDOrZero  uint
	StartAfterLast     bool
}

EditEntry holds parameters used when editing a entry.

type EditStatus

type EditStatus struct {
	AFKSince  *time.Time // set if currently AFK
	BackSince *time.Time // set if returned from being AFK
}

EditStatus holds values used when updating the current status.

type Entries

type Entries interface {
	GetEntry(ctx context.Context, id uint) (Entry, error)
	GetEntryList(ctx context.Context, search SearchEntry) ([]Entry, error)
	GetActiveEntry(ctx context.Context) (*Entry, error)
	UpdateEntry(ctx context.Context, edit EditEntry) (UpdatedEntry, error)
	DeleteEntry(ctx context.Context, id uint) (Entry, error)
	CreateEntry(ctx context.Context, entry NewEntry) (StartedEntry, error)
	StopActiveEntry(ctx context.Context, endTime time.Time) (*Entry, error)
	StreamEntry(ctx context.Context) (<-chan StreamedEntry, error)
}

Entries is the Dinkur client methods targeted to reading, creating, and updating entries.

type Entry

type Entry struct {
	CommonFields `yaml:",inline"`
	// Name of the entry.
	Name string `json:"name" yaml:"name" xml:"Name"`
	// Start time of the entry.
	Start time.Time `json:"start" yaml:"start" xml:"Start"`
	// End time of the entry, or nil if the entry is still active.
	End *time.Time `json:"end" yaml:"end" xml:"End"`
}

Entry is a time tracked entry.

func (Entry) Elapsed

func (t Entry) Elapsed() time.Duration

Elapsed returns the duration of the entry. If the entry is currently active, the duration is calculated from the start to now.

type EventType

type EventType byte

EventType is the type of a streamed event.

const (
	// EventUnknown means the remove Dinkur daemon or client sent an undefined
	// event type.
	EventUnknown EventType = iota
	// EventCreated means the subject was just created.
	EventCreated
	// EventUpdated means the subject was just updated.
	EventUpdated
	// EventDeleted means the subject was just deleted.
	EventDeleted
)

func (EventType) String

func (ev EventType) String() string

type NewEntry

type NewEntry struct {
	Name               string
	Start              *time.Time
	End                *time.Time
	StartAfterIDOrZero uint
	EndBeforeIDOrZero  uint
	StartAfterLast     bool
}

NewEntry holds parameters used when creating a new entry.

type NilClient

type NilClient struct {
}

NilClient returns "client is nil" error on all of its methods.

func (*NilClient) Close

func (*NilClient) Close() error

Close is a dummy implementation of the dinkur.Client that only returns the "client is nil" error.

func (*NilClient) Connect

func (*NilClient) Connect(context.Context) error

Connect is a dummy implementation of the dinkur.Client that only returns the "client is nil" error.

func (*NilClient) CreateEntry

func (*NilClient) CreateEntry(context.Context, NewEntry) (StartedEntry, error)

CreateEntry is a dummy implementation of the dinkur.Client that only returns the "client is nil" error.

func (*NilClient) DeleteEntry

func (*NilClient) DeleteEntry(context.Context, uint) (Entry, error)

DeleteEntry is a dummy implementation of the dinkur.Client that only returns the "client is nil" error.

func (*NilClient) GetActiveEntry

func (*NilClient) GetActiveEntry(context.Context) (*Entry, error)

GetActiveEntry is a dummy implementation of the dinkur.Client that only returns the "client is nil" error.

func (*NilClient) GetEntry

func (*NilClient) GetEntry(context.Context, uint) (Entry, error)

GetEntry is a dummy implementation of the dinkur.Client that only returns the "client is nil" error.

func (*NilClient) GetEntryList

func (*NilClient) GetEntryList(context.Context, SearchEntry) ([]Entry, error)

GetEntryList is a dummy implementation of the dinkur.Client that only returns the "client is nil" error.

func (*NilClient) GetStatus

func (*NilClient) GetStatus(context.Context) (Status, error)

GetStatus is a dummy implementation of the dinkur.Client that only returns the "client is nil" error.

func (*NilClient) Ping

func (*NilClient) Ping(context.Context) error

Ping is a dummy implementation of the dinkur.Client that only returns the "client is nil" error.

func (*NilClient) SetStatus

func (*NilClient) SetStatus(context.Context, EditStatus) error

SetStatus is a dummy implementation of the dinkur.Client that only returns the "client is nil" error.

func (*NilClient) StopActiveEntry

func (*NilClient) StopActiveEntry(context.Context, time.Time) (*Entry, error)

StopActiveEntry is a dummy implementation of the dinkur.Client that only returns the "client is nil" error.

func (*NilClient) StreamEntry

func (*NilClient) StreamEntry(context.Context) (<-chan StreamedEntry, error)

StreamEntry is a dummy implementation of the dinkur.Client that only returns the "client is nil" error.

func (*NilClient) StreamStatus

func (*NilClient) StreamStatus(context.Context) (<-chan StreamedStatus, error)

StreamStatus is a dummy implementation of the dinkur.Client that only returns the "client is nil" error.

func (*NilClient) UpdateEntry

func (*NilClient) UpdateEntry(context.Context, EditEntry) (UpdatedEntry, error)

UpdateEntry is a dummy implementation of the dinkur.Client that only returns the "client is nil" error.

type SearchEntry

type SearchEntry struct {
	Start *time.Time
	End   *time.Time
	Limit uint

	Shorthand          timeutil.TimeSpanShorthand
	NameFuzzy          string
	NameHighlightStart string
	NameHighlightEnd   string
}

SearchEntry holds parameters used when searching for list of entries.

type StartedEntry

type StartedEntry struct {
	Started Entry
	Stopped *Entry
}

StartedEntry is the response from creating a new entry, with the newly created entry object as well as the entry that was stopped when creating the entry, if any entry was previously active.

type Status

type Status struct {
	TimeFields
	AFKSince  *time.Time // set if currently AFK
	BackSince *time.Time // set if returned from being AFK
}

Status holds data about the user's status, such as if they're currently AFK.

type Statuses

type Statuses interface {
	StreamStatus(ctx context.Context) (<-chan StreamedStatus, error)
	SetStatus(ctx context.Context, edit EditStatus) error
	GetStatus(ctx context.Context) (Status, error)
}

Statuses is the Dinkur client methods targeted to setting and reading statuses.

type StreamedEntry

type StreamedEntry struct {
	Entry Entry
	Event EventType
}

StreamedEntry holds a entry and its event type.

type StreamedStatus

type StreamedStatus struct {
	Status Status
}

StreamedStatus is an event holding an updated status.

type TimeFields

type TimeFields struct {
	// CreatedAt is when the object was created.
	CreatedAt time.Time `json:"createdAt" yaml:"createdAt" xml:"CreatedAt"`
	// UpdatedAt stores when the object was last updated/edited.
	UpdatedAt time.Time `json:"updatedAt" yaml:"updatedAt" xml:"UpdatedAt"`
}

TimeFields contains time metadata fields used by multiple other models.

type UpdatedEntry

type UpdatedEntry struct {
	Before Entry
	After  Entry
}

UpdatedEntry is the response from an edited entry, with values for before the edits were applied and after they were applied.