resttools

Documentation

Index

• Constants
• Variables
• func CheckEnum(payload jsonPayload, fieldPath []protoreflect.Name) (fieldName string, ok bool)
• func CheckFieldNames(payload jsonPayload) error
• func CheckJSONEnumFields(payload jsonPayload, fieldsToCheck [][]protoreflect.Name) error
• func CheckRESTBody(jsonReader io.Reader, message protoreflect.Message) error
• func ComputeEnumFields(message protoreflect.Message) [][]protoreflect.Name
• func FromJSON() *protojson.UnmarshalOptions
• func GetEnumFields(message protoreflect.Message) [][]protoreflect.Name
• func KeysMatchPath(examine map[string][]string, lookFor []string) []string
• func PopulateFields(protoMessage proto.Message, fieldValues map[string][]string) error
• func PopulateOneField(protoMessage proto.Message, fieldPath string, fieldValues []string) error
• func PopulateSingularFields(protoMessage proto.Message, fieldValues map[string]string) error
• func ToDottedLowerCamel(fieldPath string) string
• func ToJSON() *protojson.MarshalOptions
• type JSONMarshalOptions
  • func (jm *JSONMarshalOptions) Replace(opt *protojson.MarshalOptions)
  • func (jm *JSONMarshalOptions) Restore()

Constants

const (
	// CharsField contains the characters allowed in a field name (URL path or body)
	CharsField = `-_.0-9a-zA-Z`

	// CharsLiteral contains the the characters allowed in a URL path literal segment.
	CharsLiteral = `-_.~0-9a-zA-Z%`

	// RegexURLPathSingleSegmentValue contains the regex expression for matching a single URL
	// path segment (i.e. `/` is not allowed). Since gorilla/mux hands uses the decoded paths to
	// match, we can just accept any characters.
	RegexURLPathSingleSegmentValue = ".+"

	// RegexURLPathSingleSegmentValue contains the regex expression for matching multiple URL
	// path segments (i.e. `/` is allowed). Since gorilla/mux hands uses the decoded paths to
	// match, we can just accept any characters.
	RegexURLPathMultipleSegmentValue = ".+"
)

Variables

var (
	// CharsFieldPath contains the characters allowed in a dotted field path.
	CharsFieldPath string

	// RegexField contains the regex expression for matching a single (not nested) field name.
	RegexField string

	// RegexField contains the regex expression for matching a dotted field path.
	RegexFieldPath string

	// RegexLiteral contains the regex expression for matching a URL path literal segment.
	RegexLiteral string
)

Functions

func CheckEnum

func CheckEnum(payload jsonPayload, fieldPath []protoreflect.Name) (fieldName string, ok bool)

CheckEnum verifies whether the field whose qualified name is captured in the elements of fieldPath has a string value, if it exists, in the JSON representation captured by payload. This returns the qualified field name (as present as it is in payload) as a single string, and a boolean that is true only if either fieldPath is not present or if its value is a string. This means that if fieldPath is a path to an enum field, the boolean will be false if the enum is encoded in the payload using a non-string representation.

func CheckFieldNames

func CheckFieldNames(payload jsonPayload) error

CheckFieldNames checks that the field names in the JSON request body are properly formatted (lower-camel-cased).

func CheckJSONEnumFields

func CheckJSONEnumFields(payload jsonPayload, fieldsToCheck [][]protoreflect.Name) error

CheckJSONEnumFields verifies that each of the fields listed in fieldsToCheck, presumably all referring to enum fields, are encoded correctly in the parsed JSON payload, meaning that the field is absent or its value is a string. Each element of fieldsToCheck is a qualified proto field name represented as a sequence of simple protoreflect.Name.

func CheckRESTBody

func CheckRESTBody(jsonReader io.Reader, message protoreflect.Message) error

CheckRESTBody verifies that any enum fields in message are properly represented in the JSON payload carried by jsonReader: the fields must be either absent or have lower-camel-cased names.

func ComputeEnumFields

func ComputeEnumFields(message protoreflect.Message) [][]protoreflect.Name

ComputeEnumFields determines which fields in message or its submessages are enums, and returns a list of those qualified field names (each one of those being a list of simple protoreflect.Name).

