# Project Roadmap: `stac-client`
This document outlines the development roadmap for the `stac-client` library, guided by the Architecturally Significant Requirements (ASRs) and gap analysis against the STAC API specification.
The primary goal is to evolve the client into a production-ready, ergonomic, and fully-featured library for interacting with STAC APIs in Rust.
## Near-Term Priorities (Next 1-2 Minor Releases)
These features are considered critical for production use cases and filling the most significant gaps in the current implementation.
### High Priority
- **Authentication (ASR 0101):** Implement a flexible authentication mechanism to support common patterns like API keys in headers (`x-api-key`) and bearer tokens. This is essential for accessing protected STAC APIs.
- **Retry and Backoff Policy (ASR 0102):** Introduce a configurable, opt-in retry policy for transient network errors (5xx status codes) and rate limiting (429 Too Many Requests). This will include exponential backoff with jitter to improve client resilience.
- **Filter Extension and CQL2 Support (ASR 0103):** Provide a structured, type-safe builder for creating complex filters, including support for the increasingly popular CQL2-JSON filter language. This will improve correctness and developer experience over raw string queries.
- **Enforce 100% Test Coverage:** Fulfill the project's stated goal of 100% test coverage to ensure maximum reliability.
## Mid-Term Priorities (Next Major Release)
These features focus on improving developer ergonomics, providing deeper integration with the STAC ecosystem, and handling more advanced use cases.
### Medium Priority
- **Streaming Pagination Iterator (ASR 0104):** Implement a true asynchronous stream/iterator for handling paginated search results. This will allow for efficient processing of very large query responses without high memory overhead.
- **Structured Queryables Support (ASR 0105):** Add support for fetching and parsing the `/queryables` endpoint to allow dynamic inspection of an API's filterable fields.
- **Client Timeout Configuration (ASR 0106):** Expose a simple API for setting global and per-request timeouts.
- **Conformance Class Handling (ASR 0107):** Automatically parse the `/conformance` endpoint to enable feature-gating within the client.
- **Fields Extension Support (ASR 0108):** Add a validated builder for using the `fields` and `exclude_fields` parameters.
- **Item/Asset Download Helper (ASR 0109):** Provide a convenient, streaming-first method for downloading assets.
- **Typed STAC Extensions:** Introduce typed data models for common STAC extensions (e.g., `eo`, `view`, `proj`) to allow for safer and more ergonomic access to extension-specific fields.
## Long-Term & Future Work (Exploratory)
These items are valuable but lower priority. They will be considered once the near-term and mid-term goals are substantially complete.
### Low Priority
- **Caching (ETag / If-None-Match):** Implement HTTP caching for resources like Catalogs and Collections to reduce redundant requests and improve performance.
- **Geometry Handling (`geo-types`):** Integrate more deeply with the `geo-types` ecosystem for advanced spatial operations and validation.
- **Feature-Complete CLI:** Expand the existing binary into a powerful command-line tool for searching, inspecting, and downloading STAC assets.
- **Transactions API:** Add support for the STAC Transactions API to allow for creating, updating, and deleting Items and Collections.
- **Optional Telemetry:** Consider adding opt-in, anonymized usage metrics to help guide future development priorities. This would require a governance decision.