Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
106 changes: 106 additions & 0 deletions discovery/schema_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,106 @@
package discovery

import (
"bytes"
"encoding/json"
"io"
"os"
"strings"
"testing"

"github.com/santhosh-tekuri/jsonschema/v6"
"github.com/stretchr/testify/require"
)

func discoverySchema(t *testing.T) *jsonschema.Schema {
t.Helper()
compiler := jsonschema.NewCompiler()
compiler.AssertFormat()
schema, err := compiler.Compile("../docs/discovery.schema.json")
require.NoError(t, err)
return schema
}

func validateDiscoveryJSON(t *testing.T, schema *jsonschema.Schema, data []byte) error {
t.Helper()
var value any
decoder := json.NewDecoder(bytes.NewReader(data))
decoder.UseNumber()
require.NoError(t, decoder.Decode(&value))
require.ErrorIs(t, decoder.Decode(&value), io.EOF)
return schema.Validate(value)
}

func TestDiscoverySchema(t *testing.T) {
schema := discoverySchema(t)
const runner = `{"url":"https://orch.example/app","app":"example","observed_at":"2026-10-22T18:05:00.123+01:00"}`
const metadata = `[{"nodes":[{"url":"https://orch.example","queried_at":"2026-10-22T18:05:00Z"}]}]`
envelope := func(record string) string {
return `[{"address":"https://orch.example/deployment","runners":[` + record + `]}]`
}
for _, test := range []struct {
name, body string
valid bool
}{
{"empty", `[]`, true},
{"empty runners", envelope(""), true},
{"metadata", metadata, true},
{"metadata with empty runners", `[{"nodes":[],"runners":[]}]`, true},
{"minimal runner", envelope(runner), true},
{"IPv6 with port", strings.ReplaceAll(envelope(runner), "orch.example", "[::1]:8935"), true},
{"mixed-case schemes", strings.ReplaceAll(envelope(runner), "https://", "hTtPs://"), true},
{"mixed-case node scheme", strings.ReplaceAll(metadata, "https://", "HtTp://"), true},
{"runner URL components", envelope(strings.ReplaceAll(runner, "https://orch.example/app", "https://user:pass@orch.example/app?x=1#part")), true},
{"unknown properties", envelope(strings.TrimSuffix(runner, "}") + `,"extension":{"count":9007199254740993}}`), true},
{"extensible price", envelope(strings.TrimSuffix(runner, "}") + `,"mode":"future","price_info":{"price":123456789012345678901234567890,"price_usd":0.123456789012345678901234567890123456,"currency":"credits","unit":"tokens","extension":true}}`), true},
{"USD price omitted", envelope(strings.TrimSuffix(runner, "}") + `,"price_info":{"price":1,"currency":"wei","unit":"fixed"}}`), true},
{"price string", envelope(strings.TrimSuffix(runner, "}") + `,"price_info":{"price":"1"}}`), false},
{"USD price string", envelope(strings.TrimSuffix(runner, "}") + `,"price_info":{"price":1,"price_usd":"0.1"}}`), false},
{"missing URL", envelope(strings.ReplaceAll(runner, `"url":"https://orch.example/app",`, "")), false},
{"missing app", envelope(strings.ReplaceAll(runner, `"app":"example",`, "")), false},
{"missing observation", envelope(`{"url":"https://orch.example/app","app":"example"}`), false},
{"empty app", envelope(strings.ReplaceAll(runner, `"app":"example"`, `"app":""`)), false},
{"invalid observation", envelope(strings.ReplaceAll(runner, "2026-10-22T18:05:00.123+01:00", "yesterday")), false},
{"invalid query time", `[{"nodes":[{"url":"https://orch.example","queried_at":"yesterday"}]}]`, false},
{"missing query time", `[{"nodes":[{"url":"https://orch.example"}]}]`, false},
{"missing node URL", `[{"nodes":[{"queried_at":"2026-10-22T18:05:00Z"}]}]`, false},
{"metadata with address", `[{"nodes":[],"address":"https://orch.example"}]`, false},
{"metadata with runners", `[{"nodes":[],"runners":[` + runner + `]}]`, false},
{"metadata with non-array runners", `[{"nodes":[],"runners":{}}]`, false},
{"missing runners", `[{"address":"https://orch.example"}]`, false},
{"non-HTTP address", strings.ReplaceAll(envelope(runner), "https://orch.example/deployment", "ftp://orch.example"), false},
{"non-HTTP runner URL", envelope(strings.ReplaceAll(runner, "https://orch.example/app", "ftp://orch.example/app")), false},
{"address credentials", strings.ReplaceAll(envelope(runner), "https://orch.example/deployment", "https://user:pass@orch.example/deployment"), false},
{"address query", strings.ReplaceAll(envelope(runner), "https://orch.example/deployment", "https://orch.example/deployment?x=1"), false},
{"address empty query", strings.ReplaceAll(envelope(runner), "https://orch.example/deployment", "https://orch.example/deployment?"), false},
{"address fragment", strings.ReplaceAll(envelope(runner), "https://orch.example/deployment", "https://orch.example/deployment#part"), false},
{"node credentials", strings.ReplaceAll(metadata, "https://orch.example", "https://user:pass@orch.example"), false},
{"node query", strings.ReplaceAll(metadata, "https://orch.example", "https://orch.example?x=1"), false},
{"node fragment", strings.ReplaceAll(metadata, "https://orch.example", "https://orch.example#part"), false},
{"hostless address", strings.ReplaceAll(envelope(runner), "https://orch.example/deployment", "https://:8935/deployment"), false},
{"hostless node", strings.ReplaceAll(metadata, "https://orch.example", "https://:8935"), false},
{"userinfo-only runner", envelope(strings.ReplaceAll(runner, "https://orch.example/app", "https://user:pass@/app")), false},
} {
t.Run(test.name, func(t *testing.T) {
err := validateDiscoveryJSON(t, schema, []byte(test.body))
if test.valid {
require.NoError(t, err)
} else {
require.Error(t, err)
}
})
}
}

