Help us shape the future of Go! Take the 2026 Go Developer Survey

session

package
v0.42.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 20, 2026 License: Apache-2.0 Imports: 31 Imported by: 20

README

Session Cache Implementation

This package provides session cache implementations for the Baton SDK. It includes both in-memory and gRPC-based implementations.

Overview

The session cache is used to store temporary data during sync operations. It provides a key-value store interface with support for:

  • Basic CRUD operations (Get, Set, Delete, Clear)
  • Batch operations (GetMany, SetMany)
  • Namespace isolation using sync IDs
  • Prefix support for key organization
  • Context-based configuration
  • An implemention will be chosen at runtime (the grpc interface will be used if the build tag is specified).

Documentation

Index

Constants

View Source 
const (
	SessionOpGet     = "get"
	SessionOpGetMany = "get_many"
	SessionOpGetAll  = "get_all"
	SessionOpSet     = "set"
	SessionOpSetMany = "set_many"
	SessionOpDelete  = "delete"
	SessionOpClear   = "clear"
)

Session op names are a fixed, bounded set shared by counters, annotations, and the syncer's stats token.

Variables

View Source 
var ErrSessionStoreDisabled = fmt.Errorf("session store is disabled by connector author. It must be explicitly enabled via RunConnector WithSessionStoreEnabled()")

Functions

func Chunk added in v0.5.0 

func Chunk[T any](items []T, chunkSize int) iter.Seq[[]T]

func ClearJSON 

func ClearJSON(ctx context.Context, ss sessions.SessionStore, opt ...sessions.SessionStoreOption) error

func DeleteJSON 

func DeleteJSON(ctx context.Context, ss sessions.SessionStore, key string, opt ...sessions.SessionStoreOption) error

func GetAllJSON 

func GetAllJSON[T any](ctx context.Context, ss sessions.SessionStore, opt ...sessions.SessionStoreOption) (map[string]T, error)

func GetJSON 

func GetJSON[T any](ctx context.Context, ss sessions.SessionStore, key string, opt ...sessions.SessionStoreOption) (T, bool, error)

func GetManyJSON 

func GetManyJSON[T any](ctx context.Context, ss sessions.SessionStore, keys []string, opt ...sessions.SessionStoreOption) (map[string]T, error)

func IsDeadlineExceeded added in v0.18.3 

func IsDeadlineExceeded(err error) bool

IsDeadlineExceeded reports whether err represents a timed-out operation, wrapped or carried as a gRPC status.

func NewGRPCSessionClient added in v0.5.0 

func NewGRPCSessionClient(ctx context.Context, accessToken string, dpopKey *jose.JSONWebKey, opt ...sessions.SessionStoreConstructorOption) (v1.BatonSessionServiceClient, error)

NewGRPCSessionClient creates a new gRPC session service client using existing DPoP credentials. It reuses an existing access token and DPoP key instead of performing a new authentication round. It reads the session service address from the BATON_SESSION_SERVICE_ADDR environment variable, defaulting to "localhost:50051" if not set.

func NewGRPCSessionStore added in v0.5.3 

func NewGRPCSessionStore(ctx context.Context, client v1.BatonSessionServiceClient, opt ...sessions.SessionStoreConstructorOption) (sessions.SessionStore, error)

NewGRPCSessionStore creates a new gRPC session cache instance.

func SetJSON 

func SetJSON[T any](ctx context.Context, ss sessions.SessionStore, key string, item T, opt ...sessions.SessionStoreOption) error

func SetManyJSON 

func SetManyJSON[T any](ctx context.Context, ss sessions.SessionStore, items map[string]T, opt ...sessions.SessionStoreOption) error

func StartGRPCSessionServerWithOptions added in v0.5.0 

func StartGRPCSessionServerWithOptions(ctx context.Context, listener net.Listener, sessionServer v1.BatonSessionServiceServer, opts ...grpc.ServerOption) error

func UnrollGetAll added in v0.5.3 

