ndn

Documentation

Overview

Package ndn provides basic interfaces of NDN packet, Specification abstraction, and low-level engine. Most high level packages will only depend on ndn, instead of specific implementations. To simplify implementation, Data and Interest are immutable. Package `ndn.spec_2022` has a default implementation of these interfaces based on current NDN Spec.

Index

• Variables
• type ContentType
• type Data
• type DataConfig
• type Engine
• type ErrInvalidValue
  • func (e ErrInvalidValue) Error() string
• type ErrNotSupported
  • func (e ErrNotSupported) Error() string
• type ExpressCallbackFunc
• type Interest
• type InterestConfig
• type InterestHandler
• type InterestResult
• type ReplyFunc
• type SigChecker
• type SigConfig
• type SigType
• type Signature
• type Signer
• type Spec
• type Timer

Variables

var ErrDeadlineExceed = errors.New("Interest deadline exceeded.")

ErrDeadlineExceed is returned when the deadline of the Interest passed.

var ErrFaceDown = errors.New("Face is down. Unable to send packet.")

ErrFaceDown is returned when the face is closed.

var ErrFailedToEncode = errors.New("Failed to encode an NDN packet.")

ErrFailedToEncode is returned when encoding fails but the input arguments are valid.

var ErrPrefixPropViolation = errors.New("A prefix or extention of the given handler prefix is already attached.")

ErrPrefixPropViolation is returned when the prefix property is violated during handler registration.

var ErrWrongType = errors.New("Packet to parse is not of desired type.")

ErrWrongType is returned when the type of the packet to parse is not expected.

Types

type ContentType

type ContentType uint

ContentType represents the type of Data content in MetaInfo.

const (
	ContentTypeBlob ContentType = 0
	ContentTypeLink ContentType = 1
	ContentTypeKey  ContentType = 2
	ContentTypeNack ContentType = 3
)

type Data

type Data interface {
	Name() enc.Name
	ContentType() *ContentType
	Freshness() *time.Duration
	FinalBlockID() *enc.Component
	Content() enc.Wire

	Signature() Signature
}

Data is the abstract of a received Data packet.

type DataConfig

type DataConfig struct {
	ContentType  *ContentType
	Freshness    *time.Duration
	FinalBlockID *enc.Component
}

DataConfig is used to create a Data.

type Engine

type Engine interface {
	// EngineTrait is the type trait of the NDN engine.
	EngineTrait() Engine
	// Spec returns an NDN packet specification.
	Spec() Spec
	// Timer returns a Timer managed by the engine.
	Timer() Timer
	// AttachHandler attaches an Interest handler to the namespace of prefix.
	// Interest handlers are required to have non-overlapping namespace.
	// That is, one handler's prefix must not be the prefix of another handler's prefix.
	AttachHandler(prefix enc.Name, handler InterestHandler) error
	// DetachHandler detaches an Interest handler from the namespace of prefix.
	DetachHandler(prefix enc.Name) error
	// RegisterRoute registers a route of prefix to the local forwarder.
	RegisterRoute(prefix enc.Name) error
	// UnregisterRoute unregisters a route of prefix to the local forwarder.
	UnregisterRoute(prefix enc.Name) error
	// Express expresses an Interest, with callback called when there is result.
	// To simplify the implementation, finalName needs to be the final Interest name given by MakeInterest.
	// The callback should create go routine or channel back to another routine to avoid blocking the main thread.
	Express(finalName enc.Name, config *InterestConfig, rawInterest enc.Wire, callback ExpressCallbackFunc) error
}

Engine represents a running NDN App low-level engine. Used by NTSchema.

type ErrInvalidValue

type ErrInvalidValue struct {
	Item  string
	Value any
}

func (ErrInvalidValue) Error

func (e ErrInvalidValue) Error() string

type ErrNotSupported

type ErrNotSupported struct {
	Item string
}

func (ErrNotSupported) Error

func (e ErrNotSupported) Error() string

type ExpressCallbackFunc

type ExpressCallbackFunc func(result InterestResult, data Data, rawData enc.Wire,
	sigCovered enc.Wire, nackReason uint64)

ExpressCallbackFunc represents the callback function for Interest expression.

type Interest

type Interest interface {
	Name() enc.Name
	CanBePrefix() bool
	MustBeFresh() bool
	ForwardingHint() []enc.Name
	Nonce() *uint64
	Lifetime() *time.Duration
	HopLimit() *uint
	AppParam() enc.Wire

	Signature() Signature
}

