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