Handlebars template static validation and documentation #1030

teresaromero · 2025-11-28T09:19:37Z

What does this PR do?

Includes a validation rule for verifying the static .hbs files used at input tempate and stream template are correct.
Also adds more information on the spec regarding the format of these templates and the helpers that are available at fleet when rendering them.
Linked file are also verified .hbs.link

The validation is done over the static syntax of handlebars, does not validate the render of the template taking into account the values of the values.

Why is it important?

If a template arrives fleet without being checked, the can be errors when fleet renders the template. This is a way to prevent this before the package is installed.

Checklist

Added unit tests and validation test with test packages

I have added test packages to test/packages that prove my change is effective.
I have added an entry in spec/changelog.yml.

Related issues

Resolves #21

… packages

…ency

…emplates

teresaromero · 2025-11-28T09:31:21Z

test integrations

mrodm · 2025-11-28T10:06:11Z

code/go/internal/validator/semantic/validate_hbs_templates.go

+	pkgEntries, err := fs.Glob(fsys, "agent/**/*.hbs")
+	if err != nil && !errors.Is(err, fs.ErrNotExist) {
+		return nil, err
+	}


According to the spec, this files could also be links.
Would this catch even the links thanks to the filesystem ? Or is it needed to add a special case for link files?

i've updated the PR to include the linked files. For this i've changed the aproach of glob and used nested readDirs to get into the files.
i've added tests and test packages to check this works as expected with the links 👍🏻

go.mod

code/go/internal/validator/semantic/validate_hbs_templates.go

mrodm · 2025-11-28T10:12:17Z

code/go/internal/validator/semantic/validate_hbs_templates.go

