botapi

Documentation

Overview

Package botapi implements core Bot API handlers.

Handlers related to RBE are in the "rbe" package for now.

Index

• type BotAPIServer
  • func NewBotAPIServer(cfg *cfg.Provider, secret *hmactoken.Secret, project, version string) *BotAPIServer
  • func (srv *BotAPIServer) BotCode(c *router.Context)
  • func (srv *BotAPIServer) Claim(ctx context.Context, body *UnimplementedRequest, r *botsrv.Request) (botsrv.Response, error)
  • func (srv *BotAPIServer) Event(ctx context.Context, body *EventRequest, r *botsrv.Request) (botsrv.Response, error)
  • func (srv *BotAPIServer) Handshake(ctx context.Context, body *HandshakeRequest, _ *botsrv.Request) (botsrv.Response, error)
  • func (srv *BotAPIServer) IDToken(ctx context.Context, body *UnimplementedRequest, r *botsrv.Request) (botsrv.Response, error)
  • func (srv *BotAPIServer) OAuthToken(ctx context.Context, body *UnimplementedRequest, r *botsrv.Request) (botsrv.Response, error)
  • func (srv *BotAPIServer) Poll(ctx context.Context, body *UnimplementedRequest, r *botsrv.Request) (botsrv.Response, error)
  • func (srv *BotAPIServer) TaskError(ctx context.Context, body *UnimplementedRequest, r *botsrv.Request) (botsrv.Response, error)
  • func (srv *BotAPIServer) TaskUpdate(ctx context.Context, body *UnimplementedRequest, r *botsrv.Request) (botsrv.Response, error)
• type BotGroupCfg
• type BotRBEParams
• type EventRequest
  • func (r *EventRequest) ExtractDebugRequest() any
  • func (r *EventRequest) ExtractSession() []byte
• type EventResponse
• type HandshakeRequest
  • func (r *HandshakeRequest) ExtractDebugRequest() any
  • func (r *HandshakeRequest) ExtractSession() []byte
• type HandshakeResponse
• type UnimplementedRequest
  • func (r *UnimplementedRequest) ExtractDebugRequest() any
  • func (r *UnimplementedRequest) ExtractSession() []byte

Types

type BotAPIServer

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

BotAPIServer implements core Bot API handlers.

Handlers are implement in individual Go files. They are all installed into the server router in main.go.

func NewBotAPIServer

func NewBotAPIServer(cfg *cfg.Provider, secret *hmactoken.Secret, project, version string) *BotAPIServer

NewBotAPIServer constructs a new BotAPIServer.

func (*BotAPIServer) BotCode

func (srv *BotAPIServer) BotCode(c *router.Context)

BotCode serves the bot archive blob or an HTTP redirect to it.

Used to bootstrap bots and by the self-updating bots.

Uses optional "Version" route parameter. Its value is either a concrete bot archive digest to fetch, or an empty string (in which case the handler will serve a redirect to the current stable bot version).

Attempts are made to utilize GAE's edge cache by setting the corresponding headers.

func (*BotAPIServer) Claim

func (srv *BotAPIServer) Claim(ctx context.Context, body *UnimplementedRequest, r *botsrv.Request) (botsrv.Response, error)

Claim implements the handler that claims pending tasks.

TODO: Doc, implement.

func (*BotAPIServer) Event

func (srv *BotAPIServer) Event(ctx context.Context, body *EventRequest, r *botsrv.Request) (botsrv.Response, error)

Event implements the handler that logs events sent by the bot.

func (*BotAPIServer) Handshake

func (srv *BotAPIServer) Handshake(ctx context.Context, body *HandshakeRequest, _ *botsrv.Request) (botsrv.Response, error)

Handshake implements the bot handshake handler.

It is the first ever request sent by the bot. It registers the bot in the datastore and establishes a new bot session.

func (*BotAPIServer) IDToken

func (srv *BotAPIServer) IDToken(ctx context.Context, body *UnimplementedRequest, r *botsrv.Request) (botsrv.Response, error)

IDToken mints ID tokens to be used inside the task.

TODO: Doc, implement.

func (*BotAPIServer) OAuthToken

func (srv *BotAPIServer) OAuthToken(ctx context.Context, body *UnimplementedRequest, r *botsrv.Request) (botsrv.Response, error)

OAuthToken mints OAuth tokens to be used inside the task.

TODO: Doc, implement.

func (*BotAPIServer) Poll

func (srv *BotAPIServer) Poll(ctx context.Context, body *UnimplementedRequest, r *botsrv.Request) (botsrv.Response, error)

Poll implements the handler that tell the bot what to do next.

TODO: Doc, implement.

func (*BotAPIServer) TaskError

func (srv *BotAPIServer) TaskError(ctx context.Context, body *UnimplementedRequest, r *botsrv.Request) (botsrv.Response, error)

TaskError implements the handler that collects internal task errors.

Uses optional "TaskID" route parameter with the task being worked on by the bot.

TODO: Doc, implement.

func (*BotAPIServer) TaskUpdate

func (srv *BotAPIServer) TaskUpdate(ctx context.Context, body *UnimplementedRequest, r *botsrv.Request) (botsrv.Response, error)

TaskUpdate implements handler that collects task state updates.

Uses optional "TaskID" route parameter with the task being worked on by the bot.

TODO: Doc, implement.

type BotGroupCfg

