gurafi 0.1.0

Intuitive GraphQL server for Rust
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
//! Field options: descriptions, deprecation, complexity, authorization and type overrides.

use std::{
    any::TypeId,
    sync::{Arc, OnceLock},
};

use futures::future::BoxFuture;
use gql::{AppliedDirective, ComplexityFn, Field, GraphQLError, Name, TypeRef};
use indexmap::IndexMap;

use crate::{
    registry::TypeRegistry,
    schema::ObjectRef,
    traits::{AbstractType, InputObject, ObjectModel, OutputType, coerce_args},
};

/// A deferred check that a field's declared type is compatible with its Rust type.
#[derive(Clone, Debug)]
pub(crate) enum FieldCheck {
    /// `.as_abstract(...)` declared an interface or union output.
    Abstract {
        owner: Name,
        field: Name,
        original: TypeRef,
        abstract_name: Name,
    },
    /// `.as_type::<T>()` replaced the field's GraphQL type.
    TypeOverride {
        owner: Name,
        field: Name,
        original: TypeRef,
        replacement: TypeRef,
    },
    /// `.non_null()` was applied to a resolver that can return `None`.
    NonNullOnOption {
        owner: Name,
        field: Name,
        rust_type: &'static str,
    },
    /// `.nullable_items()` was applied to a field that is not a list.
    NullableItemsOnNonList {
        owner: Name,
        field: Name,
        ty: TypeRef,
    },
    /// `.non_null_items()` was applied to a field that is not a list.
    NonNullItemsOnNonList {
        owner: Name,
        field: Name,
        ty: TypeRef,
    },
    /// A `.resolve_inherited(...)` field's Rust type must be a covariant match for the
    /// interface field it inherits.
    InheritedType {
        owner: Name,
        field: Name,
        actual: TypeRef,
        expected: TypeRef,
    },
    /// `.as_object_ref(...)` declared a runtime-named object output.
    DynamicObject {
        owner: Name,
        field: Name,
        original: TypeRef,
        model: &'static str,
    },
    /// `.as_dynamic(...)` declared an explicit runtime-named output type.
    DynamicType {
        owner: Name,
        field: Name,
        rust: TypeRef,
        declared: TypeRef,
    },
}

/// Where a field was inserted, so its options can be applied once the builder call ends.
pub(crate) enum FieldSink<'a> {
    /// A field inside an object or interface definition.
    Object(&'a mut IndexMap<Name, Field>),
    /// The most recently pushed field of a root operation.
    Fields(&'a mut Vec<Field>),
}

impl FieldSink<'_> {
    fn get(&self, name: &str) -> Option<&Field> {
        match self {
            Self::Object(fields) => fields.get(name),
            Self::Fields(fields) => fields.iter().rev().find(|field| &*field.name == name),
        }
    }

    fn get_mut(&mut self, name: &str) -> Option<&mut Field> {
        match self {
            Self::Object(fields) => fields.get_mut(name),
            Self::Fields(fields) => fields.iter_mut().rev().find(|field| &*field.name == name),
        }
    }
}

/// The predicate behind an authorization guard.
enum GuardPredicate<Ctx: 'static> {
    Sync(Arc<dyn Fn(&Ctx) -> bool + Send + Sync>),
    Async(Arc<dyn for<'r> Fn(&'r Ctx) -> BoxFuture<'r, bool> + Send + Sync>),
}

impl<Ctx: 'static> Clone for GuardPredicate<Ctx> {
    fn clone(&self) -> Self {
        match self {
            Self::Sync(predicate) => Self::Sync(Arc::clone(predicate)),
            Self::Async(predicate) => Self::Async(Arc::clone(predicate)),
        }
    }
}

/// A per-field authorization check, optionally inherited from an object or interface.
pub(crate) struct AuthGuard<Ctx: 'static> {
    predicate: GuardPredicate<Ctx>,
    message: Arc<str>,
}

impl<Ctx: 'static> Clone for AuthGuard<Ctx> {
    fn clone(&self) -> Self {
        Self {
            predicate: self.predicate.clone(),
            message: Arc::clone(&self.message),
        }
    }
}

impl<Ctx: 'static> AuthGuard<Ctx> {
    fn new(predicate: GuardPredicate<Ctx>, message: Option<Arc<str>>) -> Self {
        Self {
            predicate,
            message: message.unwrap_or_else(|| Arc::from("Not authorized")),
        }
    }

    /// Return a copy of this guard with a different denial message.
    pub(crate) fn with_message(&self, message: Option<Arc<str>>) -> Arc<Self> {
        Arc::new(Self {
            predicate: self.predicate.clone(),
            message: message.unwrap_or_else(|| Arc::clone(&self.message)),
        })
    }

    #[cfg_attr(
        feature = "tracing",
        tracing::instrument(skip_all, level = "trace", name = "gurafi.auth")
    )]
    fn check<'r>(&self, context: &'r Ctx) -> BoxFuture<'r, Result<(), GraphQLError>> {
        let message = Arc::clone(&self.message);
        match &self.predicate {
            GuardPredicate::Sync(predicate) => {
                // Evaluate before creating the future so no reference to the context is held
                // across an await point.
                let allowed = predicate(context);
                Box::pin(async move {
                    if allowed {
                        Ok(())
                    } else {
                        Err(GraphQLError::new(message.to_string()).extend("code", "UNAUTHORIZED"))
                    }
                })
            }
            GuardPredicate::Async(predicate) => {
                let future = predicate(context);
                Box::pin(async move {
                    if future.await {
                        Ok(())
                    } else {
                        Err(GraphQLError::new(message.to_string()).extend("code", "UNAUTHORIZED"))
                    }
                })
            }
        }
    }
}

