api/api.go

   1 //  Copyright (c) 2021 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, options ...StreamOption) (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 which returns
  32         // reply.
  33         Invoke(ctx context.Context, req Message, reply Message) error
  34 }
  35
  36 // Stream provides low-level access for sending and receiving messages.
  37 // Users should handle correct type and ordering of messages.
  38 //
  39 // It is not safe to call these methods on the same stream in different
  40 // goroutines.
  41 //
  42 // NOTE: This API is EXPERIMENTAL.
  43 type Stream interface {
  44         // SendMsg sends a message to the client.
  45         // It blocks until message is sent to the transport.
  46         SendMsg(Message) error
  47
  48         // RecvMsg blocks until a message is received or error occurs.
  49         RecvMsg() (Message, error)
  50
  51         // Close closes the stream. Calling SendMsg and RecvMsg will return error
  52         // after closing stream.
  53         Close() error
  54 }
  55
  56 // StreamOption allows customizing a Stream. Available options are:
  57 // - WithRequestSize
  58 // - WithReplySize
  59 // - WithReplyTimeout
  60 type StreamOption func(Stream)
  61
  62 // ChannelProvider provides the communication channel with govpp core.
  63 type ChannelProvider interface {
  64         // NewAPIChannel returns a new channel for communication with VPP via govpp core.
  65         // It uses default buffer sizes for the request and reply Go channels.
  66         NewAPIChannel() (Channel, error)
  67
  68         // NewAPIChannelBuffered returns a new channel for communication with VPP via govpp core.
  69         // It allows to specify custom buffer sizes for the request and reply Go channels.
  70         NewAPIChannelBuffered(reqChanBufSize, replyChanBufSize int) (Channel, error)
  71 }
  72
  73 // Channel provides methods for direct communication with VPP channel.
  74 type Channel interface {
  75         // SendRequest asynchronously sends a request to VPP. Returns a request context, that can be used to call ReceiveReply.
  76         // In case of any errors by sending, the error will be delivered to ReplyChan (and returned by ReceiveReply).
  77         SendRequest(msg Message) RequestCtx
  78
  79         // SendMultiRequest asynchronously sends a multipart request (request to which multiple responses are expected) to VPP.
  80         // Returns a multipart request context, that can be used to call ReceiveReply.
  81         // In case of any errors by sending, the error will be delivered to ReplyChan (and returned by ReceiveReply).
  82         SendMultiRequest(msg Message) MultiRequestCtx
  83
  84         // SubscribeNotification subscribes for receiving of the specified notification messages via provided Go channel.
  85         // Note that the caller is responsible for creating the Go channel with preferred buffer size. If the channel's
  86         // buffer is full, the notifications will not be delivered into it.
  87         SubscribeNotification(notifChan chan Message, event Message) (SubscriptionCtx, error)
  88
  89         // SetReplyTimeout sets the timeout for replies from VPP. It represents the maximum time the API waits for a reply
  90         // from VPP before returning an error.
  91         SetReplyTimeout(timeout time.Duration)
  92
  93         // CheckCompatibility checks the compatiblity for the given messages.
  94         // It will return an error if any of the given messages are not compatible.
  95         CheckCompatiblity(msgs ...Message) error
  96
  97         // Close closes the API channel and releases all API channel-related resources
  98         // in the ChannelProvider.
  99         Close()
 100 }
 101
 102 // RequestCtx is helper interface which allows to receive reply on request.
 103 type RequestCtx interface {
 104         // ReceiveReply receives a reply from VPP (blocks until a reply is delivered
 105         // from VPP, or until an error occurs). The reply will be decoded into the msg
 106         // argument. Error will be returned if the response cannot be received or decoded.
 107         ReceiveReply(msg Message) error
 108 }
 109
 110 // MultiRequestCtx is helper interface which allows to receive reply on multi-request.
 111 type MultiRequestCtx interface {
 112         // ReceiveReply receives a reply from VPP (blocks until a reply is delivered
 113         // from VPP, or until an error occurs).The reply will be decoded into the msg
 114         // argument. If the last reply has been already consumed, lastReplyReceived is
 115         // set to true. Do not use the message itself if lastReplyReceived is
 116         // true - it won't be filled with actual data.Error will be returned if the
 117         // response cannot be received or decoded.
 118         ReceiveReply(msg Message) (lastReplyReceived bool, err error)
 119 }
 120
 121 // SubscriptionCtx is helper interface which allows to control subscription for
 122 // notification events.
 123 type SubscriptionCtx interface {
 124         // Unsubscribe unsubscribes from receiving the notifications tied to the
 125         // subscription context.
 126         Unsubscribe() error
 127 }