vcl

package
v0.0.0-...-a47f6d0 Latest Latest
Warning

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

 Go to latest Published: Jul 12, 2024 License: BSD-2-Clause Imports: 14 Imported by: 0

README

GoDoc

Documentation

Overview

Package vcl encapsulates representations of a VCL configuration derived from Ingress and VarnishConfig specifications, and checking the representations for equivalence (to check if new syncs are necessary). It drives the templating that generates VCL source code.

Index

Constants

View Source 
const (
	// RecvHash to invoke cache lookup.
	RecvHash RecvReturn = "hash"
	// RecvPass to bypass cache lookup.
	RecvPass = "pass"
	// RecvPipe for pipe mode -- Varnish passes data between
	// client and backend with no further intervention.
	RecvPipe = "pipe"
	// RecvPurge to purge a cache object.
	// See: https://varnish-cache.org/docs/6.3/users-guide/purging.html?highlight=purge#http-purging
	RecvPurge = "purge"
	// RecvSynth to generate a synthetic response with a given
	// HTTP response status.
	RecvSynth = "synth"
	// RecvFail to invoke VCL failure.
	RecvFail = "fail"
	// RecvRestart to invoke request restart.
	RecvRestart = "restart"
)
View Source 
const NoMaskBits uint8 = 255

NoMaskBits is a sentinel value for ACLAddress.MaskBits indicating that a CIDR range is not to be used.

Variables

This section is empty.

Functions

func ResetACLTmpl 

func ResetACLTmpl()

ResetACLTmpl sets the VCL template for the VarnishConfig acl feature to its current "official" value. Invoked on TemplateConfig deletion, only needed when devmode is activated for the controller.

func ResetAuthTmpl 

func ResetAuthTmpl()

ResetAuthTmpl sets the VCL template for the VarnishConfig auth feature to its current "official" value. Invoked on TemplateConfig deletion, only needed when devmode is activated for the controller.

func ResetIngressTmpl 

func ResetIngressTmpl()

ResetIngressTmpl sets the VCL template for Ingress implementation (routing rules and bakend configuration) to its current "official" value. Invoked on TemplateConfig deletion, only needed when devmode is activated for the controller.

func ResetReqDispTmpl 

func ResetReqDispTmpl()

ResetReqDispTmpl sets the VCL template for the VarnishConfig reqDisp feature to its current "official" value. Invoked on TemplateConfig deletion, only needed when devmode is activated for the controller.

func ResetRewriteTmpl 

func ResetRewriteTmpl()

ResetRewriteTmpl sets the VCL template for the VarnishConfig rewrite feature to its current "official" value. Invoked on TemplateConfig deletion, only needed when devmode is activated for the controller.

func ResetShardTmpl 

func ResetShardTmpl()

ResetShardTmpl sets the VCL template for the VarnishConfig shard feature to its current "official" value. Invoked on TemplateConfig deletion, only needed when devmode is activated for the controller.

func SetACLTmpl 

func SetACLTmpl(src string) error

SetACLTmpl parses src as a text/template, using the FuncMap defined for the ACL template, which is used to generate VCL for the VarnishConfig acl feature. On success, the ACL template is replaced. If the parse fails, then the error is returned and the ACL template is unchanged.

Only used when devmode is activated for the controller.

func SetAuthTmpl 

func SetAuthTmpl(src string) error

SetAuthTmpl parses src as a text/template, using the FuncMap defined for the auth template, which is used to generate VCL for the VarnishConfig auth feature. On success, the auth template is replaced. If the parse fails, then the error is returned and the auth template is unchanged.

Only used when devmode is activated for the controller.

func SetIngressTmpl 

func SetIngressTmpl(src string) error

SetIngressTmpl parses src as a text/template, using the FuncMap defined for the ingress template, which is used to generate VCL for Ingress implementaion -- routing rules and backend configuration, including configuration set for the BackendConfig custom resource. On success, the ingress template is replaced. If the parse fails, then the error is returned and the shard template is unchanged.

Only used when devmode is activated for the controller.

func SetReqDispTmpl 

func SetReqDispTmpl(src string) error

SetReqDispTmpl parses src as a text/template, using the FuncMap defined for the reqDisp template, which is used to generate VCL for the VarnishConfig reqDisp feature. On success, the reqDisp template is replaced. If the parse fails, then the error is returned and the reqDisp template is unchanged.

Only used when devmode is activated for the controller.

func SetRewriteTmpl 

func SetRewriteTmpl(src string) error

SetRewriteTmpl parses src as a text/template, using the FuncMap defined for the rewrite template, which is used to generate VCL for the VarnishConfig rewrite feature. On success, the rewrite template is replaced. If the parse fails, then the error is returned and the rewrite template is unchanged.

Only used when devmode is activated for the controller.

func SetShardTmpl 

func SetShardTmpl(src string) error

SetShardTmpl parses src as a text/template, using the FuncMap defined for the shard template, which is used to generate VCL for the VarnishConfig shard feature. On success, the shard template is replaced. If the parse fails, then the error is returned and the shard template is unchanged.

Only used when devmode is activated for the controller.

Types

type ACL 

type ACL struct {
	Name       string
	Comparand  string
	FailStatus uint16
	Whitelist  bool
	Addresses  []ACLAddress
	Conditions []MatchTerm
	ResultHdr  ResultHdrType
}

ACL represents an Access Control List, derived from a VarnishConfig.

type ACLAddress 

type ACLAddress struct {
	Addr     string
	MaskBits uint8
	Negate   bool
}

ACLAddress represents an element in an ACL -- a host name to be resolved at VCL load, an IP address, or address range in CIDR notation. Use the '!' for negation when Negate is true.

type Address 

type Address struct {
	PodNamespace string
	PodName      string
	IP           string
	Port         int32
}

Address represents an endpoint for either a backend instance (Endpoint of a Service to which requests are routed) or a Varnish instance (where the port is the admin port).

func (Address) Address 

func (addr Address) Address() string

Address returns the network address represented by addr as "<IP>:<Port>"

func (Address) String 

func (addr Address) String() string

type AnchorType 

type AnchorType uint8

AnchorType classifies start-of-string and/or end-of-string anchoring for a regex match. 

const (
	// None indicates no anchoring.
	None AnchorType = iota
	// Start indicates anchoring at start-of-string.
	Start
	// Both indicates anchoring at start- and end-of-string.
	Both
)

type Auth 

type Auth struct {
	Conditions  []MatchTerm
	Credentials []string
	Realm       string
	Status      AuthStatus
	UTF8        bool
}

Auth specifies Basic or Proxy Authentication, derived from an AuthSpec in a VarnishConfig resource.

type AuthStatus 

type AuthStatus uint16

AuthStatus is the response code to be sent for authentication failures, and serves to distinguish the protocols. 

const (
	// Basic Authentication
	Basic AuthStatus = 401
	// Proxy Authentication
	Proxy = 407
)

type CompareType 

type CompareType uint8

CompareType classifies comparison operations performed for conditional configurations. The comparison may be negated if the boolean Negate field is true. 

const (
	// Equal specifies equality -- string equality, numeric
	// equality, or membership in a set of fixed strings.
	Equal CompareType = iota
	// Match specifies a regular expression match.
	Match
	// Prefix specifies that a string has a prefix in a set of
	// fixed strings.
	Prefix
	// Exists specifies that a request header exists.
	Exists
	// Greater specifies the > relation between a VCL variable
	// with a numeric value and a constant.
	Greater
	// GreaterEqual specifies the >= relation for a numeric VCL
	// variable and a constant.
	GreaterEqual
	// Less specifies the < relation for a numeric VCL variable
	// and a constant.
	Less
	// LessEqual specifies the <= relation for a numeric VCL
	// variable and a constant.
	LessEqual
)

type Condition 

type Condition struct {
	Values     []string
	MatchFlags MatchFlagsType
	Count      *uint
	Comparand  string
	Compare    CompareType
	Negate     bool
}

Condition specifies (one of) the conditions that must be true if a client request disposition is to be executed.

type Director 

type Director struct {
	Rampup     string
	Warmup     float64
	Type       DirectorType
	ShardParam string
}

Director is derived from spec.director in a BackendConfig, and allows for some choice of the director, and sets some parameters.

type DirectorType 

type DirectorType uint8

DirectorType corresponds to a class of director, see: https://varnish-cache.org/docs/6.3/reference/vmod_directors.generated.html 

