[GH-1319] Add Support for Path Style Parameter Expansion

[kdavisk6]

Fixes #1319

This change adds limited Path Style support to Feign URI template-style
templates. Variable expressions that start with a semi-colon ;
are now expanded in accordance to RFC 6570 Section 3.2.7
with the following modifications:

• Maps and Lists are expanded by default.
• Only Single variable templates are supported.

Examples:

{;who}             ;who=fred
{;half}            ;half=50%25
{;empty}           ;empty
{;list}            ;list=red;list=green;list=blue
{;keys}            ;semi=%3B;dot=.;comma=%2C

[velo]

LGTM, it probably would be nice to have a Feign client example using this param expansion

[kdavisk6]

Agreed. I'll update. I'm also going to export this expression as an Expander so it can be used directly be extending contracts.

[dpodder]

Hi @kdavisk6 - thank you for working on this support!

One project I'm working on has a use case where the server expects an optional Map of ;key=value pairs - such that the values are optional. E.g., assuming

/path/from{;map}/values

Here are some expected expansions:

• Case 1 - map := {} (empty)

  /path/from/values
  

• Case 2 - map := {"a": "1", "b": "", "c": "3"}

  /path/from;a=1;b=;c=3/values
  

  or:

  /path/from;a=1;b;c=3/values
  

Would these use cases work, or could the current solution be extended to support them?

[kdavisk6]

@dpodder

We'll adhere to the URI template specification:
https://datatracker.ietf.org/doc/html/rfc6570#section-3.2.7

the spec defines these use cases:

Example Template     Expansion

       {;who}             ;who=fred
       {;half}            ;half=50%25
       {;empty}           ;empty
       {;v,empty,who}     ;v=6;empty;who=fred
       {;v,bar,who}       ;v=6;who=fred
       {;x,y}             ;x=1024;y=768
       {;x,y,empty}       ;x=1024;y=768;empty
       {;x,y,undef}       ;x=1024;y=768
       {;hello:5}         ;hello=Hello
       {;list}            ;list=red,green,blue
       {;list*}           ;list=red;list=green;list=blue
       {;keys}            ;keys=semi,%3B,dot,.,comma,%2C
       {;keys*}           ;semi=%3B;dot=.;comma=%2C

In the spec ,empty would result in the name being included. To achieve the behavior you are looking for, the map would need to be undefined, which in our world would be null. There are more hints in the spec that explain this behavior:

` else if an explode modifier is given, then

      *  if named is true, then for each defined list member or array
         (name, value) pair with a defined value, do:

         +  if this is not the first defined member/value, append the
            sep string to the result string;

         +  if this is a list, append the varname to the result string
            using the same encoding process as for literals;

         +  if this is a pair, append the name to the result string
            using the same encoding process as for literals;

         +  if the member/value is empty, append the ifemp string to the
            result string; otherwise, append "=" and the member/value to
            the result string, after pct-encoding any member/value
            characters that are not in the allow set.

      *  else if named is false, then

         +  if this is a list, append each defined list member to the
            result string, after pct-encoding any characters that are
            not in the allow set, with the sep string appended to the
            result between each defined list member.

         +  if this is an array of (name, value) pairs, append each pair
            with a defined value to the result string as "name=value",
            after pct-encoding any characters that are not in the allow
            set, with the sep string appended to the result between each
            defined pair.

[dpodder]

@kdavisk6 - thank you for the clarification and details pointing out the relevant details from the spec! It looks like the {;keys*} example supported by the spec is exactly the behavior we're looking for, and would expand correctly for our cases. (Edit to add:) which with the caveat mentioned in the readme, would need to be used as {;keys} for us, but no big deal.