Add directive-argument opt-in and code-first directive APIs

src/HotChocolate/Core/src/Types/Configuration/Validation/RequiresOptInValidationRule.cs

@@ -55,5 +55,20 @@ public void Validate(
                     break;
             }
         }
+
+        foreach (var directive in schema.DirectiveDefinitions)
+        {
+            foreach (var argument in directive.Arguments)
+            {
+                if (argument.Type.IsNonNullType()
+                    && argument.DefaultValue is null
+                    && argument.Directives.Any(d => d.Definition is RequiresOptInDirectiveType))
+                {
+                    errors.Add(RequiresOptInOnRequiredDirectiveArgument(
+                        directive,
+                        argument));
+                }
+            }
+        }
     }
 }

src/HotChocolate/Core/src/Types/Execution/DependencyInjection/SchemaRequestExecutorBuilderExtensions.Types.cs

@@ -1159,6 +1159,31 @@ public static IRequestExecutorBuilder AddDirectiveType(
         return builder.ConfigureSchema(b => b.AddDirectiveType(directiveType));
     }
 
+    /// <summary>
+    /// This helper adds a new GraphQL directive type and applies the
+    /// <paramref name="configure"/> delegate.
+    /// </summary>
+    /// <param name="builder">
+    /// The GraphQL configuration builder.
+    /// </param>
+    /// <param name="configure">
+    /// A delegate to configure the type.
+    /// </param>
+    /// <returns>
+    /// Returns the GraphQL configuration builder.
+    /// </returns>
+    /// <exception cref="ArgumentNullException">
+    /// <paramref name="builder"/> or <paramref name="configure"/> is <c>null</c>
+    /// </exception>
+    public static IRequestExecutorBuilder AddDirectiveType(
+        this IRequestExecutorBuilder builder,
+        Action<IDirectiveTypeDescriptor> configure)
+    {
+        ArgumentNullException.ThrowIfNull(builder);
+        ArgumentNullException.ThrowIfNull(configure);
+        return builder.ConfigureSchema(b => b.AddDirectiveType(configure));
+    }
+
     public static IRequestExecutorBuilder SetSchema<TSchema>(
         this IRequestExecutorBuilder builder)
         where TSchema : Schema

src/HotChocolate/Core/src/Types/Extensions/SchemaBuilderExtensions.Types.cs

@@ -468,6 +468,16 @@ public static ISchemaBuilder AddDirectiveType<TDirective>(
         return AddDirectiveType(builder, typeof(TDirective));
     }
 
+    public static ISchemaBuilder AddDirectiveType(
+        this ISchemaBuilder builder,
+        Action<IDirectiveTypeDescriptor> configure)
+    {
+        ArgumentNullException.ThrowIfNull(builder);
+        ArgumentNullException.ThrowIfNull(configure);
+
+        return builder.AddDirectiveType(new DirectiveType(configure));
+    }
+
     public static ISchemaBuilder SetSchema<TSchema>(
         this ISchemaBuilder builder)
         where TSchema : Schema

src/HotChocolate/Core/src/Types/Types/Descriptors/Contracts/IDirectiveArgumentDescriptor.cs

@@ -15,6 +15,57 @@ public interface IDirectiveArgumentDescriptor
     /// <inheritdoc cref="IArgumentDescriptor.Deprecated()"/>
     IDirectiveArgumentDescriptor Deprecated();
 
