suku 0.1.1

GraphQL over HTTP 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
//! Persisted-query manifests.
//!
//! [`PreparedQueries`] loads operation text from the JSON manifests produced by Relay,
//! graphql-codegen, Apollo tooling, Hive, Envelop and urql, and builds a
//! [`gql::prepared::PreparedQueryRegistry`] once at startup. Requests then carry only an
//! identifier; the query text is never trusted or parsed per request.
//!
//! # Supported manifest shapes
//!
//! ```json
//! { "queryId": "query { hello }" }
//! ```
//!
//! ```json
//! { "operations": [ { "id": "a", "body": "query { hello }", "name": "Hello", "type": "query" } ] }
//! ```
//!
//! ```json
//! [ { "hash": "a", "query": "query { hello }" } ]
//! ```
//!
//! * Relay's generated manifest is the first form.
//! * Hive, Envelop and GraphQL Codegen's operation manifests are the second form.
//! * graphql-codegen's persisted-document output and urql's document map are the first form.
//! * An object under `"operations"` (or `"documents"`) may itself be a map of id to text.
//!
//! Operation objects accept `id`/`hash`/`sha256Hash`/`queryId` for the identifier,
//! `body`/`query`/`document`/`source` for the text, `name`/`operationName` for the operation
//! name, and `type` for a query/mutation/subscription check.

use std::{collections::HashSet, sync::Arc};

use gql::{
    Schema,
    ast::OperationKind,
    prepared::{PreparedQuery, PreparedQueryRegistry, PreparedQueryRegistryError},
};
use serde::{
    Deserialize,
    de::{self, Deserializer, MapAccess, SeqAccess, Visitor},
};
use serde_json::{Map as JsonMap, Value as JsonValue};

/// One operation loaded from a manifest.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct PreparedOperation {
    /// The persisted identifier.
    pub id: String,
    /// The GraphQL source.
    pub source: String,
    /// The operation to execute when the source contains several.
    pub operation_name: Option<String>,
    /// The operation type declared by the manifest, when it declares one.
    pub kind: Option<OperationKind>,
}

impl PreparedOperation {
    /// Create an operation entry.
    #[must_use]
    pub fn new(id: impl Into<String>, source: impl Into<String>) -> Self {
        Self {
            id: id.into(),
            source: source.into(),
            operation_name: None,
            kind: None,
        }
    }

    /// Select an operation by name.
    #[must_use]
    pub fn operation_name(mut self, name: impl Into<String>) -> Self {
        self.operation_name = Some(name.into());
        self
    }

    /// Record the manifest's operation type.
    #[must_use]
    pub fn kind(mut self, kind: OperationKind) -> Self {
        self.kind = Some(kind);
        self
    }
}

/// An error produced while loading a manifest.
#[derive(Debug)]
pub enum PreparedQueriesError {
    /// The manifest was not valid JSON.
    Json(serde_json::Error),
    /// The JSON was valid but did not have a supported manifest shape.
    Invalid(String),
    /// A query in the manifest was invalid against the schema.
    Registry(PreparedQueryRegistryError),
    /// The manifest's `type` disagreed with the operation it contains.
    KindMismatch {
        /// The operation's identifier.
        id: String,
        /// The type the manifest declared.
        expected: OperationKind,
        /// The type actually parsed from the source.
        actual: OperationKind,
    },
}

impl std::fmt::Display for PreparedQueriesError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Json(error) => write!(f, "invalid persisted-query manifest JSON: {error}"),
            Self::Invalid(message) => write!(f, "invalid persisted-query manifest: {message}"),
            Self::Registry(error) => write!(f, "{error}"),
            Self::KindMismatch {
                id,
                expected,
                actual,
            } => write!(
                f,
                "prepared query \"{id}\" is declared as {expected} but contains a {actual} operation"
            ),
        }
    }
}

impl std::error::Error for PreparedQueriesError {
    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
        match self {
            Self::Json(error) => Some(error),
            Self::Registry(error) => Some(error),
            Self::Invalid(_) | Self::KindMismatch { .. } => None,
        }
    }
}

impl From<serde_json::Error> for PreparedQueriesError {
    fn from(value: serde_json::Error) -> Self {
        Self::Json(value)
    }
}

impl From<PreparedQueryRegistryError> for PreparedQueriesError {
    fn from(value: PreparedQueryRegistryError) -> Self {
        Self::Registry(value)
    }
}

