runmode

Documentation

Overview

Package runmode defines store specific middleware to initialize the scope and its ID per request.

Index

• Constants
• func CodeIsValid(c string) error
• func FromContextRunMode(ctx context.Context) scope.TypeID
• func WithContextRunMode(ctx context.Context, runMode scope.TypeID) context.Context
• func WithRunMode(sf store.Finder, o Options) mw.Middleware
• type Calculater
• type CodeProcessor
• type Options
• type ProcessStoreCodeCookie
  • func (e *ProcessStoreCodeCookie) FromRequest(_ scope.TypeID, req *http.Request) string
  • func (a *ProcessStoreCodeCookie) ProcessAllowed(_ scope.TypeID, oldStoreID, newStoreID int64, newStoreCode string, ...)
  • func (a *ProcessStoreCodeCookie) ProcessDenied(_ scope.TypeID, _, _ int64, w http.ResponseWriter, r *http.Request)
• type RunModeFunc
  • func (f RunModeFunc) CalculateRunMode(r *http.Request) scope.TypeID

Constants

const CodeFieldName = `store`

CodeFieldName defines the filed name where store code has been saved. Used in Cookies and JSON Web Tokens (JWT) to identify an active store besides from the default loaded store.

const CodeMaxLen = 32

CodeMaxLen defines the overall maximum length a store code can have.

const CodeURLFieldName = `___store`

CodeURLFieldName name of the GET parameter to set a new store in a current website/group context/request.

const Default scope.TypeID = 0

Default defines the default run mode which is zero. It indicates the fall back to the default website and its default store.

Functions

func CodeIsValid

func CodeIsValid(c string) error

CodeIsValid checks if a store code is valid. Returns an ErrStoreCodeEmpty or an ErrStoreCodeInvalid if the first letter is not a-zA-Z and followed by a-zA-Z0-9_ or store code length is greater than 32 characters. Error behaviour: NotValid

func FromContextRunMode

func FromContextRunMode(ctx context.Context) scope.TypeID

FromContextRunMode returns the run mode scope.TypeID from a context. If no entry can be found in the context the returned TypeID has a default value (0). This default value indicates the fall back to the default website and its default store. Use case for the runMode: Cache Keys and app initialization.

func WithContextRunMode

func WithContextRunMode(ctx context.Context, runMode scope.TypeID) context.Context

WithContextRunMode sets the main run mode for the current request. It panics when called multiple times for the current context. This function is used in net/runmode together with function RunMode.CalculateMode(r, w). Use case for the runMode: Cache Keys and app initialization.

func WithRunMode

func WithRunMode(sf store.Finder, o Options) mw.Middleware

WithRunMode sets for each request the overall runMode aka. scope. The following steps will be performed:

1. Call to AppRunMode.RunMode.CalculateMode to get the default run mode. 2a. Parse Request GET parameter for the store code key (___store). 2b. If GET is empty, check cookie for key "store" 2c. Lookup CodeToIDMapper.IDbyCode() to get the website/store ID from a website/store code.
3. Retrieve all AllowedStoreIDs based on the runMode
4. Check if the website/store ID

Types

type Calculater

type Calculater interface {
	CalculateRunMode(*http.Request) scope.TypeID
}

Calculater core type to initialize the run mode of the current request. Allows you to create a multi-site / multi-tenant setup. An implementation of this lives in net.runmode.WithRunMode() middleware.

Your custom function allows to initialize the runMode based on parameters in the http.Request.

type CodeProcessor

type CodeProcessor interface {
	// FromRequest returns the valid non-empty store code. Returns an empty
	// store code on all other cases.
	FromRequest(runMode scope.TypeID, req *http.Request) (code string)
	// ProcessDenied gets called in the middleware WithRunMode whenever a store
	// ID isn't allowed to proceed. The variable newStoreID reflects the denied
	// store ID. The ResponseWriter and Request variables can be used for
	// additional information writing and extracting. The error Handler  will
	// always be called.
	ProcessDenied(runMode scope.TypeID, oldStoreID, newStoreID int64, w http.ResponseWriter, r *http.Request)
	// ProcessAllowed enables to adjust the ResponseWriter based on the new
	// store ID. The variable newStoreID contains the new ID, which can also be
	// 0. The code is guaranteed to be not empty, a valid store code, and always
	// points to an existing active store. The ResponseWriter and Request
	// variables can be used for additional information writing and extracting.
	// The next Handler in the chain will after this function be called.
	ProcessAllowed(runMode scope.TypeID, oldStoreID, newStoreID int64, newStoreCode string, w http.ResponseWriter, r *http.Request)
}

