ProductRouter split from RootRouter (nee StapiRouter) (#80)

This changeset includes a number of fixes to better align behavior with the spec and fix bugs, and a whole bunch of clean up. The main feature is moving the `GET /opportunities` and `POST /orders` endpoints under the product path, such as `/products/{product_id}/opportunities`, as the spec has determined that opportunities and placing an order are product-specific (see stapi-spec/stapi-spec#198 and stapi-spec/stapi-spec#200). This changeset also adds the missing `/products/{product_id}/constraints` endpoint (formerly parameters).

Another key feature is the introduction of the  `bin/server.py` script that can be used with uvicorn to run a minimal implementation for local browsing. See the README for instructions.

* initial implementation of router composition for products

* make OpportunityProperties and Opportunity models generics

* overhaul the main router as APIRouter, product router not a factory, add product router classmethod to main router

* resolve merge conflicts

* sort out the conftest a bit more

* the /products/{product_id}/opportunities endpoint is accessible

* adds product router and backend

* wip: splits backend and router for root and product.

Co-authored-by: Jarrett Keifer <[email protected]>

* adds test for get_constraints

* remove unused modules

* various cleanup and refinements

* no longer a problem with the root router / route

* rename tests/backend{,s}.py

* get tests passing

* more cleanup

* fixes StapiExceptions

Co-authored-by: Tyler <[email protected]>
Co-authored-by: Jarrett Keifer <[email protected]>

* removes dupe HTTPException in models

* passes product router instead of product to backend

Co-authored-by: Tyler <[email protected]>
Co-authored-by: Jarrett Keifer <[email protected]>

* Adds OrderCollection type and returns for get_orders

Co-authored-by: Tyler <[email protected]>
Co-authored-by: Jarrett Keifer <[email protected]>

* type the opporunities to the product constraints model

* upgrade fastapi

* fix GeoJSONResponse model bug per openapi docs

* minimal test server to allow accessing openapi docs

* remove nulls from serialized links

* tests should fail not warn on spec incompatibility

* add nocover to protocol implementations

* standardize links on models

---------

Co-authored-by: Mike Parks <[email protected]>
Co-authored-by: Jarrett Keifer <[email protected]>
Co-authored-by: Tyler <[email protected]>

Author: 4 people

README.md

@@ -1,7 +1,7 @@
 # STAPI FastAPI - Sensor Tasking API with FastAPI
 
-WARNING: The whole [STAPI spec](https://github.com/stapi-spec/stapi-spec) is
-very much work in progress, so things are guaranteed to be not correct.
+WARNING: The whole [STAPI spec] is very much work in progress, so things are
+guaranteed to be not correct.
 
 ## Usage
 
@@ -11,7 +11,7 @@ STAPI FastAPI provides an `fastapi.APIRouter` which must be included in
 ## Development
 
 It's 2024 and we still need to pick our poison for a 2024 dependency management
-solution. This project picks [poetry][poetry] for now.
+solution. This project picks [poetry] for now.
 
 ### Dev Setup
 
@@ -35,15 +35,22 @@ command `pytest`.
 ### Dev Server
 
 This project cannot be run on its own because it does not have any backend
-implementations. If a development server is desired, run one of the
-implementations such as
-[stapi-fastapi-tle](https://github.com/stapi-spec/stapi-fastapi-tle). To test
-something like stapi-fastapi-tle with your development version of
-stapi-fastapi, install them both into the same virtual environment.
+implementations. However, a minimal test implementation is provided in
+[`./bin/server.py`](./bin/server.py). It can be run with `uvicorn` as a way to
+interact with the API and to view the OpenAPI documentation. Run it like so
+from the project root:
+
+```commandline
+uvicorn server:app --app-dir ./bin --reload
+```
+
+With the `uvicorn` defaults the app should be accessible at
+`http://localhost:8000`.
 
 ### Implementing a backend
 
 - The test suite assumes the backend can be instantiated without any parameters
   required by the constructor.
 
+[STAPI spec]: https://github.com/stapi-spec/stapi-spec
 [poetry]: https://python-poetry.org/

bin/server.py

@@ -0,0 +1,108 @@
+from uuid import uuid4
+
+from fastapi import FastAPI, Request
+from stapi_fastapi.backends.product_backend import ProductBackend
+from stapi_fastapi.exceptions import ConstraintsException, NotFoundException
+from stapi_fastapi.models.opportunity import (
+    Opportunity,
+    OpportunityPropertiesBase,
+    OpportunityRequest,
+)
+from stapi_fastapi.models.order import Order
+from stapi_fastapi.models.product import (
+    Product,
+    Provider,
+    ProviderRole,
+)
+from stapi_fastapi.routers.root_router import RootRouter
+
+
+class MockOrderDB(dict[int | str, Order]):
+    pass
+
+
+class MockRootBackend:
+    def __init__(self, orders: MockOrderDB) -> None:
+        self._orders: MockOrderDB = orders
+
+    async def get_orders(self, request: Request) -> list[Order]:
+        """
+        Show all orders.
+        """
+        return list(self._orders.values())
+
+    async def get_order(self, order_id: str, request: Request) -> Order:
+        """
+        Show details for order with `order_id`.
+        """
+        try:
+            return self._orders[order_id]
+        except KeyError:
+            raise NotFoundException()
+
+
+class MockProductBackend(ProductBackend):
+    def __init__(self, orders: MockOrderDB) -> None:
+        self._opportunities: list[Opportunity] = []
+        self._allowed_payloads: list[OpportunityRequest] = []
+        self._orders: MockOrderDB = orders
+
+    async def search_opportunities(
+        self, product: Product, search: OpportunityRequest, request: Request
+    ) -> list[Opportunity]:
+        return [o.model_copy(update=search.model_dump()) for o in self._opportunities]
+
+    async def create_order(
+        self, product: Product, payload: OpportunityRequest, request: Request
+    ) -> Order:
+        """
+        Create a new order.
+        """
+        allowed: bool = any(allowed == payload for allowed in self._allowed_payloads)
+        if allowed:
+            order = Order(
+                id=str(uuid4()),
+                geometry=payload.geometry,
+                properties={
+                    "filter": payload.filter,
+                    "datetime": payload.datetime,
+                    "product_id": product.id,
+                },
+                links=[],
+            )
+            self._orders[order.id] = order
+            return order
+        raise ConstraintsException("not allowed")
+
+
+class TestSpotlightProperties(OpportunityPropertiesBase):
+    off_nadir: int
+
+
+order_db = MockOrderDB()
+product_backend = MockProductBackend(order_db)
+root_backend = MockRootBackend(order_db)
+
+provider = Provider(
+    name="Test Provider",
+    description="A provider for Test data",
+    roles=[ProviderRole.producer],  # Example role
+    url="https://test-provider.example.com",  # Must be a valid URL
+)
+
+product = Product(
+    id="test-spotlight",
+    title="Test Spotlight Product",
+    description="Test product for test spotlight",
+    license="CC-BY-4.0",
+    keywords=["test", "satellite"],
+    providers=[provider],
+    links=[],
+    constraints=TestSpotlightProperties,
+    backend=product_backend,
+)
+
+root_router = RootRouter(root_backend)
+root_router.add_product(product)
+app: FastAPI = FastAPI()
+app.include_router(root_router, prefix="")

poetry.lock

@@ -0,0 +1,21 @@
+from .backends import ProductBackend, RootBackend
+from .models import (
+    Link,
+    OpportunityPropertiesBase,
+    Product,
+    Provider,
+    ProviderRole,
+)
+from .routers import ProductRouter, RootRouter
+
+__all__ = [
+    "Link",
+    "OpportunityPropertiesBase",
+    "Product",
+    "ProductBackend",
+    "ProductRouter",
+    "Provider",
+    "ProviderRole",
+    "RootBackend",
+    "RootRouter",
+]