diff --git a/src/StackExchange.Redis/Groups/Scripts.MethodsNew.cs b/src/StackExchange.Redis/Groups/Scripts.MethodsNew.cs new file mode 100644 index 000000000..f67007a22 --- /dev/null +++ b/src/StackExchange.Redis/Groups/Scripts.MethodsNew.cs @@ -0,0 +1,209 @@ +using System; +using System.Threading; +using System.Threading.Tasks; +using StackExchange.Redis.Protocol; + +namespace StackExchange.Redis; + +/// +/// The scripts commands. +/// +/// +/// Here rather than in a single surface-wide class, so that a group is one place. The extension methods +/// bind by namespace, and the namespace is StackExchange.Redis, so this costs a caller nothing. +/// +public static partial class Scripts +{ + /// EVALSHA, preceded by SCRIPT LOAD so the hash is certain to resolve. + /// The scripting command group. + /// The Lua source. + /// The keys the script accesses; these route the command. + /// Everything else the script needs. + /// Command flags. + /// Cancels the request: one not yet written is never sent; one already written still runs on the server, and its reply is discarded. + /// + /// + /// The hash is computed here rather than taken from the server's reply, which is what lets the body + /// go on the wire once. The existing path cannot do that - it has no hash until + /// SCRIPT LOAD answers, so its first call sends SCRIPT LOAD and then EVAL, + /// carrying the body twice. + /// + /// + /// Every key the script touches must be passed in . That is the + /// server's rule rather than ours - it is how a script routes in a cluster - and it is also what + /// lets a client-side cache know what to invalidate. A script that reaches a key it did not declare + /// is already broken before caching enters the picture. + /// + /// + public static ValueTask EvaluateCachedAsync( + this RespScripts scripts, + CachedLuaScript script, + ReadOnlySpan keys = default, + ReadOnlySpan args = default, + CommandFlags flags = CommandFlags.None, + CancellationToken cancellationToken = default) + => EvaluateCached(scripts, script, keys, args, flags, readOnly: false, RespHandlers.Result, cancellationToken); + + private static ValueTask EvaluateCached( + RespScripts scripts, + CachedLuaScript script, + ReadOnlySpan keys, + ReadOnlySpan args, + CommandFlags flags, + bool readOnly, + IRespHandler handler, + CancellationToken cancellationToken) + { + if (script is null) throw new ArgumentNullException(nameof(script)); + var context = scripts.Context; + + if ((flags & CommandFlags.NoScriptCache) != 0 + || !context.CommandMap.IsAvailable(RedisCommand.SCRIPT) + || context.Executor is { Accumulates: true }) + { + // EVAL_RO can be DISABLED in the command map, and the fallback is not just a different name: + // EVAL_RO defaults to CommandRetryReadOnly where EVAL defaults to CommandRetryWriteAccumulating, + // so swapping the command alone would quietly make a script the caller asked for read-only + // retry like a write. ForReadOnlyScript pins the category before it falls back. + var eval = readOnly + ? ForReadOnlyScript(context.CommandMap, RedisCommand.EVAL_RO, ref flags) + : RedisCommand.EVAL; + var cmd = context.Render($"{eval}{(RedisValue)script.Bytes}{(RedisValue)keys.Length}{keys}{args}"); + return context.SendAsync(ref cmd, flags, handler, cancellationToken); + } + + var preamble = script.AsLoadRequest(); + return Repairable( + SendPair(context, preamble, (RedisValue)script.Hash, keys, args, flags, readOnly, script, handler, cancellationToken), + context, + script, + keys, + args, + flags, + readOnly, + handler, + cancellationToken); + } + + /// Recover from NOSCRIPT by re-sending the script body. + /// + /// + /// A belief about a server's script cache can always be wrong. SCRIPT FLUSH, a restart, + /// or a failover to a replica that never saw the load all leave the endpoint believing a script is + /// present when it is not - and the reply is NOSCRIPT. The shipped surface repairs this in + /// ResultProcessor and re-issues with the body; without the same repair the new surface turns + /// an ordinary, expected event into an exception the caller has to handle. + /// + /// + /// Only where the source is known. A caller who supplied a hash and not a script cannot be + /// repaired - there is nothing to re-send - so EvaluateHash lets the error stand, which is + /// what the remarks there already say. + /// + /// + /// The belief is dropped before retrying, so the retry carries its own SCRIPT LOAD rather than + /// trusting the record that has just been proved wrong, and the next caller reloads too. + /// + /// + private static ValueTask Repairable( + ValueTask pending, + RespContext context, + CachedLuaScript script, + ReadOnlySpan keys, + ReadOnlySpan args, + CommandFlags flags, + bool readOnly, + IRespHandler handler, + CancellationToken cancellationToken) + { + if (pending.IsCompletedSuccessfully) return pending; // the overwhelmingly common case: no state machine + + // the spans cannot cross an await, so the retry's arguments are captured now - only on the path + // that might need them, which is the one that has already suspended + return Awaited(pending, context, script, keys.ToArray(), args.ToArray(), flags, readOnly, handler, cancellationToken); + + static async ValueTask Awaited( + ValueTask pending, + RespContext context, + CachedLuaScript script, + RedisKey[] keys, + RedisValue[] args, + CommandFlags flags, + bool readOnly, + IRespHandler handler, + CancellationToken cancellationToken) + { + try + { + return await pending.ConfigureAwait(false); + } + catch (RedisServerException ex) when (ex.Kind == RedisErrorKind.NoScript) + { + var eval = readOnly + ? ForReadOnlyScript(context.CommandMap, RedisCommand.EVAL_RO, ref flags) + : RedisCommand.EVAL; + var cmd = context.Render($"{eval}{(RedisValue)script.Bytes}{(RedisValue)keys.Length}{keys}{args}"); + return await context.SendAsync(ref cmd, flags, handler, cancellationToken).ConfigureAwait(false); + } + } + } + + /// EVALSHA_RO, preceded by SCRIPT LOAD; the read-only form of Evaluate. + /// The scripting command group. + /// The Lua source; it must not write. + /// The keys the script accesses; these route the command. + /// Everything else the script needs. + /// Command flags. + /// Cancels the request: one not yet written is never sent; one already written still runs on the server, and its reply is discarded. + /// + /// + /// A separate method rather than a flag on Evaluate, because it is a separate command with a + /// different retry category: EVALSHA_RO is read-only, where EVALSHA must be treated as + /// a write. Hiding that behind a boolean would let a caller's retry semantics change invisibly. + /// + /// + /// Requires a server that has the read-only forms (7.0 and later). The older surface probes + /// the connection and falls back; this does not, because the frame is chosen before the connection + /// is - which is the same constraint that puts the loaded-script belief at write time. + /// + /// + public static ValueTask EvaluateCachedReadOnlyAsync( + this RespScripts scripts, + CachedLuaScript script, + ReadOnlySpan keys = default, + ReadOnlySpan args = default, + CommandFlags flags = CommandFlags.None, + CancellationToken cancellationToken = default) + => EvaluateCached(scripts, script, keys, args, flags, readOnly: true, RespHandlers.Result, cancellationToken); + + /// Render the EVALSHA and send it behind a preamble the registry already owns. + /// + /// The registry's preamble owns nothing poolable - it is a fixed array that is never returned - so + /// it needs no disposal and can be handed over directly. + /// + private static ValueTask SendPair( + RespContext context, + RespRequest preamble, + RedisValue hash, + ReadOnlySpan keys, + ReadOnlySpan args, + CommandFlags flags, + bool readOnly, + IRespPreambleGate gate, + IRespHandler handler, + CancellationToken cancellationToken) + { + var command = readOnly + ? ForReadOnlyScript(context.CommandMap, RedisCommand.EVALSHA_RO, ref flags) + : RedisCommand.EVALSHA; + var request = context.Render($"{command}{hash}{(RedisValue)keys.Length}{keys}{args}"); + try + { + return context.SendWithPreambleAsync( + preamble, ref request, flags, handler, gate, cancellationToken); + } + finally + { + request.Dispose(); + } + } +} diff --git a/src/StackExchange.Redis/Groups/Scripts.MethodsWithoutPreamble.cs b/src/StackExchange.Redis/Groups/Scripts.MethodsWithoutPreamble.cs new file mode 100644 index 000000000..2086f3ecb --- /dev/null +++ b/src/StackExchange.Redis/Groups/Scripts.MethodsWithoutPreamble.cs @@ -0,0 +1,200 @@ +using System; +using System.Threading; +using System.Threading.Tasks; +using StackExchange.Redis.Protocol; + +namespace StackExchange.Redis; + +/// +/// The scripts commands. +/// +/// +/// Here rather than in a single surface-wide class, so that a group is one place. The extension methods +/// bind by namespace, and the namespace is StackExchange.Redis, so this costs a caller nothing. +/// +public static partial class Scripts +{ + /// EVALSHA, preceded by SCRIPT LOAD so the hash is certain to resolve. + /// The scripting command group. + /// The Lua source. + /// The keys the script accesses; these route the command. + /// Everything else the script needs. + /// Command flags. + /// Cancels the request: one not yet written is never sent; one already written still runs on the server, and its reply is discarded. + /// + /// + /// The hash is computed here rather than taken from the server's reply, which is what lets the body + /// go on the wire once. The existing path cannot do that - it has no hash until + /// SCRIPT LOAD answers, so its first call sends SCRIPT LOAD and then EVAL, + /// carrying the body twice. + /// + /// + /// Every key the script touches must be passed in . That is the + /// server's rule rather than ours - it is how a script routes in a cluster - and it is also what + /// lets a client-side cache know what to invalidate. A script that reaches a key it did not declare + /// is already broken before caching enters the picture. + /// + /// + public static ValueTask EvaluateCached2Async( + this RespScripts scripts, + CachedLuaScript script, + ReadOnlySpan keys = default, + ReadOnlySpan args = default, + CommandFlags flags = CommandFlags.None, + CancellationToken cancellationToken = default) + => EvaluateCached2(scripts, script, keys, args, flags, readOnly: false, RespHandlers.Result, cancellationToken); + + private static ValueTask EvaluateCached2( + RespScripts scripts, + CachedLuaScript script, + ReadOnlySpan keys, + ReadOnlySpan args, + CommandFlags flags, + bool readOnly, + IRespHandler handler, + CancellationToken cancellationToken) + { + if (script is null) throw new ArgumentNullException(nameof(script)); + var context = scripts.Context; + + if ((flags & CommandFlags.NoScriptCache) != 0 + || !context.CommandMap.IsAvailable(RedisCommand.SCRIPT) + || context.Executor is { Accumulates: true }) + { + // EVAL_RO can be DISABLED in the command map, and the fallback is not just a different name: + // EVAL_RO defaults to CommandRetryReadOnly where EVAL defaults to CommandRetryWriteAccumulating, + // so swapping the command alone would quietly make a script the caller asked for read-only + // retry like a write. ForReadOnlyScript pins the category before it falls back. + var eval = readOnly + ? ForReadOnlyScript(context.CommandMap, RedisCommand.EVAL_RO, ref flags) + : RedisCommand.EVAL; + var cmd = context.Render($"{eval}{(RedisValue)script.Bytes}{(RedisValue)keys.Length}{keys}{args}"); + return context.SendAsync(ref cmd, flags, handler, cancellationToken); + } + + return Repairable2( + SendPair2(context, (RedisValue)script.Hash, keys, args, flags, readOnly, handler, cancellationToken), + context, + script, + keys, + args, + flags, + readOnly, + handler, + cancellationToken); + } + + /// Recover from NOSCRIPT by re-sending the script body. + /// + /// + /// A belief about a server's script cache can always be wrong. SCRIPT FLUSH, a restart, + /// or a failover to a replica that never saw the load all leave the endpoint believing a script is + /// present when it is not - and the reply is NOSCRIPT. The shipped surface repairs this in + /// ResultProcessor and re-issues with the body; without the same repair the new surface turns + /// an ordinary, expected event into an exception the caller has to handle. + /// + /// + /// Only where the source is known. A caller who supplied a hash and not a script cannot be + /// repaired - there is nothing to re-send - so EvaluateHash lets the error stand, which is + /// what the remarks there already say. + /// + /// + /// The belief is dropped before retrying, so the retry carries its own SCRIPT LOAD rather than + /// trusting the record that has just been proved wrong, and the next caller reloads too. + /// + /// + private static ValueTask Repairable2( + ValueTask pending, + RespContext context, + CachedLuaScript script, + ReadOnlySpan keys, + ReadOnlySpan args, + CommandFlags flags, + bool readOnly, + IRespHandler handler, + CancellationToken cancellationToken) + { + if (pending.IsCompletedSuccessfully) return pending; // the overwhelmingly common case: no state machine + + // the spans cannot cross an await, so the retry's arguments are captured now - only on the path + // that might need them, which is the one that has already suspended + return Awaited(pending, context, script, keys.ToArray(), args.ToArray(), flags, readOnly, handler, cancellationToken); + + static async ValueTask Awaited( + ValueTask pending, + RespContext context, + CachedLuaScript script, + RedisKey[] keys, + RedisValue[] args, + CommandFlags flags, + bool readOnly, + IRespHandler handler, + CancellationToken cancellationToken) + { + try + { + return await pending.ConfigureAwait(false); + } + catch (RedisServerException ex) when (ex.Kind == RedisErrorKind.NoScript) + { + var eval = readOnly + ? ForReadOnlyScript(context.CommandMap, RedisCommand.EVAL_RO, ref flags) + : RedisCommand.EVAL; + var cmd = context.Render($"{eval}{(RedisValue)script.Bytes}{(RedisValue)keys.Length}{keys}{args}"); + return await context.SendAsync(ref cmd, flags, handler, cancellationToken).ConfigureAwait(false); + } + } + } + + /// EVALSHA_RO, preceded by SCRIPT LOAD; the read-only form of Evaluate. + /// The scripting command group. + /// The Lua source; it must not write. + /// The keys the script accesses; these route the command. + /// Everything else the script needs. + /// Command flags. + /// Cancels the request: one not yet written is never sent; one already written still runs on the server, and its reply is discarded. + /// + /// + /// A separate method rather than a flag on Evaluate, because it is a separate command with a + /// different retry category: EVALSHA_RO is read-only, where EVALSHA must be treated as + /// a write. Hiding that behind a boolean would let a caller's retry semantics change invisibly. + /// + /// + /// Requires a server that has the read-only forms (7.0 and later). The older surface probes + /// the connection and falls back; this does not, because the frame is chosen before the connection + /// is - which is the same constraint that puts the loaded-script belief at write time. + /// + /// + public static ValueTask EvaluateCached2ReadOnlyAsync( + this RespScripts scripts, + CachedLuaScript script, + ReadOnlySpan keys = default, + ReadOnlySpan args = default, + CommandFlags flags = CommandFlags.None, + CancellationToken cancellationToken = default) + => EvaluateCached2(scripts, script, keys, args, flags, readOnly: true, RespHandlers.Result, cancellationToken); + + private static ValueTask SendPair2( + RespContext context, + RedisValue hash, + ReadOnlySpan keys, + ReadOnlySpan args, + CommandFlags flags, + bool readOnly, + IRespHandler handler, + CancellationToken cancellationToken) + { + var command = readOnly + ? ForReadOnlyScript(context.CommandMap, RedisCommand.EVALSHA_RO, ref flags) + : RedisCommand.EVALSHA; + var request = context.Render($"{command}{hash}{(RedisValue)keys.Length}{keys}{args}"); + try + { + return context.SendAsync(ref request, flags, handler, cancellationToken); + } + finally + { + request.Dispose(); + } + } +} diff --git a/src/StackExchange.Redis/Protocol/CachedLuaScript.cs b/src/StackExchange.Redis/Protocol/CachedLuaScript.cs new file mode 100644 index 000000000..5d36fa92c --- /dev/null +++ b/src/StackExchange.Redis/Protocol/CachedLuaScript.cs @@ -0,0 +1,122 @@ +using System; +using System.Buffers.Text; +using System.Diagnostics; +using System.Security.Cryptography; +using System.Text; +using RESPite.Buffers; +using StackExchange.Redis.Protocol; + +namespace StackExchange.Redis +{ + /// + /// CachedLuaScript. + /// + public class CachedLuaScript : IRespPreambleGate + { + private const int LoadArgCount = 3; + private readonly byte[] _request; + private readonly byte[] _hash; + private readonly string _str; + private readonly int _start; + + /// + /// String. + /// + public string String => _str; + + /// + /// Bytes. + /// + public ReadOnlyMemory Bytes => _request.AsMemory(_start, _request.Length - _start - 2); + + /// + /// Hash. + /// + public byte[] Hash => _hash; + + /// + /// Initializes a new instance of the class. + /// + /// bytes. + public CachedLuaScript(byte[] bytes) + { + _str = Encoding.UTF8.GetString(bytes); + _hash = Sha1Hex(bytes); + _request = AddHeader(bytes, out var start); + _start = start; + } + + /// + /// Initializes a new instance of the class. + /// + /// str. + public CachedLuaScript(string str) + { + _str = str; + + var bytes = Encoding.UTF8.GetBytes(str); + _hash = Sha1Hex(bytes); + _request = AddHeader(bytes, out var start); + _start = start; + } + + bool IRespPreambleGate.IsNeeded(IRespPreambleTarget connection) + => connection.Server is not { } endpoint || !endpoint.IsScriptLoaded(_str); + + void IRespPreambleGate.OnEstablished(IRespPreambleTarget connection) + => connection.Server?.AddScript(_str, _hash); + + internal RespRequest AsLoadRequest() + => new(_request, RefCountedBuffer.CreateFixed(_request), 0, _request.Length, argCount: LoadArgCount, command: RedisCommand.SCRIPT); + + private static byte[] AddHeader(byte[] bytes, out int start) + { + ReadOnlySpan header = "*3\r\n$6\r\nSCRIPT\r\n$4\r\nLOAD\r\n$"u8; + Span utf8len = stackalloc byte[10]; +#if NET + var status = bytes.Length.TryFormat(utf8len, out var written); +#else + var status = Utf8Formatter.TryFormat(bytes.Length, utf8len, out var written); +#endif + Debug.Assert(status); + var request = new byte[header.Length + written + 2 + bytes.Length + 2]; + header.CopyTo(request); + start = header.Length; + + utf8len.CopyTo(request.AsSpan(start)); + start += written; + + "\r\n"u8.CopyTo(request.AsSpan(start)); + start += 2; + + bytes.CopyTo(request.AsSpan(start)); + + "\r\n"u8.CopyTo(request.AsSpan(start + bytes.Length)); + + return request; + } + + private static byte[] Sha1Hex(byte[] bytes) + { +#if NET + Span digest = stackalloc byte[20]; + SHA1.HashData(bytes, digest); +#else + using var sha = SHA1.Create(); + var digest = sha.ComputeHash(bytes); +#endif + // one path for every target: lower-case hex is what the server reports, and `ToHexStringLower` + // is too new to use here. Not hot - and once the rendered SCRIPT LOAD frame is cached, this + // runs once per script rather than once per call. + const string Hex = "0123456789abcdef"; + var chars = new byte[40]; + for (var i = 0; i < 20; i++) + { + chars[i * 2] = (byte)Hex[digest[i] >> 4]; + chars[(i * 2) + 1] = (byte)Hex[digest[i] & 0xF]; + } + + return chars; + } + } +} diff --git a/src/StackExchange.Redis/PublicAPI/PublicAPI.Unshipped.txt b/src/StackExchange.Redis/PublicAPI/PublicAPI.Unshipped.txt index e7093f5c8..b85000340 100644 --- a/src/StackExchange.Redis/PublicAPI/PublicAPI.Unshipped.txt +++ b/src/StackExchange.Redis/PublicAPI/PublicAPI.Unshipped.txt @@ -1,6 +1,12 @@ #nullable enable *REMOVED*static StackExchange.Redis.RespReaderExtensions.ReadLease(this in RESPite.Messages.RespReader reader) -> StackExchange.Redis.Lease? StackExchange.Redis.Arrays +StackExchange.Redis.CachedLuaScript +StackExchange.Redis.CachedLuaScript.Bytes.get -> System.ReadOnlyMemory +StackExchange.Redis.CachedLuaScript.CachedLuaScript(byte[]! bytes) -> void +StackExchange.Redis.CachedLuaScript.CachedLuaScript(string! str) -> void +StackExchange.Redis.CachedLuaScript.Hash.get -> byte[]! +StackExchange.Redis.CachedLuaScript.String.get -> string! static StackExchange.Redis.Arrays.CountAsync(this StackExchange.Redis.RespArrays arrays, StackExchange.Redis.RedisKey key, StackExchange.Redis.CommandFlags flags = StackExchange.Redis.CommandFlags.None, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask static StackExchange.Redis.Arrays.DeleteAsync(this StackExchange.Redis.RespArrays arrays, StackExchange.Redis.RedisKey key, StackExchange.Redis.RedisArrayIndex index, StackExchange.Redis.CommandFlags flags = StackExchange.Redis.CommandFlags.None, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask static StackExchange.Redis.Arrays.DeleteAsync(this StackExchange.Redis.RespArrays arrays, StackExchange.Redis.RedisKey key, System.ReadOnlySpan indices, StackExchange.Redis.CommandFlags flags = StackExchange.Redis.CommandFlags.None, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask @@ -45,6 +51,10 @@ StackExchange.Redis.Caching.CacheKeyRemovalReason.Expired = 3 -> StackExchange.R StackExchange.Redis.Caching.CacheKeyRemovalReason.Evicted = 4 -> StackExchange.Redis.Caching.CacheKeyRemovalReason StackExchange.Redis.Caching.CacheKeyRemovalReason.Flushed = 5 -> StackExchange.Redis.Caching.CacheKeyRemovalReason StackExchange.Redis.Caching.CacheKeyRemovedHandler +static StackExchange.Redis.Scripts.EvaluateCachedAsync(this StackExchange.Redis.RespScripts scripts, StackExchange.Redis.CachedLuaScript! script, System.ReadOnlySpan keys = default(System.ReadOnlySpan), System.ReadOnlySpan args = default(System.ReadOnlySpan), StackExchange.Redis.CommandFlags flags = StackExchange.Redis.CommandFlags.None, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask +static StackExchange.Redis.Scripts.EvaluateCachedReadOnlyAsync(this StackExchange.Redis.RespScripts scripts, StackExchange.Redis.CachedLuaScript! script, System.ReadOnlySpan keys = default(System.ReadOnlySpan), System.ReadOnlySpan args = default(System.ReadOnlySpan), StackExchange.Redis.CommandFlags flags = StackExchange.Redis.CommandFlags.None, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask +static StackExchange.Redis.Scripts.EvaluateCached2Async(this StackExchange.Redis.RespScripts scripts, StackExchange.Redis.CachedLuaScript! script, System.ReadOnlySpan keys = default(System.ReadOnlySpan), System.ReadOnlySpan args = default(System.ReadOnlySpan), StackExchange.Redis.CommandFlags flags = StackExchange.Redis.CommandFlags.None, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask +static StackExchange.Redis.Scripts.EvaluateCached2ReadOnlyAsync(this StackExchange.Redis.RespScripts scripts, StackExchange.Redis.CachedLuaScript! script, System.ReadOnlySpan keys = default(System.ReadOnlySpan), System.ReadOnlySpan args = default(System.ReadOnlySpan), StackExchange.Redis.CommandFlags flags = StackExchange.Redis.CommandFlags.None, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask virtual StackExchange.Redis.Caching.CacheKeyRemovedHandler.Invoke(System.ReadOnlySpan key, StackExchange.Redis.Caching.CacheKeyRemovalReason reason) -> void StackExchange.Redis.Caching.CacheOptions.Admission.get -> StackExchange.Redis.Caching.CacheAdmission StackExchange.Redis.Caching.CacheOptions.Admission.init -> void