httpkenginefile

Documentation

Index

• func ParseSegmentAsSubroute(h Helper) (kenginehttp.MiddlewareHandler, error)
• func RegisterDirective(dir string, setupFunc UnmarshalFunc)
• func RegisterDirectiveOrder(dir string, position Positional, standardDir string)
• func RegisterGlobalOption(opt string, setupFunc UnmarshalGlobalFunc)
• func RegisterHandlerDirective(dir string, setupFunc UnmarshalHandlerFunc)
• func WasReplacedPlaceholderShorthand(token string) string
• type Address
  • func ParseAddress(str string) (Address, error)
  • func (a Address) Normalize() Address
  • func (a Address) String() string
• type App
• type ComplexShorthandReplacer
• type ConfigValue
• type Helper
  • func (h Helper) ExtractMatcherSet() (kengine.ModuleMap, error)
  • func (h Helper) GroupRoutes(vals []ConfigValue)
  • func (h Helper) JSON(val any) json.RawMessage
  • func (h Helper) Kenginefiles() []string
  • func (h Helper) MatcherToken() (kengine.ModuleMap, bool, error)
  • func (h Helper) NewRoute(matcherSet kengine.ModuleMap, handler kenginehttp.MiddlewareHandler) []ConfigValue
  • func (h Helper) Option(name string) any
  • func (h Helper) WithDispenser(d *kenginefile.Dispenser) Helper
• type Positional
• type ServerType
  • func (st ServerType) Setup(inputServerBlocks []kenginefile.ServerBlock, options map[string]any) (*kengine.Config, []kengineconfig.Warning, error)
• type ShorthandReplacer
  • func NewShorthandReplacer() ShorthandReplacer
  • func (s ShorthandReplacer) ApplyToSegment(segment *kenginefile.Segment)
• type UnmarshalFunc
• type UnmarshalGlobalFunc
• type UnmarshalHandlerFunc

Functions

func ParseSegmentAsSubroute

func ParseSegmentAsSubroute(h Helper) (kenginehttp.MiddlewareHandler, error)

ParseSegmentAsSubroute parses the segment such that its subdirectives are themselves treated as directives, from which a subroute is built and returned.

func RegisterDirective

func RegisterDirective(dir string, setupFunc UnmarshalFunc)

RegisterDirective registers a unique directive dir with an associated unmarshaling (setup) function. When directive dir is encountered in a Kenginefile, setupFunc will be called to unmarshal its tokens.

func RegisterDirectiveOrder

func RegisterDirectiveOrder(dir string, position Positional, standardDir string)

RegisterDirectiveOrder registers the default order for a directive from a plugin.

This is useful when a plugin has a well-understood place it should run in the middleware pipeline, and it allows users to avoid having to define the order themselves.

The directive dir may be placed in the position relative to ('before' or 'after') a directive included in Kengine's standard distribution. It cannot be relative to another plugin's directive.

EXPERIMENTAL: This API may change or be removed.

func RegisterGlobalOption

func RegisterGlobalOption(opt string, setupFunc UnmarshalGlobalFunc)

RegisterGlobalOption registers a unique global option opt with an associated unmarshaling (setup) function. When the global option opt is encountered in a Kenginefile, setupFunc will be called to unmarshal its tokens.

func RegisterHandlerDirective

func RegisterHandlerDirective(dir string, setupFunc UnmarshalHandlerFunc)

RegisterHandlerDirective is like RegisterDirective, but for directives which specifically output only an HTTP handler. Directives registered with this function will always have an optional matcher token as the first argument.

func WasReplacedPlaceholderShorthand

func WasReplacedPlaceholderShorthand(token string) string

WasReplacedPlaceholderShorthand checks if a token string was likely a replaced shorthand of the known Kenginefile placeholder replacement outputs. Useful to prevent some user-defined map output destinations from overlapping with one of the predefined shorthands.

Types

type Address

type Address struct {
	Original, Scheme, Host, Port, Path string
}

Address represents a site address. It contains the original input value, and the component parts of an address. The component parts may be updated to the correct values as setup proceeds, but the original value should never be changed.

The Host field must be in a normalized form.

func ParseAddress

func ParseAddress(str string) (Address, error)

ParseAddress parses an address string into a structured format with separate scheme, host, port, and path portions, as well as the original input string.

func (Address) Normalize

func (a Address) Normalize() Address

Normalize returns a normalized version of a.

func (Address) String

func (a Address) String() string

String returns a human-readable form of a. It will be a cleaned-up and filled-out URL string.

type App

type App struct {
	// The JSON key for the app being configured
	Name string

	// The raw app config as JSON
	Value json.RawMessage
}

