repoconfig

package
v0.22.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 18, 2026 License: Apache-2.0 Imports: 14 Imported by: 0

Documentation

Overview

Package repoconfig is a repo's settings, as .anfra/config.yml holds them: what each setting is, how a file is read, and how the layers that set them (the file, a member's .anfra/config.local.yml, a platform's overrides) are laid over each other. anfra core owns it, as it owns the repo format; anfra-cloud imports it, so the CLI and every host read settings alike.

A setting is a field of Config that isn't a mapping: a scalar, or a list, which is one value. Its Key is the path to it, spelled as the file spells it. What a layer sets is a list of Settings, each one setting's key and its value as JSON, which Layer applies over anfra's defaults.

Index

Constants

View Source
const (
	// FormatDuration is a Go duration: 30s, 10m, 2h.
	FormatDuration = "duration"
	// FormatTimezone is an IANA time zone that anfra knows: Asia/Ho_Chi_Minh.
	FormatTimezone = "timezone"
	// FormatOrigin is an https origin a content policy takes
	// (repoformat.CheckOrigin).
	FormatOrigin = "origin"
)

The formats a Spec names, each one check.

View Source
const FilePath = repoformat.ConfigFile

FilePath is the settings file, relative to the repo's root: committed, and published with the repo (repoformat.Publishable).

View Source
const LocalFilePath = ".anfra/config.local.yml"

LocalFilePath is a member's own settings, relative to the repo's root, laid over FilePath's on their machine only: never committed or published.

View Source
const MaxOrigins = 20

MaxOrigins is the most origins apps.allow_origins may list: each is one more server whose code runs beside readers' query results.

Variables

This section is empty.

Functions

func Equal

func Equal(k Key, a, b jsontext.Value) bool

Equal reports whether a and b, two values of the setting k as JSON, mean the same (Diff): nil is unset, anfra's default. A value k doesn't take equals nothing but itself.

func JSONSchema

func JSONSchema() map[string]any

JSONSchema is the settings file's JSON Schema (2020-12): every setting's type, default, allowed values and description, from its Spec, under the mappings it sits in, none admitting a key it doesn't know. A format anfra checks that JSON Schema has no keyword for is x-anfra-format, with a pattern where one fits, so an editor checks what it can.

func Layer

func Layer(layers ...[]Setting) (Config, []BrokenSetting)

Layer is anfra's defaults with each list of settings applied over them, key by key, a later list winning: the repo's file, then a member's own file; or the repo's settings, then a platform's overrides. A setting whose key names none, or holds a value its setting doesn't take, is returned as broken and not applied, so its key keeps its value from the layers below. Layer doesn't check how the settings go together: Check the result.

func SettingSchema

func SettingSchema(k Key) map[string]any

SettingSchema is the JSON Schema of the setting k's value: nil when k names no setting.

Types

type BrokenSetting

type BrokenSetting struct {
	Setting
	Err error
}

BrokenSetting is a setting Layer didn't apply, and why: a key anfra doesn't know, or a value that key doesn't take.

type Config

type Config struct {
	Org struct {
		// URL is the org `anfra publish` publishes the repo to, by its address on
		// its server. Never a credential. A platform ignores it (Key.Local).
		URL string `yaml:"url"`
	} `yaml:"org"`
	Apps struct {
		// AllowOrigins are the origins the repo's Data Apps may load from beyond
		// the SDK's own CDNs, each passing repoformat.CheckOrigin, at most
		// MaxOrigins.
		AllowOrigins []string `yaml:"allow_origins"`
	} `yaml:"apps"`
	// Query is how the repo's queries run (docs/designs/query-settings.md).
	Query struct {
		// Default is what a query gets when it sets none: each key is the path
		// of the query's own field, in snake_case. Unset, anfra's own default.
		Default struct {
			Input struct {
				// Timezone is input.timezone's default, an IANA zone.
				Timezone string `yaml:"timezone"`
				// WeekStartDay is input.weekStartDay's default: monday to sunday.
				WeekStartDay string `yaml:"weekStartDay"`
			} `yaml:"input"`
			Cache struct {
				// Duration is cache.duration's default: how old a cached result
				// a query accepts, and how long the result it caches is kept.
				// Unset, a query that sets none doesn't use the cache.
				Duration string `yaml:"duration"`
			} `yaml:"cache"`
		} `yaml:"default"`
		// LockedDefaults are the paths of the defaults a query can't change, such
		// as input.weekStartDay. Each names a value Default sets.
		LockedDefaults []string `yaml:"locked_defaults"`
		Cache          struct {
			// Enabled turns the query cache off for the repo when false: no
			// store, no canal-lake. Unset is on.
			Enabled *bool `yaml:"enabled"`
			// MaxDuration is the longest a query's result may be cached, at most
			// querycache.MaxDuration, which it is when unset.
			MaxDuration string `yaml:"max_duration"`
		} `yaml:"cache"`
	} `yaml:"query"`
	// AQL is how the repo's AQL compiles.
	AQL struct {
		Compiler struct {
			// Version is the AQL compiler the repo's AQL compiles and type-checks
			// with: "v1" (also when unset) or "v2".
			Version string `yaml:"version"`
		} `yaml:"compiler"`
	} `yaml:"aql"`
}

Config is a repo's settings. Its fields are the settings anfra knows: a key in a file that has no field here is refused, never ignored. The zero value is anfra's defaults.

func Parse

func Parse(file string, content []byte) (Config, error)

Parse reads a settings file's content: what it sets, laid over anfra's defaults, and checked as a whole. file names it in errors, as .anfra/config.yml. Empty content, or comments only, is anfra's defaults.

func (Config) AllowedOrigins