const (
	// RoundRobin director
	RoundRobin DirectorType = iota
	// Random director
	Random
	// Shard director
	Shard
)

func GetDirectorType 

func GetDirectorType(dirStr string) DirectorType

GetDirectorType returns a DirectorType constant for the string (enum value) used in YAML.

func (DirectorType) String 

func (dirType DirectorType) String() string

type DispositionSpec 

type DispositionSpec struct {
	Conditions  []Condition
	Disposition DispositionType
}

DispositionSpec specifies the disposition of a client request when all of the Conditions are met.

type DispositionType 

type DispositionType struct {
	Action RecvReturn
	Status uint16
	Reason string
}

DispositionType specifies the disposition of a client request when associated Conditions are met.

Status is the HTTP response status to set when Action is RecvSynth; ignored for other values of Action.

type HashAlgo 

type HashAlgo uint8

HashAlgo identifies digest algorithms. 

const (
	// Crc32 checksum
	Crc32 HashAlgo = iota
	// ICrc32 CRC32 with inverted initialization and result
	ICrc32
	// MD5 message digest
	MD5
	// RS Sedgewick's hash
	RS
	// Sha1 secure hash
	Sha1
	// Sha224 secure hash
	Sha224
	// Sha384 secure hash
	Sha384
	// Sha512 secure hash
	Sha512
	// Sha3_224 secure hash
	Sha3_224
	// Sha3_256 secure hash
	Sha3_256
	// Sha3_512 secure hash
	Sha3_512
)

func (HashAlgo) String 

func (algo HashAlgo) String() string

type KeyBy 

type KeyBy uint8

KeyBy classifies the shard key method 

const (
	// ByHash is the default (shard director by=HASH)
	ByHash KeyBy = iota
	// URL by=URL
	URL
	// Key by=KEY
	Key
	// Blob by=BLOB
	Blob
	// Cookie by=KEY with a cookie value
	Cookie
)

type MatchFlagsType 

type MatchFlagsType struct {
	MaxMem        uint64
	Anchor        AnchorType
	UTF8          bool
	PosixSyntax   bool
	LongestMatch  bool
	Literal       bool
	NeverCapture  bool
	CaseSensitive bool
	PerlClasses   bool
	WordBoundary  bool
}

MatchFlagsType is a collection of options that modify matching operations. CaseSensitive can be applied to both fixed string matches and regex matches; the remainder are for regex matches only. These correspond to flags for RE2 matching, and are used by the RE2 VMOD.

See: https://code.uplex.de/uplex-varnish/libvmod-re2

type MatchTerm 

type MatchTerm struct {
	Comparand string
	Value     string
	Compare   CompareType
	Negate    bool
}

MatchTerm is a term describing the comparison of a VCL object with a pattern.

type MethodType 

type MethodType uint8

MethodType classifies the process by which a rewrite modifies the Target object. 

const (
	// Replace means that the target is overwritten with a new
	// value.
	Replace MethodType = iota
	// Sub means that the first matching substring of the target
	// after a regex match is substituted with the new value.
	Sub
	// Suball means that each non-overlapping matching substring
	// of the target is substituted.
	Suball
	// RewriteMethod means that the target is rewritten with the
	// rule in the Rewrite field, possibly with backreferences.
	RewriteMethod
	// Append means that a string is concatenated after the source
	// string, with the result written to the target.
	Append
	// Prepend means that a string is concatenated after the
	// source string.
	Prepend
	// Delete means that the target object is deleted.
	Delete
)

type NameTTLFrom 

type NameTTLFrom uint8

NameTTLFrom is a enumeration of the ways that the name TTL that was specified in the BackendConfig can be evaluated with respect to DNS TTL. This value is mapped directly to the ttl_from parameter for VMOD dynamic. 

const (
	// FromCfg corresponds to the enum value cfg in VMOD dynamic.
	FromCfg NameTTLFrom = iota
	// FromDNS corresponds to enum dns in VMOD dynamic
	FromDNS
	// FromMin corresponds to enum min in VMOD dynamic.
	FromMin
	// FromMax corresponds to enum max in VMOD dynamic.
	FromMax
)

func (NameTTLFrom) String 

func (from NameTTLFrom) String() string

