persist

Documentation

Index

• Variables
• func SafeKey(key string) string
• type Data
  • func NewData[T any](store Store, key string) Data[T]
  • func (d *Data[T]) Age() time.Duration
  • func (d *Data[T]) Bytes() ([]byte, error)
  • func (d *Data[T]) FromBytes(bytes []byte) error
  • func (d *Data[T]) Get() T
  • func (d *Data[T]) IsExpired(ttl time.Duration) bool
  • func (d *Data[T]) IsUnset() bool
  • func (d *Data[T]) Load(ctx context.Context) error
  • func (d *Data[T]) ResetTTL()
  • func (d *Data[T]) Set(ctx context.Context, a T) error
• type FireStore
  • func NewFireStore(client *firestore.Client) *FireStore
  • func (s *FireStore) Get(ctx context.Context, key string) ([]byte, time.Time, error)
  • func (s *FireStore) Set(ctx context.Context, key string, val []byte) error
• type FsStore
  • func NewFsStore(dir string, useSafeKey bool) *FsStore
  • func (c *FsStore) Get(_ context.Context, key string) ([]byte, time.Time, error)
  • func (c *FsStore) Set(_ context.Context, key string, val []byte) error
• type MultiStore
  • func (s *MultiStore) Get(ctx context.Context, key string) ([]byte, time.Time, error)
  • func (s *MultiStore) Set(ctx context.Context, key string, val []byte) error
• type RedisStore
  • func NewRedisStore(client *redis.Client) *RedisStore
  • func (s *RedisStore) Get(_ context.Context, key string) ([]byte, time.Time, error)
  • func (s *RedisStore) Set(_ context.Context, key string, val []byte) error
• type Serializable
• type Store

Variables

var (
	// ErrExternalCache indicates there was an error reading or writing to an external cache
	// this error may mean the external cache has become out of date. However, even if this error is returned
	// the cache will be safe to use as it will fall back on and in-memory cache.
	ErrExternalCache = errors.New("could not read/write from the external cache")

	// ErrNotSerializable indicates there was an error serializing the underlying data into a storable format
	// this error may mean the external cache has become out of date. However, even if this error is returned
	// the cache will be safe to use as it will fall back on an in-memory cache.
	ErrNotSerializable = errors.New("return type could not be serialized/deserialized")

	// ErrFailedKey indicates there was an error converting an incoming parameter into a valid key
	// this error may mean the external cache has become out of date. However, even if this error is returned
	// the cache will be safe to use as it will fall back on an in-memory cache.
	ErrFailedKey = errors.New("failed to convert input into valid key")
)

var Forever = time.Duration(0)

Forever tells cache data to persist forever and never expire

Functions

func SafeKey

func SafeKey(key string) string

SafeKey takes an arbitrary string and converts it to a string that contains only the following characters 0-9, a-z, A-Z, -, _, .

Types

type Data

type Data[T any] struct {
	// contains filtered or unexported fields
}

Data wraps a value in a persistent data type. Once created, Load can be called to restore the value from a persistent data store. the Get() and Set() methods can be used to read and update the value and will attempt to keep the external data store in sync. Even if the external data store goes out of sync, Data is safe to use, however, future calls to Load may retrieve old data.

func NewData

func NewData[T any](store Store, key string) Data[T]

NewData wraps the initial in a Data type. If the provided store is non-nil, Data will sync it's internal value to the external store

func (*Data[T]) Age

func (d *Data[T]) Age() time.Duration

Age returns how long it has been since the Data was last Set

func (*Data[T]) Bytes

func (d *Data[T]) Bytes() ([]byte, error)

Bytes converts the value int a slice of bytes, so it can be stored. If the underlying type implements the Serializable interface that will be used. Otherwise, the type is JSON marshalled

func (*Data[T]) FromBytes

func (d *Data[T]) FromBytes(bytes []byte) error

FromBytes takes a slice of bytes and hydrates Data. It can fail if the by format is incorrect. If the underlying type implements the Serializable interface that will be used. Otherwise, the type is JSON marshalled

