Add Vary + s-maxage to CacheControl directive for efficient CDN caching

src/HotChocolate/AspNetCore/src/AspNetCore/Serialization/DefaultHttpResponseFormatter.cs

@@ -184,6 +184,13 @@ public async ValueTask FormatAsync(
                     response.GetTypedHeaders().CacheControl = cacheControlHeaderValue;
                 }
 
+                if (result.ContextData is not null
+                    && result.ContextData.TryGetValue(VaryHeaderValue, out var varyValue)
+                    && varyValue is string varyHeaderValue)
+                {
+                    response.Headers.Vary = varyHeaderValue;
+                }
+
                 OnWriteResponseHeaders(operationResult, format, response.Headers);
 
                 await format.Formatter.FormatAsync(result, response.Body, cancellationToken);

src/HotChocolate/Caching/src/Caching/CacheControlAttribute.cs

@@ -15,8 +15,10 @@ namespace HotChocolate.Caching;
 public sealed class CacheControlAttribute : DescriptorAttribute
 {
     private int? _maxAge;
+    private int? _sharedMaxAge;
     private CacheControlScope? _scope;
     private bool? _inheritMaxAge;
+    private string[]? _vary;
 
     public CacheControlAttribute()
     {
@@ -41,16 +43,16 @@ protected internal override void TryConfigure(
         switch (descriptor)
         {
             case IObjectFieldDescriptor objectField:
-                objectField.CacheControl(_maxAge, _scope, _inheritMaxAge);
+                objectField.CacheControl(_maxAge, _scope, _inheritMaxAge, _sharedMaxAge, _vary);
                 break;
             case IObjectTypeDescriptor objectType:
-                objectType.CacheControl(_maxAge, _scope);
+                objectType.CacheControl(_maxAge, _scope, _sharedMaxAge, _vary);
                 break;
             case IInterfaceTypeDescriptor interfaceType:
-                interfaceType.CacheControl(_maxAge, _scope);
+                interfaceType.CacheControl(_maxAge, _scope, _sharedMaxAge, _vary);
                 break;
             case IUnionTypeDescriptor unionType:
-                unionType.CacheControl(_maxAge, _scope);
+                unionType.CacheControl(_maxAge, _scope, _sharedMaxAge, _vary);
                 break;
         }
     }
@@ -60,6 +62,12 @@ protected internal override void TryConfigure(
     /// </summary>
     public int MaxAge { get => _maxAge ?? CacheControlDefaults.MaxAge; set => _maxAge = value; }
 
+    /// <summary>
+    /// The maximum time, in seconds, this resource can be cached on CDNs and other shared caches.
+    /// If not set, the value of <c>MaxAge</c> is used for shared caches too.
+    /// </summary>
+    public int SharedMaxAge { get => _sharedMaxAge ?? 0; set => _sharedMaxAge = value; }
+
     /// <summary>
     /// The scope of this resource.
     /// </summary>
@@ -70,12 +78,22 @@ public CacheControlScope Scope
     }
 
     /// <summary>
-    /// Whether this resource should inherit the <c>MaxAge</c>
+    /// Whether this resource should inherit the <c>MaxAge</c> and <c>SharedMaxAge</c>
     /// of its parent.
     /// </summary>
     public bool InheritMaxAge
     {
         get => _inheritMaxAge ?? false;
         set => _inheritMaxAge = value;
     }
+
+    /// <summary>
+    /// List of headers that might affect the value of this resource. Typically, these headers becomes part
+    /// of the cache key.
+    /// </summary>
+    public string[]? Vary
+    {
+        get => _vary ?? Array.Empty<string>();
+        set => _vary = value;
+    }
 }

src/HotChocolate/Caching/src/Caching/CacheControlConstraintsOptimizer.cs

@@ -1,10 +1,13 @@
+using System.Linq;
 using System.Runtime.CompilerServices;
+using System.Text;
 using HotChocolate.Execution.Processing;
 using HotChocolate.Language;
 using HotChocolate.Types;
 using HotChocolate.Types.Introspection;
 using HotChocolate.Utilities;
 using Microsoft.Net.Http.Headers;
+using Microsoft.Extensions.Primitives;
 using IHasDirectives = HotChocolate.Types.IHasDirectives;
 
 namespace HotChocolate.Caching;
@@ -26,24 +29,36 @@ public void OptimizeOperation(OperationOptimizerContext context)
 
         var constraints = ComputeCacheControlConstraints(context.CreateOperation());
 
-        if (constraints.MaxAge is not null)
+        if (constraints.MaxAge is not null || constraints.SharedMaxAge is not null)
         {
             var headerValue = new CacheControlHeaderValue
             {
                 Private = constraints.Scope == CacheControlScope.Private,
-                MaxAge = TimeSpan.FromSeconds(constraints.MaxAge.Value),
+                MaxAge = constraints.MaxAge is not null ? TimeSpan.FromSeconds(constraints.MaxAge.Value) : null,
+                SharedMaxAge = constraints.SharedMaxAge is not null
+                    ? TimeSpan.FromSeconds(constraints.SharedMaxAge.Value)
+                    : null,
             };
 
             context.ContextData.Add(
                 WellKnownContextData.CacheControlConstraints,
                 new ImmutableCacheConstraints(
-                    constraints.MaxAge.Value,
-                    constraints.Scope));
+                    constraints.MaxAge,
+                    constraints.SharedMaxAge,
+                    constraints.Scope,
+                    constraints.Vary ?? []));
 
             context.ContextData.Add(
                 WellKnownContextData.CacheControlHeaderValue,
                 headerValue);
         }
