Конфигурирование приложений — это интересная тема. Мало того, что форматов конфигурации в сообществе инженеров много, ситуация осложняется тем, что выбор того или иного языка определяет, как вашим приложением будут пользоваться люди. Инженеры, которые будут выкладывать ваш бэкенд в абстрактную dev- или prod-среду, будут смотреть на ваше приложение как на чёрный ящик с одной лишь ручкой: механизмом настроек.

Я, как инженер, встречал удобные и не очень текстовые конфигурации: conf в Nginx, ini в systemd, JSON в VSCode… А также YAML. Он не стал новым словом в языках, но показал, какой красивой может быть конфигурация. Впрочем, сам по себе язык тупой как пробка: если вы попробуете писать на YAML что-то сложное, с переменными или циклами, то получится химера вроде Ansible. Или вроде манифестов Kubernetes, у которого диалект настолько переусложнён, что его приходится шаблонизировать с помощью Helm.

Да, как понятно из заголовка, я хочу поговорить про язык Terraform, но сначала…

Существующие решения

Какие вообще есть языки в мире open source:

• ini, пришедший из Windows.

• А также его духовный наследник TOML, отличающийся большей структурированностью и типами.

• Java properties. Просто набор из строк ключ-значение.

• dotenv. Тоже в каком-то смысле популярный язык конфигурации из ключ-значение.

• JSON, который ещё можно встретить как язык конфигурации…

• …и YAML, наследующий структуру и типы JSON в более читаемом формате, и предоставляющий несколько расширений для строк и блоков.

• HOCON, интересный язык, который можно периодически встретить в мире Java.

• XML. Боже упаси. Нет, нет и нет. Не используйте XML как язык конфигурации в 2022 году. Пожалуйста.

• Starlark, который можно встретить в Bazel. Очень похож на Python.

• conf, антиформат, под которым вообще может скрываться что угодно: от конфигов того же Nginx или какой-нибудь Icinga2 до чёрт знает чего. Грубо говоря, это универсальное расширение для DSL.

• Groovy, который, вообще-то, полноценный язык программирования, но его можно применять как встраиваемый язык конфигурации, чем пользуется Jenkins и Gradle.

• KotlinScript, который дальше Gradle и TeamCity я нигде не встречал.

• И многие, многие другие.

А ещё есть HCL, язык, знакомый многим по Terraform.

Hashicorp Configuration Language

Так де-юре расшифровывается HCL, но на деле это больше, чем язык конфигурации: согласно официальному описанию, это инструментарий для создания своего языка, который одинаково хорошо парсится человеком и машиной. По синтаксису он больше похоже на DSL, поскольку структура конфигурации очень гибкая, может содержать блоки, переменные и вызовы функций.

Грамматика языка описана в этом документе, а, попросту говоря, код вдохновлён конфигурацией Nginx и выглядит так:

variable = “value”
block {
  type = list(string)
  attribute = [123, 456]
  innerblock {
    key = “val”
  }
}

# more real example
document “markdown” “example” {
  name = “example”
  content = file(“example.md”)
}

Здесь видно следующее:

• У языка есть все необходимые для жизни типы: числа, строки, списки и map-ы ключ-значение.

• Данные структурированы в блоки, которые могут быть вложенными. В объявлении блоков может быть два дополнительных поля (type и id).

• Можно вызывать функции.

Хорошо, с языком, в целом, разобрались. А как с ним работать из Go? На сцену приглашается фреймворк hashicorp/hcl! Он состоит из следующих библиотек:

• Одноимённая библиотека hcl/v2 содержит примитивы и интерфейсы, общие для других библиотек: Body (ветвь в дереве конфигурации), Diagnostic (структура сообщений от парсера языка) и другие.

• gohcl используется для преобразования hcl.Body в структуры Go.

• hcldec — это высокоуровневый API для валидации и работы с интерфейсом hcl.Body.

• hclparse содержит инструменты для разбора как «нативного» синтаксиса HCL, так и JSON HCL. Да, у любого HCL-кода есть и JSON-эквивалент.

• Пакет hclsimple хорош для начала работы с фреймворком, в нём есть функции высокого порядка для парсинга файлов и байтов в те же структуры.

• hclsyntax — это пакет с парсером, AST и другим низкоуровневым кодом.

• hclwrite позволяет сгенерировать HCL-конфиг по спецификации и данным.

• json — JSON-парсер HCL, о JSON-формате упоминалось чуть выше.

Пакет hclsimple

Итак. Есть hclsimple, идеальный для знакомства с системой. Попробуем написать тест?

