request

Documentation

Index

• Constants
• Variables
• func CreateRequestor(ctx context.Context) *api.EventLifecycleRequestor
• func GetContextValue[T any](ctx context.Context, key CtxKey) (T, error)
• func ProjectParam(request *http.Request) string
• func ProjectParams(r *http.Request) (string, bool, error)
• func QueryParam(request *http.Request, key string) string
• func SaveConnectionInContext(ctx context.Context, connection net.Conn) context.Context
• func SetContextValue(r *http.Request, key CtxKey, value any)
• func SetRequestor(req *http.Request, hook RequestorHook, args RequestorArgs) error
• func SetRequestorHeaders(r *RequestorAuditor, req *http.Request)
• func WithRequestorAuditor(ctx context.Context, requestor *RequestorAuditor) context.Context
• type ClientType
  • func (c ClientType) IsClusterNotification() bool
  • func (c ClientType) IsClusterOperationNotification() bool
• type CtxKey
• type Requestor
  • func GetRequestor(ctx context.Context) (*Requestor, error)
  • func (r *Requestor) CallerAllowedProjectNames() []string
  • func (r *Requestor) CallerAuthorizationGroupNames() []string
  • func (r *Requestor) CallerEffectiveAuthorizationGroupNames() []string
  • func (r *Requestor) CallerIdentityProviderGroups() []string
  • func (r *Requestor) CallerIdentityType() (identity.Type, error)
  • func (r *Requestor) CallerIsEqual(requestor *RequestorAuditor) bool
  • func (r *Requestor) ClientType() ClientType
  • func (r *Requestor) ClusterMemberTLSCertificateFingerprint() (string, error)
  • func (r *Requestor) ExpiresAt() *time.Time
  • func (r *Requestor) IsAdmin() bool
  • func (r *Requestor) IsClusterNotification() bool
  • func (r *Requestor) IsForwarded() bool
  • func (r *Requestor) IsTrusted() bool
• type RequestorArgs
• type RequestorAuditor
  • func GetRequestorAuditor(ctx context.Context) (*RequestorAuditor, error)
  • func (r *RequestorAuditor) EventLifecycleRequestor() *api.EventLifecycleRequestor
  • func (r *RequestorAuditor) OperationRequestor() *api.OperationRequestor
• type RequestorHook
• type RequestorHookResult
• type UserAgent
  • func ParseUserAgent(userAgent string) (*UserAgent, error)
• type UserAgentHost
• type UserAgentProduct

Constants

const (
	// ProtocolCluster is set as the RequestorArgs.Protocol when the request is authenticated via mTLS and the peer
	// certificate is present in the trust store as type [certificate.TypeServer].
	ProtocolCluster string = "cluster"

	// ProtocolUnix is set as the RequestorArgs.Protocol when the request is made over the unix socket.
	ProtocolUnix string = "unix"

	// ProtocolPKI is set as the RequestorArgs.Protocol when a `server.ca` file exists in LXD_DIR, the peer
	// certificate of the request was signed by the CA file, and core.trust_ca_certificates is true.
	//
	// Note: If core.trust_ca_certificates is false, the peer certificate is additionally verified via mTLS and
	// RequestorArgs.Protocol is set to [api.AuthenticationMethodTLS].
	//
	// Note: Regardless of whether `core.trust_ca_certificates` is enabled, if an identity corresponding to the clients
	// peer certificate exists in the [identity.Cache], then protocol should be set to [api.AuthenticationMethodTLS] and
	// the identity should be set as the RequestorArgs.Identity.
	ProtocolPKI string = "pki"

	// ProtocolDevLXD is the authentication method for interacting with the devlxd API.
	ProtocolDevLXD = "devlxd"
)

const UserAgentJoiner = "lxd-cluster-joiner"

UserAgentJoiner used to distinguish between a regular client request and an internal cluster request when joining a node to a cluster.

const UserAgentNotifier = "lxd-cluster-notifier"

UserAgentNotifier used to distinguish between a regular client request and an internal cluster request when notifying other nodes of a cluster change.

const UserAgentOperationNotifier = "lxd-operation-notifier"

UserAgentOperationNotifier is used to distinguish between a standard internal cluster request (which uses UserAgentNotifier) and an internal cluster request coming from within an operation (which uses UserAgentOperationNotifier). The notified node does not need to create another operation to handle the request in this case, as the asynchronous nature is already achieved by the operation on the sending node.

Variables

var ErrRequestNotInternal = errors.New("The request was not made by another cluster member")

ErrRequestNotInternal is returned if Requestor.ClusterMemberTLSCertificateFingerprint is called and the request was not made by another cluster member.

var ErrRequestorNotPresent = errors.New("No requestor was found in the given context")

ErrRequestorNotPresent is a sentinel error used when getting the Requestor from the request context.

Functions

func CreateRequestor

func CreateRequestor(ctx context.Context) *api.EventLifecycleRequestor

CreateRequestor extracts the lifecycle event requestor data from the provided context.

func GetContextValue

func GetContextValue[T any](ctx context.Context, key CtxKey) (T, error)