+
+        if (constraints.Vary is {Length: > 0})
+        {
+            context.ContextData.Add(
+                WellKnownContextData.VaryHeaderValue,
+                string.Join(", ", constraints.Vary));
+        }
     }
 
     private static CacheControlConstraints ComputeCacheControlConstraints(
@@ -67,11 +82,13 @@ private static void ProcessSelection(
     {
         var field = selection.Field;
         var maxAgeSet = false;
+        var sharedMaxAgeSet = false;
         var scopeSet = false;
+        var varySet = false;
 
         ExtractCacheControlDetailsFromDirectives(field.Directives);
 
-        if (!maxAgeSet || !scopeSet)
+        if (!maxAgeSet || !sharedMaxAgeSet || !scopeSet || !varySet)
         {
             // Either maxAge or scope have not been specified by the @cacheControl
             // directive on the field, so we try to infer these details
@@ -111,13 +128,24 @@ void ExtractCacheControlDetailsFromDirectives(
 
             if (directive is not null)
             {
+                var previousMaxAge = constraints.MaxAge;
                 if (!maxAgeSet &&
-                    directive.MaxAge.HasValue &&
-                    (!constraints.MaxAge.HasValue || directive.MaxAge < constraints.MaxAge.Value))
+                    directive.MaxAge.HasValue)
                 {
-                    // The maxAge of the @cacheControl directive is lower
-                    // than the previously lowest maxAge value.
-                    constraints.MaxAge = directive.MaxAge.Value;
+                    // If only max-age has been set, we honor the expected behavior that a CDN
+                    // cannot ever cache longer than this unless s-maxage specifies otherwise.
+                    if (!constraints.MaxAge.HasValue || directive.MaxAge < constraints.MaxAge.Value)
+                    {
+                        constraints.MaxAge = directive.MaxAge.Value;
+                    }
+
+                    if (!directive.SharedMaxAge.HasValue &&
+                        constraints.SharedMaxAge.HasValue &&
+                        constraints.SharedMaxAge.Value > directive.MaxAge.Value)
+                    {
+                        constraints.SharedMaxAge = directive.MaxAge;
+                    }
+
                     maxAgeSet = true;
                 }
                 else if (directive.InheritMaxAge == true)
@@ -127,6 +155,34 @@ void ExtractCacheControlDetailsFromDirectives(
                     maxAgeSet = true;
                 }
 
+                if (!sharedMaxAgeSet &&
+                    directive.SharedMaxAge.HasValue &&
+                    (!constraints.SharedMaxAge.HasValue || directive.SharedMaxAge < constraints.SharedMaxAge.Value))
+                {
+                    // The maxAge of the @cacheControl directive is lower
+                    // than the previously lowest maxAge value.
+                    if (!constraints.SharedMaxAge.HasValue &&
+                        previousMaxAge.HasValue &&
+                        previousMaxAge.Value < directive.SharedMaxAge.Value)
+                    {
+                        // If only max-age has been set, we honor the expected behavior that a CDN
+                        // cannot ever cache longer than this unless s-maxage specifies otherwise.
+                        constraints.SharedMaxAge = previousMaxAge.Value;
+                    }
+                    else
+                    {
+                        constraints.SharedMaxAge = directive.SharedMaxAge.Value;
+                    }
+
+                    sharedMaxAgeSet = true;
+                }
+                else if (directive.InheritMaxAge == true)
+                {
+                    // If inheritMaxAge is set, we keep the
+                    // computed maxAge value as is.
+                    sharedMaxAgeSet = true;
+                }
+
                 if (directive.Scope.HasValue &&
                     directive.Scope < constraints.Scope)
                 {
@@ -135,6 +191,22 @@ void ExtractCacheControlDetailsFromDirectives(
                     constraints.Scope = directive.Scope.Value;
                     scopeSet = true;
                 }
+
+                if (directive.Vary is {Length: > 0})
+                {
+                    if (constraints.Vary != null)
+                    {
+                        constraints.Vary = constraints.Vary.Concat(directive.Vary.Select(x => x.ToLowerInvariant()))
+                            .Distinct().OrderBy(x => x).ToArray();
+                    }
+                    else
+                    {
+                        constraints.Vary = directive.Vary.Select(x => x.ToLowerInvariant()).Distinct().OrderBy(x => x)
+                            .ToArray();
+                    }
+
+                    varySet = true;
+                }
             }
         }
     }
@@ -163,5 +235,9 @@ private sealed class CacheControlConstraints
         public CacheControlScope Scope { get; set; } = CacheControlScope.Public;
 
         internal int? MaxAge { get; set; }
+
+        internal int? SharedMaxAge { get; set; }
+
+        internal string[]? Vary { get; set; }
     }
 }

src/HotChocolate/Caching/src/Caching/CacheControlValidationTypeInterceptor.cs

@@ -133,5 +133,20 @@ private static void ValidateCacheControlOnField(
                 validationContext.ReportError(error);
             }
         }
