gql 0.3.1

A GraphQL reference implementation 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
//! Request execution.
//!
//! Execution is split into the stages required by the specification: parse, validate, select an
//! operation, coerce variables, enforce request limits, then resolve fields. Each stage produces
//! specification-shaped errors instead of panicking, and a request that fails validation never
//! reaches a resolver. Resolver callbacks are the one place caller code runs, so each invocation
//! is isolated: a resolver panic becomes a coded `INTERNAL_SERVER_ERROR` field error rather than
//! an unwind (see the panic-isolation helper).

pub(crate) mod coerce;
mod collect;
mod executor;
mod panic;
mod plan;
mod prepared;
mod selection;
pub(crate) mod subscription;

pub(crate) use prepared::{
    BuildPreparedError, PreparedDocument, build as build_prepared, execute as execute_prepared,
    execute_event as execute_prepared_event, root_type as prepared_root_type,
    subscribe as subscribe_prepared,
};

use std::{any::Any, fmt, sync::Arc, time::Duration};

use futures::{FutureExt, future::BoxFuture, stream::BoxStream};

use crate::{
    Object, Value,
    error::{GraphQLError, PathSegment, Response},
    schema::Schema,
    types::{ResolveInfo, TypeRef},
};

pub use coerce::{CoercedVariables, coerce_argument_values, coerce_variable_values};
pub use subscription::SubscriptionResponse;

/// Limits and hooks applied to one execution.
pub struct ExecutionOptions {
    /// Arbitrary per-request data made available to resolvers.
    ///
    /// A server usually puts its authenticated user, database handles and request identifiers in
    /// here. `gql` never interprets it.
    pub context: Arc<dyn Any + Send + Sync>,
    /// The root value passed to root field resolvers.
    pub root_value: Value,
    /// Whether `__schema` and `__type` introspection fields may be used.
    pub introspection: bool,
    /// An optional field authorization hook.
    pub authorizer: Option<Arc<dyn Authorizer>>,
    /// Reject operations deeper than this many selection-set levels.
    ///
    /// Zero disables the configurable limit. The parser always rejects documents nested more
    /// than [`crate::parser::MAX_DEPTH`] levels deep, because execution itself is recursive.
    pub max_depth: usize,
    /// Reject operations whose estimated cost exceeds this value.
    pub max_complexity: u32,
    /// Reject operations with more than this many distinct fields in any one selection set.
    ///
    /// This complements [`Self::max_depth`] by bounding wide, shallow queries. Zero disables the
    /// limit.
    pub max_breadth: usize,
    /// Multiplier applied to list fields while estimating complexity.
    pub list_complexity: u32,
    /// Maximum number of errors reported before execution stops reporting further errors.
    /// Zero disables the limit.
    pub max_errors: usize,
    /// Maximum number of sibling fields resolved concurrently. Zero means unlimited.
    ///
    /// Mutations always execute serially, as the specification requires.
    pub max_concurrency: usize,
    /// An optional wall-clock deadline for the whole operation.
    pub timeout: Option<Duration>,
}

impl fmt::Debug for ExecutionOptions {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("ExecutionOptions")
            .field("root_value", &self.root_value)
            .field("introspection", &self.introspection)
            .field("authorizer", &self.authorizer.is_some())
            .field("max_depth", &self.max_depth)
            .field("max_complexity", &self.max_complexity)
            .field("max_breadth", &self.max_breadth)
            .field("list_complexity", &self.list_complexity)
            .field("max_errors", &self.max_errors)
            .field("max_concurrency", &self.max_concurrency)
            .field("timeout", &self.timeout)
            .finish_non_exhaustive()
    }
}

impl Default for ExecutionOptions {
    fn default() -> Self {
        Self {
            context: Arc::new(()),
            root_value: Value::Null,
            introspection: true,
            authorizer: None,
            max_depth: 0,
            max_complexity: 0,
            max_breadth: 0,
            list_complexity: 10,
            max_errors: 100,
            max_concurrency: 16,
            timeout: None,
        }
    }
}

impl ExecutionOptions {
    /// Options with a typed context object.
    #[must_use]
    pub fn with_context<T: Any + Send + Sync>(context: T) -> Self {
        Self {
            context: Arc::new(context),
            ..Self::default()
        }
    }

    /// Replace the context object.
    #[must_use]
    pub fn context<T: Any + Send + Sync>(mut self, context: T) -> Self {
        self.context = Arc::new(context);
        self
    }