import (
    "os"
    "path"
    "testing"

    "github.com/hashicorp/hcl/v2/hclsimple"
)
type Config1 struct {
    Name  string `hcl:"name"`
    Count int64  `hcl:"count"`
}

func TestConfig1(t *testing.T) {
    content := []byte(`
name = "Дороу"
count = 64
    `)
    var cfg Config1
    err := hclsimple.Decode("test.hcl", content, nil, &cfg)
    if err != nil {
        t.Error(err)
    }
    if cfg.Name != "Дороу" {
        t.Errorf("cfg.name: expected 'Дороу', got %v", cfg.Name)
    }
    if cfg.Count != 64 {
        t.Errorf("cfg.count: expected 64, got %v", cfg.Count)
    }
}

Что можно сказать об этом коде? Здесь есть hclsimple.Decode(), который принимает на вход имя файла (можно несуществующее) и байты, которые затем парсит в структуру. У функции есть ещё компаньон DecodeFile(), принимающий имя файла.

Что произойдёт, если Decode получит некорректное содержимое?

count = "Пашов нафих"

=== RUN   TestConfig1
    /home/igor/…/config_test.go:52: test.hcl:3,10-21: Unsuitable value type; Unsuitable value: a number is required

Конечно, мы получили сообщение об ошибке, но вот что интересно: HCL вывел позицию ошибки в файле, что крайне удобно при последующей диагностике неполадок.

Также в синтаксисе HCL допускается добавлять в объявления блока двух специальных полей (label): id и type. Пробуем:

type Document struct {
    Format   string `hcl:"type,label"`
    Name     string `hcl:"id,label"`
    Content  string `hcl:"content"`
}

type Config2 struct {
    Docs    []Document `hcl:"document,block"`
}

