gorilla

Documentation

Overview

Package gorilla provides a session.Store implementation that uses kubernetes as its persistence layer

Purpose

This package will create sessions resources inside a kubernetes cluster. It does not clean the sessions up. Please consider using the package github.com/venezia/k8s-gorilla-session-store/janitor to clean up expired sessions.

Kubernetes Considerations

• This package uses a generated client github.com/venezia/k8s-gorilla-session-store/k8s/client/clientset/versioned.Interface to interact with kubernetes.
• There is a custom resource definition file provided in the k8s/crd folder. This needs to be applied to the kubernetes cluster
• If RBAC is enabled, RBAC permissions will probably be needed

Logging Considerations

This package supports log/slog.Logger as a logger provided to it through the configuration of a new store.

Size limitations

Generally speaking, kubernetes resources are limited to 1MiB in size. Therefore, a default limit of 128KiB is used on session storage. One can set the limit as they wish, but the size may exceed what the kubernetes apiserver accepts.

Index

• Constants
• func NormalizeIDValue(input string) string
• type Config
• type Error
  • func (e *Error) Error() string
  • func (e *Error) Unwrap() error
• type ErrorMessage
• type ErrorType
• type GobSerializer
  • func (g GobSerializer) Deserialize(input string, session *sessions.Session) error
  • func (g GobSerializer) Serialize(session *sessions.Session) (string, error)
• type K8SConfig
• type SessionSerializer
• type Store
  • func New(ctx context.Context, config *Config) (*Store, error)
  • func (s *Store) EnsureK8SClient() error
  • func (s *Store) Get(r *http.Request, name string) (*sessions.Session, error)
  • func (s *Store) GetK8SConfig() (*rest.Config, error)
  • func (s *Store) K8SDelete(ctx context.Context, session *sessions.Session) error
  • func (s *Store) K8SLoad(ctx context.Context, session *sessions.Session) (bool, error)
  • func (s *Store) K8SSave(ctx context.Context, session *sessions.Session) error
  • func (s *Store) New(r *http.Request, name string) (*sessions.Session, error)
  • func (s *Store) Save(r *http.Request, w http.ResponseWriter, session *sessions.Session) error

Constants

const (
	// GenericErrorType is the generic error for the demo package.
	GenericErrorType ErrorType = "generic"

	// TransientErrorType are errors when a failure happened, but we think it is a transient error
	//
	// Example causes include:
	//  - network connectivity disrupted
	//
	// It is reasonable to think that attempting the operation later may result in a happier outcome
	TransientErrorType ErrorType = "transient"

	// ExecutionErrorType is the error type that can return if something was attempted, but we cannot fulfill the request
	//
	// Repeated attempts are unlikely to result in a better outcome, as best as we can tell, the input was valid
	//
	// Examples would include:
	//  - misconfiguration of an upstream service (not disconnection, misconfiguration)
	ExecutionErrorType ErrorType = "execution"

	// InputErrorType is the error type that can return if something was attempted, but we cannot fulfill the request
	//
	// Repeated attempts are unlikely to result in a better outcome, as best as we can tell, the input was invalid
	//
	InputErrorType ErrorType = "input"

	// NotImplementedErrorType are errors when what asked simply is not implemented
	//
	// It is reasonable to expect that this change will never change
	NotImplementedErrorType ErrorType = "not-implemented"

	// GenericError is a coverall - hopefully never used
	GenericError ErrorMessage = "an error occurred"

	FeatureNotImplementedError ErrorMessage = "this feature of the store is not implemented for this provider"
)