func UnrollGetAll[T any](ctx context.Context, ss GetAllable[T], opt ...sessions.SessionStoreOption) (map[string]T, error)

func UnrollGetMany added in v0.5.3 

func UnrollGetMany[T any](ctx context.Context, ss GetManyable[T], keys []string, opt ...sessions.SessionStoreOption) (map[string]T, error)

func UnrollSetMany added in v0.5.3 

func UnrollSetMany[T any](ctx context.Context, ss SetManyable[T], items iter.Seq2[SizedItem[T], error], opt ...sessions.SessionStoreOption) error

UnrollSetMany takes an iterator of sized items and batches them into SetMany calls, respecting both MaxKeysPerRequest and MaxSessionStoreSizeLimit. The iterator yields (item, error) pairs; iteration stops on the first error.

Types

type CacheItem added in v0.5.7 

type CacheItem struct {
	Value []byte
}

type Codec added in v0.5.0 

type Codec[T any] interface {
	Encode(value T) ([]byte, error)
	Decode(data []byte) (T, error)
}

type GRPCSessionServer added in v0.5.0 

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

func NewGRPCSessionServer added in v0.5.0 

func NewGRPCSessionServer() *GRPCSessionServer

func (*GRPCSessionServer) BindSessionStore added in v0.41.0 

func (s *GRPCSessionServer) BindSessionStore(ctx context.Context, syncID string, store sessions.SessionStore) (sessions.UnbindSessionStore, error)

func (*GRPCSessionServer) Clear added in v0.5.0 

func (s *GRPCSessionServer) Clear(ctx context.Context, req *v1.ClearRequest) (*v1.ClearResponse, error)

func (*GRPCSessionServer) Delete added in v0.5.0 

func (s *GRPCSessionServer) Delete(ctx context.Context, req *v1.DeleteRequest) (*v1.DeleteResponse, error)

func (*GRPCSessionServer) DeleteMany added in v0.5.0 

func (s *GRPCSessionServer) DeleteMany(ctx context.Context, req *v1.DeleteManyRequest) (*v1.DeleteManyResponse, error)

func (*GRPCSessionServer) Get added in v0.5.0 

func (s *GRPCSessionServer) Get(ctx context.Context, req *v1.GetRequest) (*v1.GetResponse, error)

func (*GRPCSessionServer) GetAll added in v0.5.0 

func (s *GRPCSessionServer) GetAll(ctx context.Context, req *v1.GetAllRequest) (*v1.GetAllResponse, error)

func (*GRPCSessionServer) GetMany added in v0.5.0 

func (s *GRPCSessionServer) GetMany(ctx context.Context, req *v1.GetManyRequest) (*v1.GetManyResponse, error)

func (*GRPCSessionServer) Set added in v0.5.0 

func (s *GRPCSessionServer) Set(ctx context.Context, req *v1.SetRequest) (*v1.SetResponse, error)

func (*GRPCSessionServer) SetMany added in v0.5.0 

func (s *GRPCSessionServer) SetMany(ctx context.Context, req *v1.SetManyRequest) (*v1.SetManyResponse, error)

type GRPCSessionStoreClient added in v0.5.3 

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

func (*GRPCSessionStoreClient) Clear added in v0.5.3 

func (g *GRPCSessionStoreClient) Clear(ctx context.Context, opt ...sessions.SessionStoreOption) error

Clear removes all values from the cache.

func (*GRPCSessionStoreClient) Delete added in v0.5.3 

func (g *GRPCSessionStoreClient) Delete(ctx context.Context, key string, opt ...sessions.SessionStoreOption) error

Delete removes a value from the cache by key.

func (*GRPCSessionStoreClient) Get added in v0.5.3 

func (g *GRPCSessionStoreClient) Get(ctx context.Context, key string, opt ...sessions.SessionStoreOption) ([]byte, bool, error)

Get retrieves a value from the cache by key.

func (*GRPCSessionStoreClient) GetAll added in v0.5.3 

func (g *GRPCSessionStoreClient) GetAll(ctx context.Context, pageToken string, opt ...sessions.SessionStoreOption) (map[string][]byte, string, error)