/// Sentinel arguments type stored by [`crate::ObjectBuilder::raw_field`].
///
/// A raw field without arguments has no resolver, so a `validate` hook could never run. Using a
/// dedicated `TypeId` lets [`FieldConfig::validate`] report that clearly instead of accepting the
/// hook and silently dropping it.
pub(crate) struct RawFieldArgs;

/// The arguments-type check installed by [`FieldConfig::validate`].
///
/// The slot is cloned into the field's resolver before the builder returns it, so a validation
/// hook installed afterwards can run inside the resolver's single argument-coercion step. That
/// keeps input-level validation from running a second time and keeps the validator independent
/// of the resolver's concrete `A` at the type level (the arguments [`TypeId`] is checked when the
/// hook is installed).
pub(crate) struct ValidationSlot<Ctx: 'static> {
    hook: Arc<OnceLock<ErasedValidator<Ctx>>>,
}

impl<Ctx: 'static> Clone for ValidationSlot<Ctx> {
    fn clone(&self) -> Self {
        Self {
            hook: Arc::clone(&self.hook),
        }
    }
}

type ErasedValidator<Ctx> =
    Arc<dyn Fn(&dyn std::any::Any, &Ctx) -> Result<(), GraphQLError> + Send + Sync>;

impl<Ctx: 'static> Default for ValidationSlot<Ctx> {
    fn default() -> Self {
        Self::new()
    }
}

impl<Ctx: 'static> ValidationSlot<Ctx> {
    pub(crate) fn new() -> Self {
        Self {
            hook: Arc::new(OnceLock::new()),
        }
    }

    /// Install a validator for arguments of type `A`.
    pub(crate) fn install<A: 'static>(
        &self,
        validator: impl Fn(&A, &Ctx) -> Result<(), GraphQLError> + Send + Sync + 'static,
    ) {
        let validator = Arc::new(validator);
        let _ = self
            .hook
            .set(Arc::new(move |args: &dyn std::any::Any, ctx: &Ctx| {
                let args = args.downcast_ref::<A>().ok_or_else(|| {
                    GraphQLError::new(
                        "Internal error: a field validator received arguments of a different type.",
                    )
                })?;
                validator(args, ctx)
            }));
    }

    /// Whether a validator was already installed.
    pub(crate) fn is_installed(&self) -> bool {
        self.hook.get().is_some()
    }

    /// Run the installed validator, if any.
    #[cfg_attr(
        feature = "tracing",
        tracing::instrument(
            skip_all,
            level = "trace",
            name = "gurafi.validator",
            fields(args = std::any::type_name::<A>())
        )
    )]
    pub(crate) fn run<A: 'static>(&self, args: &A, ctx: &Ctx) -> Result<(), GraphQLError> {
        match self.hook.get() {
            Some(hook) => hook(args, ctx),
            None => Ok(()),
        }
    }
}

enum Complexity {
    Fixed(u32),
    Custom(ComplexityFn),
}

/// Builder returned by every `field` and `expose` method.
///
/// The options are applied when the value is dropped, which is at the end of the statement, so
/// they can be chained in any order and without an explicit `build` call:
///
/// ```
/// # use gurafi::{Object, Schema, NoArgs};
/// # struct Ctx { is_logged_in: bool }
/// # #[derive(Object)] struct Giraffe { name: String }
/// # let mut schema = Schema::<Ctx>::new();
/// # schema.object::<Giraffe>(|o| {
/// o.field("name", |g: &Giraffe, _: NoArgs, _: &Ctx| g.name.clone())
///     .description("The giraffe's name.")
///     .deprecated("Use `displayName`.")
///     .auth(|ctx: &Ctx| ctx.is_logged_in)
///     .auth_error("Sign in to read names.")
///     .complexity(2);
/// # });
/// ```
pub struct FieldConfig<'a, Ctx: 'static> {
    registry: &'a mut TypeRegistry,
    sink: FieldSink<'a>,
    name: Name,
    description: Option<Arc<str>>,
    deprecation: Option<Arc<str>>,
    directives: Vec<AppliedDirective>,
    complexity: Option<Complexity>,
    auth: Option<GuardPredicate<Ctx>>,
    auth_error: Option<Arc<str>>,
    /// Interface fields store authorization here so implementing objects inherit it.
    field_auth: Option<&'a mut IndexMap<Name, Arc<AuthGuard<Ctx>>>>,
    checks: Option<&'a mut Vec<FieldCheck>>,
    owner: Name,
    /// The field's declared type when this config was created.
    ///
    /// Most fields never change their type, so this is captured on first use instead of cloning
    /// the `TypeRef` (and its boxes) for every declared field.
    original: OnceLock<TypeRef>,
    rust_nullable: bool,
    rust_type_name: &'static str,
    /// The Rust arguments type the field's resolvers coerce into.
    args_type: TypeId,
    /// Validator installed by [`FieldConfig::validate`], read inside the resolver.
    validation: ValidationSlot<Ctx>,
    /// Output type to register when the config is dropped, unless a later option replaces the
    /// named type. `expose!` uses this so `as_object_ref`/`as_dynamic` do not leave a stale
    /// reference to the model's derived name.
    deferred_output: Option<fn(&mut TypeRegistry)>,
    suppress_deferred_output: bool,
    marker: std::marker::PhantomData<fn() -> Ctx>,
}