func TestDiscoverySchemaHTTPExample(t *testing.T) {
doc, err := os.ReadFile("../docs/http-api.md")
require.NoError(t, err)
_, section, ok := strings.Cut(string(doc), "## Discovery HTTP\n")
require.True(t, ok, "Discovery HTTP section must exist")
section, _, _ = strings.Cut(section, "\n## ")
_, block, ok := strings.Cut(section, "```json\n")
require.True(t, ok, "Discovery HTTP must contain a JSON example")
example, _, ok := strings.Cut(block, "\n```")
require.True(t, ok, "JSON example must have a closing fence")
require.NoError(t, validateDiscoveryJSON(t, discoverySchema(t), []byte(example)))
}
58 changes: 43 additions & 15 deletions discovery/server_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -210,40 +210,68 @@ func TestDiscoveryFailureThreshold(t *testing.T) {
}

func TestDiscoveryPreservesWholeRecords(t *testing.T) {
const record = `{"url":"https://orch.example/apps/runner/session","app":"test","observed_at":"2000-01-01T00:00:00.123+00:00","mode":"persistent","capacity":4,"capacity_used":1,"capacity_available":3,"gpu":{"id":"0","name":"H100","vram_mb":80000},"price_info":{"price":123456789012345678901234567890,"currency":"wei","unit":"seconds"},"extension":{"value":9007199254740993}}`
s := discoveryTestServer(t, "https://old.example", "https://child.example", "https://tie.example")
const record = `{"url":"https://orch.example/apps/runner/session","app":"test","observed_at":"2000-01-01T00:00:00.123+00:00","mode":"persistent","capacity":4,"capacity_used":1,"capacity_available":3,"gpu":{"id":"0","name":"H100","vram_mb":80000},"price_info":{"price":123456789012345678901234567890,"price_usd":0.123456789012345678901234567890123456,"currency":"wei","unit":"tokens"},"extension":{"value":9007199254740993,"ratio":1.2300e+04}}`
var calls atomic.Int32
s.collector.Client.Transport = discoveryRoundTrip(func(r *http.Request) (*http.Response, error) {
upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
calls.Add(1)
owner, runner := "https://orch.example", record
switch r.URL.Host {
case "old.example":
switch r.URL.Path {
case "/old/discovery":
owner = "https://old-owner.example"
runner = strings.ReplaceAll(runner, "2000-01-01", "1999-01-01")
case "tie.example":
case "/tie/discovery":
runner = strings.ReplaceAll(runner, `"app":"test"`, `"app":"tie"`)
}
body := `[{"address":"` + owner + `","runners":[` + runner + `]}]`
return &http.Response{StatusCode: 200, Body: io.NopCloser(strings.NewReader(body))}, nil
})
w.Header().Set("Content-Type", "application/json")
_, _ = io.WriteString(w, `[{"address":"`+owner+`","runners":[`+runner+`]}]`)
}))
defer upstream.Close()
s := discoveryTestServer(t, upstream.URL+"/old", upstream.URL+"/child", upstream.URL+"/tie")
var dumped bytes.Buffer
require.NoError(t, s.dump(t.Context(), &dumped))
require.Equal(t, int32(3), calls.Load())
server := httptest.NewServer(s)
defer server.Close()
schema := discoverySchema(t)
for range 2 {
w := httptest.NewRecorder()
s.ServeHTTP(w, httptest.NewRequest(http.MethodGet, "/discovery", nil))
require.Equal(t, 200, w.Code)
require.Equal(t, dumped.String(), w.Body.String(), "dump and HTTP share the same snapshot and encoding")
response, err := server.Client().Get(server.URL + "/discovery")
require.NoError(t, err)
data, err := io.ReadAll(response.Body)
require.NoError(t, response.Body.Close())
require.NoError(t, err)
require.Equal(t, http.StatusOK, response.StatusCode)
require.Equal(t, "application/json", response.Header.Get("Content-Type"))
require.NoError(t, validateDiscoveryJSON(t, schema, data))
require.Equal(t, dumped.String(), string(data), "dump and HTTP share the same snapshot and encoding")
var result []map[string]json.RawMessage
require.NoError(t, json.Unmarshal(w.Body.Bytes(), &result))
require.NoError(t, json.Unmarshal(data, &result))
require.Len(t, result, 2)
require.NotContains(t, result[0], "address")
var nodes []discoveryNode
require.NoError(t, json.Unmarshal(result[0]["nodes"], &nodes))
require.Len(t, nodes, 3)
require.Equal(t, upstream.URL+"/old", nodes[0].URL)
require.Equal(t, `"https://orch.example"`, string(result[1]["address"]))
// Compare raw JSON so large integers cannot be rounded through float64.
// Compare raw JSON to retain unknown fields and exact numeric tokens.
require.Equal(t, "["+record+"]", string(result[1]["runners"]))
}
}

