Repository navigation
Description
Problem
docs/discovery.schema.json defines the GET /discovery response, but very little code has to match it.
Only two served responses are validated. discovery/schema_test.go checks handwritten documents and the example in docs/http-api.md. Beyond that, only the orchestrator inventory (TestDiscoveryLocalInventory) and one standalone discovery body (TestDiscoveryPreservesWholeRecords) are checked against the schema. Nothing else that serves or accepts this document is tested.
Decode accepts documents the schema rejects. discovery/shared.Decode disagrees with the schema on what an entry looks like:
| Document | Schema (TestDiscoverySchema) |
Decode (TestDecodeValidation) |
|---|---|---|
[{"address":"https://orch.example"}], with no runners array |
Invalid | Accepted, as the omitted case |
[{"nodes":[],"address":"https://orch.example"}] |
Invalid, as the metadata with address case |
Accepted as an orchestrator entry. Decode treats an entry as metadata only when address is empty. |
Other modules have to copy the encoder. discoveryResponse and discoveryNode in discovery/server.go are unexported. Any other module that serves GET /discovery has to copy them. It can forward runner records as the upstream bytes, but the envelope around them becomes a second implementation, and this repo's schema tests never run against it.
Consumers can't pin the schema from a release. The schema landed on main in #49 and is not in github.com/livepeer/node v1.0.6. A consumer that wants to validate against it has to pin a commit that includes the file.
Expected differences
- Future timestamps.
ClockSkewindiscovery/shared/inventory.gorejects a stamp more than 30 seconds ahead. That is a runtime check, and the schema description already says timestamp freshness is not a schema constraint. Keep this exception, and keep it explicit. - New fields. The schema sets
additionalProperties: true, so new optional fields still validate. This issue is about bodies the schema rejects, and about a second encoder that never runs these tests. It is not about new fields.
Done when
-
Decodeaccepts the documents thediscovery/schema_test.gocorpus marks valid and rejects the ones it marks invalid. The only named exception is a stamp more thanClockSkewin the future. - A test in this repo fails when a
GET /discoverybody written here does not validate. The two handler tests already cover their fixtures. The gap is the set of documentsDecodeaccepts. - Another module can write the envelope without copying
discoveryResponse. Export the builder, or the server path that writes the body, and name it indocs/http-api.mdnext to the schema.
Out of scope
- Do not load the JSON Schema validator in the running process. Publish JSON Schema for discovery responses #49 kept it in tests on purpose.
- Do not build runner records from the schema.
discoveryRunner.MarshalJSONmust keep returning the upstream bytes, so unknown fields and the original numeric tokens survive. - Do not move the schema out of this repo. Callers parse this response, so its wire format is defined here.
Activity
Validate raw discovery runner records before forwarding (#82)
j0sh commentedon Nov 12, 2026
PR #82 has merged, addressing the demonstrated raw-forwarding and client interoperability gaps. CI already ran the schema fixtures and handler tests; the change strengthens their coverage rather than adding another workflow.
The agreed direction is leniency by default, tightening validation where malformed or ambiguous data is likely to cause unexpected client behavior. We are prioritizing broad correctness rules rather than an exhaustive runtime implementation of the schema.
Deliberate input tolerance is preserved: malformed runners are skipped individually, valid siblings survive, empty inventories succeed, and existing envelope/metadata tolerance and timestamp-skew checks remain. The existing failure when a source advertises runners but none are usable also remains. Consequently, the original acceptance criterion requiring Decode to reject every schema-invalid document is too strict and should not be the goal.
The merged changes:
The checks run when upstream inventories are refreshed; cached HTTP reads do not repeat validation.
The builder API request still needs more detail. Server.ServeHTTP is already public and lets another application serve the inventory collected by a configured discovery Server without copying the encoder. Exporting DiscoveryResponse would mainly expose that same server-owned inventory; it would not let a caller supply arbitrary records from its own database or collector.
Before adding another public API, we need a concrete consumer example: where its inventory comes from, why the existing handler is insufficient, and the inputs and output it needs. If the consumer owns its inventory, a separate envelope-building function may be useful. If it is embedding the existing collector/server, the current handler may already cover the use case. That clarification remains open rather than adding a speculative builder API.