⚠️The GoVPP project has been migrated from Gerrit to GitHub

What changed?

• the Go module path was changed from git.fd.io/govpp.git => go.fd.io/govpp
  • the final release for the old import path is v0.5.0
  • new module path can be imported with v0.6.0-alpha
• repository is now located at https://github.com/FDio/govpp
  • any new contributions should be created as pull requests
  • any new issues should be tracked under Issues

---

GoVPP

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

Overview

Here is a brief overview for 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
  • 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

Quick Start

Below are some code examples showing GoVPP client interacting with VPP API.

Using RPC service client

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

package main

import (
    "context"
    "log"

	"go.fd.io/govpp"
	"go.fd.io/govpp/binapi/vpe"
)

func main() {
	// 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)
}

For a complete example see rpc-service.

Using raw messages directly

Here is a code for low-level way to access the VPP API using the generated messages directly for sending/receiving.

package main

import (
    "log"
    
	"go.fd.io/govpp"
	"go.fd.io/govpp/binapi/vpe"
)

func main() {
	// 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.

More code examples

More examples can be found in examples directory.

• 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

Documentation

Further documentation can be found in docs directory.