From 90ef1cf8a5e0c5f96e9d3c1822f51c1b844f3307 Mon Sep 17 00:00:00 2001 From: Virgil Date: Fri, 3 Apr 2026 20:48:18 +0000 Subject: [PATCH] refactor(ax): add example-driven API comments Co-Authored-By: Virgil --- action.go | 6 +++--- hsd.go | 7 +++++++ http_server.go | 2 +- mainchain.go | 7 +++++++ serve.go | 3 +-- service.go | 13 ++++++++++--- 6 files changed, 29 insertions(+), 9 deletions(-) diff --git a/action.go b/action.go index 370c14a..2fa558b 100644 --- a/action.go +++ b/action.go @@ -35,7 +35,7 @@ type ActionRegistrar interface { // ActionDefinitions returns the complete DNS action surface in registration order. // -// service.ActionDefinitions() +// definitions := service.ActionDefinitions() func (service *Service) ActionDefinitions() []ActionDefinition { return []ActionDefinition{ { @@ -129,7 +129,7 @@ func (service *Service) ActionDefinitions() []ActionDefinition { // ActionNames returns the names of the registered DNS actions. // -// service.ActionNames() +// names := service.ActionNames() func (service *Service) ActionNames() []string { definitions := service.ActionDefinitions() names := make([]string, 0, len(definitions)) @@ -153,7 +153,7 @@ func (service *Service) RegisterActions(registrar ActionRegistrar) { // HandleAction executes a DNS action by name. // -// service.HandleAction("dns.resolve", map[string]any{"name": "gateway.charon.lthn"}) +// payload, ok, err := service.HandleAction("dns.resolve", map[string]any{"name": "gateway.charon.lthn"}) func (service *Service) HandleAction(name string, values map[string]any) (any, bool, error) { for _, definition := range service.ActionDefinitions() { if definition.Name == name { diff --git a/hsd.go b/hsd.go index b741ef8..0cfe883 100644 --- a/hsd.go +++ b/hsd.go @@ -60,6 +60,13 @@ func (err *HSDRPCError) Error() string { return fmt.Sprintf("hsd rpc error (%d): %s", err.Code, err.Message) } +// NewHSDClient builds a client for HSD JSON-RPC. +// +// client := dns.NewHSDClient(dns.HSDClientOptions{ +// URL: "http://127.0.0.1:14037", +// Username: "user", +// Password: "pass", +// }) func NewHSDClient(options HSDClientOptions) *HSDClient { client := options.HTTPClient if client == nil { diff --git a/http_server.go b/http_server.go index 47098fb..ce84c1c 100644 --- a/http_server.go +++ b/http_server.go @@ -45,7 +45,7 @@ func (server *HTTPServer) Close() error { // ServeHTTPHealth starts a minimal HTTP server exposing GET /health. // -// service.ServeHTTPHealth("127.0.0.1", 5554) +// server, err := service.ServeHTTPHealth("127.0.0.1", 5554) func (service *Service) ServeHTTPHealth(bind string, port int) (*HTTPServer, error) { if bind == "" { bind = "127.0.0.1" diff --git a/mainchain.go b/mainchain.go index 11bf46d..f6499c2 100644 --- a/mainchain.go +++ b/mainchain.go @@ -37,6 +37,13 @@ type MainchainRPCResponse struct { Error *HSDRPCError `json:"error"` } +// NewMainchainAliasClient builds a client for alias discovery on the main chain. +// +// client := dns.NewMainchainAliasClient(dns.MainchainClientOptions{ +// URL: "http://127.0.0.1:14037", +// Username: "user", +// Password: "pass", +// }) func NewMainchainAliasClient(options MainchainClientOptions) *MainchainAliasClient { client := options.HTTPClient if client == nil { diff --git a/serve.go b/serve.go index 6002568..820e19c 100644 --- a/serve.go +++ b/serve.go @@ -44,9 +44,8 @@ func (server *DNSServer) Close() error { } // Serve starts DNS over UDP and TCP at bind:port and returns a running server handle. -// Example: // -// srv, err := service.Serve("127.0.0.1", 0) +// srv, err := service.Serve("127.0.0.1", 53) func (service *Service) Serve(bind string, port int) (*DNSServer, error) { if bind == "" { bind = "127.0.0.1" diff --git a/service.go b/service.go index ab10631..9ec2352 100644 --- a/service.go +++ b/service.go @@ -68,6 +68,13 @@ type ServiceOptions struct { TreeRootCheckInterval time.Duration } +// NewService builds a DNS service from cached records and optional discovery hooks. +// +// service := dns.NewService(dns.ServiceOptions{ +// Records: map[string]dns.NameRecords{ +// "gateway.charon.lthn": {A: []string{"10.10.10.10"}}, +// }, +// }) func NewService(options ServiceOptions) *Service { checkInterval := options.TreeRootCheckInterval if checkInterval <= 0 { @@ -334,8 +341,9 @@ func (service *Service) Discover() error { return nil } -// DiscoverAliases refreshes DNS records by scanning chain aliases through HSD RPC calls. -// This matches the RFC `dns.discover` behavior by reusing the configured chain alias discoverers and fallback clients. +// DiscoverAliases refreshes DNS records from chain aliases. +// +// err := service.DiscoverAliases(context.Background()) func (service *Service) DiscoverAliases(ctx context.Context) error { return service.DiscoverFromChainAliases(ctx, service.hsdClient) } @@ -406,7 +414,6 @@ func (service *Service) ResolveTXTRecords(name string) (ResolveTXTResult, bool) } // DiscoverWithHSD refreshes DNS records for each alias by calling HSD. -// Example: // // err := service.DiscoverWithHSD(context.Background(), []string{"gateway.lthn"}, dns.NewHSDClient(dns.HSDClientOptions{ // URL: "http://127.0.0.1:14037",