skhron

README

Skhron

Skhron is a lightweight in-memory storage designed for in-code usage

Usage

Simple Storage Example

Example Source Code

package main

import (
	"fmt"
	"time"

	"github.com/dartt0n/skhron"
)

func main() {
	storage := skhron.New() // init new storage
	storage.LoadSnapshot()  // load snapshot from file (default: `./.skhron/snapshot.skh`)

	storage.CleanUp() // manually run cleaup - remove expored keys

	timestamp := time.Now().Format("2006_01_02 15:04:05")

	// .Exists(key) checks whether the key exists in the storage
	if storage.Exists("run-timestamp") {
		fmt.Printf("Previous run timestamp found!\n")
	}

	// .Get(key) returns value associated with the key
	if value, err := storage.Get("run-timestamp"); err != nil {
		fmt.Printf("Get failed: %v\n", err)
	} else {
		fmt.Printf("Value: %s\n", string(value)) // convert bytes to string and print
	}

	// .Delete(key) deletes the key from the storage.
	// This method call will NOT panic or return error if key does not exist
	if err := storage.Delete("run-timestamp"); err != nil {
		fmt.Printf("Delete failed: %v\n", err)
	}

	// .Put(key, value, ttl) puts value under key with time to live equal to ttl
	// Here we put bytes of string `timestamp` under the key `run-timestamp` and time-to-live equal to 1 hour
	if err := storage.PutTTL("run-timestamp", []byte(timestamp), 1*time.Hour); err != nil {
		fmt.Printf("Put failed: %v\n", err)
	}
}

Example with HTTP server

Example Source Code

func main() {
	ctx, cancel := context.WithCancel(context.Background())

	addr := flag.String("address", ":3567", "the address to listen on")
	period := flag.Int("period", 10, "the period of time to run cleanup (in seconds)")

	flag.Parse()

	storage := skhron.New() // initialize storage
	storage.LoadSnapshot() // load from snapshot

	server := newServer(*addr, storage) // basic http server

	go server.Run(ctx) // run server in background

	storage_shutdown := make(chan struct{}) // create channel for shutdown for storage
    
    // run periodic cleanup process in background.
    // it would perform cleanup each `period` seconds.
    // it would finishon ctx.cancel() call and put signal into `storage_shutdown` channel 
	go storage.PeriodicCleanup(ctx, time.Duration(*period)*time.Second, storage_shutdown)

    // listen for termination signals
	c := make(chan os.Signal, 1)
	signal.Notify(c, os.Interrupt, syscall.SIGTERM)
	signal.Notify(c, os.Interrupt, syscall.SIGINT)

    <-c // wait for Ctrl-C
	cancel() // send cancelation signal to both http server and storage process

	server.Shutdown(ctx) // wait for server

	<-storage_shutdown // wait for storage
}

Documentation

Index

• Variables
• func DefaultOpts[V any](s *Skhron[V])
• type Skhron
  • func New[V any](opts ...StorageOpt[V]) *Skhron[V]
  • func (s *Skhron[V]) CleanUp()
  • func (s *Skhron[V]) CreateSnapshot() error
  • func (s *Skhron[V]) Delete(key string) error
  • func (s *Skhron[V]) Exists(key string) bool
  • func (s *Skhron[V]) Get(key string) (V, error)
  • func (s *Skhron[V]) GetRegex(mask *regexp.Regexp) []V
  • func (s *Skhron[V]) LoadSnapshot() error
  • func (s *Skhron[V]) MarshalJSON() ([]byte, error)
  • func (s *Skhron[V]) PeriodicCleanup(ctx context.Context, period time.Duration, done chan struct{})
  • func (s *Skhron[V]) Put(key string, value V) error
  • func (s *Skhron[V]) PutTTL(key string, value V, ttl time.Duration) error
• type StorageOpt
  • func WithMapLimit[V any](limit uint64) StorageOpt[V]
  • func WithSnapshotDir[V any](dir string) StorageOpt[V]
  • func WithSnapshotName[V any](name string) StorageOpt[V]
  • func WithTempSnapshotDir[V any](dir string) StorageOpt[V]

Variables

var (
	SkhronExtension = ".skh"
)

Functions

func DefaultOpts

func DefaultOpts[V any](s *Skhron[V])

Types

type Skhron

