ndn

type Announcement struct {
	// Name of the prefix to announce.
	Name enc.Name
	// Cost of the prefix.
	Cost uint64
	// Expose the prefix to the global network.
	Expose bool
	// OnError is called when an error occurs.
	// It may be called multiple times, e.g. if the face is reopened.
	OnError func(error)
}

type Client interface {
	// String is the instance log identifier.
	String() string
	// Start starts the client. The engine must be running.
	Start() error
	// Stop stops the client.
	Stop() error
	// Engine gives the underlying API engine.
	Engine() Engine
	// Store gives the underlying data store.
	Store() Store

	// Produce generates and signs data, and inserts into the client's store.
	// The input data will be freed as the object is segmented.
	// Returns the final versioned name of the object.
	Produce(args ProduceArgs) (enc.Name, error)
	// Remove removes an object from the client's store by name.
	Remove(name enc.Name) error

	// Consume fetches an object with a given name.
	// By default, Consume will attemt to discover the latest version of the object.
	// To specify a particular version, use Name.WithVersion()
	Consume(name enc.Name, callback func(status ConsumeState))
	// ConsumeExt is a more advanced consume API that allows for
	// more control over the fetching process.
	ConsumeExt(args ConsumeExtArgs)

	// LatestLocal returns the latest version name of an object in the store.
	LatestLocal(name enc.Name) (enc.Name, error)
	// GetLocal returns the object data from the store.
	GetLocal(name enc.Name) (enc.Wire, error)

	// ExpressR sends a single interest with reliability.
	// Since this is a low-level API, the result is NOT validated.
	ExpressR(args ExpressRArgs)
	// IsCongested returns true if the client is congested.
	IsCongested() bool

	// Suggest suggests a signer for a given name.
	// nil is returned if no signer is found.
	SuggestSigner(name enc.Name) Signer
	// Validate validates a single data packet.
	Validate(data Data, sigCov enc.Wire, callback func(bool, error))
	// ValidateExt validates a single data packet (advanced API).
	ValidateExt(args ValidateExtArgs)

	// AnnouncePrefix announces a prefix to the network.
	AnnouncePrefix(args Announcement)
	// WithdrawPrefix withdraws a prefix from the network.
	WithdrawPrefix(name enc.Name, onError func(error))

	// [EXPERIMENTAL] AttachCommandHandler creates a signed command handler.
	// Currently signed commands bundle a signed data packet with a command
	// inside an Interest's AppParam. The command cannot be bigger than
	// the NDN MTU size since it must fit within a single packet.
	//
	// These methods are considered as experimental and work-in-progress.
	AttachCommandHandler(name enc.Name, handler func(name enc.Name, content enc.Wire, reply func(enc.Wire) error)) error
	// [EXPERIMENTAL] DetachCommandHandler removes a signed command handler.
	DetachCommandHandler(name enc.Name) error
	// [EXPERIMENTAL] ExpressCommand sends a signed command to a given name.
	ExpressCommand(dest enc.Name, name enc.Name, cmd enc.Wire, callback func(enc.Wire, error))
}

type ConsumeExtArgs struct {
	// Name is the name of the object to consume.
	Name enc.Name
	// Try the local store to get the object.
	// Note that if Name is not versioned, this may get an older version.
	TryStore bool
	// Callback is called when data is available.
	// True should be returned to continue fetching the object.
	Callback func(status ConsumeState)
	// OnProgress is called when progress is made (advanced usage).
	// [Caution] Any data returned by Content() may not be validated.
	OnProgress func(status ConsumeState)
	// NoMetadata disables fetching RDR metadata (advanced usage).
	NoMetadata bool
}

