controller

package
v1.1.0 Latest Latest
Warning

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

Go to latest
Published: Nov 17, 2026 License: MIT Imports: 66 Imported by: 0

Documentation

Overview

Package controller runs the bots of xtrader as agents: each bot serves the API of its chart (see ui.Chart) and the controller serves them to the users, on the web dashboard and on Telegram, reaching the agents through their API.

Index

Constants

This section is empty.

Variables

View Source
var ErrNoCandles = errors.New("no candles")

ErrNoCandles is the error of a range of candles the bridge has none of.

View Source
var ErrStopped = errors.New("the controller is stopping: nothing starts anymore")

ErrStopped is the error of a start once the supervisor stopped its processes, see Supervisor.StopAll.

Functions

func LockPIDs

func LockPIDs(dir string) (release func(), err error)

LockPIDs takes the directory of the pidfiles of a controller, dir, for this one alone until release: another controller running from the same directory, eg: of the same agents.dir, fails it, as each one would take the processes of the other for leftovers (see Supervisor.StopLeftovers).

func StartServices

func StartServices(ctx context.Context, sup *Supervisor, services []config.Service, dir string) ([]string, error)

StartServices launches the services of the host the agents need, eg: the bridge of MT5, from dir, but the ones up already, and waits for the health of each one: a service not up after its wait only warns, as the agents retry. It returns the names of the ones launched, to stop after the agents, each with its stop timeout. One a controller before launched and left running as it died isn't up already: the controller stops it before (see Supervisor.StopLeftovers).

Types

type Agent

type Agent struct {
	Name    string `yaml:"name"`
	Address string `yaml:"address"`
	Kind    string `yaml:"kind"`
}

Agent is a bot of the controller: Address is where its chart serves the API, host:port or an http(s) URL, eg: localhost:5555, and Kind the one of its settings, eg: llm.

type AgentState

type AgentState struct {
	ProcessState
	RestartPending bool
	LaunchError    string
	Exited         bool
}

AgentState is the state of an agent of the controller: its process, whether a change of its settings waits for a restart to apply, why the controller didn't launch it, eg: another agent running trades the same positions, and Exited, that it exited on its own without Restart: the controller doesn't launch it again until it is restarted, enabled again or the settings of its launch change after it exited (see held), a state kept in memory only: a controller started again launches it.

type Backlog

type Backlog struct {
	Pending  int
	Since    time.Time
	Failing  bool
	SetApart int
	Held     int
}

Backlog is what the outbox of an agent holds, as it told with its last batch (see agentapi.OutboxRequest): the records not sent yet, when the oldest of them was added (zero when unknown, eg: an agent of a version before it), whether that batch failed, the records the controller refused for good, set apart in it, and the ones held apart, failing again and again.

type Backtests

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

Backtests runs the backtests asked on the dashboard (see GET and POST /api/backtests), the runs queued in the store, concurrency at once: each a process of the program of the kind of its agent in backtest mode, apart from the agents trading (see agents/internal/backtest), on candles read at the bridge of the agent; never a broker, never a change to the agents.

func (*Backtests) Cancel

func (b *Backtests) Cancel(ctx context.Context, id int64) (bool, error)

Cancel cancels the run of id: queued, at once; running, its process interrupted (its report partial, canceled). False for a run ended.

func (*Backtests) Run

func (b *Backtests) Run(ctx context.Context)

Run runs the runs queued until ctx is done: the runs left running by a controller stopped meanwhile told interrupted first; at the end, the runs in progress interrupted, and waited for.

func (*Backtests) Wake

func (b *Backtests) Wake()

Wake makes the runner look for runs queued now.

type Bot

type Bot interface {
	// Apply starts, stops or restarts the bot for cfg, or changes its users.
	Apply(cfg TelegramConfig)
	// SyncRelays relays the events of the agents of names, the ones
	// enabled, and no other.
	SyncRelays(names []string)
}

Bot is the Telegram bot of the controller, see TelegramRunner.

type BotState

type BotState interface {
	Running() bool
}

BotState tells whether the Telegram bot runs, see TelegramRunner.

type Dashboard

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

Dashboard serves the web dashboard of the agents: the bundle, the list of agents and a proxy to the API of each one, so that the browser talks to a single server, and the settings of the controller (see WithSettings). cmd/controller runs it.

