config

Documentation

Overview

Copyright 2023 The acquirecloud Authors

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Copyright 2023 The acquirecloud Authors

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Index

• func LoadJSONAndApply[T any](e Enricher[T], path string) error
• type Enricher
  • func NewEnricher[T any](val T) Enricher[T]

Functions

func LoadJSONAndApply

func LoadJSONAndApply[T any](e Enricher[T], path string) error

LoadJSONAndApply allows to load the key-values from the JSON file. The variables will be applied to the structure like ApplyEnvVariables function but without prefix. This function is useful for loading secrets file.

Example: JSON file content: {"DB_PASSWORD": "123456"}

The loader:

type DBConfig struct {
	Password string
}

type Config struct {
	DB DBConfig
}

enricher := NewEnricher(Config{}) LoadJSONAndApply(enricher, "/mnt/service/secrets") cfg := enricher.Value()

The following Config fields will be set: cfg.DB.Password == "123456"

Types

type Enricher

type Enricher[T any] interface {
	// LoadFromFile allows to load the structure's fields from the YAML or JSON file.
	// Which format is used, is defined by the file extension (.json or .yaml)
	// The structure fields may be annotated (and maybe not) by the standard json:"..." tag
	// the first field in the tag will be used as an alias for the field, but the field also
	// may be addressed by its name, if the annotation is not specified
	LoadFromFile(fileName string) error

	// LoadFromJSONFile loads the context from the jsonFileName and try to unmarshal it as
	// JSON. If the jsonFileName is empty, nothing happens and the function immediately returns
	// nil. If the file doesn't exist, the function will return errors.NotExist error, otherwise
	// it will parse the contest and return nil if it could unmarshal it as JSON or the
	// unmarshalling JSON error.
	LoadFromJSONFile(jsonFileName string) error

	// LoadFromYAMLFile loads the context from the yamlFileName and try to unmarshal it as
	// YAML. If the yamlFileName is empty, nothing happens and the function immediately returns
	// nil. If the file doesn't exist, the function will return errors.NotExist error, otherwise
	// it will parse the contest and return nil if it could unmarshal it as YAML or the
	// unmarshalling YAML error.
	LoadFromYAMLFile(yamlFileName string) error

	// ApplyOther allows applying the T structure value by another enricher. The deep
	// apply will be done, which means that all fields from the enricher e, which are not
	// equal to its zero values will overwrite the values of the current enricher value.
	// It means e's non-zero values will overwrite the values from the current enricher
	ApplyOther(e Enricher[T]) error

	// ApplyEnvVariables will scan the existing environment variables and try to apply that
	// one, which name starts from prefix. The fields values will be separated by sep. The
	// variable will represent a path to the required value in the target structure.
	//
	// Example:
	// Inner struct {
	// 		Val int
	// 		StrPtr *string `json:"haha"`
	// }
	// T struct {
	// 	  	Field int
	//		InnerS *Inner
	// }
	// ...
	// The Enricher for the type T will allow to address the following fields with the following
	// format (separated by dots for example):
	//	- Field
	//  - InnerS.Val
	//  - Inners.StrPtr or Inners.haha (alias of Inners.StrPtr)
	//
	// To update them the following variables will make sense for the following call ApplyEnvVariables("MyServer", "_"):
	// 	- MYSERVER_FIELD
	//	- MYSERVER_INNERS_VAL
	//	- MYSERVER_INNERS_STRPTR or MYSERVER_INNERS_HAHA
	//
	// the environment variables are case-insensitive, so MYSERVER_FIELD and MyServer_fielD - will make sense.
	//
	// The variables values should be JSON values. For simple types like int or string, it can be normal value like
	// 123, "hello world" etc.
	// For complex types like slices, maps, structs, JSON format can be used. For example. above the following
	// variable makes sense:
	// MYSERVER_INNERS={"val":123, "haha": "hoho"}
	//
	// It maybe the case when a variable MYSERVER_INNERS_VAL will come before MYSERVER_INNERS, this case the
	// value set by the variable MYSERVER_INNERS_VAL will be overwritten. We consider the case corner
	// and the developers should avoid such kind of unambiguity.
	ApplyEnvVariables(prefix, sep string) error
	// ApplyKeyValues allows to apply the key-value pairs to the structure. The key-value pairs assignment rules
	// are the same as for the ApplyEnvVariables function.
	ApplyKeyValues(prefix, sep string, keyValues map[string]string)

	// Value returns the enricher current value
	Value() T
}

Enricher interface provides some helper functions to work with the configuration structures. It keeps a structure value by the type T and allows to load its value from a file, apply other values from other enricher, created for the same type T, and apply environment variables to the structure.

The following contract is applied to the type T:

• only the exported fields (started from the capital letter) will be updated
• the fields, may have JSON annotation, where the JSON field name value can be used as an alias, for example, FieldA int `json:"abc"` <- the field may be addressed either as "fieldA" or "abc"
• all the fields' names are case-insensitive, so values FIELDA, fielda, ABC, abc etc. will match to the fields in the previous example
• the reading from YAML files is defined by the same (JSON name) annotations

func NewEnricher

func NewEnricher[T any](val T) Enricher[T]

NewEnricher constructs new Enricher for the type T