type ConsumeState interface {
	// Name of the object being consumed including version.
	Name() enc.Name
	// Version of the object being consumed.
	Version() uint64

	// IsComplete returns true if the content has been completely fetched.
	IsComplete() bool
	// Progress counter
	Progress() int
	// ProgressMax is the max value for the progress counter (-1 for unknown).
	ProgressMax() int
	// Error that occurred during fetching.
	Error() error

	// Content is the currently available buffer in the content.
	// any subsequent calls to Content() will return data after the previous call.
	Content() enc.Wire

	// Cancel the consume operation.
	Cancel()
}

type ContentType uint64

type Data interface {
	Name() enc.Name
	ContentType() optional.Optional[ContentType]
	Freshness() optional.Optional[time.Duration]
	FinalBlockID() optional.Optional[enc.Component]
	Content() enc.Wire
	Signature() Signature
	CrossSchema() enc.Wire
}

type DataConfig struct {
	// Standard Data parameters
	ContentType  optional.Optional[ContentType]
	Freshness    optional.Optional[time.Duration]
	FinalBlockID optional.Optional[enc.Component]

	// Certificate parameters
	SigNotBefore optional.Optional[time.Time]
	SigNotAfter  optional.Optional[time.Time]

	// Cross Schema attachment
	CrossSchema enc.Wire
}

type EncodedData struct {
	// Encoded Data packet
	Wire enc.Wire
	// Signed part of the Data
	SigCovered enc.Wire
	// Parameter configuration of the Data
	Config *DataConfig
}

type EncodedInterest struct {
	// Encoded Interest packet
	Wire enc.Wire
	// Signed part of the Interest
	SigCovered enc.Wire
	// Final name of the Interest
	FinalName enc.Name
	// Parameter configuration of the Interest
	Config *InterestConfig
}