Only the users logged in reach it, the users of the database (see WithUsers): without any, it is closed. Any of them can operate the agents with the control panel enabled, and change the settings.

func NewDashboard

func NewDashboard(agents []Agent, options ...DashboardOption) (*Dashboard, error)

NewDashboard creates the dashboard of the agents, each with its own name, replaced later with SetAgents. Call Handler to serve it.

func (*Dashboard) Handler

func (d *Dashboard) Handler(ctx context.Context) http.Handler

Handler resolves the dashboard bundle and returns the HTTP handler: the static files, the login, and to the users logged in the list of agents and the proxy to their API. When the bundle cannot be resolved the API still works and the index page explains the failure.

func (*Dashboard) Online

func (d *Dashboard) Online(ctx context.Context, name string) bool

Online tells whether the API of the agent of that name answers.

func (*Dashboard) PrepareMT5Accounts

func (d *Dashboard) PrepareMT5Accounts(ctx context.Context)

PrepareMT5Accounts imports the accounts of the bridges and logs their terminals in the active ones, before the agents are launched, see mt5Accounts.

func (*Dashboard) RunMT5Accounts

func (d *Dashboard) RunMT5Accounts(ctx context.Context)

RunMT5Accounts keeps the terminals logged in their accounts active until ctx is done, every mt5ReconcileEvery.

func (*Dashboard) ServeBacktests

func (d *Dashboard) ServeBacktests(s *store.Store, agents config.Agents, cfg config.Backtest) *Backtests

ServeBacktests serves the backtests on the dashboard, see Backtests: Run runs them.

func (*Dashboard) ServeSettings

func (d *Dashboard) ServeSettings(s *store.Store, manager *Manager, bot BotState)

ServeSettings serves the settings of s on the dashboard, applied by manager, the state of the Telegram bot told by bot, if any: before Handler.

func (*Dashboard) ServeSupervision

func (d *Dashboard) ServeSupervision(s *store.Store, manager *Manager) *Supervision

ServeSupervision serves the supervisor of the agents of s on the dashboard, run by manager, after ServeSettings, and returns it: its Run applies its settings.

func (*Dashboard) SetAgents

func (d *Dashboard) SetAgents(agents []Agent) error

SetAgents makes agents the ones of the dashboard, in their order: the invalid ones left out, told by the error.

type DashboardOption

type DashboardOption func(*Dashboard)

DashboardOption configures a Dashboard.

func WithCacheDir

func WithCacheDir(dir string) DashboardOption

WithCacheDir overrides where downloaded bundles are stored (default: os.UserCacheDir()/xtrader/ui).

func WithHTTPClient

func WithHTTPClient(client *http.Client) DashboardOption

WithHTTPClient sets the client used to download the bundle.

func WithTrustedProxies

func WithTrustedProxies(proxies []netip.Prefix) DashboardOption

WithTrustedProxies sets the reverse proxies in front of the dashboard, whose X-Forwarded-For and X-Forwarded-Proto are believed: ui.trusted_proxies of config.yml, the loopback by default.

func WithUIDir

func WithUIDir(dir string) DashboardOption

WithUIDir serves the dashboard from a local directory (the output of `bun run build` in web/) instead of downloading the release bundle: ui.dir of config.yml.

func WithUIVersion

func WithUIVersion(version string) DashboardOption

WithUIVersion forces the release tag of the bundle to download (e.g. "v1.4.0" or "latest"): ui.version of config.yml. By default the version of the xtrader module compiled into the binary is used.

func WithUsers

func WithUsers(users Users) DashboardOption

WithUsers sets the users who log in the dashboard, see store.Store: without any, the dashboard is closed.

type Manager

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

Manager applies the database to the controller: the agents enabled launched and the others stopped, their list served by the dashboard, the runtime of each one (see agentapi.Runtime), and the Telegram bot. It runs after every change made through the controller (see Trigger), and every reconcileEvery. A change of the settings an agent was launched with waits for its restart (see Restart): it may be trading. The supervisor starts an agent of Restart again with the settings of its launch once it exited, its secrets the ones of now (see launchedAs), and an agent without Restart that exited stays stopped (see AgentState.Exited). An agent that would trade on MT5 the positions of another one running isn't launched (see conflict), whatever the database says, eg: two agents of the same magic number saved before the store refused them.

The Reconciles run one at a time, and the starts, stops and restarts of an agent one at a time (see agentLocks), a stop or a restart holding its agent alone while its process exits: the lock of an agent comes before reconciling (a Reconcile only tries the ones of the agents), then starting, then mu, then the ones of the supervisor, whose callbacks (see Prepare) take none of them.

func NewManager

func NewManager(s *store.Store, agents config.Agents, sup *Supervisor, dashboard *Dashboard, bot Bot) *Manager

NewManager creates the manager of the agents of s, run by sup with the commands of agents, served by dashboard, with the Telegram bot, if any.

func (*Manager) Fence

func (m *Manager) Fence(name string) (release func())

Fence keeps the agent of name from launching until release: its starts, the ones of the supervisor of the processes once it exited included, fail (errFenced) and are tried again later, eg: while the supervisor closes its positions on its bridge, which nothing else trades meanwhile. A start begun before goes on: State, which waits for it, tells it.

func (*Manager) InternalHandler

func (m *Manager) InternalHandler() http.Handler

InternalHandler returns the handler of the internal API of the agents (see agentapi), to serve on the loopback only.

func (*Manager) Outbox

func (m *Manager) Outbox(id int64) *ui.AgentOutbox

Outbox returns the backlog of the outbox of the agent of id, as it told with its last batch, nil for none.

func (*Manager) Reconcile

func (m *Manager) Reconcile(ctx context.Context) error

Reconcile applies the database once, the Reconciles one at a time (see reconciling). It never waits for an agent to stop: an agent being started, stopped or restarted is left to the Reconcile after that, see Trigger.

func (*Manager) RefreshRuntime

func (m *Manager) RefreshRuntime(ctx context.Context, name string) error

RefreshRuntime reads the agent of name again and publishes its runtime at once, eg: its entries just blocked, rather than at the next Reconcile.

func (*Manager) RenameOutbox

func (m *Manager) RenameOutbox(id int64, from, to string) (undo func(), err error)

RenameOutbox renames the outbox of the agent of id, stopped, from its name from to its name to, with the records it holds not sent yet: the agent reads it under its new name. None to rename is no error. undo puts it back, eg: the rename of the agent failing after it.

func (*Manager) Restart

func (m *Manager) Restart(ctx context.Context, name string) error

Restart stops the agent of name and launches it again when it is enabled, with its settings of the database read once it stopped: the way a change of the settings it was launched with applies (see launchedAs). It waits for the stop holding the agent alone: the Reconciles meanwhile leave it to the one after the restart. ErrStopped once the controller stops.

func (*Manager) Run

func (m *Manager) Run(ctx context.Context)

Run applies the database until ctx is done, then stops the agents for good: a restart in flight, or asked afterwards, launches nothing (ErrStopped).

func (*Manager) State

func (m *Manager) State(name string) AgentState

State returns the state of the agent of name.

func (*Manager) Trigger

func (m *Manager) Trigger()

Trigger makes the manager apply the database now.

type Prepare

type Prepare func() (env map[string]string, release func(), err error)

Prepare returns what a start of a process adds to its environment, eg: a token of its own, and release, called once that start exited, eg: to revoke the token: the one of its last start once the supervisor forgot the process (see Running), before Stop returns.

type ProcessSpec

type ProcessSpec struct {
	Name        string
	Command     []string // the program and its arguments
	Dir         string
	Env         map[string]string // besides baseEnv, see Prepare
	Restart     bool
	StopTimeout time.Duration
}

ProcessSpec is a program the controller runs: an agent, or a service of the host the agents need. StopTimeout is how long it has to exit once interrupted before it is killed, the one of the supervisor when 0.

type ProcessState

type ProcessState struct {
	Running    bool
	PID        int
	Since      time.Time // of the start running
	Restarts   int
	Restarting bool
	LastExit   string // how its last start exited
}

ProcessState is the state of a process of the supervisor: Restarts counts the times it was started again once exited, with Restart, and Restarting tells that it exited and waits for that, Running still.

type PromptStore

