fields

package
v1.0.0-beta.8 Latest Latest
Warning

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

 Go to latest Published: Sep 17, 2026 License: MIT Imports: 6 Imported by: 0

Documentation

Overview

Package fields is the single source of truth for every configurable property of a managed NPM resource.

One table defines, per resource kind, the canonical label name, the spellings accepted as aliases (including the ones used by Redth/npm-docker-sync), the matching environment variable, the built-in default and the NPM/NPMplus API field it ends up in. Label parsing, the global defaults, the start-up log and the generated documentation all read from this table, so they cannot drift apart.

Index

Constants

View Source 
const (
	Enable  = "enable"
	Enabled = "enabled"

	Domains        = "domains"
	Certificate    = "certificate"
	SSLForced      = "ssl.forced"
	HTTP2          = "ssl.http2"
	HTTP3          = "ssl.http3"
	HSTS           = "ssl.hsts"
	HSTSSubdomains = "ssl.hsts_subdomains"
	AdvancedConfig = "advanced_config"

	LEEmail        = "letsencrypt.email"
	LEAgree        = "letsencrypt.agree"
	LEDNSChallenge = "letsencrypt.dns_challenge"
	LEDNSProvider  = "letsencrypt.dns_provider"
	LEDNSCreds     = "letsencrypt.dns_credentials" //nolint:gosec // field name, not a credential
	LEPropagation  = "letsencrypt.propagation_seconds"

	ForwardHost   = "forward_host"
	ForwardPort   = "forward_port"
	ForwardScheme = "forward_scheme"

	Websockets          = "websockets"
	Caching             = "caching"
	BlockExploits       = "block_exploits"
	TrustForwardedProto = "trust_forwarded_proto"
	AccessList          = "access_list"
	AccessListType      = "access_list_type"
	AuthRequest         = "auth_request"
	AuthRequestUpstream = "auth_request_upstream"
	LocationConfig      = "location_config"
	NoIndex             = "noindex"
	CrowdsecAppsec      = "crowdsec_appsec"
	RequestBuffering    = "request_buffering"
	ResponseBuffering   = "response_buffering"
	UpstreamCompression = "upstream_compression"
	FancyIndex          = "fancyindex"
	XFrameOptions       = "x_frame_options"
	Location            = "location"
	ResolveIP           = "resolve_ip"

	ForwardDomain = "forward_domain"
	HTTPCode      = "http_code"
	PreservePath  = "preserve_path"

	IncomingPort  = "incoming_port"
	TCP           = "tcp"
	UDP           = "udp"
	Protocol      = "protocol"
	ProxyProtocol = "proxy_protocol"
	ProxyTLS      = "proxy_tls"
	Description   = "description"
)

Canonical field names. Referencing them as constants keeps the parser and the table honest about spelling.

View Source 
const Auto = "auto"

Auto is the default value of every field whose built-in default is derived at runtime (the certificate, the upstream port, ssl_forced).

Variables

View Source 
var (
	// SchemeValues are the upstream schemes NPMplus accepts. Upstream NPM
	// only knows http and https, which payloads.go enforces.
	SchemeValues = []string{"http", "https", "grpc", "grpcs"}
	// RedirectSchemeValues are the schemes of a redirection host.
	RedirectSchemeValues = []string{"auto", "http", "https"}
	// AuthRequestValues are the NPMplus forward-auth integrations.
	AuthRequestValues = []string{
		"none", "anubis", "tinyauth", "oauth2proxy", "voidauth",
		"authelia", "authentik", "authentik-send-basic-auth",
	}
	// XFrameOptionsValues are the accepted X-Frame-Options settings. They are
	// matched case-insensitively and written back in NPMplus' spelling.
	XFrameOptionsValues = []string{"deny", "sameorigin", "upstream", "none"}
	// AccessListTypeValues are the access list modes of a proxy host.
	AccessListTypeValues = []string{"public", "custom"}
	// LocationAccessListTypeValues additionally allow inheriting from the host.
	LocationAccessListTypeValues = []string{"global", "public", "custom"}
	// LocationTypeValues are the nginx location modifiers.
	LocationTypeValues = []string{"prefix", "exact", "regex", "iregex", "prefer", "named"}
	// ProxyProtocolValues are the stream PROXY protocol versions.
	ProxyProtocolValues = []string{"off", "v1", "v2"}
	// StreamProtocolValues are the transport shorthands of a stream.
	StreamProtocolValues = []string{"tcp", "udp", "both"}
)

Enum values.

