Struct Context

pub struct Context {
    pub ctx: *mut RedisModuleCtx,
}

Context is a structure that’s designed to give us a high-level interface to the Valkey module API by abstracting away the raw C FFI calls.

Fields

ctx: *mut RedisModuleCtx

Implementations

impl Context

pub fn create_timer<F, T: 'static>( &self, period: Duration, callback: F, data: T, ) -> RedisModuleTimerID

where F: FnOnce(&Self, T),

Wrapper for RedisModule_CreateTimer.

This function takes ownership of the provided data, and transfers it to Redis. The callback will get the original data back in a type safe manner. When the callback is done, the data will be dropped.

pub fn stop_timer<T>( &self, timer_id: RedisModuleTimerID, ) -> Result<T, ValkeyError>

Wrapper for RedisModule_StopTimer.

The caller is responsible for specifying the correct type for the returned data. This function has no way to know what the original type of the data was, so the same data type that was used for create_timer needs to be passed here to ensure their types are identical.

pub fn get_timer_info<T>( &self, timer_id: RedisModuleTimerID, ) -> Result<(Duration, &T), ValkeyError>

Wrapper for RedisModule_GetTimerInfo.

The caller is responsible for specifying the correct type for the returned data. This function has no way to know what the original type of the data was, so the same data type that was used for create_timer needs to be passed here to ensure their types are identical.

impl Context

pub fn authenticate_client_with_acl_user( &self, username: &ValkeyString, ) -> Status

Authenticates a client using an ACL user

Arguments

• username - ACL username to authenticate with

Returns

• Status::Ok - Authentication successful
• Status::Err - Authentication failed

impl Context

pub fn block_client(&self) -> BlockedClient

impl Context

GetClientNameById, GetClientUserNameById and GetClientCertificate use autoMemoryAdd on the ValkeyModuleString pointer after the callback (command, server event handler, …) these ValkeyModuleString pointers will be freed automatically

pub fn get_client_id(&self) -> u64

pub fn get_client_name_by_id( &self, client_id: u64, ) -> ValkeyResult<ValkeyString>

wrapper for RedisModule_GetClientNameById

pub fn get_client_name(&self) -> ValkeyResult<ValkeyString>

wrapper for RedisModule_GetClientNameById using current client ID

pub fn set_client_name_by_id( &self, client_id: u64, client_name: &ValkeyString, ) -> Status

wrapper for RedisModule_SetClientNameById

pub fn set_client_name(&self, client_name: &ValkeyString) -> Status

wrapper for RedisModule_SetClientNameById using current client ID

pub fn get_client_username_by_id( &self, client_id: u64, ) -> ValkeyResult<ValkeyString>

wrapper for RedisModule_GetClientUserNameById

pub fn get_client_username(&self) -> ValkeyResult<ValkeyString>

wrapper for RedisModule_GetClientUserNameById using current client ID

pub fn get_client_cert(&self) -> ValkeyResult<ValkeyString>

wrapper for RedisModule_GetClientCertificate

pub fn get_client_info_by_id( &self, client_id: u64, ) -> ValkeyResult<RedisModuleClientInfo>

wrapper for RedisModule_GetClientInfoById

pub fn get_client_info(&self) -> ValkeyResult<RedisModuleClientInfo>

wrapper for RedisModule_GetClientInfoById using current client ID

pub fn get_client_ip_by_id(&self, client_id: u64) -> ValkeyResult<String>

wrapper to get the client IP address from RedisModuleClientInfo

pub fn get_client_ip(&self) -> String

wrapper to get the client IP address from RedisModuleClientInfo using current client ID

impl Context

adding functions to the Context struct to provide a higher level interface to register and unregister filters

pub fn register_command_filter( &self, module_cmd_filter_func: extern "C" fn(*mut RedisModuleCommandFilterCtx), flags: u32, ) -> CommandFilter

wrapper for RedisModule_RegisterCommandFilter to directly register a filter, likely in init

pub fn unregister_command_filter(&self, cmd_filter: &CommandFilter)

wrapper for RedisModule_UnregisterCommandFilter to directly unregister filter, likely in deinit

impl Context

pub fn server_info(&self, section: &str) -> ServerInfo

impl Context

pub const fn new(ctx: *mut RedisModuleCtx) -> Self

pub const fn dummy() -> Self

pub fn log(&self, level: ValkeyLogLevel, message: &str)

pub fn log_debug(&self, message: &str)

pub fn log_notice(&self, message: &str)

pub fn log_verbose(&self, message: &str)

pub fn log_warning(&self, message: &str)

pub fn auto_memory(&self)

Panics

Will panic if RedisModule_AutoMemory is missing in redismodule.h

pub fn is_keys_position_request(&self) -> bool

Panics

Will panic if RedisModule_IsKeysPositionRequest is missing in redismodule.h

pub fn key_at_pos(&self, pos: i32)

Panics

Will panic if RedisModule_KeyAtPos is missing in redismodule.h

