Documentation
¶
Index ¶
- Constants
- Variables
- func ParseNetworks(networks []string) (ipNets []netip.Prefix, err error)
- type App
- type ConnMatcher
- type Connection
- func (cx *Connection) GetVar(key string) interface{}
- func (cx *Connection) MatchingBytes() []byte
- func (cx *Connection) Read(p []byte) (n int, err error)
- func (cx *Connection) SetVar(key string, value interface{})
- func (cx *Connection) Wrap(conn net.Conn) *Connection
- func (cx *Connection) Write(p []byte) (n int, err error)
- type Handler
- type HandlerFunc
- type Handlers
- type ListenerWrapper
- type MatchIP
- type MatchLocalIP
- type MatchNot
- type MatcherSet
- type MatcherSets
- type Middleware
- type NextHandler
- type NextHandlerFunc
- type RawMatcherSets
- type Route
- type RouteList
- type Server
Constants ¶
const MatchingTimeoutDefault = 3 * time.Second
const MaxMatchingBytes = 8 * 1024
MaxMatchingBytes is the amount of bytes that are at most prefetched during matching. This is probably most relevant for the http matcher since http requests do not have a size limit. 8 KiB should cover most use-cases and is similar to popular webservers.
Variables ¶
var ( // VarsCtxKey is the key used to store the variables table // in a Connection's context. VarsCtxKey caddy.CtxKey = "vars" // ReplacerCtxKey is the key used to store the replacer. ReplacerCtxKey caddy.CtxKey = "replacer" )
var ErrConsumedAllPrefetchedBytes = errors.New("consumed all prefetched bytes")
var ErrMatchingBufferFull = errors.New("matching buffer is full")
var ErrMatchingTimeout = errors.New("aborted matching according to timeout")
Functions ¶
Types ¶
type App ¶
type App struct {
// Servers are the servers to create. The key of each server must be
// a unique name identifying the server for your own convenience;
// the order of servers does not matter.
Servers map[string]*Server `json:"servers,omitempty"`
// contains filtered or unexported fields
}
App is a Caddy app that operates closest to layer 4 of the OSI model.
func (App) CaddyModule ¶
func (App) CaddyModule() caddy.ModuleInfo
CaddyModule returns the Caddy module information.
type ConnMatcher ¶
type ConnMatcher interface {
// Match returns true if the given connection matches.
// It should read from the connection as little as possible:
// only as much as necessary to determine a match.
Match(*Connection) (bool, error)
}
ConnMatcher is a type that can match a connection.
type Connection ¶
type Connection struct {
// The underlying connection.
net.Conn
// The context for the connection.
Context context.Context
Logger *zap.Logger
// contains filtered or unexported fields
}
Connection contains information about the connection as it passes through various handlers. It also has the capability of recording and rewinding when necessary.
A Connection can be used as a net.Conn because it embeds a net.Conn; but when wrapping underlying connections, usually you want to be careful to replace the embedded Conn, not this entire Connection value.
Connection structs are NOT safe for concurrent use.
func WrapConnection ¶
WrapConnection wraps an underlying connection into a layer4 connection that supports recording and rewinding, as well as adding context with a replacer and variable table. This function is intended for use at the start of a connection handler chain where the underlying connection is not yet a layer4 Connection value.
func (*Connection) GetVar ¶
func (cx *Connection) GetVar(key string) interface{}
GetVar gets a value from the context's variable table with the given key. It returns the value if found, and true if it found a value with that key; false otherwise.
func (*Connection) MatchingBytes ¶
func (cx *Connection) MatchingBytes() []byte
MatchingBytes returns all bytes currently available for matching. This is only intended for reading. Do not write into the slice. It's a view of the internal buffer and you will likely mess up the connection.
func (*Connection) Read ¶
func (cx *Connection) Read(p []byte) (n int, err error)
Read implements io.Reader in such a way that reads first deplete any associated buffer from the prior recording, and once depleted (or if there isn't one), it continues reading from the underlying connection.
func (*Connection) SetVar ¶
func (cx *Connection) SetVar(key string, value interface{})
SetVar sets a value in the context's variable table with the given key. It overwrites any previous value with the same key.
func (*Connection) Wrap ¶
func (cx *Connection) Wrap(conn net.Conn) *Connection
Wrap wraps conn in a new Connection based on cx (reusing cx's existing buffer and context). This is useful after a connection is wrapped by a package that does not support our Connection type (for example, `tls.Server()`).
type Handler ¶
type Handler interface {
Handle(*Connection) error
}
Handler is a type that can handle connections.
type HandlerFunc ¶
type HandlerFunc func(*Connection) error
HandlerFunc can turn a function into a Handler type.
func (HandlerFunc) Handle ¶
func (h HandlerFunc) Handle(cx *Connection) error
Handle handles a connection; it implements the Handler interface.
type ListenerWrapper ¶
type ListenerWrapper struct {
// Routes express composable logic for handling byte streams.
Routes RouteList `json:"routes,omitempty"`
// Maximum time connections have to complete the matching phase (the first terminal handler is matched). Default: 3s.
MatchingTimeout caddy.Duration `json:"matching_timeout,omitempty"`
// contains filtered or unexported fields
}
ListenerWrapper is a Caddy module that wraps App as a listener wrapper, it doesn't support udp.
func (ListenerWrapper) CaddyModule ¶
func (ListenerWrapper) CaddyModule() caddy.ModuleInfo
CaddyModule returns the Caddy module information.
func (*ListenerWrapper) Provision ¶
func (lw *ListenerWrapper) Provision(ctx caddy.Context) error
Provision sets up the ListenerWrapper.
func (*ListenerWrapper) WrapListener ¶
func (lw *ListenerWrapper) WrapListener(l net.Listener) net.Listener
type MatchIP ¶
type MatchIP struct {
Ranges []string `json:"ranges,omitempty"`
// contains filtered or unexported fields
}
MatchIP matches requests by remote IP (or CIDR range).
func (MatchIP) CaddyModule ¶
func (MatchIP) CaddyModule() caddy.ModuleInfo
CaddyModule returns the Caddy module information.
type MatchLocalIP ¶
type MatchLocalIP struct {
Ranges []string `json:"ranges,omitempty"`
// contains filtered or unexported fields
}
MatchLocalIP matches requests by local IP (or CIDR range).
func (MatchLocalIP) CaddyModule ¶
func (MatchLocalIP) CaddyModule() caddy.ModuleInfo
CaddyModule returns the Caddy module information.
func (MatchLocalIP) Match ¶
func (m MatchLocalIP) Match(cx *Connection) (bool, error)
Match returns true if the connection is from one of the designated IP ranges.
func (*MatchLocalIP) Provision ¶
func (m *MatchLocalIP) Provision(ctx caddy.Context) error
Provision parses m's IP ranges, either from IP or CIDR expressions.
type MatchNot ¶
type MatchNot struct {
MatcherSetsRaw []caddy.ModuleMap `json:"-" caddy:"namespace=layer4.matchers"`
MatcherSets []MatcherSet `json:"-"`
}
MatchNot matches requests by negating the results of its matcher sets. A single "not" matcher takes one or more matcher sets. Each matcher set is OR'ed; in other words, if any matcher set returns true, the final result of the "not" matcher is false. Individual matchers within a set work the same (i.e. different matchers in the same set are AND'ed).
NOTE: The generated docs which describe the structure of this module are wrong because of how this type unmarshals JSON in a custom way. The correct structure is:
```json [
{},
{}
] ```
where each of the array elements is a matcher set, i.e. an object keyed by matcher name.
func (MatchNot) CaddyModule ¶
func (MatchNot) CaddyModule() caddy.ModuleInfo
CaddyModule implements caddy.Module.
func (MatchNot) MarshalJSON ¶
MarshalJSON satisfies json.Marshaler by marshaling m's raw matcher sets.
func (MatchNot) Match ¶
func (m MatchNot) Match(r *Connection) (bool, error)
Match returns true if r matches m. Since this matcher negates the embedded matchers, false is returned if any of its matcher sets return true.
func (*MatchNot) UnmarshalJSON ¶
UnmarshalJSON satisfies json.Unmarshaler. It puts the JSON bytes directly into m's MatcherSetsRaw field.
type MatcherSet ¶
type MatcherSet []ConnMatcher
MatcherSet is a set of matchers which must all match in order for the request to be matched successfully.
func (MatcherSet) Match ¶
func (mset MatcherSet) Match(cx *Connection) (matched bool, err error)
Match returns true if the connection matches all matchers in mset or if there are no matchers. Any error terminates matching.
type MatcherSets ¶
type MatcherSets []MatcherSet
MatcherSets is a group of matcher sets capable of checking whether a connection matches any of the sets.
func (MatcherSets) AnyMatch ¶
func (mss MatcherSets) AnyMatch(cx *Connection) (matched bool, err error)
AnyMatch returns true if the connection matches any of the matcher sets in mss or if there are no matchers, in which case the request always matches. Any error terminates matching.
func (*MatcherSets) FromInterface ¶
func (mss *MatcherSets) FromInterface(matcherSets interface{}) error
FromInterface fills ms from an interface{} value obtained from LoadModule.
type Middleware ¶
Middleware is a function that wraps a handler.
type NextHandler ¶
type NextHandler interface {
Handle(*Connection, Handler) error
}
NextHandler is a type that can handle connections as part of a middleware chain.
type NextHandlerFunc ¶
type NextHandlerFunc func(cx *Connection, next Handler) error
NextHandlerFunc can turn a function into a NextHandler type.
func (NextHandlerFunc) Handle ¶
func (h NextHandlerFunc) Handle(cx *Connection, next Handler) error
type RawMatcherSets ¶
type RawMatcherSets []caddy.ModuleMap
RawMatcherSets is a group of matcher sets in their raw JSON form.
type Route ¶
type Route struct {
// Matchers define the conditions upon which to execute the handlers.
// All matchers within the same set must match, and at least one set
// must match; in other words, matchers are AND'ed together within a
// set, but multiple sets are OR'ed together. No matchers matches all.
MatcherSetsRaw []caddy.ModuleMap `json:"match,omitempty" caddy:"namespace=layer4.matchers"`
// Handlers define the behavior for handling the stream. They are
// executed in sequential order if the route's matchers match.
HandlersRaw []json.RawMessage `json:"handle,omitempty" caddy:"namespace=layer4.handlers inline_key=handler"`
// contains filtered or unexported fields
}
Route represents a collection of handlers that are gated by matching logic. A route is invoked if its matchers match the byte stream. In an equivalent "if...then" statement, matchers are like the "if" clause and handlers are the "then" clause: if the matchers match, then the handlers will be executed.
type RouteList ¶
type RouteList []*Route
RouteList is a list of connection routes that can create a middleware chain. Routes are evaluated in sequential order: for the first route, the matchers will be evaluated, and if matched, the handlers invoked; and so on for the second route, etc.
func (RouteList) Compile ¶
func (routes RouteList) Compile(logger *zap.Logger, matchingTimeout time.Duration, next NextHandler) Handler
Compile prepares a middleware chain from the route list. This should only be done once: after all the routes have been provisioned, and before the server loop begins.
type Server ¶
type Server struct {
// The network address to bind to. Any Caddy network address
// is an acceptable value:
// https://caddyserver.com/docs/conventions#network-addresses
Listen []string `json:"listen,omitempty"`
// Routes express composable logic for handling byte streams.
Routes RouteList `json:"routes,omitempty"`
// Maximum time connections have to complete the matching phase (the first terminal handler is matched). Default: 3s.
MatchingTimeout caddy.Duration `json:"matching_timeout,omitempty"`
// contains filtered or unexported fields
}
Server represents a Caddy layer4 server.
Source Files