View Source 
var DefaultPortPreference = []int{80, 8080, 3000, 8000, 443}

DefaultPortPreference is the order in which an exposed container port is picked when a container exposes several of them (NPM_PORT_PREFERENCE).

View Source 
var LocationFields = []Field{
	{Name: "path", Type: TypeString, APIField: "path", Doc: "location path (required)"},
	{
		Name: "type", Aliases: []string{"location_type", "modifier"},
		Type: TypeEnum, Enum: LocationTypeValues, Default: "prefix", APIField: "location_type", Plus: true,
		Doc: "prefix, exact, regex, iregex, prefer or named",
	},
	{Name: ForwardHost, Aliases: []string{"host", "upstream"}, Type: TypeString, APIField: "forward_host", Doc: "upstream address; inherited from the host"},
	{Name: ForwardPort, Aliases: []string{"port"}, Type: TypePort, APIField: "forward_port", Doc: "upstream port; inherited from the host"},
	{Name: ForwardScheme, Aliases: []string{"scheme"}, Type: TypeEnum, Enum: SchemeValues, APIField: "forward_scheme", Doc: "upstream scheme; inherited from the host"},
	{Name: AdvancedConfig, Aliases: []string{"advanced", "advanced.config"}, Type: TypeString, APIField: "advanced_config", Doc: "nginx snippet for this location"},
	{Name: LocationConfig, Type: TypeString, APIField: "npmplus_location_config", Plus: true, Doc: "nginx snippet inside the location block"},
	{Name: AccessList, Aliases: []string{"access_list_id", "access_list_ids", "access_lists", "accesslist"}, Type: TypeList, APIField: "npmplus_access_list_ids", Plus: true, Doc: "access list ids or names"},
	{Name: AccessListType, Type: TypeEnum, Enum: LocationAccessListTypeValues, APIField: "npmplus_access_list_type", Plus: true, Doc: "global, public or custom"},
	{Name: Enabled, Aliases: []string{Enable}, Type: TypeBool, Default: "true", APIField: "npmplus_enabled", Plus: true, Doc: "disable a single location"},
	{Name: NoIndex, Type: TypeBool, APIField: "npmplus_noindex", Plus: true, Doc: "inherited from the host"},
	{Name: CrowdsecAppsec, Aliases: []string{"crowdsec", "appsec"}, Type: TypeBool, APIField: "npmplus_crowdsec_appsec", Plus: true, Invert: true, Doc: "inherited from the host"},
	{Name: RequestBuffering, Type: TypeBool, APIField: "npmplus_proxy_request_buffering", Plus: true, Invert: true, Doc: "inherited from the host"},
	{Name: ResponseBuffering, Type: TypeBool, APIField: "npmplus_proxy_response_buffering", Plus: true, Invert: true, Doc: "inherited from the host"},
	{Name: UpstreamCompression, Aliases: []string{"compression"}, Type: TypeBool, APIField: "npmplus_upstream_compression", Plus: true, Doc: "inherited from the host"},
	{Name: FancyIndex, Aliases: []string{"fancy_index"}, Type: TypeBool, APIField: "npmplus_fancyindex", Plus: true, Doc: "inherited from the host"},
	{Name: XFrameOptions, Aliases: []string{"xframe_options"}, Type: TypeEnum, Enum: XFrameOptionsValues, APIField: "npmplus_x_frame_options", Plus: true, Doc: "inherited from the host"},
	{Name: AuthRequest, Aliases: []string{"auth"}, Type: TypeEnum, Enum: AuthRequestValues, APIField: "npmplus_auth_request", Plus: true, Doc: "inherited from the host"},
	{Name: AuthRequestUpstream, Type: TypeString, APIField: "npmplus_auth_request_upstream", Plus: true, Doc: "inherited from the host"},
}

LocationFields are the fields a custom location block accepts. They are the per-location subset of the proxy fields plus the location's own path and type.

View Source 
var Table = map[npm.Kind][]Field{
	npm.KindProxy:    proxyFields(),
	npm.KindRedirect: redirectFields(),
	npm.KindStream:   streamFields(),
	npm.KindDead:     deadFields(),
}

Table is the field table, one entry per resource kind. Location blocks reuse the proxy entries through LocationFields.

Functions

func EnvNames 

func EnvNames(kind npm.Kind, f Field) []string

EnvNames returns the environment variables that set the field's default, strongest first: the kind specific ones (canonical spelling first, then the aliases) followed by the cross-kind NPM_DEFAULT_* ones.

func IsInverseAlias 