    /// Set the root value.
    #[must_use]
    pub fn root_value(mut self, value: impl Into<Value>) -> Self {
        self.root_value = value.into();
        self
    }

    /// Enable or disable introspection.
    #[must_use]
    pub const fn introspection(mut self, enabled: bool) -> Self {
        self.introspection = enabled;
        self
    }

    /// Install a field authorizer.
    #[must_use]
    pub fn authorizer(mut self, authorizer: impl Authorizer + 'static) -> Self {
        self.authorizer = Some(Arc::new(authorizer));
        self
    }

    /// Limit query depth.
    #[must_use]
    pub const fn max_depth(mut self, depth: usize) -> Self {
        self.max_depth = depth;
        self
    }

    /// Limit estimated query complexity.
    #[must_use]
    pub const fn max_complexity(mut self, complexity: u32) -> Self {
        self.max_complexity = complexity;
        self
    }

    /// Limit the number of distinct fields in any one selection set.
    ///
    /// Zero disables the limit.
    #[must_use]
    pub const fn max_breadth(mut self, breadth: usize) -> Self {
        self.max_breadth = breadth;
        self
    }

    /// Limit the number of reported errors.
    #[must_use]
    pub const fn max_errors(mut self, max_errors: usize) -> Self {
        self.max_errors = max_errors;
        self
    }

    /// Limit how many sibling fields resolve concurrently. Zero means unlimited.
    #[must_use]
    pub const fn max_concurrency(mut self, max_concurrency: usize) -> Self {
        self.max_concurrency = max_concurrency;
        self
    }
}

/// Per-request execution state, visible to resolvers and introspection.
pub struct ExecutionContext {
    /// The schema being executed.
    pub schema: Schema,
    /// Per-request user data from [`ExecutionOptions::context`].
    pub user_data: Arc<dyn Any + Send + Sync>,
    /// The selected operation's name.
    pub operation_name: Option<Arc<str>>,
    /// Coerced variable values, including defaults.
    pub variables: Object,
    /// Whether introspection is enabled for this request.
    pub introspection: bool,
    /// The field authorizer, when one was configured.
    pub authorizer: Option<Arc<dyn Authorizer>>,
    /// The maximum number of errors to report.
    pub max_errors: usize,
    /// The maximum number of sibling fields resolved concurrently. Zero means unlimited.
    pub max_concurrency: usize,
    /// Extensions that plugins may write into the response.
    pub extensions: std::sync::Mutex<Option<Object>>,
}

impl fmt::Debug for ExecutionContext {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("ExecutionContext")
            .field("operation_name", &self.operation_name)
            .field("variables", &self.variables)
            .field("introspection", &self.introspection)
            .finish_non_exhaustive()
    }
}

impl ExecutionContext {
    /// Downcast the user data to a concrete type.
    #[must_use]
    pub fn data<T: Any>(&self) -> Option<&T> {
        self.user_data.downcast_ref()
    }

    /// Downcast the user data, returning a GraphQL error when the type is wrong.
    ///
    /// # Errors
    ///
    /// Returns an error when the server supplied a different context type. This should be
    /// unreachable in well-typed setups, but reporting it is far better than panicking inside a
    /// request.
    pub fn require_data<T: Any>(&self) -> Result<&T, GraphQLError> {
        self.data().ok_or_else(|| {
            GraphQLError::new("Execution context has an unexpected type; check the server setup.")
        })
    }

    /// Store a response extension.
    pub fn set_extension(&self, key: impl Into<Arc<str>>, value: impl Into<Value>) {
        if let Ok(mut extensions) = self.extensions.lock() {
            extensions
                .get_or_insert_with(Object::new)
                .insert(key, value);
        }
    }
}

/// Information passed to an [`Authorizer`] for each field.
pub struct AuthorizationContext<'a> {
    /// The execution context.
    pub context: &'a ExecutionContext,
    /// The field's name in the schema.
    pub field_name: &'a str,
    /// The parent type's name.
    pub parent_type: &'a str,
    /// The field's return type.
    pub return_type: &'a TypeRef,
    /// The response path to the field.
    pub path: &'a [PathSegment],
    /// The coerced arguments.
    pub args: &'a Object,
    /// Static field information, shared with resolvers.
    pub info: &'a ResolveInfo<'a>,
}

