gonfique

README

gonfique - Type checked configs for Go programs

gonfique is a CLI tool for Go developers to automatically build exact struct definitions in Go that will match the provided YAML config. Designed to get all config accesses under type check. Makes breaking changes instant to notice when and where they happen. Since gonfique makes keeping the type definitions up-to-date easier, using more dynamic keys instead arrays is more practical. So, developers can access config data through field names instead error-prone array lookups.

Before gonfique

Config:
  - Name: A
    Details:
      X:
      Y:
  - Name: B
    Details:
      X:
      Y:

func main() {
  // ...
  fmt.Println(
    cfg.Find("A").Details.Get("X"),
    cfg[0].Details.Get("Y"),
  )
}

After gonfique

A:
  X:
  Y:
B:
  X:
  Y:

func main() {
  // ...
  fmt.Println(cfg.A.X, cfg.A.Y)
}

Motivation

gonfique is necessary because of there are not many reliable and sustainable alternatives.

• Accessing config data through hardcoded strings is risky. So, defining types to marshall into is necessary.
• Manually defining types is also risky because they will get outdated eventually.
• Config complexity is inevitable when there are multiple services/binaries that needs their config to stay in sync, eg. kubernetes config.

Usage

Install

go install github.com/ufukty/gonfique@v1.0.0

[!IMPORTANT] Installing the latest version in main branch is not suggested as it is used for active development. Use version tags as shown above for stable versions or download compiled binaries from Releases.

gonfique -h
Usage of gonfique:
  -in string
        input file path (yml or yaml)
  -out string
        output file path (go)
  -pkg string
        package name that will be inserted into the generated file
  -use string
        (optional) use type definitions found in <file>

Generation

gonfique -in config.yml -out config.go -pkg main

Serving suggestions

For existing Makefile users:

config.go: config.yml
    gonfique -in config.yml -out config.go -pkg main

all: config.go
    ...

For existing Visual Studio Code users:

{
  "runOnSave.commands": [
    {
      "match": "^config.yml$",
      "command": "cd '${fileDirname}' && make config.go"
    }
  ]
}

Features

Using existing type definitions

package main

type Endpoint struct {
    Path, Method string
}

gonfique -in config.yml -out config.go -pkg main -use use.go

Considerations

Arrays

gonfique assignes the necessary slice type to arrays. It works best when all items of an array possess the same schema or at least compatible schemas. Type assignment occurs as below when items have not same but compatible schemas:

# input
- action: foo 
  foo-details: ""
- action: bar 
  bar-details: ""

// output
[]struct {
  Action     string
  FooDetails string
  BarDetails string
}

[!IMPORTANT] Slice type gets defined as []any if shared keys have different type values. Like detail has given int and string values below:

- action: ""
  detail: 0
- action: ""
  detail: ""

Full example

• Kubernetes example Input YAML file > Generated Go file

Limitations

• Multidocument YAML files are not supported.
• gonfique only creates inline type definitions. See issue for discussion.

Contribution

Issues are open for discussions and rest.

License

Apache2. See LICENSE file.