App represents the configuration for a non-standard Kengine app module (e.g. third-party plugin) which was parsed from a global options block.

type ComplexShorthandReplacer

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

type ConfigValue

type ConfigValue struct {
	// The kind of value this is. As the config is
	// being built, the adapter will look in the
	// "pile" for values belonging to a certain
	// class when it is setting up a certain part
	// of the config. The associated value will be
	// type-asserted and placed accordingly.
	Class string

	// The value to be used when building the config.
	// Generally its type is associated with the
	// name of the Class.
	Value any
	// contains filtered or unexported fields
}

ConfigValue represents a value to be added to the final configuration, or a value to be consulted when building the final configuration.

type Helper

type Helper struct {
	*kenginefile.Dispenser
	// State stores intermediate variables during kenginefile adaptation.
	State map[string]any
	// contains filtered or unexported fields
}

Helper is a type which helps setup a value from Kenginefile tokens.

func (Helper) ExtractMatcherSet

func (h Helper) ExtractMatcherSet() (kengine.ModuleMap, error)

ExtractMatcherSet is like MatcherToken, except this is a higher-level method that returns the matcher set described by the matcher token, or nil if there is none, and deletes the matcher token from the dispenser and resets it as if this look-ahead never happened. Useful when wrapping a route (one or more handlers) in a user-defined matcher.

func (Helper) GroupRoutes

func (h Helper) GroupRoutes(vals []ConfigValue)

GroupRoutes adds the routes (kenginehttp.Route type) in vals to the same group, if there is more than one route in vals.

func (Helper) JSON

func (h Helper) JSON(val any) json.RawMessage

JSON converts val into JSON. Any errors are added to warnings.

func (Helper) Kenginefiles

func (h Helper) Kenginefiles() []string

Kenginefiles returns the list of config files from which tokens in the current server block were loaded.

func (Helper) MatcherToken

func (h Helper) MatcherToken() (kengine.ModuleMap, bool, error)

MatcherToken assumes the next argument token is (possibly) a matcher, and if so, returns the matcher set along with a true value. If the next token is not a matcher, nil and false is returned. Note that a true value may be returned with a nil matcher set if it is a catch-all.

func (Helper) NewRoute

func (h Helper) NewRoute(matcherSet kengine.ModuleMap,
	handler kenginehttp.MiddlewareHandler,
) []ConfigValue

NewRoute returns config values relevant to creating a new HTTP route.

func (Helper) Option

func (h Helper) Option(name string) any

Option gets the option keyed by name.

func (Helper) WithDispenser

func (h Helper) WithDispenser(d *kenginefile.Dispenser) Helper

WithDispenser returns a new instance based on d. All others Helper fields are copied, so typically maps are shared with this new instance.

type Positional

type Positional string

Positional are the supported modes for ordering directives.

const (
	Before Positional = "before"
	After  Positional = "after"
	First  Positional = "first"
	Last   Positional = "last"
)

type ServerType

type ServerType struct{}

ServerType can set up a config from an HTTP Kenginefile.

func (ServerType) Setup

func (st ServerType) Setup(
	inputServerBlocks []kenginefile.ServerBlock,
	options map[string]any,
) (*kengine.Config, []kengineconfig.Warning, error)

Setup makes a config from the tokens.

type ShorthandReplacer

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

func NewShorthandReplacer

func NewShorthandReplacer() ShorthandReplacer

func (ShorthandReplacer) ApplyToSegment

func (s ShorthandReplacer) ApplyToSegment(segment *kenginefile.Segment)

ApplyToSegment replaces shorthand placeholder to its full placeholder, understandable by Kengine.

type UnmarshalFunc

type UnmarshalFunc func(h Helper) ([]ConfigValue, error)

UnmarshalFunc is a function which can unmarshal Kenginefile tokens into zero or more config values using a Helper type. These are passed in a call to RegisterDirective.

type UnmarshalGlobalFunc

type UnmarshalGlobalFunc func(d *kenginefile.Dispenser, existingVal any) (any, error)

UnmarshalGlobalFunc is a function which can unmarshal Kenginefile tokens from a global option. It is passed the tokens to parse and existing value from the previous instance of this global option (if any). It returns the value to associate with this global option.

type UnmarshalHandlerFunc

type UnmarshalHandlerFunc func(h Helper) (kenginehttp.MiddlewareHandler, error)

UnmarshalHandlerFunc is like UnmarshalFunc, except the output of the unmarshaling is an HTTP handler. This function does not need to deal with HTTP request matching which is abstracted away. Since writing HTTP handlers with Kenginefile support is very common, this is a more convenient way to add a handler to the chain since a lot of the details common to HTTP handlers are taken care of for you. These are passed to a call to RegisterHandlerDirective.