api

Documentation

Overview

Package api provides the REST API for OpenBotStack runtime.

Package api provides the REST API for OpenBotStack runtime.

Index

• Constants
• Variables
• func CorrelationIDFromContext(ctx context.Context) string
• func CorrelationMiddleware(next http.Handler) http.Handler
• type AuditExecutionStore
  • func NewAuditExecutionStore(logger audit.AuditLogger) *AuditExecutionStore
  • func (s *AuditExecutionStore) QueryExecutions(ctx context.Context, limit int) ([]ExecutionRecord, error)
• type ChatHandler
  • func NewChatHandler() *ChatHandler
  • func (h *ChatHandler) GetHistory(ctx context.Context, sessionID string) ([]Message, error)
  • func (h *ChatHandler) Process(ctx context.Context, req ChatRequest) (*ChatResponse, error)
• type ChatRequest
• type ChatResponse
• type ExecutionRecord
• type ExecutionStore
• type HistoryProvider
• type HistoryResponse
• type Message
• type Metrics
  • func NewMetrics() *Metrics
  • func (m *Metrics) Handler() http.HandlerFunc
  • func (m *Metrics) IncErrors()
  • func (m *Metrics) IncRequests()
• type Router
  • func NewRouter(a agent.Agent) *Router
  • func (r *Router) ServeHTTP(w http.ResponseWriter, req *http.Request)
  • func (r *Router) SetAuthMiddleware(mw func(http.Handler) http.Handler)
  • func (r *Router) SetExecutionStore(es ExecutionStore)
  • func (r *Router) SetHistoryProvider(hp HistoryProvider)
  • func (r *Router) SetSkillProvider(sp SkillProvider)
• type SSEEvent
• type SSEHandler
  • func NewSSEHandler(w http.ResponseWriter) *SSEHandler
  • func (h *SSEHandler) WriteEvent(event SSEEvent) error
• type SSEStream
  • func NewSSEStream() *SSEStream
  • func (s *SSEStream) Close() error
  • func (s *SSEStream) Count() int
  • func (s *SSEStream) Send(event SSEEvent) error
• type SkillProvider
• type SkillResponse

Constants

const (
	// CorrelationIDHeader is the HTTP header used to propagate correlation IDs.
	CorrelationIDHeader = "X-Correlation-ID"
)

Variables

var (
	// ErrMissingTenantID is returned when tenant ID is missing.
	ErrMissingTenantID = errors.New("api: tenant_id is required")

	// ErrMissingMessage is returned when message is empty.
	ErrMissingMessage = errors.New("api: message is required")
)

Functions

func CorrelationIDFromContext

func CorrelationIDFromContext(ctx context.Context) string

CorrelationIDFromContext retrieves the correlation ID from the context.

func CorrelationMiddleware

func CorrelationMiddleware(next http.Handler) http.Handler

CorrelationMiddleware injects a correlation ID into each request context and adds it to the response headers. If an incoming request already carries the X-Correlation-ID header, that value is reused; otherwise a new UUID is generated.

Every log line emitted via slog during the request will include the correlation_id attribute when the returned handler is used.

Types

type AuditExecutionStore

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

AuditExecutionStore adapts AuditLogger to ExecutionStore.

func NewAuditExecutionStore

func NewAuditExecutionStore(logger audit.AuditLogger) *AuditExecutionStore

NewAuditExecutionStore creates an ExecutionStore backed by audit logs.

func (*AuditExecutionStore) QueryExecutions

func (s *AuditExecutionStore) QueryExecutions(ctx context.Context, limit int) ([]ExecutionRecord, error)

QueryExecutions returns recent execution records from audit logs.

type ChatHandler

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

ChatHandler processes chat messages.

func NewChatHandler

func NewChatHandler() *ChatHandler

NewChatHandler creates a new chat handler.

func (*ChatHandler) GetHistory

func (h *ChatHandler) GetHistory(ctx context.Context, sessionID string) ([]Message, error)

GetHistory returns the message history for a session.

func (*ChatHandler) Process

func (h *ChatHandler) Process(ctx context.Context, req ChatRequest) (*ChatResponse, error)

Process handles a chat request.

type ChatRequest

type ChatRequest struct {
	TenantID  string `json:"tenant_id"`
	UserID    string `json:"user_id"`
	SessionID string `json:"session_id"`
	Message   string `json:"message"`
}

ChatRequest is the input for chat endpoint.

type ChatResponse

type ChatResponse struct {
	SessionID string `json:"session_id"`
	Message   string `json:"message"`
	SkillUsed string `json:"skill_used,omitempty"`
}

ChatResponse is the output from chat endpoint.

type ExecutionRecord