pub fn call<'a, T: Into<StrCallArgs<'a>>>( &self, command: &str, args: T, ) -> ValkeyResult

pub fn call_ext<'a, T: Into<StrCallArgs<'a>>, R: From<CallResult<'static>>>( &self, command: &str, options: &CallOptions, args: T, ) -> R

Invoke a command on Valkey and return the result Unlike ‘call’ this API also allow to pass a CallOption to control different aspects of the command invocation.

pub fn str_as_legal_resp_string(s: &str) -> CString

pub fn reply_simple_string(&self, s: &str) -> Status

pub fn reply_error_string(&self, s: &str) -> Status

pub fn reply_with_key(&self, result: ValkeyValueKey) -> Status

pub fn reply(&self, result: ValkeyResult) -> Status

Panics

Will panic if methods used are missing in redismodule.h

pub fn open_key(&self, key: &ValkeyString) -> ValkeyKey

pub fn open_key_with_flags( &self, key: &ValkeyString, flags: KeyFlags, ) -> ValkeyKey

pub fn open_key_writable(&self, key: &ValkeyString) -> ValkeyKeyWritable

pub fn open_key_writable_with_flags( &self, key: &ValkeyString, flags: KeyFlags, ) -> ValkeyKeyWritable

pub fn replicate_verbatim(&self)

pub fn replicate<'a, T: Into<StrCallArgs<'a>>>(&self, command: &str, args: T)

Replicate command to the replica and AOF.

pub fn create_string<T: Into<Vec<u8>>>(&self, s: T) -> ValkeyString

pub const fn get_raw(&self) -> *mut RedisModuleCtx

pub unsafe fn export_shared_api(&self, func: *const c_void, name: *const c_char)

Safety

See raw::export_shared_api.

pub fn notify_keyspace_event( &self, event_type: NotifyEvent, event: &str, keyname: &ValkeyString, ) -> Status

Safety

See raw::notify_keyspace_event.

pub fn current_command_name(&self) -> Result<String, ValkeyError>

pub fn get_server_version(&self) -> Result<Version, ValkeyError>

Returns the valkey version either by calling RedisModule_GetServerVersion API, Or if it is not available, by calling “info server” API and parsing the reply

pub fn get_server_version_rm_call(&self) -> Result<Version, ValkeyError>

Returns the valkey version by calling “info server” API and parsing the reply

pub fn version_from_info(info: ValkeyValue) -> Result<Version, ValkeyError>

pub fn set_module_options(&self, options: ModuleOptions)

pub fn get_flags(&self) -> ContextFlags

Return ContextFlags object that allows to check properties related to the state of the current Valkey instance such as:

• Role (master/slave)
• Loading RDB/AOF
• Execution mode such as multi exec or Lua

pub fn get_current_user(&self) -> ValkeyString

Return the current user name attached to the context

pub fn authenticate_user( &self, user_name: &ValkeyString, ) -> Result<ContextUserScope<'_>, ValkeyError>

Attach the given user to the current context so each operation performed from now on using this context will be validated againts this new user. Return [ContextUserScope] which make sure to unset the user when freed and can not outlive the current Context.

pub fn acl_check_key_permission( &self, user_name: &ValkeyString, key_name: &ValkeyString, permissions: &AclPermissions, ) -> Result<(), ValkeyError>

Verify the the given user has the give ACL permission on the given key. Return Ok(()) if the user has the permissions or error (with relevant error message) if the validation failed.

pub fn add_post_notification_job<F: FnOnce(&Context) + 'static>( &self, callback: F, ) -> APIResult<Status>

When running inside a key space notification callback, it is dangerous and highly discouraged to perform any write operation. In order to still perform write actions in this scenario, Valkey provides this API ([add_post_notification_job]) that allows to register a job callback which Valkey will call when the following condition holds:

1. It is safe to perform any write operation.
2. The job will be called atomically along side the key space notification.

Notice, one job might trigger key space notifications that will trigger more jobs. This raises a concerns of entering an infinite loops, we consider infinite loops as a logical bug that need to be fixed in the module, an attempt to protect against infinite loops by halting the execution could result in violation of the feature correctness and so Valkey will make no attempt to protect the module from infinite loops.

pub fn avoid_replication_traffic(&self) -> bool

Returns true if a client sent the CLIENT PAUSE command to the server or if Valkey Cluster does a manual failover, pausing the clients. This is needed when we have a master with replicas, and want to write, without adding further data to the replication channel, that the replicas replication offset, match the one of the master. When this happens, it is safe to failover the master without data loss.

However modules may generate traffic by calling commands or directly send data to the replication stream.

So modules may want to try to avoid very heavy background work that has the effect of creating data to the replication channel, when this function returns true. This is mostly useful for modules that have background garbage collection tasks, or that do writes and replicate such writes periodically in timer callbacks or other periodic callbacks.

Trait Implementations

impl Borrow<Context> for ContextGuard

fn borrow(&self) -> &Context

Immutably borrows from an owned value.

impl Debug for Context

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl ValkeyLockIndicator for Context