func TestDiscoveryEmptyInventory(t *testing.T) {
s := discoveryTestServer(t)
server := httptest.NewServer(s)
defer server.Close()
response, err := server.Client().Get(server.URL + "/discovery")
require.NoError(t, err)
defer response.Body.Close()
require.Equal(t, http.StatusOK, response.StatusCode)
require.Equal(t, "application/json", response.Header.Get("Content-Type"))
data, err := io.ReadAll(response.Body)
require.NoError(t, err)
require.JSONEq(t, `[]`, string(data))
require.NoError(t, validateDiscoveryJSON(t, discoverySchema(t), data))
}

func TestDiscoveryPrivateSourcesRequireGrants(t *testing.T) {
var calls atomic.Int32
upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
Expand Down
148 changes: 148 additions & 0 deletions docs/discovery.schema.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,148 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "GET /discovery response",
"description": "A forwarding contract for orchestrator and standalone discovery inventories. Empty arrays are successful inventories. Aggregators must preserve complete runner records, including unknown properties and the lexical form of numeric tokens. Timestamp freshness and tolerant record skipping are runtime checks, not schema constraints.",
"type": "array",
"items": {
"oneOf": [
{ "$ref": "#/$defs/metadataEntry" },
{ "$ref": "#/$defs/orchestratorEntry" }
]
},
"$defs": {
"httpURL": {
"type": "string",
"format": "uri",
"pattern": "^[Hh][Tt][Tt][Pp][Ss]?://([^/?#@]*@)?[^/?#@:][^/?#@]*([/?#]|$)"
},
"baseURL": {
"$ref": "#/$defs/httpURL",
"pattern": "^[Hh][Tt][Tt][Pp][Ss]?://[^/?#@]+(/[^?#]*)?$",
"description": "An HTTP(S) base URL without credentials, query, or fragment; deployment paths are allowed."
},
"metadataEntry": {
"type": "object",
"description": "Standalone discovery prepends this entry only when it advertises successfully queried, non-evicted sources.",
"required": ["nodes"],
"not": { "required": ["address"] },
"properties": {
"runners": { "type": "array", "maxItems": 0 },
"nodes": {
"type": "array",
"items": { "$ref": "#/$defs/node" }
}
},
"additionalProperties": true
},
"node": {
"type": "object",
"required": ["url", "queried_at"],
"properties": {
"url": {
"$ref": "#/$defs/baseURL",
"description": "The queried source's HTTP(S) base URL."
},
"queried_at": {
"type": "string",
"format": "date-time",
"description": "RFC 3339 time of the source's last successful query."
}
},
"additionalProperties": true
},
"orchestratorEntry": {
"type": "object",
"required": ["address", "runners"],
"properties": {
"address": {
"$ref": "#/$defs/baseURL",
"description": "The owning orchestrator's HTTP(S) base URL, including any deployment path; not an Ethereum address."
},
"runners": {
"type": "array",
"items": { "$ref": "#/$defs/runner" }
}
},
"additionalProperties": true
},
"runner": {
"type": "object",
"description": "A ready app. Aggregators must forward unknown properties.",
"required": ["url", "app", "observed_at"],
"properties": {
"url": {
"$ref": "#/$defs/httpURL",
"description": "The app endpoint advertised by the owning orchestrator."
},
"app": {
"type": "string",
"minLength": 1,
"description": "Application name."
},
"observed_at": {
"type": "string",
"format": "date-time",
"description": "RFC 3339 observation time, allowing fractional seconds. Orchestrators stamp local runners at response time; aggregators preserve the timestamp."
},
"version": {
"type": "string",
"description": "Application version."
},
"metadata": {
"type": "string",
"description": "Application-supplied metadata."
},
"gpu": { "$ref": "#/$defs/gpu" },
"mode": {
"type": "string",
"description": "This orchestrator emits persistent or single-shot; discovery forwards other upstream values unchanged."
},
"capacity": {
"type": "integer",
"description": "Configured concurrent session capacity."
},
"capacity_used": {
"type": "integer",
"description": "Currently reserved sessions."
},
"capacity_available": {
"type": "integer",
"description": "Capacity currently available for new sessions."
},
"price_info": { "$ref": "#/$defs/priceInfo" }
},
"additionalProperties": true
},
"gpu": {
"type": "object",
"properties": {
"id": { "type": "string", "description": "GPU identifier." },
"name": { "type": "string", "description": "GPU name." },
"vram_mb": { "type": "integer", "description": "GPU memory in MB." }
},
"additionalProperties": true
},
"priceInfo": {
"type": "object",
"properties": {
"price": {
"type": "number",
"description": "Price per advertised unit in the advertised currency. Consumers must preserve the exact JSON numeric token without rounding through binary floating point."
},
"price_usd": {
"type": "number",
"description": "Optional registered USD price per advertised unit. Consumers must preserve the exact JSON numeric token without rounding through binary floating point. On-chain orchestrators divide hourly quotes by 3600 for the seconds unit and leave fixed quotes unchanged, with up to 36 fractional digits and trailing zeros trimmed."
},
"currency": {
"type": "string",
"description": "This orchestrator emits wei; discovery forwards other upstream currencies unchanged."
},
"unit": {
"type": "string",
"description": "This orchestrator emits seconds or fixed; discovery forwards other upstream units unchanged."
}
},
"additionalProperties": true
}
}
}
2 changes: 2 additions & 0 deletions docs/http-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,8 @@ behavior, and proxy routes.