type BotGroupCfg struct {
	// Dimensions is the server-assigned dimensions from bots.cfg.
	Dimensions map[string][]string `json:"dimensions"`
}

BotGroupCfg is derived from the server's bots.cfg and sent to the bot.

type BotRBEParams

type BotRBEParams struct {
	// Instance if the full RBE instance name the bot should be using.
	Instance string `json:"instance"`
	// HybridMode, if true, indicates to use RBE and native scheduler together.
	HybridMode bool `json:"hybrid_mode"`
	// Sleep is how long to sleep (in seconds) before next Swarming check in.
	Sleep float64 `json:"sleep"`
	// PollToken is a legacy unused field preserved for compatibility.
	PollToken string `json:"poll_token"`
}

BotRBEParams is sent to the bot by the handshake and poll handlers.

Describes how the bot should be interacting with RBE API.

type EventRequest

type EventRequest struct {
	// Session is a serialized Swarming Bot Session proto.
	Session []byte `json:"session"`

	// RequestUUID is used to skip reporting duplicate events on retries.
	//
	// Generated by the client (usually an UUID4 string). Optional.
	RequestUUID string `json:"request_uuid,omitempty"`

	// Event is the kind of the event the bot is reporting.
	//
	// Required. Must be in the list of allowed events.
	Event model.BotEventType `json:"event"`

	// Message is an optional arbitrary text message associated with the event.
	//
	// Will show up in the UI and when listing bot events in the API. Not
	// interpreted by the server in any way.
	Message string `json:"message,omitempty"`

	// State is (mostly) arbitrary JSON dict with various properties of the bot.
	//
	// Optional. If set, will be used to see if the bot should be quarantined or
	// put into maintenance. If not set, the current bot state in the datastore
	// won't be affected.
	State botstate.Dict `json:"state,omitempty"`

	// Version is the bot's own version, if known.
	//
	// Optional. If set, ends up reported together with the event.
	Version string `json:"version,omitempty"`
}

EventRequest is sent by the bot.

func (*EventRequest) ExtractDebugRequest

func (r *EventRequest) ExtractDebugRequest() any

func (*EventRequest) ExtractSession

func (r *EventRequest) ExtractSession() []byte

type EventResponse

type EventResponse struct {
}

EventResponse is returned by the server.

type HandshakeRequest

type HandshakeRequest struct {
	// Dimensions are the initial dimensions collected by the bot.
	//
	// They are initial in a sense that they are collected by the base version
	// of the bot code, without using custom hooks script yet. In many cases,
	// these dimensions are very different from what the bot would end up using
	// after loading the hooks. For that reason these dimensions aren't actually
	// written to the datastore (to avoid the bot "flapping" between two sets of
	// dimensions when it restart and performs the handshake). They are still
	// used to check if the bot should be quarantined, and may be used in debug
	// logs.
	//
	// At least `id` dimension must be set. It is the bot ID.
	Dimensions map[string][]string `json:"dimensions"`

	// State is (mostly) arbitrary JSON dict with various properties of the bot.
	//
	// Values here are not indexed and they do not affect how tasks are scheduled
	// on the bot. The server is still aware of some keys and checks them to
	// decide how to handle the bot calls.
	State botstate.Dict `json:"state,omitempty"`

	// Version is the bot's own version.
	//
	// It is a digest of the running bot archive. Here it is used FYI only.
	Version string `json:"version"`

	// SessionID is an ID of a new session the bot is opening.
	//
	// If the bot has already opened this session (i.e. this is a retry), this
	// session will be reused.
	//
	// May be absent in calls from very old bots. An auto-generated ID will be
	// used instead in that case. Such bots will be asked to self update on the
	// very first poll call.
	SessionID string `json:"session_id,omitempty"`
}

HandshakeRequest is sent by the bot.

func (*HandshakeRequest) ExtractDebugRequest

func (r *HandshakeRequest) ExtractDebugRequest() any

func (*HandshakeRequest) ExtractSession

func (r *HandshakeRequest) ExtractSession() []byte

type HandshakeResponse

type HandshakeResponse struct {
	// Session is a serialized bot session proto.
	Session []byte `json:"session"`
	// BotVersion is the bot version the bot should be running, as FYI to the bot.
	BotVersion string `json:"bot_version"`
	// ServerVersion is the current server version, as FYI to the bot.
	ServerVersion string `json:"server_version"`
	// BotConfig is the body of the custom hooks script, if any.
	BotConfig string `json:"bot_config,omitempty"`
	// BotConfigName is the name of the custom hooks script or "bot_config.py".
	BotConfigName string `json:"bot_config_name"`
	// BotConfigRev is the revision of the main bot_config.py (not the hooks script).
	BotConfigRev string `json:"bot_config_rev"`
	// BotGroupCfg is derived from the server's bots.cfg.
	BotGroupCfg BotGroupCfg `json:"bot_group_cfg"`
	// RBE defines how the bot should be interacting with RBE API.
	RBE *BotRBEParams `json:"rbe,omitempty"`
}

HandshakeResponse is returned by the server.

type UnimplementedRequest

type UnimplementedRequest struct{}

UnimplementedRequest is used as a placeholder in unimplemented handlers.

func (*UnimplementedRequest) ExtractDebugRequest

func (r *UnimplementedRequest) ExtractDebugRequest() any

func (*UnimplementedRequest) ExtractSession

func (r *UnimplementedRequest) ExtractSession() []byte