Attribute Macro rocket_codegen::head

source ·

#[head]

Expand description

Attribute to generate a Route and associated metadata.

This and all other route attributes can only be applied to free functions:

#[get("/")]
fn index() -> &'static str {
    "Hello, world!"
}

There are 7 method-specific route attributes:

get - GET specific route
put - PUT specific route
post - POST specific route
delete - DELETE specific route
head - HEAD specific route
options - OPTIONS specific route
patch - PATCH specific route

Additionally, route allows the method and uri to be explicitly specified:

#[route(GET, uri = "/")]
fn index() -> &'static str {
    "Hello, world!"
}

Grammar

The grammar for all method-specific route attributes is defined as:

route := '"' uri ('?' query)? '"' (',' parameter)*

uri := ('/' segment)*

query := segment ('&' segment)*

segment := URI_SEG
         | SINGLE_PARAM
         | TRAILING_PARAM

parameter := 'rank' '=' INTEGER
           | 'format' '=' '"' MEDIA_TYPE '"'
           | 'data' '=' '"' SINGLE_PARAM '"'

SINGLE_PARAM := '<' IDENT '>'
TRAILING_PARAM := '<' IDENT '..>'

URI_SEG := valid, non-percent-encoded HTTP URI segment
MEDIA_TYPE := valid HTTP media type or known shorthand

INTEGER := unsigned integer, as defined by Rust
IDENT := valid identifier, as defined by Rust

The generic route attribute is defined as:

generic-route := METHOD ',' 'uri' '=' route

Every identifier, except for _, that appears in a dynamic parameter (SINGLE_PARAM or TRAILING_PARAM) must appear as an argument to the function. For example, the following route requires the decorated function to have the arguments foo, baz, msg, rest, and form:

#[get("/<foo>/bar/<baz..>?<msg>&closed&<rest..>", data = "<form>")]

The type of each function argument corresponding to a dynamic parameter is required to implement one of Rocket’s guard traits. The exact trait that is required to be implemented depends on the kind of dynamic parameter (SINGLE or TRAILING) and where in the route attribute the parameter appears. The table below summarizes trait requirements:

position	kind	trait
path	`<ident>`	`FromParam`
path	`<ident..>`	`FromSegments`
query	`<ident>`	`FromForm`
query	`<ident..>`	`FromForm`
data	`<ident>`	`FromData`

The type of each function argument that does not have a corresponding dynamic parameter is required to implement the FromRequest trait.

A route argument declared a _ must not appear in the function argument list and has no typing requirements.

The return type of the decorated function must implement the Responder trait.

Semantics

The attribute generates three items:

A route Handler.

The generated handler validates and generates all arguments for the generated function according to the trait that their type must implement. The order in which arguments are processed is:
1. Request guards from left to right.
  
  If a request guard fails, the request is forwarded if the Outcome is Forward or failed if the Outcome is Failure. See FromRequest Outcomes for further detail.
2. Path and query guards in an unspecified order. If a path or query guard fails, the request is forwarded.
3. Data guard, if any.
  
  If a data guard fails, the request is forwarded if the Outcome is Forward or failed if the Outcome is Failure. See FromData for further detail.
If all validation succeeds, the decorated function is called. The returned value is used to generate a Response via the type’s Responder implementation.
A static structure used by routes! to generate a Route.

The static structure (and resulting Route) is populated with the name (the function’s name), path, query, rank, and format from the route attribute. The handler is set to the generated handler.
A macro used by uri! to type-check and generate an Origin.

Attribute Macro rocket_codegen::head

Grammar

Typing Requirements

Semantics