Merge pull request #22 from VersusControl/docs/update

(docs): add template syntax document page

Author: hoalongnatsu

README.md

@@ -22,6 +22,7 @@ An open-source incident management system with multi-channel alerting capabiliti
 - [Advanced API Usage](#advanced-api-usage)
 - [SNS Usage](#sns-usage)
 - [Example](#example)
+- [Template Syntax](https://versuscontrol.github.io/versus-incident/template_syntax.html)
 - [Roadmap](#roadmap)
 - [Contributing](#contributing)
 - [License](#license)

config/telegram_message.tmpl

@@ -1,4 +1,10 @@
 🚨 <b>Critical Error Detected!</b> 🚨
 📌 <b>Service:</b> {{.ServiceName}}
 ⚠️ <b>Error Details:</b>
-{{.Logs}}
+{{.Logs}}
+---
+{{- if contains .Logs "error" }}
+This is critical error
+{{ else }}
+This is warning error
+{{ end -}}

pkg/common/email.go

@@ -7,6 +7,7 @@ import (
 	"net/smtp"
 	"path/filepath"
 	"strconv"
+	"strings"
 	m "versus-incident/pkg/models"
 )
 
@@ -33,8 +34,12 @@ func NewEmailProvider(cfg EmailConfig) *EmailProvider {
 }
 
 func (e *EmailProvider) SendAlert(i *m.Incident) error {
+	funcMapContains := template.FuncMap{
+		"contains": strings.Contains,
+	}
+
 	// Parse template
-	tmpl, err := template.New(filepath.Base(e.templatePath)).ParseFiles(e.templatePath)
+	tmpl, err := template.New(filepath.Base(e.templatePath)).Funcs(funcMapContains).ParseFiles(e.templatePath)
 	if err != nil {
 		return fmt.Errorf("failed to parse template: %w", err)
 	}

pkg/common/slack.go

@@ -2,6 +2,7 @@ package common
 
 import (
 	"fmt"
+	"path/filepath"
 	"strings"
 	"text/template"
 	m "versus-incident/pkg/models"
@@ -24,7 +25,11 @@ func NewSlackProvider(cfg SlackConfig) *SlackProvider {
 }
 
 func (s *SlackProvider) SendAlert(i *m.Incident) error {
-	tmpl, err := template.ParseFiles(s.templatePath)
+	funcMapContains := template.FuncMap{
+		"contains": strings.Contains,
+	}
+
+	tmpl, err := template.New(filepath.Base(s.templatePath)).Funcs(funcMapContains).ParseFiles(s.templatePath)
 	if err != nil {
 		return fmt.Errorf("failed to parse template: %w", err)
 	}

pkg/common/telegram.go

@@ -37,7 +37,11 @@ func (t *TelegramProvider) SendAlert(i *m.Incident) error {
 		"replaceAll": strings.ReplaceAll,
 	}
 
-	tmpl, err := template.New(filepath.Base(t.templatePath)).Funcs(funcMap).ParseFiles(t.templatePath)
+	funcMapContains := template.FuncMap{
+		"contains": strings.Contains,
+	}
+
+	tmpl, err := template.New(filepath.Base(t.templatePath)).Funcs(funcMap).Funcs(funcMapContains).ParseFiles(t.templatePath)
 	if err != nil {
 		return fmt.Errorf("failed to parse template: %w", err)
 	}

src/SUMMARY.md

@@ -3,6 +3,7 @@
 
 # User Guide
 - [Getting Started](./getting_started.md)
+- [Template Syntax](./template_syntax.md)
 
 # How to Send Error Logs to Versus Incident
 

src/template_syntax.md

@@ -0,0 +1,233 @@
+# Template Syntax Guide
+
+This document explains the template syntax (Go template syntax) used for create a custom alert template in Versus Incident.
+
+## Table of Contents
+- [Basic Syntax](#basic-syntax)
+  - [Access Data](#access-data)
+  - [Variables](#variables)
+  - [Pipelines](#pipelines)
+- [Control Structures](#control-structures)
+  - [Conditionals (if/else)](#conditionals)
+  - [Loops (range)](#loops)
+
+
+## Basic Syntax
+
+### Access Data
+
+Access data fields using double curly braces and dot notation, for example, with the data:
+
+```json
+{
+  "Logs": "[ERROR] This is an error log from User Service that we can obtain using Fluent Bit.",
+  "ServiceName": "order-service",
+}
+```
+
+Example template:
+```
+*Error in {{ .ServiceName }}*
+{{ .Logs }}
+```
+
+### Variables
+You can declare variables within a template using the {{ $variable := value }} syntax. Once declared, variables can be used throughout the template, for example:
+
+```
+{{ $owner := "Team Alpha" }}
+Owner: {{ $owner }}
+```
+
+Output:
+```
+Owner: Team Alpha
+```
+
+### Pipelines
+Pipelines allow you to chain together multiple actions or functions. The result of one action can be passed as input to another, for example:
+
+**upper**: Converts a string to uppercase.
+
+```
+*{{ .ServiceName | upper }} Failure*
+```
+
+**lower**: Converts a string to lowercase.
+
+```
+*{{ .ServiceName | lower }} Failure*
+```
+
+**title**: Converts a string to title case (first letter of each word capitalized).
+
+```
+*{{ .ServiceName | title }} Failure*
+```
+
+**default**: Provides a default value if the input is empty.
+
+```
+*{{ .ServiceName | default "unknown-service" }} Failure*
+```
+
+**slice**: Extracts a sub-slice from a slice or string.
+
+```
+{{ .Logs | slice 0 50 }}  // First 50 characters
+```
+
+**replace**: Replaces occurrences of a substring.
+
+```
+{{ .Logs | replace "error" "issue" }}
+```
+
+**trimPrefix**: Trims a prefix from a string.
+
+```
+{{ .Logs | trimPrefix "prod-" }}
+```
+
+**trimSuffix**: Trims a suffix from a string.
+
+```
+{{ .Logs | trimSuffix "-service" }}
+```
+
+**len**: Returns the length
+
+```
+{{ .Logs | len }}  // Length of the message
+```
+
+**urlquery**: Escapes a string for use in a URL query.
+
+```
+uri /search?q={{ .Query | urlquery }}
+```
+
+**You can chain multiple pipes together**:
+
+```
+{{ .Logs | trim | lower | truncate 50 }}
+```
+
+## Control Structures
+
+### Conditionals
+
+The templates support conditional logic using if, else, and end keywords.
+
+```
+{{ if .IsCritical }}
+🚨 CRITICAL ALERT 🚨
+{{ else }}
+⚠️ Warning Alert ⚠️
+{{ end }}
+```
+
+and:
+
+```
+{{ and .Value1 .Value2 .Value3 }}
+```
+
+or:
+
+```
+{{ or .Value1 .Value2 "default" }}
+```
+
+**Best Practices**
+
+Error Handling:
+
+```
+{{ If .Error }}
+  {{ .Details }}
+{{ else }}
+  No error details
+{{ end }}
+```
+
+Whitespace Control:
+
+```
+{{- if .Production }}  // Remove preceding whitespace
+PROD ALERT{{ end -}}   // Remove trailing whitespace
+```
+
+Template Comments:
+
+```
+{{/* This is a hidden comment */}}
+```
+
+Negates a boolean value:
+
+```
+{{ if not .IsCritical }}
+  This is not a critical issue.
+{{ end }}
+```
+
+Checks if two values are equal:
+
+```
+{{ if eq .Status "critical" }}
+  🚨 Critical Alert 🚨
+{{ end }}
+```
+
+Checks if two values are not equal:
+
+```
+{{ if ne .Env "production" }}
+  This is not a production environment.
+{{ end }}
+```
+
+Returns the length of a string, slice, array, or map:
+
+```
+{{ if gt (len .Errors) 0 }}
+  There are {{ len .Errors }} errors.
+{{ end }}
+```
+
+Checks if a string has a specific prefix:
+
+```
+{{ if .ServiceName | hasPrefix "prod-" }}
+  Production service!
+{{ end }}
+```
+
+Checks if a string has a specific suffix:
+
+```
+{{ if .ServiceName | hasSuffix "-service" }}
+  This is a service.
+{{ end }}
+```
+
+Checks if a message contains a specific strings:
+
+```
+{{ if contains .Logs "error" }}
+  The message contains error logs.
+{{ else }}
+  The message does NOT contain error.
+{{ end }}
+```
+
+### Loops
+
+Iterate over slices/arrays with range:
+
+```
+{{ range .ErrorStack }}
+- {{ . }}
+{{ end }}
+```