adds product router and backend

Author: parksjr

src/stapi_fastapi/backends/__init__.py

@@ -0,0 +1,35 @@
+from typing import Protocol
+
+from fastapi import Request
+
+from stapi_fastapi.models.opportunity import Opportunity, OpportunityRequest
+from stapi_fastapi.models.order import Order
+from stapi_fastapi.models.product import Product
+
+
+class ProductBackend(Protocol):
+    def product(self, product_id: str, request: Request) -> Product | None:
+        """
+        Return the product identified by `product_id` or `None` if it isn't
+        supported.
+        """
+
+    async def search_opportunities(
+        self, product_id: str, search: OpportunityRequest, request: Request
+    ) -> list[Opportunity]:
+        """
+        Search for ordering opportunities for the  given search parameters.
+
+        Backends must validate search constraints and raise
+        `stapi_fastapi.backend.exceptions.ConstraintsException` if not valid.
+        """
+
+    async def create_order(
+        self, product_id: str, search: OpportunityRequest, request: Request
+    ) -> Order:
+        """
+        Create a new order.
+
+        Backends must validate order payload and raise
+        `stapi_fastapi.backend.exceptions.ConstraintsException` if not valid.
+        """

src/stapi_fastapi/backends/product_backend.py

@@ -0,0 +1,26 @@
+from typing import Protocol
+
+from fastapi import Request
+
+from stapi_fastapi.models.order import Order
+from stapi_fastapi.models.product import Product
+
+
+class RootBackend(Protocol):
+    def products(self, request: Request) -> list[Product]:
+        """
+        Return a list of supported products.
+        """
+
+    def orders(self, request: Request) -> list[Order]:
+        """
+        Return a list of existing orders.
+        """
+
+    async def get_order(self, order_id: str, request: Request) -> Order:
+        """
+        Get details for order with `order_id`.
+
+        Backends must raise `stapi_fastapi.backend.exceptions.NotFoundException`
+        if not found or access denied.
+        """

src/stapi_fastapi/backends/root_backend.py

@@ -1,10 +1,13 @@
 from typing import Any, Mapping
+
 from fastapi import HTTPException
 
+
 class StapiException(HTTPException):
     def __init__(self, status_code: int, detail: str) -> None:
         super().__init__(status_code, detail)
 
+
 class ConstraintsException(Exception):
     detail: Mapping[str, Any] | None
 

src/stapi_fastapi/exceptions.py

@@ -1,13 +1,11 @@
 from enum import Enum
-from typing import Literal, Optional
-from abc import ABC, abstractmethod
-from fastapi import Request
+from typing import Literal, Optional, Self
 
 from pydantic import AnyHttpUrl, BaseModel, Field
 
+from stapi_fastapi.backends.product_backend import ProductBackend
 from stapi_fastapi.models.shared import Link
-from stapi_fastapi.models.opportunity import Opportunity, OpportunityProperties, OpportunityRequest
-from stapi_fastapi.models.order import Order
+from stapi_fastapi.types.json_schema_model import JsonSchemaModel
 
 
 class ProviderRole(str, Enum):
@@ -24,7 +22,7 @@ class Provider(BaseModel):
     url: AnyHttpUrl
 
 
-class Product(BaseModel, ABC):
+class Product(BaseModel):
     type: Literal["Product"] = "Product"
     conformsTo: list[str] = Field(default_factory=list)
     id: str
@@ -34,28 +32,12 @@ class Product(BaseModel, ABC):
     license: str
     providers: list[Provider] = Field(default_factory=list)
     links: list[Link]
-    parameters: OpportunityProperties
-
-    @abstractmethod
-    def search_opportunities(self, search: OpportunityRequest, request: Request
-    ) -> list[Opportunity]:
-        """
-        Search for ordering opportunities for the  given search parameters.
-
-        Backends must validate search constraints and raise
-        `stapi_fastapi.backend.exceptions.ConstraintsException` if not valid.
-        """
-        ...
-
-    @abstractmethod
-    def create_order(self, search: OpportunityRequest, request: Request) -> Order:
-        """
-        Create a new order.
-
-        Backends must validate order payload and raise
-        `stapi_fastapi.backend.exceptions.ConstraintsException` if not valid.
-        """
-        ...
+    constraints: JsonSchemaModel
+
+    def __init__(self: Self, backend: ProductBackend, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.backend = backend
+
 
 class ProductsCollection(BaseModel):
     type: Literal["ProductCollection"] = "ProductCollection"

src/stapi_fastapi/models/product.py

@@ -0,0 +1,102 @@
+# Generic product router factory
+from typing import Self
+
+from fastapi import APIRouter, HTTPException, Request, status
+from fastapi.encoders import jsonable_encoder
+from fastapi.responses import JSONResponse
+
+from stapi_fastapi.constants import TYPE_GEOJSON
+from stapi_fastapi.exceptions import ConstraintsException
+from stapi_fastapi.models.opportunity import (
+    OpportunityCollection,
+    OpportunityRequest,
+)
+from stapi_fastapi.models.product import Product
+from stapi_fastapi.models.shared import Link
+from stapi_fastapi.types.json_schema_model import JsonSchemaModel
+
+"""
+/products[MainRouter]/opportunities
+/products[MainRouter]/parameters
+/products[MainRouter]/order
+"""
+
+
+class ProductRouter(APIRouter):
+    def __init__(
+        self: Self,
+        product: Product,
+        *args,
+        **kwargs,
+    ):
+        super().__init__(*args, **kwargs)
+        self.product = product
+
+        self.add_api_route(
+            path="/opportunities",
+            endpoint=self.search_opportunities,
+            methods=["POST"],
+            summary="Search Opportunities for the product",
+        )
+
+        self.add_api_route(
+            path="/constraints",
+            endpoint=self.get_product_constraints,
+            methods=["GET"],
+            summary="Get constraints for the product",
+        )
+
+        self.add_api_route(
+            path="/order",
+            endpoint=self.create_order,
+            methods=["POST"],
+            summary="Create an order for the product",
+        )
+
+    async def search_opportunities(
+        self, search: OpportunityRequest, request: Request
+    ) -> OpportunityCollection:
+        """
+        Explore the opportunities available for a particular set of constraints
+        """
+        try:
+            opportunities = await self.product.backend.search_opportunities(
+                search, request
+            )
+        except ConstraintsException as exc:
+            raise HTTPException(status.HTTP_422_UNPROCESSABLE_ENTITY, detail=exc.detail)
+        return JSONResponse(
+            jsonable_encoder(OpportunityCollection(features=opportunities)),
+            media_type=TYPE_GEOJSON,
+        )
+
+    async def get_product_constraints(self: Self, request: Request) -> JsonSchemaModel:
+        """
+        Return supported constraints of a specific product
+        """
+        return {
+            "product_id": self.product.product_id,
+            "constraints": self.product.constraints,
+        }
+
+    async def create_order(
+        self, payload: OpportunityRequest, request: Request
+    ) -> JSONResponse:
+        """
+        Create a new order.
+        """
+        try:
+            order = await self.product.backend.create_order(payload, request)
+        except ConstraintsException as exc:
+            raise HTTPException(status.HTTP_422_UNPROCESSABLE_ENTITY, detail=exc.detail)
+
+        location = str(
+            request.url_for(f"{self.NAME_PREFIX}:get-order", order_id=order.id)
+        )
+        order.links.append(Link(href=location, rel="self", type=TYPE_GEOJSON))
+        return JSONResponse(
+            jsonable_encoder(order, exclude_unset=True),
+            status.HTTP_201_CREATED,
+            {"Location": location},
+            TYPE_GEOJSON,
+        )