Introduce filtering, ordering and pagination to graphql api

CHANGELOG.md

@@ -13,6 +13,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Introduce libp2p networking service and configuration [#282](https://github.com/p2panda/aquadoggo/pull/282)
 - Create and validate abstract queries [#302](https://github.com/p2panda/aquadoggo/pull/302)
+- Support paginated, ordered and filtered collection queries [#308](https://github.com/p2panda/aquadoggo/pull/308)
 
 ### Changed
 

aquadoggo/src/graphql/constants.rs

@@ -37,8 +37,38 @@ pub const PUBLIC_KEY_ARG: &str = "publicKey";
 /// Argument string used for passing a document view id into a query.
 pub const DOCUMENT_VIEW_ID_ARG: &str = "viewId";
 
+/// Argument string used for passing a filter into a query.
+pub const FILTER_ARG: &str = "filter";
+
+/// Argument string used for passing a filter into a query.
+pub const META_FILTER_ARG: &str = "meta";
+
+/// Argument string used for passing a pagination cursor into a query.
+pub const PAGINATION_AFTER_ARG: &str = "after";
+
+/// Argument string used for passing number of paginated items requested to query.
+pub const PAGINATION_FIRST_ARG: &str = "first";
+
+/// Argument string used for passing field to order by to query.
+pub const ORDER_BY_ARG: &str = "orderBy";
+
+/// Argument string used for passing ordering direction to query.
+pub const ORDER_DIRECTION_ARG: &str = "orderDirection";
+
+/// Name of field on a document where it's fields can be accessed.
+pub const DOCUMENT_FIELD: &str = "document";
+
 /// Name of field on a document where it's fields can be accessed.
 pub const FIELDS_FIELD: &str = "fields";
 
 /// Name of field on a document where it's meta data can be accessed.
 pub const META_FIELD: &str = "meta";
+
+/// Name of field on a document where pagination cursor can be accessed.
+pub const CURSOR_FIELD: &str = "cursor";
+
+/// Name of field on a paginated response which contains the total count.
+pub const TOTAL_COUNT_FIELD: &str = "totalCount";
+
+/// Name of field on a paginated response which shows if a next page exists.
+pub const HAS_NEXT_PAGE_FIELD: &str = "hasNextPage";

aquadoggo/src/graphql/queries/all_documents.rs

@@ -1,26 +1,30 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 
-use async_graphql::dynamic::{Field, FieldFuture, Object, TypeRef};
-use dynamic_graphql::FieldValue;
+use async_graphql::dynamic::{Field, FieldFuture, FieldValue, Object, TypeRef};
 use log::debug;
-use p2panda_rs::document::traits::AsDocument;
 use p2panda_rs::schema::Schema;
 use p2panda_rs::storage_provider::traits::DocumentStore;
 
+use crate::db::query::{Filter, Order, Pagination};
 use crate::db::SqlStore;
 use crate::graphql::constants;
-use crate::graphql::scalars::{DocumentIdScalar, DocumentViewIdScalar};
+use crate::graphql::scalars::CursorScalar;
+use crate::graphql::types::{DocumentValue, PaginationData};
+use crate::graphql::utils::{
+    paginated_response_name, parse_collection_arguments, with_collection_arguments,
+};
+use crate::schema::SchemaProvider;
 
-/// Adds GraphQL query for getting all documents of a certain p2panda schema to the root query
-/// object.
+/// Adds a GraphQL query for retrieving a paginated, ordered and filtered collection of
+/// documents by schema to the passed root query object.
 ///
-/// The query follows the format `all_<SCHEMA_ID>`.
+/// The query follows the format `all_<SCHEMA_ID>(<...ARGS>)`.
 pub fn build_all_documents_query(query: Object, schema: &Schema) -> Object {
     let schema_id = schema.id().clone();
-    query.field(
+    query.field(with_collection_arguments(
         Field::new(
             format!("{}{}", constants::QUERY_ALL_PREFIX, schema_id),
-            TypeRef::named_list(schema_id.to_string()),
+            TypeRef::named_list(paginated_response_name(&schema_id)),
             move |ctx| {
                 // Take ownership of the schema id in the resolver.
                 let schema_id = schema_id.clone();
@@ -32,18 +36,43 @@ pub fn build_all_documents_query(query: Object, schema: &Schema) -> Object {
                 );
 
                 FieldFuture::new(async move {
-                    // Fetch all queried documents and compose the field value, a list of document
-                    // id / view id tuples, which will bubble up the query tree.
-
+                    let schema_provider = ctx.data_unchecked::<SchemaProvider>();
                     let store = ctx.data_unchecked::<SqlStore>();
+
+                    // Default pagination, filtering and ordering values.
+                    let mut pagination = Pagination::<CursorScalar>::default();
+                    let mut order = Order::default();
+                    let mut filter = Filter::new();
+
+                    // Get the schema for the document type being queried.
+                    let schema = schema_provider
+                        .get(&schema_id)
+                        .await
+                        .expect("Schema should exist in schema provider");
+
+                    // Parse arguments.
+                    parse_collection_arguments(
+                        &ctx,
+                        &schema,
+                        &mut pagination,
+                        &mut order,
+                        &mut filter,
+                    )?;
+
+                    // Fetch all queried documents and compose the field value list
+                    // which will bubble up the query tree.
+                    //
+                    // TODO: This needs be be replaced with a query to the db which retrieves a
+                    // paginated, ordered, filtered collection.
                     let documents: Vec<FieldValue> = store
                         .get_documents_by_schema(&schema_id)
                         .await?
                         .iter()
                         .map(|document| {
-                            FieldValue::owned_any((
-                                Some(DocumentIdScalar::from(document.id())),
-                                None::<DocumentViewIdScalar>,
+                            FieldValue::owned_any(DocumentValue::Paginated(
+                                "CURSOR".to_string(),
+                                PaginationData::default(),
+                                document.to_owned(),
                             ))
                         })
                         .collect();
@@ -52,24 +81,174 @@ pub fn build_all_documents_query(query: Object, schema: &Schema) -> Object {
                     Ok(Some(FieldValue::list(documents)))
                 })
             },
-        )
-        .description(format!("Get all {} documents.", schema.name())),
-    )
+        ),
+        schema.id(),
+    )).description(format!("Query a paginated collection of `{}` documents. The requested collection is filtered and ordered following parameters passed into the query via the available arguments.", schema.id().name()))
 }
 
 #[cfg(test)]
 mod test {
-    use async_graphql::{value, Response};
+    use async_graphql::{value, Response, Value};
     use p2panda_rs::identity::KeyPair;
     use p2panda_rs::schema::FieldType;
-    use p2panda_rs::test_utils::fixtures::random_key_pair;
+    use p2panda_rs::test_utils::fixtures::key_pair;
     use rstest::rstest;
     use serde_json::json;
 
     use crate::test_utils::{add_document, add_schema, graphql_test_client, test_runner, TestNode};
 
     #[rstest]
-    fn collection_query(#[from(random_key_pair)] key_pair: KeyPair) {
+    // TODO: We don't actually perform any queries yet, these tests will need to be updated
+    // when we do.
+    #[case(
+        "".to_string(), 
+        value!({
+            "collection": value!([{ "hasNextPage": false, "totalCount": 0, "document": { "cursor": "CURSOR", "fields": { "bool": true, } } }]),
+        }),
+        vec![]
+    )]
+    #[case(
+        r#"(
+            first: 10, 
+            after: "1_00205406410aefce40c5cbbb04488f50714b7d5657b9f17eed7358da35379bc20331", 
+            orderBy: OWNER, 
+            orderDirection: ASC, 
+            filter: { 
+                bool : { 
+                    eq: true 
+                } 
+            }, 
+            meta: { 
+                owner: { 
+                    in: ["7cf4f58a2d89e93313f2de99604a814ecea9800cf217b140e9c3a7ba59a5d982"] 
+                },
+                documentId: { 
+                    eq: "00205406410aefce40c5cbbb04488f50714b7d5657b9f17eed7358da35379bc20331" 
+                },
+                viewId: { 
+                    notIn: ["00205406410aefce40c5cbbb04488f50714b7d5657b9f17eed7358da35379bc20331"] 
+                }
+            }
+        )"#.to_string(), 
+        value!({
+            "collection": value!([{ "hasNextPage": false, "totalCount": 0, "document": { "cursor": "CURSOR", "fields": { "bool": true, } } }]),
+        }),
+        vec![]
+    )]
+    #[case(
+        r#"(first: 0)"#.to_string(), 
+        Value::Null,
+        vec!["out of range integral type conversion attempted".to_string()]
+    )]
+    #[case(
+        r#"(first: "hello")"#.to_string(), 
+        Value::Null,
+        vec!["Invalid value for argument \"first\", expected type \"Int\"".to_string()]
+    )]
+    #[case(
+        r#"(after: HELLO)"#.to_string(), 
+        Value::Null,
+        vec!["internal: not a string".to_string()]
+    )]
+    #[case(
+        r#"(after: "00205406410aefce40c5cbbb04488f50714b7d5657b9f17eed7358da35379bc20331")"#.to_string(), 
+        Value::Null,
+        vec!["Invalid amount of cursor parts".to_string()]
+    )]
+    #[case(
+        r#"(after: 27)"#.to_string(), 
+        Value::Null,
+        vec!["internal: not a string".to_string()]
+    )]
+    #[case(
+        r#"(orderBy: HELLO)"#.to_string(), 
+        Value::Null,
+        vec!["Invalid value for argument \"orderBy\", enumeration type \"schema_name_00205406410aefce40c5cbbb04488f50714b7d5657b9f17eed7358da35379bc20331OrderBy\" does not contain the value \"HELLO\"".to_string()]
+    )]
+    #[case(
+        r#"(orderBy: "hello")"#.to_string(), 
+        Value::Null,
+        vec!["Invalid value for argument \"orderBy\", enumeration type \"schema_name_00205406410aefce40c5cbbb04488f50714b7d5657b9f17eed7358da35379bc20331OrderBy\" does not contain the value \"hello\"".to_string()]
+    )]
+    #[case(
+        r#"(orderDirection: HELLO)"#.to_string(), 
+        Value::Null,
+        vec!["Invalid value for argument \"orderDirection\", enumeration type \"OrderDirection\" does not contain the value \"HELLO\"".to_string()]
+    )]
+    #[case(
+        r#"(orderDirection: "hello")"#.to_string(), 
+        Value::Null,
+        vec!["Invalid value for argument \"orderDirection\", enumeration type \"OrderDirection\" does not contain the value \"hello\"".to_string()]
+    )]
+    #[case(
+        r#"(filter: "hello")"#.to_string(), 
+        Value::Null,
+        vec!["internal: is not an object".to_string()]
+    )]
+    #[case(
+        r#"(filter: { bool: { in: ["hello"] }})"#.to_string(), 
+        Value::Null,
+        vec!["Invalid value for argument \"filter.bool\", unknown field \"in\" of type \"BooleanFilter\"".to_string()]
+    )]
+    #[case(
+        r#"(filter: { hello: { eq: true }})"#.to_string(), 
+        Value::Null,
+        vec!["Invalid value for argument \"filter\", unknown field \"hello\" of type \"schema_name_00205406410aefce40c5cbbb04488f50714b7d5657b9f17eed7358da35379bc20331Filter\"".to_string()]
+    )]
+    #[case(
+        r#"(filter: { bool: { contains: "hello" }})"#.to_string(), 
+        Value::Null,
+        vec!["Invalid value for argument \"filter.bool\", unknown field \"contains\" of type \"BooleanFilter\"".to_string()]
+    )]
+    #[case(
+        r#"(meta: "hello")"#.to_string(), 
+        Value::Null,
+        vec!["internal: is not an object".to_string()]
+    )]
+    #[case(
+        r#"(meta: { bool: { in: ["hello"] }})"#.to_string(), 
+        Value::Null,
+        vec!["Invalid value for argument \"meta\", unknown field \"bool\" of type \"MetaFilterInput\"".to_string()]
+    )]
+    #[case(
+        r#"(meta: { owner: { contains: "hello" }})"#.to_string(), 
+        Value::Null,
+        vec!["Invalid value for argument \"meta.owner\", unknown field \"contains\" of type \"OwnerFilter\"".to_string()]
+    )]
+    #[case(
+        r#"(meta: { documentId: { contains: "hello" }})"#.to_string(), 
+        Value::Null,
+        vec!["Invalid value for argument \"meta.documentId\", unknown field \"contains\" of type \"DocumentIdFilter\"".to_string()]
+    )]
+    #[case(
+        r#"(meta: { viewId: { contains: "hello" }})"#.to_string(), 
+        Value::Null,
+        vec!["Invalid value for argument \"meta.viewId\", unknown field \"contains\" of type \"DocumentViewIdFilter\"".to_string()]
+    )]
+    #[case(
+        r#"(meta: { documentId: { eq: 27 }})"#.to_string(), 
+        Value::Null,
+        vec!["internal: not a string".to_string()]
+    )]
+    #[case(
+        r#"(meta: { viewId: { in: "hello" }})"#.to_string(), 
+        Value::Null,
+        vec!["internal: not a list".to_string()]
+    )]
+    // TODO: When we have a way to add custom validation to scalar types then this case should
+    // fail as we pass in an invalid public key string. Same for documentId and viewId meta fields.
+    // #[case(
+    //     r#"(meta: { owner: { eq: "hello" }})"#.to_string(),
+    //     Value::Null,
+    //     vec!["Invalid value for argument \"meta.owner\", unknown field \"contains\" of type \"OwnerFilter\"".to_string()]
+    // )]
+
+    fn collection_query(
+        key_pair: KeyPair,
+        #[case] query_args: String,
+        #[case] expected_data: Value,
+        #[case] expected_errors: Vec<String>,
+    ) {
         // Test collection query parameter variations.
         test_runner(move |mut node: TestNode| async move {
             // Add schema to node.
@@ -94,11 +273,17 @@ mod test {
             let client = graphql_test_client(&node).await;
             let query = format!(
                 r#"{{
-                collection: all_{type_name} {{
-                    fields {{ bool }}
+                collection: all_{type_name}{query_args} {{
+                    hasNextPage
+                    totalCount
+                    document {{ 
+                        cursor
+                        fields {{ bool }}
+                    }}
                 }},
             }}"#,
                 type_name = schema.id(),
+                query_args = query_args
             );
 
             let response = client
@@ -111,10 +296,15 @@ mod test {
 
             let response: Response = response.json().await;
 
-            let expected_data = value!({
-                "collection": value!([{ "fields": { "bool": true, } }]),
-            });
             assert_eq!(response.data, expected_data, "{:#?}", response.errors);
+
+            // Assert error messages.
+            let err_msgs: Vec<String> = response
+                .errors
+                .iter()
+                .map(|err| err.message.to_string())
+                .collect();
+            assert_eq!(err_msgs, expected_errors);
         });
     }
 }