govpp

README

⚠️ The GoVPP project is changing hosting :

• its import URL will move to go.fd.io/govpp
• its repository location will move to https://github.com/FDio/govpp.

The last version archived on git.fd.io/govpp.git will be v0.5.0.

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
    • vppapiclient - CGo wrapper of vppapiclient library (DEPRECATED!)
  • 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 - documentation
  • examples - examples demonstrating GoVPP functionality
  • internal - packages used internally by GoVPP
  • 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 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"
    
	"git.fd.io/govpp.git"
	"git.fd.io/govpp.git/binapi/interfaces"
	"git.fd.io/govpp.git/binapi/vpe"
)

func main() {
	// Connect to VPP
	conn, _ := govpp.Connect("/run/vpp/api.sock")
	defer conn.Disconnect()

	// Open channel
	ch, _ := conn.NewAPIChannel()
	defer ch.Close()

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

	// Send the request
	err := ch.SendRequest(req).ReceiveReply(reply)
	if err != nil {
        log.Fatal("ERROR: ", err)
	}

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

For a complete example see simple-client.

Using RPC service client

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

package main

import (
    "context"
    "log"

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

func main() {
	// Connect to VPP API socket
	conn, _ := govpp.Connect("/run/vpp/api.sock")
	defer conn.Disconnect()

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

	reply, err := client.ShowVersion(context.Background(), &vpe.ShowVersion{})
	if err != nil {
		log.Fatal("ERROR: ", err)
	}

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

For a complete example see rpc-service.

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.

• Adapters - detailed info about transport adapters and their implementations
• Binapi Generator - user guide for generating VPP binary API

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.