chore(oss): audit the server package and resync the SDK mirrors

Split the 657-line operation service into eor, submit, and verify
modules, add the AGENT_REVOKED and KEY_RETIRED codes the Backend already
emits, and condense every multi-line comment. Mirror Node, Python, and
Go at 2.1.0 with the deep-health 503, non-idempotent retry, rotation
grace, and path-encoding fixes. Document which routes and response
fields the self-hosted server does not provide.

Claude-Session: https://claude.ai/code/session_01Agoc9bRVE9KL7mmWtey9Vq

sdks/go/client.go

@@ -14,6 +14,8 @@ const (
 	defaultBaseURL    = "https://api.elydora.com"
 	defaultTTLMs      = 30000
 	defaultMaxRetries = 3
+	maxResponseBytes  = 10 << 20
+	requestTimeout    = 30 * time.Second
 )
 
 // Config holds the configuration for creating a new Client.
@@ -44,135 +46,195 @@ func NewClient(cfg *Config) (*Client, error) {
 	if cfg == nil {
 		return nil, fmt.Errorf("elydora: config must not be nil")
 	}
-
-	baseURL := cfg.BaseURL
-	if baseURL == "" {
-		baseURL = defaultBaseURL
-	}
-	baseURL = strings.TrimRight(baseURL, "/")
-
 	ttlMs := cfg.TTLMs
 	if ttlMs <= 0 {
 		ttlMs = defaultTTLMs
 	}
-
 	maxRetries := cfg.MaxRetries
 	if maxRetries <= 0 {
 		maxRetries = defaultMaxRetries
 	}
-
 	return &Client{
 		orgID:      cfg.OrgID,
 		agentID:    cfg.AgentID,
 		privateKey: cfg.PrivateKey,
-		baseURL:    baseURL,
+		baseURL:    normalizeBaseURL(cfg.BaseURL),
 		ttlMs:      ttlMs,
 		maxRetries: maxRetries,
 		token:      cfg.Token,
-		httpClient: &http.Client{
-			Timeout: 30 * time.Second,
-		},
+		httpClient: &http.Client{Timeout: requestTimeout},
 	}, nil
 }
 
-// doRequest executes an HTTP request with retries and error handling.
-func (c *Client) doRequest(method, path string, body interface{}, result interface{}) error {
-	u := c.baseURL + path
-
-	var bodyReader io.Reader
-	if body != nil {
-		data, err := json.Marshal(body)
-		if err != nil {
-			return fmt.Errorf("elydora: marshal request body: %w", err)
-		}
-		bodyReader = bytes.NewReader(data)
-	}
-
-	var lastErr error
-	for attempt := 0; attempt <= c.maxRetries; attempt++ {
-		if attempt > 0 {
-			// Reset body reader for retry
-			if body != nil {
-				data, _ := json.Marshal(body)
-				bodyReader = bytes.NewReader(data)
-			}
-			time.Sleep(time.Duration(attempt*attempt) * 100 * time.Millisecond)
-		}
-
-		req, err := http.NewRequest(method, u, bodyReader)
-		if err != nil {
-			return fmt.Errorf("elydora: create request: %w", err)
-		}
-
-		req.Header.Set("Content-Type", "application/json")
-		req.Header.Set("Accept", "application/json")
-		if c.token != "" {
-			req.Header.Set("Authorization", "Bearer "+c.token)
-		}
-
-		resp, err := c.httpClient.Do(req)
-		if err != nil {
-			lastErr = fmt.Errorf("elydora: http request: %w", err)
-			continue
-		}
-
-		respBody, err := io.ReadAll(io.LimitReader(resp.Body, 10<<20))
-		resp.Body.Close()
-		if err != nil {
-			lastErr = fmt.Errorf("elydora: read response body: %w", err)
-			continue
-		}
-
-		if resp.StatusCode >= 200 && resp.StatusCode < 300 {
-			if result != nil && len(respBody) > 0 {
-				if err := json.Unmarshal(respBody, result); err != nil {
-					return fmt.Errorf("elydora: unmarshal response: %w", err)
-				}
-			}
-			return nil
-		}
-
-		// Parse error response
-		var errResp errorResponse
-		if err := json.Unmarshal(respBody, &errResp); err == nil && errResp.Error.Code != "" {
-			apiErr := &ElydoraError{
-				StatusCode: resp.StatusCode,
-				Code:       errResp.Error.Code,
-				Message:    errResp.Error.Message,
-				RequestID:  errResp.Error.RequestID,
-				Details:    errResp.Error.Details,
-			}
-			// Don't retry 4xx errors (except 429)
-			if resp.StatusCode < 500 && resp.StatusCode != 429 {
-				return apiErr
-			}
-			lastErr = apiErr
-			continue
-		}
-
-		lastErr = &ElydoraError{
-			StatusCode: resp.StatusCode,
-			Code:       ErrorCodeInternalError,
-			Message:    string(respBody),
-		}
-		if resp.StatusCode < 500 && resp.StatusCode != 429 {
-			return lastErr
-		}
-	}
-	return lastErr
-}
-
-// doGet performs a GET request.
-func (c *Client) doGet(path string, result interface{}) error {
-	return c.doRequest(http.MethodGet, path, nil, result)
-}
-
-// doPost performs a POST request.
-func (c *Client) doPost(path string, body interface{}, result interface{}) error {
-	return c.doRequest(http.MethodPost, path, body, result)
-}
-
 // SetToken sets the API token used for authenticated API requests.
 func (c *Client) SetToken(token string) {
 	c.token = token
 }