/// A validated set of persisted operations loaded from a manifest.
///
/// Cloning is cheap; the underlying [`PreparedQueryRegistry`] shares one allocation.
#[derive(Clone, Debug)]
pub struct PreparedQueries {
    registry: PreparedQueryRegistry,
}

impl Default for PreparedQueries {
    fn default() -> Self {
        Self::empty()
    }
}

impl PreparedQueries {
    /// An empty set.
    #[must_use]
    pub fn empty() -> Self {
        Self {
            registry: PreparedQueryRegistry::empty(),
        }
    }

    /// Wrap an existing registry.
    #[must_use]
    pub fn from_registry(registry: PreparedQueryRegistry) -> Self {
        Self { registry }
    }

    /// Load a manifest from a JSON string.
    ///
    /// Duplicate object keys are rejected rather than silently keeping the last value, so two
    /// entries with the same identifier cannot hide a mistake in a generated manifest.
    ///
    /// # Errors
    ///
    /// Returns an error for malformed JSON, a duplicate object key, an unrecognised manifest
    /// shape, a duplicate id, or a query that is invalid against the schema.
    pub fn from_json_str(schema: &Schema, json: &str) -> Result<Self, PreparedQueriesError> {
        reject_duplicate_keys_str(json)?;
        let value: JsonValue = serde_json::from_str(json)?;
        Self::from_json_value(schema, &value)
    }

    /// Load a manifest from JSON bytes.
    ///
    /// Duplicate object keys are rejected, exactly as in [`PreparedQueries::from_json_str`].
    ///
    /// # Errors
    ///
    /// Returns an error for malformed JSON, a duplicate object key, or an invalid manifest.
    pub fn from_json_slice(schema: &Schema, json: &[u8]) -> Result<Self, PreparedQueriesError> {
        reject_duplicate_keys_slice(json)?;
        let value: JsonValue = serde_json::from_slice(json)?;
        Self::from_json_value(schema, &value)
    }

    /// Load a manifest from an already parsed JSON value.
    ///
    /// A parsed JSON object cannot retain duplicate keys, so this path cannot detect them; prefer
    /// [`PreparedQueries::from_json_str`] or [`PreparedQueries::from_json_slice`] for untrusted or
    /// generated manifest text.
    ///
    /// # Errors
    ///
    /// Returns an error for an unrecognised manifest shape or an invalid query.
    pub fn from_json_value(
        schema: &Schema,
        value: &JsonValue,
    ) -> Result<Self, PreparedQueriesError> {
        let operations = operations_from_json(value)?;
        Self::from_operations(schema, operations)
    }

    /// Load a manifest from JSON. This is an alias for [`PreparedQueries::from_json_str`].
    ///
    /// # Errors
    ///
    /// Returns an error for malformed JSON or an invalid manifest.
    pub fn from_manifest(schema: &Schema, json: &str) -> Result<Self, PreparedQueriesError> {
        Self::from_json_str(schema, json)
    }

    /// Build a set from `(id, source)` entries.
    ///
    /// # Errors
    ///
    /// Returns an error for a duplicate id or an invalid query.
    pub fn from_map<K, V, I>(schema: &Schema, entries: I) -> Result<Self, PreparedQueriesError>
    where
        K: AsRef<str>,
        V: AsRef<str>,
        I: IntoIterator<Item = (K, V)>,
    {
        let operations = entries
            .into_iter()
            .map(|(id, source)| PreparedOperation::new(id.as_ref(), source.as_ref()));
        Self::from_operations(schema, operations)
    }

    /// Build a set from explicit operation entries.
    ///
    /// # Errors
    ///
    /// Returns an error for a duplicate id, an invalid query, or a `kind` that disagrees with the
    /// operation in the source.
    pub fn from_operations<I>(schema: &Schema, operations: I) -> Result<Self, PreparedQueriesError>
    where
        I: IntoIterator<Item = PreparedOperation>,
    {
        let operations: Vec<PreparedOperation> = operations.into_iter().collect();
        let registry = PreparedQueryRegistry::new(
            schema,
            operations.iter().map(|operation| {
                (
                    operation.id.as_str(),
                    operation.source.as_str(),
                    operation.operation_name.as_deref(),
                )
            }),
        )?;

        for operation in &operations {
            if let Some(expected) = operation.kind {
                let Some(prepared) = registry.get(&operation.id) else {
                    continue;
                };
                let actual = prepared.kind();
                if actual != expected {
                    return Err(PreparedQueriesError::KindMismatch {
                        id: operation.id.clone(),
                        expected,
                        actual,
                    });
                }
            }
        }

        Ok(Self { registry })
    }

