# vpp-api-transport

This is a Rust library for interfacing with the VPP API. 

WARNING: quite likely the interfaces may change. This version
(until at least 0.2.0) is to test things out and encourage the feedback.

The idea is to have entity that implements Read and Write traits,
as well as eventually AsRawFd. This should allow to use this
in place where you would use a regular socket in your code.

# Prerequisites

## Rust and OS dependencies

### Rust

As per https://www.rust-lang.org/tools/install:

```
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```

### OS dependencies

On Ubuntu:

```
sudo apt-get install build-essential libclang-10-dev
```

### VPP client libraries

## Option 1 - your local development VPP tree at arbitrary location

Define the environment variable *VPP_LIB_DIR* to point to the folder where
the file *libvppapiclient.so* is located. You might also have to set the
*LD_LIBRARY_PATH* to the same location as well.


## Option 2 - VPP client from packagecloud.io:

Setup the repository from https://packagecloud.io/fdio/master or the
branch-specific repositories as per instructions, then install
the package *python3-vpp-api*, cargo build will find the library there.

# Usage

See the src/vpp-api-transport-test.rs, more and better docs will
come as we go :-) There is no point to document much here yet,
as the interfaces will change.

# Running *cargo test*

```
sudo apt-get install vpp vpp-plugin-core python3-vpp-api
```


# Running the examples

Same prerequisites as for cargo test, and then:

```

$ cargo run --release --example vpp-api-transport-test -- -h

...

    Finished release [optimized] target(s) in 0.04s
     Running `target/release/examples/vpp-api-transport-test -h`
vpp-api-transport version heads/main-0-gaca41b6
Andrew Yourtchenko <ayourtch@gmail.com>
This program is a minimum test of vpp-api-transport crate To make it somewhat useful, it can also
bench the cli_inband API execution time for various commands

USAGE:
    vpp-api-transport-test [FLAGS] [OPTIONS]

FLAGS:
    -h, --help           Prints help information
    -n, --nonblocking    set non-blocking mode for the connection
    -v, --verbose        A level of verbosity, and can be used multiple times
    -V, --version        Prints version information

OPTIONS:
    -c, --command <command>
            Run the bench using this CLI, else use "show version"

    -o, --options-override <options-override>    Override options from this yaml/json file
    -r, --repeat-count <repeat-count>            repeat count for the command [default: 100000]
    -s, --socket-path <socket-path>
            Use AF_UNIX socket if this path is mentioned, else use shared memory transport

$
$ cargo run --release --example vpp-api-transport-test -- -s /run/vpp/api.sock -r 1000000

...

    Finished release [optimized] target(s) in 0.04s
     Running `target/release/examples/vpp-api-transport-test -s /run/vpp/api.sock -r 1000000`
Open success!
Table: MsgSockClntCreateReplyHdr { _vl_msg_id: 16, client_index: 0, context: 124, response: 0, index: 2147483649, count: 1563 }
Connect result: 0
Starting 1000000 requests of 'show version'
Still running... 270492 iterations in 5.000010229s: 54098.2893257197 per second
Still running... 539286 iterations in 10.000028579s: 53928.445877894526 per second
Still running... 854847 iterations in 15.0000489s: 56989.61421385766 per second
Ran 1000000 operations in 17.455633583s : 57288.09528712252 per second
$
$ ./target/release/examples/vpp-api-transport-test -s /run/vpp/api.sock -c "show clock" -v -v -v -r 3
Open success!
Table: MsgSockClntCreateReplyHdr { _vl_msg_id: 16, client_index: 0, context: 124, response: 0, index: 2147483649, count: 1563 }
Connect result: 0
Starting 3 requests of 'show clock'
Result:
Time now 45666.272925, Sun, 21 Feb 2021 22:20:42 GMT

Result:
Time now 45666.272982, Sun, 21 Feb 2021 22:20:42 GMT

Result:
Time now 45666.273032, Sun, 21 Feb 2021 22:20:42 GMT

Ran 3 operations in 173.171µs : 17323.9168221007 per second
$
```