GetContextValue gets a value of type T from the context using the given key.

func ProjectParam

func ProjectParam(request *http.Request) string

ProjectParam returns the project query parameter from the given request or "default" if parameter is not set.

func ProjectParams

func ProjectParams(r *http.Request) (string, bool, error)

ProjectParams returns the project name and the value of the all projects query parameter. It returns an api.StatusError with http.StatusBadRequest if both parameters are specified.

func QueryParam

func QueryParam(request *http.Request, key string) string

QueryParam extracts the given query parameter directly from the URL, never from an encoded body.

func SaveConnectionInContext

func SaveConnectionInContext(ctx context.Context, connection net.Conn) context.Context

SaveConnectionInContext can be set as the ConnContext field of a http.Server to set the connection in the request context for later use.

func SetContextValue

func SetContextValue(r *http.Request, key CtxKey, value any)

SetContextValue sets the given value in the request context with the given key.

func SetRequestor

func SetRequestor(req *http.Request, hook RequestorHook, args RequestorArgs) error

SetRequestor validates the given RequestorArgs against the request, then populates the additional fields that requestor contains and sets a requestor in the context.

func SetRequestorHeaders

func SetRequestorHeaders(r *RequestorAuditor, req *http.Request)

SetRequestorHeaders adds the requestor details as forwarded headers on the given HTTP request so the receiving cluster member can identify the caller.

func WithRequestorAuditor

func WithRequestorAuditor(ctx context.Context, requestor *RequestorAuditor) context.Context

WithRequestorAuditor is used to set the RequestorAuditor in the given context. This is used by operations to set the requestor in the context of an async task.

Types

type ClientType

type ClientType string

ClientType indicates which sort of client type is being used.

const ClientTypeJoiner ClientType = "joiner"

ClientTypeJoiner cluster joiner client.

const ClientTypeNormal ClientType = "normal"

ClientTypeNormal normal client.

const ClientTypeNotifier ClientType = "notifier"

ClientTypeNotifier cluster notification client.

const ClientTypeOperationNotifier ClientType = "operation-notifier"

ClientTypeOperationNotifier cluster notification client coming from within an operation.

func (ClientType) IsClusterNotification

func (c ClientType) IsClusterNotification() bool

IsClusterNotification returns true if the ClientType is ClientTypeNotifier.

func (ClientType) IsClusterOperationNotification

func (c ClientType) IsClusterOperationNotification() bool

IsClusterOperationNotification returns true if the ClientType is ClientTypeOperationNotifier.

type CtxKey

type CtxKey string

CtxKey is the type used for all fields stored in the request context by LXD.

const (

	// CtxDevLXDInstance is the instance that made a request over the devLXD API.
	CtxDevLXDInstance CtxKey = "devlxd_instance"

	// CtxDevLXDOverVsock indicates whether the devLXD is being interacted with over vsock.
	CtxDevLXDOverVsock CtxKey = "devlxd_over_vsock"

	// CtxConn is the connection field in the request context.
	CtxConn CtxKey = "conn"

	// CtxEffectiveProjectName is used to indicate that the effective project of a resource is different from the project
	// specified in the URL. (For example, if a project has `features.networks=false`, any networks in this project actually
	// belong to the default project).
	CtxEffectiveProjectName CtxKey = "effective_project_name"

	// CtxMetricsCallbackFunc is a callback function that can be called to mark the request as completed for the API metrics.
	CtxMetricsCallbackFunc CtxKey = "metrics_callback_function"

	// CtxOpenFGARequestCache is used to set a cache for the OpenFGA datastore to improve driver performance on a per request basis.
	CtxOpenFGARequestCache CtxKey = "openfga_request_cache"

	// CtxSecurityEventBase carries the per-request OWASP audit fields used to
	// populate security events emitted while handling a request.
	CtxSecurityEventBase CtxKey = "security_event_base"
)

Context keys.

type Requestor

type Requestor struct {
	RequestorAuditor
	// contains filtered or unexported fields
}

Requestor contains a RequestorAuditor and additional unexported fields used for authorization purposes. It is set in the request context after authentication via SetRequestor. It always represents the original API caller, regardless of whether the request is forwarded from another cluster member.

func GetRequestor

func GetRequestor(ctx context.Context) (*Requestor, error)

GetRequestor gets a Requestor from the request context.

func (*Requestor) CallerAllowedProjectNames

func (r *Requestor) CallerAllowedProjectNames() []string

CallerAllowedProjectNames returns a list of names of projects that the caller has access to.

func (*Requestor) CallerAuthorizationGroupNames

func (r *Requestor) CallerAuthorizationGroupNames() []string

CallerAuthorizationGroupNames returns the LXD authorization groups that the requestor belongs to.

func (*Requestor) CallerEffectiveAuthorizationGroupNames

func (r *Requestor) CallerEffectiveAuthorizationGroupNames() []string

CallerEffectiveAuthorizationGroupNames returns a list of all authorization groups that the identity belongs to either directly or via a mapped identity provider group.

func (*Requestor) CallerIdentityProviderGroups