+
+        if (directive.SharedMaxAge.HasValue)
+        {
+            if (directive.SharedMaxAge.Value < 0)
+            {
+                var error = ErrorHelper.CacheControlNegativeSharedMaxAge(obj, field);
+                validationContext.ReportError(error);
+            }
+
+            if (inheritMaxAge)
+            {
+                var error = ErrorHelper.CacheControlBothSharedMaxAgeAndInheritMaxAge(obj, field);
+                validationContext.ReportError(error);
+            }
+        }
     }
 }

src/HotChocolate/Caching/src/Caching/ErrorHelper.cs

@@ -44,6 +44,16 @@ public static ISchemaError CacheControlNegativeMaxAge(
             .SetTypeSystemObject(type)
             .Build();
 
+    public static ISchemaError CacheControlNegativeSharedMaxAge(
+        ITypeSystemObject type,
+        IField field)
+        => SchemaErrorBuilder.New()
+            .SetMessage(
+                ErrorHelper_CacheControlNegativeSharedMaxAge,
+                field.Coordinate.ToString())
+            .SetTypeSystemObject(type)
+            .Build();
+
     public static ISchemaError CacheControlBothMaxAgeAndInheritMaxAge(
         ITypeSystemObject type,
         IField field)
@@ -53,4 +63,14 @@ public static ISchemaError CacheControlBothMaxAgeAndInheritMaxAge(
                 field.Coordinate.ToString())
             .SetTypeSystemObject(type)
             .Build();
+
+    public static ISchemaError CacheControlBothSharedMaxAgeAndInheritMaxAge(
+        ITypeSystemObject type,
+        IField field)
+        => SchemaErrorBuilder.New()
+            .SetMessage(
+                ErrorHelper_CacheControlBothSharedMaxAgeAndInheritMaxAge,
+                field.Coordinate.ToString())
+            .SetTypeSystemObject(type)
+            .Build();
 }

