-// Copyright (c) 2017 Cisco and/or its affiliates.
+// Copyright (c) 2020 Cisco and/or its affiliates.
//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at:
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at:
//
-// http://www.apache.org/licenses/LICENSE-2.0
+// http://www.apache.org/licenses/LICENSE-2.0
//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
package api
import (
+ "context"
"time"
)
-// MessageType represents the type of a VPP message.
-type MessageType int
-
-const (
- // RequestMessage represents a VPP request message
- RequestMessage MessageType = iota
- // ReplyMessage represents a VPP reply message
- ReplyMessage
- // EventMessage represents a VPP notification event message
- EventMessage
- // OtherMessage represents other VPP message (e.g. counters)
- OtherMessage
-)
-
-// Message is an interface that is implemented by all VPP Binary API messages generated by the binapigenerator.
-type Message interface {
- // GetMessageName returns the original VPP name of the message, as defined in the VPP API.
- GetMessageName() string
-
- // GetMessageType returns the type of the VPP message.
- GetMessageType() MessageType
-
- // GetCrcString returns the string with CRC checksum of the message definition (the string represents a hexadecimal number).
- GetCrcString() string
+// Connection represents the client connection to VPP API.
+//
+// NOTE: This API is EXPERIMENTAL.
+type Connection interface {
+ // NewStream creates a new stream for sending and receiving messages.
+ // Context can be used to close the stream using cancel or timeout.
+ NewStream(ctx context.Context, options ...StreamOption) (Stream, error)
+
+ // Invoke can be used for a simple request-reply RPC.
+ // It creates stream and calls SendMsg with req and RecvMsg with reply.
+ Invoke(ctx context.Context, req Message, reply Message) error
}
-// DataType is an interface that is implemented by all VPP Binary API data types by the binapi_generator.
-type DataType interface {
- // GetTypeName returns the original VPP name of the data type, as defined in the VPP API.
- GetTypeName() string
-
- // GetCrcString returns the string with CRC checksum of the data type definition (the string represents a hexadecimal number).
- GetCrcString() string
+// Stream provides low-level access for sending and receiving messages.
+// Users should handle correct type and ordering of messages.
+//
+// NOTE: This API is EXPERIMENTAL.
+type Stream interface {
+ // SendMsg sends a message to the client.
+ // It blocks until message is sent to the transport.
+ //
+ // It is safe to have a goroutine calling SendMsg and another goroutine
+ // calling RecvMsg on the same stream at the same time, but it is not safe
+ // to call SendMsg on the same stream in different goroutines.
+ SendMsg(Message) error
+
+ // RecvMsg blocks until a message is received or error occurs.
+ //
+ // It is safe to have a goroutine calling SendMsg and another goroutine
+ // calling RecvMsg on the same stream at the same time, but it is not safe
+ // to call SendMsg on the same stream in different goroutines.
+ RecvMsg() (Message, error)
+
+ // Close closes the stream. Calling SendMsg and RecvMsg will return error
+ // after closing stream.
+ Close() error
}
+// StreamOption allows customizing a Stream. Available options are:
+// - WithRequestSize
+// - WithReplySize
+// - WithReplyTimeout
+type StreamOption func(Stream)
+
// ChannelProvider provides the communication channel with govpp core.
type ChannelProvider interface {
// NewAPIChannel returns a new channel for communication with VPP via govpp core.
NewAPIChannelBuffered(reqChanBufSize, replyChanBufSize int) (Channel, error)
}
-// MessageDecoder provides functionality for decoding binary data to generated API messages.
-type MessageDecoder interface {
- // DecodeMsg decodes binary-encoded data of a message into provided Message structure.
- DecodeMsg(data []byte, msg Message) error
-}
-
-// MessageIdentifier provides identification of generated API messages.
-type MessageIdentifier interface {
- // GetMessageID returns message identifier of given API message.
- GetMessageID(msg Message) (uint16, error)
- // LookupByID looks up message name and crc by ID
- LookupByID(ID uint16) (string, error)
-}
-
// Channel provides methods for direct communication with VPP channel.
type Channel interface {
// SendRequest asynchronously sends a request to VPP. Returns a request context, that can be used to call ReceiveReply.
// In case of any errors by sending, the error will be delivered to ReplyChan (and returned by ReceiveReply).
SendRequest(msg Message) RequestCtx
+
// SendMultiRequest asynchronously sends a multipart request (request to which multiple responses are expected) to VPP.
// Returns a multipart request context, that can be used to call ReceiveReply.
// In case of any errors by sending, the error will be delivered to ReplyChan (and returned by ReceiveReply).
SendMultiRequest(msg Message) MultiRequestCtx
+
// SubscribeNotification subscribes for receiving of the specified notification messages via provided Go channel.
// Note that the caller is responsible for creating the Go channel with preferred buffer size. If the channel's
// buffer is full, the notifications will not be delivered into it.
- SubscribeNotification(notifChan chan Message, msgFactory func() Message) (*NotifSubscription, error)
- // UnsubscribeNotification unsubscribes from receiving the notifications tied to the provided notification subscription.
- UnsubscribeNotification(subscription *NotifSubscription) error
- // CheckMessageCompatibility checks whether provided messages are compatible with the version of VPP
- // which the library is connected to.
- CheckMessageCompatibility(messages ...Message) error
+ SubscribeNotification(notifChan chan Message, event Message) (SubscriptionCtx, error)
+
// SetReplyTimeout sets the timeout for replies from VPP. It represents the maximum time the API waits for a reply
// from VPP before returning an error.
SetReplyTimeout(timeout time.Duration)
- // GetRequestChannel returns request go channel of the VPP channel
- GetRequestChannel() chan<- *VppRequest
- // GetReplyChannel returns reply go channel of the VPP channel
- GetReplyChannel() <-chan *VppReply
- // GetNotificationChannel returns notification go channel of the VPP channel
- GetNotificationChannel() chan<- *NotifSubscribeRequest
- // GetNotificationReplyChannel returns notification reply go channel of the VPP channel
- GetNotificationReplyChannel() <-chan error
- // GetMessageDecoder returns message decoder instance
- GetMessageDecoder() MessageDecoder
- // GetID returns channel's ID
- GetID() uint16
- // Close closes the API channel and releases all API channel-related resources in the ChannelProvider.
+
+ // CheckCompatibility checks the compatiblity for the given messages.
+ // It will return an error if any of the given messages are not compatible.
+ CheckCompatiblity(msgs ...Message) error
+
+ // Close closes the API channel and releases all API channel-related resources
+ // in the ChannelProvider.
Close()
}
-// RequestCtx is helper interface which allows to receive reply on request context data
+// RequestCtx is helper interface which allows to receive reply on request.
type RequestCtx interface {
- // ReceiveReply receives a reply from VPP (blocks until a reply is delivered from VPP, or until an error occurs).
- // The reply will be decoded into the msg argument. Error will be returned if the response cannot be received or decoded.
+ // ReceiveReply receives a reply from VPP (blocks until a reply is delivered
+ // from VPP, or until an error occurs). The reply will be decoded into the msg
+ // argument. Error will be returned if the response cannot be received or decoded.
ReceiveReply(msg Message) error
}
-// MultiRequestCtx is helper interface which allows to receive reply on multi-request context data
+// MultiRequestCtx is helper interface which allows to receive reply on multi-request.
type MultiRequestCtx interface {
- // ReceiveReply receives a reply from VPP (blocks until a reply is delivered from VPP, or until an error occurs).
- // The reply will be decoded into the msg argument. If the last reply has been already consumed, lastReplyReceived is
- // set to true. Do not use the message itself if lastReplyReceived is true - it won't be filled with actual data.
- // Error will be returned if the response cannot be received or decoded.
+ // ReceiveReply receives a reply from VPP (blocks until a reply is delivered
+ // from VPP, or until an error occurs).The reply will be decoded into the msg
+ // argument. If the last reply has been already consumed, lastReplyReceived is
+ // set to true. Do not use the message itself if lastReplyReceived is
+ // true - it won't be filled with actual data.Error will be returned if the
+ // response cannot be received or decoded.
ReceiveReply(msg Message) (lastReplyReceived bool, err error)
}
-// VppRequest is a request that will be sent to VPP.
-type VppRequest struct {
- SeqNum uint16 // sequence number
- Message Message // binary API message to be send to VPP
- Multipart bool // true if multipart response is expected, false otherwise
-}
-
-// VppReply is a reply received from VPP.
-type VppReply struct {
- MessageID uint16 // ID of the message
- SeqNum uint16 // sequence number
- Data []byte // encoded data with the message - MessageDecoder can be used for decoding
- LastReplyReceived bool // in case of multipart replies, true if the last reply has been already received and this one should be ignored
- Error error // in case of error, data is nil and this member contains error description
-}
-
-// NotifSubscribeRequest is a request to subscribe for delivery of specific notification messages.
-type NotifSubscribeRequest struct {
- Subscription *NotifSubscription // subscription details
- Subscribe bool // true if this is a request to subscribe, false if unsubscribe
-}
-
-// NotifSubscription represents a subscription for delivery of specific notification messages.
-type NotifSubscription struct {
- NotifChan chan Message // channel where notification messages will be delivered to
- MsgFactory func() Message // function that returns a new instance of the specific message that is expected as a notification
+// SubscriptionCtx is helper interface which allows to control subscription for
+// notification events.
+type SubscriptionCtx interface {
+ // Unsubscribe unsubscribes from receiving the notifications tied to the
+ // subscription context.
+ Unsubscribe() error
}
Code Review / govpp.git / blobdiff