parameters

Documentation

Overview

Package parameters provides HTTP request parameter decoding and validation.

Use this package to populate struct fields from HTTP request data including URL query parameters, HTTP headers, URL path parameters, and JSON request bodies. The package automatically validates the decoded struct using the validation package.

Struct fields are tagged to indicate their source:

• urlQuery: extracts from URL query parameters
• httpHeader: extracts from HTTP headers
• urlPath: extracts from URL path parameters
• json: extracts from JSON request body

Fields with urlQuery, httpHeader, or urlPath tags must also include a json:"-" tag to prevent conflicts with JSON body parsing. The Decode function handles all parameter sources in a single call and closes the request body when complete.

Index

• func Decode[T any](request *http.Request) (*T, error)
• func ExtractAndValidateFieldTagLookupKeys[T any]() (map[Tag]LookupKeyToFieldName, error)
• func TagLookupKeyFollowsNamingConvention(lookupKey string) bool
• type LookupKeyToFieldName
• type Tag

Functions

func Decode

func Decode[T any](request *http.Request) (*T, error)

Decode populates a parameter struct with values from an HTTP request. After decoding, it validates the struct and closes the request body.

func ExtractAndValidateFieldTagLookupKeys

func ExtractAndValidateFieldTagLookupKeys[T any]() (map[Tag]LookupKeyToFieldName, error)

ExtractAndValidateFieldTagLookupKeys validates the struct tags and returns a map of unique tag lookup keys for each field in the struct.

type MyStruct struct {
	HeaderParameter string `httpHeader:"x-my-parameter" json:"-"`
	PathParameter   string `urlPath:"my-id" json:"-"`
}

Returns the following map:

{
	"httpHeader": {
		"x-my-parameter": "HeaderParameter"
	},
	"urlPath": {
		"my-id": "PathParameter"
	}
}

func TagLookupKeyFollowsNamingConvention

func TagLookupKeyFollowsNamingConvention(lookupKey string) bool

TagLookupKeyFollowsNamingConvention verifies if the tag value (the lookup key) follows the naming convention.

Types

type LookupKeyToFieldName

type LookupKeyToFieldName map[string]string

LookupKeyToFieldName is the tag's lookup key to the name of the field on the struct.

type MyStruct struct {
	HeaderParameter string `httpHeader:"x-my-parameter" json:"-"`
}

Returns the following map:

{
	"x-my-parameter": "MyParameter",
}

type Tag

type Tag string

Tag is a string of metadata associated at compile time with a field of a struct.

type MyStruct struct {
	HeaderParameter string `httpHeader:"x-my-parameter"`
}

In this case, the tag would be "httpHeader".

const (
	// QueryTag is a struct field tag used to specify that the field's value should be sourced from URL query parameters.
	QueryTag Tag = "urlQuery"

	// HeaderTag is a struct field tag used to specify that the field's value should be sourced from the HTTP headers.
	HeaderTag Tag = "httpHeader"

	// PathTag is a struct field tag used to specify that the field's value should be sourced from the URL path parameters.
	PathTag Tag = "urlPath"

	// JSONTag is a struct field tag used to specify that the field's value should be sourced from the request JSON body.
	JSONTag Tag = "json"

	// TagLookupKeyNamingConvention is the naming convention a tags lookup key must adhere to.
	TagLookupKeyNamingConvention = `^[a-zA-Z][a-zA-Z0-9_-]*$`
)