CodeProcessor gets used in the middleware WithRunMode() to extract a store code from a Request and modify the response; for example setting cookies to persists the selected store.

type Options

type Options struct {
	// ErrorHandler optional custom error handler. Defaults to sending an HTTP
	// status code 500 and exposing the real error including full paths.
	mw.ErrorHandler
	// UnauthorizedHandler gets called when a requested store code cannot be
	// authorized to continue. Defaults to sending an HTTP status code
	// StatusUnauthorized and exposing the real error including full paths.
	UnauthorizedHandler mw.ErrorHandler
	// Log can be nil, defaults to black hole.
	Log log.Logger
	// Calculater optional custom runMode otherwise falls back to
	// scope.Default which selects the default website with its default
	// store. To use the admin area enable scope.Store and ID 0.
	Calculater
	// StoreCodeProcessor extracts the store code from an HTTP requests.
	// Optional. Defaults to type ProcessStoreCodeCookie.
	store.CodeProcessor
	// DisableStoreCodeProcessor set to true and set StoreCodeProcessor to nil
	// to disable store code handling
	DisableStoreCodeProcessor bool
}

Options additional customizations for the runMode middleware.

type ProcessStoreCodeCookie

type ProcessStoreCodeCookie struct {
	// FieldName optional custom name, defaults to constant store.CodeFieldName.
	// Cannot be changed after the first call to FromRequest().
	FieldName string
	// URLFieldName optional custom name, defaults to constant
	// store.CodeURLFieldName. Cannot be changed after the first call to
	// FromRequest().
	URLFieldName string

	// CookieTemplate optional pre-configured cookie to set the store
	// code. Expiration time and value will get overwritten.
	CookieTemplate func(*http.Request) *http.Cookie
	// CookieExpiresSet defaults to one year expiration for the store code.
	CookieExpiresSet time.Time
	// CookieExpiresDelete defaults to minus ten years to delete the store code
	// cookie.
	CookieExpiresDelete time.Time
	// contains filtered or unexported fields
}

ProcessStoreCodeCookie can extract the store code from a cookie within an HTTP Request. Handles cookies to permanently set the store code under different conditions. This store code is then responsible for changing the runMode.

func (*ProcessStoreCodeCookie) FromRequest

func (e *ProcessStoreCodeCookie) FromRequest(_ scope.TypeID, req *http.Request) string

FromRequest returns from a GET request with a query string the value of the store code. If no code can be found in the query string, this function falls back to the cookie name defined in field FieldName. Valid has three values: 0 not valid, 10 valid and code found in GET query string, 20 valid and code found in cookie. Implements interface store.CodeProcessor.

func (*ProcessStoreCodeCookie) ProcessAllowed

func (a *ProcessStoreCodeCookie) ProcessAllowed(_ scope.TypeID, oldStoreID, newStoreID int64, newStoreCode string, w http.ResponseWriter, r *http.Request)

ProcessAllowed deletes the store code cookie if found and stores are equal or sets a store code cookie if the stores differ. Implements interface store.CodeProcessor.

func (*ProcessStoreCodeCookie) ProcessDenied

func (a *ProcessStoreCodeCookie) ProcessDenied(_ scope.TypeID, _, _ int64, w http.ResponseWriter, r *http.Request)

ProcessDenied deletes the store code cookie, if a store cookie can be found. Implements interface store.CodeProcessor.

type RunModeFunc

type RunModeFunc func(*http.Request) scope.TypeID

RunModeFunc type is an adapter to allow the use of ordinary functions as Calculater. If f is a function with the appropriate signature, RunModeFunc(f) is a Handler that calls f.

func (RunModeFunc) CalculateRunMode

func (f RunModeFunc) CalculateRunMode(r *http.Request) scope.TypeID

CalculateRunMode calls f(r).