RPC services

[ondrej-fabry]

This discussion contains info about the RPC services - the code generated for the RPC services specified by the VPP API.

Table of Contents

• RPC Services
  • Features
  • Background

💠 RPC Services

RPC Services are specified for VPP API packages (in the *.api.json files) and are defined as list of RPC methods, where the RPC method is defined as a request message type used to call it, expected message type of the response(s), message type of the events it enable/disables and possibly other attributes related to the RPC method. This information is used to generate extra file containing: an interface type for the RPC service and client implementation for this interface where each client method is implemented according to the RPC service specification.

The generated code for RPC services made it possible to get rid of the boilerplate and allow users to use simple methods of an interface for calling VPP API instead of manually sending/receiving the right request message types. The generated code includes an implementation of the RPC client which uses the new Stream API to send/receive messages of type declared by RPC service.

🔹 Features

The generated code currently contains the following features:

• interface type representing the RPC service API
  • accepting context.Context value as the first parameter, which greatly enhances tracing capabilities or pass any request-scoped data from the caller
• implementation of RPC client using the new Stream API to send/receive messages
  • sending/receiving the correct type of request/reply messages for the RPC methods
  • checking the value of Retval field for replies, returning an error in case it's non-zero
  • sending the extra ControlPing request after classic dump requests (dump+ping = details..+ping_reply)
  • streaming responses (details..) from dump requests via dump client
  • handling the correct Reply message type(s) for special dump requests (dump = details..+dump_reply)
  • handling event watching and subscribing to matching notifications
• generate central binapi package representing entire binapi schema
  • include list of all VPP API files that are part of schema
  • add compatibility check of generated schema with the connected VPP
  • only fail compatibility check if existing messages do not match CRC (ignore non-existing messages)
    this allows backwards compatibility with binapi generated for older VPP

🔹 Background

With the new Stream API, being so low-level, users would have to do much of the things done by Channels before themselves; e.g. send ControlPings after each dump manually. For this reasons we also introduced generated RPC methods, where each generate binapi package came with a service interface and also client implementation of this interface where all of the boilerplate was automatically generated.

BEFORE: Using Channel to manually send/receive messages

Here is a code example of using the Channel to manually send requests and receive replies:

// initialize a channel
ch, err := conn.NewAPIChannel()
if err != nil {
  // handle err
}
defer ch.Close()

// prepare request/reply messages (must be careful to pick correct match)
req := &vpe.ShowVersion{}
reply := &vpe.ShowVersionReply{}

if err := ch.SendRequest(req).ReceiveReply(reply); err != nil {
    // handle err
}

log.Print("Version: ", reply.Version)

Note
See complete code: https://github.com/FDio/govpp/blob/master/examples/simple-client/simple_client.go

NOW: Using the generated RPCService to call service methods

Here is a code example of using the generated RPCService interface to call service RPC methods:

// initialize service client
client := vpe.NewServiceClient(conn)

// simply call interface methods to interact with service API
reply, err := client.ShowVersion(context.Background(), &vpe.ShowVersion{})
if err != nil {
    // handle err
}

log.Print("Version: ", reply.Version)

Note
See complete code: https://github.com/FDio/govpp/blob/master/examples/rpc-service/rpc_service.go