fix(api_core): improve rest path validation

[daniel-sanche]

Context: b/532254612

[gemini-code-assist]

Code Review

This pull request introduces path traversal validation and percent-encoding for variables within path templates in google/api_core/path_template.py, along with corresponding unit tests. The feedback highlights a potential security bypass in _extract_and_validate_wildcards where path traversal sequences (like projects/..) could bypass validation if the value does not match the sub-template or if the template is single-segment. It is recommended to apply _validate_multi_segment_value to these edge cases and add tests to verify that these bypasses are successfully blocked.

[chalmerlowe]

Some comments and suggestions.

[chalmerlowe]

#NIT
I do not know how often _extract_and_validate_wildcards gets called. IF it is regular occurrence we will be executing the f-string and ValueError creation every single time we call the function, even when we don't have an error condition.

If we call the function often AND errors are expected to be rare then a factory function (def create_err_msg()) to generate an err message only when we raise (a la: raise create_err_msg()) could be useful.

[chalmerlowe]

#PREFERENCE/QUESTION:
Could we benefit from changing the order of operations?

If the REST API is a standard web service, 99.9% of incoming requests will be normal path segments (like "api", "v1", "users", "12345"). They will rarely be "." or "..".

This means our first check (the tuple check) will "miss" 99.9% of the time, forcing Python to execute the _validate_multi_segment_value anyway.

We can bypass the tuple lookup entirely by rewriting the logic. Since we know that _validate_multi_segment_value(val) already natively returns False for dots ("." OR ".."), we can drop the tuple check entirely to save a few cycles on every normal path

# Optimized for the 99.9% use-case (normal path segments)

if val and not _validate_multi_segment_value(val):

Why this is faster for REST routing:

Old Way (Normal Path): Checks tuple (Misses a lot), Checks if val (True), then Runs the function

New Way (Normal Path): Checks val (True) then Runs the Function.

[chalmerlowe]

#QUESTION

There is a subtle inconsistency in how we handle empty strings between the two if statements and the else statement. Is this intentional?

Snippet 1: Handling Single Segments (*)

This block checks if the template is for a single segment (like *).

    # Single-segment templates (None or "*") cannot match exactly "." or ".."
    # and cannot have multi-segment paths resolving to 0 segments.
    if template_str is None or template_str == "*":
        if val in (".", "..") or (val and not _validate_multi_segment_value(val)):
            raise err
        return

What happens if val is an empty string ("")?
The check val in (".", "..") is False.
Then it checks (val and not _validate_multi_segment_value(val)). Since val is "" (which is "falsy" in Python), the val and part evaluates to False.
The whole condition immediately evaluates to False, so it bypasses the error and returns successfully. An empty string is allowed here.

Snippet 2: Handling Bare Multi-Segments (**)

This block checks if the template is a bare double star (like **).

    # Multi-segment templates ("**") must represent at least one valid, non-escaped segment.
    if template_str == "**":
        if not _validate_multi_segment_value(val):
            raise err
        return

What happens if val is an empty string ("")?
There is no val and guard here. It calls _validate_multi_segment_value("") directly.
If we trace _validate_multi_segment_value(""), it splits the empty string into segments, ends up with 0 leftover segments, and returns False.
So not _validate_multi_segment_value("") becomes not False which is True.
So this snippet raises an error. An empty string is rejected here.

Snippet 3: Falling back for Complex Templates

This block is at the very end of the function, handling cases where the value didn't match the expected complex pattern (e.g. something like projects/{project}/locations/{location}).

    else:
        # For values that don't match the pattern, ensure the value doesn't
        # resolve to 0 segments (e.g. "projects/..").
        if val and not _validate_multi_segment_value(val):
            raise err

What happens if val is an empty string ("")?
Just like Snippet 1, we have a val and guard here.
Since val is "" (falsy), the condition val and ... is False.
It bypasses the error. An empty string is allowed here.

Why this is inconsistent:

If a user passes an empty string "" as the value:

• If the template is * (Snippet 1), it passes.
• If the template is ** (Snippet 2), it fails.
• If the template is a complex pattern (Snippet 3), it passes.

Is this difference in behavior intentional?

[chalmerlowe]

#PREFERENCE: Above we define constants that can be applied to the return values for each of these conditions. I recommend we use them:

# Segment expressions used for validating paths against a template.
_SINGLE_SEGMENT_PATTERN = r"([^/]+)"
_MULTI_SEGMENT_PATTERN = r"(.+)"

[chalmerlowe]

#PREFERENCE:

I recommend some additional checks to cover some more edge cases:

Suggested change

	("..", False),
	("..", False),
	("", False),
	("/", False),
	("//", False),
	("a/../../b", False),
	("../..", False),

[chalmerlowe]

QUESTION: What if the template is just "projects/my-project" with no wildcards at all? It should return the literal escaped and an empty tuple of wildcard types. Do you think we should add the sanity check to ensure the regex parser doesn't choke on plain strings?

("projects/my-project", "projects/my-project", ()),