ref(grouping): Make GroupingComponent generic and add subclasses (#80722)

This adds a full taxonomy of `BaseGroupingCompontent` subclasses, partially just as a form of documentation (we create this deeply nested `variants` structure when grouping, and it's helpful to understand what kind of data is in each part), and partially so that it's easier to write helpers dealing with different kinds of components and not have to constantly be checking for the presence of this or that attribute.

Key changes:

- Make `BaseGroupingComponent` generic, so that subclasses can specify the types allowed in `values`.
- Allow `id` to be a class attribute (no longer require it to be passed to `__init__`), so that it can be specified in each subclass.
- Add overloads of `get_single_grouping_component`.
- Use a `TypeVar` to make `ReturnedVariants` covaraint. This is a bit of a hack, but fixing it will require a larger change than felt reasonable here. (Basically, we'll have to make everywhere it's used treat it as read-only.) I left a TODO.

Author: lobsterkatie

src/sentry/grouping/component.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from collections.abc import Generator, Iterator, Sequence
-from typing import Any
+from typing import Any, Self
 
 from sentry.grouping.utils import hash_from_values
 
@@ -23,32 +23,32 @@
 }
 
 
-def _calculate_contributes(values: Sequence[str | int | BaseGroupingComponent]) -> bool:
+def _calculate_contributes[ValuesType](values: Sequence[ValuesType]) -> bool:
     for value in values or ():
         if not isinstance(value, BaseGroupingComponent) or value.contributes:
             return True
     return False
 
 
-class BaseGroupingComponent:
+class BaseGroupingComponent[ValuesType: str | int | BaseGroupingComponent[Any]]:
     """A grouping component is a recursive structure that is flattened
     into components to make a hash for grouping purposes.
     """
 
     id: str = "default"
     hint: str | None = None
     contributes: bool = False
-    values: Sequence[str | int | BaseGroupingComponent]
+    values: Sequence[ValuesType]
 
     def __init__(
         self,
-        id: str,
+        id: str | None = None,
         hint: str | None = None,
         contributes: bool | None = None,
-        values: Sequence[str | int | BaseGroupingComponent] | None = None,
+        values: Sequence[ValuesType] | None = None,
         variant_provider: bool = False,
     ):
-        self.id = id
+        self.id = id or self.id
         self.variant_provider = variant_provider
 
         self.update(
@@ -73,7 +73,7 @@ def description(self) -> str:
         paths = []
 
         def _walk_components(
-            component: BaseGroupingComponent, current_path: list[str | None]
+            component: BaseGroupingComponent[Any], current_path: list[str | None]
         ) -> None:
             # Keep track of the names of the nodes from the root of the component tree to here
             current_path.append(component.name)
@@ -101,13 +101,13 @@ def _walk_components(
 
     def get_subcomponent(
         self, id: str, only_contributing: bool = False
-    ) -> str | int | BaseGroupingComponent | None:
+    ) -> str | int | BaseGroupingComponent[Any] | None:
         """Looks up a subcomponent by the id and returns the first or `None`."""
         return next(self.iter_subcomponents(id=id, only_contributing=only_contributing), None)
 
     def iter_subcomponents(
         self, id: str, recursive: bool = False, only_contributing: bool = False
-    ) -> Iterator[str | int | BaseGroupingComponent | None]:
+    ) -> Iterator[str | int | BaseGroupingComponent[Any] | None]:
         """Finds all subcomponents matching an id, optionally recursively."""
         for value in self.values:
             if isinstance(value, BaseGroupingComponent):
@@ -125,7 +125,7 @@ def update(
         self,
         hint: str | None = None,
         contributes: bool | None = None,
-        values: Sequence[str | int | BaseGroupingComponent] | None = None,
+        values: Sequence[ValuesType] | None = None,
     ) -> None:
         """Updates an already existing component with new values."""
         if hint is not None:
@@ -137,14 +137,14 @@ def update(
         if contributes is not None:
             self.contributes = contributes
 
-    def shallow_copy(self) -> BaseGroupingComponent:
+    def shallow_copy(self) -> Self:
         """Creates a shallow copy."""
         rv = object.__new__(self.__class__)
         rv.__dict__.update(self.__dict__)
         rv.values = list(self.values)
         return rv
 
-    def iter_values(self) -> Generator[str | int | BaseGroupingComponent]:
+    def iter_values(self) -> Generator[str | int | BaseGroupingComponent[Any]]:
         """Recursively walks the component and flattens it into a list of
         values.
         """
@@ -183,3 +183,139 @@ def as_dict(self) -> dict[str, Any]:
 
     def __repr__(self) -> str:
         return f"{self.__class__.__name__}({self.id!r}, hint={self.hint!r}, contributes={self.contributes!r}, values={self.values!r})"
+
+
+# NOTE: In all of the classes below, the type(s) passed to `BaseGroupingComponent` represent
+# the type(s) which can appear in the `values` attribute
+
+
+# Error-related inner components
+
+
+class ContextLineGroupingComponent(BaseGroupingComponent[str]):
+    id: str = "context-line"
+
+
+class ErrorTypeGroupingComponent(BaseGroupingComponent[str]):
+    id: str = "type"
+
+
+class ErrorValueGroupingComponent(BaseGroupingComponent[str]):
+    id: str = "value"
+
+
+class FilenameGroupingComponent(BaseGroupingComponent[str]):
+    id: str = "filename"
+
+
+class FunctionGroupingComponent(BaseGroupingComponent[str]):
+    id: str = "function"
+
+
+class LineNumberGroupingComponent(BaseGroupingComponent[str]):
+    id: str = "lineno"
+
+
+class ModuleGroupingComponent(BaseGroupingComponent[str]):
+    id: str = "module"
+
+
+class NSErrorGroupingComponent(BaseGroupingComponent[str | int]):
+    id: str = "ns-error"
+
+
+class SymbolGroupingComponent(BaseGroupingComponent[str]):
+    id: str = "symbol"
+
+
+class FrameGroupingComponent(
+    BaseGroupingComponent[
+        ContextLineGroupingComponent
+        | FilenameGroupingComponent
+        | FunctionGroupingComponent
+        | LineNumberGroupingComponent  # only in legacy config
+        | ModuleGroupingComponent
+        | SymbolGroupingComponent  # only in legacy config
+    ]
+):
+    id: str = "frame"
+
+
+# Security-related inner components
+
+
+class HostnameGroupingComponent(BaseGroupingComponent[str]):
+    id: str = "hostname"
+
+
+class SaltGroupingComponent(BaseGroupingComponent[str]):
+    id: str = "salt"
+    hint: str = "a static salt"
+
+
+class ViolationGroupingComponent(BaseGroupingComponent[str]):
+    id: str = "violation"
+
+
+class URIGroupingComponent(BaseGroupingComponent[str]):
+    id: str = "uri"
+
+
+# Top-level components
+
+
+class MessageGroupingComponent(BaseGroupingComponent[str]):
+    id: str = "message"
+
+
+class StacktraceGroupingComponent(BaseGroupingComponent[FrameGroupingComponent]):
+    id: str = "stacktrace"
+
+
+class ExceptionGroupingComponent(
+    BaseGroupingComponent[
+        ErrorTypeGroupingComponent
+        | ErrorValueGroupingComponent
+        | NSErrorGroupingComponent
+        | StacktraceGroupingComponent
+    ]
+):
+    id: str = "exception"
+
+
+class ChainedExceptionGroupingComponent(BaseGroupingComponent[ExceptionGroupingComponent]):
+    id: str = "chained-exception"
+
+
+class ThreadsGroupingComponent(BaseGroupingComponent[StacktraceGroupingComponent]):
+    id: str = "threads"
+
+
+class CSPGroupingComponent(
+    BaseGroupingComponent[SaltGroupingComponent | ViolationGroupingComponent | URIGroupingComponent]
+):
+    id: str = "csp"
+
+
+class ExpectCTGroupingComponent(
+    BaseGroupingComponent[HostnameGroupingComponent | SaltGroupingComponent]
+):
+    id: str = "expect-ct"
+
+
+class ExpectStapleGroupingComponent(
+    BaseGroupingComponent[HostnameGroupingComponent | SaltGroupingComponent]
+):
+    id: str = "expect-staple"
+
+
+class HPKPGroupingComponent(
+    BaseGroupingComponent[HostnameGroupingComponent | SaltGroupingComponent]
+):
+    id: str = "hpkp"
+
+
+class TemplateGroupingComponent(
+    BaseGroupingComponent[ContextLineGroupingComponent | FilenameGroupingComponent]
+):
+    id: str = "template"

src/sentry/grouping/enhancer/__init__.py

@@ -15,7 +15,7 @@
 from sentry_ophio.enhancers import Enhancements as RustEnhancements
 
 from sentry import projectoptions
-from sentry.grouping.component import BaseGroupingComponent
+from sentry.grouping.component import FrameGroupingComponent, StacktraceGroupingComponent
 from sentry.stacktraces.functions import set_in_app
 from sentry.utils.safe import get_path, set_path
 
@@ -164,11 +164,11 @@ def apply_modifications_to_frame(
 
     def assemble_stacktrace_component(
         self,
-        components: list[BaseGroupingComponent],
+        components: list[FrameGroupingComponent],
         frames: list[dict[str, Any]],
         platform: str | None,
         exception_data: dict[str, Any] | None = None,
-    ) -> tuple[BaseGroupingComponent, bool]:
+    ) -> tuple[StacktraceGroupingComponent, bool]:
         """
         This assembles a `stacktrace` grouping component out of the given
         `frame` components and source frames.
@@ -186,8 +186,7 @@ def assemble_stacktrace_component(
         for py_component, rust_component in zip(components, rust_components):
             py_component.update(contributes=rust_component.contributes, hint=rust_component.hint)
 
-        component = BaseGroupingComponent(
-            id="stacktrace",
+        component = StacktraceGroupingComponent(
             values=components,
             hint=rust_results.hint,
             contributes=rust_results.contributes,

src/sentry/grouping/strategies/base.py

@@ -1,12 +1,19 @@
 import inspect
 from collections.abc import Callable, Iterator, Sequence
-from typing import Any, Generic, Protocol, TypeVar
+from typing import Any, Generic, Protocol, TypeVar, overload
 
 from sentry import projectoptions
 from sentry.eventstore.models import Event
-from sentry.grouping.component import BaseGroupingComponent
+from sentry.grouping.component import (
+    BaseGroupingComponent,
+    ExceptionGroupingComponent,
+    FrameGroupingComponent,
+    StacktraceGroupingComponent,
+)
 from sentry.grouping.enhancer import Enhancements
 from sentry.interfaces.base import Interface
+from sentry.interfaces.exception import SingleException
+from sentry.interfaces.stacktrace import Frame, Stacktrace
 
 STRATEGIES: dict[str, "Strategy[Any]"] = {}
 
@@ -24,7 +31,10 @@
 DEFAULT_GROUPING_ENHANCEMENTS_BASE = "common:2019-03-23"
 DEFAULT_GROUPING_FINGERPRINTING_BASES: list[str] = []
 
-ReturnedVariants = dict[str, BaseGroupingComponent]
+# TODO: Hack to make `ReturnedVariants` (no pun intended) covariant. At some point we should
+# probably turn `ReturnedVariants` into a Mapping (immutable), since in practice it's read-only.
+GroupingComponent = TypeVar("GroupingComponent", bound=BaseGroupingComponent[Any])
+ReturnedVariants = dict[str, GroupingComponent]
 ConcreteInterface = TypeVar("ConcreteInterface", bound=Interface, contravariant=True)
 
 
@@ -115,6 +125,21 @@ def get_grouping_component(
         """
         return self._get_strategy_dict(interface, event=event, **kwargs)
 
+    @overload
+    def get_single_grouping_component(
+        self, interface: Frame, *, event: Event, **kwargs: Any
+    ) -> FrameGroupingComponent: ...
+
+    @overload
+    def get_single_grouping_component(
+        self, interface: SingleException, *, event: Event, **kwargs: Any
+    ) -> ExceptionGroupingComponent: ...
+
+    @overload
+    def get_single_grouping_component(
+        self, interface: Stacktrace, *, event: Event, **kwargs: Any
+    ) -> StacktraceGroupingComponent: ...
+
     def get_single_grouping_component(
         self, interface: Interface, *, event: Event, **kwargs: Any
     ) -> BaseGroupingComponent: