feat(server): add filter conformance class (#519)

gadomski · web-flow · commit 6568f7429038 · 2024-11-12T16:50:17.000Z
diff --git a/crates/api/src/conformance.rs b/crates/api/src/conformance.rs
@@ -19,6 +19,15 @@ pub const GEOJSON_URI: &str = "http://www.opengis.net/spec/ogcapi-features-1/1.0
 /// The item search conformance uri.
 pub const ITEM_SEARCH_URI: &str = "https://api.stacspec.org/v1.0.0/item-search";
 
+/// The filter conformance uris.
+pub const FILTER_URIS: [&str; 5] = [
+    "http://www.opengis.net/spec/ogcapi-features-3/1.0/conf/filter",
+    "http://www.opengis.net/spec/cql2/1.0/conf/basic-cql2",
+    "https://api.stacspec.org/v1.0.0-rc.3/item-search#filter",
+    "http://www.opengis.net/spec/cql2/1.0/conf/cql2-text",
+    "http://www.opengis.net/spec/cql2/1.0/conf/cql2-json",
+];
+
 /// To support "generic" clients that want to access multiple OGC API Features
 /// implementations - and not "just" a specific API / server, the server has to
 /// declare the conformance classes it implements and conforms to.
@@ -76,6 +85,21 @@ impl Conformance {
         self.conforms_to.push(ITEM_SEARCH_URI.to_string());
         self
     }
+
+    /// Adds [filter](https://github.com/stac-api-extensions/filter) conformance
+    /// class.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use stac_api::Conformance;
+    /// let conformance = Conformance::new().item_search();
+    /// ```
+    pub fn filter(mut self) -> Conformance {
+        self.conforms_to
+            .extend(FILTER_URIS.iter().map(|s| s.to_string()));
+        self
+    }
 }
 
 impl Default for Conformance {
diff --git a/crates/api/src/items.rs b/crates/api/src/items.rs
@@ -87,8 +87,8 @@ pub struct GetItems {
     #[serde(skip_serializing_if = "Option::is_none", rename = "filter-crs")]
     pub filter_crs: Option<String>,
 
-    /// CQL2 filter expression.
-    #[serde(skip_serializing_if = "Option::is_none")]
+    /// This should always be cql2-text if present.
+    #[serde(skip_serializing_if = "Option::is_none", rename = "filter-lang")]
     pub filter_lang: Option<String>,
 
     /// CQL2 filter expression.
@@ -335,7 +335,11 @@ impl TryFrom<Items> for GetItems {
                     .join(",")
             }),
             filter_crs: items.filter_crs,
-            filter_lang: filter.as_ref().map(|_| "cql2-text".to_string()),
+            filter_lang: if filter.is_some() {
+                Some("cql2-text".to_string())
+            } else {
+                None
+            },
             filter,
             additional_fields: items
                 .additional_fields
@@ -413,7 +417,7 @@ fn maybe_parse_from_rfc3339(s: &str) -> Result<Option<DateTime<FixedOffset>>> {
 mod tests {
     use super::{GetItems, Items};
     use crate::{sort::Direction, Fields, Filter, Sortby};
-    use serde_json::{Map, Value};
+    use serde_json::{json, Map, Value};
     use std::collections::HashMap;
 
     #[test]
@@ -493,4 +497,14 @@ mod tests {
         assert_eq!(get_items.filter.unwrap(), "dummy text");
         assert_eq!(get_items.additional_fields["token"], "\"foobar\"");
     }
+
+    #[test]
+    fn filter() {
+        let value = json!({
+            "filter": "eo:cloud_cover >= 5 AND eo:cloud_cover < 10",
+            "filter-lang": "cql2-text",
+        });
+        let items: Items = serde_json::from_value(value).unwrap();
+        assert!(items.filter.is_some());
+    }
 }
diff --git a/crates/api/src/lib.rs b/crates/api/src/lib.rs
@@ -82,8 +82,8 @@ pub use client::{BlockingClient, Client};
 pub use {
     collections::Collections,
     conformance::{
-        Conformance, COLLECTIONS_URI, CORE_URI, FEATURES_URI, GEOJSON_URI, ITEM_SEARCH_URI,
-        OGC_API_FEATURES_URI,
+        Conformance, COLLECTIONS_URI, CORE_URI, FEATURES_URI, FILTER_URIS, GEOJSON_URI,
+        ITEM_SEARCH_URI, OGC_API_FEATURES_URI,
     },
     error::Error,
     fields::Fields,
diff --git a/crates/cli/Cargo.toml b/crates/cli/Cargo.toml
@@ -14,7 +14,7 @@ rust-version.workspace = true
 [features]
 default = ["pgstac"]
 duckdb = ["dep:stac-duckdb", "dep:duckdb"]
-pgstac = ["stac-server/pgstac"]
+pgstac = ["stac-server/pgstac", "dep:tokio-postgres"]
 python = ["dep:pyo3", "pgstac"]
 
 [dependencies]
@@ -47,6 +47,7 @@ tokio = { workspace = true, features = [
     "rt-multi-thread",
     "fs",
 ] }
+tokio-postgres = { workspace = true, optional = true }
 tokio-stream.workspace = true
 tracing.workspace = true
 tracing-subscriber.workspace = true
diff --git a/crates/cli/src/error.rs b/crates/cli/src/error.rs
@@ -54,6 +54,11 @@ pub enum Error {
     #[error(transparent)]
     TokioJoinError(#[from] tokio::task::JoinError),
 
+    /// [tokio_postgres::Error]
+    #[cfg(feature = "pgstac")]
+    #[error(transparent)]
+    TokioPostgres(#[from] tokio_postgres::Error),
+
     /// [std::num::TryFromIntError]
     #[error(transparent)]
     TryFromInt(#[from] std::num::TryFromIntError),
diff --git a/crates/cli/src/subcommand/search.rs b/crates/cli/src/subcommand/search.rs
@@ -52,10 +52,6 @@ pub struct Args {
     #[arg(long)]
     filter_crs: Option<String>,
 
-    /// `cql2-text` or `cql2-json`. If undefined, defaults to cql2-text for a GET request and cql2-json for a POST request.
-    #[arg(long)]
-    filter_lang: Option<String>,
-
     /// CQL2 filter expression.
     #[arg(short, long)]
     filter: Option<String>,
@@ -90,7 +86,6 @@ impl crate::Args {
             fields: args.fields.clone(),
             sortby: args.sortby.clone(),
             filter_crs: args.filter_crs.clone(),
-            filter_lang: args.filter_lang.clone(),
             filter: args.filter.clone(),
             ..Default::default()
         };
diff --git a/crates/cli/src/subcommand/serve.rs b/crates/cli/src/subcommand/serve.rs
@@ -35,6 +35,7 @@ impl crate::Args {
         #[cfg(feature = "pgstac")]
         {
             if let Some(pgstac) = args.pgstac.as_deref() {
+                let _ = tokio_postgres::connect(pgstac, tokio_postgres::NoTls).await?;
                 let backend = stac_server::PgstacBackend::new_from_stringlike(pgstac).await?;
                 self.load_and_serve(args, backend).await
             } else {
diff --git a/crates/server/CHANGELOG.md b/crates/server/CHANGELOG.md
@@ -6,6 +6,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 ## [Unreleased]
 
+### Added
+
+- Filter extension for **pgstac** backend ([#519](https://github.com/stac-utils/stac-rs/pull/519))
+
 ## [0.3.1] - 2024.09-19
 
 ### Changed
diff --git a/crates/server/README.md b/crates/server/README.md
@@ -71,7 +71,7 @@ This table lists the provided backends and their supported conformance classes a
 | [Collection search extension](https://github.com/stac-api-extensions/collection-search) | ✖️ | ✖️ |
 | [Collection transaction extension](https://github.com/stac-api-extensions/collection-transaction) | ✖️ | ✖️ |
 | [Fields extension](https://github.com/stac-api-extensions/fields) | ✖️ | ✖️ |
-| [Filter extension](https://github.com/stac-api-extensions/filter) | ✖️ | ✖️ |
+| [Filter extension](https://github.com/stac-api-extensions/filter) | ✖️ | ✅️ |
 | [Free-text search extension](https://github.com/stac-api-extensions/freetext-search) | ✖️ | ✖️ |
 | [Language (I18N) extension](https://github.com/stac-api-extensions/language) | ✖️ | ✖️ |
 | [Query extension](https://github.com/stac-api-extensions/query) | ✖️ | ✖️ |
diff --git a/crates/server/src/api.rs b/crates/server/src/api.rs
@@ -1,7 +1,7 @@
 use crate::{Backend, Error, Result, DEFAULT_DESCRIPTION, DEFAULT_ID};
 use http::Method;
 use serde::Serialize;
-use serde_json::{Map, Value};
+use serde_json::{json, Map, Value};
 use stac::{mime::APPLICATION_OPENAPI_3_0, Catalog, Collection, Fields, Item, Link, Links};
 use stac_api::{Collections, Conformance, ItemCollection, Items, Root, Search};
 use url::Url;
@@ -115,6 +115,15 @@ impl<B: Backend> Api<B> {
         catalog
             .links
             .push(Link::new(search_url, "search").geojson().method("POST"));
+        if self.backend.has_filter() {
+            catalog.links.push(
+                Link::new(
+                    self.url("/queryables")?,
+                    "http://www.opengis.net/def/rel/ogc/1.0/queryables",
+                )
+                .r#type("application/schema+json".to_string()),
+            );
+        }
         Ok(Root {
             catalog,
             conformance: self.conformance(),
@@ -136,9 +145,27 @@ impl<B: Backend> Api<B> {
         if self.backend.has_item_search() {
             conformance = conformance.item_search();
         }
+        if self.backend.has_filter() {
+            conformance = conformance.filter();
+        }
         conformance
     }
 
+    /// Returns queryables.
+    pub fn queryables(&self) -> Value {
+        // This is a pure punt from https://github.com/stac-api-extensions/filter?tab=readme-ov-file#queryables
+        json!({
+          "$schema" : "https://json-schema.org/draft/2019-09/schema",
+          "$id" : "https://stac-api.example.com/queryables",
+          "type" : "object",
+          "title" : "Queryables for Example STAC API",
+          "description" : "Queryable names for the example STAC API Item Search filter.",
+          "properties" : {
+          },
+          "additionalProperties": true
+        })
+    }
+
     /// Returns the collections from the backend.
     ///
     /// # Examples
diff --git a/crates/server/src/backend/memory.rs b/crates/server/src/backend/memory.rs
@@ -38,6 +38,10 @@ impl Backend for MemoryBackend {
         true
     }
 
+    fn has_filter(&self) -> bool {
+        false
+    }
+
     async fn collections(&self) -> Result<Vec<Collection>> {
         let collections = self.collections.read().unwrap();
         Ok(collections.values().cloned().collect())
diff --git a/crates/server/src/backend/mod.rs b/crates/server/src/backend/mod.rs
@@ -23,6 +23,17 @@ pub trait Backend: Clone + Sync + Send + 'static {
     /// ```
     fn has_item_search(&self) -> bool;
 
+    /// Returns true if this backend has [filter](https://github.com/stac-api-extensions/filter) capabilities.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use stac_server::{MemoryBackend, Backend};
+    ///
+    /// assert!(!MemoryBackend::new().has_filter());
+    /// ```
+    fn has_filter(&self) -> bool;
+
     /// Returns all collections.
     ///
     /// # Examples
diff --git a/crates/server/src/backend/pgstac.rs b/crates/server/src/backend/pgstac.rs
@@ -89,6 +89,10 @@ where
         true
     }
 
+    fn has_filter(&self) -> bool {
+        true
+    }
+
     async fn add_collection(&mut self, collection: Collection) -> Result<()> {
         let client = self.pool.get().await?;
         let client = Client::new(&*client);
diff --git a/crates/server/src/routes.rs b/crates/server/src/routes.rs
@@ -104,6 +104,7 @@ pub fn from_api<B: Backend>(api: Api<B>) -> Router {
         .route("/api", get(service_desc))
         .route("/api.html", get(service_doc))
         .route("/conformance", get(conformance))
+        .route("/queryables", get(queryables))
         .route("/collections", get(collections))
         .route("/collections/:collection_id", get(collection))
         .route("/collections/:collection_id/items", get(items))
@@ -147,6 +148,15 @@ pub async fn conformance<B: Backend>(State(api): State<Api<B>>) -> Response {
     Json(api.conformance()).into_response()
 }
 
+/// Returns the `/queryables` endpoint.
+pub async fn queryables<B: Backend>(State(api): State<Api<B>>) -> Response {
+    (
+        [(CONTENT_TYPE, "application/schema+json")],
+        Json(api.queryables()),
+    )
+        .into_response()
+}
+
 /// Returns the `/collections` endpoint from the [ogcapi-features conformance
 /// class](https://github.com/radiantearth/stac-api-spec/blob/release/v1.0.0/ogcapi-features/README.md#endpoints).
 pub async fn collections<B: Backend>(State(api): State<Api<B>>) -> Result<Json<Collections>> {
diff --git a/scripts/validate-stac-server b/scripts/validate-stac-server
@@ -10,11 +10,13 @@ set -e
 
 args="crates/server/data/sentinel-2/*"
 build_args="--no-default-features"
+conformance="--conformance core --conformance features --conformance item-search"
 
 if [ $# -eq 1 ]; then
     if [ "$1" = "--pgstac" ]; then
         args="$args --pgstac postgres://username:password@localhost/postgis"
         build_args="$build_args -F pgstac"
+        conformance="$conformance --conformance filter"
     else
         echo "Unknown argument: $1"
         exit 1
@@ -29,9 +31,7 @@ set +e
 scripts/wait-for-it.sh localhost:7822 && \
     stac-api-validator \
         --root-url http://localhost:7822 \
-        --conformance core \
-        --conformance features \
-        --conformance item-search \
+        $conformance \
         --collection sentinel-2-c1-l2a \
         --geometry '{"type":"Point","coordinates":[-105.07,40.08]}'
 status=$?

Original file line number	Diff line number	Diff line change
`@@ -35,6 +35,7 @@ impl crate::Args {`
`35`	`35`	`#[cfg(feature = "pgstac")]`
`36`	`36`	`{`
`37`	`37`	`if let Some(pgstac) = args.pgstac.as_deref() {`
	`38`	`+ let _ = tokio_postgres::connect(pgstac, tokio_postgres::NoTls).await?;`
`38`	`39`	`let backend = stac_server::PgstacBackend::new_from_stringlike(pgstac).await?;`
`39`	`40`	`self.load_and_serve(args, backend).await`
`40`	`41`	`} else {`