controller

Documentation

Overview

Package controller provides various access controllers for use in socket-based and HTTP-based services.

Index

• Variables
• func GetClaim(ctx context.Context) *jwt.Claims
• func IsMonitoring(cl *jwt.Claims) bool
• func SetClaim(ctx context.Context, claim *jwt.Claims) context.Context
• type Controller
• type Paths
• type TokenController
  • func NewTokenController(verifier Verifier, required bool, exp jwt.Expected, enforced Paths) (*TokenController, error)
  • func (t *TokenController) Limit(next http.Handler) http.Handler
• type TxController
  • func NewTxController(ctx context.Context, enforced Paths) (*TxController, error)
  • func Setup(ctx context.Context, v Verifier, tokenRequired bool, machine string, ...) (alice.Chain, *TxController)
  • func (tx *TxController) Accept(l net.Listener) (net.Conn, error)
  • func (tx *TxController) Current() uint64
  • func (tx *TxController) Limit(next http.Handler) http.Handler
  • func (tx *TxController) Watch(ctx context.Context) error
• type Verifier

Variables

var (

	// ErrNoDevice is returned when device is empty or not found in procfs.
	ErrNoDevice = errors.New("no device found")

	// ErrNilPaths is returned when a nil Paths value is given.
	ErrNilPaths = errors.New("nil paths value given")
)

var ErrInvalidVerifier = errors.New("verifier is invalid")

ErrInvalidVerifier may be returned when creating a new TokenController.

Functions

func GetClaim

func GetClaim(ctx context.Context) *jwt.Claims

GetClaim attempts to extract the monitoring value from the given context.

func IsMonitoring

func IsMonitoring(cl *jwt.Claims) bool

IsMonitoring reports whether (possibly nil) claim is from a monitoring issuer.

func SetClaim

func SetClaim(ctx context.Context, claim *jwt.Claims) context.Context

SetClaim returns a derived context with the given value.

Types

type Controller

type Controller interface {
	Limit(next http.Handler) http.Handler
}

Controller is the interface that all access control types should implement.

type Paths

type Paths map[string]bool

Paths is used to specify resource names (paths) operated on by access controllers.

type TokenController

type TokenController struct {
	// Public is a public key access token verifier.
	Public Verifier

	// When access tokens are required, then clients without tokens are
	// rejected. When tokens are not required and clients do not provide an
	// access token the connection wil be allowed. In either case, when an
	// access token is provided it must be valid to be accepted.
	Required bool

	// Expected JWT fields are used to validate access token claims.
	// Client-provided claims are only valid if each non-empty expected field
	// matches the corresponding claims field.
	Expected jwt.Expected

	// Enforced is a set of HTTP request resource paths on which the
	// TokenController will enforce token authorization. Any resource missing
	// from the Enforced set is allowed.
	Enforced Paths
}

TokenController manages access control for clients providing access_token parameters in HTTP requests.

func NewTokenController

func NewTokenController(verifier Verifier, required bool, exp jwt.Expected, enforced Paths) (*TokenController, error)

NewTokenController creates a new token controller that requires tokens (or not) and the default expected claims. An audience must be specified. The issuer should be provided.

func (*TokenController) Limit

func (t *TokenController) Limit(next http.Handler) http.Handler

Limit checks client-provided access_tokens. Limit implements the Controller interface.

type TxController

type TxController struct {

	// Enforced is a set of HTTP request resource paths on which the
	// TokenController will enforce token authorization. Any resource missing
	// from the Enforced set, is allowed. When the TxController is used for
	// Accept(), these paths have no effect.
	Enforced Paths
	// contains filtered or unexported fields
}

TxController calculates the bytes transmitted every period from the named device.

func NewTxController

func NewTxController(ctx context.Context, enforced Paths) (*TxController, error)

NewTxController creates a new instance and runs TxController.Watch in a goroutine to observe the current rate every 100 msec. When the given context is canceled or expires, Watch will return and the TxController will no longer be updated until Watch is started again.

func Setup

func Setup(ctx context.Context, v Verifier, tokenRequired bool, machine string, txEnf, tkEnf Paths) (alice.Chain, *TxController)

Setup creates a sequence of access control http.Handlers. When the verifier is nil then the token controller will be excluded from the returned handler chain. When the tx controller is unconfigured then the tx controller will be excluded from the returned handler chain. Setup returns the TxController because it provides the Accepter interface for use by servers accepting raw TCP connections. See TxController.Accept for more information. When tokenRequired is true, then the token controller requires valid access tokens for the named machine.

func (*TxController) Accept

func (tx *TxController) Accept(l net.Listener) (net.Conn, error)

Accept wraps the call to listener's Accept. If the TxController is limited, then Accept immediately closes the connection and returns an error.

func (*TxController) Current

func (tx *TxController) Current() uint64

Current exports the current rate. Useful for diagnostics.

func (*TxController) Limit

func (tx *TxController) Limit(next http.Handler) http.Handler

Limit enforces that the TxController rate limit is respected before running the next handler. If the rate is unspecified (zero), all requests are accepted.

func (*TxController) Watch

func (tx *TxController) Watch(ctx context.Context) error

Watch updates the current rate every period. If the context is cancelled, the context error is returned. If the TxController rate is zero, Watch returns immediately. Callers should typically run Watch in a goroutine.

type Verifier

type Verifier interface {
	Verify(token string, exp jwt.Expected) (*jwt.Claims, error)
}

Verifier is used by the TokenController to verify JWT claims in access tokens.