/// A shared empty name for interface fields, which never report a field check.
fn empty_name() -> Name {
    static EMPTY: OnceLock<Name> = OnceLock::new();
    Arc::clone(EMPTY.get_or_init(|| Name::from("")))
}

impl<'a, Ctx: 'static> FieldConfig<'a, Ctx> {
    pub(crate) fn for_object_checked(
        registry: &'a mut TypeRegistry,
        fields: &'a mut IndexMap<Name, Field>,
        checks: &'a mut Vec<FieldCheck>,
        owner: impl Into<Name>,
        name: Name,
        rust_nullable: bool,
        rust_type_name: &'static str,
        args_type: TypeId,
        validation: ValidationSlot<Ctx>,
    ) -> Self {
        Self::new(
            registry,
            FieldSink::Object(fields),
            name,
            Some(checks),
            owner.into(),
            rust_nullable,
            rust_type_name,
            args_type,
            validation,
        )
    }

    pub(crate) fn for_interface(
        registry: &'a mut TypeRegistry,
        fields: &'a mut IndexMap<Name, Field>,
        field_auth: &'a mut IndexMap<Name, Arc<AuthGuard<Ctx>>>,
        name: Name,
        rust_nullable: bool,
        rust_type_name: &'static str,
    ) -> Self {
        let mut config = Self::new(
            registry,
            FieldSink::Object(fields),
            name,
            None,
            empty_name(),
            rust_nullable,
            rust_type_name,
            TypeId::of::<()>(),
            ValidationSlot::new(),
        );
        config.field_auth = Some(field_auth);
        config
    }

    pub(crate) fn for_fields_checked(
        registry: &'a mut TypeRegistry,
        fields: &'a mut Vec<Field>,
        checks: &'a mut Vec<FieldCheck>,
        owner: impl Into<Name>,
        name: Name,
        rust_nullable: bool,
        rust_type_name: &'static str,
        args_type: TypeId,
        validation: ValidationSlot<Ctx>,
    ) -> Self {
        Self::new(
            registry,
            FieldSink::Fields(fields),
            name,
            Some(checks),
            owner.into(),
            rust_nullable,
            rust_type_name,
            args_type,
            validation,
        )
    }

    fn new(
        registry: &'a mut TypeRegistry,
        sink: FieldSink<'a>,
        name: Name,
        checks: Option<&'a mut Vec<FieldCheck>>,
        owner: Name,
        rust_nullable: bool,
        rust_type_name: &'static str,
        args_type: TypeId,
        validation: ValidationSlot<Ctx>,
    ) -> Self {
        if !crate::schema::is_valid_graphql_name(&name) {
            registry.push_error(GraphQLError::new(format!(
                "Field name \"{name}\" is not a valid GraphQL name. A name must match \
                 [_A-Za-z][_0-9A-Za-z]*."
            )));
        }
        Self {
            registry,
            sink,
            name,
            description: None,
            deprecation: None,
            directives: Vec::new(),
            complexity: None,
            auth: None,
            auth_error: None,
            field_auth: None,
            checks,
            owner,
            original: OnceLock::new(),
            rust_nullable,
            rust_type_name,
            args_type,
            validation,
            deferred_output: None,
            suppress_deferred_output: false,
            marker: std::marker::PhantomData,
        }
    }

    /// Register `T`'s output type when this config is dropped, unless a later option replaces
    /// the field's named type.
    pub(crate) fn defer_output<T: crate::OutputType>(&mut self) {
        self.deferred_output = Some(|registry| T::register_output(registry));
    }

    /// Stop the deferred output registration. Called by options that replace the named type.
    fn suppress_output_registration(&mut self) {
        self.suppress_deferred_output = true;
    }

    /// The field's declared type when this config was created.
    fn original(&self) -> &TypeRef {
        self.original.get_or_init(|| {
            self.sink.get(&self.name).map_or_else(
                || TypeRef::Named(Arc::clone(&self.name)),
                |field| field.ty.clone(),
            )
        })
    }

    /// The GraphQL field name.
    #[must_use]
    pub fn name(&self) -> &str {
        &self.name
    }

    /// Set the field's description.
    pub fn description(&mut self, description: impl Into<Arc<str>>) -> &mut Self {
        self.description = Some(description.into());
        self
    }

    /// Mark the field as deprecated with a reason shown by introspection.
    pub fn deprecated(&mut self, reason: impl Into<Arc<str>>) -> &mut Self {
        self.deprecation = Some(reason.into());
        self
    }

    /// Apply a directive to this field.
    ///
    /// Each call adds an application in declaration order, so a repeatable directive can appear
    /// more than once. The application is checked against its definition when the schema is
    /// built; see [`crate::Schema::directive`]. Field directives print in SDL and are visible to
    /// [`crate::Plugin::field`] through `gql::Field::directives`.
    pub fn directive(&mut self, directive: AppliedDirective) -> &mut Self {
        self.directives.push(directive);
        self
    }

    /// Set a constant complexity estimate for the field.
    ///
    /// The executor uses estimates to reject expensive operations before running them.
    pub fn complexity(&mut self, complexity: u32) -> &mut Self {
        self.complexity = Some(Complexity::Fixed(complexity));
        self
    }

    /// Set a complexity estimate computed from the field's coerced arguments.
    pub fn complexity_with(
        &mut self,
        estimator: impl Fn(&gql::Object) -> u32 + Send + Sync + 'static,
    ) -> &mut Self {
        self.complexity = Some(Complexity::Custom(Arc::new(estimator)));
        self
    }

    /// Require the caller to satisfy `predicate` before the resolver runs.
    ///
    /// The predicate receives the schema's context type, where a server usually stores the
    /// authenticated user. A denied field returns a GraphQL error, so it follows normal null
    /// propagation: a nullable field becomes `null`, a non-null field nulls its parent.
    pub fn auth(&mut self, predicate: impl Fn(&Ctx) -> bool + Send + Sync + 'static) -> &mut Self {
        self.auth = Some(GuardPredicate::Sync(Arc::new(predicate)));
        self
    }

    /// Like [`FieldConfig::auth`], but the predicate is asynchronous.
    ///
    /// Use this when the check needs a database or an external policy service. The future must
    /// borrow the context; write it as `Box::pin(async move { ... })`.
    pub fn auth_async(
        &mut self,
        predicate: impl for<'r> Fn(&'r Ctx) -> BoxFuture<'r, bool> + Send + Sync + 'static,
    ) -> &mut Self {
        self.auth = Some(GuardPredicate::Async(Arc::new(predicate)));
        self
    }

    /// Set the message returned when [`FieldConfig::auth`] denies access.
    ///
    /// The default is `"Not authorized"`. Avoid leaking sensitive details: clients see this
    /// message.
    pub fn auth_error(&mut self, message: impl Into<Arc<str>>) -> &mut Self {
        self.auth_error = Some(message.into());
        self
    }

    /// Validate coerced arguments before the resolver runs.
    ///
    /// `A` must be the field's arguments type. Naming a different type is a schema build error,
    /// because the validator would otherwise be handed arguments the resolver never sees. A
    /// validation error is reported as a normal field error, exactly like a failed coercion.
    /// This is the builder-side counterpart to `#[graphql(validate = "...")]`, for rules that
    /// need the request context.
    ///
    /// The hook runs inside the resolver's single argument-coercion step, after input-level
    /// validation and before the resolver closure. It never coerces or re-validates the
    /// arguments a second time. For subscription fields it runs once per event, after the
    /// arguments were validated once when the subscription was set up.
    ///
    /// ```
    /// use gurafi::{Input, Schema};
    ///
    /// struct Ctx {
    ///     logged_in: bool,
    /// }
    ///
    /// #[derive(Input)]
    /// struct GreetArgs {
    ///     name: String,
    /// }
    ///
    /// let mut schema = Schema::<Ctx>::new();
    /// schema.query(|q| {
    ///     q.field("greet", |args: GreetArgs, _: &Ctx| args.name)
    ///         .validate::<GreetArgs>(|args, ctx| {
    ///             if args.name.is_empty() {
    ///                 Err(gurafi::GraphQLError::new("name must not be empty"))
    ///             } else if !ctx.logged_in {
    ///                 Err(gurafi::GraphQLError::new("sign in first"))
    ///             } else {
    ///                 Ok(())
    ///             }
    ///         });
    /// });
    /// let schema = schema.build().expect("schema builds");
    /// # let _ = schema;
    /// ```
    pub fn validate<A: InputObject>(
        &mut self,
        validator: impl Fn(&A, &Ctx) -> Result<(), GraphQLError> + Send + Sync + 'static,
    ) -> &mut Self {
        if self.args_type == TypeId::of::<RawFieldArgs>() {
            self.registry.push_error(GraphQLError::new(format!(
                "Field `{}.{}` is declared with `raw_field`, which installs no resolver, so a \
                 `validate` hook could never run. Declare the field with `raw_field_with::<_, \
                 Args>(...)` to coerce arguments through a resolver, then call `validate` on that.",
                self.owner, self.name,
            )));
            return self;
        }
        if TypeId::of::<A>() != self.args_type {
            self.registry.push_error(GraphQLError::new(format!(
                "Field `{}.{}` calls `validate::<{}>()`, but its resolver's arguments type is \
                 not `{}`. Use the field's actual arguments type, or change the resolver to take \
                 `{}`.",
                self.owner,
                self.name,
                std::any::type_name::<A>(),
                std::any::type_name::<A>(),
                std::any::type_name::<A>(),
            )));
            return self;
        }
        if self.validation.is_installed() {
            self.registry.push_error(GraphQLError::new(format!(
                "Field `{}.{}` installs more than one `validate` hook. Combine the checks into \
                 one validator.",
                self.owner, self.name,
            )));
            return self;
        }
        self.validation.install::<A>(validator);
        // A synchronous property resolver reads the model directly and never coerces arguments,
        // so a validator would have nowhere to run. Convert to the boxed path once, at the point
        // the option is applied, and run the hook before the property read — the same place a
        // resolver-backed field runs it.
        let materialize = self
            .sink
            .get(&self.name)
            .is_some_and(|field| field.sync_resolve.is_some());
        if materialize {
            if let Some(field) = self.sink.get_mut(&self.name) {
                materialize_resolve(field);
                if let Some(resolve) = field.resolve.take() {
                    let validation = self.validation.clone();
                    field.resolve = Some(Arc::new(move |context| {
                        let resolve = Arc::clone(&resolve);
                        let validation = validation.clone();
                        Box::pin(async move {
                            let args = coerce_args::<A>(
                                context.args,
                                context.info.parent_type,
                                context.info.field_name,
                            )?;
                            let ctx = context.context.require_data::<Ctx>()?;
                            validation.run(&args, ctx)?;
                            resolve(context).await
                        })
                    }));
                }
            }
        }
        self
    }

    /// Declare the field's GraphQL type as an interface or union instead of its concrete Rust
    /// type.
    ///
    /// The resolver still returns concrete model values; the executor's `is_type_of` check (or
    /// the abstract type's `resolve_type`) selects the concrete type per value. List and
    /// nullability wrappers are preserved.
    ///
    /// The compatibility check uses the field's current named type, so it composes with
    /// [`FieldConfig::as_object_ref`]: declare a runtime-named object first, then widen it to an
    /// interface or union that lists that object as a possible type.
    pub fn as_abstract(&mut self, reference: impl AbstractType) -> &mut Self {
        self.suppress_output_registration();
        let abstract_name: Name = Arc::from(reference.abstract_name());
        let original = self
            .sink
            .get(&self.name)
            .map_or_else(|| self.original().clone(), |field| field.ty.clone());
        if let Some(checks) = &mut self.checks {
            checks.push(FieldCheck::Abstract {
                owner: self.owner.clone(),
                field: self.name.clone(),
                original,
                abstract_name: abstract_name.clone(),
            });
        }
        if let Some(field) = self.sink.get_mut(&self.name) {
            field.ty = replace_named_type(&field.ty, abstract_name);
        }
        self
    }

    /// Declare the field's output type as a runtime-named object.
    ///
    /// The named type is replaced, keeping the list and nullability wrappers of the field's Rust
    /// type. This is what [`crate::ObjectBuilder::field_ref`] uses internally; it is public for
    /// fields whose type is declared separately, such as `raw_field`.
    ///
    /// The Rust type must be the model the reference was created for (`M` itself, or a wrapper
    /// such as [`crate::Raw<M>`] that delegates its output type to `M`). A mismatch is a build
    /// error.
    pub fn as_object_ref<M: ObjectModel>(&mut self, reference: &ObjectRef<M>) -> &mut Self {
        self.suppress_output_registration();
        self.registry.reference_object(reference.name());
        if self.checks.is_some() {
            let original = self.original().clone();
            if let Some(checks) = &mut self.checks {
                checks.push(FieldCheck::DynamicObject {
                    owner: self.owner.clone(),
                    field: self.name.clone(),
                    original,
                    model: M::NAME,
                });
            }
        }
        if let Some(field) = self.sink.get_mut(&self.name) {
            field.ty = replace_named_type(&field.ty, Arc::from(reference.name()));
        }
        self
    }

    /// Replace the field's GraphQL type with an explicitly built runtime type reference.
    ///
    /// Use this when the output type's name is computed at runtime and there is no object model
    /// to pass to [`FieldConfig::as_object_ref`] — for example a runtime-named interface or
    /// union, or a list such as `TypeRef::named(name).list().non_null()`.
    ///
    /// The wrappers must still be truthful for the resolver's Rust type: nullability may be
    /// loosened and never tightened, and the list shape must match. The named type must exist in
    /// the schema by build time.
    pub fn as_dynamic(&mut self, ty: TypeRef) -> &mut Self {
        self.suppress_output_registration();
        let current = self
            .sink
            .get(&self.name)
            .map_or_else(|| self.original().clone(), |field| field.ty.clone());
        if let Some(checks) = &mut self.checks {
            checks.push(FieldCheck::DynamicType {
                owner: self.owner.clone(),
                field: self.name.clone(),
                rust: current,
                declared: ty.clone(),
            });
        }
        if let Some(field) = self.sink.get_mut(&self.name) {
            field.ty = ty;
        }
        self
    }

    /// Replace the field's GraphQL type with `T`'s output type.
    ///
    /// This is the escape hatch for the rare case where a Rust type is serialized differently
    /// from how its own [`OutputType`] describes it — for example resolving a `String` but
    /// declaring a custom scalar, or resolving a model as an interface. `returns` is an alias.
    ///
    /// # Compatibility
    ///
    /// The override is checked when the schema is built. It is only accepted between scalars,
    /// between enums, or to and from an abstract type when the Rust type is a possible type of
    /// it. Wrappers are taken from `T`, unlike [`FieldConfig::as_abstract`] which preserves them,
    /// but they must be truthful for the resolver's Rust type: nullability may be loosened and
    /// never tightened, and the list shape must match. `Option<String>` cannot be declared
    /// `String!`, `Vec<Option<String>>` cannot be declared `[String!]!`, and `Vec<String>` cannot
    /// be declared `String!`.
    ///
    /// # Runtime risk
    ///
    /// Schema validation cannot see the runtime value of a scalar that is serialized by a custom
    /// conversion. If the resolver returns a value the new named type cannot serialize, the
    /// request still fails with a field error at execution time. Keep the Rust return type and
    /// the override honest.
    pub fn as_type<T: OutputType>(&mut self) -> &mut Self {
        self.override_type::<T>()
    }

    /// Alias for [`FieldConfig::as_type`].
    pub fn returns<T: OutputType>(&mut self) -> &mut Self {
        self.override_type::<T>()
    }

    fn override_type<T: OutputType>(&mut self) -> &mut Self {
        self.suppress_output_registration();
        T::register_output(self.registry);
        let replacement = T::output_type();
        if self.checks.is_some() {
            let original = self.original().clone();
            if let Some(checks) = &mut self.checks {
                checks.push(FieldCheck::TypeOverride {
                    owner: self.owner.clone(),
                    field: self.name.clone(),
                    original,
                    replacement: replacement.clone(),
                });
            }
        }
        if let Some(field) = self.sink.get_mut(&self.name) {
            field.ty = replacement;
        }
        self
    }

    /// Remove the outer non-null wrapper, making the field nullable.
    ///
    /// This is the safe direction: a resolver that always returns a value can still be declared
    /// nullable. The opposite direction, [`FieldConfig::non_null`], is checked against the Rust
    /// type.
    pub fn nullable(&mut self) -> &mut Self {
        if let Some(field) = self.sink.get_mut(&self.name) {
            if let TypeRef::NonNull(inner) = &field.ty {
                field.ty = (**inner).clone();
            }
        }
        // A preceding `non_null()` may have queued a check against the resolver's Rust type.
        // That check is no longer relevant once the final wrapper is nullable, and options are
        // documented to compose in any order.
        if let Some(checks) = &mut self.checks {
            checks.retain(|check| {
                !matches!(
                    check,
                    FieldCheck::NonNullOnOption { owner, field, .. }
                        if owner == &self.owner && field == &self.name
                )
            });
        }
        self
    }

    /// Add an outer non-null wrapper.
    ///
    /// Applying this to a resolver whose Rust return type is `Option<T>` is a schema build
    /// error, because a `None` would then violate the declared type.
    pub fn non_null(&mut self) -> &mut Self {
        if self.rust_nullable {
            if let Some(checks) = &mut self.checks {
                checks.push(FieldCheck::NonNullOnOption {
                    owner: self.owner.clone(),
                    field: self.name.clone(),
                    rust_type: self.rust_type_name,
                });
            }
        }
        if let Some(field) = self.sink.get_mut(&self.name) {
            if !matches!(field.ty, TypeRef::NonNull(_)) {
                field.ty = TypeRef::NonNull(Box::new(field.ty.clone()));
            }
        }
        self
    }

    /// Remove the item-level non-null wrapper from a list field.
    ///
    /// `[Giraffe!]!` becomes `[Giraffe]!`; the field's own nullability is unchanged. Applying
    /// this to a field that is not a list is a schema build error.
    pub fn nullable_items(&mut self) -> &mut Self {
        let Some(field) = self.sink.get_mut(&self.name) else {
            return self;
        };
        match nullable_items(&field.ty) {
            Some(ty) => field.ty = ty,
            None => {
                let ty = field.ty.clone();
                if let Some(checks) = &mut self.checks {
                    checks.push(FieldCheck::NullableItemsOnNonList {
                        owner: self.owner.clone(),
                        field: self.name.clone(),
                        ty,
                    });
                }
            }
        }
        self
    }

    /// Add the item-level non-null wrapper to a list field.
    ///
    /// `[Giraffe]!` becomes `[Giraffe!]!`; the field's own nullability is unchanged. Applying
    /// this to a field that is not a list is a schema build error.
    ///
    /// Only use this when the Rust collection's items cannot be `None`. Rust's type system is
    /// not reflected in the GraphQL wrapper, so this cannot be checked automatically: a
    /// `Vec<Option<T>>` must not be declared with non-null items.
    pub fn non_null_items(&mut self) -> &mut Self {
        let Some(field) = self.sink.get_mut(&self.name) else {
            return self;
        };
        match non_null_items(&field.ty) {
            Some(ty) => field.ty = ty,
            None => {
                let ty = field.ty.clone();
                if let Some(checks) = &mut self.checks {
                    checks.push(FieldCheck::NonNullItemsOnNonList {
                        owner: self.owner.clone(),
                        field: self.name.clone(),
                        ty,
                    });
                }
            }
        }
        self
    }
}