type ExecutionRecord struct {
	ExecutionID string `json:"execution_id"`
	SessionID   string `json:"session_id"`
	SkillID     string `json:"skill_id"`
	DurationMs  int64  `json:"duration_ms"`
	Status      string `json:"status"`
	Error       string `json:"error,omitempty"`
}

ExecutionRecord is a single execution entry.

type ExecutionStore

type ExecutionStore interface {
	QueryExecutions(ctx context.Context, limit int) ([]ExecutionRecord, error)
}

ExecutionStore provides access to execution history.

type HistoryProvider

type HistoryProvider interface {
	// GetSessionHistory retrieves messages for a session.
	GetSessionHistory(ctx context.Context, sessionID string) ([]Message, error)
}

HistoryProvider gives access to conversation history.

type HistoryResponse

type HistoryResponse struct {
	SessionID string    `json:"session_id"`
	Messages  []Message `json:"messages"`
}

HistoryResponse contains conversation history.

type Message

type Message struct {
	Role    string `json:"role"`
	Content string `json:"content"`
}

Message represents a single chat message.

type Metrics

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

Metrics holds simple counters for Prometheus-style exposition. This is a lightweight stub — a full implementation would use prometheus/client_golang, but keeping zero external dependencies for the initial stub.

func NewMetrics

func NewMetrics() *Metrics

NewMetrics returns a new Metrics instance.

func (*Metrics) Handler

func (m *Metrics) Handler() http.HandlerFunc

Handler returns an http.HandlerFunc that exposes metrics in Prometheus text exposition format.

func (*Metrics) IncErrors

func (m *Metrics) IncErrors()

IncErrors increments the error counter.

func (*Metrics) IncRequests

func (m *Metrics) IncRequests()

IncRequests increments the total request counter.

type Router

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

Router handles HTTP routing.

The Router is responsible ONLY for:

• HTTP request/response handling
• Request validation
• Session management
• Delegating to Agent

The Router does NOT:

• Select skills (that's the Agent's job)
• Execute skills (that's the Executor's job)
• Make any decisions about which skill to use

func NewRouter

func NewRouter(a agent.Agent) *Router

NewRouter creates a new API router with an Agent.

func (*Router) ServeHTTP

func (r *Router) ServeHTTP(w http.ResponseWriter, req *http.Request)

ServeHTTP implements http.Handler.

func (*Router) SetAuthMiddleware

func (r *Router) SetAuthMiddleware(mw func(http.Handler) http.Handler)

SetAuthMiddleware sets an authentication middleware to be used for all /v1/ endpoints. This should be called before requests begin processing.

func (*Router) SetExecutionStore

func (r *Router) SetExecutionStore(es ExecutionStore)

SetExecutionStore sets the execution store for the /v1/executions endpoint.

func (*Router) SetHistoryProvider

func (r *Router) SetHistoryProvider(hp HistoryProvider)

SetHistoryProvider sets the history provider for the /v1/sessions/{id}/history endpoint.

func (*Router) SetSkillProvider

func (r *Router) SetSkillProvider(sp SkillProvider)

SetSkillProvider sets the skill registry for the /v1/skills endpoint.

type SSEEvent

type SSEEvent struct {
	ID    string
	Event string
	Data  string
}

SSEEvent represents a Server-Sent Event.

type SSEHandler

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

SSEHandler writes SSE events to an HTTP response.

func NewSSEHandler

func NewSSEHandler(w http.ResponseWriter) *SSEHandler

NewSSEHandler creates a new SSE handler.

func (*SSEHandler) WriteEvent

func (h *SSEHandler) WriteEvent(event SSEEvent) error

WriteEvent writes a single SSE event.

type SSEStream

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

SSEStream buffers events for streaming.

func NewSSEStream

func NewSSEStream() *SSEStream

NewSSEStream creates a new SSE stream.

func (*SSEStream) Close

func (s *SSEStream) Close() error

Close marks the stream as closed.

func (*SSEStream) Count

func (s *SSEStream) Count() int

Count returns the number of events.

func (*SSEStream) Send

func (s *SSEStream) Send(event SSEEvent) error

Send adds an event to the stream.

type SkillProvider

type SkillProvider interface {
	List() []string
	Get(id string) (skills.Skill, error)
}

SkillProvider provides access to loaded skills for the API.

type SkillResponse

type SkillResponse struct {
	ID           string      `json:"id"`
	Name         string      `json:"name"`
	Description  string      `json:"description"`
	Type         string      `json:"type"`
	InputSchema  interface{} `json:"input_schema,omitempty"`
	OutputSchema interface{} `json:"output_schema,omitempty"`
	Version      string      `json:"version"`
	Enabled      bool        `json:"enabled"`
}

SkillResponse is the JSON representation of a skills.