README
¶
witchcraft-go-params
witchcraft-go-params defines the wparams package, which provides the ParamStorer interface and functions for
storing and retrieving ParamStorer implementations in from a context.
Conceptually, "params" are values that are associated with a specific key that provide context about an operation that is being performed. Params are categorized as "safe" or "unsafe" -- "safe" params are parameters which are considered safe to ship/export/expose off-premises, while "unsafe" parameters are parameters that should not leave the premises. Param values are typically used by things such as loggers and errors to provide further context for an operation. Keys are case-sensitive and must be unique across both safe and unsafe parameters.
The following is a short example of a canonical use case:
type UserID int64
func UpdateUserInfo(ctx context.Context, userID UserID, info UserInfo) error {
ctx = wparams.ContextWithSafeParam(ctx, "userId", userID)
svc1log.FromContext(ctx).Info("Updating user information", svc1log.Params(wparams.ParamsFromContext(ctx)))
if err := validateInput(ctx, info); err != nil {
return err
}
// ...
return nil
}
func validateInput(ctx context.Context, info UserInfo) error {
if info.Name == "" {
return werror.Error("invalid user info", werror.Params(wparams.ParamsFromContext(ctx)))
}
// ...
return nil
}
In this example, "userId" and its value are registered as a safe parameter on the context at the beginning of the
UpdateUserInfo function. This function (and the other functions that it calls) extract the safe and unsafe parameters
from the context when performing operations such as logging or creating errors. This makes it such that the logger
messages and errors are provided with all of the relevant parameters for their operation, along with the knowledge of
whether the parameters are safe and unsafe.
If a specific type will be recorded as a parameter often and there is a sensible default value for its name and
safe/unsafe status, it may make sense to have the type implement the ParamStorer interface directly. For example, if
UserID is known to be safe and should always be recorded as "userId", the example above could be updated as follows:
type UserID int64
func (id UserID) SafeParams() map[string]interface{} {
return map[string]interface{}{
"userId": id,
}
}
func (id UserID) UnsafeParams() map[string]interface{} {
return nil
}
func UpdateUserInfo(ctx context.Context, userID UserID, info UserInfo) error {
ctx = wparams.ContextWithParams(ctx, userID)
// the rest is the same as the first example
}
This pattern allows a type to dictate its default behavior for its name and whether it is safe/unsafe, which makes it easier to ensure that the parameter is consistent across various usages.
License
This project is made available under the Apache 2.0 License.
Documentation
¶
Index ¶
- func ContextWithParamStorers(ctx context.Context, params ...ParamStorer) context.Context
- func ContextWithSafeAndUnsafeParams(ctx context.Context, safeParams, unsafeParams map[string]interface{}) context.Context
- func ContextWithSafeParam(ctx context.Context, key string, value interface{}) context.Context
- func ContextWithSafeParams(ctx context.Context, safeParams map[string]interface{}) context.Context
- func ContextWithUnsafeParam(ctx context.Context, key string, value interface{}) context.Context
- func ContextWithUnsafeParams(ctx context.Context, unsafeParams map[string]interface{}) context.Context
- func SafeAndUnsafeParamsFromContext(ctx context.Context) (safeParams map[string]interface{}, unsafeParams map[string]interface{})
- type ParamStorer
- func NewParamStorer(paramStorers ...ParamStorer) ParamStorer
- func NewSafeAndUnsafeParamStorer(safeParams, unsafeParams map[string]interface{}) ParamStorer
- func NewSafeParam(key string, value interface{}) ParamStorer
- func NewSafeParamStorer(safeParams map[string]interface{}) ParamStorer
- func NewUnsafeParam(key string, value interface{}) ParamStorer
- func NewUnsafeParamStorer(unsafeParams map[string]interface{}) ParamStorer
- func ParamStorerFromContext(ctx context.Context) ParamStorer
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ContextWithParamStorers ¶
func ContextWithParamStorers(ctx context.Context, params ...ParamStorer) context.Context
ContextWithParamStorers returns a copy of the provided context that contains all of the safe and unsafe parameters provided by the provided ParamStorers. If the provided context already has safe/unsafe params, the newly returned context will contain the result of merging the previous parameters with the provided parameters.
func ContextWithSafeAndUnsafeParams ¶
func ContextWithSafeAndUnsafeParams(ctx context.Context, safeParams, unsafeParams map[string]interface{}) context.Context
ContextWithSafeAndUnsafeParams returns a copy of the provided context that contains the provided safe and unsafe parameters. If the provided context already has safe/unsafe params, the newly returned context will contain the result of merging the previous parameters with the provided parameters.
func ContextWithSafeParam ¶
ContextWithSafeParam returns a copy of the provided context that contains the provided safe parameter. If the provided context already has safe/unsafe params, the newly returned context will contain the result of merging the previous parameters with the provided parameter.
func ContextWithSafeParams ¶
ContextWithSafeParams returns a copy of the provided context that contains the provided safe parameters. If the provided context already has safe/unsafe params, the newly returned context will contain the result of merging the previous parameters with the provided parameters.
func ContextWithUnsafeParam ¶
ContextWithUnsafeParam returns a copy of the provided context that contains the provided unsafe parameter. If the provided context already has safe/unsafe params, the newly returned context will contain the result of merging the previous parameters with the provided parameter.
func ContextWithUnsafeParams ¶
func ContextWithUnsafeParams(ctx context.Context, unsafeParams map[string]interface{}) context.Context
ContextWithUnsafeParams returns a copy of the provided context that contains the provided unsafe parameters. If the provided context already has safe/unsafe params, the newly returned context will contain the result of merging the previous parameters with the provided parameters.
func SafeAndUnsafeParamsFromContext ¶
func SafeAndUnsafeParamsFromContext(ctx context.Context) (safeParams map[string]interface{}, unsafeParams map[string]interface{})
SafeAndUnsafeParamsFromContext returns the safe and unsafe parameters stored in the ParamStorer returned by ParamStorerFromContext for the provided context. Returns nil maps if the provided context does not have a ParamStorer.
Types ¶
type ParamStorer ¶
type ParamStorer interface {
SafeParams() map[string]interface{}
UnsafeParams() map[string]interface{}
}
ParamStorer is a type that stores safe and unsafe parameters. Keys should be unique across both SafeParams and UnsafeParams (that is, if a key occurs in one map, it should not occur in the other). For performance reasons, the maps returned by SafeParams and UnsafeParams are references to the underlying storage and should not be modified by the caller.
func NewParamStorer ¶
func NewParamStorer(paramStorers ...ParamStorer) ParamStorer
NewParamStorer returns a new ParamStorer that stores all of the params in the provided ParamStorer inputs. The params are added from the param storers in the order in which they are provided, and for each individual param storer all of the safe params are added before the unsafe params while maintaining key uniqueness across both safe and unsafe parameters. This means that, if the same parameter is provided by multiple ParamStorer inputs, the returned ParamStorer will have the key (including safe/unsafe type) and value as provided by the last ParamStorer (for example, if an unsafe key/value pair is provided by one ParamStorer and a later ParamStorer specifies a safe key/value pair with the same key, the returned ParamStorer will store the last safe key/value pair).
func NewSafeAndUnsafeParamStorer ¶
func NewSafeAndUnsafeParamStorer(safeParams, unsafeParams map[string]interface{}) ParamStorer
NewSafeAndUnsafeParamStorer returns a new ParamStorer that stores the provided safe parameters as SafeParams and the unsafe parameters as UnsafeParams. If the safeParams and unsafeParams have any keys in common, the key/value pairs in the unsafeParams will be used (the conflicting key/value pairs provided by safeParams will be ignored).
func NewSafeParam ¶ added in v1.2.0
func NewSafeParam(key string, value interface{}) ParamStorer
NewSafeParam returns a new ParamStorer that stores a single safe parameter.
func NewSafeParamStorer ¶
func NewSafeParamStorer(safeParams map[string]interface{}) ParamStorer
NewSafeParamStorer returns a new ParamStorer that stores the provided parameters as SafeParams.
func NewUnsafeParam ¶ added in v1.2.0
func NewUnsafeParam(key string, value interface{}) ParamStorer
NewUnsafeParam returns a new ParamStorer that stores a single unsafe parameter.
func NewUnsafeParamStorer ¶
func NewUnsafeParamStorer(unsafeParams map[string]interface{}) ParamStorer
NewUnsafeParamStorer returns a new ParamStorer that stores the provided parameters as UnsafeParams.
func ParamStorerFromContext ¶
func ParamStorerFromContext(ctx context.Context) ParamStorer
ParamStorerFromContext returns the ParamStorer stored in the provided context. Returns nil if the provided context does not contain a ParamStorer.
Source Files