paramgen

ParamGen

ParamGen is a conduit tool that generates the code to return the parameters map from a certain Go struct.

Installation

Once you have installed Go, install the paramgen tool.

Note: If you have not done so already be sure to add $GOPATH/bin to your PATH.

go install github.com/conduitio/conduit-connector-sdk/cmd/paramgen@latest

Usage

ParamGen has one required argument, which is the struct name, and two optional flags for the path and the output file name.

paramgen [-path] [-output] structName

Example:

paramgen -path=./source -output=source_params.go SourceConfig

This example will search for a struct called SourceConfig in the path ./source, it will create a parameter map of only the exported fields, and generate the code to return this map in the file source_params.go under the same folder.

Parameter Tags

In order to give your parameter a name, a default value, or add some validations to it, tags are the way to go. We have three tags that can be parsed:

1. json: this tag is used to rename the parameter.

   Name string `json:"first-name"`
   

2. default: sets the default value for the parameter.

   Name string `default:"conduit"`
   

3. validate: adds builtin validations to the parameter, these validations will be executed by conduit once a connector is configured. Validations are separated by a comma, and have 6 main types:

   • required: a boolean tag to indicate if a field is required or not. If it is added to the validate tag without a value, then we assume the field is required.

     NameRequired    string `validate:"required"`
     NameRequired2   string `validate:"required=true"`
     NameNotRequired string `validate:"required=false"`
     

   • lt or less-than: takes an int or a float value, indicated that the parameter should be less than the value provided.

   • gt or greater-than: takes an int or a float value, indicated that the parameter should be greater than the value provided.

     Age int `validate:"gt=0,lt=200"`
     Age2 float `validate:"greater-than=0,less-than=200.2"`
     

   • inclusion: validates that the parameter value is included in a specified list, this list values are separated using a pipe character |.

     Gender string `validate:"inclusion=male|female|other"`
     

   • exclusion: validates that the parameter value is NOT included in a specified list, this list values are separated using a pipe character |.

     Color string `validate:"exclusion=red|green"`
     

   • regex: validates that the parameter value matches the regex pattern.

     Email string `validate:"regex=^[\w-\.]+@([\w-]+\.)+[\w-]{2,4}$"`
     

Example

Assume we have this configuration struct:

package source
type SourceConfig struct {
	InnerConfig
	// Param1 my param1 description
	Param1 int `validate:"required,gt=0,lt=100" default:"10"`
	// comment about param2
	Param2 bool   `validate:"inclusion=true|t,exclusion=false|f" default:"t"`
	Param3 string `validate:"regex=.*" default:"yes"`
	
	// this will be ignored because it's not exported
	privateParam string
}

type InnerConfig struct {
	Name string `validate:"required" json:"my-name"`
}

And you call ParamGen:

paramgen -path ./source SourceConfig

A file called paramgen.go will be created under ./source:

// Code generated by ParamGen. DO NOT EDIT.
// Source: github.com/conduitio/conduit-connector-sdk/cmd/paramgen

package source

import (
	"regexp"

	sdk "github.com/conduitio/conduit-connector-sdk"
)

func (SourceConfig) Parameters() map[string]sdk.Parameter {
	return map[string]sdk.Parameter{
		"innerConfig.my-name": {
			Default:     "",
			Description: "",
			Type:        sdk.ParameterTypeString,
			Validations: []sdk.Validation{
				sdk.ValidationRequired{},
			},
		},
		"param1": {
			Default:     "10",
			Description: "param1 my param1 description",
			Type:        sdk.ParameterTypeInt,
			Validations: []sdk.Validation{
				sdk.ValidationRequired{},
				sdk.ValidationGreaterThan{Value: 0},
				sdk.ValidationLessThan{Value: 100},
			},
		},
		"param2": {
			Default:     "t",
			Description: "comment about param2",
			Type:        sdk.ParameterTypeBool,
			Validations: []sdk.Validation{
				sdk.ValidationInclusion{List: []string{"true", "t"}},
				sdk.ValidationExclusion{List: []string{"false", "f"}},
			},
		},
		"param3": {
			Default:     "yes",
			Description: "",
			Type:        sdk.ParameterTypeString,
			Validations: []sdk.Validation{
				sdk.ValidationRegex{Regex: regexp.MustCompile(".*")},
			},
		},
	}
}