Interest is the abstract of a received Interest packet.

type InterestConfig

type InterestConfig struct {
	CanBePrefix    bool
	MustBeFresh    bool
	ForwardingHint []enc.Name
	Nonce          *uint64
	Lifetime       *time.Duration
	HopLimit       *uint
}

InterestConfig is used to create a Interest.

type InterestHandler

type InterestHandler func(
	interest Interest, rawInterest enc.Wire, sigCovered enc.Wire,
	reply ReplyFunc, deadline time.Time,
)

InterestHandler represents the callback function for an Interest handler. It should create a go routine to avoid blocking the main thread, if either 1) Data is not ready to send; or 2) Validation is required.

type InterestResult

type InterestResult int

InterestResult represents the result of Interest expression. Can be Data fetched (succeeded), NetworkNack received, or Timeout. Note that AppNack is considered as Data.

const (
	// Empty result. Not used by the engine.
	// Used by high-level part if the setting to construct an Interest is incorrect.
	InterestResultNone InterestResult = iota
	// Data is fetched
	InterestResultData
	// NetworkNack is received
	InterestResultNack
	// Timeout
	InterestResultTimeout
	// Cancelled due to disconnection
	InterestCancelled
	// Failed of validation. Not used by the engine itself.
	InterestResultUnverified
	// Other error happens during handling the fetched data. Not used by the engine itself.
	InterestResultError
)

type ReplyFunc

type ReplyFunc func(encodedData enc.Wire) error

ReplyFunc represents the callback function to reply for an Interest.

type SigChecker

type SigChecker func(name enc.Name, sigCovered enc.Wire, sig Signature) bool

SigChecker is a basic function to check the signature of a packet. In NTSchema, policies&sub-trees are supposed to be used for validation; SigChecker is only designed for low-level engine. Create a go routine for time consuming jobs.

type SigConfig

type SigConfig struct {
	Type      SigType
	KeyName   enc.Name
	Nonce     []byte
	SigTime   *time.Time
	SeqNum    *uint64
	NotBefore *time.Time
	NotAfter  *time.Time
}

SigConfig represents the configuration of signature used in signing.

type SigType

type SigType int

SigType represents the type of signature.

const (
	SignatureNone            SigType = -1
	SignatureDigestSha256    SigType = 0
	SignatureSha256WithRsa   SigType = 1
	SignatureSha256WithEcdsa SigType = 3
	SignatureHmacWithSha256  SigType = 4
	SignatureEd25519         SigType = 5
	SignatureEmptyTest       SigType = 200
)

type Signature

type Signature interface {
	SigType() SigType
	KeyName() enc.Name
	SigNonce() []byte
	SigTime() *time.Time
	SigSeqNum() *uint64
	Validity() (notBefore, notAfter *time.Time)

	SigValue() []byte
}

Signature is the abstract of the signature of a packet. Some of the fields are invalid for Data or Interest.

type Signer

type Signer interface {
	SigInfo() (*SigConfig, error)
	EstimateSize() uint
	ComputeSigValue(enc.Wire) ([]byte, error)
}

Signer is the interface of the signer of a packet.

type Spec

type Spec interface {
	// MakeData creates a Data packet, returns the encoded Data, signature covered parts, and error.
	MakeData(name enc.Name, config *DataConfig, content enc.Wire, signer Signer) (enc.Wire, enc.Wire, error)
	// MakeData creates an Interest packet, returns the encoded Interest, signature covered parts,
	// the final Interest name, and error.
	MakeInterest(
		name enc.Name, config *InterestConfig, appParam enc.Wire, signer Signer,
	) (enc.Wire, enc.Wire, enc.Name, error)
	// ReadData reads and parses a Data from the reader, returns the Data, signature covered parts, and error.
	ReadData(reader enc.ParseReader) (Data, enc.Wire, error)
	// ReadData reads and parses an Interest from the reader, returns the Data, signature covered parts, and error.
	ReadInterest(reader enc.ParseReader) (Interest, enc.Wire, error)
}

Spec represents an NDN packet specification.

type Timer

type Timer interface {
	// Now returns current time.
	Now() time.Time
	// Sleep sleeps for the duration.
	Sleep(time.Duration)
	// Schedule schedules the callback function to be called after the duration,
	// and returns a cancel callback to cancel the scheduled function.
	Schedule(time.Duration, func()) func() error
	// Nonce generates a random nonce.
	Nonce() []byte
}