httpserver

Documentation

Overview

Package httpserver provides an HTTP API server for AQL queries.

Index

• Constants
• type CacheStatusResponse
• type Config
  • func DefaultConfig() Config
• type EntitiesResponse
• type EntityInfo
• type EntitySyncInfo
• type ErrorResponse
• type FilterRequest
• type FilterResponse
• type FiltersResponse
• type GraphQueryRequest
• type GraphStatusResponse
• type ProductInfo
• type ProductsResponse
• type QueryMode
  • func (m QueryMode) IsValid() bool
• type QueryRequest
• type QueryResponse
• type SearchRequest
• type SearchResponse
• type SearchResult
• type Server
  • func New(cfg Config) (*Server, error)
  • func (s *Server) CacheEnabled() bool
  • func (s *Server) EffectiveQueryMode(requested QueryMode) QueryMode
  • func (s *Server) GraphEnabled() bool
  • func (s *Server) ListenAndServe() error
  • func (s *Server) Run() error
  • func (s *Server) Shutdown(ctx context.Context) error
  • func (s *Server) Start() error
• type SyncEntityResult
• type SyncRequest
• type SyncResponse
• type SyncStatusResponse
• type SyntaxResponse
• type VersionResponse

Constants

const Version = "0.2.0"

Version is the HTTP server version.

Types

type CacheStatusResponse

type CacheStatusResponse struct {
	Enabled      bool   `json:"enabled"`
	DatabasePath string `json:"database_path"`
	DefaultMode  string `json:"default_mode"`
	OfflineOnly  bool   `json:"offline_only"`
}

CacheStatusResponse is the response for GET /api/cache/status.

type Config

type Config struct {
	// Addr is the address to listen on (e.g., ":8080").
	Addr string

	// CORSOrigins specifies allowed CORS origins.
	// Use "*" to allow all origins.
	CORSOrigins []string

	// APIKey is the API key for authenticating requests.
	// If empty and NoAuth is false, uses AHA_API_KEY from environment.
	APIKey string

	// NoAuth disables API key authentication (for local development).
	NoAuth bool

	// Logger is the server logger. If nil, a default logger is used.
	Logger *slog.Logger

	// DefaultQueryMode is the default query mode when not specified in request.
	// If empty, defaults to "prefer-cache" when cache is available, otherwise "api".
	DefaultQueryMode QueryMode

	// OfflineOnly restricts the server to offline-only mode (no API calls).
	OfflineOnly bool

	// BackgroundSync enables automatic background sync.
	BackgroundSync bool

	// SyncInterval is the interval for background sync (default: 15 minutes).
	SyncInterval time.Duration

	// DefaultProduct is the default product for sync operations.
	DefaultProduct string
}

Config configures the HTTP server.

func DefaultConfig

func DefaultConfig() Config

DefaultConfig returns a Config with default values.

type EntitiesResponse

type EntitiesResponse struct {
	Entities []EntityInfo `json:"entities"`
}

EntitiesResponse is the response for /api/entities.

type EntityInfo

type EntityInfo struct {
	Name        string   `json:"name"`
	Description string   `json:"description"`
	Fields      []string `json:"fields"`
}

EntityInfo describes an available entity.

type EntitySyncInfo

type EntitySyncInfo struct {
	LastSync    string `json:"last_sync"`
	RecordCount int    `json:"record_count"`
}

EntitySyncInfo contains sync status for a single entity.

type ErrorResponse

type ErrorResponse struct {
	Error   string `json:"error"`
	Code    string `json:"code,omitempty"`
	Details string `json:"details,omitempty"`
}

ErrorResponse represents an API error.

type FilterRequest

type FilterRequest struct {
	Name        string `json:"name"`
	AQL         string `json:"aql"`
	Product     string `json:"product,omitempty"`
	Description string `json:"description,omitempty"`
	IsFavorite  bool   `json:"is_favorite,omitempty"`
}

FilterRequest is the request body for creating/updating a saved filter.

type FilterResponse

type FilterResponse struct {
	ID          string `json:"id"`
	Name        string `json:"name"`
	AQL         string `json:"aql"`
	Product     string `json:"product,omitempty"`
	Description string `json:"description,omitempty"`
	IsFavorite  bool   `json:"is_favorite"`
	CreatedAt   string `json:"created_at"`
	UpdatedAt   string `json:"updated_at"`
}

FilterResponse is the response for a single saved filter.

type FiltersResponse

type FiltersResponse struct {
	Filters []FilterResponse `json:"filters"`
}

FiltersResponse is the response for listing saved filters.

type GraphQueryRequest

type GraphQueryRequest struct {
	Cypher string         `json:"cypher"`
	Params map[string]any `json:"params,omitempty"`
}

GraphQueryRequest is the request for POST /api/graph/query.

type GraphStatusResponse

type GraphStatusResponse struct {
	Enabled bool   `json:"enabled"`
	URI     string `json:"uri,omitempty"`
}

GraphStatusResponse is the response for GET /api/graph/status.