+
+func normalizeBaseURL(baseURL string) string {
+	if baseURL == "" {
+		baseURL = defaultBaseURL
+	}
+	return strings.TrimRight(baseURL, "/")
+}
+
+func newRequest(method, url string, body []byte, token, accept string) (*http.Request, error) {
+	var reader io.Reader
+	if body != nil {
+		reader = bytes.NewReader(body)
+	}
+	req, err := http.NewRequest(method, url, reader)
+	if err != nil {
+		return nil, fmt.Errorf("elydora: create request: %w", err)
+	}
+	if accept != "" {
+		req.Header.Set("Accept", accept)
+	}
+	if body != nil {
+		req.Header.Set("Content-Type", "application/json")
+	}
+	if token != "" {
+		req.Header.Set("Authorization", "Bearer "+token)
+	}
+	return req, nil
+}
+
+func marshalBody(body interface{}) ([]byte, error) {
+	if body == nil {
+		return nil, nil
+	}
+	data, err := json.Marshal(body)
+	if err != nil {
+		return nil, fmt.Errorf("elydora: marshal request body: %w", err)
+	}
+	return data, nil
+}
+
+func readBody(resp *http.Response, limit int64) ([]byte, error) {
+	defer resp.Body.Close()
+	var reader io.Reader = resp.Body
+	if limit > 0 {
+		reader = io.LimitReader(resp.Body, limit)
+	}
+	body, err := io.ReadAll(reader)
+	if err != nil {
+		return nil, fmt.Errorf("elydora: read response body: %w", err)
+	}
+	return body, nil
+}
+
+func decodeSuccess(body []byte, result interface{}) error {
+	if result == nil {
+		return nil
+	}
+	if err := json.Unmarshal(body, result); err != nil {
+		return fmt.Errorf("elydora: unmarshal response: %w", err)
+	}
+	return nil
+}
+
+func apiError(status int, body []byte) *ElydoraError {
+	var errResp errorResponse
+	if err := json.Unmarshal(body, &errResp); err == nil && errResp.Error.Code != "" {
+		return &ElydoraError{
+			StatusCode: status,
+			Code:       errResp.Error.Code,
+			Message:    errResp.Error.Message,
+			RequestID:  errResp.Error.RequestID,
+			Details:    errResp.Error.Details,
+		}
+	}
+	return &ElydoraError{StatusCode: status, Code: ErrorCodeInternalError, Message: string(body)}
+}
+
+func retryable(status int) bool {
+	return status >= 500 || status == http.StatusTooManyRequests
+}
+
+// A lost response to a non-idempotent request must not be replayed.
+func idempotent(method string) bool {
+	switch method {
+	case http.MethodGet, http.MethodHead, http.MethodOptions, http.MethodPut, http.MethodDelete:
+		return true
+	}
+	return false
+}
+
+// doRequest executes an authenticated request; only idempotent methods retry.
+func (c *Client) doRequest(method, path string, body interface{}, result interface{}) error {
+	data, err := marshalBody(body)
+	if err != nil {
+		return err
+	}
+	var lastErr error
+	for attempt := 0; attempt <= c.maxRetries; attempt++ {
+		if attempt > 0 {
+			time.Sleep(time.Duration(attempt*attempt) * 100 * time.Millisecond)
+		}
+		req, err := newRequest(method, c.baseURL+path, data, c.token, "application/json")
+		if err != nil {
+			return err
+		}
+		resp, err := c.httpClient.Do(req)
+		if err != nil {
+			lastErr = fmt.Errorf("elydora: http request: %w", err)
+			if !idempotent(method) {
+				return lastErr
+			}
+			continue
+		}
+		respBody, err := readBody(resp, maxResponseBytes)
+		if err != nil {
+			lastErr = err
+			if !idempotent(method) {
+				return lastErr
+			}
+			continue
+		}
+		if resp.StatusCode >= 200 && resp.StatusCode < 300 {
+			return decodeSuccess(respBody, result)
+		}
+		lastErr = apiError(resp.StatusCode, respBody)
+		if !retryable(resp.StatusCode) || !idempotent(method) {
+			return lastErr
+		}
+	}
+	return lastErr
+}
+
+func (c *Client) doGet(path string, result interface{}) error {
+	return c.doRequest(http.MethodGet, path, nil, result)
+}
+
+func (c *Client) doPost(path string, body interface{}, result interface{}) error {
+	return c.doRequest(http.MethodPost, path, body, result)
+}
+
+// publicRequest sends one unauthenticated request and decodes accepted statuses.
+func publicRequest(method, url string, body interface{}, result interface{}, accepted ...int) error {
+	data, err := marshalBody(body)
+	if err != nil {
+		return err
+	}
+	req, err := newRequest(method, url, data, "", "application/json")
+	if err != nil {
+		return err
+	}
+	resp, err := (&http.Client{Timeout: requestTimeout}).Do(req)
+	if err != nil {
+		return fmt.Errorf("elydora: http request: %w", err)
+	}
+	respBody, err := readBody(resp, maxResponseBytes)
+	if err != nil {
+		return err
+	}
+	for _, status := range accepted {
+		if resp.StatusCode == status {
+			return decodeSuccess(respBody, result)
+		}
+	}
+	if len(accepted) == 0 && resp.StatusCode >= 200 && resp.StatusCode < 300 {
+		return decodeSuccess(respBody, result)
+	}
+	return apiError(resp.StatusCode, respBody)
+}