type Skhron[V any] struct {

	// Skhron.Data is a main object. All the data is stored here.
	// It is shrinking map, which shrinks every "limit" (skhron.WithMapLimit option) deletions.
	Data *smap.Map[string, V] `json:"data,omitempty"`
	// Skhron.TTLq is a queue object used to delete expired items in time.
	// Each put operation the object is either added to the queue or updated in the queue.
	// The cleaning up process takes an item from the front of the queue and checks,
	// Whether the item has expired or not. Thus, we avoid scanning the whole map to find expired items.
	TTLq *expireQueue `json:"ttlq,omitempty"`

	// A directory where snapshots would be stored
	SnapshotDir string
	// A name (WITHOUT EXTENSION) which would be used to store the latest snapshot
	SnapshotName string
	// A directory where temporary files would be stored
	TempSnapshotDir string
	// contains filtered or unexported fields
}

func New

func New[V any](opts ...StorageOpt[V]) *Skhron[V]

Initialize Skhron instance with options.

func (*Skhron[V]) CleanUp

func (s *Skhron[V]) CleanUp()

CleanUp is a function which removes expired items. It is called periodically by the `PeriodicCleanup` function. This function locks mutex for its operations.

func (*Skhron[V]) CreateSnapshot

func (s *Skhron[V]) CreateSnapshot() error

CreateSnapshot is a function which create snapshot (json dump of struct) in the temporary directory. Then it checks if an older snapshot exists in snapshot directory. If it is, it renames it to format "{snapshot name}_{time stamp}.skh" and then moves new snapshot to the snapshot directory

func (*Skhron[V]) Delete

func (s *Skhron[V]) Delete(key string) error

Delete is a function which deletes a key from the storage. It takes the key as string parameter. It does not delete the key from the queue, since when the key is expired it would be deleted from the queue without side effects. This function locks mutex for its operations.

func (*Skhron[V]) Exists

func (s *Skhron[V]) Exists(key string) bool

Exists is a function which check wheater a key is present in the storage. It takes the key as string parameter. This function locks mutex for its operations.

func (*Skhron[V]) Get

func (s *Skhron[V]) Get(key string) (V, error)

Get is a function which fetches a value in the storage under a key. It takes the key as string parameter. If the key is not present, error is returned. This function locks mutex for its operations.

func (*Skhron[V]) GetRegex

func (s *Skhron[V]) GetRegex(mask *regexp.Regexp) []V

GetRegex is a function which fetches values in the storage under keys, which match the mask regex. It takes the regex as parameter. This function locks mutex for its operations.

func (*Skhron[V]) LoadSnapshot

func (s *Skhron[V]) LoadSnapshot() error

LoadSnapshot is a function, which loads data from the latest snapshot file and writes data to the Skhron object. It looks for file {snapshot dir}/{snapshot file}.skh If load is failed, error is returned.

func (*Skhron[V]) MarshalJSON

func (s *Skhron[V]) MarshalJSON() ([]byte, error)

JsonMarshal is a function, which converts the struct into JSON-string bytes

func (*Skhron[V]) PeriodicCleanup

func (s *Skhron[V]) PeriodicCleanup(ctx context.Context, period time.Duration, done chan struct{})

`PeriodicCleanup` is a function that periodically calls the `CleanUp` function. It works until `ctx.Done()` signal is sent. It puts into `done` channel when it finishes. It backups current state of the storage into file `./skhron/skhron_{timestamp}.json` on exit. It runs clean up process every `period` time duration.

func (*Skhron[V]) Put

func (s *Skhron[V]) Put(key string, value V) error

Put is a function which puts a value in the storage under a key. It takes the key as string and the value as V. This function locks mutex for its operations.

func (*Skhron[V]) PutTTL

func (s *Skhron[V]) PutTTL(key string, value V, ttl time.Duration) error

PutTTL is a function which puts a value in the storage under a key with certain TTL. It takes the key as string, the value as V and ttl as time.Duration. It scans the entire queue to find if the item is already in the queue. If it is, it updates the item and updates the queue (to maintain priority). If it is not, it puts the item into the queue. This function locks mutex for its operations.

type StorageOpt

type StorageOpt[V any] func(s *Skhron[V])

func WithMapLimit

func WithMapLimit[V any](limit uint64) StorageOpt[V]

func WithSnapshotDir

func WithSnapshotDir[V any](dir string) StorageOpt[V]

func WithSnapshotName

func WithSnapshotName[V any](name string) StorageOpt[V]

func WithTempSnapshotDir

func WithTempSnapshotDir[V any](dir string) StorageOpt[V]