impl fmt::Debug for AuthorizationContext<'_> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("AuthorizationContext")
            .field("field_name", &self.field_name)
            .field("parent_type", &self.parent_type)
            .field("path", &self.path)
            .finish_non_exhaustive()
    }
}

/// A field-level authorization hook.
///
/// Authentication (who the caller is) belongs to the HTTP layer. Authorization (whether this
/// caller may see this field) is enforced here, immediately before a resolver runs, so a denied
/// field behaves like a resolver error: it is nulled in the response and reported in `errors`.
pub trait Authorizer: Send + Sync {
    /// Decide whether a field may be resolved, synchronously.
    ///
    /// This is the easy implementation path and the default `authorize_async` wraps it in a
    /// ready future. Override [`Authorizer::authorize_async`] when the decision needs to wait on
    /// I/O (for example, an object-level permission lookup).
    ///
    /// # Errors
    ///
    /// Return an error to deny access. The error message is exposed to the client, so avoid
    /// leaking sensitive details.
    fn authorize(&self, context: &AuthorizationContext<'_>) -> Result<(), GraphQLError> {
        let _ = context;
        Ok(())
    }

    /// Decide whether a field may be resolved, asynchronously.
    ///
    /// The executor awaits this immediately before resolving the field. The default forwards to
    /// [`Authorizer::authorize`], so synchronous authorizers only need to implement that method.
    ///
    /// # Errors
    ///
    /// Return an error to deny access. The error message is exposed to the client, so avoid
    /// leaking sensitive details.
    fn authorize_async<'a>(
        &'a self,
        context: &'a AuthorizationContext<'a>,
    ) -> BoxFuture<'a, Result<(), GraphQLError>> {
        futures::future::ready(self.authorize(context)).boxed()
    }
}

/// A GraphQL request.
#[derive(Clone, Copy, Debug)]
pub struct Request<'a> {
    /// The GraphQL document.
    pub query: &'a str,
    /// The operation to execute when the document contains more than one.
    pub operation_name: Option<&'a str>,
    /// Variable values, as a JSON-like object.
    pub variables: Option<&'a Object>,
}

impl<'a> Request<'a> {
    /// A request for a document with no variables.
    #[must_use]
    pub const fn new(query: &'a str) -> Self {
        Self {
            query,
            operation_name: None,
            variables: None,
        }
    }

    /// Select an operation by name.
    #[must_use]
    pub const fn operation_name(mut self, name: &'a str) -> Self {
        self.operation_name = Some(name);
        self
    }

    /// Attach variable values.
    #[must_use]
    pub const fn variables(mut self, variables: &'a Object) -> Self {
        self.variables = Some(variables);
        self
    }
}

/// Execute a GraphQL request.
///
/// The returned response always has the shape a GraphQL client expects: `data` is omitted when
/// execution could not start, `errors` is omitted when there were none, and partial data is
/// preserved exactly as the specification requires.
#[cfg_attr(
    feature = "tracing",
    tracing::instrument(
        skip_all,
        level = "info",
        name = "gql.execute",
        fields(
            operation = request.operation_name.unwrap_or("<anonymous>"),
            document_bytes = request.query.len(),
            variable_count = request.variables.map_or(0, Object::len),
            kind = tracing::field::Empty,
            errors = tracing::field::Empty,
        )
    )
)]
pub async fn execute(
    schema: &Schema,
    request: Request<'_>,
    options: &ExecutionOptions,
) -> Response {
    executor::execute(schema, request, options).await
}

/// Execute a GraphQL subscription.
///
/// Parsing, validation and subscription-field selection happen immediately. The returned stream
/// then yields one response per source event. Errors during setup are returned as a response
/// instead of a stream.
///
/// # Errors
///
/// Returns a fully formed error response when the request is invalid or the subscription could
/// not be started.
#[cfg_attr(
    feature = "tracing",
    tracing::instrument(
        skip_all,
        level = "info",
        name = "gql.subscribe",
        fields(
            operation = request.operation_name.unwrap_or("<anonymous>"),
            document_bytes = request.query.len(),
            variable_count = request.variables.map_or(0, Object::len),
            kind = "subscription",
            errors = tracing::field::Empty,
        )
    )
)]
pub async fn subscribe(
    schema: &Schema,
    request: Request<'_>,
    options: &ExecutionOptions,
) -> Result<SubscriptionResponse, Response> {
    subscription::subscribe(schema, request, options).await
}

/// A boxed stream of subscription responses, useful for transport layers.
pub type ResponseStream = BoxStream<'static, Response>;