Documentation
¶
Overview ¶
Package session provides NETCONF Session and their Handler.
NETCONF client and server applications implement the Handler (session event) interface, most important being its OnMessage method. Handler access uncooked transport I/O via the Session's Incoming and Outgoing messages.
Session implementation and execution overview ¶
Session for either client or server use are created using the New function, providing the input (src) and output (dst) along with a session Config. The config has two fields, at least one of which (Capabilities) must be populated for a session to establish successfully, so that protocol framing capability exchange can occur. See the sections on the Session.Config fields below.
The Session manages access to the underlying transport through an abstraction of the NETCONF message layer. Each Session has a "current" Incoming and Outgoing message, an io.Reader and io.WriteCloser, respectively, which applications use to read from and write to the session's current message.
Session.Config.ID (uint32) field ¶
The Session type handles initial <hello> and <capabilities> exchange (during the call to InitialHandshake). For this we need to know whether the Session is considered a client or server session (as their error checking differs). Server sessions are those which have a non-zero Config.ID value, while Client sessions have a zero value in this field.
For example, a server's "session manager" would provide the Config.ID value when creating the session, while clients ignore Config.ID and can retrieve the session-id via the State.ID field as required, e.g., when calling the <kill-session> RPC.
Session.Config.Capabilities (string slice) field ¶
This slice field must be populated to define the <capability> URLs which will be sent to the peer during session initialization and capability exchange.
Session execution ¶
The Run function takes a base Session (as created by New) and a a custom Handler implementation. Run calls Handler methods, as described in Handler documentation. When the transport layer sees the end-of-message token on input, the current Incoming message returns EOF to Read, and is set for renewal before the Handler OnMessage method is called again. On the other hand, the lifetime of Outgoing messages is controlled locally. Calling the Outgoing message Close ends the Outgoing message and sets it for renewal for future calls to Outgoing (i.e., in the next OnMessage handler).
Because the Incoming message returns EOF on each message, it effectively masks EOF as a signal for the end of the underlying Session input stream. To signal end of stream, the first call (only) to an Incoming message's Read function will return ErrEndOfStream instead of EOF in case of EOF of the underlying stream (on the first call to each Incoming) message, meaning an unexpected EOF mid-message will not report ErrEndOfStream until a Read to the next Incoming message is made.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrEndOfStream is the error returned by Read calls to Incoming messages // when the final EOF has been reached. ErrEndOfStream = message.ErrEndOfStream )
Functions ¶
Types ¶
type Capabilities ¶
type Capabilities []string
Capabilities is a slice of strings denoting NETCONF capability URIs
func (Capabilities) Has ¶
func (c Capabilities) Has(uri string) bool
Has returns true if uri is in the capabilities set
type Config ¶
type Config struct {
// ID is the configured session-id. Must be 0 for client sessions
// and non-0 for server sessions
ID uint32
// Capabilities holds our session capabilities
Capabilities Capabilities
}
Config contains Session configuration
type Handler ¶
type Handler interface {
// OnEstablish is called when the session is established.
// When called, session capabilities processing has completed
OnEstablish(*Session)
// OnMessage is called after the session is established
// and then repeatedly while the session remains in the
// StatusEstablished state.
OnMessage(*Session)
// OnError is called once if the session transitions from
// to the StatusError state. This can occur initially,
// instead of OnEstablish, or after the OnEstablish state,
// indicating a session transport error occurred.
OnError(*Session)
// OnClose is called immediately after the session's
// transport is closed.
OnClose(*Session)
}
Handler is the Session handler interface. Client and/or server applications implement this interface.
See Run() for usage.
type Session ¶
type Session struct {
Config Config
State *State
Message *message.Splitter
// contains filtered or unexported fields
}
Session represents a NETCONF session
func (*Session) Incoming ¶
Incoming returns the incoming (from peer) message channel (implements io.Reader).
This function always returned a non-nil message channel, even when the peer stream has ended or been closed.
Note that the object returned returned will return message.ErrEndOfStream to Read when the underlying transport reaches EOF or has been closed, and will return io.EOF at the end of each message.
func (*Session) InitialHandshake ¶
InitialHandshake performs session handshake, capabilities exchange and framing mode selection.
Returns true if the handshake completed successfully, in which case the session status will be StatusEstablished; otherwise returns false if an error occurred (for either transport or validation reasons), in which case Session.Errors will return non-nil and the session status will be StatusError.
type State ¶
type State struct {
// ID is the established session-id. Will be populated during
// capabilities exchange.
ID uint32
// Capabilities holds the remote peer's capabilities
Capabilities Capabilities
// Status is the session status
Status Status
// Counters contains session counters
Counters struct {
// RxMsgs is the number of NETCONF messages received on the session
RxMsgs int
}
// Opaque is user private data and is not used by the netconf libraries.
Opaque interface{}
// contains filtered or unexported fields
}
State contains runtime Session state
type Status ¶
type Status int
Status is a Session's (present) state.
const ( // StatusInactive is the initial session state, indicating that // I/O has not yet been started. StatusInactive Status = iota // StatusCapabilitiesExchange is the capabilities exchange status. // This is set after the <hello> message is received from the peer. StatusCapabilitiesExchange // StatusEstablished is set after capabilities exchange finishes // if the session has been successfully established. Otherwise, // the state machine will proceed to StatusError. StatusEstablished // StatusError indicates the session has encountered an error. StatusError // StatusClosed indicates the session closed normally. StatusClosed )
Source Files