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 ¶
- Variables
- func LockPIDs(dir string) (release func(), err error)
- func StartServices(ctx context.Context, sup *Supervisor, services []config.Service, dir string) ([]string, error)
- type Agent
- type AgentState
- type Backlog
- type Backtests
- type Bot
- type BotState
- type Dashboard
- func (d *Dashboard) Handler(ctx context.Context) http.Handler
- func (d *Dashboard) Online(ctx context.Context, name string) bool
- func (d *Dashboard) PrepareMT5Accounts(ctx context.Context)
- func (d *Dashboard) RunMT5Accounts(ctx context.Context)
- func (d *Dashboard) ServeBacktests(s *store.Store, agents config.Agents, cfg config.Backtest) *Backtests
- func (d *Dashboard) ServeSettings(s *store.Store, manager *Manager, bot BotState)
- func (d *Dashboard) ServeSupervision(s *store.Store, manager *Manager) *Supervision
- func (d *Dashboard) SetAgents(agents []Agent) error
- type DashboardOption
- func WithCacheDir(dir string) DashboardOption
- func WithHTTPClient(client *http.Client) DashboardOption
- func WithTrustedProxies(proxies []netip.Prefix) DashboardOption
- func WithUIDir(dir string) DashboardOption
- func WithUIVersion(version string) DashboardOption
- func WithUsers(users Users) DashboardOption
- type Manager
- func (m *Manager) Fence(name string) (release func())
- func (m *Manager) InternalHandler() http.Handler
- func (m *Manager) Outbox(id int64) *ui.AgentOutbox
- func (m *Manager) Reconcile(ctx context.Context) error
- func (m *Manager) RefreshRuntime(ctx context.Context, name string) error
- func (m *Manager) RenameOutbox(id int64, from, to string) (undo func(), err error)
- func (m *Manager) Restart(ctx context.Context, name string) error
- func (m *Manager) Run(ctx context.Context)
- func (m *Manager) State(name string) AgentState
- func (m *Manager) Trigger()
- type Prepare
- type ProcessSpec
- type ProcessState
- type PromptStore
- type Supervision
- func (s *Supervision) Analyze(ctx context.Context, origin, by string) (store.SupervisorRun, error)
- func (s *Supervision) Ask(ctx context.Context, userID int64, by, text string) ([]store.SupervisorMessage, error)
- func (s *Supervision) AskFollowed(ctx context.Context, userID int64, by, text string, events chatEvents) ([]store.SupervisorMessage, error)
- func (s *Supervision) Confirm(ctx context.Context, id, userID int64, by string) (store.SupervisorAction, store.SupervisorMessage, error)
- func (s *Supervision) Reject(ctx context.Context, id, userID int64, by string) (store.SupervisorAction, store.SupervisorMessage, error)
- func (s *Supervision) Run(ctx context.Context)
- func (s *Supervision) Trigger()
- type Supervisor
- func (s *Supervisor) KeepPIDs(dir string) error
- func (s *Supervisor) KillAll()
- func (s *Supervisor) Running(name string) bool
- func (s *Supervisor) Start(spec ProcessSpec, prepare Prepare) error
- func (s *Supervisor) State(name string) ProcessState
- func (s *Supervisor) Stop(name string)
- func (s *Supervisor) StopAll()
- func (s *Supervisor) StopLeftovers()
- type Telegram
- type TelegramConfig
- type TelegramOption
- type TelegramRunner
- type Users
Constants ¶
This section is empty.
Variables ¶
var ErrNoCandles = errors.New("no candles")
ErrNoCandles is the error of a range of candles the bridge has none of.
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 ¶
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 ¶
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 ¶
Cancel cancels the run of id: queued, at once; running, its process interrupted (its report partial, canceled). False for a run ended.
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 ¶
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) PrepareMT5Accounts ¶
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 ¶
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 ¶
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.
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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.
type Prepare ¶
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 ¶
func (s *Supervision) Confirm(ctx context.Context, id, userID int64, by string) (store.SupervisorAction, store.SupervisorMessage, error)
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 ¶
func (s *Supervision) Reject(ctx context.Context, id, userID int64, by string) (store.SupervisorAction, store.SupervisorMessage, error)
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) SyncRelays ¶
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 ¶
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.
Source Files
¶
- access.go
- agents_param.go
- api.go
- asset_agents.go
- auth.go
- backlog.go
- backtest.go
- backtest_api.go
- backtest_compare.go
- backtest_data.go
- backtest_summary.go
- bot_controls.go
- bundle.go
- closed.go
- config_file.go
- config_import.go
- config_secrets.go
- daily_limits.go
- daily_metrics.go
- daily_stops.go
- dashboard.go
- errors.go
- excursions.go
- exposure.go
- headers.go
- internal.go
- loginlimit.go
- manager.go
- mt5_accounts.go
- mt5_switch.go
- news.go
- news_calendar.go
- paging.go
- performance.go
- periods.go
- pids.go
- positions.go
- process_linux.go
- process_unix.go
- proxy.go
- ranges.go
- registry.go
- rename.go
- roles.go
- runtime.go
- services.go
- settings.go
- supervision.go
- supervision_actions.go
- supervision_api.go
- supervision_bridge.go
- supervision_chat.go
- supervision_commands.go
- supervision_protect.go
- supervision_snapshot.go
- supervision_stream.go
- supervisor.go
- telegram.go
- telegram_prompts.go
- telegram_redact.go
- telegram_runner.go
- tokens.go
- trading_hours.go