Skip to content

docs: draft /api/routing/trace endpoint - #2

Open
luochen1990 wants to merge 1 commit into
daeuniverse:honkfrom
luochen1990:docs-routing-trace
Open

docs: draft /api/routing/trace endpoint#2
luochen1990 wants to merge 1 commit into
daeuniverse:honkfrom
luochen1990:docs-routing-trace

Conversation

@luochen1990

Copy link
Copy Markdown

What

Adds a draft spec page for GET /api/routing/trace: dry-run the active
routing rules against a hypothetical flow (domain / IP / port / network /
process name / source IP) and return the per-rule decision path plus the
outbound that would have been selected.

Why

"Why did this connection go through this group?" is the most common routing
question, and the current endpoints cannot answer it:

  • A configuration dump only gives the rule list — users must mentally
    execute the routing DSL (rule order, && short-circuits, fallback).
  • GET /api/connections shows
    outcomes for existing connections, not reasons, and nothing at all about
    a flow that has not happened yet.

The result taxonomy in this draft comes from production experience with an
offline routing matcher I maintain for dae (a visualization panel that
reuses dae's rule compilation to render decision trees). Three semantics
proved essential there and are encoded here:

  • skipped is not a verdict. After the deciding rule (or a
    short-circuited subcondition), later rules are not evaluated; they carry
    no verdict and must not be displayed as results.
  • indeterminate is not a guess. A rule whose verdict depends on an
    input the caller did not provide (e.g. dip(geoip:...) without an IP,
    pname() without a process name) is reported as indeterminate, and the
    evaluation-level flag marks results whose decision path contains such
    steps — a client can tell "this answer is solid" from "provide more
    inputs to sharpen it".
  • One evaluation per resolved address. A domain-only query is resolved
    through the engine's own DNS chain and evaluated once per address:
    production routing decides per connection, and different addresses of
    one name legitimately select different outbounds.

Notes

  • The evaluation is pure computation: no datapath changes, no dialing of
    the traced flow through outbounds; the only network activity is the
    engine's own DNS resolution for name-only queries.
  • Docs-only change; no code.
  • Designed to compose with feat(api): add some based honk/dae pat #1, and happy to rebase onto its vocabulary
    once it lands:

@Glassyiris

Copy link
Copy Markdown

Once 1.0 ships, the target is full per-flow transparency: trace every routing decision from rule input → dial mode → IP/DNS → reroute? → outbound → connection status. That's the honk/dae API plan.

thanks pr!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants