store

type EncodedResponse ¶

type EncodedResponse struct {
	Status  int
	Headers [][2]string
	Body    []byte
}

EncodedResponse is a byte-efficient snapshot of an HTTP response used by cache and idempotency middleware to persist captured responses.

Wire format (version 1):

[1 byte version=1]
[2 bytes status (big-endian)]
[2 bytes header_count (big-endian)]
for each header:
  [2 bytes key_len (big-endian)] [key_len bytes key]
  [2 bytes val_len (big-endian)] [val_len bytes value]
[remaining bytes: body]

func DecodeResponse(buf []byte) (EncodedResponse, error)

func (r EncodedResponse) AppendTo(dst []byte) []byte

func (r EncodedResponse) Encode() []byte

type GetAndDeleter ¶

type GetAndDeleter interface {
	GetAndDelete(ctx context.Context, key string) ([]byte, error)
}

GetAndDeleter is implemented by backends that support atomic GET+DEL (e.g., Redis GETDEL). Used by csrf for TOCTOU-safe single-use token validation. When a KV does not implement GetAndDeleter, callers fall back to a non-atomic Get+Delete pair.

type KV ¶

type KV interface {
	Get(ctx context.Context, key string) ([]byte, error)
	Set(ctx context.Context, key string, value []byte, ttl time.Duration) error
	Delete(ctx context.Context, key string) error
}

KV is the unified byte-level key-value interface for middleware stores.

Contract:

• Get returns (nil, ErrNotFound) on a missing key. A (nil, nil) return is forbidden; callers may rely on err != nil when the value is absent.
• Set with ttl == 0 stores a value with no expiry. Positive ttl is honored by the backend; sub-second precision is best-effort.
• Delete returning nil means "the key is not present" regardless of whether it was present before the call.
• All methods are safe for concurrent use from multiple goroutines.
• Values returned by Get are owned by the caller; backends must copy any internal buffer before returning.

func Prefixed(inner KV, prefix string) KV

package main

import (
	"context"
	"fmt"
	"time"

	"github.com/goceleris/celeris/middleware/store"
)

func main() {
	kv := store.NewMemoryKV()
	defer kv.Close()

	sessions := store.Prefixed(kv, "sess:")
	_ = sessions.Set(context.Background(), "abc", []byte("hi"), time.Minute)

	// Underlying key is "sess:abc".
	raw, _ := kv.Get(context.Background(), "sess:abc")
	fmt.Println(string(raw))
}

Output:
hi

type MemoryKV ¶

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

MemoryKV is an in-memory, sharded implementation of KV. It also implements GetAndDeleter, Scanner, PrefixDeleter, and SetNXer.

MemoryKV is intended as the default/test backend and for single-process deployments. For multi-instance deployments, use a driver-backed adapter (middleware/session/redisstore, etc.).

func NewMemoryKV(config ...MemoryKVConfig) *MemoryKV

package main

import (
	"context"
	"fmt"
	"time"

	"github.com/goceleris/celeris/middleware/store"
)

func main() {
	kv := store.NewMemoryKV()
	defer kv.Close()

	ctx := context.Background()
	_ = kv.Set(ctx, "session:abc", []byte("payload"), 30*time.Minute)
	v, _ := kv.Get(ctx, "session:abc")
	fmt.Println(string(v))
}

Output:
payload

func (m *MemoryKV) Close()

func (m *MemoryKV) Delete(_ context.Context, key string) error

func (m *MemoryKV) DeletePrefix(_ context.Context, prefix string) error

func (m *MemoryKV) Get(_ context.Context, key string) ([]byte, error)

func (m *MemoryKV) GetAndDelete(_ context.Context, key string) ([]byte, error)

func (m *MemoryKV) Scan(_ context.Context, prefix string) ([]string, error)

func (m *MemoryKV) Set(_ context.Context, key string, value []byte, ttl time.Duration) error

func (m *MemoryKV) SetNX(_ context.Context, key string, value []byte, ttl time.Duration) (bool, error)

type MemoryKVConfig ¶

type MemoryKVConfig struct {
	// Shards is the number of lock shards. Default: runtime.NumCPU(),
	// rounded up to the next power of two.
	Shards int

	// CleanupInterval is how often expired entries are evicted.
	// Default: 1 minute. Zero is replaced with the default.
	CleanupInterval time.Duration

	// CleanupContext, if set, controls the cleanup goroutine lifetime.
	// When the context is cancelled, the goroutine stops. If nil,
	// [MemoryKV.Close] is the only way to stop the goroutine.
	CleanupContext context.Context
}

MemoryKVConfig configures the in-memory MemoryKV store.

type PrefixDeleter ¶

type PrefixDeleter interface {
	DeletePrefix(ctx context.Context, prefix string) error
}

PrefixDeleter is implemented by backends that can atomically (or efficiently) delete all keys matching a prefix. Used by Cache for InvalidatePrefix operations. Backends that do not implement this may emulate it via Scan + Delete, but with weaker atomicity guarantees.

type Scanner ¶

type Scanner interface {
	Scan(ctx context.Context, prefix string) ([]string, error)
}

Scanner is implemented by backends that support key enumeration by prefix (e.g., Redis SCAN). Used by session Reset to delete all keys matching a prefix. When a KV does not implement Scanner, Reset is a documented no-op.

type Scripter ¶

type Scripter interface {
	EvalSHA(ctx context.Context, sha string, keys []string, args ...any) (any, error)
	ScriptLoad(ctx context.Context, script string) (string, error)
}

Scripter is implemented by backends that support server-side atomic scripts (e.g., Redis EVALSHA + ScriptLoad). Used by the ratelimit Redis adapter for atomic token-bucket updates via a Lua script. Most KV backends do not implement Scripter; it is strictly optional.

type SetNXer ¶

type SetNXer interface {
	SetNX(ctx context.Context, key string, value []byte, ttl time.Duration) (acquired bool, err error)
}

SetNXer is implemented by backends that support atomic "set if not exists" semantics (e.g., Redis SET NX, Postgres INSERT ON CONFLICT DO NOTHING). Used by idempotency for lock acquisition. A backend without SetNX cannot serve as an idempotency store.