+
+// validateFile validates a single Handlebars file located at filePath.
+// it parses the file using the raymond library to check for syntax errors.
+func validateFile(filePath string) error {


I'd rename this to be more specific, what about validateHandlebarTemplateFile or validateHandlebarTemplate?

yup, i've gone around this one :D as the "parent" function is very similar... i will think around this

…est.go

…or consistency

code/go/internal/validator/semantic/validate_hbs_templates.go

…bsolute path for linked files

teresaromero · 2025-12-03T11:22:44Z

test integrations

elastic-vault-github-plugin-prod · 2025-12-03T11:29:29Z

Created or updated PR in integrations repository to test this version. Check elastic/integrations#16224

mrodm · 2025-12-03T11:07:43Z

code/go/internal/validator/semantic/validate_hbs_templates.go

+		// If fs.ReadFile fails (likely due to linked file path outside filesystem boundary),
+		// fall back to absolute path approach like linkedfiles.FS does
+		absolutePath := fsys.Path(filePath)
+		if content, err = os.ReadFile(absolutePath); err != nil {
+			return err
+		}


According to the comment, is this already done by the linkedfiles.FS ? If so, maybe it could be removed from here.

this refers to the logic at getLinkedFileChecksum where the file content is read to get the checksum. If the file is not within fsys fs.ReadFile fails, as is not in its scope. If this happens, we use os.ReadFile (like in getLinkedFileChecksum) to read the file with the absolute path of it

spec/integration/agent/spec.yml

code/go/internal/validator/semantic/validate_hbs_templates.go

mrodm · 2025-12-03T11:37:23Z

code/go/internal/validator/semantic/validate_hbs_templates.go

+			}
+			err = validateHandlebarsEntry(fsys, dir, linkFile.IncludedFilePath)
+			if err != nil {
+				return err


Could it be defined a specerrors.ValidationErrors here in this function and add all the errors found in a given folder?
I was thinking if it could be possible to show all the errors at once to the user.

fixed this and adding more context to the error 👍🏻

an example of the output when testing one of the failed integration:

Error: building package failed: invalid content found in built zip package: found 1 validation error: 1. invalid handlebars template: error validating data_stream/alerts_events_v2/agent/stream/gcs.yml.hbs: Parse error on line 49: Expecting OpenEndBlock, got: 'EOF'

…s in spec files

… tests for clarity

…bars-validation

teresaromero · 2025-12-03T14:20:29Z

after running the test against the current integrations, two of them had errors regarding some template parsing.
I opened a draft elastic/integrations#16230 to solve this. pending to test this changes

andrewkroh · 2025-12-03T14:54:41Z

spec/integration/data_stream/agent/spec.yml

+            Config template file for inputs defined in the policy_templates section of the top level manifest.
+            The template should use standard Handlebars syntax (e.g., `{{vars.key}}`, `{{#if vars.condition}}`, `{{#each vars.items}}`)
+            and must compile to valid YAML.
+            Available Handlebars helpers include: 


Can you please document the metadata variables that are available in templates too. See elastic/kibana#241140

udpated the pr bd2358e with more docs on variables

…nd clarify helper list

…bars-validation

elasticmachine · 2025-12-12T10:25:53Z

💚 Build Succeeded

Buildkite Build
Commit: 5b236f1

History

💚 Build #1685 succeeded 76d1835
💔 Build #1683 failed 75e87b6
💛 Build #1665 was flaky bd2358e
💚 Build #1660 succeeded 17b18db
💔 Build #1658 failed 31644e8
💔 Build #1657 failed 0d298e7

mrodm

LGTM, thanks!

jsoriano

Only a couple of comments, but I am fine with implemented approach.

jsoriano · 2025-12-15T11:22:41Z

code/go/internal/validator/semantic/validate_hbs_templates_test.go

+func TestValidateTemplateDir(t *testing.T) {
+	t.Run("empty directory", func(t *testing.T) {
+		tmpDir := t.TempDir()
+		pkgDir := path.Join(tmpDir, "package")


Nit. Most paths in these tests are native paths, they should be joined with filepath.Join.

jsoriano · 2025-12-15T11:24:28Z

code/go/internal/validator/spec.go

 		{fn: semantic.ValidateMinimumAgentVersion},
 		{fn: semantic.ValidateIntegrationPolicyTemplates, types: []string{"integration"}},
 		{fn: semantic.ValidatePipelineTags, types: []string{"integration"}, since: semver.MustParse("3.6.0")},
+		{fn: semantic.ValidateStaticHandlebarsFiles, types: []string{"integration", "input"}},


Did you consider to place the validation in the spec? It could have been done by using a content media type and something like the validateContentType method.

But using a semantic validator LGTM too in any case.

I did not. Thanks for this suggestion, i see now that adding this to the spec, perhaps with a custom type application/x-hbs could simplify the validation, as it will detect the files, instead of looking for them under the folders as the current implementation does.... 🤔 although for linked files i am not sure how it will work, i guess we could rely on the internal linked file to exist, and this being validated as hbs where originally is placed.

i think this approach could be an improvement

teresaromero added 4 commits November 28, 2025 09:46

Add Handlebars template validation and corresponding tests

d6d204e

add validator test cases with bad packages

ea6d4bd

Add validation for Handlebars template files in input and integration…

67389f6

… packages

Refactor Handlebars definition specifications for clarity and consist…

97a32b2

…ency

teresaromero requested a review from a team as a code owner November 28, 2025 09:19

teresaromero added 3 commits November 28, 2025 10:20

Update changelog with link

f5854ea

Fix variable naming for handlebars template validation error

32ebc29

Fix syntax error in sql_query definition across multiple Handlebars t…

e76c19a

…emplates

mrodm reviewed Nov 28, 2025

View reviewed changes

teresaromero added 7 commits November 28, 2025 11:17

Reorder import statements for consistency in validate_hbs_templates.go

49c9c5a

update compliace gomod

86281bb

Refactor Handlebars validation logic to include linked files

3e48130

Add bad integration Handlebars templates with linked files

32ab54d

Reorder import statements for consistency in validate_hbs_templates_t…

bc7eee5

…est.go

use path instead of filepath

0f1ae93

Replace filepath.Join with path.Join in TestValidateHandlebarsFiles f…

d4898fe

…or consistency

teresaromero commented Dec 1, 2025

View reviewed changes

code/go/internal/validator/semantic/validate_hbs_templates.go Outdated Show resolved Hide resolved

teresaromero marked this pull request as draft December 1, 2025 14:09

fix validateHandlebarsEntry to read file content from filesystem or a…

d6ee0cd

…bsolute path for linked files

teresaromero marked this pull request as ready for review December 1, 2025 15:56

Reorder logrus dependency in go.mod for consistency

ab1a541

elastic-vault-github-plugin-prod bot mentioned this pull request Dec 3, 2025

Test branch package-spec#1030 - DO NOT MERGE elastic/integrations#16224

Closed

mrodm reviewed Dec 3, 2025

View reviewed changes

teresaromero added 4 commits December 3, 2025 14:31

Improve error messages in Handlebars validation for clarity

0d298e7

Add link to Fleet implementation link for available Handlebars helper…

e699759

…s in spec files

Refactor Handlebars validation to return structured errors and update…

31644e8

… tests for clarity

Merge branch 'main' of github.com:elastic/package-spec into 21-handle…

62679a5

…bars-validation

append errors instead of return

17b18db

teresaromero mentioned this pull request Dec 3, 2025

fix integrations with failing parsing hbs templates elastic/integrations#16230

Merged

5 tasks

andrewkroh reviewed Dec 3, 2025

View reviewed changes

teresaromero added 3 commits December 5, 2025 09:43

Update Handlebars documentation to include available meta variables a…

bd2358e

…nd clarify helper list

Merge branch 'main' of github.com:elastic/package-spec into 21-handle…

79bde15

…bars-validation

Merge branch 'main' of github.com:elastic/package-spec into 21-handle…

667ed7c

…bars-validation

teresaromero changed the title ~~Handlebars template validation and documentation~~ Handlebars template static validation and documentation Dec 11, 2025

teresaromero added 5 commits December 11, 2025 11:41

Add test for valid multiline Handlebars file template

70547b9

Replace mailgun/raymond with aymerick/raymond and update dependencies

b896c68

Rename Handlebars validation functions for clarity and update changelog

75e87b6

Add missing newline in import section of validate_hbs_templates.go

76d1835

Handlebars validation: improve error handling for invalid file reads

5b236f1

mrodm approved these changes Dec 12, 2025

View reviewed changes

teresaromero merged commit bea6555 into elastic:main Dec 15, 2025
3 checks passed

jsoriano reviewed Dec 15, 2025

View reviewed changes

Handlebars template static validation and documentation #1030

Handlebars template static validation and documentation #1030

Uh oh!

Conversation

teresaromero commented Nov 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What does this PR do?

Why is it important?

Checklist

Related issues

Uh oh!

teresaromero commented Nov 28, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

teresaromero commented Dec 3, 2025

Uh oh!

elastic-vault-github-plugin-prod bot commented Dec 3, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

teresaromero commented Dec 3, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

elasticmachine commented Dec 12, 2025

💚 Build Succeeded

History

Uh oh!

mrodm left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jsoriano left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

teresaromero commented Nov 28, 2025 •

edited

Loading