    /// The underlying registry.
    #[must_use]
    pub fn registry(&self) -> &PreparedQueryRegistry {
        &self.registry
    }

    /// Consume this set into its registry.
    #[must_use]
    pub fn into_registry(self) -> PreparedQueryRegistry {
        self.registry
    }

    /// Look up a prepared query by identifier.
    #[must_use]
    pub fn get(&self, id: &str) -> Option<&PreparedQuery> {
        self.registry.get(id)
    }

    /// The number of loaded operations.
    #[must_use]
    pub fn len(&self) -> usize {
        self.registry.len()
    }

    /// Whether no operations were loaded.
    #[must_use]
    pub fn is_empty(&self) -> bool {
        self.registry.is_empty()
    }

    /// Identifiers in manifest order.
    pub fn ids(&self) -> impl ExactSizeIterator<Item = &str> {
        self.registry.ids()
    }
}

impl From<PreparedQueries> for PreparedQueryRegistry {
    fn from(value: PreparedQueries) -> Self {
        value.registry
    }
}

fn operations_from_json(value: &JsonValue) -> Result<Vec<PreparedOperation>, PreparedQueriesError> {
    match value {
        JsonValue::Object(map) => {
            if let Some(operations) = map.get("operations").or_else(|| map.get("documents")) {
                return operations_from_json(operations);
            }
            operations_from_map(map)
        }
        JsonValue::Array(items) => {
            if items.is_empty() {
                return Err(PreparedQueriesError::Invalid(
                    "the manifest contains no operations".to_owned(),
                ));
            }
            items
                .iter()
                .enumerate()
                .map(|(index, item)| {
                    operation_from_object(item, None).map_err(|error| match error {
                        PreparedQueriesError::Invalid(message) => PreparedQueriesError::Invalid(
                            format!("operation at index {index}: {message}"),
                        ),
                        other => other,
                    })
                })
                .collect()
        }
        _ => Err(PreparedQueriesError::Invalid(
            "expected an object map or an array of operations".to_owned(),
        )),
    }
}

/// Read a `{id: source}` map, or a map of id to operation objects.
fn operations_from_map(
    map: &JsonMap<String, JsonValue>,
) -> Result<Vec<PreparedOperation>, PreparedQueriesError> {
    if map.is_empty() {
        return Err(PreparedQueriesError::Invalid(
            "the manifest contains no operations".to_owned(),
        ));
    }
    map.iter()
        .map(|(id, value)| match value {
            JsonValue::String(source) => Ok(PreparedOperation::new(id.as_str(), source.as_str())),
            JsonValue::Object(_) => operation_from_object(value, Some(id.as_str())),
            _ => Err(PreparedQueriesError::Invalid(format!(
                "operation \"{id}\" must be a GraphQL string or an object"
            ))),
        })
        .collect()
}

/// Read one operation object from a Hive/Envelop/codegen-style array.
fn operation_from_object(
    value: &JsonValue,
    fallback_id: Option<&str>,
) -> Result<PreparedOperation, PreparedQueriesError> {
    let JsonValue::Object(map) = value else {
        return Err(PreparedQueriesError::Invalid(
            "each operation must be an object".to_owned(),
        ));
    };

    let id = first_string(map, &["id", "hash", "sha256Hash", "queryId", "documentId"])
        .or(fallback_id)
        .ok_or_else(|| {
            PreparedQueriesError::Invalid("operation is missing an id or hash".to_owned())
        })?;
    let source = first_string(map, &["body", "query", "document", "source"]).ok_or_else(|| {
        PreparedQueriesError::Invalid(format!(
            "operation \"{id}\" is missing its GraphQL source (body/query)"
        ))
    })?;
    let operation_name = first_string(map, &["name", "operationName"]).map(str::to_owned);
    let kind = first_string(map, &["type"])
        .map(|kind| match kind.to_ascii_lowercase().as_str() {
            "query" => Ok(OperationKind::Query),
            "mutation" => Ok(OperationKind::Mutation),
            "subscription" => Ok(OperationKind::Subscription),
            other => Err(PreparedQueriesError::Invalid(format!(
                "operation \"{id}\" has unsupported type \"{other}\""
            ))),
        })
        .transpose()?;

    Ok(PreparedOperation {
        id: id.to_owned(),
        source: source.to_owned(),
        operation_name,
        kind,
    })
}

