httprule

func ParseSegments ¶

func ParseSegments(pathTemplate string) (*api.PathTemplate, error)

ParseSegments parses a PathTemplate, defined at the google.api.http annotation.

The following documentation was copied and adapted from the C++ HTTP Annotation parser

A `google.api.http` annotation describes how to convert gRPC RPCs to HTTP URLs. The description uses a "path template", showing what portions of the URL path are replaced with values from the gRPC request message.

These path templates follow a specific grammar. The grammar is defined by:

Template = "/" Segments [ Verb ] ;
Segments = Segment { "/" Segment } ;
Segment  = "*" | "**" | LITERAL | Variable ;
Variable = "{" FieldPath [ "=" Segments ] "}" ;
FieldPath = IDENT { "." IDENT } ;
Verb     = ":" LITERAL ;

The specific notation is not defined, but it seems inspired by Backus-Naur Form. In this notation, `{ ... }` allows repetition.

The documentation goes on to say:

A variable template must not contain other variables.

So the grammar is better defined by:

Template = "/" Segments [ Verb ] ;
Segments = Segment { "/" Segment } ;
Segment  = Variable | PlainSegment;
PlainSegment  = "*" | "**" | LITERAL ;
Variable = "{" FieldPath [ "=" PlainSegments ] "}" ;
PlainSegments = PlainSegment { "/" PlainSegment };
FieldPath = IDENT { "." IDENT } ;
Verb     = ":" LITERAL ;

Neither "IDENT" nor "LITERAL" are defined. From context we can infer that IDENT must be a valid proto3 identifier, so matching the regular expression `[A-Za-z][A-Za-z0-9_]*`. Likewise, we can infer that LITERAL must be a path segment in a URL. RFC 3986 provides a definition for these, which we summarize as:

Segment = pchar { pchar } pchar = unreserved | pct-encoded | sub-delims | ":" | "@" unreserved = ALPHA | DIGIT | "-" | "." | "_" | "~" pct-encoded = "%" HEXDIG HEXDIG sub-delims = "!" | "$" | "&" | "'" | "(" | ")" | "*" | "+" | "," | ";" | "="

ALPHA = [A-Za-z] DIGIT = [0-9] HEXDIG = [0-9A-Fa-f]

Because pchar includes special characters like ':' and '*', which are part of the HTTP Rule spec, we define LITERAL as the following subset of pchar:

LITERAL = unreserved | pct-encoded { unreserved | pct-encoded }