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