Allow escaped colons in route paths for Google API compliance

[yuxialuozi]

Feature Description

Description

The current router implementation does not allow for colons in the route path immediately following a path parameter. This prevents us from following the Google API Design Guide for Custom Methods, which recommends using the pattern {resource}/{id}:customVerb for custom operations.

According to the Google API specification, custom methods should use a colon suffix after the resource identifier:

POST /v1/projects/{project}:archive
POST /v1/files/{file}:undelete
POST /v1/instances/{instance}:stop

Current Behavior

When attempting to register a route with an escaped colon following a path parameter (e.g., /v1/projects/:name\:undelete), Gin panics during application startup:

panic: only one wildcard per path segment is allowed, has: ':name\:undelete' in path '/v1/projects/:name\:undelete'

goroutine 1 [running]:
github.com/gin-gonic/gin.(*node).insertChild(...)
    github.com/gin-gonic/gin@v1.11.0/tree.go:308

Steps to Reproduce

package main

import (
    "fmt"
    "github.com/gin-gonic/gin"
)

func main() {
    r := gin.Default()

    // This will panic at startup
    r.POST("/v1/projects/:name\\:undelete", func(c *gin.Context) {
        name := c.Param("name")
        c.JSON(200, gin.H{
            "message":   fmt.Sprintf("Project %s undeleted", name),
            "projectId": name,
        })
    })

    r.Run(":8088")
}

Expected URL pattern: POST /v1/projects/proj123:undelete
Actual result: Panic during route registration

Screenshots

Expected Behavior

The route should register successfully and handle requests like:

curl -X POST "http://localhost:8088/v1/projects/proj123:undelete"

Where proj123 is captured as the :name parameter, and :undelete is treated as a literal string (custom method) rather than another parameter.

Proposed Solution

Modify the router's findWildcard function in tree.go to support escaped colons (\:), treating them as literal characters rather than parameter delimiters.

Key changes needed:

1. Allow \: escape sequence in route path definitions
2. Skip escaped colons when identifying wildcard boundaries
3. Remove escape characters when matching actual requests

Impact

This feature would enable Gin users to:

• ✅ Follow Google Cloud API design standards
• ✅ Build APIs compatible with gRPC Gateway and other Google API tools
• ✅ Use industry-standard custom method patterns
• ✅ Maintain consistency with other Google API implementations

Additional Context

• Similar issue was partially addressed in Echo framework: allow escaping of colon in route path  labstack/echo#1988

Contribution

I'm willing to contribute a PR to implement this feature if the maintainers are open to it. I've already identified the necessary changes in the tree.go file and can provide a backward-compatible implementation with comprehensive tests.

Environment:

• Gin version: v1.11.0
• Go version: go1.21+
• OS: Windows

[yuxialuozi]

I may have misunderstood Google's intention, or Google indeed means this, but it's very difficult for me to implement. So I'll close this PR for now. There have been many parameter binding errors and route matching errors. Additionally, I suggest using /v1/files/123/push instead of /v1/files/123:push.

[anfaas1618]

hey @yuxialuozi can i try it , is it required by google api compliance ?