api.go

Overview

The [api.go](/projects/291/69232) file defines the HTTP API layer for the Cosmos blockchain service within the application. It provides RESTful endpoints and WebSocket support to interact with Cosmos blockchain data such as account information, transaction history, transaction submission, and gas estimation.

The core component is the `API` struct, which acts as an HTTP handler integrating with a `RouteHandler` (business logic interface) and a WebSocket connection manager. The file manages incoming HTTP requests, upgrades connections to WebSockets when required, validates query parameters, and formats responses or errors consistently.

Key features include:

• Starting and gracefully shutting down the HTTP server and WebSocket manager.

• Serving blockchain info, accounts, transaction details, and transaction history.

• Accepting raw transactions for broadcasting and estimating gas costs.

• Validating paging parameters for paginated endpoints to prevent invalid or oversized queries.

• WebSocket connection upgrade and lifecycle management.

This file is a crucial bridge between the client-facing API and the internal blockchain processing logic.

Detailed Descriptions

Constants and Variables

Type: API

The `API` struct encapsulates the HTTP API handler for Cosmos blockchain endpoints.

Fields:

Functions and Methods

New(handler RouteHandler, manager *websocket.Manager, server *http.Server) *API

Constructor function to create a new `API` instance.

• Parameters:

  • handler: The route handler implementing blockchain logic.

  • manager: WebSocket manager instance.

  • server: HTTP server instance.

• Returns:

  • Pointer to a new API struct.

• Usage:

  api := New(myHandler, myWebSocketManager, myHTTPServer)
  

(a *API) Serve(errChan chan<- error)

Starts serving the API by launching the WebSocket and HTTP server.

• Parameters:

  • errChan: Channel to send errors encountered while serving.

• Behavior:

  • Logs server start.

  • Starts the WebSocket handler.

  • Starts the WebSocket manager in a goroutine.

  • Listens and serves HTTP requests.

  • Sends wrapped errors on errChan if any failures occur.

• Example:

  errChan := make(chan error)
  go api.Serve(errChan)
  

(a *API) Shutdown()

Gracefully shuts down the HTTP server and stops WebSocket connections.

• Behavior:

  • Creates a context with a 15-second timeout for shutdown.

  • Stops WebSocket handler.

  • Calls Shutdown on the HTTP server.

  • Logs any errors during shutdown.

(a *API) Root(w http.ResponseWriter, r *http.Request)

Root endpoint handler.

• Behavior:

  • If the HTTP request contains an Upgrade: websocket header, upgrades the connection to WebSocket.

  • Otherwise, redirects to API documentation.

• Example:

  GET /
  Upgrade: websocket
  

(a *API) ValidatePagingParams(w http.ResponseWriter, r *http.Request, defaultPageSize int, maxPageSize *int) (string, int, error)

Validates and parses paging query parameters `cursor` and `pageSize`.

• Parameters:

  • w: HTTP response writer (used to write errors).

  • r: HTTP request.

  • defaultPageSize: Default page size if none provided.

  • maxPageSize: Optional max page size limit.

• Returns:

  • cursor string from query (used for pagination).

  • pageSize integer page size.

  • error if validation fails.

• Validation Logic:

  • Defaults pageSize to defaultPageSize if empty.

  • Returns error if pageSize is zero or exceeds maxPageSize.

  • Returns error if pageSize is not an integer.

• Usage Example:

  cursor, pageSize, err := api.ValidatePagingParams(w, r, 10, &maxPageSize)
  

(a *API) Websocket(w http.ResponseWriter, r *http.Request)

Handles upgrading an HTTP connection to WebSocket and managing the new connection.

• Behavior:

  • Uses Gorilla WebSocket upgrader to upgrade the connection.

  • On success, registers new WebSocket connection via the route handler.

  • On failure, returns HTTP 500 with error.

(a *API) Info(w http.ResponseWriter, r *http.Request)

Returns general blockchain node information.

• Behavior:

  • Calls GetInfo() on the route handler.

  • Writes JSON response or error.

(a *API) Account(w http.ResponseWriter, r *http.Request)

Returns account details for a given public key.

• Parameters:

  • Expects pubkey URL variable (validated by middleware).

• Behavior:

  • Calls GetAccount(pubkey) on the route handler.

  • Writes JSON response or error.

(a *API) TxHistory(w http.ResponseWriter, r *http.Request)

