Documentation
¶
Overview ¶
Package valkey distributes monotonic policy revision invalidations through Valkey as advisory hints, not authorization or policy content. New borrows a native Client; Watch owns a Receive goroutine/ticker only until the call joins on cancellation. The client must cooperate; shutdown can otherwise block. Publish uses Lua numeric comparison, not an exact full-uint64 ordering primitive. Backend persistence/replication, credentials, retries and client close are deployment-owned; repository polling remains the authoritative correctness path.
Index ¶
- Constants
- Variables
- type Invalidator
- func (invalidator *Invalidator) Publish(ctx context.Context, revision authorization.Revision) (bool, error)
- func (invalidator *Invalidator) Revision(ctx context.Context) (authorization.Revision, error)
- func (invalidator *Invalidator) Watch(ctx context.Context, after authorization.Revision, ...) error
- type Options
Constants ¶
const ( // DefaultPrefix is the default Valkey key/channel namespace; applications own isolation. DefaultPrefix = "authorization" // DefaultPollInterval is the default 30-second advisory-key polling cadence. DefaultPollInterval = 30 * time.Second )
Variables ¶
var ( // ErrNilClient identifies authorization valkey client is nil. Compare with errors.Is, not error text. ErrNilClient = errors.New("authorization valkey client is nil") // ErrInvalidPrefix identifies authorization valkey prefix is invalid. Compare with errors.Is, not error text. ErrInvalidPrefix = errors.New("authorization valkey prefix is invalid") // ErrInvalidPollInterval identifies authorization valkey poll interval is invalid. Compare with errors.Is, not error text. ErrInvalidPollInterval = errors.New("authorization valkey poll interval is invalid") // ErrInvalidRevision identifies authorization valkey revision is invalid. Compare with errors.Is, not error text. ErrInvalidRevision = errors.New("authorization valkey revision is invalid") // ErrInvalidResponse identifies authorization valkey response is invalid. Compare with errors.Is, not error text. ErrInvalidResponse = errors.New("authorization valkey response is invalid") // ErrNilHandler identifies authorization valkey handler is nil. Compare with errors.Is, not error text. ErrNilHandler = errors.New("authorization valkey handler is nil") )
Functions ¶
This section is empty.
Types ¶
type Invalidator ¶
type Invalidator struct {
// contains filtered or unexported fields
}
Invalidator borrows a native client with no Close ownership; zero is unusable. Concurrent use depends on client/callback safety, not policy authentication.
func New ¶
func New(client native.Client, options Options) (*Invalidator, error)
New rejects literal nil clients and blank/negative settings, with default prefix/interval for zero fields. Typed-nil clients and callbacks are not panic-contained; caller namespace strings are not authenticated scope.
func (*Invalidator) Publish ¶
func (invalidator *Invalidator) Publish( ctx context.Context, revision authorization.Revision, ) (bool, error)
Publish atomically sets the key and emits a wakeup within one Lua operation. It rejects zero and otherwise delegates ordering to Lua tonumber, which is not an exact full-uint64 comparator; applications must stay within the backend's exact numeric domain. False means the script considered existing state >= next. Backend persistence/replication is not guaranteed, and an error can require reconciling unknown execution state. No authoritative policy data is published.
func (*Invalidator) Revision ¶
func (invalidator *Invalidator) Revision( ctx context.Context, ) (authorization.Revision, error)
Revision reads the current advisory key as exact nonzero uint64 decimal text. Missing keys return zero; deletion/eviction/restoration can remove/reset state, so zero is not proof that a policy was never published. Client response allocation, credentials, persistence and untrusted mutation remain external trust boundaries.
func (*Invalidator) Watch ¶
func (invalidator *Invalidator) Watch( ctx context.Context, after authorization.Revision, handler func(authorization.Revision) error, ) error
Watch observes newer revisions. Pub/sub only wakes the watcher; every notification triggers a key read and periodic polling continues after Receive exits (its error is not returned). The handler runs serially and advances the local after revision only on success; polling/key/handler errors stop the call. Cancellation joins Receive, requiring cooperative client I/O. Handler panics are not contained and its work is not preempted; repository verification belongs to the handler. The key is advisory and backend durability must be configured.
type Options ¶
type Options struct {
// Prefix selects Valkey key/channel names; empty chooses DefaultPrefix.
Prefix string
// PollInterval chooses periodic advisory-key reads; zero selects 30 seconds, negative is invalid.
PollInterval time.Duration
}
Options selects caller-owned key/channel namespace and polling cadence.
Source Files