fn first_string<'a>(map: &'a JsonMap<String, JsonValue>, keys: &[&str]) -> Option<&'a str> {
    keys.iter().find_map(|key| {
        map.get(*key)
            .and_then(JsonValue::as_str)
            .filter(|value| !value.is_empty())
    })
}

/// A JSON value walker that rejects duplicate object keys.
///
/// `serde_json` parses an object into a map, so a duplicated key silently overwrites the earlier
/// value before any manifest code can see it. This visitor runs first and reports the duplicate
/// with its key, which is the only place the raw text still distinguishes the two entries.
struct DuplicateKeyCheck;

impl<'de> Deserialize<'de> for DuplicateKeyCheck {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: Deserializer<'de>,
    {
        deserializer.deserialize_any(DuplicateKeyVisitor)
    }
}

struct DuplicateKeyVisitor;

impl<'de> Visitor<'de> for DuplicateKeyVisitor {
    type Value = DuplicateKeyCheck;

    fn expecting(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        formatter.write_str("any JSON value")
    }

    fn visit_map<A>(self, mut map: A) -> Result<Self::Value, A::Error>
    where
        A: MapAccess<'de>,
    {
        let mut seen = HashSet::new();
        while let Some(key) = map.next_key::<String>()? {
            if !seen.insert(key.clone()) {
                return Err(de::Error::custom(format!("duplicate object key \"{key}\"")));
            }
            map.next_value::<DuplicateKeyCheck>()?;
        }
        Ok(DuplicateKeyCheck)
    }

    fn visit_seq<A>(self, mut seq: A) -> Result<Self::Value, A::Error>
    where
        A: SeqAccess<'de>,
    {
        while seq.next_element::<DuplicateKeyCheck>()?.is_some() {}
        Ok(DuplicateKeyCheck)
    }

    fn visit_bool<E>(self, _value: bool) -> Result<Self::Value, E> {
        Ok(DuplicateKeyCheck)
    }

    fn visit_i64<E>(self, _value: i64) -> Result<Self::Value, E> {
        Ok(DuplicateKeyCheck)
    }

    fn visit_u64<E>(self, _value: u64) -> Result<Self::Value, E> {
        Ok(DuplicateKeyCheck)
    }

    fn visit_f64<E>(self, _value: f64) -> Result<Self::Value, E> {
        Ok(DuplicateKeyCheck)
    }

    fn visit_str<E>(self, _value: &str) -> Result<Self::Value, E> {
        Ok(DuplicateKeyCheck)
    }

    fn visit_string<E>(self, _value: String) -> Result<Self::Value, E> {
        Ok(DuplicateKeyCheck)
    }

    fn visit_unit<E>(self) -> Result<Self::Value, E> {
        Ok(DuplicateKeyCheck)
    }

    fn visit_none<E>(self) -> Result<Self::Value, E> {
        Ok(DuplicateKeyCheck)
    }

    fn visit_some<D>(self, deserializer: D) -> Result<Self::Value, D::Error>
    where
        D: Deserializer<'de>,
    {
        DuplicateKeyCheck::deserialize(deserializer)
    }
}

fn reject_duplicate_keys_str(json: &str) -> Result<(), serde_json::Error> {
    let mut deserializer = serde_json::Deserializer::from_str(json);
    DuplicateKeyCheck::deserialize(&mut deserializer)?;
    deserializer.end()
}

fn reject_duplicate_keys_slice(json: &[u8]) -> Result<(), serde_json::Error> {
    let mut deserializer = serde_json::Deserializer::from_slice(json);
    DuplicateKeyCheck::deserialize(&mut deserializer)?;
    deserializer.end()
}

/// Build the error response for an unknown persisted identifier.
///
/// Apollo clients look for the message `PersistedQueryNotFound`; the machine-readable code lives
/// in `extensions.code`.
#[must_use]
pub fn persisted_query_not_found(id: &str) -> gql::Response {
    gql::Response::error(persisted_query_not_found_error(id))
}

/// Build the GraphQL error for an unknown persisted identifier.
#[must_use]
pub fn persisted_query_not_found_error(id: &str) -> gql::GraphQLError {
    gql::GraphQLError::new("PersistedQueryNotFound")
        .extend("code", "PERSISTED_QUERY_NOT_FOUND")
        .extend("persistedQueryId", Arc::<str>::from(id))
}