Documentation
¶
Overview ¶
Package raw is the explicit trusted Redis command boundary. Normal application features use Foundry's typed cache, data, lease and pub/sub APIs. Commands here require scoped keys and typed decoders, but arbitrary arguments and Lua source are trusted code: Foundry cannot prove that they only refer to declared keys.
Index ¶
- Constants
- func Ignore[R any](p *Pipeline, c Command[R]) error
- type Argument
- type Backend
- type Builder
- type Command
- type Config
- type Declaration
- type Decoder
- func DecodeArray[R any](element Decoder[R]) Decoder[[]R]
- func DecodeBool() Decoder[bool]
- func DecodeBytes() Decoder[[]byte]
- func DecodeInt64() Decoder[int64]
- func DecodeNullable[R any](element Decoder[R]) Decoder[value.Nullable[R]]
- func DecodeString() Decoder[string]
- func DecodeUint64() Decoder[uint64]
- func DecodeWith[R any](fn func(context.Context, Reply) (R, error)) Decoder[R]
- type Key
- type Keys
- func (k Keys[K]) Delete(ctx context.Context, input K) (bool, error)
- func (k Keys[K]) DeleteMany(ctx context.Context, inputs ...K) (uint64, error)
- func (k Keys[K]) Exists(ctx context.Context, input K) (bool, error)
- func (k Keys[K]) Expire(ctx context.Context, input K, ttl cache.TTL) (bool, error)
- func (k Keys[K]) For(ctx context.Context, input K) (Key, error)
- func (k Keys[K]) Name() Name
- func (k Keys[K]) Version() Version
- type Limits
- type Mode
- type Name
- type Pipeline
- type Reply
- type ReplyLimits
- type Request
- type Result
- type Store
- type Version
Constants ¶
const ( MaxArguments = 256 MaxCommands = 256 MaxRequestBytes = 16 << 20 MaxArgumentBytes = 1 << 20 MaxScriptBytes = 64 << 10 MaxReplyBytes = 16 << 20 MaxReplyNodes = 65536 MaxReplyDepth = 64 )
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Argument ¶
type Argument struct {
// contains filtered or unexported fields
}
Argument snapshots one explicit raw value. Zero is invalid; empty Text/Bytes arguments are valid. Use Command.Key for additional keys, not Text(key.String()).
func Bytes ¶
Bytes copies data into an argument, returning an invalid argument if it exceeds MaxArgumentBytes.
type Backend ¶
type Backend interface {
// ExecuteRaw executes one validated request and returns a bounded owned reply without retrying.
ExecuteRaw(context.Context, Request, Limits) (Reply, error)
// ExecuteRawBatch executes the batch in the selected mode and bounds its combined replies.
ExecuteRawBatch(context.Context, []Request, Mode, Limits) ([]Reply, error)
// ExpireRaw atomically changes an existing key's expiry while preserving its contents.
ExpireRaw(context.Context, Key, cache.TTL) (bool, error)
}
Backend executes validated immutable requests without automatic retries. Batch errors may follow partial execution; Transaction errors do not roll back earlier successful commands. Capture and bound every reply, including ignored results. ExpireRaw uses one atomic native operation, preserving contents and returning true for an existing key even when Forever is already set. The caller owns the adapter lifecycle. A lost acknowledgement leaves the outcome unknown.
type Builder ¶
type Builder[R any] struct { // contains filtered or unexported fields }
Builder cannot execute until Key produces a Command. Prefix arguments support commands such as XGROUP CREATE whose key is not the first argument.
func NewCommand ¶
NewCommand constructs a builder with an uppercase command name and typed decoder. Invalid names and connection-state commands produce an invalid request.
type Command ¶
type Command[R any] struct { // contains filtered or unexported fields }
Command owns immutable arguments and a concrete result decoder. Lua source and raw arguments are trusted; declared key checks are not a sandbox for that code.
func NewScript ¶
NewScript uses a single EVAL with typed KEYS and explicit ARGV, without script cache fallback. It can also be queued in a Pipeline like any other command.
type Config ¶
type Config struct {
Namespace keyspace.Namespace
MaxDeclarations, MaxKeyBytes, MaxConcurrent int
Timeout time.Duration
Limits Limits
}
Config sets the raw store namespace, declaration capacity, concurrency, timeout, and request limits.
func DefaultConfig ¶
DefaultConfig returns bounded raw store defaults for the supplied namespace.
type Declaration ¶
type Declaration[K any] struct { // contains filtered or unexported fields }
Declaration retains a reusable raw key family identity and concrete key codec. Its zero value cannot bind.
func DefineKeys ¶
DefineKeys creates a reusable declaration without validating or binding it.
type Decoder ¶
type Decoder[R any] struct { // contains filtered or unexported fields }
Decoder preserves the command's concrete result type. Custom callbacks must be deterministic, concurrency-safe and return owned values. Execution owns their lifetime and catches panic/Goexit without abandoning uncooperative callbacks.
func DecodeArray ¶
DecodeArray decodes each array element in order and returns no partial result on failure.
func DecodeBool ¶
DecodeBool accepts integer replies of zero or one as false or true.
func DecodeBytes ¶
DecodeBytes accepts a text reply and returns an owned byte slice.
func DecodeNullable ¶
DecodeNullable maps a nil reply to null and delegates every other reply to element.
func DecodeUint64 ¶
DecodeUint64 accepts a nonnegative integer reply.
type Key ¶
type Key struct {
// contains filtered or unexported fields
}
Key is an explicit adapter address. Obtain it from Keys.For or FromDataKey. Possessing a key does not statically verify arbitrary command/script arguments.
func FromDataKey ¶
FromDataKey validates and preserves a typed data address for explicit raw operations.
type Keys ¶
type Keys[K any] struct { // contains filtered or unexported fields }
Keys preserves the domain resource type while resolving explicit raw addresses.
func (Keys[K]) DeleteMany ¶
DeleteMany encodes all input keys before one atomic DEL and returns a count of distinct existing keys. It never enumerates namespaces or retries an uncertain DEL.
func (Keys[K]) Exists ¶
Exists checks a resource of any native Redis data type through its typed key.
func (Keys[K]) Expire ¶
Expire changes an existing resource's TTL without replacing its contents. Forever removes expiry.
func (Keys[K]) For ¶
For encodes a resource key under the store's timeout and admission bounds without backend I/O.
type Limits ¶
type Limits struct {
Arguments, Commands, RequestBytes int
Reply ReplyLimits
}
Limits bounds request arguments, batch commands, request bytes, and captured replies.
func DefaultLimits ¶
func DefaultLimits() Limits
DefaultLimits returns bounded request and reply defaults with at most 64 batch commands.
type Mode ¶
type Mode uint8
Mode selects ordinary pipelining or a Redis transaction. Zero is invalid.
type Pipeline ¶
type Pipeline struct {
// contains filtered or unexported fields
}
Pipeline is built once and executed once. Queue operations and Run are serialized; whichever obtains the lock first determines inclusion. Execution consumes the pipeline even on failure. Construct another pipeline for a deliberate new attempt.
func NewPipeline ¶
NewPipeline validates mode and creates an empty pipeline for one execution.
func (*Pipeline) IsEmpty ¶
IsEmpty reports whether no commands remain queued, including for a nil pipeline.
type Reply ¶
type Reply struct {
// contains filtered or unexported fields
}
Reply is an immutable, owned RESP2 value for explicit decoders and adapters. Its zero value is Redis nil. Array returns a new slice of immutable child values.
func CaptureReplies ¶
CaptureReplies shares one budget across a complete pipeline, including its synthetic array root. Errors return no partial batch and do not expose payloads.
func CaptureReply ¶
CaptureReply is the adapter boundary for driver-decoded RESP2 (nil, int64, string, or []any). No driver types escape. Bounds apply after RESP parsing.
func (Reply) Array ¶
Array returns an owned slice of immutable children or fault.Invalid for another reply kind.
type ReplyLimits ¶
type ReplyLimits struct{ Bytes, Nodes, Depth int }
ReplyLimits apply to the complete reply, or the combined batch. They bound retained/captured replies after the driver parses RESP, not malicious server parser allocations. Depth counts the root as zero.
func DefaultReplyLimits ¶
func DefaultReplyLimits() ReplyLimits
DefaultReplyLimits returns reply bounds of 1 MiB, 8,192 nodes, and depth 32.
func (ReplyLimits) Validate ¶
func (l ReplyLimits) Validate() error
Validate checks byte, node, and depth bounds against the package maxima.
type Request ¶
type Request struct {
// contains filtered or unexported fields
}
Request is an immutable adapter invocation. Only a command containing a typed key, or a script constructor requiring a key, can produce one.
func (Request) Arguments ¶
Arguments returns owned command arguments (including its name) or script ARGV.
func (Request) Bytes ¶
Bytes returns the combined byte length of the command name, script source, and arguments.
type Result ¶
type Result[R any] struct { // contains filtered or unexported fields }
Result is a typed pipeline receipt. Value is available only after the entire execution and all decoders succeed. Repeated Value calls share the application's decoded value; callers own synchronization of any maps/slices it contains.
Source Files