Macro metadata 

macro_rules! metadata {
    ( @for $request_type:ty, $( $field:ident: $rhs:tt ),+ $(,)? ) => { ... };
    ( $( $field:ident: $rhs:tt ),+ $(,)? ) => { ... };
    ( @field method: $method:ident ) => { ... };
    ( @field rate_limited: $rate_limited:literal ) => { ... };
    ( @field authentication: $scheme:path ) => { ... };
    ( @field path: $path:literal ) => { ... };
    ( @field history: {
        $( unstable $(($unstable_feature:literal))? => $unstable_path:literal, )*
        $( stable ($stable_feature_only:literal) => $stable_feature_path:literal, )?
        $( $( $version:literal $(| stable ($stable_feature:literal))? => $rhs:tt, )+ )?
    } ) => { ... };
    ( @history_impl
        [ $( $unstable_path:literal $(= $unstable_feature:literal)? ),* ]
        $( stable ($stable_feature_only:literal) => $stable_feature_path:literal, )?
        $(
            $( $stable_path:literal = $version:literal $(| stable ($stable_feature:literal))? ),+
            $(,
                deprecated = $deprecated_version:literal
                $(, removed = $removed_version:literal )?
            )?
        )?
    ) => { ... };
    ( @optional_feature ) => { ... };
    ( @optional_feature $feature:literal ) => { ... };
    ( @stable_path_selector stable($feature:literal)) => { ... };
    ( @stable_path_selector $version:literal | stable($feature:literal)) => { ... };
    ( @stable_path_selector $version:literal) => { ... };
    ( @optional_version ) => { ... };
    ( @optional_version $version:literal ) => { ... };
}

Available on crate feature api only.

Convenient constructor for Metadata implementation.

Definition

By default, Metadata is implemented on a type named Request that is in scope. This can be overridden by adding @for MyType at the beginning of the declaration.

The rest of the definition of the macro is made to look like a struct, with the following fields:

• method - The HTTP method to use for the endpoint. Its value must be one of the associated constants of http::Method. In most cases it should be one of GET, POST, PUT or DELETE.
• rate_limited - Whether the endpoint should be rate-limited, according to the specification. Its value must be a bool.
• authentication - The type of authentication that is required for the endpoint, according to the specification. The type must be in scope and implement AuthScheme.

And either of the following fields to define the path(s) of the endpoint.

• history - The history of the paths of the endpoint. This should be used for endpoints from Matrix APIs that have a /versions endpoint that returns a list a MatrixVersions and possibly features, like the Client-Server API or the Identity Service API. However, a few endpoints from those APIs shouldn’t use this field because they cannot be versioned, like the /versions or the /.well-known endpoints.

  Its definition is made to look like match arms and must include at least one arm. The match arms accept the following syntax:

  • unstable => "unstable/endpoint/path/{variable}" - An unstable version of the endpoint as defined in the MSC that adds it, if the MSC does NOT define an unstable feature in the unstable_features field of the client-server API’s /versions endpoint.

  • unstable("org.bar.unstable_feature") => "unstable/endpoint/path/{variable}" - An unstable version of the endpoint as defined in the MSC that adds it, if the MSC defines an unstable feature in the unstable_features field of the client-server API’s /versions endpoint.

  • 1.0 | stable("org.bar.feature.stable") => "stable/endpoint/path/{variable}" - A stable version of the endpoint as defined in an MSC or the Matrix specification. The match arm can be a Matrix version, a stable feature, or both separated by |.

    A stable feature can be defined in an MSC alongside an unstable feature, and can be found in the unstable_features field of the client-server API’s /versions endpoint. It is meant to be used by homeservers if they want to declare stable support for a feature before they can declare support for a whole Matrix version that supports it.

  • 1.2 => deprecated - The Matrix version that deprecated the endpoint, if any. It must be preceded by a match arm with a stable path and a different Matrix version.

  • 1.3 => removed - The Matrix version that removed the endpoint, if any. It must be preceded by a match arm with a deprecation and a different Matrix version.

  A Matrix version is a float representation of the version that looks like major.minor. It must match one of the variants of MatrixVersion. For example 1.0 matches MatrixVersion::V1_0, 1.1 matches MatrixVersion::V1_1, etc.

  It is expected that the match arms are ordered by descending age. Usually the older unstable paths would be before the newer unstable paths, then we would find the stable paths, and finally the deprecation and removal.

  The following checks occur at compile time:

  • All unstable and stable paths contain the same variables (or lack thereof).
  • Matrix versions in match arms are all different and in ascending order.

  This field is represented as the VersionHistory type in the generated implementation.

• path - The only path of the endpoint. This should be used for endpoints from Matrix APIs that do NOT have a /versions endpoint that returns a list a MatrixVersions, like the Server-Server API or the Appservice API. It should also be used for endpoints that cannot be versioned, like the /versions or the /.well-known endpoints.

  Its value must be a static string representing the path, like "endpoint/path/{variable}".

  This field is represented as the SinglePath type in the generated implementation.

Example

use ruma_common::{
    api::auth_scheme::{AccessToken, NoAuthentication},
    metadata,
};

/// A Request with a path version history.
pub struct Request {
    body: Vec<u8>,
}

metadata! {
    method: GET,
    rate_limited: true,
    authentication: AccessToken,

    history: {
        unstable => "/_matrix/unstable/org.bar.msc9000/baz",
        unstable("org.bar.msc9000.v1") => "/_matrix/unstable/org.bar.msc9000.v1/qux",
        1.0 | stable("org.bar.msc9000.stable") => "/_matrix/media/r0/qux",
        1.1 => "/_matrix/media/v3/qux",
        1.2 => deprecated,
        1.3 => removed,
    }
};

/// A request with a single path.
pub struct MySinglePathRequest {
    body: Vec<u8>,
}

metadata! {
    @for MySinglePathRequest,

    method: GET,
    rate_limited: false,
    authentication: NoAuthentication,
    path: "/_matrix/key/query",
};