feat: add support for agent cache

Consul.Test/AgentTest.cs

@@ -408,6 +408,31 @@ public async Task Agent_Checks_ServiceBound()
             await _client.Agent.ServiceDeregister(svcID);
         }
 
+        [Theory]
+        [InlineData(false)]
+        [InlineData(true)]
+        public async Task Agent_UseCache(bool useCache)
+        {
+
+            var opts = new QueryOptions
+            {
+                UseCache = useCache,
+                MaxAge = TimeSpan.FromSeconds(10),
+                StaleIfError = TimeSpan.FromSeconds(10),
+            };
+
+            var response = await _client.Catalog.Datacenters(opts);
+
+            if (useCache)
+            {
+                Assert.NotEqual(QueryResult.CacheResult.UNDEFINED, response.XCache);
+            }
+            else
+            {
+                Assert.Equal(QueryResult.CacheResult.UNDEFINED, response.XCache);
+            }
+        }
+
         [Fact]
         public async Task Agent_Join()
         {

Consul.Test/ClientTest.cs

@@ -94,6 +94,31 @@ public async Task Client_SetQueryOptions()
             Assert.Equal("1m40s", request.Params["wait"]);
         }
 
+        [Fact]
+        public async Task Client_SetQueryOptionsWithCache()
+        {
+            var opts = new QueryOptions()
+            {
+                Datacenter = "foo",
+                Consistency = ConsistencyMode.Default,
+                WaitIndex = 1000,
+                WaitTime = new TimeSpan(0, 0, 100),
+                Token = "12345",
+                UseCache = true,
+                MaxAge = new TimeSpan(0, 0, 10),
+                StaleIfError = new TimeSpan(0, 0, 10)
+            };
+            var request = _client.Get<KVPair>("/v1/kv/foo", opts);
+
+            await Assert.ThrowsAsync<ConsulRequestException>(async () => await request.Execute(CancellationToken.None));
+
+            Assert.Equal("foo", request.Params["dc"]);
+            Assert.Equal("1000", request.Params["index"]);
+            Assert.Equal("1m40s", request.Params["wait"]);
+            Assert.Equal(string.Empty, request.Params["cached"]);
+            Assert.Equal("max-age=10,stale-if-error=10", request.Params["Cache-Control"]);
+        }
+
         [Fact]
         public async Task Client_SetClientOptions()
         {
@@ -138,9 +163,11 @@ public async Task Client_CustomHttpClient()
                 hc.Timeout = TimeSpan.FromDays(10);
                 hc.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
 
-                var config = new ConsulClientConfiguration();
-                config.Address = TestHelper.HttpUri;
-                config.Token = TestHelper.MasterToken;
+                var config = new ConsulClientConfiguration
+                {
+                    Address = TestHelper.HttpUri,
+                    Token = TestHelper.MasterToken
+                };
 
 #pragma warning disable CS0618 // Type or member is obsolete
                 using (var client = new ConsulClient(config, hc))
@@ -175,9 +202,11 @@ public async Task Client_DisposeBehavior()
         [Fact]
         public async Task Client_ReuseAndUpdateConfig()
         {
-            var config = new ConsulClientConfiguration();
-            config.Address = TestHelper.HttpUri;
-            config.Token = TestHelper.MasterToken;
+            var config = new ConsulClientConfiguration
+            {
+                Address = TestHelper.HttpUri,
+                Token = TestHelper.MasterToken
+            };
 
 #pragma warning disable CS0618 // Type or member is obsolete
             using (var client = new ConsulClient(config))
@@ -219,8 +248,8 @@ public async Task Client_ReuseAndUpdateConfig()
         [Fact]
         public void Client_Constructors()
         {
-            Action<ConsulClientConfiguration> cfgAction2 = (cfg) => { cfg.Token = "yep"; };
-            Action<ConsulClientConfiguration> cfgAction = (cfg) => { cfg.Datacenter = "foo"; cfgAction2(cfg); };
+            void cfgAction2(ConsulClientConfiguration cfg) { cfg.Token = "yep"; }
+            void cfgAction(ConsulClientConfiguration cfg) { cfg.Datacenter = "foo"; cfgAction2(cfg); }
 
             using (var c = new ConsulClient())
             {

Consul/Catalog.cs

@@ -147,6 +147,15 @@ internal Catalog(ConsulClient c)
             return _client.Get<string[]>("/v1/catalog/datacenters").Execute(ct);
         }
 
+        /// <summary>
+        /// Datacenters is used to query for all the known datacenters with custom query options
+        /// </summary>
+        /// <returns>A list of datacenter names</returns>
+        public Task<QueryResult<string[]>> Datacenters(QueryOptions q, CancellationToken ct = default(CancellationToken))
+        {
+            return _client.Get<string[]>("/v1/catalog/datacenters", q).Execute(ct);
+        }
+
         /// <summary>
         /// Nodes is used to query all the known nodes
         /// </summary>

Consul/Client_GetRequests.cs

@@ -17,6 +17,7 @@
 // -----------------------------------------------------------------------
 
 using System;
+using System.Collections.Generic;
 using System.Diagnostics;
 using System.IO;
 using System.Linq;
@@ -116,16 +117,15 @@ public async Task<QueryResult<Stream>> ExecuteStreaming(CancellationToken ct)
             ApplyHeaders(message, Client.Config);
             var response = await Client.HttpClient.SendAsync(message, HttpCompletionOption.ResponseHeadersRead, ct).ConfigureAwait(false);
 
-            ParseQueryHeaders(response, (result as QueryResult<TOut>));
+            ParseQueryHeaders(response, result as QueryResult<TOut>);
             result.StatusCode = response.StatusCode;
             ResponseStream = await response.Content.ReadAsStreamAsync().ConfigureAwait(false);
 
             result.Response = ResponseStream;
 
             if (response.StatusCode != HttpStatusCode.NotFound && !response.IsSuccessStatusCode)
             {
-                throw new ConsulRequestException(string.Format("Unexpected response, status code {0}",
-                    response.StatusCode), response.StatusCode);
+                throw new ConsulRequestException($"Unexpected response, status code {response.StatusCode}", response.StatusCode);
             }
 
             result.RequestTime = timer.Elapsed;
@@ -171,6 +171,27 @@ protected override void ApplyOptions(ConsulClientConfiguration clientConfig)
             {
                 Params["near"] = Options.Near;
             }
+
+            if (Options.UseCache)
+            {
+                Params["cached"] = string.Empty;
+                var cacheControl = new List<string>();
+
+                if (Options.MaxAge.HasValue && Options.MaxAge > TimeSpan.Zero)
+                {
+                    cacheControl.Add($"max-age={Convert.ToInt32(Options.MaxAge.Value.TotalSeconds)}");
+                }
+
+                if (Options.StaleIfError.HasValue && Options.StaleIfError > TimeSpan.Zero)
+                {
+                    cacheControl.Add($"stale-if-error={Convert.ToInt32(Options.StaleIfError.Value.TotalSeconds)}");
+                }
+
+                if (cacheControl.Count > 0)
+                {
+                    Params["Cache-Control"] = string.Join(",", cacheControl);
+                }
+            }
         }
 
         protected void ParseQueryHeaders(HttpResponseMessage res, QueryResult<TOut> meta)
@@ -224,6 +245,31 @@ protected void ParseQueryHeaders(HttpResponseMessage res, QueryResult<TOut> meta
                     throw new ConsulRequestException("Failed to parse X-Consul-Translate-Addresses", res.StatusCode, ex);
                 }
             }
+
+            if (headers.Contains("X-Cache"))
+            {
+                try
+                {
+
+                    meta.XCache = headers.GetValues("X-Cache").Single() == "HIT" ? QueryResult.CacheResult.HIT : QueryResult.CacheResult.MISS;
+                }
+                catch (Exception ex)
+                {
+                    throw new ConsulRequestException("Failed to parse X-Cache", res.StatusCode, ex);
+                }
+            }
+
+            if (headers.Contains("Age"))
+            {
+                try
+                {
+                    meta.Age = TimeSpan.FromSeconds(double.Parse(headers.GetValues("Age").Single()));
+                }
+                catch (Exception ex)
+                {
+                    throw new ConsulRequestException("Failed to parse Age", res.StatusCode, ex);
+                }
+            }
         }
 
         protected override void ApplyHeaders(HttpRequestMessage message, ConsulClientConfiguration clientConfig)