impl<Ctx: 'static> Drop for FieldConfig<'_, Ctx> {
    fn drop(&mut self) {
        if !self.suppress_deferred_output {
            if let Some(register) = self.deferred_output.take() {
                register(self.registry);
            }
        }
        let Some(field) = self.sink.get_mut(&self.name) else {
            return;
        };
        if let Some(description) = self.description.take() {
            field.description = Some(description);
        }
        if let Some(deprecation) = self.deprecation.take() {
            field.deprecation_reason = Some(deprecation);
        }
        if !self.directives.is_empty() {
            field.directives.append(&mut self.directives);
        }
        if let Some(complexity) = self.complexity.take() {
            field.complexity = Some(match complexity {
                Complexity::Fixed(value) => Arc::new(move |_| value),
                Complexity::Custom(function) => function,
            });
        }
        if let Some(predicate) = self.auth.take() {
            let guard = Arc::new(AuthGuard::new(predicate, self.auth_error.take()));
            if let Some(field_auth) = &mut self.field_auth {
                field_auth.insert(self.name.clone(), guard);
            } else {
                apply_auth_guard(field, guard);
            }
        }
    }
}

/// Options for an interface field.
///
/// Interface fields have no resolver: execution uses the concrete object's field. Authorization
/// declared here is inherited by every implementing object's matching field, so a rule can be
/// stated once on the interface. Descriptions and deprecation are metadata on the interface
/// field itself.
pub struct InterfaceFieldConfig<'a, Ctx: 'static> {
    inner: FieldConfig<'a, Ctx>,
}

impl<'a, Ctx: 'static> InterfaceFieldConfig<'a, Ctx> {
    pub(crate) fn new(inner: FieldConfig<'a, Ctx>) -> Self {
        Self { inner }
    }

    /// The GraphQL field name.
    #[must_use]
    pub fn name(&self) -> &str {
        self.inner.name()
    }

    /// Set the field's description.
    pub fn description(&mut self, description: impl Into<Arc<str>>) -> &mut Self {
        self.inner.description(description);
        self
    }

    /// Mark the field as deprecated with a reason shown by introspection.
    pub fn deprecated(&mut self, reason: impl Into<Arc<str>>) -> &mut Self {
        self.inner.deprecated(reason);
        self
    }

    /// Apply a directive to this interface field.
    ///
    /// The directive stays on the interface field. An implementing object that declares the
    /// field through [`crate::ObjectBuilder::resolve_inherited`] copies the interface field's
    /// directives that it does not already carry.
    pub fn directive(&mut self, directive: AppliedDirective) -> &mut Self {
        self.inner.directive(directive);
        self
    }

    /// Require every implementing object's field to satisfy `predicate`.
    ///
    /// The rule is attached to the interface field and applied when the schema is built, so an
    /// object does not have to repeat it.
    pub fn auth(&mut self, predicate: impl Fn(&Ctx) -> bool + Send + Sync + 'static) -> &mut Self {
        self.inner.auth(predicate);
        self
    }

    /// Like [`InterfaceFieldConfig::auth`], but asynchronous.
    pub fn auth_async(
        &mut self,
        predicate: impl for<'r> Fn(&'r Ctx) -> BoxFuture<'r, bool> + Send + Sync + 'static,
    ) -> &mut Self {
        self.inner.auth_async(predicate);
        self
    }

    /// Set the message returned when the inherited authorization denies access.
    pub fn auth_error(&mut self, message: impl Into<Arc<str>>) -> &mut Self {
        self.inner.auth_error(message);
        self
    }
}