const (
	// Main Kubernetes Driver Messages
	LogCannotReadKubeconfigFile        = "cannot read in kubeconfig file as specified"
	LogCannotConvertKubeconfigContents = "could not convert kubeconfig contents to a valid configuration"
	LogCannotUseInClusterConfig        = "seemingly not in a kubernetes cluster, cannot use in cluster configuration"
	LogCannotConvertInClusterConfig    = "seemingly in a kubernetes cluster but cannot create a valid cluster configuration"

	LogSavingSessionDataToKubernetes                  = "saving session data to kubernetes"
	LogCannotPersistDataToKubernetes                  = "could not save data to kubernetes"
	LogLoadSessionDataFromKubernetes                  = "loading session data from kubernetes"
	LogSessionDataNotFoundInKubernetes                = "session resource not found in kubernetes"
	LogSessionDataRetrievalErrorOccurred              = "error occurred while trying to retrieve session data from kubernetes"
	LogErrorTryingToDeserializeSessionData            = "error occurred while trying to deserialize session data"
	LogCannotDeleteNonExistentSessionFromKubernetes   = "could not delete session from kubernetes - already removed"
	LogDeletingSessionFromKubernetes                  = "deleting session from kubernetes"
	LogErrorTryingToDeleteSessionResourceInKubernetes = "error occurred while trying to delete a session resource in kubernetes"

	LogK8SClientAlreadyExists                     = "kubernetes client already set, not going to recreate"
	LogCannotCreateKubernetesClient               = "error occurred while trying to create a kubernetes client"
	LogK8SConfigCreationThroughKubeconfigLocation = "attempting to create a kubernetes configuration via a kubeconfig file location setting"
	LogK8SConfigCreationThroughKubeconfig         = "attempting to create a kubernetes configuration via a kubeconfig contents provided directly in configuration"
	LogK8SConfigCreationThroughInCluster          = "attempting to create a kubernetes configuration through the in-cluster option"

	LogSessionIDKey          = "sessionID"
	LogKubeconfigLocationKey = "kubeconfigLocation"
	LogKubeconfigSizeKey     = "kubeconfigSize"

	ErrSessionDataTooBig = "k8s-gorilla-session-store.K8SSave: data to persist is over size limit"
)

const (
	DefaultMaxAge     = 86400             // how long should the session persist for
	DefaultMaxLength  = 1024 * 128        // 128KB of session storage
	DefaultCookiePath = "/"               // have the session be site wide
	DefaultSecret     = "notAGreatSecret" // default secret for session validation
)

Functions

func NormalizeIDValue

func NormalizeIDValue(input string) string

NormalizeIDValue will return back a lowercase string. Kubernetes id values have to be lowercase

Types

type Config

type Config struct {
	K8S            K8SConfig
	SessionOptions *sessions.Options
	MaxLength      int    // Max amount of storage to be allowed in session data for a given user
	Secret         string // Secret is for validating a session key
	Logger         *slog.Logger
}

type Error

type Error struct {
	Type    ErrorType
	Details interface{}
	Message ErrorMessage
	Err     error
}

func (*Error) Error

func (e *Error) Error() string

func (*Error) Unwrap

func (e *Error) Unwrap() error

type ErrorMessage

type ErrorMessage string

type ErrorType

type ErrorType string

type GobSerializer

type GobSerializer struct{}

GobSerializer uses gob package to encode the session map

func (GobSerializer) Deserialize

func (g GobSerializer) Deserialize(input string, session *sessions.Session) error

Deserialize back to map[interface{}]interface{}

func (GobSerializer) Serialize

func (g GobSerializer) Serialize(session *sessions.Session) (string, error)

Serialize using gob

type K8SConfig

type K8SConfig struct {
	KubeconfigLocation string // Where a kubeconfig file is located on the system
	Kubeconfig         []byte // The contents of a kubeconfig
	Namespace          string // The namespace that will be used to look for resources
	Client             clientset.Interface
}

type SessionSerializer

type SessionSerializer interface {
	Deserialize(s string, session *sessions.Session) error
	Serialize(session *sessions.Session) (string, error)
}

SessionSerializer provides an interface hook for alternative serializers

type Store

type Store struct {
	Ctx        context.Context
	Config     *Config
	Serializer SessionSerializer
	Codecs     []securecookie.Codec
}

func New

func New(ctx context.Context, config *Config) (*Store, error)

New returns a new Store based on configuration

func (*Store) EnsureK8SClient

func (s *Store) EnsureK8SClient() error

EnsureK8SClient will try to create a kubernetes client if it isn't already set

func (*Store) Get

func (s *Store) Get(r *http.Request, name string) (*sessions.Session, error)

Get should return a cached session.

func (*Store) GetK8SConfig

func (s *Store) GetK8SConfig() (*rest.Config, error)

GetK8SConfig will try to get a working kubernetes client configuration returning an error if it cannot

func (*Store) K8SDelete

func (s *Store) K8SDelete(ctx context.Context, session *sessions.Session) error

K8SDelete removes a session's contents from the data store (kubernetes)

func (*Store) K8SLoad

func (s *Store) K8SLoad(ctx context.Context, session *sessions.Session) (bool, error)

K8SLoad reads the session from the kubernetes api. returns true if there is session data to be found

func (*Store) K8SSave

func (s *Store) K8SSave(ctx context.Context, session *sessions.Session) error

K8SSave Stores the session in the kubernetes api.

func (*Store) New

func (s *Store) New(r *http.Request, name string) (*sessions.Session, error)

New creates new session and if possible, loads the stored data into it

func (*Store) Save

func (s *Store) Save(r *http.Request, w http.ResponseWriter, session *sessions.Session) error

Save should persist session to the store (kubernetes)