Returns a paginated list of transactions for a given public key.

• Parameters:

  • pubkey URL variable.

  • Paging query parameters: cursor and pageSize.

• Behavior:

  • Validates paging parameters with max page size limit.

  • Calls GetTxHistory(pubkey, cursor, pageSize) on the route handler.

  • Writes JSON response or error.

(a *API) Tx(w http.ResponseWriter, r *http.Request)

Returns details for a specific transaction by transaction ID.

• Parameters:

  • txid URL variable.

• Behavior:

  • Validates presence of txid.

  • Calls GetTx(txid) on the route handler.

  • Writes JSON response or error.

(a *API) SendTx(w http.ResponseWriter, r *http.Request)

Submits a raw transaction to the blockchain network.

• Request Body:

  • JSON object matching api.TxBody containing RawTx string.

• Behavior:

  • Decodes JSON request body.

  • Calls SendTx(rawTx) on the route handler.

  • Returns transaction hash or error.

(a *API) EstimateGas(w http.ResponseWriter, r *http.Request)

Estimates the gas fee required for a raw transaction.

• Request Body:

  • JSON object matching api.TxBody containing RawTx string.

• Behavior:

  • Decodes JSON request body.

  • Calls EstimateGas(rawTx) on the route handler.

  • Returns estimated gas or error.

Important Implementation Details

• WebSocket Handling:
  The file uses Gorilla WebSocket's upgrader with a permissive origin check (CheckOrigin always returns true) to allow WebSocket connections from any origin. The WebSocket lifecycle (connection creation, message handling) is delegated to the RouteHandler and websocket.Manager.

• Paging Validation:
  The ValidatePagingParams method ensures that pageSize query parameter is numeric, within allowed bounds, and never zero, preventing excessive or invalid queries to the backend.

• Error Handling:
  All API handlers use centralized error and response helpers from the imported api package (api.HandleError and api.HandleResponse) to maintain consistent HTTP status codes and JSON response structure.

• Graceful Shutdown:
  Shutdown() uses a 15-second timeout context to allow the HTTP server to finish processing current requests before closing.

Interaction with Other Parts of the System

• RouteHandler:
  The handler field is an interface responsible for the core blockchain logic such as fetching accounts, transactions, and sending transactions. This abstraction allows the API layer to remain decoupled from blockchain-specific implementations.

• websocket.Manager:
  Manages WebSocket connections, including broadcasting and lifecycle, running concurrently via manager.Start().

• HTTP Server:
  The configured http.Server listens on the specified port and delegates incoming HTTP requests to the API handlers.

• API Utilities (api package):
  Provides common utilities for error handling, response formatting, and API documentation redirection.

• Router (mux):
  Uses Gorilla Mux to parse URL variables such as pubkey and txid.

Visual Diagram

classDiagram
    class API {
        -handler: RouteHandler
        -manager: *websocket.Manager
        -server: *http.Server
        +New(handler, manager, server) *API
        +Serve(errChan chan<- error)
        +Shutdown()
        +Root(w http.ResponseWriter, r *http.Request)
        +ValidatePagingParams(w http.ResponseWriter, r *http.Request, defaultPageSize int, maxPageSize *int) (string, int, error)
        +Websocket(w http.ResponseWriter, r *http.Request)
        +Info(w http.ResponseWriter, r *http.Request)
        +Account(w http.ResponseWriter, r *http.Request)
        +TxHistory(w http.ResponseWriter, r *http.Request)
        +Tx(w http.ResponseWriter, r *http.Request)
        +SendTx(w http.ResponseWriter, r *http.Request)
        +EstimateGas(w http.ResponseWriter, r *http.Request)
    }

    API --> RouteHandler : uses
    API --> websocket.Manager : manages
    API --> http.Server : serves
    API ..> api.HandleError : uses utility
    API ..> api.HandleResponse : uses utility

Summary

The [api.go](/projects/291/69232) file implements the HTTP API for Cosmos blockchain interactions, providing endpoints for querying blockchain data, managing transactions, and supporting WebSocket connections. It is designed with clean separation of concerns, delegating business logic to a `RouteHandler` interface, and maintaining consistent request validation, error handling, and graceful server lifecycle management. This file integrates tightly with the WebSocket manager and HTTP server to deliver a responsive, scalable API service.