type ProductInfo

type ProductInfo struct {
	ID            string `json:"id"`
	ReferenceNum  string `json:"reference_num"`
	Name          string `json:"name"`
	ProductLineID string `json:"product_line_id,omitempty"`
}

ProductInfo describes an available product.

type ProductsResponse

type ProductsResponse struct {
	Products []ProductInfo `json:"products"`
}

ProductsResponse is the response for /api/products.

type QueryMode

type QueryMode string

QueryMode specifies how queries are executed.

const (
	// QueryModeAPI queries the live Aha API (default).
	QueryModeAPI QueryMode = "api"

	// QueryModeOffline queries only the local SQLite cache.
	QueryModeOffline QueryMode = "offline"

	// QueryModePreferCache tries the local cache first, falls back to API.
	QueryModePreferCache QueryMode = "prefer-cache"
)

func (QueryMode) IsValid

func (m QueryMode) IsValid() bool

IsValid returns true if the query mode is valid.

type QueryRequest

type QueryRequest struct {
	AQL     string    `json:"aql"`
	Product string    `json:"product,omitempty"`
	Mode    QueryMode `json:"mode,omitempty"` // api, offline, prefer-cache
}

QueryRequest is the request body for POST /api/query.

type QueryResponse

type QueryResponse struct {
	Entity  string          `json:"entity"`
	Count   int             `json:"count"`
	Records []result.Record `json:"records"`
	Source  string          `json:"source"` // "api", "cache", or "offline"
	Error   string          `json:"error,omitempty"`
}

QueryResponse is the response for query endpoints.

type SearchRequest

type SearchRequest struct {
	Query    string   `json:"query"`
	Entities []string `json:"entities,omitempty"` // optional filter by entity types
	Limit    int      `json:"limit,omitempty"`    // default 100
}

SearchRequest is the request for full-text search.

type SearchResponse

type SearchResponse struct {
	Query   string         `json:"query"`
	Results []SearchResult `json:"results"`
	Count   int            `json:"count"`
}

SearchResponse is the response for full-text search.

type SearchResult

type SearchResult struct {
	Entity      string  `json:"entity"`
	ID          string  `json:"id"`
	Name        string  `json:"name"`
	Description string  `json:"description"`
	Score       float64 `json:"score"`
}

SearchResult represents a single search hit.

type Server

type Server struct {
	// contains filtered or unexported fields
}

Server is the HTTP API server for AQL queries.

func New

func New(cfg Config) (*Server, error)

New creates a new HTTP server with the given configuration.

func (*Server) CacheEnabled

func (s *Server) CacheEnabled() bool

CacheEnabled returns true if the cache database is available.

func (*Server) EffectiveQueryMode

func (s *Server) EffectiveQueryMode(requested QueryMode) QueryMode

EffectiveQueryMode returns the query mode to use, resolving empty to default.

func (*Server) GraphEnabled

func (s *Server) GraphEnabled() bool

GraphEnabled returns true if the Neo4j graph client is available.

func (*Server) ListenAndServe

func (s *Server) ListenAndServe() error

ListenAndServe starts the server and blocks until shutdown.

func (*Server) Run

func (s *Server) Run() error

Run starts the server and handles graceful shutdown on SIGINT/SIGTERM.

func (*Server) Shutdown

func (s *Server) Shutdown(ctx context.Context) error

Shutdown gracefully shuts down the server.

func (*Server) Start

func (s *Server) Start() error

Start starts the HTTP server.

type SyncEntityResult

type SyncEntityResult struct {
	Entity      string `json:"entity"`
	RecordCount int    `json:"record_count"`
	Duration    string `json:"duration"`
	Error       string `json:"error,omitempty"`
}

SyncEntityResult contains the result of syncing a single entity.

type SyncRequest

type SyncRequest struct {
	Product     string   `json:"product"`
	Incremental bool     `json:"incremental,omitempty"`
	Entities    []string `json:"entities,omitempty"`
}

SyncRequest is the request body for POST /api/sync.

type SyncResponse

type SyncResponse struct {
	Product string             `json:"product"`
	Results []SyncEntityResult `json:"results"`
	Error   string             `json:"error,omitempty"`
}

SyncResponse is the response for POST /api/sync.

type SyncStatusResponse

type SyncStatusResponse struct {
	Product  string                    `json:"product"`
	Entities map[string]EntitySyncInfo `json:"entities"`
}

SyncStatusResponse is the response for GET /api/sync/status.

type SyntaxResponse

type SyntaxResponse struct {
	Syntax    string   `json:"syntax"`
	Operators []string `json:"operators"`
	Examples  []string `json:"examples"`
}

SyntaxResponse is the response for /api/syntax.

type VersionResponse

type VersionResponse struct {
	Server       string `json:"server"`
	Studio       string `json:"studio"`
	CacheEnabled bool   `json:"cache_enabled"`
	DefaultMode  string `json:"default_mode"`
}

VersionResponse is the response for /api/version.