+    /// <summary>
+    /// Sets a directive on the argument
+    /// <example>
+    /// <code lang="csharp">
+    /// descriptor.Directive(new MyDirective());
+    /// </code>
+    /// Results in the following schema
+    /// <code lang="graphql">
+    /// directive @example(arg: Int @myDirective) on FIELD
+    /// </code>
+    /// </example>
+    /// </summary>
+    /// <param name="directiveInstance">
+    /// The instance of the directive
+    /// </param>
+    /// <typeparam name="T">The type of the directive</typeparam>
+    IDirectiveArgumentDescriptor Directive<T>(T directiveInstance)
+        where T : class;
+
+    /// <summary>
+    /// Sets a directive on the argument
+    /// <example>
+    /// <code lang="csharp">
+    /// descriptor.Directive&lt;MyDirective>();
+    /// </code>
+    /// Results in the following schema
+    /// <code lang="graphql">
+    /// directive @example(arg: Int @myDirective) on FIELD
+    /// </code>
+    /// </example>
+    /// </summary>
+    /// <typeparam name="T">The type of the directive</typeparam>
+    IDirectiveArgumentDescriptor Directive<T>()
+        where T : class, new();
+
+    /// <summary>
+    /// Sets a directive on the argument
+    /// <example>
+    /// <code lang="csharp">
+    /// descriptor.Directive("myDirective");
+    /// </code>
+    /// Results in the following schema
+    /// <code lang="graphql">
+    /// directive @example(arg: Int @myDirective) on FIELD
+    /// </code>
+    /// </example>
+    /// </summary>
+    /// <param name="name">The name of the directive</param>
+    /// <param name="arguments">The arguments of the directive</param>
+    IDirectiveArgumentDescriptor Directive(string name, params ArgumentNode[] arguments);
+
     /// <summary>
     /// Sets the name of the argument
     /// <example>

src/HotChocolate/Core/src/Types/Types/Descriptors/Contracts/IDirectiveTypeDescriptor.cs

@@ -43,6 +43,20 @@ public interface IDirectiveTypeDescriptor
     /// <param name="name">The name of the argument.</param>
     IDirectiveArgumentDescriptor Argument(string name);
 
+    /// <summary>
+    /// Specifies a directive argument and applies the
+    /// <paramref name="configure"/> delegate.
+    /// </summary>
+    /// <param name="name">
+    /// The name of the argument.
+    /// </param>
+    /// <param name="configure">
+    /// The argument descriptor to specify the argument configuration.
+    /// </param>
+    IDirectiveTypeDescriptor Argument(
+        string name,
+        Action<IDirectiveArgumentDescriptor> configure);
+
     /// <summary>
     /// Specifies in which location the directive belongs in.
     /// </summary>

src/HotChocolate/Core/src/Types/Types/Descriptors/DirectiveArgumentDescriptor.cs

@@ -100,6 +100,31 @@ public IDirectiveArgumentDescriptor Name(string value)
         return this;
     }
 
+    /// <inheritdoc />
+    public new IDirectiveArgumentDescriptor Directive<T>(T directiveInstance)
+        where T : class
+    {
+        base.Directive(directiveInstance);
+        return this;
+    }
+
+    /// <inheritdoc />
+    public new IDirectiveArgumentDescriptor Directive<T>()
+        where T : class, new()
+    {
+        base.Directive<T>();
+        return this;
+    }
+
+    /// <inheritdoc />
+    public new IDirectiveArgumentDescriptor Directive(
+        string name,
+        params ArgumentNode[] arguments)
+    {
+        base.Directive(name, arguments);
+        return this;
+    }
+
     /// <inheritdoc />
     public new IDirectiveArgumentDescriptor Description(string value)
     {

src/HotChocolate/Core/src/Types/Types/Descriptors/DirectiveTypeDescriptor.cs

@@ -135,6 +135,17 @@ public IDirectiveArgumentDescriptor Argument(string name)
         return descriptor;
     }
 