func (c Config) AllowedOrigins() []string

AllowedOrigins is apps.allow_origins, each an origin a Data App's content policy can take: Check checked them.

func (Config) Check

func (c Config) Check() error

Check refuses settings no repo can run with: a value anfra doesn't take, or settings that contradict each other, such as a default cache duration over the cap. Each error names the setting and how to fix it. A host checks the settings in effect with it, after Layer.

func (Config) Get

func (c Config) Get(k Key) jsontext.Value

Get is k's value in c, as JSON, as a file would hold it: nil when c leaves it unset, which is anfra's default, or when k names no setting.

func (Config) QueryCacheEnabled

func (c Config) QueryCacheEnabled() bool

QueryCacheEnabled is query.cache.enabled: on unless the repo sets false.

func (Config) QueryCacheSettings

func (c Config) QueryCacheSettings() command.QueryCacheSettings

QueryCacheSettings are query.cache's rules the engine takes: its cap, zero when unset. Whether the cache is off is the host's to decide, since the environment can override the file. Check checked them.

func (Config) QueryDefaults

func (c Config) QueryDefaults() command.QueryDefaults

QueryDefaults are query.default and query.locked_defaults, as the engine takes them: the one place settings become a query's defaults. Check checked them.

func (Config) UseV2Compiler

func (c Config) UseV2Compiler() bool

UseV2Compiler is whether the repo's AQL compiles and type-checks with the AQL v2 compiler: aql.compiler.version is v2.

type Key

type Key string

Key is a setting's path in the settings: the names on the way to it, spelled as the file spells them, joined with ".", such as query.default.input.weekStartDay. No name in a key holds a ".", so the dotted form is exact, with no quoting, wherever a key is stored, sent or shown. A setting keyed by names users choose (none yet) refuses a name with a ".".

func Diff

func Diff(a, b Config) []Key

Diff is the settings whose values differ between a and b, in Keys' order, leaving out the folder's own (Key.Local). It compares what each setting means, not how it's written: a setting at anfra's default equals one not set, and 60m equals 1h. A list's order counts.

func GroupOf

func GroupOf(k Key) Key

GroupOf is the mapping the setting k is shown under (Spec.Group).

func Keys

func Keys() []Key

Keys is every setting anfra knows, in Config's order.

func LockedKey

func LockedKey(entry string) Key

LockedKey is the key a query.locked_defaults entry locks: its path under query.default, such as input.weekStartDay for query.default.input.weekStartDay.

func ParseKey

func ParseKey(s string) (Key, error)

ParseKey reads a key, refusing one with an empty name.

func (Key) Local

func (k Key) Local() bool

Local reports whether k is about the folder rather than the repo, such as org.url, which says where a folder publishes: a platform ignores it.

func (Key) Segments

func (k Key) Segments() []string

Segments are the key's names, in order.

func (Key) String

func (k Key) String() string

String is the key as people read it.

func (Key) Within

func (k Key) Within(prefix Key) bool

Within reports whether k is prefix or a setting under it, name by name: so aql covers aql.compiler.version, and not aqlx.

type Setting

type Setting struct {
	Key   Key
	Value jsontext.Value
}

Setting is one setting's value, as one layer sets it: its key, and its value as JSON, as the file would hold it.

func ParseSettings

func ParseSettings(file string, content []byte) ([]Setting, error)

ParseSettings is what a settings file's content sets, one per setting it names, in the file's order, each value checked on its own. It refuses a key anfra doesn't know (an UnknownKeyError), a setting with no value, one set twice, and a value its setting doesn't take. It doesn't check how the settings go together: Layer them, then Check.

type Spec

type Spec struct {
	// Label names the setting for people: "Time zone".
	Label string
	// Description says what it does: one sentence with no end period, or
	// several, each with its own.
	Description string
	// Default is the value anfra uses when nothing sets it, as the file would
	// hold it; nil when there's none, such as no default cache duration.
	Default any
	// Enum is the values a string takes, or a list's items take.
	Enum []string
	// Format names the check a string's value, or a list's items, pass beyond
	// its type: FormatDuration, FormatTimezone, FormatOrigin. "" for none.
	Format string
	// MaxDuration is the longest a FormatDuration value may be; zero, no cap.
	MaxDuration time.Duration
	// MaxItems is the most items a list holds; zero, no limit.
	MaxItems int
	// Group is the mapping the setting is shown under, for people: by default
	// its key's first two names (query.default for
	// query.default.input.timezone), or its first for a key of two. Set for a
	// setting that belongs with others than its key's, as query.locked_defaults
	// with the defaults it locks.
	Group Key
}

Spec is one setting as anfra defines it: what it's called and does, the value anfra uses when nothing sets it, and the values it takes. The checks enforce what it says (checkValues reads Enum, Format and MaxItems, Diff reads Default), and JSONSchema publishes it, so what a client reads is what anfra refuses. Rules across settings, such as a default over the cap, aren't a setting's: Check holds them, and a client learns of them from its error.

func SpecOf

func SpecOf(k Key) (Spec, bool)

SpecOf is the setting k's Spec, ok false when k names no setting.

type UnknownKeyError

type UnknownKeyError struct {
	// File names the file the key is in, as messages name it.
	File string
	// Line is the key's line in File, or 0 when it isn't from a file.
	Line  int
	Key   Key
	Near  string
	Known []string
}

UnknownKeyError is a key the settings have no such setting for. Near is the key meant, when one is close; Known are the settings beside it.

func AsUnknownKey

func AsUnknownKey(err error) (*UnknownKeyError, bool)

AsUnknownKey is err's UnknownKeyError, if it is one.

func (*UnknownKeyError) Error

func (e *UnknownKeyError) Error() string

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL