dv: add routing status datasets and an HTTP status page

docs/dv-control.md

@@ -2,6 +2,56 @@
 
 This is the detailed reference for the ndn-dv routing daemon control tool.
 
+## Routing status dataset
+
+Each DV router serves a read-only dataset at
+`/<router-name>/32=DV/32=STATUS`. For example:
+
+```sh
+ndnd cat /example/a/32=DV/32=STATUS > routing-status.tlv
+```
+
+The content is a `dv/tlv.RoutingStatus` snapshot of the responding router's
+view: its general status and all reachable routers, with each router's
+selected next hop, routing cost, and learned prefix announcements with their
+multicast flags and validity periods.
+Unreachable routers are omitted. Router and prefix entries are sorted by NDN
+name. This reports distance-vector reachability, rather than an NLSR
+link-state database or a complete graph of physical links.
+
+Fetch the unversioned name using the object client's `Consume` API. RDR
+metadata identifies a versioned, segmented object with a FinalBlockId.
+Snapshots have one-second freshness and a bounded history of recent versions
+is retained for in-progress segment fetches. Snapshot generation does not run
+on the engine's packet-processing loop.
+
+Secure routers sign metadata and data segments with their configured DV
+router key. Consumers should validate using the DV trust schema and their
+network's trust anchors. DV routers install PET egress mappings for other
+reachable routers' dataset prefixes, so queries can cross multiple upgraded DV hops.
+For remote validation, set `trust.UseDataNameFwHint = true` on the consumer's
+`security.TrustConfig` unless the certificate names are independently routable.
+This sends certificate Interests with the original Data name as a forwarding
+hint, allowing them to follow the dataset route back to its producer. The
+dataset routes alone do not route certificate names. DV routers already enable
+this option on their own trust configuration.
+The existing `/localhost/dv/status` summary remains available.
+When using an external routing trust schema, add a rule authorizing the status
+prefix under the router certificate, as shown in `dv/config/schema.trust`.
+
+The dataset content has these TLV fields. The complete wire grammar, including
+the nested status fields, is specified in the
+[routing status dataset specification](../dv/SPEC.md#routing-status-dataset).
+
+| Field | Type | Value |
+|---|---|---|
+| Status | `0x1A0` | Existing DV Status fields |
+| Router (repeated) | `0x1A2` | Name, NextHop, Cost, and Prefix fields |
+| Name | `0x07` | Router or announced prefix name |
+| NextHop | `0xCE` | Destination containing the selected router name |
+| Cost | `0xD0` | Non-negative integer |
+| Prefix (repeated within Router) | `0x130` | Announced Name, optional Multicast, and ValidityPeriod |
+
 ## `ndnd dv link-create`
 
 The link-create command creates a new neighbor link. A new permanent face will be created for the neighbor if a matching face does not exist.

docs/fw-control.md

@@ -8,6 +8,79 @@ You can also use the [nfdc](https://docs.named-data.net/NFD/24.07/manpages/nfdc.
 
 The status command shows general status of the forwarder, including its version, uptime, data structure counters, and global packet counters.
 
+## `ndnd fw status-report`
+
+The status-report command prints the NDNd status document as XML by default. Use `--format json` for JSON output. It includes general forwarder counters, faces, FIB, RIB, PET, and BIER/BIFT entries, content-store statistics, strategy choices, and DV status when the DV service is available. The DV section includes reachable routers, next hops, costs, and learned prefix announcements from the [DV routing dataset](dv-control.md#routing-status-dataset). Fields that NDNd does not provide, such as NameTree, Measurements, and Nack counters, are not included.
+
+DV2-specific sections include PET prefix-to-egress mappings, direct next-hop
+faces and costs, and multicast flags. The BIER/BIFT section reports whether
+BIER is enabled, the local bit index, router-to-BFR-ID mappings, next-hop
+faces, and neighbor forwarding masks as bit-position lists. Disabled BIER
+is explicit and distinct from enabled bit index zero. Both sections come
+from the local forwarder's management datasets; DV routing/PSD information
+comes from the signed router dataset when trust anchors are configured.
+
+The JSON field types are fixed, independent of the current value:
+
+| Fields | JSON type |
+|---|---|
+| Cumulative packet/byte counters and content-store hits/misses | Decimal string |
+| Face identifiers, FIB/RIB/PET costs, congestion intervals and thresholds | Decimal string |
+| Table sizes, neighbor counts, and content-store capacity | Number |
+| DV router costs, BIER bit indices, MTUs, and expiration periods in milliseconds | Number |
+
+Strings preserve exact full-width integers, including zero and small values.
+Numbers represent operational quantities such as current table sizes and
+bounded DV costs. XML and HTML output retain their existing representations.
+
+The dataset reader accepts reachable router costs below `16`, using NDNd's existing DV infinity limit.
+A dataset containing a cost outside this range is rejected and its DV
+routing details are marked unavailable in all report formats; other status
+sections remain available.
+
+## `ndnd fw status-server`
+
+The status-server command serves a server-rendered HTML status page at `/` and machine-readable reports at `/status.xml` (`application/xml`) and `/status.json` (`application/json`) over HTTP on port 6380. These endpoints use the same encoders as `status-report`. All formats use the same management datasets. Missing DV status or an unavailable routing dataset is explicitly marked, including when querying an older DV router.
+
+```sh
+ndnd fw status-report > status.xml
+ndnd fw status-report --format json > status.json
+ndnd fw status-server
+# Open http://localhost:6380/
+curl http://localhost:6380/status.xml
+curl http://localhost:6380/status.json
+```
+
+Both status commands accept repeatable `--trust-anchor FILE` options for DV
+routing dataset validation. Each file contains one or more trusted NDN root
+certificates in PEM or binary format; private keys are not required. Metadata
+and every data segment are validated against these anchors and a locally
+selected trust schema. `--trust-schema FILE` loads a compiled LVS schema;
+otherwise the bundled [DV trust schema](../dv/config/schema.trust) is used.
+A custom schema requires at least one trust anchor. Missing or invalid files
+fail at startup. Schema mismatches reject the routing dataset; there is no
+fallback to the bundled schema, `NullSchema`, or unvalidated data after a
+custom schema is selected. Certificate retrieval uses the
+data name as a forwarding hint.
+
+```sh
+ndnd fw status-report --trust-anchor network-root.cert
+ndnd fw status-server --trust-anchor network-root.cert
+# Use the deployment's routing schema, including its status dataset rule:
+ndnd fw status-server --trust-schema dv-schema.tlv --trust-anchor network-root.cert
+```
+
+Without trust anchors, or when validation fails, DV routing details are marked
+unavailable. There is no unvalidated fallback for the routing dataset. General
+forwarder datasets and the local DV summary continue to use the existing
+management connection's trust model; these are not authenticated by the DV
+schema.
+
+When DV validation is configured, failures are logged to stderr with the router
+name and the underlying retrieval, validation, or parsing error. The report
+still includes available forwarder status. Omitting trust anchors intentionally
+disables the routing dataset and does not produce a warning.
+
 ## `ndnd fw face-list`
 
 The face list command prints the face table, which contains information about faces.
@@ -99,6 +172,37 @@ The fib-list command prints the existing FIB entries.
 The bift-list command prints the current Bit Index Forwarding Table (BIFT)
 entries, including each router's BFR-ID, next-hop face ID, and forwarding bit mask.
 
+### BIFT management dataset
+
+`/localhost/nfd/bift/list` serves a segmented TLV dataset, consumed by both
+`bift-list` and the status reports. This replaces DV2's previous JSON wire
+payload; the forwarder and its consumers must be updated together. JSON
+remains available as a report output format through `/status.json`.
+
+```abnf
+BiftStatus = BiftGeneralStatus *BiftEntry *BiftNeighbor
+BiftGeneralStatus = BIFT-GENERAL-TYPE TLV-LENGTH [BierIndex]
+BiftEntry = BIFT-ENTRY-TYPE TLV-LENGTH BierIndex Name *FaceId *FbmBit
+BiftNeighbor = BIFT-NEIGHBOR-TYPE TLV-LENGTH FaceId *FbmBit
+BierIndex = BIER-INDEX-TYPE TLV-LENGTH NonNegativeInteger
+FaceId = FACE-ID-TYPE TLV-LENGTH NonNegativeInteger
+FbmBit = FBM-BIT-TYPE TLV-LENGTH NonNegativeInteger
+
+BIFT-GENERAL-TYPE = 768
+BIFT-ENTRY-TYPE = 770
+BIFT-NEIGHBOR-TYPE = 772
+BIER-INDEX-TYPE = 774
+FBM-BIT-TYPE = 776
+FACE-ID-TYPE = 105
+```
+
+General status is always present. Its absent `BierIndex` indicates disabled
+BIER; a present zero indicates enabled index zero. Within a BIFT entry,
+`BierIndex` identifies the destination router's BFR-ID. Repeated `FaceId`
+fields list next hops. `FbmBit` fields list the set positions of the
+forwarding bit mask. Router entries are sorted by BFR-ID, neighbors by
+face ID, and mask positions in ascending order.
+
 ## `ndnd fw pet-list`
 
 The pet-list command prints the existing PET entries.

dv/SPEC.md

@@ -27,6 +27,10 @@ Prefix Group SVS                  = /<network>/32=DV/32=PSD/32=svs
 Prefix Data                       = /<network>/32=DV/32=PSD/<router>/t=<boot>/seq=<seq>/v=0
 Prefix Snapshot                   = /<network>/32=DV/32=PSD/<router>/t=<boot>/32=SNAP/v=<seq>
 
+Routing Status Discovery Interest = /<router>/32=DV/32=STATUS/32=metadata
+Routing Status Metadata Data      = /<router>/32=DV/32=STATUS/32=metadata/v=<version>/seg=0
+Routing Status Data               = /<router>/32=DV/32=STATUS/v=<version>/seg=<segment>
+
 <router>  = router's unique name in the network
 <network> = globally unique network prefix
 ```
@@ -70,7 +74,11 @@ ExitRouter = DESTINATION-TYPE TLV-LENGTH Name
 PrefixOpReset = PREFIX-OP-RESET-TYPE TLV-LENGTH
 PrefixOpAdd = PREFIX-OP-ADD-TYPE TLV-LENGTH
               Name
-              Cost
+              [Multicast]
+              [ValidityPeriod]
+
+Multicast = COST-TYPE 0
+; ValidityPeriod uses the NDN certificate validity-period format.
 PrefixOpRemove = PREFIX-OP-REMOVE-TYPE TLV-LENGTH
                  Name
 
@@ -80,6 +88,61 @@ PREFIX-OP-ADD-TYPE = 304
 PREFIX-OP-REMOVE-TYPE = 306
 ```
 
+### Routing status dataset
+
+A router serves its routing status as a versioned, segmented object.
+An RDR metadata discovery Interest uses `CanBePrefix` and `MustBeFresh`;
+the metadata identifies the versioned object name and final segment.
+After reassembling the segments, the Data Content has the following format.
+`RoutingStatus` has no outer TLV wrapper.
+
+```abnf
+RoutingStatus = Status
+                *RouterStatus
+
+Status = STATUS-TYPE TLV-LENGTH
+         Version
+         NetworkName
+         RouterName
+         NRibEntries
+         NNeighbors
+         NFibEntries
+         NPsdEntries
+
+Version = VERSION-TYPE TLV-LENGTH *OCTET
+NetworkName = NETWORK-NAME-TYPE TLV-LENGTH Name
+RouterName = ROUTER-NAME-TYPE TLV-LENGTH Name
+NRibEntries = N-RIB-ENTRIES-TYPE TLV-LENGTH NonNegativeInteger
+NNeighbors = N-NEIGHBORS-TYPE TLV-LENGTH NonNegativeInteger
+NFibEntries = N-FIB-ENTRIES-TYPE TLV-LENGTH NonNegativeInteger
+NPsdEntries = N-PSD-ENTRIES-TYPE TLV-LENGTH NonNegativeInteger
+
+RouterStatus = ROUTER-STATUS-TYPE TLV-LENGTH
+               Name
+               NextHop
+               Cost
+               *PrefixOpAdd
+
+VERSION-TYPE = 401
+NETWORK-NAME-TYPE = 403
+ROUTER-NAME-TYPE = 405
+N-RIB-ENTRIES-TYPE = 407
+N-NEIGHBORS-TYPE = 409
+N-FIB-ENTRIES-TYPE = 411
+N-PSD-ENTRIES-TYPE = 413
+STATUS-TYPE = 416
+ROUTER-STATUS-TYPE = 418
+```
+
+`Status` identifies the responding router and its network, reports the NDNd
+version as a UTF-8 string, and includes its RIB, neighbor, FIB, and prefix-state
+entry counts.
+Each `RouterStatus` describes a reachable router, its selected next hop and
+routing cost, and its learned prefix announcements. `NextHop`, `Cost`, and
+`PrefixOpAdd` use the definitions above. Unreachable routers are omitted.
+Router entries and each router's prefix entries are sorted by canonical NDN
+name order.
+
 ## 4. Protocol Operation
 
 ### RIB State

dv/config/config.go

@@ -255,6 +255,11 @@ func (c *Config) NetworkName() enc.Name {
 	return c.networkNameN
 }
 
+// StatusDatasetPrefix names a router's remotely retrievable DV status dataset.
+func StatusDatasetPrefix(router enc.Name) enc.Name {
+	return router.Clone().Append(enc.NewKeywordComponent("DV"), enc.NewKeywordComponent("STATUS"))
+}
+
 // (AI GENERATED DESCRIPTION): Returns the router name (enc.Name) stored in the Config instance.
 func (c *Config) RouterName() enc.Name {
 	return c.routerNameN

dv/config/schema.trust

@@ -8,6 +8,9 @@
 // Advertisement data and broadcast
 #advertisement_data: /"localhop"/#router/"32=DV"/"32=ADV"/_ <= #router_cert
 
+// Read-only routing status dataset
+#status_data: #router/"32=DV"/"32=STATUS" <= #router_cert
+
 // Prefix state database
 #prefix_state: #network/"32=DV"/"32=PSD"
 // Prefix state database data

dv/dv/router.go

@@ -38,6 +38,13 @@ type Router struct {
 	// single mutex for all operations
 	mutex sync.Mutex
 
+	// Cache a bounded set of versioned status snapshots for segment fetches.
+	statusMu      sync.Mutex
+	statusUpdated time.Time
+	statusObjects *storage.MemoryFifoDir
+	// Dataset prefix mappings to remote egress routers, protected by mutex.
+	statusRoutes map[uint64]enc.Name
+
 	// channel to stop the DV
 	stop chan bool
 	// heartbeat for outgoing Advertisements
@@ -123,12 +130,14 @@ func NewRouter(config *config.Config, engine ndn.Engine) (*Router, error) {
 
 	// Create the DV router
 	dv := &Router{
-		engine: engine,
-		config: config,
-		trust:  trust,
-		client: object.NewClient(engine, store, trust),
-		nfdc:   nfdc.NewNfdMgmtThread(engine),
-		mutex:  sync.Mutex{},
+		engine:        engine,
+		config:        config,
+		trust:         trust,
+		client:        object.NewClient(engine, store, trust),
+		nfdc:          nfdc.NewNfdMgmtThread(engine),
+		mutex:         sync.Mutex{},
+		statusObjects: storage.NewMemoryFifoDir(32),
+		statusRoutes:  make(map[uint64]enc.Name),
 	}
 
 	// Initialize advertisement module
@@ -266,6 +275,10 @@ func (dv *Router) register() (err error) {
 		return err
 	}
 
+	if err = dv.engine.AttachHandler(config.StatusDatasetPrefix(dv.config.RouterName()), dv.onStatusDataset); err != nil {
+		return err
+	}
+
 	insertPrefix := dv.pfx.InsertionPrefix()
 	err = dv.engine.AttachHandler(insertPrefix,
 		func(args ndn.InterestHandlerArgs) {
@@ -283,6 +296,7 @@ func (dv *Router) register() (err error) {
 		dv.pfx.DataPrefix(),
 		dv.config.MgmtPrefix(),
 		insertPrefix,
+		config.StatusDatasetPrefix(dv.config.RouterName()),
 	}
 
 	for _, prefix := range pfxs {