docs: notification templates (#263)

* docs: notification overview

* feat: template vars

* chore: kubernetes deployment health notification example

* docs: slack template for components, config & check events

* docs: add all notification template vars in reference

* docs: complete all template vars for notification

* chore: lint workflow change

* chore: refactor config notification events page

* chore: add slack notification screenshots

* docs: notification rate limiting

* docs: slack template functions

* docs: use gomplate style for notification template functions

* docs: repeat interval

.github/workflows/lint.yml

@@ -13,4 +13,17 @@ jobs:
         with:
           node-version: '20.11.1'
 
-      - run: make fmt-check
+      - name: Run format check
+        run: make fmt-check
+        continue-on-error: true
+        id: fmt-check
+
+      - name: Run formatter and show diff if check failed
+        if: steps.fmt-check.outcome == 'failure'
+        run: |
+          make fmt
+          git diff
+
+      - name: Exit with error if format check failed
+        if: steps.fmt-check.outcome == 'failure'
+        run: exit 1

Makefile

@@ -12,7 +12,7 @@ fmt:
 
 .PHONY: fmt-check
 fmt-check:
-	npx prettier --check "**/*.md"
+	npx prettier --check --log-level=debug "**/*.md"
 
 .PHONY:
 sync:

canary-checker/docs/windows.md

@@ -20,7 +20,7 @@ To run Canary Checker on windows please ensure the following
 
 ## 2. Downloading required files
 
-You only need the powershell script below(assuming internet connectivity),  place it in the folder you wish to install Canary Checker in.
+You only need the powershell script below(assuming internet connectivity). Place it in the folder you wish to install Canary Checker in.
 
 ```powershell
 [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

common/src/components/Fields.jsx

@@ -28,8 +28,8 @@ const schemes = {
   "notificationconnection": "[Connection](/reference/connections)",
   "notificationproperties": "[map[string]string](/reference/notifications#properties)",
 }
-export default function Fields({ common = [], rows = [], oneOf, anyOf, connection }) {
 
+export default function Fields({ common = [], rows = [], oneOf, anyOf, connection, withTemplates }) {
   const { siteConfig, siteMetadata } = useDocusaurusContext();
 
   const oss = siteConfig.customFields.oss;
@@ -292,55 +292,85 @@ export default function Fields({ common = [], rows = [], oneOf, anyOf, connectio
 
   return (
     <>
-      <table className='fields'>
+      <table className="fields">
         <thead>
           <tr>
             <th>Field</th>
             <th>Description</th>
             <th>Scheme</th>
+            {withTemplates && <th>Template Env</th>}
           </tr>
         </thead>
         <tbody>
           {rows.map((row, index) => (
             <tr key={index}>
               <td>
-                <code className={row.required ? "font-bold" : ""}>{row.field}{row.required ? "*" : ""}</code>
+                <code className={row.required ? 'font-bold' : ''}>
+                  {row.field}
+                  {row.required ? '*' : ''}
+                </code>
               </td>
-              <td><ReactMarkdown>{(row.description ? row.description : "") + (row.default ? `. Defaults to \`${row.default}\`` : '')}</ReactMarkdown></td>
               <td>
-                {row.anyOf &&
-                  <code>{row.anyOf.join(' | ')}</code>
-                }
-                {!row.anyOf && row.scheme &&
+                <ReactMarkdown>
+                  {(row.description ? row.description : '') +
+                    (row.default ? `. Defaults to \`${row.default}\`` : '')}
+                </ReactMarkdown>
+              </td>
+              <td>
+                {row.anyOf && <code>{row.anyOf.join(' | ')}</code>}
+                {!row.anyOf && row.scheme && (
                   <ReactMarkdown>
-                    {
-                      schemes[row.scheme.toLowerCase()] || (row.scheme ? row.scheme : 'string')
-                    }
+                    {schemes[row.scheme.toLowerCase()] ||
+                      (row.scheme ? row.scheme : 'string')}
                   </ReactMarkdown>
-                }
+                )}
               </td>
+              {withTemplates && (
+                <td>
+                  {row.templateEnv &&
+                    row.templateEnv.map((v) => (
+                      <p>
+                        <a href={v.url}>
+                          <code>{v.name}</code>
+                        </a>
+                      </p>
+                    ))}
+                </td>
+              )}
             </tr>
           ))}
-
         </tbody>