func (*GRPCSessionStoreClient) GetMany added in v0.5.3 

func (g *GRPCSessionStoreClient) GetMany(ctx context.Context, keys []string, opt ...sessions.SessionStoreOption) (map[string][]byte, []string, error)

GetMany retrieves multiple values from the cache by keys.

func (*GRPCSessionStoreClient) Set added in v0.5.3 

func (g *GRPCSessionStoreClient) Set(ctx context.Context, key string, value []byte, opt ...sessions.SessionStoreOption) error

Set stores a value in the cache with the given key.

func (*GRPCSessionStoreClient) SetMany added in v0.5.3 

func (g *GRPCSessionStoreClient) SetMany(ctx context.Context, values map[string][]byte, opt ...sessions.SessionStoreOption) error

SetMany stores multiple values in the cache.

type GetAllable added in v0.5.3 

type GetAllable[T any] interface {
	GetAll(ctx context.Context, pageToken string, opt ...sessions.SessionStoreOption) (map[string]T, string, error)
}

type GetManyable added in v0.5.3 

type GetManyable[T any] interface {
	GetMany(ctx context.Context, keys []string, opt ...sessions.SessionStoreOption) (map[string]T, []string, error)
}

type InstrumentedSessionStore added in v0.18.3 

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

InstrumentedSessionStore wraps a SessionStore with per-op latency and outcome observation, so session-store cost is attributable instead of vanishing into inflated connector-call latency. It holds no cumulative state: observations go to the request context's UsageCollector (connector side, reported back on response annotations) and/or the OnOp callback (syncer side, recorded into the sync stats token).

func NewInstrumentedSessionStore added in v0.18.3 

func NewInstrumentedSessionStore(backing sessions.SessionStore, kind string, opPrefix string, onOp SessionOpObserver) *InstrumentedSessionStore

NewInstrumentedSessionStore wraps backing. kind is a bounded label naming the backend variant (e.g. c1z_pebble, c1z_sqlite, connector_backend); empty means this layer does not claim the collector's kind. opPrefix is prepended to reported op names ("" for the backend layer, "cache." for a cache-level view). onOp may be nil.

func (*InstrumentedSessionStore) Clear added in v0.18.3 

func (i *InstrumentedSessionStore) Clear(ctx context.Context, opt ...sessions.SessionStoreOption) error

func (*InstrumentedSessionStore) Delete added in v0.18.3 

func (i *InstrumentedSessionStore) Delete(ctx context.Context, key string, opt ...sessions.SessionStoreOption) error

func (*InstrumentedSessionStore) Get added in v0.18.3 

func (i *InstrumentedSessionStore) Get(ctx context.Context, key string, opt ...sessions.SessionStoreOption) ([]byte, bool, error)

func (*InstrumentedSessionStore) GetAll added in v0.18.3 

func (i *InstrumentedSessionStore) GetAll(ctx context.Context, pageToken string, opt ...sessions.SessionStoreOption) (map[string][]byte, string, error)

func (*InstrumentedSessionStore) GetMany added in v0.18.3 

func (i *InstrumentedSessionStore) GetMany(ctx context.Context, keys []string, opt ...sessions.SessionStoreOption) (map[string][]byte, []string, error)

func (*InstrumentedSessionStore) Kind added in v0.18.3 

func (i *InstrumentedSessionStore) Kind() string

Kind returns the backend label this wrapper was constructed with.

func (*InstrumentedSessionStore) Set added in v0.18.3 

func (i *InstrumentedSessionStore) Set(ctx context.Context, key string, value []byte, opt ...sessions.SessionStoreOption) error

func (*InstrumentedSessionStore) SetMany added in v0.18.3 

func (i *InstrumentedSessionStore) SetMany(ctx context.Context, values map[string][]byte, opt ...sessions.SessionStoreOption) error

type IntCodec added in v0.5.0 

type IntCodec struct{}

func (*IntCodec) Decode added in v0.5.0 

