1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
|
// 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:
//
// 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.
package api
import (
"context"
"time"
)
// 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
}
// 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.
// It uses default buffer sizes for the request and reply Go channels.
NewAPIChannel() (Channel, error)
// NewAPIChannelBuffered returns a new channel for communication with VPP via govpp core.
// It allows to specify custom buffer sizes for the request and reply Go channels.
NewAPIChannelBuffered(reqChanBufSize, replyChanBufSize int) (Channel, 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, 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)
// 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.
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(msg Message) error
}
// 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(msg Message) (lastReplyReceived bool, err error)
}
// 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
}
|