func IsInverseAlias(name string) (string, bool)

IsInverseAlias reports whether name is the explicit "disable_x" spelling of an inverted field, and returns the canonical field name.

func Kinds 

func Kinds() []npm.Kind

Kinds returns the resource kinds in their canonical order.

func Markdown 

func Markdown() string

Markdown renders the whole field table as documentation.

docs/FIELDS.md is generated from this and checked in CI, so the label reference, the environment variables and the built-in defaults can never drift apart from what the parser actually does.

func Normalize 

func Normalize(name string) string

Normalize exposes the label-name normalisation used for lookups.

func ParseBool 

func ParseBool(raw string) (bool, error)

ParseBool accepts the usual strconv values plus the human friendly yes/no/on/off spellings commonly used in Docker labels.

func Suggest 

func Suggest(kind npm.Kind, name string) string

Suggest returns the closest known field name for a misspelling, or "" when nothing is close enough. It powers the "did you mean" hint for unknown labels.

func SuggestLocation 

func SuggestLocation(name string) string

SuggestLocation is Suggest for location fields.

Types

type Defaults 

type Defaults struct {
	// contains filtered or unexported fields
}

Defaults holds the effective default of every field, together with where it came from. It is nil-safe: the zero value serves the built-in defaults.

func LoadDefaults 

func LoadDefaults(getenv func(string) string, environ []string) (*Defaults, []string, error)

LoadDefaults resolves the default of every field from the environment. environ is the process environment (os.Environ()) and is only used to warn about variables that look like a field default but match no field.

func (*Defaults) Entries 

func (d *Defaults) Entries() []Entry

Entries returns every effective default, sorted by kind and field. Used for the start-up log and the generated documentation.

func (*Defaults) FromEnv 

func (d *Defaults) FromEnv() []Entry

FromEnv returns only the defaults that the environment changed.

func (*Defaults) Source 

func (d *Defaults) Source(kind npm.Kind, field string) string

Source returns where the effective default came from ("builtin" or the environment variable name).

func (*Defaults) Value 

func (d *Defaults) Value(kind npm.Kind, field string) string

Value returns the effective default of a field.

type Entry 

type Entry struct {
	Kind   npm.Kind
	Field  string
	Value  string
	Source string // "builtin" or the environment variable name
}

Entry is one row of the effective-defaults table.

type Field 

type Field struct {
	// Name is the canonical label spelling, e.g. "ssl.hsts_subdomains".
	Name string
	// Aliases are additional accepted spellings. They also produce
	// environment variable aliases, which is how the Redth names
	// (NPM_PROXY_SSL_FORCE, NPM_PROXY_HSTS_SUBDOMAINS, ...) keep working.
	Aliases []string
	// Type is the value domain.
	Type Type
	// Enum lists the accepted values of a TypeEnum field (lower case).
	Enum []string
	// Default is the built-in default, "" meaning "unset".
	Default string
	// APIField is the NPM/NPMplus property the value is written to.
	APIField string
	// Plus marks a field that only exists on NPMplus.
	Plus bool
	// Invert marks a field whose API property has the opposite meaning
	// ("crowdsec_appsec: true" writes npmplus_crowdsec_appsec: false).
	Invert bool
	// Doc is the one line description used by the generated field table.
	Doc string
}

Field describes one configurable property.

func List 

func List(kind npm.Kind) []Field

List returns the fields of a kind sorted by canonical name.

func Lookup 

func Lookup(kind npm.Kind, name string) (Field, bool)

Lookup resolves a label field name (any accepted spelling) for a kind.

func LookupLocation 

func LookupLocation(name string) (Field, bool)

LookupLocation resolves a field name inside a location block.

func (Field) EnumHint 

func (f Field) EnumHint() string

EnumHint renders the accepted values of an enum field for an error message.

func (Field) Parse 

func (f Field) Parse(raw string) (string, error)

Parse validates and canonicalises a raw value for the field. It is used for environment defaults; label values go through the same rules in the parser.

func (Field) ValidateEnum 

func (f Field) ValidateEnum(value string) (string, error)

ValidateEnum matches a value against the field's enum, case-insensitively.

type Type 

type Type int

Type is the value domain of a field. It decides how a label value is parsed and which values the documentation advertises. 

const (
	TypeString Type = iota
	TypeBool
	TypeInt
	TypePort
	TypeEnum
	TypeDomains
	TypeList
	TypeCertificate
)

The supported value domains.

func (Type) String 

func (t Type) String() string

String implements fmt.Stringer and doubles as the documented value domain.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.