server

package
v1.261116.0 Latest Latest
Warning

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

Go to latest
Published: Nov 16, 2026 License: MPL-2.0 Imports: 103 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func GenerateCurlCommand

func GenerateCurlCommand(apiBase, apiStyle, token, model string) string

GenerateCurlCommand generates a curl command for testing the provider

func GenerateOpenAPI added in v0.260418.2200

func GenerateOpenAPI(cfg *config.Config) (string, error)

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

func UseWebStaticEndpoints(engine *gin.Engine)

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

type LogsResponse struct {
	Total int        `json:"total"`
	Logs  []LogEntry `json:"logs"`
}

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) Context added in v0.260414.2000

func (s *Server) Context() context.Context

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

func (s *Server) GetGuardrailsSupportedScenarios() []string

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) GetRouter

func (s *Server) GetRouter() *gin.Engine

GetRouter returns the Gin engine for testing purposes

func (*Server) GetTrace added in v0.260819.0

func (s *Server) GetTrace(c *gin.Context)

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

func (s *Server) GetUserToken(c *gin.Context)

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

func (s *Server) IsRemoteCoderRunning() bool

IsRemoteCoderRunning returns whether the remote control service is running

func (*Server) RefreshGuardrailsCredentialCacheOrWarn added in v0.260709.1

func (s *Server) RefreshGuardrailsCredentialCacheOrWarn(context string)

RefreshGuardrailsCredentialCacheOrWarn rebuilds the protected-credential cache, logging (rather than returning) any failure.

func (*Server) ResetModelToken

func (s *Server) ResetModelToken(c *gin.Context)

ResetModelToken generates a new secure random model token and updates the configuration Requires authentication

func (*Server) ResetUserToken

func (s *Server) ResetUserToken(c *gin.Context)

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) Start

func (s *Server) Start(port int) error

Start starts the HTTP server

func (*Server) StartDynamicCallbackServer

func (s *Server) StartDynamicCallbackServer(sessionID string, port int) error

StartDynamicCallbackServer starts a temporary callback server for OAuth Implements CallbackServerManager interface for oauth module

func (*Server) StartRemoteCoder

func (s *Server) StartRemoteCoder() error

StartRemoteCoder starts the remote control service if not already running

func (*Server) Stop

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

Stop gracefully stops the HTTP server

func (*Server) StopDynamicCallbackServer

func (s *Server) StopDynamicCallbackServer(sessionID string)

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 (s *Server) StopServer(c *gin.Context)

func (*Server) SyncRemoteCoderBots

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

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

func (s *Server) UseUIEndpoints(ctx context.Context)

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

func (s *Server) ValidateAuthToken(c *gin.Context)

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 WithDefault

func WithDefault() ServerOption

WithDefault applies all default server options

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 SystemLogLevelResponse struct {
	Message string `json:"message,omitempty"`
	Level   string `json:"level"`
}

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.

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.
mcp
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.

Jump to

Keyboard shortcuts

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