impl<Ctx> std::fmt::Debug for FieldConfig<'_, Ctx> {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("FieldConfig")
            .field("name", &self.name)
            .field("description", &self.description)
            .field("deprecation", &self.deprecation)
            .field("authorized", &self.auth.is_some())
            .finish_non_exhaustive()
    }
}

/// Read a raw field's value from the executor parent value.
///
/// A raw object field has no resolver: its value comes from the object map produced by
/// [`crate::Raw::object`]. A model parent (`Value::External`) means the object was resolved
/// normally, so the map is absent and the field cannot be read.
pub(crate) fn read_raw_field(
    field_name: &str,
    parent: &gql::Value,
) -> Result<gql::Value, GraphQLError> {
    match parent {
        gql::Value::Object(object) => {
            Ok(object.get(field_name).cloned().unwrap_or(gql::Value::Null))
        }
        gql::Value::Null => Ok(gql::Value::Null),
        gql::Value::External(_) => Err(GraphQLError::new(format!(
            "Field \"{field_name}\" is a raw field with no resolver, but its parent is a model \
             value, not a raw object. Resolve the parent with `Raw`, or declare the field with a \
             resolver."
        ))),
        other => Err(GraphQLError::new(format!(
            "Field \"{field_name}\" is a raw field with no resolver and its parent is a {}, not \
             an object.",
            other.kind()
        ))),
    }
}

