Stream API

[ondrej-fabry]

This discussion contains info about the Stream API - a new client interface for interacting with VPP API.

Table of Contents

• Stream API
  • Overview
  • Background
  • Implementation

💠 Stream API

The Stream API is a new experimental client API for interacting with VPP API. The goal is to provide full alternative to the old Channel API, remove the complexity of API interfaces, move the responsibilities of handling messages to the user while minimizing the footprint of the Stream.

The semantics of the VPP API that were part of Channel implementation must be handled by the user. E.g. sending ControlPing request after dumps. However, the generated code for the RPC Services contains all of this boilerplate so you actually never need to manually call the Stream methods at all.

💠 Overview

Here is a comparison summary of the Stream API features and improvements over Channel API:

Feature	Stream API	Channel API
Request	requests to VPP are sent synchronously (SengMsg returns after message is sent or error occurs)	sends requests to a buffered go channel to get processesed by a background goroutine
Reply	replies are received as a return value (RecvMsg returns reply or error)	accepts reply as a parameter where user had to use correct type of message this limitation was preventing channels to be used for special dump requests where multiple message types are received for single request
Interface	single interface for sending/receiving all messages (SendMsg/RecvMsg)	different interfaces for normal requests and dump requests (RequestCtx/MultiRequestCtx)
Context	accepts context.Context as a parameter for passing request-scoped data from the caller	not supported

💠 Background

🔹 Old Channel API

The GoVPP originally came with Channels for sending and receiving messages, which supported simple requests (request/reply) types, multi requests (dump/details) and subscription requests (want/event).
The Channel instances were created using ChannelProvider and internally, the Channel implementation uses buffered channels with capacity set to 100 by default.

type ChannelProvider interface {
	NewAPIChannel() (Channel, error)
	NewAPIChannelBuffered(reqChanBufSize, replyChanBufSize int) (Channel, error)
}

type Channel interface {
	SendRequest(msg Message) RequestCtx
	SendMultiRequest(msg Message) MultiRequestCtx
	SubscribeNotification(notifChan chan Message, event Message) (SubscriptionCtx, error)
	SetReplyTimeout(timeout time.Duration)
	CheckCompatiblity(msgs ...Message) error
	Close()
}
type RequestCtx interface {
	ReceiveReply(msg Message) error
}
type MultiRequestCtx interface {
	ReceiveReply(msg Message) (lastReplyReceived bool, err error)
}
type SubscriptionCtx interface {
	Unsubscribe() error
}

🔗 api.ChannelProvider definition
🔗 api.Channel definition

However, the Channel API could not be used for new type of multi-requests (dump/details+reply) that VPP later introduced. This new type of requests could not work with the old Channel API, because it was not possible to receive message without knowing exactly what type of message will be received (reply message was a parameter not a return value). The implementation of Channels also does several stuff behind the scenes which are either impossible to control by user (sending ControlPing for multi-requests) or just plain inefficient (using reflect to get Retval field).

🔹 New Stream API

For the reasons above mentioned above, we introduced a new API interface for sending and receiving messages called Stream and Connection interface for creating streams and watching events.

type Connection interface {
	NewStream(ctx context.Context, options ...StreamOption) (Stream, error)
	Invoke(ctx context.Context, req Message, reply Message) error
	WatchEvent(ctx context.Context, event Message) (Watcher, error)
}

type Stream interface {
	SendMsg(Message) error
	RecvMsg() (Message, error)
	Close() error
}

🔗 api.Connection definition
🔗 api.Stream definition

The goal of the new Stream API is to be less restrictive and very simple. This means it does not try to do any assumptions about the semantics of the VPP API requests. It only has two methods for sending and receiving messages: SendMsg(Message) error and RecvMsg() (Message, error) and Close() error for closing the stream.

💠 Implementation

Here is brief status of implementation:

• define Stream interface
  • implement SendMsg for sending requests
  • implement RecvMsg for receiving replies (as return value instead of input parameter)
  • implement SubscribeEvent for subscribing to events (tracked under Add support of VPP events to Stream API #63)
• replace the implementation of the Stream without using channels

Once all the planned features are completed, the old Channel API could be deprecated as the Stream will provide a simple and efficient API without the current limitations of Channel API.

🔹 Known Limitations

However, the new Stream API does not currently come with completely new implementation yet. For now it still uses the channel implementation under the hood. This means it creates a new channel for each stream which brings some extra overhead which is not even necessary or even used. The plan is to re-implement this without using Channels.