type Engine interface {
	// String is the instance log identifier.
	String() string
	// 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
	// Face returns the face of the engine.
	Face() Face

	// Start processing packets.
	// If the engine is attached to a face, this will attempt
	// to open the face, and may block until the face is up.
	Start() error
	// Stops processing packets.
	Stop() error
	// Checks if the engine is running.
	IsRunning() bool

	// AttachHandler attaches an Interest handler to the namespace of prefix.
	AttachHandler(prefix enc.Name, handler InterestHandler) error
	// DetachHandler detaches an Interest handler from the namespace of prefix.
	DetachHandler(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(interest *EncodedInterest, callback ExpressCallbackFunc) error

	// ExecMgmtCmd executes a management command.
	//   args are the control arguments (*mgmt.ControlArgs)
	//   returns response and error if any (*mgmt.ControlResponse, error)
	ExecMgmtCmd(module string, cmd string, args any) (any, error)
	// SetCmdSec sets the interest signing parameters for management commands.
	SetCmdSec(signer Signer, validator func(enc.Name, enc.Wire, Signature) bool)
	// 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

	// Post a task to the engine goroutine (internal usage only).
	// Be careful not to deadlock the engine.
	Post(func())
}

type ErrInvalidValue struct {
	Item  string
	Value any
}

type ErrNotSupported struct {
	Item string
}

type ExpressCallbackArgs struct {
	// Result of the Interest expression.
	// If the result is not InterestResultData, Data fields are invalid.
	Result InterestResult
	// Data fetched.
	Data Data
	// Raw Data wire.
	RawData enc.Wire
	// Signature covered part of the Data.
	SigCovered enc.Wire
	// NACK reason code, if the result is InterestResultNack.
	NackReason uint64
	// Error, if the result is InterestResultError.
	Error error
	// IsLocal indicates if a local copy of the Data was found.
	// e.g. returned by ExpressR when used with TryStore.
	IsLocal bool
}

type ExpressCallbackFunc func(args ExpressCallbackArgs)

type ExpressRArgs struct {
	// Name of the data to fetch.
	Name enc.Name
	// Interest configuration.
	Config *InterestConfig
	// AppParam for the interest.
	AppParam enc.Wire
	// Signer for signed interests.
	Signer Signer
	// Number of retries.
	Retries int
	// Try to get the data from a local store.
	TryStore Store
	// Callback for the result. This will be called on the engine's
	// main thread, so make sure it is either non-blocking and very fast,
	// or use a goroutine to handle the result.
	Callback ExpressCallbackFunc
}

type Face interface {
	// String returns the log identifier.
	String() string
	// IsRunning returns true if the face is running.
	IsRunning() bool
	// IsLocal returns true if the face is local.
	IsLocal() bool
	// OnPacket sets the callback for receiving packets.
	// This function should only be called by engine implementations.
	OnPacket(onPkt func(frame []byte))
	// OnError sets the callback for fatal errors.
	// On receiving an error, the engine will close itself.
	// This function should only be called by engine implementations.
	OnError(onError func(err error))

	// Open starts the face and may blocks until it is up.
	Open() error
	// Close stops the face.
	Close() error
	// Send sends a packet frame to the face.
	Send(pkt enc.Wire) error

	// OnUp sets the callback for the face going up.
	// The callback may be called multiple times.
	OnUp(onUp func()) (cancel func())
	// OnDown sets the callback for the face going down.
	// The callback may be called multiple times.
	// The callback will not be called when the face is closed.
	OnDown(onDown func()) (cancel func())
}

type Interest interface {
	// Name of the Interest packet
	Name() enc.Name
	// Indicates whether a Data with a longer name can match
	CanBePrefix() bool
	// Indicates whether the Data must be fresh
	MustBeFresh() bool
	// ForwardingHint is the list of names to guide the Interest forwarding
	ForwardingHint() []enc.Name
	// Number to identify the Interest uniquely
	Nonce() optional.Optional[uint32]
	// Lifetime of the Interest
	Lifetime() optional.Optional[time.Duration]
	// Max number of hops the Interest can traverse
	HopLimit() *uint
	// Application parameters of the Interest (optional)
	AppParam() enc.Wire
	// Signature on the Interest (optional)
	Signature() Signature
}

type InterestConfig struct {
	// Standard Interest parameters
	CanBePrefix    bool
	MustBeFresh    bool
	ForwardingHint []enc.Name
	Nonce          optional.Optional[uint32]
	Lifetime       optional.Optional[time.Duration]
	HopLimit       *byte

	// Signed Interest parameters.
	// The use of signed interests is strongly discouraged, and will
	// be gradually phased out, which is why these parameters are
	// not directly provided by the signer.
	SigNonce []byte
	SigTime  optional.Optional[time.Duration]
	SigSeqNo optional.Optional[uint64]

	// NDNLPv2 parameters
	NextHopId optional.Optional[uint64]
}

type InterestHandler func(args InterestHandlerArgs)

type InterestHandlerArgs struct {
	// Decoded interest packet
	Interest Interest
	// Function to reply to the Interest
	Reply WireReplyFunc
	// Raw Interest packet wire
	RawInterest enc.Wire
	// Signature covered part of the Interest
	SigCovered enc.Wire
	// Deadline of the Interest
	Deadline time.Time
	// PIT token
	PitToken []byte
	// Incoming face ID (if available)
	IncomingFaceId optional.Optional[uint64]
}

type InterestResult int

type KeyChain interface {
	// String provides the log identifier of the keychain.
	String() string
	// Store provides the public storage of the keychain.
	Store() Store
	// Identities returns all identities in the keychain.
	Identities() []KeyChainIdentity
	// IdentityByName returns the identity by full name.
	IdentityByName(enc.Name) KeyChainIdentity
	// InsertKey inserts a key to the keychain.
	InsertKey(Signer) error
	// InsertCert inserts a certificate to the keychain.
	InsertCert([]byte) error
}

type KeyChainIdentity interface {
	// Name returns the full name of the identity.
	Name() enc.Name
	// Keys returns all keys of the identity.
	Keys() []KeyChainKey
}

type KeyChainKey interface {
	// KeyName returns the key name of the key.
	KeyName() enc.Name
	// Signer returns the signer of the key.
	Signer() Signer
	// UniqueCerts returns a list of unique cert names in the key.
	// The version number is always set to zero.
	UniqueCerts() []enc.Name
}

type ProduceArgs struct {
	// Name is the name of the object to produce.
	// The version of the object MUST be set using WithVersion.
	Name enc.Name
	// Content is the raw data wire.
	// Content can be larger than a single packet and will be segmented.
	Content enc.Wire
	// Time for which the object version can be cached (default 4s).
	FreshnessPeriod time.Duration
	// NoMetadata disables RDR metadata (advanced usage).
	NoMetadata bool
}

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

type SigType int

type Signature interface {
	// SigType returns the type of the signature.
	SigType() SigType
	// KeyName returns the key locator in the signature.
	// Note that this may not be the actual key name.
	KeyName() enc.Name
	// Validity returns the validity period of the signature.
	// This field is generally only present in NDN certificates.
	Validity() (notBefore, notAfter optional.Optional[time.Time])
	// SigValue returns the signature value.
	SigValue() []byte

	// SigNonce returns the nonce in the Interest signature.
	SigNonce() []byte
	// SigTime returns the time in the Interest signature.
	SigTime() *time.Time
	// SigSeqNum returns the sequence number in the Interest signature.
	SigSeqNum() *uint64
}

type Signer interface {
	// SigInfo returns the configuration of the signature.
	Type() SigType
	// KeyName returns the key name of the signer.
	KeyName() enc.Name
	// KeyLocator returns the key locator name of the signer.
	KeyLocator() enc.Name
	// EstimateSize gives the approximate size of the signature in bytes.
	EstimateSize() uint
	// Sign computes the signature value of a wire.
	Sign(enc.Wire) ([]byte, error)
	// Public returns the public key of the signer or nil.
	Public() ([]byte, error)
}

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

type Store interface {
	// Get returns a Data wire matching the given name
	// prefix = return the lexicographically last Data wire with the given prefix
	Get(name enc.Name, prefix bool) ([]byte, error)

	// Put inserts a Data wire into the store
	Put(name enc.Name, wire []byte) error

	// Remove removes a Data wire from the store
	Remove(name enc.Name) error
	// RemovePrefix remove all Data wires under a prefix
	RemovePrefix(prefix enc.Name) error
	// RemoveFlatRange removes (recursively) all subtrees under a range of
	// flat prefixes. This is useful for removing a range of segments or
	// sequence numbers that have the same prefix.
	// The removal is inclusive of the first and last element.
	//  i.e. RemoveFlatRange({/A/B}, 0, 3) removes {/A/B/0}, {/A/B/1}, {/A/B/2}, {/A/B/3}
	// The first and last components must be a number of the same type,
	// otherwise the behavior is undefined (since ordering is undefined)
	RemoveFlatRange(prefix enc.Name, first enc.Component, last enc.Component) error

	// Begin starts a write transaction (for put only)
	// we support these primarily for performance rather than correctness
	// do not rely on atomicity of transactions as far as possible
	Begin() (Store, error)
	// Commit commits a write transaction
	Commit() error
	// Rollback discards a write transaction
	Rollback() error
}

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
}

type TrustSchema interface {
	// Check checks if a packet can be signed with the provided certificate.
	Check(pkt enc.Name, cert enc.Name) bool
	// Suggest suggests a signer for a packet.
	Suggest(enc.Name, KeyChain) Signer
}

type ValidateExtArgs struct {
	// Data packet to validate.
	Data Data
	// Signature covered wire.
	SigCovered enc.Wire
	// Callback for the result.
	Callback func(bool, error)
	// Override data name during first validation.
	OverrideName enc.Name
	// Next Hop ID to use for fetching certificates.
	CertNextHop optional.Optional[uint64]
	// UseDataNameFwHint overrides trust config option.
	UseDataNameFwHint optional.Optional[bool]
}

type WireReplyFunc func(wire enc.Wire) error