feat(notif-platform): Prototype the template layer (#94369)

This PR introduces some more structure around templates, including a
template registry. I've also added some tests to ensure developer
interface with it correctly.

For example, registering with an unknown key:

```
@template_registry.register('some-unknown-key')
MyTemplate(...): ...
```
will yield:
```
tests/sentry/notifications/platform/test_registry.py:40: in test_no_unknown_registration_keys
    assert (
E   AssertionError: Template <class 'sentry.notifications.platform.registry.DemoNotificationTemplate'> was registered with an unknown key (some-unknown-key)
E
E   assert 'some-unknown-key' in NotificationTemplateKey
```
and forgetting a template, but adding to NotificationTemplateKey

```
tests/sentry/notifications/platform/test_registry.py:55: in test_no_unused_production_keys
    raise AssertionError(
E   AssertionError: Known NotificationTemplateKey(s) have no associated template registered: 'my_new_template'
E   Use @template_registry.register() to register them, or explicitly exclude them within this test.

```

We've discussed this below block offline, it's the way forward for now
so collapsing it for legibility
  <details> 
  <summary>Explanation of NotificationRenderedTemplate</summary>
  
  This has a few things to consider though: 
- For email, we have flexibility, we can just pass the existing django
templates and get whatever level of customization we want by modifying
the templates.
- For integrations though, `body` (for example) is just a `str`. So if a
notification wanted bold the text of a slack message, it'd have to be
signaled within the `str` to bold somehow, likely from a shared
templating language (e.g. markdown `**`s), which is idealistic. This
would have to be understood by all providers; which is reasonable for
MSTeams/Slack/Discord, but might not work for future providers(?) if
they don't parse markdown, or do so differently (e.g notion uses `|
text` for quotes, md uses `> text` even though most other syntax is
md-like)
- If we allow markdown in the `str` attributes, it's likely we'd get
bugs as soon as someone tries a provider specific md formatting (e.g.
imagine like `f"[John](@john)"` or something)
- Onboarding new providers would also become a minefield if there is
syntax assumed to be understood by all that is done differently for
other integrations (e.g. if jira uses [img:link](...) but slack uses
![link](...)) -- If a new provider needs a new format, it means every
notify call must now be updated to include the new syntax :(
  
    
The only way around this I can see is restricting to top level building
blocks (e.g. `subject`, `body`, `action`, `chart`) that explicitly will
not allow custom formatting, and deferring to renderers to do all
non-standard elements. Pros: Consistency out of the box, and devs never
need to learn slack markdown vs discord markdown. Cons: If a dev wants
to bold text, they need a custom renderer for each provider 🙃
  </details>

Author: leeandher

src/sentry/notifications/platform/README.md

@@ -1,8 +1,56 @@
 # Notification Platform
 
-TODO(ecosystem): Fill this out
+This module enables Sentry to send standardized notifications across different providers, with rich contents
+like images, calls to action, and dynamic links. It does this through a series of data models and concepts which can be heavily customized,
+but also provides some opinionated defaults to make it easy to get started.
 
-## NotificationProvider
+A quick glossary overview:
+
+- **Notification Service** - the interface to actually send your notifications
+- **Notification Data** - the raw data which is necessary for your notification
+- **Notification Template** - the class which is responsible for processing your raw Notification Data into a user readable format
+- **Notification Rendered Template** - the standardized format all notifications adhere to prior to being sent
+- **Notification Provider** - the medium to which a notification is sent (e.g. slack, discord)
+- **Notification Provider Renderer** - the adapter to convert templates to provider specific formats (e.g. Slack's BlockKit, HTML for emails)
+- **Notification Target** - the intended recipients of a notification
+- **Notification Strategy** - a standardized pattern for repeatably creating targets
+
+If you're developing a new feature, and wish to notify a Slack channel, Discord direct message, or just send an email,
+refer to the [usage](#usage) instructions ahead. If you're extending the platform, check out [development](#development) instead.
+
+## Usage
+
+For wholly new notifications, you'll have to set up the following:
+
+1. Decide on a `NotificationCategory` (for opt-out) and assign a `NotificationSource` (for logs/metrics) in [types.py](./types.py).
+2. Use the above to create a dataclass (following the `NotificationData` protocol in [types.py](./types.py))
+3. Create a template (`NotificationTemplate` subclass) to convert your `NotificationData` to a `NotificationRenderedTemplate`.
+4. Create targets from the intended recipients (preferably with a `NotificationStrategy`)
+5. Import the `NotificationService` into your app code, and call `notify()`!
+
+If you're changing the formatting of an existing notification, just update the loader from Step 3.
+If you're sending an existing notification from new code, just import the service from Step 5.
+
+In general, the platform has sensible defaults, and standardized elements to help with consistency across providers and notifications.
+If you find yourself needing more customization, a [custom ProviderRenderer](#notificationproviderrenderer) might be helpful, but consider adding the change to all other providers as well.
+
+### Example
+
+<!-- TODO(ecosystem): Add example here -->
+
+## Development
+
+The following are common areas that owners of the NotificationPlatform may need to extend/improve.
+
+### NotificationStrategy
+
+<!-- TODO(ecosystem): Add guidance here -->
+
+### NotificationProviderRenderer
+
+<!-- TODO(ecosystem): Add guidance here -->
+
+### NotificationProvider
 
 A notification provider is the system which Sentry will trigger in order to notify NotificationTargets, for example; Email or Slack.
 
@@ -14,3 +62,7 @@ To register a new provider:
    - Extend `NotificationProvider` from [`.provider`](./provider.py) and implement its methods/variables.
    - Import `provider_registry` from [`.registry`](./registry.py) and add it via decorator: `@provider_registry.register(<YOUR-KEY-HERE>)`
 4. In [../apps](../apps.py), explicitly import the module to register the provider on initialization.
+
+### NotificationTemplate
+
+<!-- TODO(ecosystem): Add guidance here -->

src/sentry/notifications/platform/discord/provider.py

@@ -7,9 +7,9 @@
 from sentry.notifications.platform.types import (
     NotificationData,
     NotificationProviderKey,
+    NotificationRenderedTemplate,
     NotificationTarget,
     NotificationTargetResourceType,
-    NotificationTemplate,
 )
 from sentry.organizations.services.organization.model import RpcOrganizationSummary
 
@@ -23,7 +23,7 @@ class DiscordRenderer(NotificationRenderer[DiscordRenderable]):
     @classmethod
     def render[
         DataT: NotificationData
-    ](cls, *, data: DataT, template: NotificationTemplate[DataT]) -> DiscordRenderable:
+    ](cls, *, data: DataT, rendered_template: NotificationRenderedTemplate) -> DiscordRenderable:
         return {}
 
 

src/sentry/notifications/platform/email/provider.py

@@ -7,9 +7,9 @@
 from sentry.notifications.platform.types import (
     NotificationData,
     NotificationProviderKey,
+    NotificationRenderedTemplate,
     NotificationTarget,
     NotificationTargetResourceType,
-    NotificationTemplate,
 )
 from sentry.organizations.services.organization.model import RpcOrganizationSummary
 
@@ -23,7 +23,7 @@ class EmailRenderer(NotificationRenderer[EmailRenderable]):
     @classmethod
     def render[
         DataT: NotificationData
-    ](cls, *, data: DataT, template: NotificationTemplate[DataT]) -> EmailRenderable:
+    ](cls, *, data: DataT, rendered_template: NotificationRenderedTemplate) -> EmailRenderable:
         return {}
 
 

src/sentry/notifications/platform/msteams/provider.py

@@ -7,9 +7,9 @@
 from sentry.notifications.platform.types import (
     NotificationData,
     NotificationProviderKey,
+    NotificationRenderedTemplate,
     NotificationTarget,
     NotificationTargetResourceType,
-    NotificationTemplate,
 )
 from sentry.organizations.services.organization.model import RpcOrganizationSummary
 
@@ -23,7 +23,7 @@ class MSTeamsRenderer(NotificationRenderer[MSTeamsRenderable]):
     @classmethod
     def render[
         DataT: NotificationData
-    ](cls, *, data: DataT, template: NotificationTemplate[DataT]) -> MSTeamsRenderable:
+    ](cls, *, data: DataT, rendered_template: NotificationRenderedTemplate) -> MSTeamsRenderable:
         return {}
 
 

src/sentry/notifications/platform/provider.py

@@ -3,6 +3,7 @@
 from sentry.notifications.platform.renderer import NotificationRenderer
 from sentry.notifications.platform.types import (
     NotificationCategory,
+    NotificationData,
     NotificationProviderKey,
     NotificationTarget,
     NotificationTargetResourceType,
@@ -51,7 +52,7 @@ def validate_target(cls, *, target: NotificationTarget) -> None:
 
     @classmethod
     def get_renderer(
-        cls, *, category: NotificationCategory
+        cls, *, data: NotificationData, category: NotificationCategory
     ) -> type[NotificationRenderer[RenderableT]]:
         """
         Returns an instance of a renderer for a given notification, falling back to the default renderer.

src/sentry/notifications/platform/registry.py

@@ -3,6 +3,7 @@
 from typing import Any
 
 from sentry.notifications.platform.provider import NotificationProvider
+from sentry.notifications.platform.types import NotificationTemplate
 from sentry.organizations.services.organization.model import RpcOrganizationSummary
 from sentry.utils.registry import Registry
 
@@ -33,3 +34,4 @@ def get_available(
 
 
 provider_registry = NotificationProviderRegistry()
+template_registry = Registry[type[NotificationTemplate[Any]]]()

src/sentry/notifications/platform/renderer.py

@@ -3,7 +3,7 @@
 from sentry.notifications.platform.types import (
     NotificationData,
     NotificationProviderKey,
-    NotificationTemplate,
+    NotificationRenderedTemplate,
 )
 
 
@@ -22,9 +22,13 @@ class NotificationRenderer[RenderableT](Protocol):
     @classmethod
     def render[
         DataT: NotificationData
-    ](cls, *, data: DataT, template: NotificationTemplate[DataT]) -> RenderableT:
+    ](cls, *, data: DataT, rendered_template: NotificationRenderedTemplate) -> RenderableT:
         """
-        Convert template, and data into a renderable object.
-        The form of the renderable object is defined by the provider.
+        Convert a rendered template into a renderable object specific to the provider.
+        For example, Slack might output BlockKit JSON, email might output HTML/txt.
+
+        We pass in the data as well since custom renderers may use raw data to modify the output
+        for the provider where the template cannot. For example, custom markdown formatting,
+        provider-specific features like modals, etc.
         """
         ...

src/sentry/notifications/platform/service.py

@@ -1,13 +1,12 @@
 import logging
 from typing import Final
 
-from sentry.notifications.platform.registry import provider_registry
+from sentry.notifications.platform.registry import provider_registry, template_registry
 from sentry.notifications.platform.target import prepare_targets
 from sentry.notifications.platform.types import (
     NotificationData,
     NotificationStrategy,
     NotificationTarget,
-    NotificationTemplate,
 )
 
 logger = logging.getLogger(__name__)
@@ -21,12 +20,8 @@ class NotificationService[T: NotificationData]:
     def __init__(self, *, data: T):
         self.data: Final[T] = data
 
-    def notify_prepared_target(
-        self,
-        *,
-        target: NotificationTarget,
-        template: NotificationTemplate[T],
-    ) -> None:
+    # TODO(ecosystem): Eventually this should be converted to spawn a task with the business logic below
+    def notify_prepared_target(self, *, target: NotificationTarget) -> None:
         """
         Send a notification directly to a prepared target.
         NOTE: This method ignores notification settings. When possible, consider using a strategy instead of
@@ -48,8 +43,11 @@ def notify_prepared_target(
         provider.validate_target(target=target)
 
         # Step 4: Render the template
-        renderer = provider.get_renderer(category=self.data.category)
-        renderable = renderer.render(data=self.data, template=template)
+        template_cls = template_registry.get(self.data.source)
+        template = template_cls()
+        rendered_template = template.render(data=self.data)
+        renderer = provider.get_renderer(data=self.data, category=template.category)
+        renderable = renderer.render(data=self.data, rendered_template=rendered_template)
 
         # Step 5: Send the notification
         provider.send(target=target, renderable=renderable)
@@ -59,9 +57,7 @@ def notify(
         *,
         strategy: NotificationStrategy | None = None,
         targets: list[NotificationTarget] | None = None,
-        template: NotificationTemplate[T],
     ) -> None:
-
         if not strategy and not targets:
             raise NotificationServiceError(
                 "Must provide either a strategy or targets. Strategy is preferred."
@@ -80,4 +76,4 @@ def notify(
         prepare_targets(targets=targets)
 
         for target in targets:
-            self.notify_prepared_target(target=target, template=template)
+            self.notify_prepared_target(target=target)

src/sentry/notifications/platform/slack/provider.py

@@ -7,9 +7,9 @@
 from sentry.notifications.platform.types import (
     NotificationData,
     NotificationProviderKey,
+    NotificationRenderedTemplate,
     NotificationTarget,
     NotificationTargetResourceType,
-    NotificationTemplate,
 )
 from sentry.organizations.services.organization.model import RpcOrganizationSummary
 
@@ -23,7 +23,7 @@ class SlackRenderer(NotificationRenderer[SlackRenderable]):
     @classmethod
     def render[
         DataT: NotificationData
-    ](cls, *, data: DataT, template: NotificationTemplate[DataT]) -> SlackRenderable:
+    ](cls, *, data: DataT, rendered_template: NotificationRenderedTemplate) -> SlackRenderable:
         return {}