Documentation
¶
Index ¶
- func GenerateCurlCommand(apiBase, apiStyle, token, model string) string
- func GenerateOpenAPI(cfg *config.Config) (string, error)
- func GetShutdownChannel() <-chan struct{}
- func RuntimeAuditSink() remotescenario.AuditFunc
- func SetGlobalServer(server *Server)
- func UseWebStaticEndpoints(engine *gin.Engine)
- type ActionHistoryEntry
- type ActionHistoryResponse
- type GenerateTokenRequest
- type HTTPTimeouts
- type HistoryResponse
- type LBSimulator
- func (s *LBSimulator) Advance(d time.Duration)
- func (s *LBSimulator) BreakerStates() map[string]string
- func (s *LBSimulator) HealthStates() map[string]string
- func (s *LBSimulator) Pin(session string) string
- func (s *LBSimulator) PinDetail(session string) (serviceID string, lockedAt, expiresAt time.Time, ok bool)
- func (s *LBSimulator) Request(session string) (LBTrace, error)
- func (s *LBSimulator) SeedPin(session, provider, model string)
- type LBTrace
- type LoadBalancerAPI
- func (api *LoadBalancerAPI) ClearAllStats(c *gin.Context)
- func (api *LoadBalancerAPI) ClearRuleStats(c *gin.Context)
- func (api *LoadBalancerAPI) ClearServiceStats(c *gin.Context)
- func (api *LoadBalancerAPI) GetAllStats(c *gin.Context)
- func (api *LoadBalancerAPI) GetCurrentService(c *gin.Context)
- func (api *LoadBalancerAPI) GetRule(c *gin.Context)
- func (api *LoadBalancerAPI) GetRuleStats(c *gin.Context)
- func (api *LoadBalancerAPI) GetRuleSummary(c *gin.Context)
- func (api *LoadBalancerAPI) GetServiceStats(c *gin.Context)
- func (api *LoadBalancerAPI) GetServicesHealth(c *gin.Context)
- func (api *LoadBalancerAPI) RegisterRoutes(loadBalancer *gin.RouterGroup)
- func (api *LoadBalancerAPI) ResetServiceHealth(c *gin.Context)
- func (api *LoadBalancerAPI) UpdateRuleTactic(c *gin.Context)
- type LoadBalancerEngine
- type LogEntry
- type LogsResponse
- type ModelRequestDetail
- type ModelRequestEvent
- type ModelRequestSummary
- type ModelRequestsResponse
- type OpenAIChatCompletionResponse
- type ProbeRequestDetail
- type ProbeResponse
- type ProbeResponseData
- type ProbeResponseDetail
- type ProbeUsage
- type RequestConfig
- type Server
- func (s *Server) Cancel() context.CancelFunc
- func (s *Server) CloseMCPRuntime()
- func (s *Server) CloseVirtualModelServer()
- func (s *Server) Context() context.Context
- func (s *Server) CurrentGuardrailsRuntime() *guardrails.Guardrails
- func (s *Server) EnsureProtocolRecorder(c *gin.Context, scenario string, provider *typ.Provider, model string, ...) *recording.ProtocolRecorder
- func (s *Server) GetGuardrailsSupportedScenarios() []string
- func (s *Server) GetLoadBalancer() *protocolserver.LoadBalancer
- func (s *Server) GetOrCreateScenarioSink(scenario typ.RuleScenario, mode obs.RecordMode) *obs.Sink
- func (s *Server) GetRouter() *gin.Engine
- func (s *Server) GetTrace(c *gin.Context)
- func (s *Server) GetUserToken(c *gin.Context)
- func (s *Server) GetVirtualModelService() *virtualserver.Service
- func (s *Server) HealthMonitor() *loadbalance.HealthMonitor
- func (s *Server) IsRemoteCoderRunning() bool
- func (s *Server) RefreshGuardrailsCredentialCacheOrWarn(context string)
- func (s *Server) ResetModelToken(c *gin.Context)
- func (s *Server) ResetUserToken(c *gin.Context)
- func (s *Server) SetGuardrailsRuntime(runtime *guardrails.Guardrails, context string)
- func (s *Server) Start(port int) error
- func (s *Server) StartDynamicCallbackServer(sessionID string, port int) error
- func (s *Server) StartRemoteCoder() error
- func (s *Server) Stop(ctx context.Context) error
- func (s *Server) StopDynamicCallbackServer(sessionID string)
- func (s *Server) StopRemoteCoder()
- func (s *Server) StopServer(c *gin.Context)
- func (s *Server) SyncRemoteCoderBots(ctx context.Context) error
- func (s *Server) UsageStore() *db.UsageStore
- func (s *Server) UseAIEndpoints()
- func (s *Server) UseLoadBalanceEndpoints()
- func (s *Server) UseTokenManagementEndpoints()
- func (s *Server) UseUIEndpoints(ctx context.Context)
- func (s *Server) UseVirtualModelEndpoints()
- func (s *Server) UseWebAPIEndpoints(manager *swagger.RouteManager) *module.Routes
- func (s *Server) ValidateAuthToken(c *gin.Context)
- type ServerActionResponse
- type ServerOption
- func WithAuthMiddleware(userAuth, modelAuth gin.HandlerFunc) ServerOption
- func WithDebug(enabled bool) ServerOption
- func WithDefault() ServerOption
- func WithGuardrails(runtime *guardrails.Guardrails) ServerOption
- func WithHTTPTimeouts(t HTTPTimeouts) ServerOption
- func WithHost(host string) ServerOption
- func WithLaunchSource(source string) ServerOption
- func WithModelAuthMiddleware(modelAuth gin.HandlerFunc) ServerOption
- func WithMultiLogger(logger *obs.MultiLogger) ServerOption
- func WithOpenBrowser(enabled bool) ServerOption
- func WithProjectsDir(dir string) ServerOption
- func WithRecordDir(dir string) ServerOption
- func WithRecordingCAS(enabled bool) ServerOption
- func WithServertoolProviders(providers ...servertool.ToolProvider) ServerOption
- func WithTemplateManager(tm *catalog.ProviderCatalogManager) ServerOption
- func WithUI(enabled bool) ServerOption
- func WithUserAuthMiddleware(userAuth gin.HandlerFunc) ServerOption
- func WithVersion(version string) ServerOption
- type ServiceHealthResponse
- type StatusResponse
- type SystemLogEntry
- type SystemLogLevelRequest
- type SystemLogLevelResponse
- type SystemLogsResponse
- type TokenResponse
- type TraceDetailResponse
- type WebDeps
- type WebHandler
- func (h *WebHandler) ClearLogs(c *gin.Context)
- func (h *WebHandler) GenerateToken(c *gin.Context)
- func (h *WebHandler) GetActionHistory(c *gin.Context)
- func (h *WebHandler) GetActionStats(c *gin.Context)
- func (h *WebHandler) GetHistory(c *gin.Context)
- func (h *WebHandler) GetLogStats(c *gin.Context)
- func (h *WebHandler) GetLogs(c *gin.Context)
- func (h *WebHandler) GetModelRequestDetail(c *gin.Context)
- func (h *WebHandler) GetModelRequests(c *gin.Context)
- func (h *WebHandler) GetStatus(c *gin.Context)
- func (h *WebHandler) GetSystemLogLevel(c *gin.Context)
- func (h *WebHandler) GetSystemLogStats(c *gin.Context)
- func (h *WebHandler) GetSystemLogs(c *gin.Context)
- func (h *WebHandler) GetToken(c *gin.Context)
- func (h *WebHandler) RestartServer(c *gin.Context)
- func (h *WebHandler) SetSystemLogLevel(c *gin.Context)
- func (h *WebHandler) StartServer(c *gin.Context)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func GenerateCurlCommand ¶
GenerateCurlCommand generates a curl command for testing the provider
func GenerateOpenAPI ¶ added in v0.260418.2200
GenerateOpenAPI creates an OpenAPI v3 schema without starting the server
func GetShutdownChannel ¶
func GetShutdownChannel() <-chan struct{}
GetShutdownChannel returns the shutdown channel for the main process to listen on
func RuntimeAuditSink ¶ added in v0.260709.1
func RuntimeAuditSink() remotescenario.AuditFunc
RuntimeAuditSink builds the AuditFunc the scenario runtime hands to plugins. Plugin actions (e.g. claude_code.interactive.start / .done / .error) land here as regular structured log lines — no separate audit trail is needed on top of the application log.
func SetGlobalServer ¶
func SetGlobalServer(server *Server)
SetGlobalServer sets the global server instance for web UI control
func UseWebStaticEndpoints ¶ added in v0.260709.1
Types ¶
type ActionHistoryEntry ¶
type ActionHistoryEntry struct {
Time time.Time `json:"time"`
Level string `json:"level"`
Message string `json:"message"`
Action string `json:"action,omitempty"`
Success bool `json:"success,omitempty"`
Details interface{} `json:"details,omitempty"`
Fields map[string]interface{} `json:"fields,omitempty"`
}
ActionHistoryEntry represents an action history entry for API response
type ActionHistoryResponse ¶
type ActionHistoryResponse struct {
Total int `json:"total"`
Actions []ActionHistoryEntry `json:"actions"`
}
ActionHistoryResponse represents the API response for action history
type GenerateTokenRequest ¶
type GenerateTokenRequest struct {
ClientID string `json:"client_id" binding:"required" description:"Client ID for token generation" example:"user123"`
}
GenerateTokenRequest represents the request to generate a token
type HTTPTimeouts ¶ added in v0.260723.1
type HTTPTimeouts struct {
ReadHeaderTimeout time.Duration
ReadTimeout time.Duration
WriteTimeout time.Duration
IdleTimeout time.Duration
}
HTTPTimeouts overrides the timeouts Start() arms on the underlying http.Server. Zero fields keep Start()'s hardcoded default for that field — see WithHTTPTimeouts.
type HistoryResponse ¶
type HistoryResponse struct {
Success bool `json:"success" example:"true"`
Data interface{} `json:"data"`
}
HistoryResponse represents the response for request history
type LBSimulator ¶ added in v0.260625.1
type LBSimulator struct {
// contains filtered or unexported fields
}
LBSimulator drives the real load-balancing path — routing.ServiceSelector.Select (health → smart → affinity → strategy) followed by dispatchWithPriorityFailover — against programmable fake upstreams over a request sequence, with a deterministic breaker clock.
It is the shared engine behind both the Go scenario tests (internal/server/lb_scenario_test.go) and the `harness lb` CLI tier, so the "how an LB scenario is simulated" logic lives in exactly one place. It lives in package server because it must reach the unexported failover dispatch loop.
func NewLBSimulator ¶ added in v0.260625.1
func NewLBSimulator(rule *typ.Rule, faults map[string][]int) (sim *LBSimulator, cleanup func(), err error)
NewLBSimulator builds the real selection + dispatch stack for rule against a throwaway config, registering one provider per distinct service provider. The faults map keys are serviceIDs (loadbalance.Service.ServiceID(), i.e. "provider/model"); each value is a per-call status sequence (last repeats). Services without a fault entry always return 200.
This is the status-list shorthand over NewLBSimulatorWithSequences: each []int becomes a vmodel.Sequence with ExhaustClamp, preserving the historical "last entry repeats" semantics. Callers that need repeats or a loop/fail exhaustion policy build the SequenceConfig form and call NewLBSimulatorWithSequences directly.
func NewLBSimulatorWithSequences ¶ added in v0.260723.1
func NewLBSimulatorWithSequences(rule *typ.Rule, faults map[string]vmodel.SequenceConfig) (sim *LBSimulator, cleanup func(), err error)
NewLBSimulatorWithSequences is NewLBSimulator's richer form: each fault is a full vmodel.SequenceConfig, so scenarios can express repeats and a loop/clamp/fail exhaustion policy rather than only a clamped status list. Only each step's HTTP status affects LB/failover decisions.
It installs a deterministic breaker clock; the returned cleanup restores the real clock and removes the temp config dir, and must be called.
func (*LBSimulator) Advance ¶ added in v0.260625.1
func (s *LBSimulator) Advance(d time.Duration)
Advance moves the deterministic breaker clock forward, e.g. past OpenDuration to drive a half-open recovery probe.
func (*LBSimulator) BreakerStates ¶ added in v0.260625.1
func (s *LBSimulator) BreakerStates() map[string]string
BreakerStates returns a snapshot of every rule service's breaker state, keyed by serviceID (values: "closed" / "open" / "half_open"). The breaker store is rule-scoped, so reads key on s.rule.UUID; the returned map stays serviceID-keyed (a consumer-facing contract used by scenario tests + the harness CLI).
func (*LBSimulator) HealthStates ¶ added in v0.260625.1
func (s *LBSimulator) HealthStates() map[string]string
HealthStates returns a snapshot of every rule service's health-monitor state, keyed by serviceID (values: "healthy" / "unhealthy"). This is the channel fed by the special status codes (429 → rate-limit, 401/403 → auth), separate from the breaker.
func (*LBSimulator) Pin ¶ added in v0.260625.1
func (s *LBSimulator) Pin(session string) string
Pin returns the serviceID the session is currently affinity-locked to ("" if none).
func (*LBSimulator) PinDetail ¶ added in v0.260625.1
func (s *LBSimulator) PinDetail(session string) (serviceID string, lockedAt, expiresAt time.Time, ok bool)
PinDetail returns the current (non-expired) affinity lock for a session: the serviceID and its LockedAt/ExpiresAt timestamps (on the simulator's fake clock). ok is false when there is no live lock. It reads through the store's strict-TTL Get, so an expired lock reports ok=false — exactly what selection sees. Used to assert strict (non-sliding) TTL: an unrefreshed lock keeps its original timestamps, and a re-lock after expiry carries a fresh LockedAt.
func (*LBSimulator) Request ¶ added in v0.260625.1
func (s *LBSimulator) Request(session string) (LBTrace, error)
Request runs one request for the given session (empty = no affinity) through the real selection + failover path, returning the trace.
func (*LBSimulator) SeedPin ¶ added in v0.260625.1
func (s *LBSimulator) SeedPin(session, provider, model string)
SeedPin manually locks a session to a service (e.g. to reproduce a stale pin).
type LBTrace ¶ added in v0.260625.1
type LBTrace struct {
Session string `json:"session"`
Attempts []string `json:"attempts"` // serviceIDs attempted, in order (failover hops)
Statuses []int `json:"statuses"` // per-attempt status, parallel to Attempts
FinalStatus int `json:"final_status"` // status the client would see
PinAfter string `json:"pin_after"` // affinity pin after this request ("" if none)
// State snapshots taken AFTER this request, keyed by serviceID.
BreakerAfter map[string]string `json:"breaker_after"` // closed/open/half_open
HealthAfter map[string]string `json:"health_after"` // healthy/unhealthy
}
LBTrace is the record of one simulated request.
type LoadBalancerAPI ¶
type LoadBalancerAPI struct {
// contains filtered or unexported fields
}
LoadBalancerAPI provides REST endpoints for load balancer management
func NewLoadBalancerAPI ¶
func NewLoadBalancerAPI(loadBalancer LoadBalancerEngine, cfg *config.Config) *LoadBalancerAPI
NewLoadBalancerAPI creates a new load balancer API
func (*LoadBalancerAPI) ClearAllStats ¶
func (api *LoadBalancerAPI) ClearAllStats(c *gin.Context)
ClearAllStats clears all statistics
func (*LoadBalancerAPI) ClearRuleStats ¶
func (api *LoadBalancerAPI) ClearRuleStats(c *gin.Context)
ClearRuleStats clears statistics for all services in a rule
func (*LoadBalancerAPI) ClearServiceStats ¶
func (api *LoadBalancerAPI) ClearServiceStats(c *gin.Context)
ClearServiceStats clears statistics for a specific service
func (*LoadBalancerAPI) GetAllStats ¶
func (api *LoadBalancerAPI) GetAllStats(c *gin.Context)
GetAllStats returns statistics for all services
func (*LoadBalancerAPI) GetCurrentService ¶
func (api *LoadBalancerAPI) GetCurrentService(c *gin.Context)
GetCurrentService returns the currently active service for a rule
func (*LoadBalancerAPI) GetRule ¶
func (api *LoadBalancerAPI) GetRule(c *gin.Context)
GetRule returns a specific rule configuration
func (*LoadBalancerAPI) GetRuleStats ¶
func (api *LoadBalancerAPI) GetRuleStats(c *gin.Context)
GetRuleStats returns statistics for all services in a rule
func (*LoadBalancerAPI) GetRuleSummary ¶
func (api *LoadBalancerAPI) GetRuleSummary(c *gin.Context)
GetRuleSummary returns a comprehensive summary of a rule including statistics
func (*LoadBalancerAPI) GetServiceStats ¶
func (api *LoadBalancerAPI) GetServiceStats(c *gin.Context)
GetServiceStats returns statistics for a specific service
func (*LoadBalancerAPI) GetServicesHealth ¶
func (api *LoadBalancerAPI) GetServicesHealth(c *gin.Context)
GetServicesHealth returns health status for all services in a rule
func (*LoadBalancerAPI) RegisterRoutes ¶
func (api *LoadBalancerAPI) RegisterRoutes(loadBalancer *gin.RouterGroup)
RegisterRoutes registers the load balancer API routes
func (*LoadBalancerAPI) ResetServiceHealth ¶
func (api *LoadBalancerAPI) ResetServiceHealth(c *gin.Context)
ResetServiceHealth manually resets a service's health to healthy
func (*LoadBalancerAPI) UpdateRuleTactic ¶
func (api *LoadBalancerAPI) UpdateRuleTactic(c *gin.Context)
UpdateRuleTactic updates the load balancing tactic for a rule without resubmitting the whole rule. The tactic name is validated strictly (unknown names are rejected, not silently degraded) and the params decode through Tactic.UnmarshalJSON — the SAME polymorphic path a full rule save uses — so this partial update cannot drift from the canonical parser.
type LoadBalancerEngine ¶ added in v0.260709.1
type LoadBalancerEngine interface {
// PreviewService is the side-effect-free selection used by read-only
// endpoints: unlike SelectService it never claims a breaker probe slot.
PreviewService(rule *typ.Rule) (*loadbalance.Service, error)
GetServiceStats(provider, model string) *loadbalance.ServiceStats
GetAllServiceStats() map[string]*loadbalance.ServiceStats
ClearServiceStats(provider, model string)
ClearAllStats()
GetRuleSummary(rule *typ.Rule) map[string]interface{}
HealthFilter() *routing.HealthFilter
}
LoadBalancerEngine is the narrow slice of the AI Model API's load-balancer engine (internal/server(aimodel).LoadBalancer) that the admin REST surface needs. Declared as an interface here — rather than importing the concrete type — to avoid an import cycle, since the root server package already imports this webui package for static-asset wiring.
type LogEntry ¶
type LogEntry struct {
Time time.Time `json:"time"`
Level string `json:"level"`
Message string `json:"message"`
Data map[string]interface{} `json:"data,omitempty"`
Fields map[string]interface{} `json:"fields,omitempty"`
}
LogEntry represents a log entry for API response
type LogsResponse ¶
LogsResponse represents the API response for logs
type ModelRequestDetail ¶ added in v0.260604.1
type ModelRequestDetail struct {
ModelRequestSummary
Events []ModelRequestEvent `json:"events"`
}
ModelRequestDetail is a summary plus the full, time-ordered event timeline.
type ModelRequestEvent ¶ added in v0.260604.1
type ModelRequestEvent struct {
Time time.Time `json:"time"`
Source string `json:"source"`
Level string `json:"level"`
Stage string `json:"stage,omitempty"`
Message string `json:"message"`
Fields map[string]interface{} `json:"fields,omitempty"`
}
ModelRequestEvent is a single log line belonging to one model request, regardless of which pipeline stage emitted it (HTTP envelope, protocol conversion / upstream client call, or smart-routing evaluation).
type ModelRequestSummary ¶ added in v0.260604.1
type ModelRequestSummary struct {
RequestID string `json:"request_id"`
Time time.Time `json:"time"`
Scenario string `json:"scenario,omitempty"`
RequestModel string `json:"request_model,omitempty"`
RoutedModel string `json:"routed_model,omitempty"`
Provider string `json:"provider,omitempty"`
Method string `json:"method,omitempty"`
Path string `json:"path,omitempty"`
Status int `json:"status,omitempty"`
LatencyMs int64 `json:"latency_ms,omitempty"`
HasError bool `json:"has_error"`
MaxLevel string `json:"max_level,omitempty"`
// TraceID links the request to its span tree in the in-memory trace
// buffer (GET /api/v1/traces/{trace_id}); empty when the span was not
// sampled or tracing is disabled.
TraceID string `json:"trace_id,omitempty"`
EventCount int `json:"event_count"`
// Failover visibility: how many failover hops this request took and the
// service path it walked ("prov-a/model-a → prov-b/model-b"). Zero/empty
// when the first attempt served the request. Derived from the failover
// loop's stage=failover_retry events, so the list view can answer "did
// this request fail over, and to where" without opening the timeline.
FailoverHops int `json:"failover_hops,omitempty"`
FailoverPath string `json:"failover_path,omitempty"`
}
ModelRequestSummary is the per-request row shown in the Requests view. It is derived by correlating every event that shares a request_id.
type ModelRequestsResponse ¶ added in v0.260604.1
type ModelRequestsResponse struct {
Total int `json:"total"`
Requests []ModelRequestSummary `json:"requests"`
}
ModelRequestsResponse is the list response for the Requests view.
type OpenAIChatCompletionResponse ¶
type OpenAIChatCompletionResponse struct {
ID string `json:"id" example:"chatcmpl-123"`
Object string `json:"object" example:"chat.completion"`
Created int64 `json:"created" example:"1677652288"`
Model string `json:"model" example:"gpt-3.5-turbo"`
Choices []struct {
Index int `json:"index" example:"0"`
Message struct {
Role string `json:"role" example:"assistant"`
Content string `json:"content" example:"Hello! How can I help you?"`
} `json:"message"`
FinishReason string `json:"finish_reason" example:"stop"`
} `json:"choices"`
Usage struct {
PromptTokens int `json:"prompt_tokens" example:"10"`
CompletionTokens int `json:"completion_tokens" example:"20"`
TotalTokens int `json:"total_tokens" example:"30"`
} `json:"usage"`
}
OpenAIChatCompletionResponse represents the OpenAI chat completion response
type ProbeRequestDetail ¶
type ProbeRequestDetail struct {
Messages []map[string]interface{} `json:"messages"`
Model string `json:"model"`
MaxTokens int `json:"max_tokens"`
Temperature float64 `json:"temperature"`
Provider string `json:"provider"`
Timestamp string `json:"timestamp"`
}
ProbeRequestDetail represents the mock request data for probing
func NewMockRequest ¶
func NewMockRequest(provider, model string) ProbeRequestDetail
NewMockRequest creates a new mock request with default values
type ProbeResponse ¶
type ProbeResponse struct {
Success bool `json:"success"`
Error *protocolserver.ErrorDetail `json:"error,omitempty"`
Data *ProbeResponseData `json:"data,omitempty"`
}
ProbeResponse represents the overall probe response
type ProbeResponseData ¶
type ProbeResponseData struct {
Request ProbeRequestDetail `json:"request"`
Response ProbeResponseDetail `json:"response"`
Usage ProbeUsage `json:"usage"`
CurlCommand string `json:"curl_command,omitempty"`
}
ProbeResponseData represents the response data structure
type ProbeResponseDetail ¶
type ProbeResponseDetail struct {
Content string `json:"content"`
Model string `json:"model"`
Provider string `json:"provider"`
FinishReason string `json:"finish_reason"`
Error string `json:"error,omitempty"`
}
ProbeResponseDetail represents the API response
type ProbeUsage ¶
type ProbeUsage struct {
PromptTokens int `json:"prompt_tokens"`
CompletionTokens int `json:"completion_tokens"`
TotalTokens int `json:"total_tokens"`
TimeCost int `json:"time_cost"`
}
ProbeUsage represents token usage information
type RequestConfig ¶
type RequestConfig struct {
RequestModel string `json:"request_model" example:"gpt-3.5-turbo"`
ResponseModel string `json:"response_model" example:"gpt-3.5-turbo"`
Provider string `json:"provider" example:"openai"`
DefaultModel string `json:"default_model" example:"gpt-3.5-turbo"`
}
RequestConfig represents a request configuration in defaults response
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server represents the HTTP server
func GetGlobalServer ¶
func GetGlobalServer() *Server
GetGlobalServer gets the global server instance
func NewServer ¶
func NewServer(cfg *config.Config, opts ...ServerOption) *Server
NewServer creates a new HTTP server instance with functional options
func (*Server) Cancel ¶ added in v0.260414.2000
func (s *Server) Cancel() context.CancelFunc
func (*Server) CloseMCPRuntime ¶ added in v1.261026.0
func (s *Server) CloseMCPRuntime()
CloseMCPRuntime releases external sessions and subprocesses for embedded servers.
func (*Server) CloseVirtualModelServer ¶ added in v0.260903.1
func (s *Server) CloseVirtualModelServer()
CloseVirtualModelServer stops the private virtual-model HTTP server started by NewServer. Stop calls it; test harnesses that build a Server without Start must call it themselves so the serving goroutine does not outlive the test. Safe to call more than once.
func (*Server) CurrentGuardrailsRuntime ¶ added in v0.260709.1
func (s *Server) CurrentGuardrailsRuntime() *guardrails.Guardrails
CurrentGuardrailsRuntime returns the active guardrails runtime snapshot.
func (*Server) EnsureProtocolRecorder ¶ added in v0.260531.1
func (s *Server) EnsureProtocolRecorder(c *gin.Context, scenario string, provider *typ.Provider, model string, mode obs.RecordMode, bs []byte) *recording.ProtocolRecorder
EnsureProtocolRecorder delegates to the AI Model API handler, which owns the ProtocolRecorder type. Kept as a thin root wrapper since callers (anthropic_message.go and its tests) have not moved to aimodel yet.
func (*Server) GetGuardrailsSupportedScenarios ¶ added in v0.260709.1
GetGuardrailsSupportedScenarios returns the scenarios guardrails can gate.
func (*Server) GetLoadBalancer ¶
func (s *Server) GetLoadBalancer() *protocolserver.LoadBalancer
GetLoadBalancer returns the load balancer instance
func (*Server) GetOrCreateScenarioSink ¶
func (s *Server) GetOrCreateScenarioSink(scenario typ.RuleScenario, mode obs.RecordMode) *obs.Sink
GetOrCreateScenarioSink gets or creates a recording sink for the specified scenario. The sink is created on-demand and cached for subsequent use. mode is the request's effective recording selection (rule override or scenario default, already resolved by the caller) — passing it in lets a rule-level recording flag create the sink even when the scenario-level flag is off. Per-request capture-point filtering happens in the recorder, not here; the sink just needs to exist.
func (*Server) GetTrace ¶ added in v0.260819.0
GetTrace returns the spans of one trace. A 404 means the trace was never sampled into the store or has been evicted from the ring buffer — the frontend renders that as "no longer buffered", not as an error.
func (*Server) GetUserToken ¶
GetUserToken returns the current user token (masked) Requires authentication
func (*Server) GetVirtualModelService ¶ added in v0.260716.1
func (s *Server) GetVirtualModelService() *virtualserver.Service
GetVirtualModelService returns the in-process virtual-model service, so embedding callers (e.g. the duo harness child) can register additional virtual models before Start.
func (*Server) HealthMonitor ¶
func (s *Server) HealthMonitor() *loadbalance.HealthMonitor
HealthMonitor returns the server's health monitor
func (*Server) IsRemoteCoderRunning ¶
IsRemoteCoderRunning returns whether the remote control service is running
func (*Server) RefreshGuardrailsCredentialCacheOrWarn ¶ added in v0.260709.1
RefreshGuardrailsCredentialCacheOrWarn rebuilds the protected-credential cache, logging (rather than returning) any failure.
func (*Server) ResetModelToken ¶
ResetModelToken generates a new secure random model token and updates the configuration Requires authentication
func (*Server) ResetUserToken ¶
ResetUserToken generates a new secure random token and updates the configuration Requires authentication
func (*Server) SetGuardrailsRuntime ¶ added in v0.260709.1
func (s *Server) SetGuardrailsRuntime(runtime *guardrails.Guardrails, context string)
SetGuardrailsRuntime swaps in a new guardrails runtime, preserving history and credential-cache state carried over from the previous runtime.
func (*Server) StartDynamicCallbackServer ¶
StartDynamicCallbackServer starts a temporary callback server for OAuth Implements CallbackServerManager interface for oauth module
func (*Server) StartRemoteCoder ¶
StartRemoteCoder starts the remote control service if not already running
func (*Server) StopDynamicCallbackServer ¶
StopDynamicCallbackServer stops a temporary callback server for OAuth Implements CallbackServerManager interface for oauth module
func (*Server) StopRemoteCoder ¶
func (s *Server) StopRemoteCoder()
StopRemoteCoder stops the remote control service if running
func (*Server) StopServer ¶
func (*Server) SyncRemoteCoderBots ¶
SyncRemoteCoderBots syncs bots with the remote control bot manager
func (*Server) UsageStore ¶
func (s *Server) UsageStore() *db.UsageStore
UsageStore returns the server's usage store instance for internal integrations.
func (*Server) UseAIEndpoints ¶
func (s *Server) UseAIEndpoints()
func (*Server) UseLoadBalanceEndpoints ¶
func (s *Server) UseLoadBalanceEndpoints()
func (*Server) UseTokenManagementEndpoints ¶ added in v0.260418.2200
func (s *Server) UseTokenManagementEndpoints()
UseTokenManagementEndpoints registers the token management API endpoints.
func (*Server) UseUIEndpoints ¶
Init sets up Server routes and templates on the main server engine
func (*Server) UseVirtualModelEndpoints ¶
func (s *Server) UseVirtualModelEndpoints()
UseVirtualModelEndpoints sets up the direct virtual-model entrypoints, split per protocol:
/virtual/openai/v1/{models,chat/completions,responses}
/virtual/anthropic/v1/{models,messages}
These bypass the provider/rule/scenario pipeline and call the in-process handler directly — useful when a client wants a fixed URL pointed at the vmodel registry without configuring a provider. The protocol split ensures /models returns only the model IDs the chosen protocol can actually dispatch.
The canonical path for virtual models in normal use is still /v1/messages and /v1/chat/completions, where a vmodel provider is dispatched like any other provider: through the SDK to the private in-memory virtualserver listener (see .design/vmodel-transport.md).
func (*Server) UseWebAPIEndpoints ¶ added in v0.260709.1
func (s *Server) UseWebAPIEndpoints(manager *swagger.RouteManager) *module.Routes
UseWebAPIEndpoints configures the core API routes for the web UI using the swagger manager and returns the shared route groups so the caller can mount further modules on them (see apiModules).
func (*Server) ValidateAuthToken ¶
ValidateAuthToken validates an authentication token without requiring auth This is used during login flow to verify a token before establishing session
type ServerActionResponse ¶
type ServerActionResponse struct {
Success bool `json:"success" example:"true"`
Message string `json:"message" example:"Server stopped successfully"`
}
ServerActionResponse represents the response for server actions (start/stop/restart)
type ServerOption ¶
type ServerOption func(*Server)
ServerOption defines a functional option for Server configuration
func WithAuthMiddleware ¶
func WithAuthMiddleware(userAuth, modelAuth gin.HandlerFunc) ServerOption
WithAuthMiddleware sets custom auth middlewares for WebUI and Model API endpoints This allows TBE to inject its own JWT auth middleware instead of using tingly-box's default UserAuthMiddleware and ModelAuthMiddleware
Usage in TBE:
server := NewServer(cfg,
WithAuthMiddleware(tbeUserAuth, tbeModelAuth),
)
func WithDebug ¶
func WithDebug(enabled bool) ServerOption
WithDebug enables or disables debug mode for the server
func WithGuardrails ¶
func WithGuardrails(runtime *guardrails.Guardrails) ServerOption
WithGuardrails sets a guardrails runtime for stream evaluation.
func WithHTTPTimeouts ¶ added in v0.260723.1
func WithHTTPTimeouts(t HTTPTimeouts) ServerOption
WithHTTPTimeouts overrides the http.Server timeouts Start() otherwise hardcodes (ReadHeaderTimeout: 10s, ReadTimeout: 30s, WriteTimeout: 10m, IdleTimeout: 120s). Only non-zero fields in HTTPTimeouts are applied; the rest keep Start()'s defaults. Production callers have no reason to use this — it exists so tests can arm a real http.Server with a short WriteTimeout/ReadTimeout to exercise deadline-dependent behavior (e.g. ClearServerIOTimeouts, see internal/middleware/io_timeout_test.go) without hand-rolling a parallel http.Server outside the real Start() path.
func WithHost ¶
func WithHost(host string) ServerOption
func WithLaunchSource ¶ added in v0.260827.1
func WithLaunchSource(source string) ServerOption
WithLaunchSource records how this process was itself invoked ("", "binary", "npx", "npm" — see internal/shortcut's Source* constants), so the /api/v1/shortcut handler can build a shortcut that relaunches the same way, without any detection or persistence (mirrors the CLI's own --source flag).
func WithModelAuthMiddleware ¶
func WithModelAuthMiddleware(modelAuth gin.HandlerFunc) ServerOption
WithModelAuthMiddleware sets a custom model auth middleware for Model API endpoints Use this if you only want to replace ModelAuthMiddleware but keep UserAuthMiddleware
func WithMultiLogger ¶
func WithMultiLogger(logger *obs.MultiLogger) ServerOption
WithMultiLogger sets the multi-mode logger for the server
func WithOpenBrowser ¶
func WithOpenBrowser(enabled bool) ServerOption
WithOpenBrowser enables or disables automatic browser opening
func WithProjectsDir ¶ added in v1.261022.1
func WithProjectsDir(dir string) ServerOption
WithProjectsDir sets the directory embedded Projects keeps its database and thread worktrees in.
func WithRecordDir ¶
func WithRecordDir(dir string) ServerOption
WithRecordDir sets the scenario-level record directory
func WithRecordingCAS ¶ added in v0.260514.1
func WithRecordingCAS(enabled bool) ServerOption
WithRecordingCAS toggles content-addressed dedup alongside the default gzip recording. When enabled, each session is written twice: once as a gzip JSONL.gz (default), and once as content-addressed slim JSONL plus a per-record blob tree. Useful for cross-session prompt analysis and replay.
func WithServertoolProviders ¶ added in v1.261001.1
func WithServertoolProviders(providers ...servertool.ToolProvider) ServerOption
WithServertoolProviders registers additional in-process server tools. They join the servertool pipeline alongside the configured advisor and survive config hot reload. Used by the protocol harness to exercise server-owned tool loops without an external MCP source.
func WithTemplateManager ¶ added in v0.260409.1540
func WithTemplateManager(tm *catalog.ProviderCatalogManager) ServerOption
WithTemplateManager allows TBE to inject a custom TemplateManager. This follows the same pattern as WithAuthMiddleware for consistency.
func WithUI ¶
func WithUI(enabled bool) ServerOption
WithUI enables or disables the UI for the server
func WithUserAuthMiddleware ¶
func WithUserAuthMiddleware(userAuth gin.HandlerFunc) ServerOption
WithUserAuthMiddleware sets a custom user auth middleware for WebUI endpoints Use this if you only want to replace UserAuthMiddleware but keep ModelAuthMiddleware
func WithVersion ¶
func WithVersion(version string) ServerOption
type ServiceHealthResponse ¶
type ServiceHealthResponse struct {
Rule string `json:"rule" example:"gpt-4"`
Health map[string]interface{} `json:"health"`
}
ServiceHealthResponse represents the health check response for services
type StatusResponse ¶
type StatusResponse struct {
Success bool `json:"success" example:"true"`
Data struct {
ServerRunning bool `json:"server_running" example:"true"`
Port int `json:"port" example:"12580"`
ProvidersTotal int `json:"providers_total" example:"3"`
ProvidersEnabled int `json:"providers_enabled" example:"2"`
RequestCount int `json:"request_count" example:"100"`
} `json:"data"`
}
StatusResponse represents the server status API response
type SystemLogEntry ¶
type SystemLogEntry struct {
Time time.Time `json:"time"`
Level string `json:"level"`
Message string `json:"message"`
Fields map[string]interface{} `json:"fields,omitempty"`
}
SystemLogEntry represents a system log entry for API response
type SystemLogLevelRequest ¶
type SystemLogLevelRequest struct {
Level string `json:"level" binding:"required"`
}
SystemLogLevelRequest represents a request to set the log level
type SystemLogLevelResponse ¶ added in v0.260716.1
type SystemLogsResponse ¶
type SystemLogsResponse struct {
Total int `json:"total"`
Logs []SystemLogEntry `json:"logs"`
}
SystemLogsResponse represents the API response for system logs
type TokenResponse ¶
type TokenResponse struct {
Token string `json:"token" example:"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."`
Type string `json:"type" example:"Bearer"`
}
TokenResponse represents the token response
type TraceDetailResponse ¶ added in v0.260819.0
type TraceDetailResponse struct {
TraceID string `json:"trace_id"`
Spans []pkgotel.StoredSpan `json:"spans"`
// DroppedSpans counts spans discarded because the trace exceeded the
// per-trace cap; nonzero means the view is a truncated prefix.
DroppedSpans int `json:"dropped_spans,omitempty"`
}
TraceDetailResponse is the response of GET /api/v1/traces/:trace_id.
type WebDeps ¶ added in v0.260709.1
type WebDeps struct {
// MemoryLogMW backs the HTTP request log API (GetLogs/GetLogStats/ClearLogs).
MemoryLogMW *middleware.MemoryLog
// MultiLogger backs the system log, model-request trace and action
// history APIs.
MultiLogger *obs.MultiLogger
// Config backs token generation/retrieval (model token persistence).
Config *config.Config
// JWTManager issues the JWT-backed model tokens.
JWTManager *auth.JWTManager
}
WebDeps declares exactly what WebHandler needs from the host server. It is populated once, from server.NewServer, after all of *Server's fields have been constructed.
type WebHandler ¶ added in v0.260709.1
type WebHandler struct {
// contains filtered or unexported fields
}
WebHandler serves the WebUI Management API's server-control surface: status/start/restart (status_handler.go), HTTP/system/action logs (log_handler.go), correlated model requests (model_request_handler.go) and model-token management (token_handler.go).
func NewWebHandler ¶ added in v0.260709.1
func NewWebHandler(deps WebDeps) *WebHandler
NewWebHandler constructs the WebUI control handler from its dependencies.
func (*WebHandler) ClearLogs ¶ added in v0.260709.1
func (h *WebHandler) ClearLogs(c *gin.Context)
ClearLogs clears all log entries
func (*WebHandler) GenerateToken ¶ added in v0.260709.1
func (h *WebHandler) GenerateToken(c *gin.Context)
GenerateToken handles token generation requests
func (*WebHandler) GetActionHistory ¶ added in v0.260709.1
func (h *WebHandler) GetActionHistory(c *gin.Context)
GetActionHistory retrieves user action history from memory Query parameters:
- limit: maximum number of recent entries to return (default: 100, max: 1000)
func (*WebHandler) GetActionStats ¶ added in v0.260709.1
func (h *WebHandler) GetActionStats(c *gin.Context)
GetActionStats returns statistics about user actions
func (*WebHandler) GetHistory ¶ added in v0.260709.1
func (h *WebHandler) GetHistory(c *gin.Context)
GetHistory returns request history from the action log.
func (*WebHandler) GetLogStats ¶ added in v0.260709.1
func (h *WebHandler) GetLogStats(c *gin.Context)
GetLogStats returns statistics about the logs
func (*WebHandler) GetLogs ¶ added in v0.260709.1
func (h *WebHandler) GetLogs(c *gin.Context)
GetLogs retrieves logs with optional filtering Query parameters:
- limit: maximum number of entries to return (default: 100)
- level: filter by log level (debug, info, warn, error)
- since: RFC3339 timestamp to filter entries after this time
func (*WebHandler) GetModelRequestDetail ¶ added in v0.260709.1
func (h *WebHandler) GetModelRequestDetail(c *gin.Context)
GetModelRequestDetail returns the full event timeline for a single request id.
func (*WebHandler) GetModelRequests ¶ added in v0.260709.1
func (h *WebHandler) GetModelRequests(c *gin.Context)
GetModelRequests returns recent model requests, one row per correlation id, built by joining the HTTP access log, model_request stage logs and smart-routing traces from recent JSON history and the live memory sinks.
Query parameters:
- limit: maximum number of requests to return (default: 100, max: 1000)
- scenario / provider / status: optional exact-match filters
func (*WebHandler) GetStatus ¶ added in v0.260709.1
func (h *WebHandler) GetStatus(c *gin.Context)
GetStatus returns server status and statistics.
func (*WebHandler) GetSystemLogLevel ¶ added in v0.260709.1
func (h *WebHandler) GetSystemLogLevel(c *gin.Context)
GetSystemLogLevel returns the current system log level
func (*WebHandler) GetSystemLogStats ¶ added in v0.260709.1
func (h *WebHandler) GetSystemLogStats(c *gin.Context)
GetSystemLogStats returns statistics about the system logs
func (*WebHandler) GetSystemLogs ¶ added in v0.260709.1
func (h *WebHandler) GetSystemLogs(c *gin.Context)
GetSystemLogs retrieves system logs with optional filtering Query parameters:
- limit: maximum number of recent entries to return (default: 100, max: 1000)
func (*WebHandler) GetToken ¶ added in v0.260709.1
func (h *WebHandler) GetToken(c *gin.Context)
GetToken handles token retrieval requests - generates a token if it doesn't exist
func (*WebHandler) RestartServer ¶ added in v0.260709.1
func (h *WebHandler) RestartServer(c *gin.Context)
RestartServer is a placeholder: restarting via the web UI is not supported.
func (*WebHandler) SetSystemLogLevel ¶ added in v0.260709.1
func (h *WebHandler) SetSystemLogLevel(c *gin.Context)
SetSystemLogLevel sets the minimum log level for system logs
func (*WebHandler) StartServer ¶ added in v0.260709.1
func (h *WebHandler) StartServer(c *gin.Context)
StartServer is a placeholder: starting the server via the web UI is not supported — the server itself must already be running to serve this request, so start would be a no-op even if implemented.
Source Files
¶
- guardrails_runtime_adapter.go
- load_balance_handler.go
- load_balance_simulator.go
- log_handler.go
- model_request_handler.go
- server.go
- server_control.go
- server_control_chats.go
- server_flags.go
- server_lifecycle.go
- server_middleware.go
- server_modules.go
- server_oauth.go
- server_options.go
- server_routes.go
- server_types.go
- server_webui_api.go
- status_handler.go
- swagger.go
- token_handler.go
- trace_handler.go
- webui_handler.go
- webui_static.go
Directories
¶
| Path | Synopsis |
|---|---|
|
Package module defines the contract every HTTP module under internal/server/module implements, so the host server mounts all of them the same way instead of through per-module RegisterRoutes signatures.
|
Package module defines the contract every HTTP module under internal/server/module implements, so the host server mounts all of them the same way instead of through per-module RegisterRoutes signatures. |
|
apierr
Package apierr provides the shared JSON error-response writers for module HTTP handlers, so packages that must avoid importing internal/server can depend on error-response formatting without reintroducing that cycle.
|
Package apierr provides the shared JSON error-response writers for module HTTP handlers, so packages that must avoid importing internal/server can depend on error-response formatting without reintroducing that cycle. |
|
bind
Package bind holds the request-binding helper shared by module handlers.
|
Package bind holds the request-binding helper shared by module handlers. |
|
debug
Package debug exposes runtime memory diagnostics for a running instance: a memstats snapshot and a pprof heap profile.
|
Package debug exposes runtime memory diagnostics for a running instance: a memstats snapshot and a pprof heap profile. |
|
imagegen
Package imagegen exposes control-plane HTTP endpoints for the image generation scenario — separate from the OpenAI-compatible gateway routes under /tingly/imagegen, which only ever see requests/responses, never the local filesystem.
|
Package imagegen exposes control-plane HTTP endpoints for the image generation scenario — separate from the OpenAI-compatible gateway routes under /tingly/imagegen, which only ever see requests/responses, never the local filesystem. |
|
imbot
wechat_qr.go implements the Weixin QR-login HTTP session flow.
|
wechat_qr.go implements the Weixin QR-login HTTP session flow. |
|
info
Package versioncheck provides version lookup against the npm registry (with npmmirror as a China-mirror fallback) and semver-style comparison.
|
Package versioncheck provides version lookup against the npm registry (with npmmirror as a China-mirror fallback) and semver-style comparison. |
|
notify
Package notify — bot interaction API.
|
Package notify — bot interaction API. |
|
paginate
Package paginate parses the limit/offset query parameters shared by list endpoints.
|
Package paginate parses the limit/offset query parameters shared by list endpoints. |
|
projects
Package projects mounts Projects (the projects/ module, see .design/projects.md) in Tingly Box: a Host that points its Claude Code sessions at the gateway, and the routes behind the "projects" feature flag.
|
Package projects mounts Projects (the projects/ module, see .design/projects.md) in Tingly Box: a Host that points its Claude Code sessions at the gateway, and the routes behind the "projects" feature flag. |
|
provider
Package provider handles CRUD and model-management HTTP endpoints for AI provider configurations.
|
Package provider handles CRUD and model-management HTTP endpoints for AI provider configurations. |
|
sharing
Package apitoken implements CRUD HTTP endpoints for shared API tokens.
|
Package apitoken implements CRUD HTTP endpoints for shared API tokens. |
|
shortcut
Package shortcut exposes the /api/v1/shortcut HTTP endpoints that let the frontend create (or check for) the desktop / start-menu shortcut the CLI's `tingly-box shortcut` command already writes.
|
Package shortcut exposes the /api/v1/shortcut HTTP endpoints that let the frontend create (or check for) the desktop / start-menu shortcut the CLI's `tingly-box shortcut` command already writes. |
|
uiprefs
Package uiprefs serves the UI-only preference store (config.UIPrefs): small per-instance settings the frontend keeps server-side so a browser tab and the desktop window see the same state.
|
Package uiprefs serves the UI-only preference store (config.UIPrefs): small per-instance settings the frontend keeps server-side so a browser tab and the desktop window see the same state. |
|
virtualmodel
Package virtualmodel exposes management endpoints for the in-process virtual-model providers.
|
Package virtualmodel exposes management endpoints for the in-process virtual-model providers. |