Documentation
¶
Overview ¶
Package httpserver provides an HTTP API server for AQL queries.
Index ¶
- Constants
- type CacheStatusResponse
- type Config
- type EntitiesResponse
- type EntityInfo
- type EntitySyncInfo
- type ErrorResponse
- type FilterRequest
- type FilterResponse
- type FiltersResponse
- type GraphQueryRequest
- type GraphStatusResponse
- type Metrics
- func (m *Metrics) RecordCacheHit()
- func (m *Metrics) RecordCacheMiss()
- func (m *Metrics) RecordGraphQuery(err error)
- func (m *Metrics) RecordQuery(fromCache bool, parseError, execError bool)
- func (m *Metrics) RecordRequest(endpoint string, status int, durationMs float64)
- func (m *Metrics) RecordSync(durationMs int64, err error)
- func (m *Metrics) WritePrometheus(w http.ResponseWriter)
- type OpenAPIComponents
- type OpenAPIInfo
- type OpenAPIMediaType
- type OpenAPIOperation
- type OpenAPIParameter
- type OpenAPIPath
- type OpenAPIRequestBody
- type OpenAPIResponse
- type OpenAPISchema
- type OpenAPISecurityScheme
- type OpenAPIServer
- type OpenAPISpec
- type ProductInfo
- type ProductsResponse
- type QueryMode
- type QueryRequest
- type QueryResponse
- type SearchRequest
- type SearchResponse
- type SearchResult
- type Server
- type SyncEntityResult
- type SyncRequest
- type SyncResponse
- type SyncStatusResponse
- type SyntaxResponse
- type VersionResponse
Constants ¶
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 ¶
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
RecordGraphQuery records a graph query.
func (*Metrics) RecordQuery ¶ added in v0.12.0
RecordQuery records a query execution.
func (*Metrics) RecordRequest ¶ added in v0.12.0
RecordRequest records a request for an endpoint.
func (*Metrics) RecordSync ¶ added in v0.12.0
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" )
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 (*Server) CacheEnabled ¶
CacheEnabled returns true if the cache database is available.
func (*Server) EffectiveQueryMode ¶
EffectiveQueryMode returns the query mode to use, resolving empty to default.
func (*Server) GraphEnabled ¶
GraphEnabled returns true if the Neo4j graph client is available.
func (*Server) ListenAndServe ¶
ListenAndServe starts the server and blocks until shutdown.
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.