Attribute Macro head

#[head]

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 path to be explicitly specified:

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

Grammar

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

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

path := ('/' segment)*

query := segment ('&' segment)*

segment := URI_SEG
         | SINGLE_PARAM
         | MULTI_PARAM

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

SINGLE_PARAM := '<' IDENT '>'
MULTI_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, except `_`

The generic route attribute is defined as:

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

Typing Requirements

Every identifier that appears in a dynamic parameter (SINGLE_PARAM or MULTI_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 MULTI) 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>	FromFormValue
query	<ident..>	FromQuery
data	<ident>	FromData

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

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

Semantics

The attribute generates three items:

1. 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 parameters from left to right as declared in the function argument list.

      If a path or query parameter guard fails, the request is forwarded.

   3. Data parameter, 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 Outcomes 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.

2. 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.

3. A macro used by uri! to type-check and generate an Origin.