func (i *IntCodec) Decode(data []byte) (int, error)

func (*IntCodec) Encode added in v0.5.0 

func (i *IntCodec) Encode(value int) ([]byte, error)

type JSONCodec added in v0.5.0 

type JSONCodec[T any] struct{}

func (*JSONCodec[T]) Decode added in v0.5.0 

func (j *JSONCodec[T]) Decode(data []byte) (T, error)

func (*JSONCodec[T]) Encode added in v0.5.0 

func (j *JSONCodec[T]) Encode(value T) ([]byte, error)

type MemorySessionCache 

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

func NewMemorySessionCache 

func NewMemorySessionCache(otterOptions *otter.Options[string, []byte], ss sessions.SessionStore) (*MemorySessionCache, error)

func (*MemorySessionCache) Clear 

func (m *MemorySessionCache) Clear(ctx context.Context, opt ...sessions.SessionStoreOption) error

func (*MemorySessionCache) Delete 

func (m *MemorySessionCache) Delete(ctx context.Context, key string, opt ...sessions.SessionStoreOption) error

func (*MemorySessionCache) Get 

func (m *MemorySessionCache) Get(ctx context.Context, key string, opt ...sessions.SessionStoreOption) ([]byte, bool, error)

func (*MemorySessionCache) GetAll 

func (m *MemorySessionCache) GetAll(ctx context.Context, pageToken string, opt ...sessions.SessionStoreOption) (map[string][]byte, string, error)

GetAll always calls the backing store and caches the results.

func (*MemorySessionCache) GetMany 

func (m *MemorySessionCache) GetMany(ctx context.Context, keys []string, opt ...sessions.SessionStoreOption) (map[string][]byte, []string, error)

func (*MemorySessionCache) Set 

func (m *MemorySessionCache) Set(ctx context.Context, key string, value []byte, opt ...sessions.SessionStoreOption) error

func (*MemorySessionCache) SetMany 

func (m *MemorySessionCache) SetMany(ctx context.Context, values map[string][]byte, opt ...sessions.SessionStoreOption) error

type NoOpSessionStore added in v0.5.7 

type NoOpSessionStore struct{}

Don't panic in dev (ideally).

func (*NoOpSessionStore) Clear added in v0.5.7 

func (n *NoOpSessionStore) Clear(ctx context.Context, opt ...sessions.SessionStoreOption) error

func (*NoOpSessionStore) Delete added in v0.5.7 

func (n *NoOpSessionStore) Delete(ctx context.Context, key string, opt ...sessions.SessionStoreOption) error

func (*NoOpSessionStore) Get added in v0.5.7 

func (n *NoOpSessionStore) Get(ctx context.Context, key string, opt ...sessions.SessionStoreOption) ([]byte, bool, error)

func (*NoOpSessionStore) GetAll added in v0.5.7 

func (n *NoOpSessionStore) GetAll(ctx context.Context, pageToken string, opt ...sessions.SessionStoreOption) (map[string][]byte, string, error)

func (*NoOpSessionStore) GetMany added in v0.5.7 

func (n *NoOpSessionStore) GetMany(ctx context.Context, keys []string, opt ...sessions.SessionStoreOption) (map[string][]byte, []string, error)

func (*NoOpSessionStore) Set added in v0.5.7 

func (n *NoOpSessionStore) Set(ctx context.Context, key string, value []byte, opt ...sessions.SessionStoreOption) error

func (*NoOpSessionStore) SetMany added in v0.5.7 

func (n *NoOpSessionStore) SetMany(ctx context.Context, values map[string][]byte, opt ...sessions.SessionStoreOption) error

type SessionOpObserver added in v0.18.3 

type SessionOpObserver func(op string, elapsed time.Duration, err error)

SessionOpObserver receives one observation per session-store operation. Implementations must be safe for concurrent use.

type SessionOpStat added in v0.18.3 

type SessionOpStat struct {
	Count    int64
	Errors   int64
	Timeouts int64
	TotalMs  int64
	MaxMs    int64
}

