GoVPP

The GoVPP repository contains Go client libraries, code bindings generator and other toolings for VPP.

Here is brief summary of features provided by GoVPP:

Generator of Go bindings for VPP API
Go client library for VPP binary API & Stats API
Extendable code generator supporting custom plugins
Pure Go implementation of VPP binary API protocol
Efficient reader of VPP Stats data from shared memory
Simple client API that does not rely on VPP API semantics
Generated RPC client code that handles all boilerplate
..and much more!

ℹ️ Migration to GitHub

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.

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.

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

Refer to User Guide document for all the basics. If you run into issues or just need help debugging read our Troubleshooting document.

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

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

themiron / govpp