httpserver

package
v0.12.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 24, 2026 License: MIT Imports: 24 Imported by: 0

Documentation

Overview

Package httpserver provides an HTTP API server for AQL queries.

Index

Constants

View Source
const Version = "0.2.0"

Version is the HTTP server version.

Variables

This section is empty.

Functions

This section is empty.

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 Metrics added in v0.12.0

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

Metrics tracks server metrics for Prometheus exposition.

func NewMetrics added in v0.12.0

func NewMetrics() *Metrics

NewMetrics creates a new Metrics instance.

func (*Metrics) RecordCacheHit added in v0.12.0

func (m *Metrics) RecordCacheHit()

RecordCacheHit records a cache hit.

func (*Metrics) RecordCacheMiss added in v0.12.0

func (m *Metrics) RecordCacheMiss()

RecordCacheMiss records a cache miss.

func (*Metrics) RecordGraphQuery added in v0.12.0

func (m *Metrics) RecordGraphQuery(err error)

RecordGraphQuery records a graph query.

func (*Metrics) RecordQuery added in v0.12.0

func (m *Metrics) RecordQuery(fromCache bool, parseError, execError bool)

RecordQuery records a query execution.

func (*Metrics) RecordRequest added in v0.12.0

func (m *Metrics) RecordRequest(endpoint string, status int, durationMs float64)

RecordRequest records a request for an endpoint.

func (*Metrics) RecordSync added in v0.12.0

func (m *Metrics) RecordSync(durationMs int64, err error)

RecordSync records a sync operation.

func (*Metrics) WritePrometheus added in v0.12.0

func (m *Metrics) WritePrometheus(w http.ResponseWriter)

WritePrometheus writes metrics in Prometheus exposition format.

type OpenAPIComponents added in v0.12.0

type OpenAPIComponents struct {
	Schemas         map[string]OpenAPISchema         `json:"schemas,omitempty"`
	SecuritySchemes map[string]OpenAPISecurityScheme `json:"securitySchemes,omitempty"`
}

OpenAPIComponents contains reusable components.

type OpenAPIInfo added in v0.12.0

type OpenAPIInfo struct {
	Title       string `json:"title"`
	Description string `json:"description"`
	Version     string `json:"version"`
}

OpenAPIInfo contains API metadata.

type OpenAPIMediaType added in v0.12.0

type OpenAPIMediaType struct {
	Schema OpenAPISchema `json:"schema"`
}

OpenAPIMediaType describes media type content.

type OpenAPIOperation added in v0.12.0

type OpenAPIOperation struct {
	Summary     string                     `json:"summary"`
	Description string                     `json:"description,omitempty"`
	OperationID string                     `json:"operationId"`
	Tags        []string                   `json:"tags,omitempty"`
	Parameters  []OpenAPIParameter         `json:"parameters,omitempty"`
	RequestBody *OpenAPIRequestBody        `json:"requestBody,omitempty"`
	Responses   map[string]OpenAPIResponse `json:"responses"`
	Security    []map[string][]string      `json:"security,omitempty"`
}

OpenAPIOperation describes an API operation.

type OpenAPIParameter added in v0.12.0

type OpenAPIParameter struct {
	Name        string        `json:"name"`
	In          string        `json:"in"`
	Description string        `json:"description,omitempty"`
	Required    bool          `json:"required,omitempty"`
	Schema      OpenAPISchema `json:"schema"`
}

OpenAPIParameter describes a parameter.

type OpenAPIPath added in v0.12.0

type OpenAPIPath map[string]OpenAPIOperation

OpenAPIPath contains operations for a path.

type OpenAPIRequestBody added in v0.12.0

type OpenAPIRequestBody struct {
	Description string                      `json:"description,omitempty"`
	Required    bool                        `json:"required,omitempty"`
	Content     map[string]OpenAPIMediaType `json:"content"`
}

OpenAPIRequestBody describes a request body.

type OpenAPIResponse added in v0.12.0

type OpenAPIResponse struct {
	Description string                      `json:"description"`
	Content     map[string]OpenAPIMediaType `json:"content,omitempty"`
}

OpenAPIResponse describes a response.

type OpenAPISchema added in v0.12.0

type OpenAPISchema struct {
	Type        string                   `json:"type,omitempty"`
	Format      string                   `json:"format,omitempty"`
	Description string                   `json:"description,omitempty"`
	Items       *OpenAPISchema           `json:"items,omitempty"`
	Properties  map[string]OpenAPISchema `json:"properties,omitempty"`
	Required    []string                 `json:"required,omitempty"`
	Ref         string                   `json:"$ref,omitempty"`
	Enum        []string                 `json:"enum,omitempty"`
}

OpenAPISchema describes a schema.

type OpenAPISecurityScheme added in v0.12.0

type OpenAPISecurityScheme struct {
	Type         string `json:"type"`
	Scheme       string `json:"scheme,omitempty"`
	BearerFormat string `json:"bearerFormat,omitempty"`
	Name         string `json:"name,omitempty"`
	In           string `json:"in,omitempty"`
	Description  string `json:"description,omitempty"`
}

OpenAPISecurityScheme describes a security scheme.

type OpenAPIServer added in v0.12.0

type OpenAPIServer struct {
	URL         string `json:"url"`
	Description string `json:"description,omitempty"`
}

OpenAPIServer describes a server.

type OpenAPISpec added in v0.12.0

type OpenAPISpec struct {
	OpenAPI    string                 `json:"openapi"`
	Info       OpenAPIInfo            `json:"info"`
	Servers    []OpenAPIServer        `json:"servers,omitempty"`
	Paths      map[string]OpenAPIPath `json:"paths"`
	Components *OpenAPIComponents     `json:"components,omitempty"`
}

OpenAPISpec is the OpenAPI 3.0 specification for the Aha Studio HTTP API.

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL