brain

type Bot struct {

	// SendC delivers messages to the bot's stdin, in order -- send-only
	// from the caller's side. Keep sending until ErrC fires; there's no
	// need (and no way) to close SendC yourself.
	SendC chan<- catmsg.FixedPair
	// RecvC delivers every message the bot sends via stdout, in order.
	// Closed once the bot's connection ends (check ErrC for why).
	RecvC <-chan catmsg.FixedPair
	// ErrC receives exactly one value when the bot's connection ends --
	// nil for a clean shutdown (context cancelled), non-nil otherwise
	// (stdout subscription error or the bot process itself exiting).
	ErrC <-chan error
	// contains filtered or unexported fields
}

type Configuration struct {
	// LogDir is where each uploaded bot's stderr log file is created --
	// one file per upload, named "<mode>-<pipeline>-<unixnano>.log".
	// Defaults to os.TempDir() if empty.
	LogDir string
}

type Hook interface {
	brain.Brain
	// Request submits req to the background upload dispatcher Init
	// starts. Non-blocking as long as the dispatcher isn't badly
	// backlogged (the request channel is buffered) -- req.ResultC
	// receives exactly one *UploadResult once the upload finishes
	// (success or failure). If req.ResultC is nil, Request allocates
	// one (buffered by 1) before submitting.
	Request(req *UploadRequest)
	// Bots returns a snapshot of every bot this Hook has successfully
	// uploaded and not yet closed, keyed by the pipeline it's running
	// on. Safe to call concurrently with Request/the dispatcher.
	Bots() map[sgo.PublicKey]*Bot
}

type UploadRequest struct {
	// Mode is the MODE env var the WASM bot image dispatches on at
	// startup (e.g. "arbv1", "testperpv1", "testlatencylitev1") --
	// see catscope-rust-bot's brain::mod BotMode::from_env.
	Mode string
	// BotImagePath is a local path to compile from; empty downloads the
	// published default image instead (see downloadDefaultImage).
	BotImagePath string
	// Env is merged with {"MODE": Mode} and forwarded to the image at
	// load/compile time (e.g. TEST_PROTOCOL) -- may be nil.
	Env map[string]string
	// Pipeline selects which validator to upload to; the zero value
	// uses the pipeline Init allocated (see eventHook.defaultPipeline).
	Pipeline sgo.PublicKey
	// Timeout bounds the whole allocate-a-connection/upload/handshake
	// retry loop; <= 0 uses defaultUploadTimeout.
	Timeout time.Duration
	// ResultC receives exactly one *UploadResult. Request allocates
	// this (buffered by 1) if left nil.
	ResultC chan *UploadResult
}

type UploadResult struct {
	Bot *Bot
	Err error
}