fix: make max sub-collection depth configurable

Author: jyecusch

nitric/api/const.py

@@ -0,0 +1,3 @@
+# The maximum number of parent collections a sub-collection can have.
+# This is implemented in the Membrane, but reinforced here for immediate exceptions without a server connection.
+MAX_SUB_COLLECTION_DEPTH = 1

nitric/api/documents.py

@@ -4,6 +4,7 @@
 from enum import Enum
 from typing import List, AsyncIterator, Union, Any, Tuple
 
+from nitric.api.const import MAX_SUB_COLLECTION_DEPTH
 from nitric.proto.nitric.document.v1 import (
     DocumentServiceStub,
     Collection as CollectionMessage,
@@ -15,6 +16,12 @@
 from nitric.utils import new_default_channel, _dict_from_struct, _struct_from_dict
 
 
+class CollectionDepthException(Exception):
+    """Exception when the max depth of document sub-collections is exceeded."""
+
+    pass
+
+
 @dataclass(frozen=True, order=True)
 class DocumentRef:
     """A reference to a document in a collection."""
@@ -31,9 +38,13 @@ def collection(self, name: str) -> CollectionRef:
         e.g. Documents().collection('a').doc('b').collection('c').doc('d') is valid,
         Documents().collection('a').doc('b').collection('c').doc('d').collection('e') is invalid (1 level too deep).
         """
-        if self.parent.is_sub_collection():
-            # Collection nesting is currently unsupported, but may be included in a future enhancement.
-            raise Exception("Currently, sub-collections may only be nested 1 deep")
+        current_depth = self.parent.sub_collection_depth()
+        if current_depth >= MAX_SUB_COLLECTION_DEPTH:
+            # Collection nesting is only supported to a maximum depth.
+            raise CollectionDepthException(
+                f"sub-collections supported to a depth of {MAX_SUB_COLLECTION_DEPTH}, "
+                f"attempted to create new collection with depth {current_depth + 1}"
+            )
         return CollectionRef(_documents=self._documents, name=name, parent=self)
 
     async def get(self) -> Document:
@@ -121,6 +132,12 @@ def query(
             expressions=[expressions] if isinstance(expressions, Expression) else expressions,
         )
 
+    def sub_collection_depth(self) -> int:
+        if not self.is_sub_collection():
+            return 0
+        else:
+            return self.parent.parent.sub_collection_depth() + 1
+
     def is_sub_collection(self):
         """Return True if this collection is a sub-collection of a document in another collection."""
         return self.parent is not None
@@ -302,7 +319,7 @@ def where(
         self,
         *expressions: Union[
             Expression, List[Expression], Union[str, Operator, int, bool, Tuple[str, Union[str, Operator], Any]]
-        ]
+        ],
     ) -> QueryBuilder:
         """
         Add a filter expression to the query.

tests/api/test_documents.py

@@ -186,7 +186,9 @@ async def test_nested_subcollections_fail(self):
         with pytest.raises(Exception) as e:
             Documents().collection("a").doc("b").collection("c").doc("d").collection("should-fail")
 
-        self.assertIn("sub-collections may only be nested 1 deep", str(e.value))
+        self.assertIn(
+            "sub-collections supported to a depth of 1, attempted to create new collection with depth 2", str(e.value)
+        )
 
     async def test_collection_query_fetch(self):
         mock_query = AsyncMock()