func (r *Requestor) CallerIdentityProviderGroups() []string

CallerIdentityProviderGroups returns the original caller identity provider groups.

func (*Requestor) CallerIdentityType

func (r *Requestor) CallerIdentityType() (identity.Type, error)

CallerIdentityType returns the identity.Type corresponding to the CallerIdentity. It may be nil (e.g. if the protocol is ProtocolUnix).

func (*Requestor) CallerIsEqual

func (r *Requestor) CallerIsEqual(requestor *RequestorAuditor) bool

CallerIsEqual returns true if the given Requestor is the same caller as this Requestor.

func (*Requestor) ClientType

func (r *Requestor) ClientType() ClientType

ClientType returns the client type, which is derived from the "User-Agent" request header.

func (*Requestor) ClusterMemberTLSCertificateFingerprint

func (r *Requestor) ClusterMemberTLSCertificateFingerprint() (string, error)

ClusterMemberTLSCertificateFingerprint returns the TLS certificate fingerprint of the cluster member that sent the request. It returns an error if the request was not sent by another cluster member.

func (*Requestor) ExpiresAt

func (r *Requestor) ExpiresAt() *time.Time

ExpiresAt returns the expiration date of the credential used to authenticate the caller. Returns nil if the caller is not authenticated using a bearer token or TLS.

func (*Requestor) IsAdmin

func (r *Requestor) IsAdmin() bool

IsAdmin returns true if the caller is an administrator and false otherwise.

func (*Requestor) IsClusterNotification

func (r *Requestor) IsClusterNotification() bool

IsClusterNotification returns true if this an API request coming from a cluster node that is notifying us of some user-initiated API request that needs some action to be taken on this node as well.

func (*Requestor) IsForwarded

func (r *Requestor) IsForwarded() bool

IsForwarded returns true if the request was forwarded from another cluster member and false otherwise.

func (*Requestor) IsTrusted

func (r *Requestor) IsTrusted() bool

IsTrusted returns true if the caller is authenticated and false otherwise.

type RequestorArgs

type RequestorArgs struct {
	// Trusted indicates whether the request was authenticated or not. This is always set (and is false by default).
	Trusted bool

	// Username is the caller username. If the request was forwarded this may be the certificate fingerprint of another
	// cluster member. It is only set if the Trusted is true.
	Username string

	// Protocol is the caller protocol. If the request was forwarded this may be the certificate fingerprint of another
	// cluster member. It is only set if the Trusted is true.
	Protocol string

	// ExpiresAt is the expiration time of the credential used to authenticate the caller.
	// It is set only when the client is trusted and the authentication method is either
	// [api.AuthenticationMethodBearer] or [api.AuthenticationMethodTLS].
	ExpiresAt *time.Time
}

RequestorArgs contains information that is gathered when the requestor is initially authenticated.

type RequestorAuditor

type RequestorAuditor struct {
	Username      string
	Protocol      string
	OriginAddress string
	IdentityID    *int64
}

RequestorAuditor is used for auditing and request forwarding within the cluster, and within operations. Permission checks cannot be performed with RequestorAuditor, save only for checking if two requestors are equal.

func GetRequestorAuditor

func GetRequestorAuditor(ctx context.Context) (*RequestorAuditor, error)

GetRequestorAuditor gets an RequestorAuditor from the context.

func (*RequestorAuditor) EventLifecycleRequestor

func (r *RequestorAuditor) EventLifecycleRequestor() *api.EventLifecycleRequestor

EventLifecycleRequestor returns an api.EventLifecycleRequestor representing the original caller.

func (*RequestorAuditor) OperationRequestor

func (r *RequestorAuditor) OperationRequestor() *api.OperationRequestor

OperationRequestor returns an api.OperationRequestor representing the original caller.

type RequestorHook

type RequestorHook func(ctx context.Context, authenticationMethod string, identifier string) (result *RequestorHookResult, err error)

RequestorHook is the signature of a hook that is passed into calls to SetRequestor. This allows the caller to specify how to get authorization information about an identity that has successfully authenticated.

type RequestorHookResult

type RequestorHookResult struct {
	IdentityID             int64
	IdentityType           identity.Type
	AuthGroups             []string
	IdentityProviderGroups []string
	EffectiveAuthGroups    []string
	Projects               []string
}

RequestorHookResult contains identity and access management details returned by the RequestorHook.

type UserAgent

type UserAgent struct {
	Product  UserAgentProduct
	Host     UserAgentHost
	Storage  map[string]string
	Features []string
}

UserAgent represents a LXD user agent.

func ParseUserAgent

func ParseUserAgent(userAgent string) (*UserAgent, error)

ParseUserAgent parses a user agent to return a UserAgent.

type UserAgentHost

type UserAgentHost struct {
	OS            string
	Arch          string
	KernelVersion string
	Distro        string
	DistroVersion string
}

UserAgentHost contains host information stored in the user agent.

type UserAgentProduct

type UserAgentProduct struct {
	Name    string
	Version string
	LTS     bool
}

UserAgentProduct contains information about the product (first part of user agent).