-      </table >
-      {anyOf &&
-        <blockquote style={{ borderLeft: "2px solid var(--ifm-color-warning-light)" }}>
-          <p>You must specify <code>{anyOf[0]}</code> and/or  <code>{anyOf[1]}</code></p>
+      </table>
+      {anyOf && (
+        <blockquote
+          style={{ borderLeft: '2px solid var(--ifm-color-warning-light)' }}
+        >
+          <p>
+            You must specify <code>{anyOf[0]}</code> and/or{' '}
+            <code>{anyOf[1]}</code>
+          </p>
         </blockquote>
-      }
-      {
-        oneOf && oneOf.length == 2 &&
-        <blockquote style={{ borderLeft: "2px solid var(--ifm-color-warning-light)" }}>
-          <p>You must specify <code>{oneOf[0]}</code> or <code>{oneOf[1]}</code> but not both</p>
+      )}
+      {oneOf && oneOf.length == 2 && (
+        <blockquote
+          style={{ borderLeft: '2px solid var(--ifm-color-warning-light)' }}
+        >
+          <p>
+            You must specify <code>{oneOf[0]}</code> or <code>{oneOf[1]}</code>{' '}
+            but not both
+          </p>
         </blockquote>
-      }
-      {
-        oneOf && oneOf.length == 3 &&
-        <blockquote style={{ borderLeft: "2px solid var(--ifm-color-warning-light)" }}>
-          <p>You must specify one of <code>{oneOf[0]}</code>, <code>{oneOf[1]}</code> or <code>{oneOf[2]}</code></p>
+      )}
+      {oneOf && oneOf.length == 3 && (
+        <blockquote
+          style={{ borderLeft: '2px solid var(--ifm-color-warning-light)' }}
+        >
+          <p>
+            You must specify one of <code>{oneOf[0]}</code>,{' '}
+            <code>{oneOf[1]}</code> or <code>{oneOf[2]}</code>
+          </p>
         </blockquote>
-      }
+      )}
     </>
   )
 }

mission-control/docs/notifications/concepts/index.md

@@ -0,0 +1,8 @@
+---
+title: Concepts
+sidebar_position: 2
+---
+
+import DocCardList from '@theme/DocCardList';
+
+<DocCardList />

mission-control/docs/notifications/concepts/rate-limiting.mdx

@@ -0,0 +1,40 @@
+---
+title: Rate Limiting
+---
+
+To prevent overwhelming users with excessive notifications, Mission Control implements a rate limiting mechanism.
+
+We use a sliding window rate limiter that restricts the total number of notifications sent within a specified time period.
+
+:::info
+The rate limit is applied individually to each notification.
+:::
+
+:::caution Rate Limited Notifications
+When a notification exceeds the rate limit, it is dropped and not delivered to the user.
+:::
+
+## Default Configuration
+
+The following table outlines the default rate limiting parameters:
+
+| Property                         | Value    |
+|----------------------------------|----------|
+| Maximum number of notifications allowed per window  | 50       |
+| Time period for the sliding window                  | 4 hours  | 
+
+## Customizing Rate Limiting Parameters
+
+You can override the default settings by adjusting the following properties:
+
+- `notifications.max.count`: Sets the maximum number of notifications allowed within the window
+- `notifications.max.window`: Defines the duration of the sliding window (in hours)
+
+### Example Configuration
+
+To allow a maximum of 100 notifications in a 6 hour window:
+
+```
+notifications.max.count=100
+notifications.max.window=6h
+```

mission-control/docs/notifications/concepts/repeat-interval.mdx

@@ -0,0 +1,61 @@
+---
+title: Repeat Interval
+---
+
+The repeat interval determines the duration between subsequent notifications after an initial successful delivery.
+
+```yaml title="deployment-failed.yaml"
+apiVersion: mission-control.flanksource.com/v1
+kind: Notification
+metadata:
+  name: config-updates
+  namespace: default
+spec:
+  events:
+    - config.healthy
+    - config.unhealthy
+    - config.warning
+    - config.unknown
+  filter: config.type == "Kubernetes::Deployment"
+  to:
+    email: [email protected]
+  repeatInterval: 2h
+```
+
+The above notification sends at max 1 email notification in a moving 2 hour window.
+
+## Repeat Group
+
+By default, the repeat interval applies to any notification sent for the given notification. 
+
+In the example above, if a notification is sent for a `config.healthy` event and then a new notification is to be sent
+for a `config.unhealthy` event, then the notification is dropped due to the repeat interval.
+
+With grouping, you can apply the repeat interval per source event & per resource ID.
+
+- `source_event`
+- `resource_id`
+
+```yaml title="deployment-updates.yaml"
+apiVersion: mission-control.flanksource.com/v1
+kind: Notification
+metadata:
+  name: config-updates
+  namespace: default
+spec:
+  events:
+    - config.healthy
+    - config.unhealthy
+    - config.warning
+    - config.unknown
+  filter: config.type == "Kubernetes::Deployment"
+  to:
+    email: [email protected]
+  repeatInterval: 2h
+  // highlight-start
+  repeatGroup:
+    - source_event
+  // highlight-end
+```
+
+With this change, you'll now receive at max 4 notifications for each source event.