/// Install the executor's default property resolver on a field that has none.
///
/// Raw object fields intentionally have no resolver, so the executor reads the value from the
/// object map without a per-field call. Authorization, however, is applied by wrapping the
/// field's resolver. When an authorization rule reaches such a field, install an equivalent
/// property resolver first so the guard cannot be silently skipped.
pub(crate) fn install_property_resolver(field: &mut Field) {
    if field.resolve.is_some() || field.sync_resolve.is_some() || field.subscribe.is_some() {
        return;
    }
    field.resolve = Some(property_resolver(field.name.clone()));
}

/// Replace a synchronous property resolver with the equivalent boxed resolver.
///
/// A builder option that needs a future — a validation hook, field authorization, or a plugin
/// wrapper — cannot call the synchronous hook from inside its own future unless the hook is
/// boxed. Converting here, when the option is applied, keeps the allocation-free path for every
/// field that never receives such an option.
pub(crate) fn materialize_resolve(field: &mut Field) {
    if field.sync_resolve.is_some() {
        field.resolve = field.take_resolve();
    }
}

/// The resolver a raw field would use if the executor ran its default property lookup.
///
/// Plugins use it as `next` while deciding whether they wrap a raw field. If no plugin wraps,
/// the caller leaves the field without a resolver and the executor keeps its leaf fast path.
pub(crate) fn property_resolver(name: Name) -> gql::ResolveFn {
    Arc::new(move |context| {
        let name = name.clone();
        Box::pin(async move { read_raw_field(&name, context.parent) })
    })
}

