⚠️ The GoVPP project has changed URL : - the import URL has moved to go.fd.io/govpp - the repository location has moved to https://github.com/FDio/govpp.

The last version archived on git.fd.io/govpp.git is 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"

    "go.fd.io/govpp"
    "go.fd.io/govpp/binapi/interfaces"
    "go.fd.io/govpp/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"

    "go.fd.io/govpp"
    "go.fd.io/govpp/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