type PromptStore interface {
	Prompts(ctx context.Context) ([]store.PromptSummary, error)
	PromptByName(ctx context.Context, name string) (store.Prompt, error)
	UpdatePrompt(ctx context.Context, id int64, edit store.PromptEdit, by string) (store.Prompt, error)
	AgentByName(ctx context.Context, name string) (store.Agent, error)
	SetAgentPrompt(ctx context.Context, id int64, promptID *int64) error
	Agents(ctx context.Context) ([]store.Agent, error)
}

PromptStore is the prompts of the database the bot serves, see store.Store.

type Supervision

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

Supervision is the supervisor of the agents: a language model that analyzes every agent each interval of its settings, while enabled (see Run), and answers the users of the dashboard (see the chat), with what it read of them (see view), never a secret. What it does goes through tools validated here, never through its text: alone, within the autonomy of its settings, it blocks the entries of an agent, stops it once flat or cancels its pending entries; the rest, closing positions among them, it proposes, and a user confirms. Every action is recorded with what it rests on, executed against the state read then (see execute), and checked on the accounts before it is told done.

func (*Supervision) Analyze

func (s *Supervision) Analyze(ctx context.Context, origin, by string) (store.SupervisorRun, error)

Analyze runs an analysis of the agents, the only one: another one asked meanwhile is recorded skipped (errAnalyzing). The model answers with its findings, and with the actions it asks for, executed within its autonomy, proposed beyond it (see analysisTools). A model unavailable fails the analysis, the agents untouched.

func (*Supervision) Ask

func (s *Supervision) Ask(ctx context.Context, userID int64, by, text string) ([]store.SupervisorMessage, error)

Ask answers the message text of the user of userID, by, with the model of the supervisor, and returns the messages it added to the conversation: the question, the proposals of actions the model made through its tool (see propose), validated, executed only once a user confirms them, and the answer, or the error, eg: the model unavailable. Nothing the model writes runs.

func (*Supervision) AskFollowed

func (s *Supervision) AskFollowed(ctx context.Context, userID int64, by, text string,
	events chatEvents) ([]store.SupervisorMessage, error)

AskFollowed answers as Ask does, telling events what it does as it goes, the model asked for a stream of its answer when it has one (see llm.ChatStreamer).

func (*Supervision) Confirm

Confirm executes the proposal of id, confirmed by the user of userID, by, and adds its result, checked, to the conversation: store.ErrDecided when it was decided already, store.ErrExpired once expired.

func (*Supervision) Reject

Reject rejects the proposal of id, by the user of userID, by, and adds it to the conversation.

func (*Supervision) Run

func (s *Supervision) Run(ctx context.Context)

Run applies the settings of the supervisor until ctx is done: an analysis each interval while enabled, the first one an interval after it is enabled or the controller starts; the agents it stops once flat watched; the proposals expired. The analyses and the actions a controller before left in their middle end first: failed, unknown.

func (*Supervision) Trigger

func (s *Supervision) Trigger()

Trigger makes the supervisor read its settings again now, eg: its interval changed.

type Supervisor

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

Supervisor runs processes by name, started and stopped on demand: a process stopped can be started again, a start being a process of its own, until StopAll. Their lines are written to the output of the controller, prefixed with their name. Each start runs in a group of its own, stopped whole, and on Linux stops with the controller, even killed (see group): what a controller killed elsewhere leaves running, the next one stops (see KeepPIDs).

func NewSupervisor

func NewSupervisor(stdout, stderr io.Writer, stopTimeout time.Duration) *Supervisor

NewSupervisor creates a supervisor writing the lines of its processes to stdout and stderr, which have stopTimeout to exit once interrupted, unless their spec says otherwise.

func (*Supervisor) KeepPIDs

func (s *Supervisor) KeepPIDs(dir string) error

KeepPIDs makes the supervisor keep the pidfile of each start of its processes in dir, removed once the start is over: a controller that died, eg: killed, leaves them, for the next one to stop what it left running (see StopLeftovers). Called before the first start.

func (*Supervisor) KillAll

func (s *Supervisor) KillAll()

KillAll kills every process at once, without waiting for them, and nothing starts afterwards: the last resort of a controller out of time to stop, see config.Config.ShutdownTimeout.

func (*Supervisor) Running

func (s *Supervisor) Running(name string) bool

Running reports whether the process of name runs, or waits to be started again.

func (*Supervisor) Start