SessionOpStat is one op's cumulative counters within a collection window. Timeouts are the deadline-exceeded subset of Errors — the signature of a backend whose every request times out before a fallback is MaxMs pinned at the deadline with Timeouts ≈ Count.

type SetManyable added in v0.5.3 

type SetManyable[T any] interface {
	SetMany(ctx context.Context, values map[string]T, opt ...sessions.SessionStoreOption) error
}

type SizedItem added in v0.6.7 

type SizedItem[T any] struct {
	Key   string
	Value T
	Size  int // size in bytes of key + value
}

SizedItem represents a key-value pair with its size in bytes.

type StringCodec added in v0.5.0 

type StringCodec struct{}

func (*StringCodec) Decode added in v0.5.0 

func (s *StringCodec) Decode(data []byte) (string, error)

func (*StringCodec) Encode added in v0.5.0 

func (s *StringCodec) Encode(value string) ([]byte, error)

type TypedSessionCache added in v0.5.0 

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

func NewIntSessionCache added in v0.5.0 

func NewIntSessionCache(cache sessions.SessionStore) *TypedSessionCache[int]

func NewJSONSessionCache added in v0.5.0 

func NewJSONSessionCache[T any](cache sessions.SessionStore) *TypedSessionCache[T]

func NewStringSessionCache added in v0.5.0 

func NewStringSessionCache(cache sessions.SessionStore) *TypedSessionCache[string]

func NewTypedSessionCache added in v0.5.0 

func NewTypedSessionCache[T any](cache sessions.SessionStore, codec Codec[T]) *TypedSessionCache[T]

func (*TypedSessionCache[T]) Clear added in v0.5.0 

func (t *TypedSessionCache[T]) Clear(ctx context.Context, opt ...sessions.SessionStoreOption) error

func (*TypedSessionCache[T]) Delete added in v0.5.0 

func (t *TypedSessionCache[T]) Delete(ctx context.Context, key string, opt ...sessions.SessionStoreOption) error

func (*TypedSessionCache[T]) Get added in v0.5.0 

func (t *TypedSessionCache[T]) Get(ctx context.Context, key string, opt ...sessions.SessionStoreOption) (T, bool, error)

func (*TypedSessionCache[T]) GetAll added in v0.5.0 

func (t *TypedSessionCache[T]) GetAll(ctx context.Context, pageToken string, opt ...sessions.SessionStoreOption) (map[string]T, string, error)

func (*TypedSessionCache[T]) GetMany added in v0.5.0 

func (t *TypedSessionCache[T]) GetMany(ctx context.Context, keys []string, opt ...sessions.SessionStoreOption) (map[string]T, []string, error)

func (*TypedSessionCache[T]) Set added in v0.5.0 

func (t *TypedSessionCache[T]) Set(ctx context.Context, key string, value T, opt ...sessions.SessionStoreOption) error

func (*TypedSessionCache[T]) SetMany added in v0.5.0 

func (t *TypedSessionCache[T]) SetMany(ctx context.Context, values map[string]T, opt ...sessions.SessionStoreOption) error

type UsageCollector added in v0.18.3 

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

UsageCollector accumulates session-store op stats for one request. It is carried in the request context so stats never outlive the request — no process-lifetime state, which keeps overlapping syncs sharing one warm container from cross-contaminating each other's numbers.

func UsageCollectorFromContext added in v0.18.3 

func UsageCollectorFromContext(ctx context.Context) *UsageCollector

UsageCollectorFromContext returns the collector installed by WithUsageCollector, or nil.

func WithUsageCollector added in v0.18.3 

func WithUsageCollector(ctx context.Context) (context.Context, *UsageCollector)

WithUsageCollector returns a child context carrying a fresh collector.

func (*UsageCollector) Annotation added in v0.18.3 

func (c *UsageCollector) Annotation() *v2.SessionStoreUsage

Annotation renders the collected stats as a SessionStoreUsage annotation message, or nil when nothing was recorded. Ops are sorted for stable output.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.