script flags update (redis#1954)

updating docs about read only scripts and oom related flag changes in 7.0.1

Author: oranagra

commands/command.md

@@ -64,7 +64,6 @@ Command flags are an array. It can contain the following simple strings (status
 * **fast:** the command operates in constant or log(N) time.
   This flag is used for monitoring latency with the `LATENCY` command.
 * **loading:** the command is allowed while the database is loading.
-* **may_replicate:** the command may be replicated to replicas and the AOF.
 * **movablekeys:** the _first key_, _last key_, and _step_ values don't determine all key positions.
   Clients need to use `COMMAND GETKEYS` or [key specifications][td] in this case.
   See below for more details.

commands/eval_ro.md

@@ -1,6 +1,6 @@
 This is a read-only variant of the `EVAL` command that cannot execute commands that modify data.
 
-For more information about when to use this command vs `EVAL`, please refer to [Read-only scripts](/docs/manual/programmability/#Read-only_scripts).
+For more information about when to use this command vs `EVAL`, please refer to [Read-only scripts](/docs/manual/programmability/#read-only_scripts).
 
 For more information about `EVAL` scripts please refer to [Introduction to Eval Scripts](/topics/eval-intro).
 

commands/evalsha_ro.md

@@ -1,5 +1,5 @@
 This is a read-only variant of the `EVALSHA` command that cannot execute commands that modify data.
 
-For more information about when to use this command vs `EVALSHA`, please refer to [Read-only scripts](/docs/manual/programmability/#Read-only_scripts).
+For more information about when to use this command vs `EVALSHA`, please refer to [Read-only scripts](/docs/manual/programmability/#read-only_scripts).
 
 For more information about `EVALSHA` scripts please refer to [Introduction to Eval Scripts](/topics/eval-intro).

commands/fcall_ro.md

@@ -1,5 +1,5 @@
 This is a read-only variant of the `FCALL` command that cannot execute commands that modify data.
 
-For more information about when to use this command vs `FCALL`, please refer to [Read-only scripts](/docs/manual/programmability/#Read-only_scripts).
+For more information about when to use this command vs `FCALL`, please refer to [Read-only scripts](/docs/manual/programmability/#read-only_scripts).
 
 For more information please refer to [Introduction to Redis Functions](/topics/functions-intro).

docs/manual/programmability/_index.md

@@ -62,13 +62,31 @@ However, if you intend to use a slow script in your application, be aware that a
 ## Read-only scripts
 
 A read-only script is a script that only executes commands that don't modify any keys within Redis.
-Read-only scripts are useful because they can always be executed on replicas and can always be killed by the `SCRIPT KILL` command. 
-Read-only scripts can be executed either by adding the `no-writes` flag to the script or by executing the script with one of the read-only script command variants: `EVAL_RO`, `EVALSHA_RO`, or `FCALL_RO`.
-In addition to the benefits provided by all read-only scripts, the read-only script commands are also not blocked during write pauses, such as those that occur during coordinated failovers, and can be used to configure an ACL user to only be able to execute read-only scripts.
-Many clients also better support routing the read-only script commands to replicas for applications that want to use replicas for read scaling.
+Read-only scripts can be executed either by adding the `no-writes` [flag](/topics/lua-api#script_flags) to the script or by executing the script with one of the read-only script command variants: `EVAL_RO`, `EVALSHA_RO`, or `FCALL_RO`.
+They have the following properties:
+
+* They can always be executed on replicas.
+* They can always be killed by the `SCRIPT KILL` command. 
+* They never fail with OOM error when redis is over the memory limit.
+* They are not blocked during write pauses, such as those that occur during coordinated failovers.
+* They cannot execute any command that may modify the data set.
+* Currently `PUBLISH`, `SPUBLISH` and `PFCOUNT` are also considered write commands in scripts, because they could attempt to propagate commands to replicas and AOF file.
+
+In addition to the benefits provided by all read-only scripts, the read-only script commands have the following advantages:
+
+* They can be used to configure an ACL user to only be able to execute read-only scripts.
+* Many clients also better support routing the read-only script commands to replicas for applications that want to use replicas for read scaling.
+
+#### Read-only script history
+
+Read-only scripts and read-only script commands were introduced in Redis 7.0
+
+* Before Redis 7.0.1 `PUBLISH`, `SPUBLISH` and `PFCOUNT` were not considered write commands in scripts
+* Before Redis 7.0.1 the `no-writes` [flag](/topics/lua-api#script_flags) did not imply `allow-oom`
+* Before Redis 7.0.1 the `no-writes` flag did not permit the script to run during write pauses.
+
 
 The recommended approach is to use the standard scripting commands with the `no-writes` flag unless you need one of the previously mentioned features.
-In future versions of Redis, this extra functionality may become available to all scripts that declare the `no-writes` flag.
 
 ## Sandboxed script context
 

docs/manual/programmability/lua-api.md

@@ -454,25 +454,32 @@ You can use the following flags and instruct the server to treat the scripts' ex
 
 * `no-writes`: this flag indicates that the script only reads data but never writes.
 
-    By default, Redis will deny the execution of scripts against read-only replicas, as they may attempt to perform writes.
+    By default, Redis will deny the execution of flagged scripts (Functions and Eval scripts with [shebang](/topics/eval-intro#eval-flags)) against read-only replicas, as they may attempt to perform writes.
     Similarly, the server will not allow calling scripts with `FCALL_RO` / `EVAL_RO`.
     Lastly, when data persistence is at risk due to a disk error, execution is blocked as well.
 
     Using this flag allows executing the script:
-    1. With `FCALL_RO` / `EVAL_RO` against masters and read-only replicas.
-    2. Even if there's a disk error (Redis is unable to persist so it rejects writes).
+    1. With `FCALL_RO` / `EVAL_RO`
+    2. On read-only replicas.
+    3. Even if there's a disk error (Redis is unable to persist so it rejects writes).
+    4. When over the memory limit since it implies the script doesn't increase memory consumption (see `allow-oom` below)
 
     However, note that the server will return an error if the script attempts to call a write command.
+    Also note that currently `PUBLISH`, `SPUBLISH` and `PFCOUNT` are also considered write commands in scripts, because they could attempt to propagate commands to replicas and AOF file.
+
+    For more information please refer to [Read-only scripts](/docs/manual/programmability/#read-only_scripts)
 
 * `allow-oom`: use this flag to allow a script to execute when the server is out of memory (OOM).
 
-    Unless used, Redis will deny the execution of scripts when in an OOM state, regardless of the `no-write` flag and method of calling.
+    Unless used, Redis will deny the execution of flagged scripts (Functions and Eval scripts with [shebang](/topics/eval-intro#eval-flags)) when in an OOM state.
     Furthermore, when you use this flag, the script can call any Redis command, including commands that aren't usually allowed in this state.
+    Specifying `no-writes` or using `FCALL_RO` / `EVAL_RO` also implies the script can run in OOM state (without specifying `allow-oom`)
 
-* `allow-stale`: a flag that enables running the script against a stale replica.
+* `allow-stale`: a flag that enables running the flagged scripts (Functions and Eval scripts with [shebang](/topics/eval-intro#eval-flags)) against a stale replica when the `replica-serve-stale-data` config is set to `no` .
 
-    By default, Redis prevents data consistency problems from using old data by having stale replicas return a runtime error.
-    In cases where the consistency is a lesser concern, this flag allows stale Redis replicas to run the script.
+    Redis can be set to prevent data consistency problems from using old data by having stale replicas return a runtime error.
+    For scripts that do not access the data, this flag can be set to allow stale Redis replicas to run the script.
+    Note however that the script will still be unable to execute any command that accesses stale data.
 
 * `no-cluster`: the flag causes the script to return an error in Redis cluster mode.