type NameTTLSpec 

type NameTTLSpec struct {
	TTL  string
	From NameTTLFrom
}

NameTTLSpec encapsulates the TTL configuration used for VMOD dynamic. Its fields are mapped directly to the ttl and ttl_from paramater of the VMOD.

type PathKey 

type PathKey struct {
	Path string
	Type PathType
}

PathKey is a two-dimensional map key to map from paths and types to Services, derived from the paths field of an Ingress rule.

This is because it is possible in principle to have the same path with more than one pathType in an Ingress rule.

type PathType 

type PathType uint8

PathType is the classifier corresponding to the Ingress pathType field. 

const (
	// PathExact corresponds to Ingress pathType: Exact
	PathExact PathType = iota
	// PathPrefix corresponds to Ingress pathType: Prefix
	PathPrefix
	// PathImplSpecific corresponds to Ingress
	// pathType: ImplementationSpecfic
	PathImplSpecific
)

type Probe 

type Probe struct {
	URL         string
	Request     []string
	ExpResponse uint16
	Timeout     string
	Interval    string
	Initial     string
	Window      string
	Threshold   string
}

Probe represents the configuration of health probes derived from a VarnishConfig or BackendConfig Custom Resource.

type RecvReturn 

type RecvReturn string

RecvReturn is a name for the disposition of a client request. See: https://varnish-cache.org/docs/6.3/reference/states.html

type ResultHdrType 

type ResultHdrType struct {
	Header  string
	Success string
	Failure string
}

ResultHdrType describes the configuration for writing a header as the result of an ACL comparison. Header is the header to write in VCL notation. Failure is the value to write on the fail condition, Success the value to write otherwise.

type Rewrite 

type Rewrite struct {
	Rules      []RewriteRule
	MatchFlags MatchFlagsType
	Target     string
	Source     string
	Method     MethodType
	Compare    CompareType
	Negate     bool
	VCLSub     SubType
	Select     SelectType
}

Rewrite is the specification for a set of rewrite rules; elements of the Rewrites array of a VCL Spec have this type.

Target is the object to be rewritten, in VCL notation. It can be the client or backend URL path, or a client or backend request or response header.

Source is the object against which comparisons are applied, and from which substrings may be extracted. It may have the same values as Target.

type RewriteRule 

type RewriteRule struct {
	Value   string
	Rewrite string
}

RewriteRule describes conditions under which a rewrite is executed, and strings to be used for the rewrite. Elements of the Rules array for a Rewrite have this type.

