Documentation
¶
Overview ¶
Package operations provides cache operations with automatic routing. This package is used by both the gRPC service layer and the embedded client.
Index ¶
- Constants
- type ContinuationToken
- type DeleteError
- type NodeResponse
- type Operations
- func (o *Operations) Delete(ctx context.Context, key string) error
- func (o *Operations) DeleteLocal(ctx context.Context, key string) error
- func (o *Operations) Get(ctx context.Context, key string, start, end int64) (io.Reader, bool, error)
- func (o *Operations) GetBytes(ctx context.Context, key string) ([]byte, bool, error)
- func (o *Operations) GetCoordinator() *coordinator.Coordinator
- func (o *Operations) GetLocal(ctx context.Context, key string, start, end int64) (io.Reader, bool, error)
- func (o *Operations) GetLocalNodeID() string
- func (o *Operations) GetRange(ctx context.Context, key string, start, end int64) ([]byte, bool, error)
- func (o *Operations) GetRangeStream(ctx context.Context, key string, start, end int64, w io.Writer) (bool, error)
- func (o *Operations) GetRing() *ring.RingManager
- func (o *Operations) GetRouter() *coordinator.Router
- func (o *Operations) GetStorage() *stor.Storage
- func (o *Operations) GetStream(ctx context.Context, key string, w io.Writer) (bool, error)
- func (o *Operations) IsClusterMode() bool
- func (o *Operations) IsLocal(key string) bool
- func (o *Operations) IsReady() bool
- func (o *Operations) List(ctx context.Context, prefix string) ([]string, error)
- func (o *Operations) ListLocal(ctx context.Context, prefix string, limit int, continuationToken string) ([]string, string, bool, error)
- func (o *Operations) ListLocalWithValues(ctx context.Context, prefix string, limit int, continuationToken string) ([]*pb.KeyValue, string, bool, error)
- func (o *Operations) ListPage(ctx context.Context, prefix string, limit int, continuationToken string) ([]string, string, bool, error)
- func (o *Operations) ListPageWithValues(ctx context.Context, prefix string, limit int, continuationToken string) ([]*pb.KeyValue, string, bool, error)
- func (o *Operations) Put(ctx context.Context, key string, body io.Reader, ttl int) error
- func (o *Operations) PutBytes(ctx context.Context, key string, data []byte, ttl int) error
- func (o *Operations) PutLocal(ctx context.Context, key string, body io.Reader, ttl int) error
- func (o *Operations) Route(key string) (pb.CacheServiceClient, error)
- type PutError
Constants ¶
const ( // MaxListLimit is the maximum number of keys to return in a single List call MaxListLimit = 1000 // DefaultListLimit is the default limit if not specified DefaultListLimit = 1000 )
const ( // DefaultStreamBufferSize is the default buffer size for streaming operations DefaultStreamBufferSize = 1 << 20 // 1 MiB )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ContinuationToken ¶
type ContinuationToken struct {
NodeCursors map[string]string `json:"node_cursors"` // nodeID -> last_key_from_node
Prefix string `json:"prefix"` // Original prefix filter
}
ContinuationToken represents the state for resuming a paginated list operation
type DeleteError ¶
type DeleteError struct {
Message string
}
DeleteError represents an error from a Delete operation.
func (*DeleteError) Error ¶
func (e *DeleteError) Error() string
type NodeResponse ¶
type NodeResponse struct {
NodeID string
Keys []string // populated in keys-only mode
Entries []*pb.KeyValue // populated in withValues mode
ContinuationToken string
HasMore bool
}
NodeResponse holds the response from a single node. In keys-only mode, Keys is populated. In withValues mode, Entries is populated.
type Operations ¶
type Operations struct {
// contains filtered or unexported fields
}
Operations provides cache operations with automatic routing. For local keys, it accesses storage directly. For remote keys, it routes via gRPC to the appropriate node.
func New ¶
func New(storage *stor.Storage, coord *coordinator.Coordinator) *Operations
New creates a new Operations instance.
func (*Operations) Delete ¶
func (o *Operations) Delete(ctx context.Context, key string) error
Delete removes a key with automatic routing. If the key is local, it deletes from local storage. If the key is remote, it sends delete request via gRPC to the appropriate node.
func (*Operations) DeleteLocal ¶
func (o *Operations) DeleteLocal(ctx context.Context, key string) error
DeleteLocal deletes a key from local storage directly.
func (*Operations) Get ¶
func (o *Operations) Get(ctx context.Context, key string, start, end int64) (io.Reader, bool, error)
Get retrieves data for the given key with automatic routing. If the key is local, it accesses storage directly. If the key is remote, it fetches via gRPC from the appropriate node. The start and end parameters specify byte range (0, 0 for full content). Returns (reader, found, error).
func (*Operations) GetBytes ¶
GetBytes retrieves data as a byte slice with automatic routing. This is a convenience method that reads all data into memory.
func (*Operations) GetCoordinator ¶
func (o *Operations) GetCoordinator() *coordinator.Coordinator
GetCoordinator returns the underlying coordinator. This is primarily for testing and advanced use cases.
func (*Operations) GetLocal ¶
func (o *Operations) GetLocal(ctx context.Context, key string, start, end int64) (io.Reader, bool, error)
GetLocal retrieves data from local storage directly. This is used by CacheService for streaming and by embedded clients for local access.
func (*Operations) GetLocalNodeID ¶
func (o *Operations) GetLocalNodeID() string
GetLocalNodeID returns the local node's ID. Returns empty string if clustering is disabled.
func (*Operations) GetRange ¶
func (o *Operations) GetRange(ctx context.Context, key string, start, end int64) ([]byte, bool, error)
GetRange retrieves a byte range as a byte slice with automatic routing.
func (*Operations) GetRangeStream ¶
func (o *Operations) GetRangeStream(ctx context.Context, key string, start, end int64, w io.Writer) (bool, error)
GetRangeStream retrieves a byte range and writes it to the provided writer.
func (*Operations) GetRing ¶
func (o *Operations) GetRing() *ring.RingManager
GetRing returns the ring manager for cluster topology. Returns nil if clustering is disabled.
func (*Operations) GetRouter ¶
func (o *Operations) GetRouter() *coordinator.Router
GetRouter returns the router for getting remote clients. Returns nil if clustering is disabled.
func (*Operations) GetStorage ¶
func (o *Operations) GetStorage() *stor.Storage
GetStorage returns the underlying storage. This is primarily for testing and advanced use cases.
func (*Operations) GetStream ¶
GetStream retrieves data and writes it to the provided writer with automatic routing.
func (*Operations) IsClusterMode ¶
func (o *Operations) IsClusterMode() bool
IsClusterMode returns true if clustering is enabled.
func (*Operations) IsLocal ¶
func (o *Operations) IsLocal(key string) bool
IsLocal checks if a key belongs to the local node. Returns true if clustering is disabled or if the key is owned by this node.
func (*Operations) IsReady ¶
func (o *Operations) IsReady() bool
IsReady returns true if the operations layer is ready to serve requests. In cluster mode, this checks if the coordinator is ready.
func (*Operations) List ¶
List returns all keys matching prefix across the entire cluster. In cluster mode, performs K-way merge from all nodes. In single-node mode, queries local storage directly.
func (*Operations) ListLocal ¶
func (o *Operations) ListLocal(ctx context.Context, prefix string, limit int, continuationToken string) ([]string, string, bool, error)
ListLocal returns keys from local storage only.
func (*Operations) ListLocalWithValues ¶
func (o *Operations) ListLocalWithValues(ctx context.Context, prefix string, limit int, continuationToken string) ([]*pb.KeyValue, string, bool, error)
ListLocalWithValues returns key-value pairs from local storage only.
func (*Operations) ListPage ¶
func (o *Operations) ListPage(ctx context.Context, prefix string, limit int, continuationToken string) ([]string, string, bool, error)
ListPage returns a page of keys with pagination support. In cluster mode, performs K-way merge from all nodes. In single-node mode, queries local storage directly. Returns (keys, continuationToken, hasMore, error).
func (*Operations) ListPageWithValues ¶
func (o *Operations) ListPageWithValues(ctx context.Context, prefix string, limit int, continuationToken string) ([]*pb.KeyValue, string, bool, error)
ListPageWithValues returns a page of key-value pairs with pagination support. In cluster mode, performs K-way merge from all nodes. In single-node mode, queries local storage directly.
func (*Operations) Put ¶
Put stores data for the given key with automatic routing. If the key is local, it stores directly in storage. If the key is remote, it sends via gRPC to the appropriate node.
func (*Operations) PutBytes ¶
PutBytes stores a byte slice for the given key with automatic routing. This is a convenience method that wraps the byte slice in a reader.
func (*Operations) PutLocal ¶
PutLocal stores data in local storage directly. If the body implements io.Seeker (e.g., bytes.Reader), retries are enabled with automatic reset. For non-seekable readers (e.g., io.PipeReader from streaming), no retries are attempted since the reader cannot be rewound.
func (*Operations) Route ¶
func (o *Operations) Route(key string) (pb.CacheServiceClient, error)
Route returns a gRPC client for the node that owns the given key. Returns an error if the key is local (caller should check IsLocal first).
Source Files