Redis Functions Flags

Following the discussion on #10025 Added Functions Flags support. The PR is divided to 2 sections:

• Add named argument support to redis.register_function API.
• Add support for function flags

redis.register_function named argument support

The first part of the PR adds support for named argument on redis.register_function, example:

redis.register_function{
    function_name='f1',
    callback=function()
        return 'hello'
    end,
    description='some desc'
}

The positional arguments is also kept, which means that it still possible to write:

redis.register_function('f1', function() return 'hello' end)

But notice that it is no longer possible to pass the optional description argument on the positional argument version. Positional argument was change to allow passing only the mandatory arguments (function name and callback). To pass more arguments the user must use the named argument version.

As with positional arguments, the function_name and callback is mandatory and an error will be raise if those are missing. Also, an error will be raise if an unknown argument name is given or the arguments type is wrong.

Tests was added to verify the new syntax.

Functions Flags

The second part of the PR is adding functions flags support. Flags are given to Redis when the engine calls functionLibCreateFunction, supported flags are:

• no-writes - indicating the function perform no writes which means that it is OK to run it on:

  • read-only replica
  • Using FCALL_RO
  • If disk error detected

  It will not be possible to run a function in those situations unless the function turns on the no-writes flag

• allow-oom - indicate that its OK to run the function even if Redis is in OOM state, if the function will not turn on this flag it will not be possible to run it if OOM reached. If this flag is set, any command will be allow on OOM (even those that is marked with CMD_DENYOOM). The assumption is that this flag is for advance users that knows its meaning and understand what they are doing, and Redis trust them to not increase the memory usage. (e.g. it could be an INCR or a modification on an existing key, or a DEL command)
  Note: starting with redis 7.0.1, the no-writes flag also implies allow-oom, so read-only scripts (including ones used by FCALL_RO and EVAL_RO) can run in OOM state without explicitly specifying this flag. see Scripts that declare the no-writes flag are implicitly allow-oom too. #10699

• allow-state - indicate that its OK to run the function on stale replica, in this case we will also make sure the function is only perform stale commands and raise an error if not.

• no-cluster - indicate to disallow running the function if cluster is enabled.

Default behaviure of functions (if no flags is given):

1. Allow functions to read and write
2. Do not run functions on OOM
3. Do not run functions on stale replica
4. Allow functions on cluster

Lua API for functions flags

On Lua engine, it is possible to give functions flags as flags named argument:

redis.register_function{function_name='f1', callback=function() return 1 end, flags={'no-writes', 'allow-oom'}, description='description'}

The function flags argument must be a Lua table that contains all the requested flags, The following will result in an error:

• Unknown flag
• Wrong flag type

Default behaviour is the same as if no flags are used.

Tests were added to verify all flags functionality

Additional changes

• mark FCALL and FCALL_RO with CMD_STALE flag (unlike EVAL), so that they can run if the function was registered with the allow-stale flag.
• Verify CMD_STALE on scriptCall (redis.call), so it will not be possible to call commands from script while stale unless the command is marked with the CMD_STALE flags. so that even if the function is allowed while stale we do not allow it to bypass the CMD_STALE flag of commands.
• Flags section was added to FUNCTION LIST command to provide the set of flags for each function:

> FUNCTION list withcode
1)  1) "library_name"
    2) "test"
    3) "engine"
    4) "LUA"
    5) "description"
    6) (nil)
    7) "functions"
    8) 1) 1) "name"
          2) "f1"
          3) "description"
          4) (nil)
          5) "flags"
          6) (empty array)
    9) "library_code"
   10) "redis.register_function{function_name='f1', callback=function() return 1 end}"

• Added API to get Redis version from within a script, The redis version can be provided using:

  1. redis.REDIS_VERSION - string representation of the redis version in the format of MAJOR.MINOR.PATH
  2. redis.REDIS_VERSION_NUM - number representation of the redis version in the format of 0x00MMmmpp (MM - major, mm - minor, pp - patch). The number version can be used to check if version is greater or less another version. The string version can be used to return to the user or print as logs.

  This new API is provided to eval scripts and functions, it also possible to use this API during functions loading phase.

Considerations

• After discussion with @oranagra, @yossigo and @guybe7 we decided User experience should be smooth even at the cost of not matching functions flags to modules and commands flags. This is why we see different flags for functions on this PR.

todo:

• Decide if we want to allow EVAL\_RO, EVALSHA\_RO to be allowed while stale and in worst case, if the script performs a command which is not allowed while stale, an error will be raised.
  • An argument against it is that scripts that publish some data and then read some data from the key space will fail when trying to read data and after already performed the publish command. This can be considered as breaking change and maybe even break atomicity?
  • An argument in favor is that we already have such issue with write commands.
• Add functions flags to function list
• redis.version API