govpp

README

GoVPP

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

---

Features

• 🆕 CLI app for interacting with VPP instance and development of VPP API (see GoVPP CLI)
• 🆕 Extendable code generator supporting custom plugins (see Enhanced Generator)
• 🆕 Generated RPC client code that handles all boilerplate (see RPC Services)
• Simple VPP client API that is not dependent on any VPP API semantics (see Stream API)
• Generator of Go bindings for VPP API schema (see Binapi Generator)
• Go client library for VPP binary API & Stats API (see VPP API calls)
• Pure Go implementation of VPP binary API protocol (see socketclient)
• Efficient reader of VPP Stats data from shared memory (see stats client example)

Quick Start

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

Note For extensive info about using generated RPC client , see RPC Services

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

// Initialize VPP API service client
client := vpe.NewServiceClient(conn)

// Call VPP API service method
reply, err := client.ShowVersion(context.Background(), &vpe.ShowVersion{})
if err != nil {
  // handle err
}
log.Print("Version: ", reply.Version)

See complete code for the example above: examples/rpc-service.

Examples

For complete code examples demonstrating vrious GoVPP features, please refer to the examples directory.

Documentation

Refer to User Guide document for info about how to use GoVPP. If you run into any issues or need some help with debugging GoVPP, read our Troubleshooting document.

Go reference docs are available at pkg.go.dev.

For other documentation refer to docs directory.

How to contribute?

Anyone insterested in GoVPP development is welcome to join our bi-weekly 📣 GoVPP Community Meeting, where we accept inputs from projects using GoVPP and have technical discussions about actual development.

• Contribute code: submit a Pull Request
• Report bugs: open an Issue
• Ask questions: start a Discussion

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

Documentation

Overview

Package govpp provides the entry point to govpp functionality. It provides the API for connecting the govpp core to VPP either using the default VPP adapter, or using the adapter previously set by SetAdapter function (useful mostly just for unit/integration tests with mocked VPP adapter).

To create a connection to VPP, use govpp.Connect function:

conn, err := govpp.Connect()
if err != nil {
	// handle error!
}
defer conn.Disconnect()

Make sure you close the connection after using it. If the connection is not closed, it will leak resources. Please note that only one VPP connection is allowed for a single process.

In case you need to mock the connection to VPP (e.g. for testing), use the govpp.SetAdapter function before calling govpp.Connect.

Once connected to VPP, use the functions from the api package to communicate with it.

Index

• Variables
• func AsyncConnect(target string, attempts int, interval time.Duration) (*core.Connection, chan core.ConnectionEvent, error)
• func Connect(target string) (*core.Connection, error)
• func Version() string

Variables

var NewVppAdapter = func(target string) adapter.VppAPI {
	return socketclient.NewVppClient(target)
}

NewVppAdapter returns new instance of VPP adapter for connecting to VPP API.

Functions

func AsyncConnect

func AsyncConnect(target string, attempts int, interval time.Duration) (*core.Connection, chan core.ConnectionEvent, error)

AsyncConnect asynchronously connects to the VPP API using a new adapter instance created with NewVppAPIAdapter.

This call does not block until connection is established, it returns immediately. The caller is supposed to watch the returned ConnectionState channel for connection events. In case of disconnect, the library will asynchronously try to reconnect.

func Connect

func Connect(target string) (*core.Connection, error)

Connect connects to the VPP API using a new adapter instance created with NewVppAPIAdapter.

This call blocks until VPP is connected, or an error occurs. Only one connection attempt will be performed.

func Version

func Version() string

Version returns version of GoVPP.