server

Documentation

Index

• func WithChallengeParams(params pkg.ChallengeParams) func(h *Server)
• func WithChallengeParamsChooser(chooser ChallengeParamChooserFunc) func(h *Server)
• func WithErrorHandler(errFunc ErrorHandlerFunc) func(h *Server)
• func WithIPForRateLimit(ipFunc IPExtractorFunc) func(h *Server)
• func WithValidDuration(duration time.Duration) func(h *Server)
• type ChallengeHandlerOpts
• type ChallengeParamChooserFunc
  • func NewStaticChallengeParamsChooser(params pkg.ChallengeParams) ChallengeParamChooserFunc
• type ErrorHandlerFunc
• type IPExtractorFunc
  • func NewHeaderIPExtractor(header string) IPExtractorFunc
• type Server
  • func NewServer(cap *pkg.Cap, opts ...func(h *Server)) *Server
  • func (s *Server) ChallengeHandler(res http.ResponseWriter, req *http.Request)
  • func (s *Server) RedeemHandler(res http.ResponseWriter, req *http.Request)

Functions

func WithChallengeParams

func WithChallengeParams(params pkg.ChallengeParams) func(h *Server)

WithChallengeParams sets the parameters to use when creating new challenges. When not specified, uses cap.DefaultChallengeParams. To specify a dynamic params chooser, use WithChallengeParamsChooser.

func WithChallengeParamsChooser

func WithChallengeParamsChooser(chooser ChallengeParamChooserFunc) func(h *Server)

WithChallengeParamsChooser sets the challenge params chooser to use when creating new challenges. When not specified, see comment on WithChallengeParams. If you just want to choose static params, use WithChallengeParamsChooser.

func WithErrorHandler

func WithErrorHandler(errFunc ErrorHandlerFunc) func(h *Server)

WithErrorHandler sets a function to handle errors in the HTTP handlers. The function is called when an error occurs, such as when the Cap driver returns an error.

func WithIPForRateLimit

func WithIPForRateLimit(ipFunc IPExtractorFunc) func(h *Server)

WithIPForRateLimit uses the specified IP extractor function to pass IPs to the driver for rate limiting. Without an IP extractor function, the driver cannot perform rate limiting, even if it is enabled.

func WithValidDuration

func WithValidDuration(duration time.Duration) func(h *Server)

WithValidDuration sets the duration that a Cap challenge is valid before it expires. When not specified, uses cap.DefaultValidDuration.

Types

type ChallengeHandlerOpts

type ChallengeHandlerOpts struct {
	// IpExtractor is the function used to extract the IP from a request.
	// It is used for rate limiting.
	// If unspecified/nil, rate limiting will be disabled.
	IpExtractor IPExtractorFunc
}

ChallengeHandlerOpts is options for Server.

type ChallengeParamChooserFunc

type ChallengeParamChooserFunc func(req *http.Request) (pkg.ChallengeParams, error)

ChallengeParamChooserFunc is a function that chooses challenge params based on a request. It can be used to dynamically select parameters based on things like the path, authentication, etc. If it returns an error, the error will be passed to the server's error handler.

func NewStaticChallengeParamsChooser

func NewStaticChallengeParamsChooser(params pkg.ChallengeParams) ChallengeParamChooserFunc

NewStaticChallengeParamsChooser creates a new ChallengeParamChooserFunc that uses a static params struct. Will never return an error.

type ErrorHandlerFunc

type ErrorHandlerFunc func(err error, res http.ResponseWriter, req *http.Request)

ErrorHandlerFunc is a function that handles an error and optionally writes an HTTP response. The error passed to it will never be nil.

type IPExtractorFunc

type IPExtractorFunc func(req *http.Request) *netip.Addr

IPExtractorFunc is a function that extracts the client IP from a request. If the function returns nil, the IP cannot be determined.

var RemoteAddrIPExtractor IPExtractorFunc = func(req *http.Request) *netip.Addr {
	remoteAddr := req.RemoteAddr

	colonIdx := strings.IndexByte(remoteAddr, ':')
	if colonIdx == -1 {
		return nil
	}

	addrPort, err := netip.ParseAddrPort(req.RemoteAddr)
	if err != nil {
		return nil
	}

	addr := addrPort.Addr()
	return &addr
}

RemoteAddrIPExtractor is an IPExtractorFunc that uses the request's remote address. This SHOULD NOT be used in environments where the application is behind a reverse proxy.

func NewHeaderIPExtractor

func NewHeaderIPExtractor(header string) IPExtractorFunc

NewHeaderIPExtractor creates a new IPExtractorFunc that gets the request IP from a header. If the header is not present or does not contain a valid IP, the extractor returns nil. If the header is a comma-separated list, gets the leftmost entry.

Example: NewHeaderIPExtractor("X-Forwarded-For")

type Server

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

Server is an implementation of the Cap server endpoints used to issue and validate challenges. It uses a Cap instance and its driver; it does not provide its own.

func NewServer

func NewServer(cap *pkg.Cap, opts ...func(h *Server)) *Server

NewServer creates a new Cap server with the specified options.

func (*Server) ChallengeHandler

func (s *Server) ChallengeHandler(res http.ResponseWriter, req *http.Request)

ChallengeHandler is the HTTP handler that issues new challenges. Should be mounted on `/challenge`.

func (*Server) RedeemHandler

func (s *Server) RedeemHandler(res http.ResponseWriter, req *http.Request)

RedeemHandler is the HTTP handler that accepts solutions and verifies them, returning a redeem token if correct and valid. Should be mounted on `/redeem`.