Skip to content

Latest commit

 

History

History
155 lines (114 loc) · 5.72 KB

README.md

File metadata and controls

155 lines (114 loc) · 5.72 KB
Raw

logo
GoVPP

CI Latest PkgGoDev

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 :octocat: 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.

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
    • cmd
    • 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