func TestConfig2(t *testing.T) {
    content := []byte(`
document "markdown" "readme" {
    content = "this is readme"
}
document "rst" "development" {
    content = "dev process"
}
    `)
    // …

Остальная часть теста остаётся той же.

Также можно описать в структуре только id:

type Folder struct {
    Name  string   `hcl:"id,label"`
    Items []string `hcl:"items"`
}

type Config3 struct {
    Docs    []Document `hcl:"document,block"`
    Folders []Folder   `hcl:"folder,block"`
}

func TestConfig3(t *testing.T) {
    content := []byte(`
document "markdown" "readme.md" {
    content = "this is readme"
}
document "rst" "development.rst" {
    content = "dev process"
}
folder "project" {
    items = ["readme.md", "development.rst"]
}
                      `

Отлично! С блоками и примитивными типами разобрались

Выполнение выражений

Но бывает так, что примитивных типов мало, и хочется, например, обращаться к другим атрибутам других блоков, как в Terraform. Для этого есть тип поля hcl.Expression. Но для работы с ним придётся спуститься немного поглубже в фреймворк HCL, точнее, в его систему типов и их преобразования. Этими задачами занимается библиотека zclconf/go-cty. В общем, довольно лирики:

import (
    "testing"

    "github.com/hashicorp/hcl/v2"
    "github.com/hashicorp/hcl/v2/hclsimple"
    "github.com/zclconf/go-cty/cty"
    "github.com/zclconf/go-cty/cty/gocty"
)

type Document struct {
    Format   string `hcl:"type,label" cty:"format"`
    Name     string `hcl:"id,label"   cty:"name"`
    Filename string `hcl:"filename"   cty:"filename"`
    Content  string `hcl:"content"    cty:"content"`
}

type Folder struct {
    Name        string         `hcl:"id,label"`
    Items       hcl.Expression `hcl:"items,attr"`
    ParsedItems []string
}

type Config3 struct {
    Docs    []Document `hcl:"document,block"`
    Folders []Folder   `hcl:"folder,block"`
}

func TestConfig3(t *testing.T) {
    content := []byte(`
document "markdown" "readme" {
    filename = "readme.md"
    content = "this is readme"
}
document "rst" "development" {
    filename = "development.rst"
    content = "dev process"
}
folder "project" {
    items = [doc.readme.name, doc.development.name]
}
    `)
    docType := cty.Object(map[string]cty.Type{
        "format":   cty.String,
        "filename": cty.String,
        "name":     cty.String,
        "content":  cty.String,
    })
    ctx := hcl.EvalContext{
        Variables: map[string]cty.Value{
            "doc": cty.EmptyObjectVal,
        },
    }
    var cfg Config3
    err := hclsimple.Decode("docs.hcl", content, &ctx, &cfg)
    if err != nil {
        t.Error(err)
    }
    docs := make(map[string]Document)
    docMapType := make(map[string]cty.Type)
    for _, doc := range cfg.Docs {
        docs[doc.Name] = doc
        docMapType[doc.Name] = docType
    }
    ctx.Variables["doc"], err = gocty.ToCtyValue(docs, cty.Object(docMapType))
    if err != nil {
        t.Error(err)
    }
    for _, folder := range cfg.Folders {
        val, diags := folder.Items.Value(&ctx)
        if diags.HasErrors() {
            t.Error(diags)
        }
        items := val.AsValueSlice()
        folder.ParsedItems = make([]string, 0, len(items))
        for _, v := range items {
            folder.ParsedItems = append(folder.ParsedItems, v.AsString())
        }
    }
}

Что в коде нового:

• В структуре Document появились теги cty. Они нужны для функции ToCtyValue().

• Переменная docType, в которой явно описываем поля и типы структуры Document.

• В Folder поле Items теперь типа hcl.Expression. Почему не []hcl.Expression? Просто потому, что, во-первых, массив с переменными — это тоже выражение; во-вторых, десериализатор не сможет привести массив выражений к нужной структуре.

• В EvalContext появилась пустая переменная doc типа объекта.

• Проходимся по десериализованным документам, создаём map-ы с именем и структурой документа, а также с именем и описанием типов структуры. Для чего перечислять тип документа в каждом элементе? Если мы хотим обращаться к данным через точку, то надо во всех местах ставить тип cty.Object(). А так как у объектов атрибуты могут быть разных типов, то придётся указывать тип каждого документа.

• Записываем в переменную doc EvalContext-а результат преобразования структуры в cty.Value (функция gocty.ToCtyValue()).

• Для выполнения выражения используется метод Expression.Value(ctx). Контекст при желании может быть нулевым, но сейчас мы его заполнили переменной для того, чтобы в выражениях можно было обращаться к ним.

• Кастуем значение выражения к слайсу, каждый его элемент кастуем к строке, и только тогда добавляем в каталог.

Если в двух словах, то да, работа с переменными и выражениями в HCL трудна: надо проходить по конфигурации в несколько этапов, а если появляются графы зависимостей, как в Terraform, то становится вообще понуро! С другой стороны, легко это всё равно нельзя сделать, и вообще здорово, что фреймворк позволяет отложенно обрабатывать выражения, а не в один прогон, когда парсится файл.

Анализ выражений

К слову, если хочется не обрабатывать все переменные, а просто определить по выражению, к каким переменным идёт обращение, то есть метод Expression.Variables(). Он возвращает []hcl.Traversal, то есть массив из обращений к переменным. Traversal, в свою очередь, это путь поиска значения: в пути могут встречаться обращения к индексам, к ключам map-ы, к атрибутам структуры, и так далее.

Попробуем реализовать разбор []hcl.Traversal для частного случая с переменной doc:

func TestConfig4(t *testing.T) {
    var cfg Config3
    // …
    docRefs := make(map[string]int, 0)
    for _, f := range cfg.Folders {
        varRefs := f.Items.Variables()
        for _, varref := range varRefs {
            if varref.RootName() != "doc" {
                t.Errorf("%s is not a doc variable", varref.RootName())
            }
            for lvl, it := range varref[1:] {
                switch value := it.(type) {
                case hcl.TraverseAttr:
                    if lvl == 0 {
                        if _, ok := docRefs[value.Name]; !ok {
                            docRefs[value.Name] = 1
                        }
                    }
                case hcl.TraverseIndex:
                    t.Error("indexing operations not supported")
                }
            }
        }
    }
    docType := cty.Object(map[string]cty.Type{
        "format":   cty.String,
        "name":     cty.String,
        "filename": cty.String,
        "content":  cty.String,
    })
    docVars := make(map[string]Document)
    docTypes := make(map[string]cty.Type)
    for _, doc := range cfg.Docs {
        for ref, _ := range docRefs {
            if ref == doc.Name {
                docVars[doc.Name] = doc
                docTypes[doc.Name] = docType
                break
            }
        }
    }
    var err error
    ctx.Variables["doc"], err = gocty.ToCtyValue(docVars, cty.Object(docTypes))
    // дальше парсим как раньше
}

Из интересного:

• У Config.Items (тип hcl.Expression) вызываем метод Variables(), который возвращает перечень обращений к переменным ([]hcl.Traversal, о котором говорилось ранее).

• Поскольку Traversal — это псевдоним для []Traverser, то по нему тоже можно итерироваться.

• Traverser — это общий интерфейс, поэтому в обходе цикла понадобится кастовать к конкретным структурам, то есть делать switch value := it.(type).

• У Traverse три реализации — это TraverseAttr, TraverseIndex, а также TraverseSplat.

• Если переменная типа doc.<name>.<attrs>, то записываем name в docRefs (это наше а-ля set) с исключением дубликатов.

• Проходимся по cfg.Docs, если имя документа есть в docRefs, то добавляем его в объект переменной.

Частичный парсинг

Потенциально можно пойти ещё дальше в сторону не просто разбора обращения к переменным, а ещё и в сторону частичного разбора конфига в целом: 

func TestConfig4(t *testing.T) {
    // ...
    hclfile, diags := hclsyntax.ParseConfig(content, "docs.hcl", hcl.InitialPos)
    if diags.HasErrors() {
        t.Error(diags)
    }
    bc, _, _ := hclfile.Body.PartialContent(folderSchema)
    folder := bc.Blocks[0]
    if folder.Labels[0] != "project" {
        t.Errorf("folder name: expected %v, got %v", "project", folder.Labels[0])
    }
    attrs, diags := folder.Body.JustAttributes()
    if diags.HasErrors() {
        t.Error(diags)
    }
    for key, _ := range attrs {
        if key != "items" {
            t.Errorf("folder attr: expected %v, got %v", "items", key)
        }
    }
}

var folderSchema = &hcl.BodySchema{
    Blocks: []hcl.BlockHeaderSchema{
        {
            Type:       "folder",
            LabelNames: []string{"name"},
        },
    },
    Attributes: []hcl.AttributeSchema{
        {Name: "items", Required: true},
    },
}

• Здесь через низкоуровневый hclsyntax.ParseConfig() конфиг парсится в hcl.File.

• Это нужно для того, чтобы потом обратиться к его полю Body (тип hcl.Body) и получить частичный результат (hcl.BodyContent).

• Также PartialContent() возвращает оставшуюся часть hcl.Body и «диагностику». Диагностика при частичном парсинге будет содержать ошибки, поэтому её мы игнорируем, как и тело, которое нам сейчас не нужно.

• PartialContent() принимает только один аргумент — hcl.BodySchema, схему документа для валидации.

• В конце берём первый попавшийся блок, смотрим на его первую метку, а также на атрибуты.

Функции

HCL, как уже упоминалось, поддерживает функции, а как их объявлять в контексте? Примерно следующим образом:

func TestConfig5(t *testing.T) {
    content := []byte(`
document "markdown" "readme" {
    filename = "readme.md"
    content = file("readme.md")
}
document "rst" "development" {
    filename = "development.rst"
    content = file("development.rst")
}
folder "project" {
    items = [doc.readme.name, doc.development.name]
}
    `)
    ctx := hcl.EvalContext{
        Functions: map[string]function.Function{
            "file": FileFunc,
        },
    }
    var cfg Config3
    err := hclsimple.Decode("docs.hcl", content, &ctx, &cfg)
    if err != nil {
        t.Error(err)
    }
    for _, v := range cfg.Docs {
        if v.Name == "readme" && v.Content != "<readme.md content>" {
            t.Error("readme has content:", v.Content)
        }
        if v.Name == "development" && v.Content != "<development.rst content>" {
            t.Error("development has content:", v.Content)
        }
    }
}

var FileFunc = function.New(&function.Spec{
    VarParam: nil,
    Params: []function.Parameter{
        {Type: cty.String},
    },
    Type: func(args []cty.Value) (cty.Type, error) {
        return cty.String, nil
    },
    Impl: func(args []cty.Value, retType cty.Type) (cty.Value, error) {
        filename := args[0].AsString()
        var err error
        // content, err := os.ReadFile(filename)
        content, err := []byte(fmt.Sprintf("<%s content>", filename)), nil
        if err != nil {
            return cty.NilVal, err
        }
        return cty.StringVal(string(content)), nil
    },
})

• VarParam — это тип для varargs-аргумента функции. Если таковой у функции есть.

• Params — набор аргументов, которые принимает функция.

• Type — тип возвращаемого значения, можно вычислить на основе полученных аргументов.

• Impl — собственно, тело функции. os.ReadFile подменён фейковыми данными, но принцип работы понятен.

Также в библиотеке cty есть пакет functions.stdlib с уже готовыми функциями для работы с числами, массивами, строками и их форматированием, и другие.

В заключение

Hashicorp Configuration Language выделяется из других языков хорошим синтаксисом и одноимённым фреймворком. По функциональности язык можно сравнить можно со Starlark, Groovy и KotlinScript, однако в отличие от первого hashicorp/hcl умеет парсить код в несколько этапов и с разными подходами, а Groovy/Kotlin требуют свой компилятор в runtime. На мой взгляд, HCL — это отличное решение для сложной и декларативной конфигурации, или если вы пишете инструмент для DevOps, которые тоже любят описывать инфраструктуру в декларативной конфигурации.