src/HotChocolate/Caching/src/Caching/Extensions/CacheControlInterfaceTypeDescriptorExtensions.cs

@@ -17,17 +17,27 @@ public static class CacheControlInterfaceTypeDescriptorExtensions
     /// <param name="scope">
     /// The scope of fields of this type.
     /// </param>
+    /// <param name="sharedMaxAge">
+    /// The maximum time, in seconds, fields of this
+    /// type should be cached in a shared cache.
+    /// </param>
+    /// <param name="vary">
+    /// List of headers that might affect the value of this resource.
+    /// </param>
     public static IInterfaceTypeDescriptor CacheControl(
         this IInterfaceTypeDescriptor descriptor,
-        int? maxAge = null, CacheControlScope? scope = null)
+        int? maxAge = null, 
+        CacheControlScope? scope = null,
+        int? sharedMaxAge = null, 
+        string[]? vary = null)
     {
         if (descriptor is null)
         {
             throw new ArgumentNullException(nameof(descriptor));
         }
 
         return descriptor.Directive(
-            new CacheControlDirective(maxAge, scope));
+            new CacheControlDirective(maxAge, scope, null, sharedMaxAge, vary));
     }
     /// <summary>
     /// Specifies the caching rules for this interface type.

src/HotChocolate/Caching/src/Caching/Extensions/CacheControlObjectFieldDescriptorExtensions.cs

@@ -21,17 +21,27 @@ public static class CacheControlObjectFieldDescriptorExtensions
     /// Whether this field should inherit the <c>MaxAge</c>
     /// from its parent.
     /// </param>
+    /// <param name="sharedMaxAge">
+    /// The maximum time, in seconds, fields of this
+    /// type should be cached in a shared cache.
+    /// </param>
+    /// <param name="vary">
+    /// List of headers that might affect the value of this resource.
+    /// </param>
+    ///
     public static IObjectFieldDescriptor CacheControl(
         this IObjectFieldDescriptor descriptor,
         int? maxAge = null, CacheControlScope? scope = null,
-        bool? inheritMaxAge = null)
+        bool? inheritMaxAge = null, 
+        int? sharedMaxAge = null, 
+        string[]? vary = null)
     {
         if (descriptor is null)
         {
             throw new ArgumentNullException(nameof(descriptor));
         }
 
         return descriptor.Directive(
-            new CacheControlDirective(maxAge, scope, inheritMaxAge));
+            new CacheControlDirective(maxAge, scope, inheritMaxAge, sharedMaxAge, vary));
     }
 }

src/HotChocolate/Caching/src/Caching/Extensions/CacheControlObjectTypeDescriptorExtensions.cs

@@ -17,17 +17,27 @@ public static class CacheControlObjectTypeDescriptorExtensions
     /// <param name="scope">
     /// The scope of fields of this type.
     /// </param>
+    /// <param name="sharedMaxAge">
+    /// The maximum time, in seconds, fields of this
+    /// type should be cached in a shared cache.
+    /// </param>
+    /// <param name="vary">
+    /// List of headers that might affect the value of this resource.
+    /// </param>
     public static IObjectTypeDescriptor CacheControl(
         this IObjectTypeDescriptor descriptor,
-        int? maxAge = null, CacheControlScope? scope = null)
+        int? maxAge = null,
+        CacheControlScope? scope = null,
+        int? sharedMaxAge = null, 
+        string[]? vary = null)
     {
         if (descriptor is null)
         {
             throw new ArgumentNullException(nameof(descriptor));
         }
 
         return descriptor.Directive(
-            new CacheControlDirective(maxAge, scope));
+            new CacheControlDirective(maxAge, scope, null, sharedMaxAge, vary));
     }
 
     /// <summary>