+    public IDirectiveTypeDescriptor Argument(
+        string name,
+        Action<IDirectiveArgumentDescriptor> configure)
+    {
+        ArgumentNullException.ThrowIfNull(configure);
+
+        var descriptor = Argument(name);
+        configure(descriptor);
+        return this;
+    }
+
     public IDirectiveTypeDescriptor Location(DirectiveLocation value)
     {
         Configuration.Locations |= value;

src/HotChocolate/Core/src/Types/Types/Directives/RequiresOptInDirectiveExtensions.cs

@@ -86,6 +86,30 @@ public static IArgumentDescriptor RequiresOptIn(
         return descriptor;
     }
 
+    /// <summary>
+    /// Adds an <c>@requiresOptIn</c> directive to a <see cref="DirectiveArgument"/>.
+    /// <code>
+    /// directive @example(arg: Int @requiresOptIn(feature: "your-feature")) on FIELD
+    /// </code>
+    /// </summary>
+    /// <param name="descriptor">
+    /// The <paramref name="descriptor"/> on which this directive shall be annotated.
+    /// </param>
+    /// <param name="feature">
+    /// The name of the feature that requires opt in.
+    /// </param>
+    /// <returns>
+    /// Returns the <paramref name="descriptor"/> on which this directive
+    /// was applied for configuration chaining.
+    /// </returns>
+    public static IDirectiveArgumentDescriptor RequiresOptIn(
+        this IDirectiveArgumentDescriptor descriptor,
+        string feature)
+    {
+        ApplyRequiresOptIn(descriptor, feature);
+        return descriptor;
+    }
+
     /// <summary>
     /// Adds an <c>@requiresOptIn</c> directive to an <see cref="EnumValue"/>.
     /// <code>
@@ -132,6 +156,10 @@ private static void ApplyRequiresOptIn(this IDescriptor descriptor, string featu
                 desc.Directive(new RequiresOptIn(feature));
                 break;
 
+            case IDirectiveArgumentDescriptor desc:
+                desc.Directive(new RequiresOptIn(feature));
+                break;
+
             case IEnumValueDescriptor desc:
                 desc.Directive(new RequiresOptIn(feature));
                 break;

src/HotChocolate/Core/src/Types/Types/Interceptors/OptInFeaturesTypeInterceptor.cs

@@ -1,4 +1,5 @@
 using HotChocolate.Configuration;
+using HotChocolate.Language;
 using HotChocolate.Types.Descriptors;
 using HotChocolate.Types.Descriptors.Configurations;
 
@@ -27,6 +28,12 @@ public override void OnBeforeCompleteType(
     {
         switch (configuration)
         {
+            case DirectiveTypeConfiguration directiveType:
+                _optInFeatures.UnionWith(
+                    directiveType.Arguments.SelectMany(a => a.GetOptInFeatures()));
+
+                break;
+
             case EnumTypeConfiguration enumType:
                 _optInFeatures.UnionWith(enumType.Values.SelectMany(v => v.GetOptInFeatures()));
 
@@ -61,10 +68,22 @@ file static class Extensions
     public static IEnumerable<string> GetOptInFeatures(
         this IDirectiveConfigurationProvider configuration)
     {
-        return configuration.Directives
-            .Select(d => d.Value)
-            .OfType<RequiresOptIn>()
-            .Select(r => r.Feature);
+        foreach (var directive in configuration.Directives)
+        {
+            switch (directive.Value)
+            {
+                case RequiresOptIn requiresOptIn:
+                    yield return requiresOptIn.Feature;
+                    break;
+
+                case DirectiveNode { Name.Value: DirectiveNames.RequiresOptIn.Name } node
+                    when node.Arguments.FirstOrDefault(
+                        a => a.Name.Value == DirectiveNames.RequiresOptIn.Arguments.Feature)
+                        is { Value: StringValueNode feature }:
+                    yield return feature.Value;
+                    break;
+            }
+        }
     }
 }
 

src/HotChocolate/Core/src/Types/Types/Introspection/__Directive.cs

@@ -16,11 +16,14 @@ protected override ObjectTypeConfiguration CreateConfiguration(ITypeDiscoveryCon
     {
         var stringType = Create(ScalarNames.String);
         var nonNullStringType = Parse($"{ScalarNames.String}!");
+        var nonNullStringListType = Parse($"[{ScalarNames.String}!]");
         var nonNullBooleanType = Parse($"{ScalarNames.Boolean}!");
         var argumentListType = Parse($"[{nameof(__InputValue)}!]!");
         var locationListType = Parse($"[{nameof(__DirectiveLocation)}!]!");
 
-        return new ObjectTypeConfiguration(
+        var optInFeaturesEnabled = context.DescriptorContext.Options.EnableOptInFeatures;
+
+        var def = new ObjectTypeConfiguration(
             Names.__Directive,
             TypeResources.Directive_Description,
             typeof(DirectiveType))
@@ -30,7 +33,12 @@ protected override ObjectTypeConfiguration CreateConfiguration(ITypeDiscoveryCon
                 new(Names.Name, type: nonNullStringType, pureResolver: Resolvers.Name),
                 new(Names.Description, type: stringType, pureResolver: Resolvers.Description),
                 new(Names.Locations, type: locationListType, pureResolver: Resolvers.Locations),
-                new(Names.Args, type: argumentListType, pureResolver: Resolvers.Arguments)
+                new(
+                    Names.Args,
+                    type: argumentListType,
+                    pureResolver: optInFeaturesEnabled
+                        ? Resolvers.ArgumentsWithOptIn
+                        : Resolvers.Arguments)
                 {
                     Arguments =
                     {
@@ -70,6 +78,15 @@ protected override ObjectTypeConfiguration CreateConfiguration(ITypeDiscoveryCon
                 }
             }
         };
+
+        if (optInFeaturesEnabled)
+        {
+            def.Fields.Single(f => f.Name == Names.Args)
+                .Arguments
+                .Add(new(Names.IncludeOptIn, type: nonNullStringListType));
+        }
+
+        return def;
     }
 
     private static class Resolvers
@@ -95,7 +112,28 @@ public static object Locations(IResolverContext context)
             return DirectiveLocationUtils.AsEnumerable(locations);
         }
 
-        public static object Arguments(IResolverContext context)
+        public static object ArgumentsWithOptIn(IResolverContext context)
+        {
+            var includeOptIn = context.ArgumentValue<string[]?>(Names.IncludeOptIn) ?? [];
+
+            // If an argument has no @requiresOptIn directives, it is always included.
+            // If an argument requires opting into features "f1" and "f2", then `includeOptIn`
+            // must list at least one of the features in order for the argument to be included.
+            return Arguments(context).Where(
+                a =>
+                {
+                    var requiredFeatures = a
+                        .Directives
+                        .Where(d => d.Definition is RequiresOptInDirectiveType)
+                        .Select(d => d.ToValue<RequiresOptIn>().Feature)
+                        .ToList();
+
+                    return requiredFeatures.Count == 0
+                        || requiredFeatures.Any(feature => includeOptIn.Contains(feature));
+                });
+        }
+
+        public static IEnumerable<IInputValueDefinition> Arguments(IResolverContext context)
         {
             var directive = context.Parent<DirectiveType>();
             return context.ArgumentValue<bool>(Names.IncludeDeprecated)
@@ -132,6 +170,7 @@ public static class Names
         public const string IsDeprecated = "isDeprecated";
         public const string DeprecationReason = "deprecationReason";
         public const string IncludeDeprecated = "includeDeprecated";
+        public const string IncludeOptIn = "includeOptIn";
         public const string Locations = "locations";
         public const string Args = "args";
         public const string OnOperation = "onOperation";

src/HotChocolate/Core/src/Types/Utilities/ErrorHelper.cs

@@ -578,4 +578,13 @@ public static ISchemaError RequiresOptInOnRequiredArgument(
             .SetField(field)
             .SetArgument(argument)
             .Build();
+
+    public static ISchemaError RequiresOptInOnRequiredDirectiveArgument(
+        IDirectiveDefinition directive,
+        IInputValueDefinition argument)
+        => SchemaErrorBuilder.New()
+            .SetMessage(ErrorHelper_RequiresOptInOnRequiredArgument)
+            .SetDirective(directive)
+            .SetArgument(argument)
+            .Build();
 }