Macro fizyr_rpc::interface

macro_rules! interface {
    ($($tokens:tt)*) => { ... };
}

Define an RPC interface.

This macro generates an Interface, ClientandServer` struct, and some more helper types.

The Interface struct is used to enable RPC interface introspection. Currently, it only supports retrieving the documentation of the interface itself. In the future, you can use this struct to get a list of services and streaming messages too.

The client struct is used to initiate requests and send stream messages. It can be created from a PeerWriteHandle or a PeerHandle. Note that if you create the client from a PeerHandle, the PeerReadHandle will not be accessible.

For the server struct it is exactly the opposite: it is used to receive requests and stream messages. It can be created from a PeerReadHandle or a PeerHandle, but creating it from a PeerHandle will discard the PeerWriteHandle.

Example

See the interface_example module for an example, with the source code and generated documentation.

Syntax

The syntax for the macro is as follows:

fizyr_rpc::interface! {
    // The `interface` keyword defines an RPC interface.
    // You must have exactly one interface definition in the macro invocation.
    //
    // The $interface_name is used in automatically generated documentation and should be UpperCamelCase.
    //
    // You can adjust the visiblity of the generated items with the `pub` keyword as normal.
    // By default, all generated items are private.
    //
    // Each item can have user written documentation.
    // Simply write doc comments with triple slashes as usual.
    // This applies to the interface definition, service definitions, update definitions and stream definitions.
    //
    // The documentation writter on the `interface` item can be retrieved through the introspection API,
    // but does not appear in rustdoc.
    pub interface $interface_name {
        // The `service` keyword defines a service.
        //
        // You can have any amount of service definitions inside an interface definition.
        //
        // The $id is used as the service ID and must be an i32.
        // The ID must be unique for all services in the interface.
        //
        // The $name is the name of the service.
        // It is used to generate function and type names.
        // It must be a valid Rust identifier and should be lowercase with underscores.
        //
        // The $request_type and $response_type indicate the message body for the request and the response.
        // If there is no data in a request or response, you can use the unit type: `()`
        //
        // If the service has no update messages, you can end the definition with a comma.
        // See the next item for the syntax of services with update messages.
        service $id $name: $request_type -> $response_type,

        // If a service has update messages, you can declare them in the service block.
        service $id $name: $request_type -> $response_type {
            // The `request_update` keyword defines a request update.
            // You can have any amount of request updates inside a service definition.
            //
            // The $id is used as the service ID for the update and must be an i32.
            // The ID must be unique for all request updates in the service.
            //
            // The $name is the name of the update message.
            // It is used to generate function and type names.
            // It must be a valid Rust identifier and should be lowercase with underscores.
            //
            // The $body_type indicates the type of the message.
            // If there is no data in the message, you can use the unit type: `()`
            request_update $id $name: $body_type,

            // The `response_update` keyword defines a response update.
            // You can have any amount of response updates inside a service definition.
            //
            // The $id is used as the service ID for the update and must be an i32.
            // The ID must be unique for all response updates in the service.
            //
            // The $name is the name of the update message.
            // It is used to generate function and type names.
            // It must be a valid Rust identifier and should be lowercase with underscores.
            //
            // The $body_type indicates the type of the message.
            // If there is no data in the message, you can use the unit type: `()`
            response_update $id $name: $body_type,
        }

        // The `stream` keyword defines a stream message.
        // You can have any amount of stream definitions in an interface definition.
        //
        // The $id is used as the service ID of the stream message and must be an i32.
        // The ID must be unique for all streams in the interface.
        //
        // The $name is the name of the stream.
        // It is used to generate function and type names.
        // It must be a valid Rust identifier and should be lowercase with underscores.
        //
        // The $body_type indicates the type of the message.
        // If there is no data in the message, you can use the unit type: `()`
       stream $id $name: $body_type,
    }
}