Skip to content

Commit c6893e3

Browse files
committed
Address misleading documentation
Remove references that mention SHA-1 hashes being passed when evaluating server loaded Lua scripts. The current implementation passes the script itself instead of the hash, generated when the script was initially loaded, due to resiliency concerns.
1 parent 571d832 commit c6893e3

File tree

2 files changed

+23
-11
lines changed

2 files changed

+23
-11
lines changed

docs/Scripting.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -35,10 +35,10 @@ Any object that exposes field or property members with the same name as @-prefix
3535
- RedisKey
3636
- RedisValue
3737

38-
StackExchange.Redis handles Lua script caching internally. It automatically transmits the Lua script to redis on the first call to 'ScriptEvaluate'. For further calls of the same script only the hash with [`EVALSHA`](https://redis.io/commands/evalsha) is used.
38+
StackExchange.Redis handles Lua script caching internally. It automatically transmits the Lua script to redis on the first call to 'ScriptEvaluate'. For further calls of the same script [`EVAL`](https://redis.io/commands/eval) is used instead of [`EVALSHA`](https://redis.io/commands/evalsha), due to resiliency concerns.
3939

4040
For more control of the Lua script transmission to redis, `LuaScript` objects can be converted into `LoadedLuaScript`s via `LuaScript.Load(IServer)`.
41-
`LoadedLuaScripts` are evaluated with the [`EVALSHA`](https://redis.io/commands/evalsha), and referred to by hash.
41+
`LoadedLuaScripts` are evaluated with the [`EVAL`](https://redis.io/commands/eval) command instead of [`EVALSHA`](https://redis.io/commands/evalsha), due to resiliency concerns.
4242

4343
An example use of `LoadedLuaScript`:
4444

src/StackExchange.Redis/LuaScript.cs

+21-9
Original file line numberDiff line numberDiff line change
@@ -166,13 +166,16 @@ public Task<RedisResult> EvaluateAsync(IDatabaseAsync db, object? ps = null, Red
166166

167167
/// <summary>
168168
/// <para>
169-
/// Loads this LuaScript into the given IServer so it can be run with it's SHA1 hash, instead of
170-
/// using the implicit SHA1 hash that's calculated after the script is sent to the server for the first time.
169+
/// Loads this LuaScript into the given IServer. Due to resiliency concerns, the LoadedLuaScript
170+
/// does not evaluate the script by it's SHA-1 hash anymore.
171171
/// </para>
172172
/// <para>Note: the FireAndForget command flag cannot be set.</para>
173173
/// </summary>
174174
/// <param name="server">The server to load the script on.</param>
175175
/// <param name="flags">The command flags to use.</param>
176+
/// <remarks>
177+
/// Previously, this method was intended provide scripts, that can be evaluated by their SHA-1 hashes.
178+
/// </remarks>
176179
public LoadedLuaScript Load(IServer server, CommandFlags flags = CommandFlags.None)
177180
{
178181
if ((flags & CommandFlags.FireAndForget) != 0)
@@ -186,13 +189,16 @@ public LoadedLuaScript Load(IServer server, CommandFlags flags = CommandFlags.No
186189

187190
/// <summary>
188191
/// <para>
189-
/// Loads this LuaScript into the given IServer so it can be run with it's SHA1 hash, instead of
190-
/// using the implicit SHA1 hash that's calculated after the script is sent to the server for the first time.
192+
/// Loads this LuaScript into the given IServer. Due to resiliency concerns, the LoadedLuaScript
193+
/// does not evaluate the script by it's SHA-1 hash anymore.
191194
/// </para>
192195
/// <para>Note: the FireAndForget command flag cannot be set</para>
193196
/// </summary>
194197
/// <param name="server">The server to load the script on.</param>
195198
/// <param name="flags">The command flags to use.</param>
199+
/// <remarks>
200+
/// Previously, this method was intended provide scripts, that can be evaluated by their SHA-1 hashes.
201+
/// </remarks>
196202
public async Task<LoadedLuaScript> LoadAsync(IServer server, CommandFlags flags = CommandFlags.None)
197203
{
198204
if ((flags & CommandFlags.FireAndForget) != 0)
@@ -239,7 +245,7 @@ public sealed class LoadedLuaScript
239245

240246
/// <summary>
241247
/// <para>The SHA1 hash of ExecutableScript.</para>
242-
/// <para>This is sent to Redis instead of ExecutableScript during Evaluate and EvaluateAsync calls.</para>
248+
/// <para>This is not sent to Redis, instead ExecutableScript is used during Evaluate and EvaluateAsync calls.</para>
243249
/// </summary>
244250
/// <remarks>Be aware that using hash directly is not resilient to Redis server restarts.</remarks>
245251
[EditorBrowsable(EditorBrowsableState.Never)]
@@ -257,14 +263,17 @@ internal LoadedLuaScript(LuaScript original, byte[] hash)
257263
/// <summary>
258264
/// <para>Evaluates this LoadedLuaScript against the given database, extracting parameters for the passed in object if any.</para>
259265
/// <para>
260-
/// This method sends the SHA1 hash of the ExecutableScript instead of the script itself.
261-
/// If the script has not been loaded into the passed Redis instance, it will fail.
266+
/// This method evaluates the script itself and does not send the SHA-1 hash, generated by the server when loaded initially, in order to execute it.
267+
/// If the script has not been loaded into the passed Redis instance, it will not fail.
262268
/// </para>
263269
/// </summary>
264270
/// <param name="db">The redis database to evaluate against.</param>
265271
/// <param name="ps">The parameter object to use.</param>
266272
/// <param name="withKeyPrefix">The key prefix to use, if any.</param>
267273
/// <param name="flags">The command flags to use.</param>
274+
/// <remarks>
275+
/// Previously, this method evaluated the script by it's SHA-1 hash.
276+
/// </remarks>
268277
public RedisResult Evaluate(IDatabase db, object? ps = null, RedisKey? withKeyPrefix = null, CommandFlags flags = CommandFlags.None)
269278
{
270279
Original.ExtractParameters(ps, withKeyPrefix, out RedisKey[]? keys, out RedisValue[]? args);
@@ -275,14 +284,17 @@ public RedisResult Evaluate(IDatabase db, object? ps = null, RedisKey? withKeyPr
275284
/// <summary>
276285
/// <para>Evaluates this LoadedLuaScript against the given database, extracting parameters for the passed in object if any.</para>
277286
/// <para>
278-
/// This method sends the SHA1 hash of the ExecutableScript instead of the script itself.
279-
/// If the script has not been loaded into the passed Redis instance, it will fail.
287+
/// This method evaluates the script itself and does not send the SHA-1 hash, generated by the server when loaded initially, in order to execute it.
288+
/// If the script has not been loaded into the passed Redis instance, it will not fail.
280289
/// </para>
281290
/// </summary>
282291
/// <param name="db">The redis database to evaluate against.</param>
283292
/// <param name="ps">The parameter object to use.</param>
284293
/// <param name="withKeyPrefix">The key prefix to use, if any.</param>
285294
/// <param name="flags">The command flags to use.</param>
295+
/// <remarks>
296+
/// Previously, this method evaluated the script by it's SHA-1 hash.
297+
/// </remarks>
286298
public Task<RedisResult> EvaluateAsync(IDatabaseAsync db, object? ps = null, RedisKey? withKeyPrefix = null, CommandFlags flags = CommandFlags.None)
287299
{
288300
Original.ExtractParameters(ps, withKeyPrefix, out RedisKey[]? keys, out RedisValue[]? args);

0 commit comments

Comments
 (0)