func FromJSON

func FromJSON() *protojson.UnmarshalOptions

FromJSON returns a copy of the current global JSON unmarshaling options. Modifications to this copy do not change the values of these options returned in subsequent calls to this function. This is the function Showcase REST endpoints should use to handle JSON unmarshaling.

func GetEnumFields

func GetEnumFields(message protoreflect.Message) [][]protoreflect.Name

GetEnumFields returns a list of any arbitrarily nested fields in message that are enums. Each member of the returned list is a qualified field name, itself represented as a list of simple protoreflect.Name.

func KeysMatchPath

func KeysMatchPath(examine map[string][]string, lookFor []string) []string

KeysMatchPath returns the keys in `examine` that match any of the elements in `lookFor`, interpreting the latter as dotted-field paths. This means a match occurs when (a) the two are identical, or (b) when any element of `lookFor` is a prefix of the `examine` key and is followed by a period. For example: KeysMatchPath(map[string][]string{"loc": nil, "loc.lat": nil, "location":nil},

         []string{"loc"})
== []string{"loc","loc.lat"}

func PopulateFields

func PopulateFields(protoMessage proto.Message, fieldValues map[string][]string) error

PopulateFields sets the fields within protoMessage to the values provided in fieldValues. The fields and values are provided as a map of field paths to lists of string representations of their values. The field paths can refer to fields nested arbitrarily deep within protoMessage; each path element must be lower-camel-cased. `fieldValues` contains the list of values applicable to the field: a single value of singular fields, or ordered values for a repeated field. This returns an error if any field path is not valid or if any value can't be parsed into the correct data type for the field.

func PopulateOneField

func PopulateOneField(protoMessage proto.Message, fieldPath string, fieldValues []string) error

PopulateOneField finds in protoMessage the field identified by fieldPath (which could refer to an arbitrarily nested field using dotted notation; each path element must be lower-camel-cased) and sets it to `value`. It returns an error if the fieldPath does not properly reference a field, or if `fieldValues` could not be parsed into a list of the data type expected for the field. `fieldValues` is a slice to allow passing a series of repeated field entries.

func PopulateSingularFields

func PopulateSingularFields(protoMessage proto.Message, fieldValues map[string]string) error

PopulateSingularFields sets the fields within protoMessage to the values provided in fieldValues. The fields and values are provided as a map of field paths to the string representation of their values. The field paths can refer to fields nested arbitrarily deep within protoMessage; each path element must be lower-camel-cased. This returns an error if any field path is not valid or if any value can't be parsed into the correct data type for the field.

func ToDottedLowerCamel

func ToDottedLowerCamel(fieldPath string) string

ToDottedLowerCamel converts each segment of a dot-delimited fieldPath to be individually lower-camel-cased; the dots are preserved.

func ToJSON

func ToJSON() *protojson.MarshalOptions

ToJSON returns a copy of the current global JSON marshaling options in JSONMarshaler. Modifications to this copy do not change the values of these options returned in subsequent calls to this function. This is the function Showcase REST endpoints should use to handle JSON marshaling.

Types

type JSONMarshalOptions

type JSONMarshalOptions struct {
	// contains filtered or unexported fields
}

JSONMarshalOptions contains the current JSON marshaling options used by REST endpoints, and allows for temporarily replacing these global options and then restoring them. This functionality is useful for some tests.

var JSONMarshaler JSONMarshalOptions

JSONMarshaler captures the JSON marshaling options. It is intended only for tests of Showcase functionality (not for normal Showcase use or tests of generators against Showcase).

func (*JSONMarshalOptions) Replace

func (jm *JSONMarshalOptions) Replace(opt *protojson.MarshalOptions)

Replace replaces the current JSON marshaling options with those provided by opt. Call Restore() to restore the production options. Only one replacement can be active at a time; subsequent calls hang waiting for the first call's mutex to be released.

As a special case, if opt==nil, the replacement is with the production options themselves; this is useful for tests that need to lock the production options to protect from other tests which may need to change them.

func (*JSONMarshalOptions) Restore

func (jm *JSONMarshalOptions) Restore()

Restore restores the production JSON marshaling options. There must be an active Replace() called previously.