docs: add doc comments to internal registry and server components

Author: gitcommitankit

cmd/main.go

@@ -69,6 +69,7 @@ type registryServerRunnable struct {
 	mcpRegistry  *registry.Registry
 }
 
+// Start starts the MCP discovery HTTP server and listens until context cancellation.
 func (r *registryServerRunnable) Start(ctx context.Context) error {
 	r.mcpRegistry.Start(ctx)
 	srv := &http.Server{
@@ -92,6 +93,7 @@ func (r *registryServerRunnable) Start(ctx context.Context) error {
 	return nil
 }
 
+// NeedLeaderElection returns false so the registry server runs across all manager replicas.
 func (r *registryServerRunnable) NeedLeaderElection() bool {
 	return false
 }

internal/registry/mcp_client.go

@@ -64,12 +64,14 @@ type mcpInitializeRequest struct {
 	Params  mcpInitializeParams `json:"params"`
 }
 
+// mcpInitializeParams encapsulates the parameters passed to the MCP initialize RPC.
 type mcpInitializeParams struct {
 	ProtocolVersion string                 `json:"protocolVersion"`
 	ClientInfo      mcpClientInfo          `json:"clientInfo"`
 	Capabilities    map[string]interface{} `json:"capabilities"`
 }
 
+// mcpClientInfo identifies the client implementation and version to the MCP server.
 type mcpClientInfo struct {
 	Name    string `json:"name"`
 	Version string `json:"version"`
@@ -83,27 +85,32 @@ type mcpInitializeResponse struct {
 	Error   *mcpError            `json:"error,omitempty"`
 }
 
+// mcpError represents a JSON-RPC 2.0 error object.
 type mcpError struct {
 	Code    int    `json:"code"`
 	Message string `json:"message"`
 }
 
+// mcpInitializeResult encapsulates the capability and tool declarations returned by an MCP server.
 type mcpInitializeResult struct {
 	ProtocolVersion string              `json:"protocolVersion"`
 	Capabilities    mcpCapabilities     `json:"capabilities"`
 	ServerInfo      *mcpClientInfo      `json:"serverInfo,omitempty"`
 	Tools           []mcpToolDefinition `json:"tools,omitempty"`
 }
 
+// mcpCapabilities declares server-supported features such as tools or resources.
 type mcpCapabilities struct {
 	Tools *mcpToolsCapability `json:"tools,omitempty"`
 }
 
+// mcpToolsCapability specifies tool availability and listing support.
 type mcpToolsCapability struct {
 	Available []string `json:"available,omitempty"`
 	List      bool     `json:"list,omitempty"`
 }
 
+// mcpToolDefinition describes an individual tool declared in the initialize result.
 type mcpToolDefinition struct {
 	Name string `json:"name"`
 }

internal/registry/mcp_registrar.go

@@ -152,6 +152,7 @@ func (r *Registrar) Heartbeat(ctx context.Context, ad *agentraxv1alpha1.AgentDep
 	return hbErr
 }
 
+// incrementFailures records a probe failure and returns the new consecutive failure count.
 func (r *Registrar) incrementFailures(namespace, name string) int {
 	r.failuresMu.Lock()
 	defer r.failuresMu.Unlock()
@@ -163,6 +164,7 @@ func (r *Registrar) incrementFailures(namespace, name string) int {
 	return r.failures[k]
 }
 
+// resetFailures clears the consecutive failure counter for the specified agent.
 func (r *Registrar) resetFailures(namespace, name string) {
 	r.failuresMu.Lock()
 	defer r.failuresMu.Unlock()

internal/registry/registry.go

@@ -375,6 +375,7 @@ func (r *Registry) Handler() http.Handler {
 	return mux
 }
 
+// handleRegister handles HTTP POST requests to register or update an agent entry.
 func (r *Registry) handleRegister(w http.ResponseWriter, req *http.Request) {
 	var entry Entry
 	if err := json.NewDecoder(req.Body).Decode(&entry); err != nil {
@@ -391,6 +392,7 @@ func (r *Registry) handleRegister(w http.ResponseWriter, req *http.Request) {
 	_ = json.NewEncoder(w).Encode(map[string]string{"status": "registered"})
 }
 
+// handleDeregisterAgentPath handles HTTP DELETE requests targeting /agents/{namespace}/{name}.
 func (r *Registry) handleDeregisterAgentPath(w http.ResponseWriter, req *http.Request) {
 	namespace := req.PathValue("namespace")
 	name := req.PathValue("name")
@@ -409,6 +411,7 @@ func (r *Registry) handleDeregisterAgentPath(w http.ResponseWriter, req *http.Re
 	_ = json.NewEncoder(w).Encode(map[string]string{"status": "deregistered"})
 }
 
+// handleDeregister handles legacy HTTP DELETE requests targeting /deregister.
 func (r *Registry) handleDeregister(w http.ResponseWriter, req *http.Request) {
 	namespace := req.URL.Query().Get("namespace")
 	name := req.URL.Query().Get("name")
@@ -439,13 +442,15 @@ func (r *Registry) handleDeregister(w http.ResponseWriter, req *http.Request) {
 	_ = json.NewEncoder(w).Encode(map[string]string{"status": "deregistered"})
 }
 
+// handleListAgents handles HTTP GET requests to list all active, non-expired registered agents.
 func (r *Registry) handleListAgents(w http.ResponseWriter, req *http.Request) {
 	agents := r.List()
 	w.Header().Set("Content-Type", "application/json")
 	w.WriteHeader(http.StatusOK)
 	_ = json.NewEncoder(w).Encode(agents)
 }
 
+// handleGetAgent handles HTTP GET requests to fetch details of a specific agent.
 func (r *Registry) handleGetAgent(w http.ResponseWriter, req *http.Request) {
 	namespace := req.PathValue("namespace")
 	name := req.PathValue("name")