@@ -246,7 +292,7 @@ public GetRequest(ConsulClient client, string url, QueryOptions options = null)
         {
             if (string.IsNullOrEmpty(url))
             {
-                throw new ArgumentException(nameof(url));
+                throw new ArgumentException(null, nameof(url));
             }
             Options = options ?? QueryOptions.Default;
         }
@@ -306,6 +352,27 @@ protected override void ApplyOptions(ConsulClientConfiguration clientConfig)
             {
                 Params["dc"] = Options.Datacenter;
             }
+
+            if (Options.UseCache && Options.Consistency != ConsistencyMode.Consistent)
+            {
+                Params["cached"] = string.Empty;
+                var cacheControl = new List<string>();
+
+                if (Options.MaxAge.HasValue && Options.MaxAge > TimeSpan.Zero)
+                {
+                    cacheControl.Add($"max-age={Options.MaxAge.Value.Seconds}");
+                }
+
+                if (Options.StaleIfError.HasValue && Options.StaleIfError > TimeSpan.Zero)
+                {
+                    cacheControl.Add($"stale-if-error={Options.StaleIfError.Value.Seconds}");
+                }
+
+                if (cacheControl.Count > 0)
+                {
+                    Params["Cache-Control"] = string.Join(",", cacheControl);
+                }
+            }
         }
 
         protected override void ApplyHeaders(HttpRequestMessage message, ConsulClientConfiguration clientConfig)

Consul/Client_Options.cs

@@ -38,15 +38,39 @@ public class QueryOptions
         };
 
         /// <summary>
-        /// Providing a datacenter overwrites the DC provided by the Config
+        /// Providing a datacenter overwrites the DC provided by the Config.
         /// </summary>
         public string Datacenter { get; set; }
 
         /// <summary>
-        /// The consistency level required for the operation
+        /// The consistency level required for the operation.
         /// </summary>
         public ConsistencyMode Consistency { get; set; }
 
+        /// <summary>
+        /// UseCache requests that the agent cache results locally.
+        /// See https://www.consul.io/api/features/caching.html for more details on the semantics.
+        /// </summary>
+        public bool UseCache { get; set; }
+
+        /// <summary>
+        /// MaxAge limits how old a cached value will be returned if UseCache is true.
+        /// If there is a cached response that is older than the MaxAge, it is treated as a cache miss and a new fetch invoked.
+        /// If the fetch fails, the error is returned.
+        /// Clients that wish to allow for stale results on error can set StaleIfError to a longer duration to change this behavior.
+        /// It is ignored if the endpoint supports background refresh caching.
+        /// See https://www.consul.io/api/features/caching.html for more details.
+        /// </summary>
+        public TimeSpan? MaxAge { get; set; }
+
+        /// <summary>
+        /// StaleIfError specifies how stale the client will accept a cached response if the servers are unavailable to fetch a fresh one.
+        /// Only makes sense when UseCache is true and MaxAge is set to a lower, non-zero value.
+        /// It is ignored if the endpoint supports background refresh caching.
+        /// See https://www.consul.io/api/features/caching.html for more details.
+        /// </summary>
+        public TimeSpan? StaleIfError { get; set; }
+
         /// <summary>
         /// WaitIndex is used to enable a blocking query. Waits until the timeout or the next index is reached
         /// </summary>

Consul/Client_Results.cs

@@ -44,6 +44,24 @@ public ConsulResult(ConsulResult other)
     /// </summary>
     public class QueryResult : ConsulResult
     {
+        public enum CacheResult
+        {
+            UNDEFINED,
+            MISS,
+            HIT
+        }
+
+        /// <summary>
+        /// In all cases the HTTP `X-Cache` header is always set in the response to either `HIT` or `MISS` indicating whether the response was served from cache or not.
+        /// </summary>
+        public CacheResult XCache { get; set; }
+
+        /// <summary>
+        /// For cache hits, the HTTP `Age` header is always set in the response to indicate how many seconds since that response was fetched from the servers.
+        /// As long as the local agent has an active connection to the servers, the age will always be 0 since the value is up-to-date.
+        /// </summary>
+        public TimeSpan Age { get; set; }
+
         /// <summary>
         /// The index number when the query was serviced. This can be used as a WaitIndex to perform a blocking query
         /// </summary>

Consul/Interfaces/ICatalogEndpoint.cs

@@ -30,6 +30,7 @@ namespace Consul
     public interface ICatalogEndpoint
     {
         Task<QueryResult<string[]>> Datacenters(CancellationToken ct = default(CancellationToken));
+        Task<QueryResult<string[]>> Datacenters(QueryOptions q, CancellationToken ct = default(CancellationToken));
         Task<WriteResult> Deregister(CatalogDeregistration reg, CancellationToken ct = default(CancellationToken));
         Task<WriteResult> Deregister(CatalogDeregistration reg, WriteOptions q, CancellationToken ct = default(CancellationToken));
         Task<QueryResult<CatalogNode>> Node(string node, CancellationToken ct = default(CancellationToken));

Consul/Lock.cs

@@ -614,7 +614,7 @@ public TimeSpan LockRetryTime
         /// <summary>
         /// When set to false, <see cref="Lock.Acquire"/> will block forever until the lock is acquired. LockWaitTime is ignored in this case.
         /// <br/>
-        /// When set to true, <see cref="Lock.Acquire"/> the lock within a timestamp (It is analogous to <c>SemaphoreSlim.Wait(Timespan timeout)</c>. 
+        /// When set to true, <see cref="Lock.Acquire"/> the lock within a timestamp (It is analogous to <c>SemaphoreSlim.Wait(Timespan timeout)</c>.
         /// Under the hood, it attempts to acquire the lock multiple times if needed (due to the HTTP Long Poll returning early),
         /// and will do so as many times as it can within the bounds set by LockWaitTime.
         /// If LockWaitTime is set to 0, there will be only single attempt to acquire the lock.