func (*Data[T]) Get

func (d *Data[T]) Get() T

Get returns the underlying value of the data value

func (*Data[T]) IsExpired

func (d *Data[T]) IsExpired(ttl time.Duration) bool

IsExpired can be used to determine if a Data value is expired in relation to the provided expiration

func (*Data[T]) IsUnset

func (d *Data[T]) IsUnset() bool

IsUnset returns true if the value has never been set

func (*Data[T]) Load

func (d *Data[T]) Load(ctx context.Context) error

Load will load the initial data from the external store. If the store is nil or the Data has already been set Load is a no-op. Load can safely be called multiple times.

func (*Data[T]) ResetTTL

func (d *Data[T]) ResetTTL()

func (*Data[T]) Set

func (d *Data[T]) Set(ctx context.Context, a T) error

Set will set the Data's internal value, it will always succeed at setting the in memory value. However, setting the store value may fail. If this happens, Data is still safe to use, and it's value will still reflect the update. however, the data in the external store will not be updated and may be out of date the next time the backed value is created.

type FireStore

type FireStore struct {
	// contains filtered or unexported fields
}

FireStore is a Store that uses a firestore collection to store cache data

func NewFireStore

func NewFireStore(client *firestore.Client) *FireStore

NewFireStore creates a new FireStore, the client is used to interact with the store.

func (*FireStore) Get

func (s *FireStore) Get(ctx context.Context, key string) ([]byte, time.Time, error)

Get attempts to get the firestore document that matches the provided key. If the document does not exist no error will be returned. If the document does exist, it's value and last updated time will be returned

func (*FireStore) Set

func (s *FireStore) Set(ctx context.Context, key string, val []byte) error

Set attempts to update or creates a firestore document that matches the provided key. In order to ensure the key does not contain illegal characters, the key will be converted to a 'safe' key.

type FsStore

type FsStore struct {
	// contains filtered or unexported fields
}

FsStore is a Store that uses the filesystem to store cache data

func NewFsStore

func NewFsStore(dir string, useSafeKey bool) *FsStore

NewFsStore creates a new FsStore, dir is the rood directory where all cached files will be stored

func (*FsStore) Get

func (c *FsStore) Get(_ context.Context, key string) ([]byte, time.Time, error)

Get searches for a file that matches the provided key in the stores root directory. If the file is missing no error will be returned

func (*FsStore) Set

func (c *FsStore) Set(_ context.Context, key string, val []byte) error

Set writes or updates a file that matches the provided key in the stores root directory. The file will contain the raw bytes passed in by val

type MultiStore

type MultiStore struct {
	// contains filtered or unexported fields
}

func (*MultiStore) Get

func (s *MultiStore) Get(ctx context.Context, key string) ([]byte, time.Time, error)

func (*MultiStore) Set

func (s *MultiStore) Set(ctx context.Context, key string, val []byte) error

type RedisStore

type RedisStore struct {
	// contains filtered or unexported fields
}

RedisStore is a Store that uses redis to store cache data

func NewRedisStore

func NewRedisStore(client *redis.Client) *RedisStore

NewRedisStore creates a new RedisStore.

func (*RedisStore) Get

func (s *RedisStore) Get(_ context.Context, key string) ([]byte, time.Time, error)

Get searches for a key that matches the provided key in the redis cache. If the key does not exist no error will be returned

func (*RedisStore) Set

func (s *RedisStore) Set(_ context.Context, key string, val []byte) error

Set updates the redis cache, if the key can't be updated or created an error will be returned

type Serializable

type Serializable interface {
	Bytes() ([]byte, error)
	FromBytes([]byte) error
}

Serializable is an optional interface that can be used to customize the way a Data struct serializes its data if this interface is not provided, jsonMarshall and jsonUnmarshal will be used instead.

type Store

type Store interface {
	Get(context.Context, string) ([]byte, time.Time, error)
	Set(context.Context, string, []byte) error
}

Store is an interface that can be used by a Data struct to back up it's internal value to any external persistent storage mechanism