func (s *Supervisor) Start(spec ProcessSpec, prepare Prepare) error

Start starts the process of spec, unless one of its name runs: prepare, when set, is called before each start of it, the first and the restarts. ErrStopped once StopAll was called.

func (*Supervisor) State

func (s *Supervisor) State(name string) ProcessState

State returns the state of the process of name, the one of its last start once exited.

func (*Supervisor) Stop

func (s *Supervisor) Stop(name string)

Stop stops the process of name, if it runs, and waits for it: interrupted, killed once its stop timeout passed.

func (*Supervisor) StopAll

func (s *Supervisor) StopAll()

StopAll stops every process, at once, and waits for them: nothing starts afterwards (see ErrStopped), eg: a restart in flight as the controller stops.

func (*Supervisor) StopLeftovers

func (s *Supervisor) StopLeftovers()

StopLeftovers stops what the starts of the pidfiles of the supervisor (see KeepPIDs) left running: the processes of a controller that died, which went on without it, eg: the program of `go run`, or any one on a system other than Linux (see parentDeath). Each group is stopped as Stop does, interrupted, then killed once its stop timeout passed, and its pidfile removed; a PID of another program now is left alone (see members). Called once, before the first start.

type Telegram

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

Telegram serves the agents of a dashboard on a Telegram bot, in place of the Telegram of each bot: every user picks the agent of the commands with /agents, the commands reach it through its API, and the notifications of the agents relayed (see SyncRelays) are sent to every user, prefixed with their name. With the prompts of the database (see WithPrompts), the users list, show, edit and switch the prompts of the LLM agents too. The token of the bot is never logged, see redact.

func NewTelegram

func NewTelegram(dashboard *Dashboard, token string, users []int64, options ...TelegramOption) (*Telegram, error)

NewTelegram creates the Telegram bot of the token for the dashboard, which only the users, by their Telegram ID, can drive (see SetUsers). Call Start to serve it. Its errors never carry the token.

func (*Telegram) SetUsers

func (t *Telegram) SetUsers(users []int64)

SetUsers makes users, by their Telegram ID, the ones the bot answers.

func (*Telegram) Start

func (t *Telegram) Start(ctx context.Context)

Start serves the bot until ctx is done.

func (*Telegram) SyncRelays

func (t *Telegram) SyncRelays(names []string)

SyncRelays relays the events of the agents of names, the ones of the dashboard, and no other: a relay of an agent whose address changed starts over, and a relay stopped says nothing of its agent.

type TelegramConfig

type TelegramConfig struct {
	Enabled bool
	Token   string
	Users   []int64
}

TelegramConfig are the settings of the Telegram bot of the database.

type TelegramOption

type TelegramOption func(*Telegram)

TelegramOption configures a Telegram.

func WithPrompts

func WithPrompts(prompts PromptStore, onChange func()) TelegramOption

WithPrompts serves the prompts of prompts on the bot, onChange called after each change.

type TelegramRunner

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

TelegramRunner runs the Telegram bot of the controller with the settings of the database (see Apply): started, stopped or restarted with a new token as they change, its users changed as they are, the events of the agents enabled relayed (see SyncRelays). A bot that can't start, eg: its token refused or the API out of reach, is tried again at the next Apply: the controller runs on without it meanwhile.

func NewTelegramRunner

func NewTelegramRunner(ctx context.Context, dashboard *Dashboard, options ...TelegramOption) *TelegramRunner

NewTelegramRunner creates the runner of the bot of the dashboard, with options, eg: WithPrompts, until ctx is done.

func (*TelegramRunner) Apply

func (r *TelegramRunner) Apply(cfg TelegramConfig)

Apply runs the bot of cfg: off without a token, without users or disabled.

func (*TelegramRunner) Running

func (r *TelegramRunner) Running() bool

Running reports whether the bot serves.

func (*TelegramRunner) SyncRelays

func (r *TelegramRunner) SyncRelays(names []string)

SyncRelays relays the events of the agents of names, the ones enabled.

type Users

type Users interface {
	Authenticate(ctx context.Context, username, password string) (store.User, error)
	User(ctx context.Context, id int64) (store.User, error)
	CountUsers(ctx context.Context) (int64, error)
}

Users are the users of the dashboard, see store.Store.

Jump to

Keyboard shortcuts

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