api/api.go

   1 //  Copyright (c) 2020 Cisco and/or its affiliates.
   2 //
   3 //  Licensed under the Apache License, Version 2.0 (the "License");
   4 //  you may not use this file except in compliance with the License.
   5 //  You may obtain a copy of the License at:
   6 //
   7 //      http://www.apache.org/licenses/LICENSE-2.0
   8 //
   9 //  Unless required by applicable law or agreed to in writing, software
  10 //  distributed under the License is distributed on an "AS IS" BASIS,
  11 //  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12 //  See the License for the specific language governing permissions and
  13 //  limitations under the License.
  14
  15 package api
  16
  17 import (
  18         "context"
  19         "time"
  20 )
  21
  22 // Connection represents the client connection to VPP API.
  23 //
  24 // NOTE: This API is EXPERIMENTAL.
  25 type Connection interface {
  26         // NewStream creates a new stream for sending and receiving messages.
  27         // Context can be used to close the stream using cancel or timeout.
  28         NewStream(ctx context.Context) (Stream, error)
  29
  30         // Invoke can be used for a simple request-reply RPC.
  31         // It creates stream and calls SendMsg with req and RecvMsg with reply.
  32         Invoke(ctx context.Context, req Message, reply Message) error
  33 }
  34
  35 // Stream provides low-level access for sending and receiving messages.
  36 // Users should handle correct type and ordering of messages.
  37 //
  38 // NOTE: This API is EXPERIMENTAL.
  39 type Stream interface {
  40         // SendMsg sends a message to the client.
  41         // It blocks until message is sent to the transport.
  42         //
  43         // It is safe to have a goroutine calling SendMsg and another goroutine
  44         // calling RecvMsg on the same stream at the same time, but it is not safe
  45         // to call SendMsg on the same stream in different goroutines.
  46         SendMsg(Message) error
  47
  48         // RecvMsg blocks until a message is received or error occurs.
  49         //
  50         // It is safe to have a goroutine calling SendMsg and another goroutine
  51         // calling RecvMsg on the same stream at the same time, but it is not safe
  52         // to call SendMsg on the same stream in different goroutines.
  53         RecvMsg() (Message, error)
  54
  55         // Close closes the stream. Calling SendMsg and RecvMsg will return error
  56         // after closing stream.
  57         Close() error
  58 }
  59
  60 // ChannelProvider provides the communication channel with govpp core.
  61 type ChannelProvider interface {
  62         // NewAPIChannel returns a new channel for communication with VPP via govpp core.
  63         // It uses default buffer sizes for the request and reply Go channels.
  64         NewAPIChannel() (Channel, error)
  65
  66         // NewAPIChannelBuffered returns a new channel for communication with VPP via govpp core.
  67         // It allows to specify custom buffer sizes for the request and reply Go channels.
  68         NewAPIChannelBuffered(reqChanBufSize, replyChanBufSize int) (Channel, error)
  69 }
  70
  71 // Channel provides methods for direct communication with VPP channel.
  72 type Channel interface {
  73         // SendRequest asynchronously sends a request to VPP. Returns a request context, that can be used to call ReceiveReply.
  74         // In case of any errors by sending, the error will be delivered to ReplyChan (and returned by ReceiveReply).
  75         SendRequest(msg Message) RequestCtx
  76
  77         // SendMultiRequest asynchronously sends a multipart request (request to which multiple responses are expected) to VPP.
  78         // Returns a multipart request context, that can be used to call ReceiveReply.
  79         // In case of any errors by sending, the error will be delivered to ReplyChan (and returned by ReceiveReply).
  80         SendMultiRequest(msg Message) MultiRequestCtx
  81
  82         // SubscribeNotification subscribes for receiving of the specified notification messages via provided Go channel.
  83         // Note that the caller is responsible for creating the Go channel with preferred buffer size. If the channel's
  84         // buffer is full, the notifications will not be delivered into it.
  85         SubscribeNotification(notifChan chan Message, event Message) (SubscriptionCtx, error)
  86
  87         // SetReplyTimeout sets the timeout for replies from VPP. It represents the maximum time the API waits for a reply
  88         // from VPP before returning an error.
  89         SetReplyTimeout(timeout time.Duration)
  90
  91         // CheckCompatibility checks the compatiblity for the given messages.
  92         // It will return an error if any of the given messages are not compatible.
  93         CheckCompatiblity(msgs ...Message) error
  94
  95         // Close closes the API channel and releases all API channel-related resources
  96         // in the ChannelProvider.
  97         Close()
  98 }
  99
 100 // RequestCtx is helper interface which allows to receive reply on request.
 101 type RequestCtx interface {
 102         // ReceiveReply receives a reply from VPP (blocks until a reply is delivered
 103         // from VPP, or until an error occurs). The reply will be decoded into the msg
 104         // argument. Error will be returned if the response cannot be received or decoded.
 105         ReceiveReply(msg Message) error
 106 }
 107
 108 // MultiRequestCtx is helper interface which allows to receive reply on multi-request.
 109 type MultiRequestCtx interface {
 110         // ReceiveReply receives a reply from VPP (blocks until a reply is delivered
 111         // from VPP, or until an error occurs).The reply will be decoded into the msg
 112         // argument. If the last reply has been already consumed, lastReplyReceived is
 113         // set to true. Do not use the message itself if lastReplyReceived is
 114         // true - it won't be filled with actual data.Error will be returned if the
 115         // response cannot be received or decoded.
 116         ReceiveReply(msg Message) (lastReplyReceived bool, err error)
 117 }
 118
 119 // SubscriptionCtx is helper interface which allows to control subscription for
 120 // notification events.
 121 type SubscriptionCtx interface {
 122         // Unsubscribe unsubscribes from receiving the notifications tied to the
 123         // subscription context.
 124         Unsubscribe() error
 125 }