GoVPP

The GoVPP repository contains a Go client library for interacting with the VPP API,
generator for Go bindings of the VPP binary API and various other tooling for the VPP.

---

Migration to GitHub

The GoVPP project has been recently migrated to GitHub.

What has changed?

• Go module path has changed from git.fd.io/govpp.git to go.fd.io/govpp.
  • The final release for the old path is v0.5.0.
  • The new module can be imported using go get go.fd.io/govpp@latest.
• Repository location has changed from Gerrit to GitHub.
  • The old Gerrit repository has been archived.

How to contribute?

• Contribute code by submitting a Pull Request.
• Report bugs by opening an Issue.
• Ask questions & open discussions by starting a Discussion.

Documentation

Go reference is available at https://pkg.go.dev/go.fd.io/govpp. More documentation can be found under docs directory.

Examples

Here is a list of code examples with short description of demonstrated GoVPP functionality.

• api-trace - trace sent/received messages
• binapi-types - using common types from generated code
• multi-vpp - connect to multiple VPP instances
• perf-bench - very basic performance test for measuring throughput
• rpc-service - effortless way to call VPP API via RPC client
• simple-client - send and receive VPP API messages using GoVPP API directly
• stats-client - client for retrieving VPP stats data
• stream-client - using new stream API to call VPP API

All code examples can be found under examples directory.

Quick Start

Below are short code samples showing a GoVPP client interacting with the VPP API.

Using RPC client

Here is a code sample of an effortless way for calling the VPP API by using a generated RPC client.

// Connect to VPP API socket
conn, err := govpp.Connect("/run/vpp/api.sock")
if err != nil {
  // handle err
}
defer conn.Disconnect()

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

reply, err := client.ShowVersion(context.Background(), &vpe.ShowVersion{})
if err != nil {
  // handle err
}

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

Complete example in rpc-service.

Using messages directly

Here is a code sample of a low-level way to send/receive messages to/from the VPP by using a Channel.

// Connect to the VPP API socket
conn, err := govpp.Connect("/run/vpp/api.sock")
if err != nil {
	// handle err
}
defer conn.Disconnect()

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

// Prepare messages
req := &vpe.ShowVersion{}
reply := &vpe.ShowVersionReply{}

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

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

For a complete example see simple-client.

Repository Structure

Here is a brief overview of the repository structure.

• govpp - the entry point for the GoVPP client
  • adapter - VPP binary & stats API interface
    • mock - Mock adapter used for testing
    • socketclient - Go implementation of VPP API client for unix socket
    • statsclient - Go implementation of VPP Stats client for shared memory
  • api - GoVPP client API
  • binapi - generated Go bindings for the latest VPP release
  • binapigen - library for generating code from VPP API
    • vppapi - VPP API parser
  • cmd
    • binapi-generator - VPP binary API generator
    • vpp-proxy - VPP proxy for remote access
  • codec - handles encoding/decoding of generated messages into binary form
  • core - implementation of the GoVPP client
  • docs - user & developer documentation
  • examples - examples demonstrating GoVPP functionality
  • proxy - contains client/server implementation for proxy
  • test - integration tests, benchmarks and performance tests