Value is a string or pattern against which the Source object is compared. If Values is a regular expression, it has the syntax and semantics of RE2 (https://github.com/google/re2/wiki/Syntax).

Rewrite is a string to be used for the rewrite if the Value compares successfully. Depending on the RewriteSpec's Method, Rewrite may contain backreferences captured from a regex match.

type Rule 

type Rule struct {
	Host    string
	PathMap map[PathKey]Service
}

Rule represents an IngressRule: a Host name (possibly empty) and a map from URL paths to Services.

type SelectType 

type SelectType uint8

SelectType classifies the determination of the rewrite rule to apply if more than one of them in the Rules array compares successfully. This is only possible when the Method specifies a regex or prefix match.

The values Unique, First or Last may be used for both regex and prefix matches; the others may only be used for prefix matches. 

const (
	// Unique means that only one rewrite rule may match,
	// otherwise VCL failure is invoked.
	Unique SelectType = iota
	// First means that the first matching rule in the order of
	// the Rules array is executed.
	// Last means that the last matching rule is executed.
	First
	// Last means that the last matching rule is executed.
	Last
	// Exact means that, for a prefix match, the rule by which the
	// full string matched exactly is executed.
	Exact
	// Longest means that the rule for the longest prefix that
	// matched is executed.
	Longest
	// Shortest means that the rule for the shortest prefix that
	// matched is executed.
	Shortest
)

func (SelectType) String 

func (s SelectType) String() string

The String method returns the upper-case name of the enum used for VMOD re2.

type Service 

type Service struct {
	Name                string
	Addresses           []Address
	Probe               *Probe
	Director            *Director
	NameTTL             *NameTTLSpec
	Authority           *string
	ExternalName        string
	ExternalPort        string
	HostHeader          string
	ConnectTimeout      string
	FirstByteTimeout    string
	BetweenBytesTimeout string
	DNSRetryDelay       string
	DomainUsageTimeout  string
	FirstLookupTimeout  string
	ResolverIdleTimeout string
	ResolverTimeout     string
	MaxConnections      uint32
	MaxDNSQueries       uint16
	ProxyHeader         uint8
	FollowDNSRedirects  bool
	Via                 bool
}

Service represents either a backend Service (Endpoints to which requests are routed) or a Varnish Service (with addresses for the admin ports).

type ShardCluster 

type ShardCluster struct {
	Nodes           []Service
	Rules           []ShardRule
	Probe           *Probe
	MaxSecondaryTTL string
}

ShardCluster represents the configuration for self-sharding derived from the VarnishConfig Custom Resource.

type ShardRule 

type ShardRule struct {
	Conditions  []Condition
	DefaultKey  string
	Key         string
	By          KeyBy
	Algo        HashAlgo
	PrimaryOnly bool
}

ShardRule represents a sharding configuration, and optional conditions under which the configuration holds.

type Spec 

type Spec struct {
	// DefaultService corresponds to the default IngressBackend in
	// an Ingress, if present.
	DefaultService Service
	// Rules corresponds to the IngressRules in an Ingress.
	Rules []Rule
	// IntSvcs is a map of Service names to Service configurations
	// for in-cluster IngressBackends mentioned in an Ingress. May
	// include the default Backend.
	IntSvcs map[string]Service
	// ExtSvcs is a map of Service names to ExternalName Service
	// configurations that are IngressBackends mentioned in an
	// Ingress.
	ExtSvcs map[string]Service
	// ShardCluster is derived from the self-sharding
	// specification in a VarnishConfig resource.
	ShardCluster ShardCluster
	// Auths is a list of specifications for Basic or Proxy
	// Authentication, derived from the Auth section of a
	// VarnishConfig.
	Auths []Auth
	// VCL is custom VCL, derived from VarnishConfig.Spec.VCL.
	VCL string
	// ACLs is a list of specifications for whitelisting or
	// blacklisting IPs with access control lists, derived from
	// VarnishConfig.Spec.ACLs.
	ACLs []ACL
	// Rewrites is a list of specifications for header and URL
	// rewriting, derived from VarnishConfig.Spec.Rewrites.
	Rewrites []Rewrite
	// Dispositions is a list of specifications for the
	// disposition of client requests, derived from
	// VarnishConfig.Spec.ReqDispositions.
	Dispositions []DispositionSpec
}

Spec is the specification for a VCL configuration derived from Ingresses and VarnishConfig Custom Resources. This abstracts the VCL to be loaded by all instances of a Varnish Service.

func (Spec) Canonical 

func (spec Spec) Canonical() Spec

Canonical returns a canonical form of a Spec, in which all of its fields are ordered. This ensures that reflect.DeepEqual and DeepHash return values consistent with the equivalence of two Specs.

func (Spec) DeepHash 

func (spec Spec) DeepHash() string

DeepHash computes a alphanumerically encoded hash value from a Spec such that, almost certainly, two Specs are deeply equal iff their hash values are equal (unless we've discovered a SHA512 collision).

func (Spec) GetSrc 

func (spec Spec) GetSrc() (string, error)

GetSrc returns the VCL generated to implement a Spec.

type SubType 

type SubType uint8

SubType classifies the VCL subroutine in which a rewrite is executed. 

const (
	// Unspecified means that the VCL sub was not specified in the
	// user configuration, and will be inferred from the Source
	// and Target.
	Unspecified SubType = iota
	// Recv for vcl_recv
	Recv
	// Pipe for vcl_pipe
	Pipe
	// Pass for vcl_pass
	Pass
	// Hash for vcl_hash
	Hash
	// Purge for vcl_purge
	Purge
	// Miss for vcl_miss
	Miss
	// Hit for vcl_hit
	Hit
	// Deliver for vcl_deliver
	Deliver
	// Synth for vcl_synth
	Synth
	// BackendFetch for vcl_backend_fetch
	BackendFetch
	// BackendResponse for vcl_backend_response
	BackendResponse
	// BackendError for vcl_backend_error
	BackendError
)

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.