/// Wrap a field's resolvers with an authorization check.
///
/// Used for field-level auth as the config is dropped, and for object- and interface-level auth
/// when the schema is built. Wrapping here rather than relying on the executor's authorizer keeps
/// the feature available even when a server does not install one.
pub(crate) fn apply_auth_guard<Ctx: 'static>(field: &mut Field, guard: Arc<AuthGuard<Ctx>>) {
    install_property_resolver(field);
    materialize_resolve(field);
    let resolve_guard = Arc::clone(&guard);
    if let Some(resolve) = field.resolve.take() {
        field.resolve = Some(Arc::new(move |context| {
            let resolve = Arc::clone(&resolve);
            let guard = Arc::clone(&resolve_guard);
            Box::pin(async move {
                let ctx = context.context.require_data::<Ctx>()?;
                guard.check(ctx).await?;
                let _span = crate::telemetry::span_if_enabled!(
                    tracing::Level::TRACE,
                    "gurafi",
                    "gurafi.resolver",
                    parent_type = context.info.parent_type,
                    field = context.info.field_name,
                );
                crate::telemetry::instrument_span!(_span.clone(), resolve(context)).await
            })
        }));
    }
    if let Some(subscribe) = field.subscribe.take() {
        field.subscribe = Some(Arc::new(move |context| {
            let subscribe = Arc::clone(&subscribe);
            let guard = Arc::clone(&guard);
            Box::pin(async move {
                let ctx = context.context.require_data::<Ctx>()?;
                guard.check(ctx).await?;
                subscribe(context).await
            })
        }));
    }
}

pub(crate) fn sync_guard<Ctx: 'static>(
    predicate: impl Fn(&Ctx) -> bool + Send + Sync + 'static,
    message: Option<Arc<str>>,
) -> Arc<AuthGuard<Ctx>> {
    Arc::new(AuthGuard::new(
        GuardPredicate::Sync(Arc::new(predicate)),
        message,
    ))
}

pub(crate) fn async_guard<Ctx: 'static>(
    predicate: impl for<'r> Fn(&'r Ctx) -> BoxFuture<'r, bool> + Send + Sync + 'static,
    message: Option<Arc<str>>,
) -> Arc<AuthGuard<Ctx>> {
    Arc::new(AuthGuard::new(
        GuardPredicate::Async(Arc::new(predicate)),
        message,
    ))
}

fn replace_named_type(ty: &TypeRef, name: Name) -> TypeRef {
    match ty {
        TypeRef::Named(_) => TypeRef::Named(name),
        TypeRef::List(inner) => TypeRef::List(Box::new(replace_named_type(inner, name))),
        TypeRef::NonNull(inner) => TypeRef::NonNull(Box::new(replace_named_type(inner, name))),
    }
}

/// Add the item non-null to a list type, preserving the outer nullability.
fn non_null_items(ty: &TypeRef) -> Option<TypeRef> {
    match ty {
        TypeRef::NonNull(inner) => non_null_items(inner).map(|ty| TypeRef::NonNull(Box::new(ty))),
        TypeRef::List(inner) => Some(TypeRef::List(match inner.as_ref() {
            TypeRef::NonNull(_) => inner.clone(),
            other => Box::new(TypeRef::NonNull(Box::new(other.clone()))),
        })),
        TypeRef::Named(_) => None,
    }
}

/// Remove the item non-null from a list type, preserving the outer nullability.
fn nullable_items(ty: &TypeRef) -> Option<TypeRef> {
    match ty {
        TypeRef::NonNull(inner) => nullable_items(inner).map(|ty| TypeRef::NonNull(Box::new(ty))),
        TypeRef::List(inner) => Some(TypeRef::List(match inner.as_ref() {
            TypeRef::NonNull(item) => item.clone(),
            other => Box::new(other.clone()),
        })),
        TypeRef::Named(_) => None,
    }
}