l3

Documentation

Overview

Package l3 defines a network layer face abstraction.

The Transport interface defines a lower layer communication channel. It knows NDN-TLV structure, but not NDN packet types. It should be implemented for different communication technologies. NDNgo library offers Transport implementations for memif, UDP sockets, etc.

The Face type is the service exposed to the network layer. It allows sending and receiving packets on a Transport.

Index

• Constants
• Variables
• func DeleteDefaultForwarder()
• func NewTransportBase(cfg TransportBaseConfig) (b *TransportBase, p *TransportBasePriv)
• type Face
  • func NewFace(tr Transport, cfg FaceConfig) (Face, error)
• type FaceConfig
• type Forwarder
  • func GetDefaultForwarder() Forwarder
  • func NewForwarder() Forwarder
• type FwFace
• type ReadvertiseDestination
• type Transport
• type TransportBase
  • func (b *TransportBase) MTU() int
  • func (b *TransportBase) OnStateChange(cb func(st TransportState)) (cancel func())
  • func (b *TransportBase) State() TransportState
• type TransportBaseConfig
• type TransportBasePriv
  • func (p *TransportBasePriv) SetState(st TransportState)
• type TransportState
  • func (st TransportState) String() string

Constants

const (
	MinReassemblerCapacity = 16
	DefaultRxQueueSize     = 64
	DefaultTxQueueSize     = 64
)

Limits and defaults.

const MaxFwFaces = 1 << 23

MaxFwFaces is the maximum number of active FwFaces in a Forwarder.

Variables

var (
	ErrMaxFwFaces = errors.New("too many FwFaces")
)

Error conditions.

Functions

func DeleteDefaultForwarder

func DeleteDefaultForwarder()

DeleteDefaultForwarder deletes the default Forwarder. This is non-thread-safe and should only be used in test cases.

func NewTransportBase

func NewTransportBase(cfg TransportBaseConfig) (b *TransportBase, p *TransportBasePriv)

NewTransportBase creates helpers for implementing Transport.

Types

type Face

type Face interface {
	// Transport returns the underlying transport.
	Transport() Transport

	// Rx returns a channel to receive incoming packets toward the forwarder.
	// This function always returns the same channel.
	// This channel is closed when the face is closed.
	Rx() <-chan *ndn.Packet

	// Tx returns a channel to send outgoing packets from the forwarder.
	// This function always returns the same channel.
	// Closing this channel causes the face to close.
	Tx() chan<- ndn.L3Packet

	State() TransportState
	OnStateChange(cb func(st TransportState)) (cancel func())
}

Face represents a communicate channel to send and receive NDN network layer packets.

func NewFace

func NewFace(tr Transport, cfg FaceConfig) (Face, error)

NewFace creates a Face. tr.Read() and tr.Write() should not be used after this operation.

type FaceConfig

type FaceConfig struct {
	// ReassemblerCapacity is the maximum number of partial messages stored in the reassembler.
	// Default is MinReassemblerCapacity.
	ReassemblerCapacity int

	// RxQueueSize is the Go channel buffer size of RX channel.
	// Default is DefaultRxQueueSize.
	RxQueueSize int `json:"rxQueueSize,omitempty"`

	// TxQueueSize is the Go channel buffer size of TX channel.
	// Default is DefaultTxQueueSize.
	TxQueueSize int `json:"txQueueSize,omitempty"`
}

FaceConfig contains options for NewFace.

type Forwarder

type Forwarder interface {
	// AddFace adds a Face to the forwarder.
	// face.Rx() and face.Tx() should not be used after this operation.
	AddFace(face Face) (FwFace, error)

	// AddReadvertiseDestination adds a destination for prefix announcement.
	//
	// Limitations of current implementation:
	//  - Existing announcements are not advertised on dest.
	//    Thus, it is recommended to add all readvertise destinations before announcing a prefix.
	//  - There is no error handling.
	AddReadvertiseDestination(dest ReadvertiseDestination)

	// RemoveReadvertiseDestination removes a destination for prefix announcement.
	//
	// Limitations of current implementation:
	//  - Announcements are not withdrawn before removing dest.
	//  - There is no error handling.
	RemoveReadvertiseDestination(dest ReadvertiseDestination)
}

Forwarder is a logical forwarding plane. Its main purpose is to demultiplex incoming packets among faces, where a 'face' is defined as a duplex stream of packets.

This is a simplified forwarder with several limitations.

• There is no loop prevention: no Nonce list and no decrementing HopLimit. If multiple uplinks have "/" route, Interests will be forwarded among them and might cause persistent loops. Thus, it is not recommended to connect to multiple uplinks with overlapping routes.
• There is no pending Interest table. Instead, downstream 'face' ID is inserted as part of the PIT token. Since PIT token cannot exceed 32 octets, this takes away some space. Thus, consumers are allowed to use a PIT token up to 28 octets; Interests with longer PIT tokens may be dropped.

func GetDefaultForwarder

func GetDefaultForwarder() Forwarder

GetDefaultForwarder returns the default Forwarder.

func NewForwarder

func NewForwarder() Forwarder

NewForwarder creates a Forwarder.

type FwFace

type FwFace interface {
	io.Closer
	Transport() Transport
	State() TransportState
	OnStateChange(cb func(st TransportState)) (cancel func())

	AddRoute(name ndn.Name)
	RemoveRoute(name ndn.Name)

	AddAnnouncement(name ndn.Name)
	RemoveAnnouncement(name ndn.Name)
}

FwFace represents a face added to the forwarder.

type ReadvertiseDestination

type ReadvertiseDestination interface {
	Advertise(name ndn.Name) error

	Withdraw(name ndn.Name) error
}

ReadvertiseDestination represents a destination of name advertisement.

Generally, a name advertised to a destination would cause Interests matching the name to come to the forwarder. This is also known as name registration.

type Transport

type Transport interface {
	io.ReadWriteCloser

	// MTU returns maximum size of outgoing packets.
	MTU() int

	// State returns current state.
	State() TransportState

	// OnStateChange registers a callback to be invoked when State() changes.
	// Returns a function to cancel the callback registration.
	OnStateChange(cb func(st TransportState)) (cancel func())
}

Transport represents a communicate channel to send and receive TLV packets.

type TransportBase

type TransportBase struct {
	// contains filtered or unexported fields
}

TransportBase is an optional helper for implementing Transport.

func (*TransportBase) MTU

func (b *TransportBase) MTU() int

MTU implements Transport interface.

func (*TransportBase) OnStateChange

func (b *TransportBase) OnStateChange(cb func(st TransportState)) (cancel func())

OnStateChange implements Transport interface.

func (*TransportBase) State

func (b *TransportBase) State() TransportState

State implements Transport interface.

type TransportBaseConfig

type TransportBaseConfig struct {
	MTU          int
	InitialState TransportState
}

TransportBaseConfig contains parameters to NewTransportBase.

type TransportBasePriv

type TransportBasePriv struct {
	// contains filtered or unexported fields
}

TransportBasePriv is an optional helper for implementing Transport interface.

func (*TransportBasePriv) SetState

func (p *TransportBasePriv) SetState(st TransportState)

SetState changes transport state.

type TransportState

type TransportState int

TransportState indicates up/down state of a transport.

const (
	// TransportUp indicates the transport is operational.
	TransportUp TransportState = iota

	// TransportDown indicates the transport is nonoperational.
	TransportDown

	// TransportClosed indicates the transport has been closed.
	// It cannot be restarted.
	TransportClosed
)

func (TransportState) String

func (st TransportState) String() string