restconf

README

Add support or configuration, metrics, alerts and management functions to your application!

In this repository

• IETF RESTCONF RFC8040 server-side and client-side protocol handlers. See compliance for all supporting RFCs.
• Works in conjunction with FreeCONF YANG project

Getting Started

Getting started docs here

Building Requirements

Requires Go version 1.20 or greater.

Getting the source

go get -u github.com/freeconf/restconf

Resources

• Web site
• Documentation
  • Getting Started
  • Next Steps
  • Generating Documentation from YANG files
  • RFC Compliance
• Go API Docs
• Issues
• Discussions

Documentation

Index

• Constants
• Variables
• func FindDeviceIdInUrl(addr string) string
• func Node(mgmt *Server, ypath source.Opener) node.Node
• func SplitAddress(fullurl string) (address string, module string, path string, err error)
• func SplitUri(uri string) (module string, path string, err error)
• type AnyDataReader
• type ComplianceContextKeyType
• type ComplianceOptions
  • func (compliance ComplianceOptions) String() string
• type MimeType
  • func (m MimeType) IsJson() bool
  • func (m MimeType) IsRfc() bool
  • func (m MimeType) IsXml() bool
• type ProxyContextKey
• type RequestFilter
• type Server
  • func NewHttpServe(d *device.Local) *Server
  • func NewServer(d *device.Local) *Server
  • func (srv *Server) Close() error
  • func (srv *Server) DeviceAddress(id string, d device.Device) string
  • func (srv *Server) ModuleAddress(m *meta.Module) string
  • func (srv *Server) RegisterWebApp(homeDir string, homePage string, endpoint string)
  • func (srv *Server) ServeDevice(d device.Device) error
  • func (srv *Server) ServeDevices(m device.Map) error
  • func (srv *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)

Constants

const (
	// TODO: Clarify this: RFC8572 uses application/yang.data+xml and RFC8040 uses application/yang-data+json
	YangDataJsonMimeType1 = MimeType("application/yang-data+json")
	YangDataJsonMimeType2 = MimeType("application/yang.data+json")

	YangDataXmlMimeType1 = MimeType("application/yang-data+xml")
	YangDataXmlMimeType2 = MimeType("application/yang.data+xml")

	PlainJsonMimeType = MimeType("application/json")

	TextStreamMimeType = MimeType("text/event-stream")
)

const EventTimeFormat = "2006-01-02T15:04:05-07:00"

const SimplifiedComplianceParam = "simplified"

Variables

var ComplianceContextKey = ComplianceContextKeyType("RESTCONF_COMPLIANCE")

var ErrBadAddress = errors.New("expected format: http://server/restconf[=device]/operation/module:path")

var InternalIetfRfcYPath = source.EmbedDir(internalIetf, "yang/ietf-rfc")

Access to IETF RFC yang definitions (as of 2023-12-29)

var InternalYPath = source.Any(yang.InternalYPath, source.EmbedDir(internal, "yang"))

Access to fc-yang and fc-doc yang definitions.

var RemoteIpAddressKey = ProxyContextKey("FC_REMOTE_IP")

var Simplified = ComplianceOptions{
	AllowRpcUnderData:          true,
	DisableNotificationWrapper: true,
	DisableActionWrapper:       true,
	SimpleErrorResponse:        true,
	QualifyNamespaceDisabled:   true,
}

Simplified are the settings pre 2023 before true IETF compliance was attempted. To use this:

restconf.Compliance = restconf.Simplified

or you can just set individual settings on restconf.Compliance global variable.

var Strict = ComplianceOptions{}

Compliance is the global variable that sets the default behavior if the FreeCONF RESTCONF library.

By default this is for strict IETF compliance!

This sets just the default behavior of data structures, each individual instance should allow for controlling the compliance of that instance should you need to have instances in different modes at the same time.

Functions

func FindDeviceIdInUrl

func FindDeviceIdInUrl(addr string) string

FindDeviceIdInUrl picks out device id in URL

func Node

func Node(mgmt *Server, ypath source.Opener) node.Node

func SplitAddress

func SplitAddress(fullurl string) (address string, module string, path string, err error)

SplitAddress takes a complete address and breaks it into pieces according to RESTCONF standards so you can use each piece in appropriate API call Example:

http://server[:port]/restconf[=device]/module:path/here

func SplitUri

func SplitUri(uri string) (module string, path string, err error)

Types

type AnyDataReader

type AnyDataReader interface {
	io.Reader
	Name() string
}

AnyDataReader is field value for anydata types that are io.Reader, but receiver might also want the name submitted with reader. Think file upload or plain old os.File as underlying type

type ComplianceContextKeyType

type ComplianceContextKeyType string

type ComplianceOptions

type ComplianceOptions struct {

	// allow rpc to serve under /restconf/data/{module:}/{rpc} which while intuative
	// it is not in compliance w/RESTCONF spec
	AllowRpcUnderData bool

	// IETF notification messages with extra data including
	// event time and ietf-restconf:notfication container
	// https://datatracker.ietf.org/doc/html/rfc8040#section-6.4
	DisableNotificationWrapper bool

	// IETF rpc/action inputs and outputs are wrapped with extra container
	// https://datatracker.ietf.org/doc/html/rfc8040#section-6.
	DisableActionWrapper bool

	// Errors have a specific structure
	// https://datatracker.ietf.org/doc/html/rfc8040#section-3.6.3
	SimpleErrorResponse bool

	// QualifyNamespaceDisabled when true then all JSON object keys will not
	// include YANG module according to RFC7952.
	QualifyNamespaceDisabled bool
}

ComplianceOptions hold all the compliance settings. If you enable any of these settings, then you run the risk of not being complatible with other RESTCONF implementations

func (ComplianceOptions) String

func (compliance ComplianceOptions) String() string

type MimeType

type MimeType string

func (MimeType) IsJson

func (m MimeType) IsJson() bool

func (MimeType) IsRfc

func (m MimeType) IsRfc() bool

func (MimeType) IsXml

func (m MimeType) IsXml() bool

type ProxyContextKey

type ProxyContextKey string

type RequestFilter

type RequestFilter func(ctx context.Context, w http.ResponseWriter, r *http.Request) (context.Context, error)

type Server

type Server struct {
	Web *stock.HttpServer

	Auth                     secure.Auth
	Ver                      string
	NotifyKeepaliveTimeoutMs int

	// Optional: Anything not handled by RESTCONF protocol can call this handler otherwise
	UnhandledRequestHandler http.HandlerFunc

	// Give app change to read custom header data and stuff into context so info can get
	// to app layer
	Filters []RequestFilter

	// allow rpc to serve under /restconf/data/{module:}/{rpc} which while intuative and
	// original design, it is not in compliance w/RESTCONF spec
	OnlyStrictCompliance bool
	// contains filtered or unexported fields
}

func NewHttpServe

func NewHttpServe(d *device.Local) *Server

func NewServer

func NewServer(d *device.Local) *Server

func (*Server) Close

func (srv *Server) Close() error

func (*Server) DeviceAddress

func (srv *Server) DeviceAddress(id string, d device.Device) string

func (*Server) ModuleAddress

func (srv *Server) ModuleAddress(m *meta.Module) string

func (*Server) RegisterWebApp

func (srv *Server) RegisterWebApp(homeDir string, homePage string, endpoint string)

func (*Server) ServeDevice

func (srv *Server) ServeDevice(d device.Device) error

func (*Server) ServeDevices

func (srv *Server) ServeDevices(m device.Map) error

func (*Server) ServeHTTP

func (srv *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)