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
//! A type-safe, code-first GraphQL schema builder for Rust.
//!
//! `gurafi` sits on top of [`gql`], which implements the GraphQL specification. This crate adds
//! the part a Rust developer actually writes: Rust types drive GraphQL types, field declarations
//! derive their arguments from a Rust `Args` type, and mistakes are compile errors wherever
//! possible.
//!
//! # The idea
//!
//! - `#[derive(Object)]`, `#[derive(Input)]`, `#[derive(Enum)]`, `#[derive(Scalar)]` and
//! `#[derive(Union)]` register a Rust type as a GraphQL type.
//! - `#[derive(ErrorUnion)]` and `field_result_union` expose a `Result<T, E>` as a generated
//! GraphQL union of a success payload and typed error payloads.
//! - A field's GraphQL output type is inferred from its Rust return type via [`OutputType`].
//! - A field's GraphQL arguments are inferred from its Rust arguments type via [`InputObject`].
//! There is no second list of argument declarations to keep in sync. An `Input` type is
//! args-only by default; add `#[graphql(name = "FilterInput")]` when it should also be a
//! reusable input object nested inside other inputs.
//! - Resolvers always receive `(&Model, Args, &Ctx)` for object fields and `(Args, &Ctx)` for
//! root fields, with sync, async, infallible and fallible variants. `*_with_info` variants add
//! the [`gql::ResolveInfo`].
//! - Field options are chained on the returned [`FieldConfig`]: descriptions, deprecation,
//! complexity estimates, authorization, nullability and checked type overrides.
//! - A type's definition can be split across modules with [`Schema::object_fields`],
//! [`Schema::interface_fields`] and the root `*_fields` methods; declarations merge.
//! - Object, interface and union names can be computed at runtime with [`Schema::object_ref`],
//! [`Schema::interface_ref`] and [`Schema::union_ref`]. The reference keeps the model for
//! resolvers and `is_type_of`, while [`ObjectBuilder::field_ref`] and
//! [`FieldConfig::as_dynamic`] declare the runtime name in output positions. This is how
//! Relay-style `UserPostsConnection` and `CreateUserPayload` types are expressed.
//!
//! # Example
//!
//! ```
//! use gurafi::{Enum, ID, Input, NoArgs, Object, Result, Schema, expose};
//!
//! struct Ctx {
//! is_logged_in: bool,
//! }
//!
//! #[derive(Object)]
//! #[graphql(description = "A long-necked animal.")]
//! struct Giraffe {
//! name: String,
//! birthday: String,
//! height: f32,
//! }
//!
//! #[derive(Input)]
//! struct FriendsArgs {
//! #[graphql(description = "Max results", default = 10)]
//! limit: i32,
//! after: Option<String>,
//! }
//!
//! #[derive(Enum)]
//! enum Color {
//! #[graphql(name = "RED")]
//! Red,
//! Blue,
//! }
//!
//! let mut schema = Schema::<Ctx>::new();
//!
//! let node = schema.interface("Node", |i| {
//! i.description("Anything with an id").field::<ID>("id");
//! });
//!
//! schema.object::<Giraffe>(|o| {
//! o.description("Long necks.");
//! o.implements(&node);
//! o.expose(expose!(Giraffe::name));
//! o.expose(expose!(Giraffe::height)).deprecated("Use heightMeters");
//! o.field("id", |g: &Giraffe, _: NoArgs, _: &Ctx| ID::new(g.name.clone()));
//! o.field("age", |g: &Giraffe, _: NoArgs, _: &Ctx| {
//! g.birthday.parse::<u16>().ok()
//! })
//! .description("Age in years");
//! o.field_result("friends", |_: &Giraffe, _: FriendsArgs, _: &Ctx| {
//! Result::Ok(Vec::<Giraffe>::new())
//! });
//! o.field_async("nameAsync", |g: &Giraffe, _: NoArgs, _: &Ctx| {
//! Box::pin(async move { g.name.clone() })
//! });
//! });
//!
//! schema.query(|q| {
//! q.field("giraffe", |_: NoArgs, _: &Ctx| Giraffe {
//! name: "Melman".into(),
//! birthday: "2001-04-12".into(),
//! height: 3.4,
//! })
//! .auth(|ctx: &Ctx| ctx.is_logged_in)
//! .complexity(2);
//! });
//!
//! let gql_schema: gql::Schema = schema.build().expect("valid schema");
//! assert!(gql_schema.object_type("Giraffe").is_some());
//! ```
//!
//! # Authentication and authorization
//!
//! Authentication is the server's job: it validates a token and puts the resulting user into
//! the context passed to [`gql::ExecutionOptions::with_context`]. Authorization is per field:
//! [`FieldConfig::auth`] runs a predicate against that context before the resolver, and a denial
//! is a normal GraphQL error, so it participates in null propagation. Root and nested fields use
//! the same mechanism.
//!
//! Whole-object rules are declared once with [`ObjectBuilder::auth`]; interface rules with
//! [`InterfaceBuilder::auth`] are inherited by every implementing object, including through
//! another interface. `auth_async` variants await a boxed future, and interface fields can carry
//! their own authorization that objects inherit. Every variant composes with field-level checks.
//!
//! # Asynchronous resolvers
//!
//! An async resolver returns a boxed future:
//!
//! ```
//! # use gurafi::{Object, Schema, NoArgs};
//! # struct Ctx {}
//! # #[derive(Object)] struct Giraffe { name: String }
//! # let mut schema = Schema::<Ctx>::new();
//! # schema.object::<Giraffe>(|o| {
//! o.field_async("name", |g: &Giraffe, _: NoArgs, _: &Ctx| {
//! Box::pin(async move { g.name.clone() })
//! });
//! # });
//! ```
//!
//! `Box::pin` is required because the closure must return a future that borrows the model, and
//! Rust's `Fn` traits cannot express a return type that borrows from the closure's arguments.
//! The executor boxes resolver futures anyway, so this is not an extra allocation in practice.
//!
//! # Resolving a whole object at once
//!
//! [`Raw<T>`] returns a prebuilt [`gql::Value`] while taking its schema type from `T`. Declare
//! the object's fields with [`ObjectBuilder::raw_field`] and the executor reads them from the
//! map, so one resolver can produce an entire object:
//!
//! ```
//! # use gurafi::{NoArgs, Object, Raw, RawObject, Schema};
//! # struct Ctx;
//! # #[derive(Object)] struct Giraffe { name: String, height: f32 }
//! # let mut schema = Schema::<Ctx>::new();
//! schema.object::<Giraffe>(|o| {
//! o.raw_field::<String>("name");
//! o.raw_field::<f32>("height");
//! });
//! schema.query(|q| {
//! q.field("giraffe", |_: NoArgs, _: &Ctx| {
//! Raw::<Giraffe>::object(
//! RawObject::new()
//! .field("name", "Melman")
//! .field("height", 3.4)
//! .build(),
//! )
//! });
//! });
//! # let _ = schema.build().expect("valid schema");
//! ```
//!
//! The caller is responsible for field names, nullability and `__typename`; most mistakes are
//! execution-time field errors with normal null propagation. Custom scalar values are passed
//! through unchanged, and mixing a raw field with a resolver-backed field is a build error. See
//! [`Raw`] and [`RawObject`] for lists, abstract types, reserved `__gql_*` keys and the
//! performance tradeoff.
//!
//! # Plugins
//!
//! [`Schema::plugin`] registers a build-time extension that sees every object, interface and
//! root field. A plugin can change metadata through [`FieldMeta`] and [`Plugin::field`], wrap
//! resolvers with [`Plugin::wrap_resolve`] and subscription factories with
//! [`Plugin::wrap_subscribe`], or add types and directives through [`Plugin::configure`].
//! Plugins are applied once when the schema is built, so fields declared before or after
//! registration are covered equally.
//!
//! ```
//! use gurafi::{NoArgs, ResponseExtensionPlugin, Schema};
//!
//! struct Ctx;
//!
//! let mut schema = Schema::<Ctx>::new();
//! schema.plugin(ResponseExtensionPlugin::new("servedBy", "gurafi").root_only());
//! schema.query(|q| {
//! q.field("ok", |_: NoArgs, _: &Ctx| true);
//! });
//! let schema = schema.build().expect("valid schema");
//! # let _ = schema;
//! ```
//!
//! [`TracingPlugin`] emits start/finish events without depending on a particular logging crate,
//! and [`MockPlugin`] replaces named fields for tests. See the [`plugin`] module for ordering,
//! coverage and the full hook documentation.
//!
//! # Custom directives
//!
//! A directive is registered once with [`Schema::directive`] and applied where it belongs. The
//! definition is the `gql` model, so descriptions, arguments, repeatability and locations come
//! from the usual builders:
//!
//! ```
//! use gurafi::{NoArgs, Object, Schema};
//!
//! struct Ctx;
//!
//! #[derive(Object)]
//! struct Giraffe {
//! name: String,
//! }
//!
//! let mut schema = Schema::<Ctx>::new();
//! schema.directive(
//! gql::DirectiveDefinition::new("tag")
//! .description("A documentation tag.")
//! .location(gql::ast::DirectiveLocation::Object)
//! .location(gql::ast::DirectiveLocation::FieldDefinition)
//! .repeatable()
//! .arg(gql::InputValue::new("name", gql::TypeRef::string())),
//! );
//!
//! // Apply by name; the type may be registered before or after this call.
//! schema.type_directive(
//! "Giraffe",
//! gql::AppliedDirective::new("tag").argument("name", "animal"),
//! );
//!
//! schema.object::<Giraffe>(|o| {
//! o.directive(gql::AppliedDirective::new("tag").argument("name", "declared"));
//! o.field("name", |g: &Giraffe, _: NoArgs, _: &Ctx| g.name.clone())
//! .directive(gql::AppliedDirective::new("tag").argument("name", "public"));
//! });
//! schema.query(|q| {
//! q.field("giraffe", |_: NoArgs, _: &Ctx| Giraffe { name: "Melman".into() });
//! });
//!
//! let sdl = schema.build().expect("valid schema").sdl();
//! assert!(sdl.contains("type Giraffe @tag(name: \"declared\") @tag(name: \"animal\")"));
//! assert!(sdl.contains("name: String! @tag(name: \"public\")"));
//! ```
//!
//! Applications attach at the declaration site with [`ObjectBuilder::directive`],
//! [`InterfaceBuilder::directive`], [`UnionBuilder::directive`], [`FieldConfig::directive`] and
//! [`InterfaceFieldConfig::directive`]. Types registered elsewhere use
//! [`Schema::type_directive`], which accepts an object, interface, union, scalar, enum, input
//! object or root operation type and works whether the type already exists or is registered
//! later. Field arguments and input object fields use [`Schema::argument_directive`] and
//! [`Schema::input_field_directive`].
//!
//! Definitions are validated by the same rules as SDL: an unknown directive, a location the
//! definition does not allow, a wrong argument type, a missing required argument and a repeated
//! use of a non-repeatable directive are build errors. Definitions appear in SDL and in
//! introspection's `__schema.directives`; applications appear in SDL. Standard introspection has
//! no field for *applied* directives, so a client that needs them reads the SDL.
//!
//! The `#[graphql(directive = "...")]` derive attribute is not implemented. A directive on a
//! derived type or field is declared on the builder instead, which keeps every application in
//! the schema where the rest of the type's shape is defined.
//!
//! # Batching and per-request caches
//!
//! [`Loader`] collects loads issued in the same scheduler tick into one call of a user-supplied
//! batch function, deduplicates keys that are already in flight, and caches each result for the
//! rest of the request. It is spawn-free and executor-agnostic, so it needs no timer and no
//! runtime-specific API. [`RequestCache`] is a type-keyed store scoped to one request, which is
//! where loaders and other request-wide state belong: put both in the context passed to
//! [`gql::ExecutionOptions::with_context`] and every resolver in that request shares them, while
//! the next request starts empty.
//!
//! # Observability
//!
//! The optional `tracing` feature instruments schema building, plugin application, authorization,
//! validation, resolvers, error-union dispatch, [`Loader`] batching and [`RequestCache`] lookups.
//! It is off by default. Loader spans record the key *type* and cache hit/miss, never key values;
//! per-resolver and cache events are TRACE. See the repository's `docs/plugins/tracing.md`.
pub use gql;
pub use RequestCache;
pub use SchemaError;
pub use ErrorUnionModel;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ID;
pub use ;
pub use ;
pub use ;
pub use TypeRegistry;
pub use ;
pub use ;
pub use Upload;
/// The result type used by fallible resolvers.
///
/// `E = gql::GraphQLError` is the default, so `Result<Vec<Giraffe>>` is
/// `Result<Vec<Giraffe>, GraphQLError>` and any error type implementing
/// `Into<gql::GraphQLError>` also works.
pub type Result<T, E = GraphQLError> = Result;
/// Implement the conversions needed to use a hand-written [`ScalarValue`] type in a schema.
///
/// [`derive(Scalar)`](macro@Scalar) writes these impls for newtype scalars. A scalar with a
/// custom representation implements [`ScalarValue`] by hand and then invokes this macro:
///
/// ```
/// use gurafi::{GraphQLError, ScalarValue, Value, impl_scalar_traits};
///
/// struct Slug(String);
///
/// impl ScalarValue for Slug {
/// const NAME: &'static str = "Slug";
///
/// fn to_value(&self) -> Result<Value, GraphQLError> {
/// Ok(Value::String(self.0.clone().into()))
/// }
///
/// fn from_value(value: &Value) -> Result<Self, GraphQLError> {
/// value
/// .as_str()
/// .map(|value| Self(value.to_owned()))
/// .ok_or_else(|| GraphQLError::new("Expected a string."))
/// }
/// }
///
/// impl_scalar_traits!(Slug);
/// ```