## Discovery HTTP

The response body follows the [discovery JSON Schema](discovery.schema.json).

`GET /discovery` returns available local runners at an orchestrator, or cached
runners grouped by owning orchestrator at standalone discovery. In this
live-runner format, `address` is the orchestrator's HTTP(S) base URL, such as
Expand Down
1 change: 1 addition & 0 deletions go.mod
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@ require (
github.com/j0sh/minikafka v0.0.0-20261001174935-0bc8dcedd322
github.com/prometheus/client_golang v1.25.0
github.com/prometheus/client_model v0.6.3
github.com/santhosh-tekuri/jsonschema/v6 v6.0.3
github.com/segmentio/kafka-go v0.4.51
github.com/spf13/cobra v1.10.2
github.com/stretchr/testify v1.12.1
Expand Down
4 changes: 4 additions & 0 deletions go.sum
Original file line number Diff line number Diff line change
Expand Up @@ -58,6 +58,8 @@ github.com/decred/dcrd/dcrec/secp256k1/v4 v4.0.1 h1:YLtO71vCjJRCBcrPMtQ9nqBsqpA1
github.com/decred/dcrd/dcrec/secp256k1/v4 v4.0.1/go.mod h1:hyedUtir6IdtD/7lIxGeCxkaw7y45JueMRL4DIyJDKs=
github.com/deepmap/oapi-codegen v1.6.0 h1:w/d1ntwh91XI0b/8ja7+u5SvA4IFfM0UNNLmiDR1gg0=
github.com/deepmap/oapi-codegen v1.6.0/go.mod h1:ryDa9AgbELGeB+YEXE1dR53yAjHwFvE9iAUlWl9Al3M=
github.com/dlclark/regexp2 v1.11.0 h1:G/nrcoOa7ZXlpoa/91N3X7mM3r8eIlMBBJZvsz/mxKI=
github.com/dlclark/regexp2 v1.11.0/go.mod h1:DHkYz0B9wPfa6wondMfaivmHpzrQ3v9q8cnmRbL6yW8=
github.com/dustin/go-humanize v1.1.0 h1:dbKTrvD0klcbBV/h4AWJdMuZogJACoMlvWIWZ5b2xWg=
github.com/dustin/go-humanize v1.1.0/go.mod h1:hc1CvRkJMsgxqjmjMQF3QNRAZBwY8AXBAzKYoSX9sFI=
github.com/emicklei/dot v1.6.2 h1:08GN+DD79cy/tzN6uLCT84+2Wk9u+wvqP+Hkx/dIR8A=
Expand Down Expand Up @@ -204,6 +206,8 @@ github.com/rs/cors v1.7.0 h1:+88SsELBHx5r+hZ8TCkggzSstaWNbDvThkVK8H6f9ik=
github.com/rs/cors v1.7.0/go.mod h1:gFx+x8UowdsKA9AchylcLynDq+nNFfI8FkUZdN/jGCU=
github.com/russross/blackfriday/v2 v2.1.0 h1:JIOH55/0cWyOuilr9/qlrm0BSXldqnqwMsf35Ld67mk=
github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
github.com/santhosh-tekuri/jsonschema/v6 v6.0.3 h1:1EYB5IzjZawrrnELUi78f9fPu57HuXjmddZPjrls/28=
github.com/santhosh-tekuri/jsonschema/v6 v6.0.3/go.mod h1:JXeL+ps8p7/KNMjDQk3TCwPpBy0wYklyWTfbkIzdIFU=
github.com/segmentio/kafka-go v0.4.51 h1:JgDPPG75tC1rWIS2Me6MwcvXJ6f49UQ4HjAOef71Hno=
github.com/segmentio/kafka-go v0.4.51/go.mod h1:Y1gn60kzLEEaW28YshXyk2+VCUKbJ3Qr6DrnT3i4+9E=
github.com/shirou/gopsutil v3.21.4-0.20210419000835-c7a38de76ee5+incompatible h1:Bn1aCHHRnjv4Bl16T8rcaFjYSrGrIZvpiGO6P3Q4GpU=
Expand Down
Loading
Loading